x-twitter-scraper 0.4.1 → 0.5.0

package/src/resources/x/profile.ts

@@ -2,6 +2,7 @@
 
 import { APIResource } from '../../core/resource';
 import { APIPromise } from '../../core/api-promise';
+import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 import { maybeMultipartFormRequestOptions } from '../../internal/uploads';
 
@@ -16,6 +17,7 @@ export class Profile extends APIResource {
    * ```ts
    * const profile = await client.x.profile.update({
    *   account: '@elonmusk',
+   *   'Idempotency-Key': 'Idempotency-Key',
    *   description: 'description_value',
    *   location: 'location_value',
    *   name: 'Example Name',
@@ -23,8 +25,13 @@ export class Profile extends APIResource {
    * });
    * ```
    */
-  update(body: ProfileUpdateParams, options?: RequestOptions): APIPromise<ProfileUpdateResponse> {
-    return this._client.patch('/x/profile', { body, ...options });
+  update(params: ProfileUpdateParams, options?: RequestOptions): APIPromise<ProfileUpdateResponse> {
+    const { 'Idempotency-Key': idempotencyKey, ...body } = params;
+    return this._client.patch('/x/profile', {
+      body,
+      ...options,
+      headers: buildHeaders([{ 'Idempotency-Key': idempotencyKey }, options?.headers]),
+    });
   }
 
   /**
@@ -35,16 +42,25 @@ export class Profile extends APIResource {
    * const response = await client.x.profile.updateAvatar({
    *   account: '@elonmusk',
    *   url: 'https://example.com/avatar.png',
+   *   'Idempotency-Key': 'Idempotency-Key',
    * });
    * ```
    */
   updateAvatar(
-    body: ProfileUpdateAvatarParams,
+    params: ProfileUpdateAvatarParams,
     options?: RequestOptions,
   ): APIPromise<ProfileUpdateAvatarResponse> {
+    const { 'Idempotency-Key': idempotencyKey, ...body } = params;
     return this._client.patch(
       '/x/profile/avatar',
-      maybeMultipartFormRequestOptions({ body, ...options }, this._client),
+      maybeMultipartFormRequestOptions(
+        {
+          body,
+          ...options,
+          headers: buildHeaders([{ 'Idempotency-Key': idempotencyKey }, options?.headers]),
+        },
+        this._client,
+      ),
     );
   }
 
@@ -56,78 +72,831 @@ export class Profile extends APIResource {
    * const response = await client.x.profile.updateBanner({
    *   account: '@elonmusk',
    *   url: 'https://example.com/banner.png',
+   *   'Idempotency-Key': 'Idempotency-Key',
    * });
    * ```
    */
   updateBanner(
-    body: ProfileUpdateBannerParams,
+    params: ProfileUpdateBannerParams,
     options?: RequestOptions,
   ): APIPromise<ProfileUpdateBannerResponse> {
+    const { 'Idempotency-Key': idempotencyKey, ...body } = params;
     return this._client.patch(
       '/x/profile/banner',
-      maybeMultipartFormRequestOptions({ body, ...options }, this._client),
+      maybeMultipartFormRequestOptions(
+        {
+          body,
+          ...options,
+          headers: buildHeaders([{ 'Idempotency-Key': idempotencyKey }, options?.headers]),
+        },
+        this._client,
+      ),
     );
   }
 }
 
+/**
+ * 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 ProfileUpdateResponse {
-  success: true;
+  id: string;
+
+  /**
+   * Connected account selected for the write.
+   */
+  account: ProfileUpdateResponse.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: ProfileUpdateResponse.Billing;
+
+  charged: boolean;
+
+  chargedCredits: string;
+
+  /**
+   * Exact follow-up an API client or agent should perform.
+   */
+  nextAction: ProfileUpdateResponse.NextAction | null;
+
+  object: 'x_write_action';
+
+  pollAfterMs: number | null;
+
+  /**
+   * Stable fingerprint and sanitized payload for replay checks.
+   */
+  request: ProfileUpdateResponse.Request;
+
+  /**
+   * Confirmed result produced by the write, when available.
+   */
+  result: ProfileUpdateResponse.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: ProfileUpdateResponse.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;
+
+  /**
+   * Media count, kind, size, and billing details when used.
+   */
+  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 namespace ProfileUpdateResponse {
+  /**
+   * Connected account selected for the write.
+   */
+  export 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.
+   */
+  export 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.
+   */
+  export interface NextAction {
+    type: 'poll' | 'retry' | 'verify_result' | 'fix_request';
+
+    afterMs?: number;
+
+    requiresNewIdempotencyKey?: boolean;
+
+    url?: string;
+  }
+
+  /**
+   * Stable fingerprint and sanitized payload for replay checks.
+   */
+  export 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.
+   */
+  export interface Result {
+    id?: string;
+
+    state?: string;
+
+    type?: 'tweet' | 'direct_message' | 'media' | 'community' | 'state_change';
+  }
+
+  /**
+   * Existing X resource targeted by the write, when applicable.
+   */
+  export interface Target {
+    id: string;
+
+    type: 'tweet' | 'user' | 'community';
+  }
+}
+
+/**
+ * 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 ProfileUpdateAvatarResponse {
-  success: true;
+  id: string;
+
+  /**
+   * Connected account selected for the write.
+   */
+  account: ProfileUpdateAvatarResponse.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: ProfileUpdateAvatarResponse.Billing;
+
+  charged: boolean;
+
+  chargedCredits: string;
+
+  /**
+   * Exact follow-up an API client or agent should perform.
+   */
+  nextAction: ProfileUpdateAvatarResponse.NextAction | null;
+
+  object: 'x_write_action';
+
+  pollAfterMs: number | null;
+
+  /**
+   * Stable fingerprint and sanitized payload for replay checks.
+   */
+  request: ProfileUpdateAvatarResponse.Request;
+
+  /**
+   * Confirmed result produced by the write, when available.
+   */
+  result: ProfileUpdateAvatarResponse.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: ProfileUpdateAvatarResponse.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;
+
+  /**
+   * Media count, kind, size, and billing details when used.
+   */
+  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 namespace ProfileUpdateAvatarResponse {
+  /**
+   * Connected account selected for the write.
+   */
+  export 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.
+   */
+  export 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.
+   */
+  export interface NextAction {
+    type: 'poll' | 'retry' | 'verify_result' | 'fix_request';
+
+    afterMs?: number;
+
+    requiresNewIdempotencyKey?: boolean;
+
+    url?: string;
+  }
+
+  /**
+   * Stable fingerprint and sanitized payload for replay checks.
+   */
+  export 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.
+   */
+  export interface Result {
+    id?: string;
+
+    state?: string;
+
+    type?: 'tweet' | 'direct_message' | 'media' | 'community' | 'state_change';
+  }
+
+  /**
+   * Existing X resource targeted by the write, when applicable.
+   */
+  export interface Target {
+    id: string;
+
+    type: 'tweet' | 'user' | 'community';
+  }
+}
+
+/**
+ * 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 ProfileUpdateBannerResponse {
-  success: true;
+  id: string;
+
+  /**
+   * Connected account selected for the write.
+   */
+  account: ProfileUpdateBannerResponse.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: ProfileUpdateBannerResponse.Billing;
+
+  charged: boolean;
+
+  chargedCredits: string;
+
+  /**
+   * Exact follow-up an API client or agent should perform.
+   */
+  nextAction: ProfileUpdateBannerResponse.NextAction | null;
+
+  object: 'x_write_action';
+
+  pollAfterMs: number | null;
+
+  /**
+   * Stable fingerprint and sanitized payload for replay checks.
+   */
+  request: ProfileUpdateBannerResponse.Request;
+
+  /**
+   * Confirmed result produced by the write, when available.
+   */
+  result: ProfileUpdateBannerResponse.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: ProfileUpdateBannerResponse.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;
+
+  /**
+   * Media count, kind, size, and billing details when used.
+   */
+  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 namespace ProfileUpdateBannerResponse {
+  /**
+   * Connected account selected for the write.
+   */
+  export 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.
+   */
+  export 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.
+   */
+  export interface NextAction {
+    type: 'poll' | 'retry' | 'verify_result' | 'fix_request';
+
+    afterMs?: number;
+
+    requiresNewIdempotencyKey?: boolean;
+
+    url?: string;
+  }
+
+  /**
+   * Stable fingerprint and sanitized payload for replay checks.
+   */
+  export 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.
+   */
+  export interface Result {
+    id?: string;
+
+    state?: string;
+
+    type?: 'tweet' | 'direct_message' | 'media' | 'community' | 'state_change';
+  }
+
+  /**
+   * Existing X resource targeted by the write, when applicable.
+   */
+  export interface Target {
+    id: string;
+
+    type: 'tweet' | 'user' | 'community';
+  }
 }
 
 export interface ProfileUpdateParams {
   /**
-   * X account (@username or ID) to update profile
+   * Body param: X account (@username or ID) to update profile
    */
   account: string;
 
   /**
-   * Bio description
+   * 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;
+
+  /**
+   * Body param: Bio description
    */
   description?: string;
 
+  /**
+   * Body param
+   */
   location?: string;
 
   /**
-   * Display name
+   * Body param: Display name
    */
   name?: string;
 
   /**
-   * Website URL
+   * Body param: Website URL
    */
   url?: string;
 }
 
 export interface ProfileUpdateAvatarParams {
   /**
-   * X account (@username or ID) receiving avatar from URL
+   * Body param: X account (@username or ID) receiving avatar from URL
    */
   account: string;
 
   /**
-   * HTTPS URL to the avatar image to download
+   * Body param: HTTPS URL to the avatar image to download
    */
   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 interface ProfileUpdateBannerParams {
   /**
-   * X account (@username or ID) receiving banner from URL
+   * Body param: X account (@username or ID) receiving banner from URL
    */
   account: string;
 
   /**
-   * HTTPS URL to the banner image to download
+   * Body param: HTTPS URL to the banner image to download
    */
   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 Profile {