x-twitter-scraper 0.12.3 → 0.13.0

package/src/resources/x/dm.ts

@@ -12,7 +12,37 @@ import { path } from '../../internal/utils/path';
 
 export class Dm extends APIResource {
   /**
-   * Get DM conversation history
+   * Deletes 1 DM from the account's side; the other person keeps it. Success means
+   * the account's conversation no longer shows it. Still shown gets 422
+   * `x_dm_not_deleted`, uncharged.
+   *
+   * @example
+   * ```ts
+   * const response = await client.x.dm.deleteMessage(
+   *   '321669910225',
+   *   {
+   *     userId: 'userId',
+   *     account: 'account',
+   *     'Idempotency-Key': 'Idempotency-Key',
+   *   },
+   * );
+   * ```
+   */
+  deleteMessage(
+    messageID: string,
+    params: DmDeleteMessageParams,
+    options?: RequestOptions,
+  ): APIPromise<DmDeleteMessageResponse> {
+    const { userId, account, 'Idempotency-Key': idempotencyKey } = params;
+    return this._client.delete(path`/x/dm/${userId}/messages/${messageID}`, {
+      query: { account },
+      ...options,
+      headers: buildHeaders([{ 'Idempotency-Key': idempotencyKey }, options?.headers]),
+    });
+  }
+
+  /**
+   * Returns message history with one user for the connected X account.
    *
    * @example
    * ```ts
@@ -31,7 +61,9 @@ export class Dm extends APIResource {
   }
 
   /**
-   * Send direct message
+   * Sends a direct message through a connected X account. Once X rate limits an
+   * account's DMs, its DMs get 429 until X's reset. Xquik sends nothing to X &
+   * charges nothing. `Retry-After` & `nextAction.afterMs` give the wait.
    *
    * @example
    * ```ts
@@ -53,6 +85,257 @@ export class Dm extends APIResource {
   }
 }
 
+/**
+ * Durable write record. Poll statusUrl until terminal is true. Reusing its
+ * Idempotency-Key returns this record. Create another action only when safeToRetry
+ * is true.
+ */
+export interface DmDeleteMessageResponse {
+  id: string;
+
+  /**
+   * Connected account selected for the write.
+   */
+  account: DmDeleteMessageResponse.Account | null;
+
+  action:
+    | 'create_tweet'
+    | 'delete_tweet'
+    | 'like'
+    | 'unlike'
+    | 'retweet'
+    | 'unretweet'
+    | 'follow'
+    | 'unfollow'
+    | 'remove_follower'
+    | 'send_dm'
+    | 'delete_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: DmDeleteMessageResponse.Billing;
+
+  charged: boolean;
+
+  chargedCredits: string;
+
+  /**
+   * Exact follow-up an API client or agent should perform.
+   */
+  nextAction: DmDeleteMessageResponse.NextAction | null;
+
+  object: 'x_write_action';
+
+  pollAfterMs: number | null;
+
+  /**
+   * Stable fingerprint and sanitized payload for replay checks.
+   */
+  request: DmDeleteMessageResponse.Request;
+
+  /**
+   * Confirmed result produced by the write, when available.
+   */
+  result: DmDeleteMessageResponse.Result | null;
+
+  /**
+   * True only when a new attempt can reasonably succeed.
+   */
+  retryable: boolean;
+
+  /**
+   * True only when X did not get the write 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: DmDeleteMessageResponse.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;
+
+  /**
+   * True when this answers a retry of an earlier request with the same
+   * Idempotency-Key.
+   */
+  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 DmDeleteMessageResponse {
+  /**
+   * 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';
+
+    /**
+     * Milliseconds to wait before you poll or retry.
+     */
+    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 DmRetrieveHistoryResponse {
   has_next_page: boolean;
 
@@ -77,14 +360,17 @@ export namespace DmRetrieveHistoryResponse {
      */
     mediaUrl?: string;
 
+    /**
+     * Text as x.com shows it, with `&`, `<` & `>` decoded.
+     */
     text?: 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.
+ * Durable write record. Poll statusUrl until terminal is true. Reusing its
+ * Idempotency-Key returns this record. Create another action only when safeToRetry
+ * is true.
  */
 export interface DmSendResponse {
   id: string;
@@ -105,6 +391,7 @@ export interface DmSendResponse {
     | 'unfollow'
     | 'remove_follower'
     | 'send_dm'
+    | 'delete_dm'
     | 'upload_media'
     | 'update_profile'
     | 'update_avatar'
@@ -149,7 +436,7 @@ export interface DmSendResponse {
   retryable: boolean;
 
   /**
-   * True only when no write was dispatched and a new idempotency key may be used.
+   * True only when X did not get the write and a new idempotency key may be used.
    */
   safeToRetry: boolean;
 
@@ -205,6 +492,10 @@ export interface DmSendResponse {
    */
   expiresAt?: string;
 
+  /**
+   * True when this answers a retry of an earlier request with the same
+   * Idempotency-Key.
+   */
   idempotent?: boolean;
 
   /**
@@ -281,6 +572,9 @@ export namespace DmSendResponse {
   export interface NextAction {
     type: 'poll' | 'retry' | 'verify_result' | 'fix_request';
 
+    /**
+     * Milliseconds to wait before you poll or retry.
+     */
     afterMs?: number;
 
     requiresNewIdempotencyKey?: boolean;
@@ -324,6 +618,30 @@ export namespace DmSendResponse {
   }
 }
 
+export interface DmDeleteMessageParams {
+  /**
+   * Path param: The other person in the conversation: user ID, username with or
+   * without @, or URL-encoded profile URL, such as x.com/nasa. Xquik looks up a
+   * username's ID first. Anything else gets 400 `invalid_user_id`.
+   */
+  userId: string;
+
+  /**
+   * Query param: Connected X account (@username or ID) that sees the DM.
+   */
+  account: string;
+
+  /**
+   * Header param: Use one unique value per intended write. Reuse it only for an
+   * identical retry. A matching retry returns the first answer again, with
+   * idempotent: true added. It keeps the first status, body & Retry-After. It sends
+   * nothing to X & charges nothing. While the first request runs, a retry returns
+   * 202 & the action. Different input returns 409. Protection lasts at least 90
+   * days.
+   */
+  'Idempotency-Key': string;
+}
+
 export interface DmRetrieveHistoryParams {
   /**
    * X handle (without the `@` prefix) of the connected X account used to read the
@@ -332,7 +650,8 @@ export interface DmRetrieveHistoryParams {
   account: string;
 
   /**
-   * Pagination cursor for DM history
+   * Pagination cursor for collection results. Also read as next_cursor, next_token,
+   * pagination_token or continuation_token.
    */
   cursor?: string;
 
@@ -354,10 +673,12 @@ export interface DmSendParams {
   text: 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.
+   * Header param: Use one unique value per intended write. Reuse it only for an
+   * identical retry. A matching retry returns the first answer again, with
+   * idempotent: true added. It keeps the first status, body & Retry-After. It sends
+   * nothing to X & charges nothing. While the first request runs, a retry returns
+   * 202 & the action. Different input returns 409. Protection lasts at least 90
+   * days.
    */
   'Idempotency-Key': string;
 
@@ -369,8 +690,10 @@ export interface DmSendParams {
 
 export declare namespace Dm {
   export {
+    type DmDeleteMessageResponse as DmDeleteMessageResponse,
     type DmRetrieveHistoryResponse as DmRetrieveHistoryResponse,
     type DmSendResponse as DmSendResponse,
+    type DmDeleteMessageParams as DmDeleteMessageParams,
     type DmRetrieveHistoryParams as DmRetrieveHistoryParams,
     type DmSendParams as DmSendParams,
   };

package/src/resources/x/followers.ts

@@ -13,7 +13,8 @@ import { RequestOptions } from '../../internal/request-options';
  */
 export class Followers extends APIResource {
   /**
-   * Check if one user follows another
+   * Returns whether one public account follows another, & the reverse, with each
+   * account's username & user ID as X names them.
    *
    * @example
    * ```ts
@@ -35,19 +36,50 @@ export interface FollowerCheckResponse {
 
   sourceUsername: string;
 
+  /**
+   * The target account's username, in lower case.
+   */
   targetUsername: string;
+
+  /**
+   * The source account's user ID, as X gives it.
+   */
+  sourceId?: string;
+
+  /**
+   * The target account's user ID, as X gives it.
+   */
+  targetId?: string;
 }
 
 export interface FollowerCheckParams {
   /**
-   * Source username, @username, or X or Twitter profile URL
+   * Source user ID, username, @username, or X or Twitter profile URL, such as
+   * x.com/i/user/11348282. A number is a user ID.
    */
   source: string;
 
   /**
-   * Target username, @username, or X or Twitter profile URL
+   * Target user ID, username, @username, or X or Twitter profile URL, such as
+   * x.com/i/user/11348282. A number is a user ID.
    */
   target: string;
+
+  /**
+   * Fields to keep in each row, comma-separated. Use dots for nested fields, such as
+   * author.username. A list keeps the field in each item. Case & underscores do not
+   * matter. A row that lacks a field leaves it out. Cursors, counts & diagnostics
+   * always stay. An unknown name answers 400 unknown_field with the valid names,
+   * before any read. The price stays the same. SDK row types then hold only the
+   * named fields.
+   */
+  fields?: string;
+
+  /**
+   * Fields to drop from each row, comma-separated. It takes the same names as
+   * fields. With fields, it drops from the kept fields.
+   */
+  omit?: string;
 }
 
 export declare namespace Followers {

package/src/resources/x/index.ts

@@ -23,32 +23,79 @@ export {
   type AccountBulkRetryResponse,
   type AccountReauthResponse,
   type AccountCreateParams,
+  type AccountListParams,
   type AccountReauthParams,
 } from './accounts';
-export { Bookmarks, type BookmarkRetrieveFoldersResponse, type BookmarkListParams } from './bookmarks';
+export {
+  Analysis,
+  type AnalysisBrandResponse,
+  type AnalysisClassifyResponse,
+  type AnalysisMarketSignalsResponse,
+  type AnalysisNewsResponse,
+  type AnalysisSentimentResponse,
+  type AnalysisViralScoreResponse,
+  type AnalysisBrandParams,
+  type AnalysisClassifyParams,
+  type AnalysisMarketSignalsParams,
+  type AnalysisNewsParams,
+  type AnalysisSentimentParams,
+  type AnalysisViralScoreParams,
+} from './analysis';
+export {
+  Bookmarks,
+  type BookmarkRetrieveFoldersResponse,
+  type BookmarkListParams,
+  type BookmarkRetrieveFoldersParams,
+} from './bookmarks';
+export { Broadcasts, type BroadcastRetrieveResponse, type BroadcastRetrieveParams } from './broadcasts';
 export {
   Communities,
   type CommunityCreateResponse,
   type CommunityDeleteResponse,
+  type CommunityListSuggestedResponse,
+  type CommunityListTopicsResponse,
   type CommunityRetrieveInfoResponse,
   type CommunityCreateParams,
   type CommunityDeleteParams,
+  type CommunityFindParams,
+  type CommunityListPopularParams,
+  type CommunityListSuggestedParams,
+  type CommunityListTopicsParams,
+  type CommunityRetrieveInfoParams,
   type CommunityRetrieveMembersParams,
   type CommunityRetrieveModeratorsParams,
   type CommunityRetrieveSearchParams,
+  type CommunitySearchMembersParams,
 } from './communities/index';
 export {
   Dm,
+  type DmDeleteMessageResponse,
   type DmRetrieveHistoryResponse,
   type DmSendResponse,
+  type DmDeleteMessageParams,
   type DmRetrieveHistoryParams,
   type DmSendParams,
 } from './dm';
 export { Followers, type FollowerCheckResponse, type FollowerCheckParams } from './followers';
+export {
+  Jobs,
+  type JobRetrieveResponse,
+  type JobListLocationsResponse,
+  type JobSearchResponse,
+  type JobRetrieveParams,
+  type JobListLocationsParams,
+  type JobSearchParams,
+} from './jobs';
 export {
   Lists,
+  type ListRetrieveResponse,
+  type ListRetrieveFollowersResponse,
+  type ListRetrieveMembersResponse,
+  type ListRetrieveSearchResponse,
+  type ListRetrieveParams,
   type ListRetrieveFollowersParams,
   type ListRetrieveMembersParams,
+  type ListRetrieveSearchParams,
   type ListRetrieveTweetsParams,
 } from './lists';
 export {
@@ -67,52 +114,110 @@ export {
   type ProfileUpdateAvatarParams,
   type ProfileUpdateBannerParams,
 } from './profile';
+export {
+  Spaces,
+  type SpaceRetrieveResponse,
+  type SpaceRetrieveReplayResponse,
+  type SpaceSearchResponse,
+  type SpaceRetrieveParams,
+  type SpaceRetrieveReplayParams,
+  type SpaceSearchParams,
+} from './spaces';
 export {
   Tweets,
   type TweetAuthor,
   type TweetDetail,
   type TweetCreateResponse,
   type TweetRetrieveResponse,
+  type TweetListResponse,
   type TweetDeleteResponse,
+  type TweetCheckRepostResponse,
+  type TweetEmbedResponse,
+  type TweetGetInsightsResponse,
   type TweetGetRepliesResponse,
+  type TweetGetRetweeterIDsResponse,
+  type TweetGetSubtitlesResponse,
+  type TweetResolveLinksResponse,
   type TweetSearchResponse,
+  type TweetTranslateResponse,
   type TweetCreateParams,
+  type TweetRetrieveParams,
   type TweetListParams,
   type TweetDeleteParams,
+  type TweetCheckRepostParams,
+  type TweetEmbedParams,
   type TweetGetFavoritersParams,
+  type TweetGetHiddenRepliesParams,
+  type TweetGetInsightsParams,
   type TweetGetQuotesParams,
   type TweetGetRepliesParams,
+  type TweetGetRetweeterIDsParams,
   type TweetGetRetweetersParams,
+  type TweetGetSubtitlesParams,
   type TweetGetThreadParams,
+  type TweetListTopParams,
+  type TweetResolveLinksParams,
   type TweetSearchParams,
+  type TweetTranslateParams,
 } from './tweets/index';
 export {
   Users,
   type UserRemoveFollowerResponse,
   type UserRetrieveBatchResponse,
+  type UserRetrieveBatchTweetsResponse,
+  type UserRetrieveFollowerIDsResponse,
   type UserRetrieveFollowersResponse,
   type UserRetrieveFollowingResponse,
+  type UserRetrieveFollowingIDsResponse,
+  type UserRetrieveInsightsResponse,
+  type UserRetrieveListMembershipsResponse,
+  type UserRetrieveListsResponse,
+  type UserRetrieveLiveResponse,
   type UserRetrieveVerifiedFollowersResponse,
+  type UserTranslateBioResponse,
+  type UserRetrieveParams,
   type UserRemoveFollowerParams,
+  type UserRetrieveAffiliatesParams,
+  type UserRetrieveArticlesParams,
   type UserRetrieveBatchParams,
+  type UserRetrieveBatchTweetsParams,
+  type UserRetrieveFollowerIDsParams,
   type UserRetrieveFollowersParams,
   type UserRetrieveFollowersYouKnowParams,
   type UserRetrieveFollowingParams,
+  type UserRetrieveFollowingIDsParams,
+  type UserRetrieveHighlightsParams,
+  type UserRetrieveInsightsParams,
   type UserRetrieveLikesParams,
+  type UserRetrieveListMembershipsParams,
+  type UserRetrieveListsParams,
+  type UserRetrieveLiveParams,
   type UserRetrieveMediaParams,
   type UserRetrieveMentionsParams,
   type UserRetrieveRepliesParams,
   type UserRetrieveSearchParams,
+  type UserRetrieveSimilarParams,
+  type UserRetrieveSubscriptionsParams,
   type UserRetrieveTweetsParams,
   type UserRetrieveVerifiedFollowersParams,
+  type UserTranslateBioParams,
 } from './users/index';
 export { WriteActions, type WriteActionRetrieveResponse } from './write-actions';
 export {
   X,
+  type XAutocompleteSearchResponse,
   type XGetArticleResponse,
+  type XGetHashflagsResponse,
   type XGetNotificationsResponse,
+  type XGetTrendLocationsResponse,
   type XGetTrendsResponse,
+  type XSearchPlacesResponse,
+  type XAutocompleteSearchParams,
+  type XGetArticleParams,
+  type XGetHashflagsParams,
   type XGetHomeTimelineParams,
   type XGetNotificationsParams,
+  type XGetTrendLocationsParams,
   type XGetTrendsParams,
+  type XSearchPlacesParams,
 } from './x';