V2 Media Metata & Updated Docs (#575)

Author: francistogram

doc/v2.md

@@ -62,6 +62,9 @@ This is a comprehensive guide of all methods available for the Twitter API v2 on
     - [Mute someone](#mute-someone)
     - [Unmute someone](#unmute-someone)
     - [Get users that are muted by you](#get-users-that-are-muted-by-you)
+  - [Upload medias](#upload-medias)
+    - [Upload media](#upload-media)
+    - [Upload media metadata](#upload-media-metadata)
   - [Usage](#usage)
     - [Get usage](#get-usage)
   - [Lists](#lists)
@@ -999,6 +1002,51 @@ for await (const mutedUser of mutedPaginator) {
 }
 ```
 
+## Upload medias
+
+### Upload media
+
+**Method**: `.uploadMedia()`
+
+**Endpoint**: `media/upload`
+
+**Right level**: `Read-write`
+
+**Arguments**:
+  - `media: Buffer`: Media buffer
+  - `options: MediaV2UploadParams`
+    - `options.media_type`: EUploadMimeType (the mimetype of the media)
+    - `options.media_category?`: MediaV2MediaCategory (the category of the media)
+    - `options.chunkSize`: Chunk size
+
+**Returns**: `string`: Media ID
+
+**Example**
+```ts
+const mediaId = await client.v2.uploadMedia(Buffer.from('imgae.png'), { media_type: 'image/png' });
+const newTweet = await client.v1.tweet('Hello!', { media_ids: mediaId });
+```
+
+### Upload media metadata
+
+**Method**: `.createMediaMetadata()`
+
+**Endpoint**: `media/metadata`
+
+**Right level**: `Read-write`
+
+**Arguments**:
+  - `mediaId: string`
+  - `metadata: MediaV2MetadataCreateParams`
+    - `metadata.alt_text`: `{ text: string }` the alt text of the media
+
+**Returns**: `MediaV2MetadataCreateResult`
+
+**Example**
+```ts
+await client.v2.createMediaMetadata(mediaId, { alt_text: { text: 'Hello, world!' } });
+```
+
 ### Get usage
 
 **Method**: `.usage()`

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

@@ -36,4 +36,17 @@ export interface MediaV2UploadResponse {
     expires_after_secs: number;
     processing_info?: MediaV2ProcessingInfo;
   };
+}
+
+export interface MediaV2MetadataCreateParams {
+  alt_text?: { text: string };
+}
+
+export interface MediaV2MetadataCreateResult {
+  data: {
+    id: string;
+    associated_metadata: {
+      alt_text: { text: string };
+    };
+  };
 }

src/v2/client.v2.write.ts

@@ -24,7 +24,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 { MediaV2MediaCategory, MediaV2UploadAppendParams, MediaV2UploadFinalizeParams, MediaV2UploadInitParams, MediaV2UploadResponse } from '../types/v2/media.v2.types';
+import { MediaV2MediaCategory, MediaV2MetadataCreateParams, MediaV2MetadataCreateResult, MediaV2UploadAppendParams, MediaV2UploadFinalizeParams, MediaV2UploadInitParams, MediaV2UploadResponse } from '../types/v2/media.v2.types';
 
 /**
  * Base Twitter v2 client with read/write rights.
@@ -215,6 +215,15 @@ export default class TwitterApiv2ReadWrite extends TwitterApiv2ReadOnly {
     }
   }
 
+  /**
+   * Creates the metadata for media to be uploaded.
+   * This feature is currently only supported for images and GIFs.
+   * https://docs.x.com/x-api/media/metadata-create
+   */
+  public createMediaMetadata(mediaId: string, metadata: Partial<MediaV2MetadataCreateParams>) {
+    return this.post<MediaV2MetadataCreateResult>('/media/metadata', { media_id: mediaId, ...metadata });
+  }
+
   /**
    * 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