MediaUploader

MediaUploader は、メディアアップロードの開始からステータスポーリング・完了待機までを簡略化するヘルパーです。

インストール

追加インストールは不要です。mixi2-js に同梱されています。

// ESM
import { MediaUploader } from 'mixi2-js/helpers';
// CJS
const { MediaUploader } = require('mixi2-js/helpers');

import { MediaUploader } from '@otoneko1102/mixi2-js/helpers';

なぜ MediaUploader を使うのか？

メディアをポストに添付するには、3 つのステップが必要です:

initiatePostMediaUpload() でアップロード URL を取得
uploadUrl に HTTP POST でメディアデータを送信
getPostMediaStatus() を繰り返し呼んで処理完了を待機

ステップ 3 のポーリングは自前で実装すると煩雑です:

// ❌ ポーリングを自前実装
const upload = await client.initiatePostMediaUpload(request);
// ... HTTP POST ...
let status;
while (true) {
  status = await client.getPostMediaStatus(upload.mediaId);
  if (status.status === MediaUploadStatus.COMPLETED) break;
  if (status.status === MediaUploadStatus.FAILED) throw new Error("Failed");
  await new Promise((r) => setTimeout(r, 1000));
}

MediaUploader を使えば upload() と waitForReady() を呼ぶだけです:

// ✅ 簡潔
const uploader = new MediaUploader(client);
const { mediaId, uploadUrl } = await uploader.initiate(request);
await uploader.upload(uploadUrl, imageBuffer);
await uploader.waitForReady(mediaId);

基本的な使い方

import { MediaUploadType } from 'mixi2-js';
import { MediaUploader } from 'mixi2-js/helpers';

import { MediaUploadType } from '@otoneko1102/mixi2-js';
import { MediaUploader } from '@otoneko1102/mixi2-js/helpers';

import { readFile } from 'node:fs/promises';

const uploader = new MediaUploader(client);
const imageBuffer = await readFile("image.png");

// 1. アップロード開始（uploadUrl と mediaId を取得）
const { mediaId, uploadUrl } = await uploader.initiate({
  contentType: "image/png",
  dataSize: imageBuffer.byteLength,
  mediaType: MediaUploadType.IMAGE,
});

// 2. メディアデータを送信（Authorization ヘッダーを自動付与）
await uploader.upload(uploadUrl, imageBuffer.buffer);

// 3. 完了まで待機
await uploader.waitForReady(mediaId);

// 4. ポストに添付
await client.createPost({
  text: "画像付きポスト！",
  mediaIdList: [mediaId],
});

オプション

const uploader = new MediaUploader(client, {
  pollInterval: 2000, // ポーリング間隔（ミリ秒）。デフォルト: 1000
  timeout: 120000, // タイムアウト（ミリ秒）。デフォルト: 60000
});

オプション	型	デフォルト	説明
`pollInterval`	`number`	`1000`	ステータスポーリングの間隔（ミリ秒）
`timeout`	`number`	`60000`	完了待機のタイムアウト（ミリ秒）

API リファレンス

コンストラクタ

new MediaUploader(client: Client, options?: MediaUploaderOptions)

メソッド

メソッド	引数	戻り値	説明
`initiate(request)`	`InitiatePostMediaUploadRequest`	`Promise<UploadedMedia>`	アップロードを開始し `mediaId` と `uploadUrl` を返す
`upload(uploadUrl, data)`	`string, ArrayBuffer`	`Promise<void>`	`uploadUrl` にメディアデータを HTTP POST で送信
`waitForReady(mediaId)`	`string`	`Promise<string>`	処理完了までポーリングして待機。完了時に `mediaId` を返す

エラー

upload() が HTTP エラーを返した場合: Error: Media upload failed ({status}): {body}
waitForReady() でアップロードが失敗した場合: Error: Media upload failed: {mediaId}
タイムアウトした場合: Error: Media upload timed out after {timeout}ms: {mediaId}

メディアアップロードの制限

項目	制限
画像最大サイズ	15 MB
動画最大サイズ	50 MB
対応フォーマット	JPEG, PNG, GIF, MP4 など
有効期限（画像）	200 秒
有効期限（動画）	600 秒
アップロード容量上限	1 GB / 日（アプリ単位）