feat: add v2 upload media method (#562)

* feat: add v2 upload media method

* tests: add v2.uploadMedia tests

* chore(waitForMediaProcessing): recursively poll for media processing status

Author: leeran7

src/types/v2/media.v2.types.ts

@@ -0,0 +1,37 @@
+export interface MediaV2UploadInitParams {
+  command: 'INIT';
+  media_type: string;
+  total_bytes: number;
+  media_category?: string;
+}
+
+export interface MediaV2UploadAppendParams {
+  command: 'APPEND';
+  media_id: string;
+  segment_index: number;
+  media: Buffer | string;
+}
+
+export interface MediaV2UploadFinalizeParams {
+  command: 'FINALIZE';
+  media_id: string;
+}
+
+export interface MediaV2ProcessingInfo {
+  state: 'pending' | 'in_progress' | 'failed' | 'succeeded';
+  check_after_secs?: number;
+  error?: {
+    code: number;
+    message: string;
+  };
+}
+
+export interface MediaV2UploadResponse {
+  data: {
+    id: string;
+    media_key: string;
+    size?: number;
+    expires_after_secs: number;
+    processing_info?: MediaV2ProcessingInfo;
+  };
+}

src/v2/client.v2.write.ts

@@ -23,6 +23,7 @@ import type {
 } from '../types';
 import TwitterApiv2LabsReadWrite from '../v2-labs/client.v2.labs.write';
 import { CreateDMConversationParams, PostDMInConversationParams, PostDMInConversationResult } from '../types/v2/dm.v2.types';
+import { MediaV2UploadAppendParams, MediaV2UploadFinalizeParams, MediaV2UploadInitParams, MediaV2UploadResponse } from '../types/v2/media.v2.types';
 
 /**
  * Base Twitter v2 client with read/write rights.
@@ -121,6 +122,85 @@ export default class TwitterApiv2ReadWrite extends TwitterApiv2ReadOnly {
     return this.post<TweetV2PostTweetResult>('tweets', payload);
   }
 
+  /**
+   * Uploads media to Twitter using chunked upload.
+   * https://docs.x.com/x-api/media/media-upload
+   *
+   * @param media The media buffer to upload
+   * @param options Upload options including media type and category
+   * @param chunkSize Size of each chunk in bytes (default: 1MB)
+   * @returns The media ID of the uploaded media
+   */
+  public async uploadMedia(
+    media: Buffer,
+    options: { media_type: string; media_category?: string },
+    chunkSize: number = 1024 * 1024
+  ): Promise<string> {
+    const initArguments: MediaV2UploadInitParams = {
+      command: 'INIT',
+      media_type: options.media_type,
+      total_bytes: media.length,
+      media_category: options.media_category,
+    };
+
+    const initResponse = await this.post<MediaV2UploadResponse>('media/upload', initArguments);
+    const mediaId = initResponse.data.id;
+
+    const chunks = Math.ceil(media.length / chunkSize);
+    for (let i = 0; i < chunks; i++) {
+      const start = i * chunkSize;
+      const end = Math.min(start + chunkSize, media.length);
+      const mediaChunk = Uint8Array.prototype.slice.call(media, start, end);
+      const chunkedBuffer = Buffer.from(mediaChunk);
+
+      const appendArguments: MediaV2UploadAppendParams = {
+        command: 'APPEND',
+        media_id: mediaId,
+        segment_index: i,
+        media: chunkedBuffer,
+      };
+
+      await this.post('media/upload', appendArguments);
+    }
+
+    const finalizeArguments: MediaV2UploadFinalizeParams = {
+      command: 'FINALIZE',
+      media_id: mediaId,
+    };
+
+    const finalizeResponse = await this.post<MediaV2UploadResponse>('media/upload', finalizeArguments);
+    if (finalizeResponse.data.processing_info) {
+      await this.waitForMediaProcessing(mediaId);
+    }
+
+    return mediaId;
+  }
+
+  private async waitForMediaProcessing(mediaId: string): Promise<void> {
+    const response = await this.get<MediaV2UploadResponse>('media/upload', {
+      command: 'STATUS',
+      media_id: mediaId,
+    });
+
+    const info = response.data.processing_info;
+    if (!info) return;
+
+    switch (info.state) {
+      case 'succeeded':
+        return;
+      case 'failed':
+        throw new Error(`Media processing failed: ${info.error?.message}`);
+      case 'pending':
+      case 'in_progress': {
+        const waitTime = info?.check_after_secs;
+        if(waitTime && waitTime > 0) {
+          await new Promise(resolve => setTimeout(resolve, waitTime * 1000));
+          await this.waitForMediaProcessing(mediaId);
+        }
+      }
+    }
+  }
+
   /**
    * Reply to a Tweet on behalf of an authenticated user.
    * https://developer.x.com/en/docs/twitter-api/tweets/manage-tweets/api-reference/post-tweets

test/media-upload.test.ts test/media-upload.v1..test.tstest/media-upload.test.ts renamed to test/media-upload.v1..test.ts

@@ -0,0 +1,24 @@
+import 'mocha';
+import { expect } from 'chai';
+import { EUploadMimeType, TwitterApi } from '../src';
+import { getUserClient } from '../src/test/utils';
+import * as fs from 'fs';
+import * as path from 'path';
+
+let client: TwitterApi;
+
+const gifImg = path.resolve(__dirname, 'assets', 'pec.gif');
+const maxTimeout = 1000 * 60;
+
+describe('Media upload for v2 API', () => {
+  before(() => {
+    client = getUserClient();
+  });
+
+  it('Upload a GIF image from buffer', async () => {
+    // Upload media (from buffer)
+    const mediaId = await client.v2.uploadMedia(await fs.promises.readFile(gifImg), { media_type: EUploadMimeType.Gif });
+    expect(mediaId).to.be.an('string');
+    expect(mediaId).to.have.length.greaterThan(0);
+  }).timeout(maxTimeout);
+});