@the-convocation/twitter-scraper 0.15.0 → 0.16.0

package/dist/types/index.d.ts

@@ -1,3 +1,5 @@
+import * as _sinclair_typebox from '@sinclair/typebox';
+import { Static } from '@sinclair/typebox';
 import { Cookie } from 'tough-cookie';
 import fetch from 'cross-fetch';
 
@@ -21,13 +23,6 @@ interface FetchTransformOptions {
     response: (response: Response) => Response | Promise<Response>;
 }
 
-declare class ApiError extends Error {
-    readonly response: Response;
-    readonly data: any;
-    private constructor();
-    static fromResponse(response: Response): Promise<ApiError>;
-}
-
 /**
  * Information about a rate-limiting event. Both the request and response
  * information are provided.
@@ -81,6 +76,185 @@ declare class ErrorRateLimitStrategy implements RateLimitStrategy {
     onRateLimit({ response: res }: RateLimitEvent): Promise<void>;
 }
 
+declare class ApiError extends Error {
+    readonly response: Response;
+    readonly data: any;
+    constructor(response: Response, data: any, message: string);
+    static fromResponse(response: Response): Promise<ApiError>;
+}
+declare class AuthenticationError extends Error {
+    constructor(message?: string);
+}
+interface TwitterApiErrorPosition {
+    line: number;
+    column: number;
+}
+interface TwitterApiErrorTraceInfo {
+    trace_id: string;
+}
+interface TwitterApiErrorExtensions {
+    code?: number;
+    kind?: string;
+    name?: string;
+    source?: string;
+    tracing?: TwitterApiErrorTraceInfo;
+}
+interface TwitterApiErrorRaw extends TwitterApiErrorExtensions {
+    message?: string;
+    locations?: TwitterApiErrorPosition[];
+    path?: string[];
+    extensions?: TwitterApiErrorExtensions;
+}
+
+interface TwitterUserAuthFlowInitRequest {
+    flow_name: string;
+    input_flow_data: Record<string, unknown>;
+}
+interface TwitterUserAuthFlowSubtaskRequest {
+    flow_token: string;
+    subtask_inputs: ({
+        subtask_id: string;
+    } & Record<string, unknown>)[];
+}
+type TwitterUserAuthFlowRequest = TwitterUserAuthFlowInitRequest | TwitterUserAuthFlowSubtaskRequest;
+interface TwitterUserAuthFlowResponse {
+    errors?: TwitterApiErrorRaw[];
+    flow_token?: string;
+    status?: string;
+    subtasks?: TwitterUserAuthSubtask[];
+}
+declare const TwitterUserAuthSubtask: _sinclair_typebox.TObject<{
+    subtask_id: _sinclair_typebox.TString;
+    enter_text: _sinclair_typebox.TOptional<_sinclair_typebox.TObject<{}>>;
+}>;
+type TwitterUserAuthSubtask = Static<typeof TwitterUserAuthSubtask>;
+type FlowTokenResultSuccess = {
+    status: 'success';
+    response: TwitterUserAuthFlowResponse;
+};
+type FlowTokenResultError = {
+    status: 'error';
+    err: Error;
+};
+type FlowTokenResult = FlowTokenResultSuccess | FlowTokenResultError;
+interface TwitterUserAuthCredentials {
+    username: string;
+    password: string;
+    email?: string;
+    twoFactorSecret?: string;
+}
+/**
+ * The API interface provided to custom subtask handlers for interacting with the Twitter authentication flow.
+ * This interface allows handlers to send flow requests and access the current flow token.
+ *
+ * The API is passed to each subtask handler and provides methods necessary for implementing
+ * custom authentication subtasks. It abstracts away the low-level details of communicating
+ * with Twitter's authentication API.
+ *
+ * @example
+ * ```typescript
+ * import { Scraper, FlowSubtaskHandler } from "@the-convocation/twitter-scraper";
+ *
+ * // A custom subtask handler that implements a hypothetical example subtask
+ * const exampleHandler: FlowSubtaskHandler = async (subtaskId, response, credentials, api) => {
+ *   // Process the example subtask somehow
+ *   const data = await processExampleTask();
+ *
+ *   // Submit the processed data using the provided API
+ *   return await api.sendFlowRequest({
+ *     flow_token: api.getFlowToken(),
+ *     subtask_inputs: [{
+ *       subtask_id: subtaskId,
+ *       example_data: {
+ *         value: data,
+ *         link: "next_link"
+ *       }
+ *     }]
+ *   });
+ * };
+ *
+ * const scraper = new Scraper();
+ * scraper.registerAuthSubtaskHandler("ExampleSubtask", exampleHandler);
+ * ```
+ */
+interface FlowSubtaskHandlerApi {
+    /**
+     * Send a flow request to the Twitter API.
+     * @param request The request object containing flow token and subtask inputs
+     * @returns The result of the flow task
+     */
+    sendFlowRequest: (request: TwitterUserAuthFlowRequest) => Promise<FlowTokenResult>;
+    /**
+     * Gets the current flow token.
+     * @returns The current flow token
+     */
+    getFlowToken: () => string;
+}
+/**
+ * A handler function for processing Twitter authentication flow subtasks.
+ * Library consumers can implement and register custom handlers for new or
+ * existing subtask types using the Scraper.registerAuthSubtaskHandler method.
+ *
+ * Each subtask handler is called when its corresponding subtask ID is encountered
+ * during the authentication flow. The handler receives the subtask ID, the previous
+ * response data, the user's credentials, and an API interface for interacting with
+ * the authentication flow.
+ *
+ * Handlers should process their specific subtask and return either a successful response
+ * or an error. Success responses typically lead to the next subtask in the flow, while
+ * errors will halt the authentication process.
+ *
+ * @param subtaskId - The identifier of the subtask being handled
+ * @param previousResponse - The complete response from the previous authentication flow step
+ * @param credentials - The user's authentication credentials including username, password, etc.
+ * @param api - An interface providing methods to interact with the authentication flow
+ * @returns A promise resolving to either a successful flow response or an error
+ *
+ * @example
+ * ```typescript
+ * import { Scraper, FlowSubtaskHandler } from "@the-convocation/twitter-scraper";
+ *
+ * // Custom handler for a hypothetical verification subtask
+ * const verificationHandler: FlowSubtaskHandler = async (
+ *   subtaskId,
+ *   response,
+ *   credentials,
+ *   api
+ * ) => {
+ *   // Extract the verification data from the response
+ *   const verificationData = response.subtasks?.[0].exampleData?.value;
+ *   if (!verificationData) {
+ *     return {
+ *       status: 'error',
+ *       err: new Error('No verification data found in response')
+ *     };
+ *   }
+ *
+ *   // Process the verification data somehow
+ *   const result = await processVerification(verificationData);
+ *
+ *   // Submit the result using the flow API
+ *   return await api.sendFlowRequest({
+ *     flow_token: api.getFlowToken(),
+ *     subtask_inputs: [{
+ *       subtask_id: subtaskId,
+ *       example_verification: {
+ *         value: result,
+ *         link: "next_link"
+ *       }
+ *     }]
+ *   });
+ * };
+ *
+ * const scraper = new Scraper();
+ * scraper.registerAuthSubtaskHandler("ExampleVerificationSubtask", verificationHandler);
+ *
+ * // Later, when logging in...
+ * await scraper.login("username", "password");
+ * ```
+ */
+type FlowSubtaskHandler = (subtaskId: string, previousResponse: TwitterUserAuthFlowResponse, credentials: TwitterUserAuthCredentials, api: FlowSubtaskHandlerApi) => Promise<FlowTokenResult>;
+
 interface LegacyUserRaw {
     created_at?: string;
     description?: string;
@@ -372,6 +546,13 @@ declare class Scraper {
      * - Reusing Scraper objects is recommended to minimize the time spent authenticating unnecessarily.
      */
     constructor(options?: Partial<ScraperOptions> | undefined);
+    /**
+     * Registers a subtask handler for the given subtask ID. This
+     * will override any existing handler for the same subtask.
+     * @param subtaskId The ID of the subtask to register the handler for.
+     * @param subtaskHandler The handler function to register.
+     */
+    registerAuthSubtaskHandler(subtaskId: string, subtaskHandler: FlowSubtaskHandler): void;
     /**
      * Fetches a Twitter profile.
      * @param username The Twitter username of the profile to fetch, without an `@` at the beginning.
@@ -598,4 +779,4 @@ declare class Scraper {
     private handleResponse;
 }
 
-export { ApiError, ErrorRateLimitStrategy, type FetchParameters, type FetchTransformOptions, type Mention, type Photo, type PlaceRaw, type Profile, type QueryProfilesResponse, type QueryTweetsResponse, type RateLimitEvent, type RateLimitStrategy, Scraper, type ScraperOptions, SearchMode, type Tweet, type TweetQuery, type Video, WaitingRateLimitStrategy };
+export { ApiError, AuthenticationError, ErrorRateLimitStrategy, type FetchParameters, type FetchTransformOptions, type FlowSubtaskHandler, type FlowSubtaskHandlerApi, type FlowTokenResult, type FlowTokenResultError, type FlowTokenResultSuccess, type Mention, type Photo, type PlaceRaw, type Profile, type QueryProfilesResponse, type QueryTweetsResponse, type RateLimitEvent, type RateLimitStrategy, Scraper, type ScraperOptions, SearchMode, type Tweet, type TweetQuery, type TwitterApiErrorExtensions, type TwitterApiErrorPosition, type TwitterApiErrorRaw, type TwitterApiErrorTraceInfo, type TwitterUserAuthCredentials, type TwitterUserAuthFlowInitRequest, type TwitterUserAuthFlowRequest, type TwitterUserAuthFlowResponse, type TwitterUserAuthFlowSubtaskRequest, type Video, WaitingRateLimitStrategy };

package/package.json

@@ -7,7 +7,7 @@
     "scraper",
     "crawler"
   ],
-  "version": "0.15.0",
+  "version": "0.16.0",
   "main": "dist/default/cjs/index.js",
   "types": "./dist/types/index.d.ts",
   "exports": {