x-twitter-scraper 0.4.1 → 0.5.1

package/resources/x/media.d.mts

@@ -1,9 +1,6 @@
 import { APIResource } from "../../core/resource.mjs";
 import { APIPromise } from "../../core/api-promise.mjs";
 import { RequestOptions } from "../../internal/request-options.mjs";
-/**
- * Media upload and download
- */
 export declare class Media extends APIResource {
     /**
      * Download images and videos from tweets
@@ -24,10 +21,11 @@ export declare class Media extends APIResource {
      * const response = await client.x.media.upload({
      *   account: '@elonmusk',
      *   url: 'https://example.com/image.png',
+     *   'Idempotency-Key': 'Idempotency-Key',
      * });
      * ```
      */
-    upload(body: MediaUploadParams, options?: RequestOptions): APIPromise<MediaUploadResponse>;
+    upload(params: MediaUploadParams, options?: RequestOptions): APIPromise<MediaUploadResponse>;
 }
 export interface MediaDownloadResponse {
     cacheHit?: boolean;
@@ -36,13 +34,176 @@ export interface MediaDownloadResponse {
     totalTweets?: number;
     tweetId?: string;
 }
+/**
+ * Durable write lifecycle record. Poll statusUrl until terminal is true. Reusing
+ * the original Idempotency-Key returns this same record. Submit a new write only
+ * when safeToRetry is true, using a new key.
+ */
 export interface MediaUploadResponse {
-    mediaId: string;
+    id: string;
+    /**
+     * Connected account selected for the write.
+     */
+    account: MediaUploadResponse.Account | null;
+    action: 'create_tweet' | 'delete_tweet' | 'like' | 'unlike' | 'retweet' | 'unretweet' | 'follow' | 'unfollow' | 'remove_follower' | 'send_dm' | 'upload_media' | 'update_profile' | 'update_avatar' | 'update_banner' | 'create_community' | 'delete_community' | 'join_community' | 'leave_community';
+    /**
+     * plannedCredits is the approved maximum. chargedCredits comes from the settled
+     * credit ledger. Pending or failed writes are not charged.
+     */
+    billing: MediaUploadResponse.Billing;
+    charged: boolean;
+    chargedCredits: string;
+    /**
+     * Exact follow-up an API client or agent should perform.
+     */
+    nextAction: MediaUploadResponse.NextAction | null;
+    object: 'x_write_action';
+    pollAfterMs: number | null;
+    /**
+     * Stable fingerprint and sanitized payload for replay checks.
+     */
+    request: MediaUploadResponse.Request;
+    /**
+     * Confirmed result produced by the write, when available.
+     */
+    result: MediaUploadResponse.Result | null;
+    /**
+     * True only when a new attempt can reasonably succeed.
+     */
+    retryable: boolean;
+    /**
+     * True only when no write was dispatched and a new idempotency key may be used.
+     */
+    safeToRetry: boolean;
+    sendDispatched: boolean;
+    status: 'accepted' | 'dispatching' | 'pending_confirmation' | 'success' | 'failed' | 'expired';
+    statusUrl: string;
+    success: boolean;
+    /**
+     * Existing X resource targeted by the write, when applicable.
+     */
+    target: MediaUploadResponse.Target | null;
+    targetId: string | null;
+    terminal: boolean;
+    writeActionId: string;
+    /**
+     * Compatibility field for a confirmed community ID.
+     */
+    communityId?: string;
+    /**
+     * Confirmed community name when available.
+     */
+    communityName?: string;
+    completedAt?: string;
+    confirmationAttempts?: number;
+    confirmationCheckedAt?: string;
+    confirmedAt?: string;
+    createdAt?: string;
+    /**
+     * Structured recovery context for a failed write.
+     */
+    details?: {
+        [key: string]: unknown;
+    };
+    error?: string;
+    /**
+     * Deadline for resolving a non-terminal write. This is not the Idempotency-Key
+     * retention deadline.
+     */
+    expiresAt?: string;
+    idempotent?: boolean;
     /**
-     * Public media URL for tweet `media` arrays.
+     * Media count, kind, size, and billing details when used.
      */
-    mediaUrl: string;
-    success: true;
+    media?: {
+        [key: string]: unknown;
+    };
+    /**
+     * Compatibility field for a confirmed media upload ID.
+     */
+    mediaId?: string;
+    /**
+     * Public media URL when the upload creates one.
+     */
+    mediaUrl?: string;
+    message?: string;
+    /**
+     * Compatibility field for a confirmed direct message ID.
+     */
+    messageId?: string;
+    requestHash?: string;
+    requestId?: string;
+    /**
+     * Compatibility result ID for other write actions.
+     */
+    resultId?: string;
+    /**
+     * Dispatch timestamp when the write reached execution.
+     */
+    sendDispatchedAt?: string;
+    /**
+     * Compatibility field for a confirmed tweet result ID.
+     */
+    tweetId?: string;
+    updatedAt?: string;
+}
+export declare namespace MediaUploadResponse {
+    /**
+     * Connected account selected for the write.
+     */
+    interface Account {
+        id: string;
+        username: string;
+    }
+    /**
+     * plannedCredits is the approved maximum. chargedCredits comes from the settled
+     * credit ledger. Pending or failed writes are not charged.
+     */
+    interface Billing {
+        charged: boolean;
+        chargedCredits: string;
+        plannedCredits: string;
+        status: 'not_charged' | 'pending' | 'charged' | 'charge_failed' | 'refunded';
+    }
+    /**
+     * Exact follow-up an API client or agent should perform.
+     */
+    interface NextAction {
+        type: 'poll' | 'retry' | 'verify_result' | 'fix_request';
+        afterMs?: number;
+        requiresNewIdempotencyKey?: boolean;
+        url?: string;
+    }
+    /**
+     * Stable fingerprint and sanitized payload for replay checks.
+     */
+    interface Request {
+        /**
+         * Stable hash of account, action, target, and payload.
+         */
+        hash: string | null;
+        /**
+         * Exact sanitized payload dispatched for this action.
+         */
+        payload: {
+            [key: string]: unknown;
+        } | null;
+    }
+    /**
+     * Confirmed result produced by the write, when available.
+     */
+    interface Result {
+        id?: string;
+        state?: string;
+        type?: 'tweet' | 'direct_message' | 'media' | 'community' | 'state_change';
+    }
+    /**
+     * Existing X resource targeted by the write, when applicable.
+     */
+    interface Target {
+        id: string;
+        type: 'tweet' | 'user' | 'community';
+    }
 }
 export interface MediaDownloadParams {
     /**
@@ -64,13 +225,20 @@ export interface MediaDownloadParams {
 }
 export interface MediaUploadParams {
     /**
-     * X account (@username or ID) uploading media from URL
+     * Body param: X account (@username or ID) uploading media from URL
      */
     account: string;
     /**
-     * HTTPS URL to download and upload as media
+     * Body param: HTTPS URL to download and upload as media
      */
     url: string;
+    /**
+     * Header param: Generate one unique value for each intended write. Reuse it only
+     * when retrying the exact same account, action, target, and payload. A reused key
+     * returns the original action. Reusing it with different input returns 409. Replay
+     * protection remains active for at least 90 days.
+     */
+    'Idempotency-Key': string;
 }
 export declare namespace Media {
     export { type MediaDownloadResponse as MediaDownloadResponse, type MediaUploadResponse as MediaUploadResponse, type MediaDownloadParams as MediaDownloadParams, type MediaUploadParams as MediaUploadParams, };

package/resources/x/media.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"media.d.mts","sourceRoot":"","sources":["../../src/resources/x/media.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,gCAA4B;AAClD,OAAO,EAAE,UAAU,EAAE,mCAA+B;AACpD,OAAO,EAAE,cAAc,EAAE,2CAAuC;AAGhE;;GAEG;AACH,qBAAa,KAAM,SAAQ,WAAW;IACpC;;;;;;;;;OASG;IACH,QAAQ,CAAC,IAAI,EAAE,mBAAmB,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,qBAAqB,CAAC;IAIhG;;;;;;;;;;OAUG;IACH,MAAM,CAAC,IAAI,EAAE,iBAAiB,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,mBAAmB,CAAC;CAM3F;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB,OAAO,EAAE,IAAI,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,QAAQ,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAEzB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,CAAC,OAAO,WAAW,KAAK,CAAC;IAC7B,OAAO,EACL,KAAK,qBAAqB,IAAI,qBAAqB,EACnD,KAAK,mBAAmB,IAAI,mBAAmB,EAC/C,KAAK,mBAAmB,IAAI,mBAAmB,EAC/C,KAAK,iBAAiB,IAAI,iBAAiB,GAC5C,CAAC;CACH"}
+{"version":3,"file":"media.d.mts","sourceRoot":"","sources":["../../src/resources/x/media.ts"],"names":[],"mappings":"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"}

package/resources/x/media.d.ts

@@ -1,9 +1,6 @@
 import { APIResource } from "../../core/resource.js";
 import { APIPromise } from "../../core/api-promise.js";
 import { RequestOptions } from "../../internal/request-options.js";
-/**
- * Media upload and download
- */
 export declare class Media extends APIResource {
     /**
      * Download images and videos from tweets
@@ -24,10 +21,11 @@ export declare class Media extends APIResource {
      * const response = await client.x.media.upload({
      *   account: '@elonmusk',
      *   url: 'https://example.com/image.png',
+     *   'Idempotency-Key': 'Idempotency-Key',
      * });
      * ```
      */
-    upload(body: MediaUploadParams, options?: RequestOptions): APIPromise<MediaUploadResponse>;
+    upload(params: MediaUploadParams, options?: RequestOptions): APIPromise<MediaUploadResponse>;
 }
 export interface MediaDownloadResponse {
     cacheHit?: boolean;
@@ -36,13 +34,176 @@ export interface MediaDownloadResponse {
     totalTweets?: number;
     tweetId?: string;
 }
+/**
+ * Durable write lifecycle record. Poll statusUrl until terminal is true. Reusing
+ * the original Idempotency-Key returns this same record. Submit a new write only
+ * when safeToRetry is true, using a new key.
+ */
 export interface MediaUploadResponse {
-    mediaId: string;
+    id: string;
+    /**
+     * Connected account selected for the write.
+     */
+    account: MediaUploadResponse.Account | null;
+    action: 'create_tweet' | 'delete_tweet' | 'like' | 'unlike' | 'retweet' | 'unretweet' | 'follow' | 'unfollow' | 'remove_follower' | 'send_dm' | 'upload_media' | 'update_profile' | 'update_avatar' | 'update_banner' | 'create_community' | 'delete_community' | 'join_community' | 'leave_community';
+    /**
+     * plannedCredits is the approved maximum. chargedCredits comes from the settled
+     * credit ledger. Pending or failed writes are not charged.
+     */
+    billing: MediaUploadResponse.Billing;
+    charged: boolean;
+    chargedCredits: string;
+    /**
+     * Exact follow-up an API client or agent should perform.
+     */
+    nextAction: MediaUploadResponse.NextAction | null;
+    object: 'x_write_action';
+    pollAfterMs: number | null;
+    /**
+     * Stable fingerprint and sanitized payload for replay checks.
+     */
+    request: MediaUploadResponse.Request;
+    /**
+     * Confirmed result produced by the write, when available.
+     */
+    result: MediaUploadResponse.Result | null;
+    /**
+     * True only when a new attempt can reasonably succeed.
+     */
+    retryable: boolean;
+    /**
+     * True only when no write was dispatched and a new idempotency key may be used.
+     */
+    safeToRetry: boolean;
+    sendDispatched: boolean;
+    status: 'accepted' | 'dispatching' | 'pending_confirmation' | 'success' | 'failed' | 'expired';
+    statusUrl: string;
+    success: boolean;
+    /**
+     * Existing X resource targeted by the write, when applicable.
+     */
+    target: MediaUploadResponse.Target | null;
+    targetId: string | null;
+    terminal: boolean;
+    writeActionId: string;
+    /**
+     * Compatibility field for a confirmed community ID.
+     */
+    communityId?: string;
+    /**
+     * Confirmed community name when available.
+     */
+    communityName?: string;
+    completedAt?: string;
+    confirmationAttempts?: number;
+    confirmationCheckedAt?: string;
+    confirmedAt?: string;
+    createdAt?: string;
+    /**
+     * Structured recovery context for a failed write.
+     */
+    details?: {
+        [key: string]: unknown;
+    };
+    error?: string;
+    /**
+     * Deadline for resolving a non-terminal write. This is not the Idempotency-Key
+     * retention deadline.
+     */
+    expiresAt?: string;
+    idempotent?: boolean;
     /**
-     * Public media URL for tweet `media` arrays.
+     * Media count, kind, size, and billing details when used.
      */
-    mediaUrl: string;
-    success: true;
+    media?: {
+        [key: string]: unknown;
+    };
+    /**
+     * Compatibility field for a confirmed media upload ID.
+     */
+    mediaId?: string;
+    /**
+     * Public media URL when the upload creates one.
+     */
+    mediaUrl?: string;
+    message?: string;
+    /**
+     * Compatibility field for a confirmed direct message ID.
+     */
+    messageId?: string;
+    requestHash?: string;
+    requestId?: string;
+    /**
+     * Compatibility result ID for other write actions.
+     */
+    resultId?: string;
+    /**
+     * Dispatch timestamp when the write reached execution.
+     */
+    sendDispatchedAt?: string;
+    /**
+     * Compatibility field for a confirmed tweet result ID.
+     */
+    tweetId?: string;
+    updatedAt?: string;
+}
+export declare namespace MediaUploadResponse {
+    /**
+     * Connected account selected for the write.
+     */
+    interface Account {
+        id: string;
+        username: string;
+    }
+    /**
+     * plannedCredits is the approved maximum. chargedCredits comes from the settled
+     * credit ledger. Pending or failed writes are not charged.
+     */
+    interface Billing {
+        charged: boolean;
+        chargedCredits: string;
+        plannedCredits: string;
+        status: 'not_charged' | 'pending' | 'charged' | 'charge_failed' | 'refunded';
+    }
+    /**
+     * Exact follow-up an API client or agent should perform.
+     */
+    interface NextAction {
+        type: 'poll' | 'retry' | 'verify_result' | 'fix_request';
+        afterMs?: number;
+        requiresNewIdempotencyKey?: boolean;
+        url?: string;
+    }
+    /**
+     * Stable fingerprint and sanitized payload for replay checks.
+     */
+    interface Request {
+        /**
+         * Stable hash of account, action, target, and payload.
+         */
+        hash: string | null;
+        /**
+         * Exact sanitized payload dispatched for this action.
+         */
+        payload: {
+            [key: string]: unknown;
+        } | null;
+    }
+    /**
+     * Confirmed result produced by the write, when available.
+     */
+    interface Result {
+        id?: string;
+        state?: string;
+        type?: 'tweet' | 'direct_message' | 'media' | 'community' | 'state_change';
+    }
+    /**
+     * Existing X resource targeted by the write, when applicable.
+     */
+    interface Target {
+        id: string;
+        type: 'tweet' | 'user' | 'community';
+    }
 }
 export interface MediaDownloadParams {
     /**
@@ -64,13 +225,20 @@ export interface MediaDownloadParams {
 }
 export interface MediaUploadParams {
     /**
-     * X account (@username or ID) uploading media from URL
+     * Body param: X account (@username or ID) uploading media from URL
      */
     account: string;
     /**
-     * HTTPS URL to download and upload as media
+     * Body param: HTTPS URL to download and upload as media
      */
     url: string;
+    /**
+     * Header param: Generate one unique value for each intended write. Reuse it only
+     * when retrying the exact same account, action, target, and payload. A reused key
+     * returns the original action. Reusing it with different input returns 409. Replay
+     * protection remains active for at least 90 days.
+     */
+    'Idempotency-Key': string;
 }
 export declare namespace Media {
     export { type MediaDownloadResponse as MediaDownloadResponse, type MediaUploadResponse as MediaUploadResponse, type MediaDownloadParams as MediaDownloadParams, type MediaUploadParams as MediaUploadParams, };

package/resources/x/media.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"media.d.ts","sourceRoot":"","sources":["../../src/resources/x/media.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,+BAA4B;AAClD,OAAO,EAAE,UAAU,EAAE,kCAA+B;AACpD,OAAO,EAAE,cAAc,EAAE,0CAAuC;AAGhE;;GAEG;AACH,qBAAa,KAAM,SAAQ,WAAW;IACpC;;;;;;;;;OASG;IACH,QAAQ,CAAC,IAAI,EAAE,mBAAmB,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,qBAAqB,CAAC;IAIhG;;;;;;;;;;OAUG;IACH,MAAM,CAAC,IAAI,EAAE,iBAAiB,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,mBAAmB,CAAC;CAM3F;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB,OAAO,EAAE,IAAI,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,QAAQ,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAEzB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,CAAC,OAAO,WAAW,KAAK,CAAC;IAC7B,OAAO,EACL,KAAK,qBAAqB,IAAI,qBAAqB,EACnD,KAAK,mBAAmB,IAAI,mBAAmB,EAC/C,KAAK,mBAAmB,IAAI,mBAAmB,EAC/C,KAAK,iBAAiB,IAAI,iBAAiB,GAC5C,CAAC;CACH"}
+{"version":3,"file":"media.d.ts","sourceRoot":"","sources":["../../src/resources/x/media.ts"],"names":[],"mappings":"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"}

package/resources/x/media.js

@@ -3,10 +3,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Media = void 0;
 const resource_1 = require("../../core/resource.js");
+const headers_1 = require("../../internal/headers.js");
 const uploads_1 = require("../../internal/uploads.js");
-/**
- * Media upload and download
- */
 class Media extends resource_1.APIResource {
     /**
      * Download images and videos from tweets
@@ -29,11 +27,17 @@ class Media extends resource_1.APIResource {
      * const response = await client.x.media.upload({
      *   account: '@elonmusk',
      *   url: 'https://example.com/image.png',
+     *   'Idempotency-Key': 'Idempotency-Key',
      * });
      * ```
      */
-    upload(body, options) {
-        return this._client.post('/x/media', (0, uploads_1.maybeMultipartFormRequestOptions)({ body, ...options }, this._client));
+    upload(params, options) {
+        const { 'Idempotency-Key': idempotencyKey, ...body } = params;
+        return this._client.post('/x/media', (0, uploads_1.maybeMultipartFormRequestOptions)({
+            body,
+            ...options,
+            headers: (0, headers_1.buildHeaders)([{ 'Idempotency-Key': idempotencyKey }, options?.headers]),
+        }, this._client));
     }
 }
 exports.Media = Media;

package/resources/x/media.js.map

@@ -1 +1 @@
-{"version":3,"file":"media.js","sourceRoot":"","sources":["../../src/resources/x/media.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;AAEtF,qDAAkD;AAGlD,uDAA0E;AAE1E;;GAEG;AACH,MAAa,KAAM,SAAQ,sBAAW;IACpC;;;;;;;;;OASG;IACH,QAAQ,CAAC,IAAyB,EAAE,OAAwB;QAC1D,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,mBAAmB,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACtE,CAAC;IAED;;;;;;;;;;OAUG;IACH,MAAM,CAAC,IAAuB,EAAE,OAAwB;QACtD,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CACtB,UAAU,EACV,IAAA,0CAAgC,EAAC,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC,CACrE,CAAC;IACJ,CAAC;CACF;AAhCD,sBAgCC"}
+{"version":3,"file":"media.js","sourceRoot":"","sources":["../../src/resources/x/media.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;AAEtF,qDAAkD;AAElD,uDAAsD;AAEtD,uDAA0E;AAE1E,MAAa,KAAM,SAAQ,sBAAW;IACpC;;;;;;;;;OASG;IACH,QAAQ,CAAC,IAAyB,EAAE,OAAwB;QAC1D,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,mBAAmB,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACtE,CAAC;IAED;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,MAAyB,EAAE,OAAwB;QACxD,MAAM,EAAE,iBAAiB,EAAE,cAAc,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;QAC9D,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CACtB,UAAU,EACV,IAAA,0CAAgC,EAC9B;YACE,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,EAAE,iBAAiB,EAAE,cAAc,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SACjF,EACD,IAAI,CAAC,OAAO,CACb,CACF,CAAC;IACJ,CAAC;CACF;AAzCD,sBAyCC"}

package/resources/x/media.mjs

@@ -1,9 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 import { APIResource } from "../../core/resource.mjs";
+import { buildHeaders } from "../../internal/headers.mjs";
 import { maybeMultipartFormRequestOptions } from "../../internal/uploads.mjs";
-/**
- * Media upload and download
- */
 export class Media extends APIResource {
     /**
      * Download images and videos from tweets
@@ -26,11 +24,17 @@ export class Media extends APIResource {
      * const response = await client.x.media.upload({
      *   account: '@elonmusk',
      *   url: 'https://example.com/image.png',
+     *   'Idempotency-Key': 'Idempotency-Key',
      * });
      * ```
      */
-    upload(body, options) {
-        return this._client.post('/x/media', maybeMultipartFormRequestOptions({ body, ...options }, this._client));
+    upload(params, options) {
+        const { 'Idempotency-Key': idempotencyKey, ...body } = params;
+        return this._client.post('/x/media', maybeMultipartFormRequestOptions({
+            body,
+            ...options,
+            headers: buildHeaders([{ 'Idempotency-Key': idempotencyKey }, options?.headers]),
+        }, this._client));
     }
 }
 //# sourceMappingURL=media.mjs.map

package/resources/x/media.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"media.mjs","sourceRoot":"","sources":["../../src/resources/x/media.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAEtF,OAAO,EAAE,WAAW,EAAE,gCAA4B;AAGlD,OAAO,EAAE,gCAAgC,EAAE,mCAA+B;AAE1E;;GAEG;AACH,MAAM,OAAO,KAAM,SAAQ,WAAW;IACpC;;;;;;;;;OASG;IACH,QAAQ,CAAC,IAAyB,EAAE,OAAwB;QAC1D,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,mBAAmB,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACtE,CAAC;IAED;;;;;;;;;;OAUG;IACH,MAAM,CAAC,IAAuB,EAAE,OAAwB;QACtD,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CACtB,UAAU,EACV,gCAAgC,CAAC,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC,CACrE,CAAC;IACJ,CAAC;CACF"}
+{"version":3,"file":"media.mjs","sourceRoot":"","sources":["../../src/resources/x/media.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAEtF,OAAO,EAAE,WAAW,EAAE,gCAA4B;AAElD,OAAO,EAAE,YAAY,EAAE,mCAA+B;AAEtD,OAAO,EAAE,gCAAgC,EAAE,mCAA+B;AAE1E,MAAM,OAAO,KAAM,SAAQ,WAAW;IACpC;;;;;;;;;OASG;IACH,QAAQ,CAAC,IAAyB,EAAE,OAAwB;QAC1D,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,mBAAmB,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACtE,CAAC;IAED;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,MAAyB,EAAE,OAAwB;QACxD,MAAM,EAAE,iBAAiB,EAAE,cAAc,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;QAC9D,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CACtB,UAAU,EACV,gCAAgC,CAC9B;YACE,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,iBAAiB,EAAE,cAAc,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SACjF,EACD,IAAI,CAAC,OAAO,CACb,CACF,CAAC;IACJ,CAAC;CACF"}