@the-convocation/twitter-scraper 0.15.1 → 0.16.0

package/dist/default/cjs/index.js

@@ -47,6 +47,12 @@ class ApiError extends Error {
     return new ApiError(response, data, `Response status: ${response.status}`);
   }
 }
+class AuthenticationError extends Error {
+  constructor(message) {
+    super(message || "Authentication failed");
+    this.name = "AuthenticationError";
+  }
+}
 
 class WaitingRateLimitStrategy {
   async onRateLimit({ response: res }) {
@@ -275,7 +281,9 @@ class TwitterGuestAuth {
     }
     const token = this.guestToken;
     if (token == null) {
-      throw new Error("Authentication token is null or undefined.");
+      throw new AuthenticationError(
+        "Authentication token is null or undefined."
+      );
     }
     headers.set("authorization", `Bearer ${this.bearerToken}`);
     headers.set("x-guest-token", token);
@@ -322,15 +330,15 @@ class TwitterGuestAuth {
     });
     await updateCookieJar(this.jar, res.headers);
     if (!res.ok) {
-      throw new Error(await res.text());
+      throw new AuthenticationError(await res.text());
     }
     const o = await res.json();
     if (o == null || o["guest_token"] == null) {
-      throw new Error("guest_token not found.");
+      throw new AuthenticationError("guest_token not found.");
     }
     const newGuestToken = o["guest_token"];
     if (typeof newGuestToken !== "string") {
-      throw new Error("guest_token was not a string.");
+      throw new AuthenticationError("guest_token was not a string.");
     }
     this.guestToken = newGuestToken;
     this.guestCreatedAt = /* @__PURE__ */ new Date();
@@ -351,6 +359,47 @@ const TwitterUserAuthSubtask = typebox.Type.Object({
 class TwitterUserAuth extends TwitterGuestAuth {
   constructor(bearerToken, options) {
     super(bearerToken, options);
+    this.subtaskHandlers = /* @__PURE__ */ new Map();
+    this.initializeDefaultHandlers();
+  }
+  /**
+   * Register a custom subtask handler or override an existing one
+   * @param subtaskId The ID of the subtask to handle
+   * @param handler The handler function that processes the subtask
+   */
+  registerSubtaskHandler(subtaskId, handler) {
+    this.subtaskHandlers.set(subtaskId, handler);
+  }
+  initializeDefaultHandlers() {
+    this.subtaskHandlers.set(
+      "LoginJsInstrumentationSubtask",
+      this.handleJsInstrumentationSubtask.bind(this)
+    );
+    this.subtaskHandlers.set(
+      "LoginEnterUserIdentifierSSO",
+      this.handleEnterUserIdentifierSSO.bind(this)
+    );
+    this.subtaskHandlers.set(
+      "LoginEnterAlternateIdentifierSubtask",
+      this.handleEnterAlternateIdentifierSubtask.bind(this)
+    );
+    this.subtaskHandlers.set(
+      "LoginEnterPassword",
+      this.handleEnterPassword.bind(this)
+    );
+    this.subtaskHandlers.set(
+      "AccountDuplicationCheck",
+      this.handleAccountDuplicationCheck.bind(this)
+    );
+    this.subtaskHandlers.set(
+      "LoginTwoFactorAuthChallenge",
+      this.handleTwoFactorAuthChallenge.bind(this)
+    );
+    this.subtaskHandlers.set("LoginAcid", this.handleAcid.bind(this));
+    this.subtaskHandlers.set(
+      "LoginSuccessSubtask",
+      this.handleSuccessSubtask.bind(this)
+    );
   }
   async isLoggedIn() {
     const res = await requestApi(
@@ -365,52 +414,49 @@ class TwitterUserAuth extends TwitterGuestAuth {
   }
   async login(username, password, email, twoFactorSecret) {
     await this.updateGuestToken();
+    const credentials = {
+      username,
+      password,
+      email,
+      twoFactorSecret
+    };
     let next = await this.initLogin();
-    while ("subtask" in next && next.subtask) {
-      if (next.subtask.subtask_id === "LoginJsInstrumentationSubtask") {
-        next = await this.handleJsInstrumentationSubtask(next);
-      } else if (next.subtask.subtask_id === "LoginEnterUserIdentifierSSO") {
-        next = await this.handleEnterUserIdentifierSSO(next, username);
-      } else if (next.subtask.subtask_id === "LoginEnterAlternateIdentifierSubtask") {
-        next = await this.handleEnterAlternateIdentifierSubtask(
-          next,
-          email
-        );
-      } else if (next.subtask.subtask_id === "LoginEnterPassword") {
-        next = await this.handleEnterPassword(next, password);
-      } else if (next.subtask.subtask_id === "AccountDuplicationCheck") {
-        next = await this.handleAccountDuplicationCheck(next);
-      } else if (next.subtask.subtask_id === "LoginTwoFactorAuthChallenge") {
-        if (twoFactorSecret) {
-          next = await this.handleTwoFactorAuthChallenge(next, twoFactorSecret);
-        } else {
-          throw new Error(
-            "Requested two factor authentication code but no secret provided"
-          );
-        }
-      } else if (next.subtask.subtask_id === "LoginAcid") {
-        next = await this.handleAcid(next, email);
-      } else if (next.subtask.subtask_id === "LoginSuccessSubtask") {
-        next = await this.handleSuccessSubtask(next);
+    while (next.status === "success" && next.response.subtasks?.length) {
+      const flowToken = next.response.flow_token;
+      if (flowToken == null) {
+        throw new Error("flow_token not found.");
+      }
+      const subtaskId = next.response.subtasks[0].subtask_id;
+      const handler = this.subtaskHandlers.get(subtaskId);
+      if (handler) {
+        next = await handler(subtaskId, next.response, credentials, {
+          sendFlowRequest: this.executeFlowTask.bind(this),
+          getFlowToken: () => flowToken
+        });
       } else {
-        throw new Error(`Unknown subtask ${next.subtask.subtask_id}`);
+        throw new Error(`Unknown subtask ${subtaskId}`);
       }
     }
-    if ("err" in next) {
+    if (next.status === "error") {
       throw next.err;
     }
   }
   async logout() {
-    if (!this.isLoggedIn()) {
+    if (!this.hasToken()) {
       return;
     }
-    await requestApi(
-      "https://api.twitter.com/1.1/account/logout.json",
-      this,
-      "POST"
-    );
-    this.deleteToken();
-    this.jar = new toughCookie.CookieJar();
+    try {
+      await requestApi(
+        "https://api.twitter.com/1.1/account/logout.json",
+        this,
+        "POST"
+      );
+    } catch (error) {
+      console.warn("Error during logout:", error);
+    } finally {
+      this.deleteToken();
+      this.jar = new toughCookie.CookieJar();
+    }
   }
   async installCsrfToken(headers) {
     const cookies = await this.getCookies();
@@ -449,12 +495,12 @@ class TwitterUserAuth extends TwitterGuestAuth {
       }
     });
   }
-  async handleJsInstrumentationSubtask(prev) {
-    return await this.executeFlowTask({
-      flow_token: prev.flowToken,
+  async handleJsInstrumentationSubtask(subtaskId, _prev, _credentials, api) {
+    return await api.sendFlowRequest({
+      flow_token: api.getFlowToken(),
       subtask_inputs: [
         {
-          subtask_id: "LoginJsInstrumentationSubtask",
+          subtask_id: subtaskId,
           js_instrumentation: {
             response: "{}",
             link: "next_link"
@@ -463,32 +509,32 @@ class TwitterUserAuth extends TwitterGuestAuth {
       ]
     });
   }
-  async handleEnterAlternateIdentifierSubtask(prev, email) {
+  async handleEnterAlternateIdentifierSubtask(subtaskId, _prev, credentials, api) {
     return await this.executeFlowTask({
-      flow_token: prev.flowToken,
+      flow_token: api.getFlowToken(),
       subtask_inputs: [
         {
-          subtask_id: "LoginEnterAlternateIdentifierSubtask",
+          subtask_id: subtaskId,
           enter_text: {
-            text: email,
+            text: credentials.email,
             link: "next_link"
           }
         }
       ]
     });
   }
-  async handleEnterUserIdentifierSSO(prev, username) {
+  async handleEnterUserIdentifierSSO(subtaskId, _prev, credentials, api) {
     return await this.executeFlowTask({
-      flow_token: prev.flowToken,
+      flow_token: api.getFlowToken(),
       subtask_inputs: [
         {
-          subtask_id: "LoginEnterUserIdentifierSSO",
+          subtask_id: subtaskId,
           settings_list: {
             setting_responses: [
               {
                 key: "user_identifier",
                 response_data: {
-                  text_data: { result: username }
+                  text_data: { result: credentials.username }
                 }
               }
             ],
@@ -498,26 +544,26 @@ class TwitterUserAuth extends TwitterGuestAuth {
       ]
     });
   }
-  async handleEnterPassword(prev, password) {
+  async handleEnterPassword(subtaskId, _prev, credentials, api) {
     return await this.executeFlowTask({
-      flow_token: prev.flowToken,
+      flow_token: api.getFlowToken(),
       subtask_inputs: [
         {
-          subtask_id: "LoginEnterPassword",
+          subtask_id: subtaskId,
           enter_password: {
-            password,
+            password: credentials.password,
             link: "next_link"
           }
         }
       ]
     });
   }
-  async handleAccountDuplicationCheck(prev) {
+  async handleAccountDuplicationCheck(subtaskId, _prev, _credentials, api) {
     return await this.executeFlowTask({
-      flow_token: prev.flowToken,
+      flow_token: api.getFlowToken(),
       subtask_inputs: [
         {
-          subtask_id: "AccountDuplicationCheck",
+          subtask_id: subtaskId,
           check_logged_in_account: {
             link: "AccountDuplicationCheck_false"
           }
@@ -525,16 +571,24 @@ class TwitterUserAuth extends TwitterGuestAuth {
       ]
     });
   }
-  async handleTwoFactorAuthChallenge(prev, secret) {
-    const totp = new OTPAuth__namespace.TOTP({ secret });
+  async handleTwoFactorAuthChallenge(subtaskId, _prev, credentials, api) {
+    if (!credentials.twoFactorSecret) {
+      return {
+        status: "error",
+        err: new AuthenticationError(
+          "Two-factor authentication is required but no secret was provided"
+        )
+      };
+    }
+    const totp = new OTPAuth__namespace.TOTP({ secret: credentials.twoFactorSecret });
     let error;
     for (let attempts = 1; attempts < 4; attempts += 1) {
       try {
-        return await this.executeFlowTask({
-          flow_token: prev.flowToken,
+        return await api.sendFlowRequest({
+          flow_token: api.getFlowToken(),
           subtask_inputs: [
             {
-              subtask_id: "LoginTwoFactorAuthChallenge",
+              subtask_id: subtaskId,
               enter_text: {
                 link: "next_link",
                 text: totp.generate()
@@ -549,23 +603,23 @@ class TwitterUserAuth extends TwitterGuestAuth {
     }
     throw error;
   }
-  async handleAcid(prev, email) {
+  async handleAcid(subtaskId, _prev, credentials, api) {
     return await this.executeFlowTask({
-      flow_token: prev.flowToken,
+      flow_token: api.getFlowToken(),
       subtask_inputs: [
         {
-          subtask_id: "LoginAcid",
+          subtask_id: subtaskId,
           enter_text: {
-            text: email,
+            text: credentials.email,
             link: "next_link"
           }
         }
       ]
     });
   }
-  async handleSuccessSubtask(prev) {
+  async handleSuccessSubtask(_subtaskId, _prev, _credentials, api) {
     return await this.executeFlowTask({
-      flow_token: prev.flowToken,
+      flow_token: api.getFlowToken(),
       subtask_inputs: []
     });
   }
@@ -573,7 +627,9 @@ class TwitterUserAuth extends TwitterGuestAuth {
     const onboardingTaskUrl = "https://api.twitter.com/1.1/onboarding/task.json";
     const token = this.guestToken;
     if (token == null) {
-      throw new Error("Authentication token is null or undefined.");
+      throw new AuthenticationError(
+        "Authentication token is null or undefined."
+      );
     }
     const headers = new headersPolyfill.Headers({
       authorization: `Bearer ${this.bearerToken}`,
@@ -598,12 +654,15 @@ class TwitterUserAuth extends TwitterGuestAuth {
     }
     const flow = await res.json();
     if (flow?.flow_token == null) {
-      return { status: "error", err: new Error("flow_token not found.") };
+      return {
+        status: "error",
+        err: new AuthenticationError("flow_token not found.")
+      };
     }
     if (flow.errors?.length) {
       return {
         status: "error",
-        err: new Error(
+        err: new AuthenticationError(
           `Authentication error (${flow.errors[0].code}): ${flow.errors[0].message}`
         )
       };
@@ -611,7 +670,7 @@ class TwitterUserAuth extends TwitterGuestAuth {
     if (typeof flow.flow_token !== "string") {
       return {
         status: "error",
-        err: new Error("flow_token was not a string.")
+        err: new AuthenticationError("flow_token was not a string.")
       };
     }
     const subtask = flow.subtasks?.length ? flow.subtasks[0] : void 0;
@@ -619,13 +678,12 @@ class TwitterUserAuth extends TwitterGuestAuth {
     if (subtask && subtask.subtask_id === "DenyLoginSubtask") {
       return {
         status: "error",
-        err: new Error("Authentication error: DenyLoginSubtask")
+        err: new AuthenticationError("Authentication error: DenyLoginSubtask")
       };
     }
     return {
       status: "success",
-      subtask,
-      flowToken: flow.flow_token
+      response: flow
     };
   }
 }
@@ -1288,8 +1346,8 @@ async function fetchSearchProfiles(query, maxProfiles, auth, cursor) {
   return parseSearchTimelineUsers(timeline);
 }
 async function getSearchTimeline(query, maxItems, searchMode, auth, cursor) {
-  if (!auth.isLoggedIn()) {
-    throw new Error("Scraper is not logged-in for search.");
+  if (!await auth.isLoggedIn()) {
+    throw new AuthenticationError("Scraper is not logged-in for search.");
   }
   if (maxItems > 50) {
     maxItems = 50;
@@ -1396,6 +1454,11 @@ function getFollowers(userId, maxProfiles, auth) {
   });
 }
 async function fetchProfileFollowing(userId, maxProfiles, auth, cursor) {
+  if (!await auth.isLoggedIn()) {
+    throw new AuthenticationError(
+      "Scraper is not logged-in for profile following."
+    );
+  }
   const timeline = await getFollowingTimeline(
     userId,
     maxProfiles,
@@ -1405,6 +1468,11 @@ async function fetchProfileFollowing(userId, maxProfiles, auth, cursor) {
   return parseRelationshipTimeline(timeline);
 }
 async function fetchProfileFollowers(userId, maxProfiles, auth, cursor) {
+  if (!await auth.isLoggedIn()) {
+    throw new AuthenticationError(
+      "Scraper is not logged-in for profile followers."
+    );
+  }
   const timeline = await getFollowersTimeline(
     userId,
     maxProfiles,
@@ -1415,7 +1483,9 @@ async function fetchProfileFollowers(userId, maxProfiles, auth, cursor) {
 }
 async function getFollowingTimeline(userId, maxItems, auth, cursor) {
   if (!auth.isLoggedIn()) {
-    throw new Error("Scraper is not logged-in for profile following.");
+    throw new AuthenticationError(
+      "Scraper is not logged-in for profile following."
+    );
   }
   if (maxItems > 50) {
     maxItems = 50;
@@ -1448,7 +1518,9 @@ async function getFollowingTimeline(userId, maxItems, auth, cursor) {
 }
 async function getFollowersTimeline(userId, maxItems, auth, cursor) {
   if (!auth.isLoggedIn()) {
-    throw new Error("Scraper is not logged-in for profile followers.");
+    throw new AuthenticationError(
+      "Scraper is not logged-in for profile followers."
+    );
   }
   if (maxItems > 50) {
     maxItems = 50;
@@ -1705,8 +1777,10 @@ function getTweetsAndRepliesByUserId(userId, maxTweets, auth) {
   });
 }
 async function fetchLikedTweets(userId, maxTweets, cursor, auth) {
-  if (!auth.isLoggedIn()) {
-    throw new Error("Scraper is not logged-in for fetching liked tweets.");
+  if (!await auth.isLoggedIn()) {
+    throw new AuthenticationError(
+      "Scraper is not logged-in for fetching liked tweets."
+    );
   }
   if (maxTweets > 200) {
     maxTweets = 200;
@@ -1811,6 +1885,20 @@ class Scraper {
     this.token = bearerToken;
     this.useGuestAuth();
   }
+  /**
+   * 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, subtaskHandler) {
+    if (this.auth instanceof TwitterUserAuth) {
+      this.auth.registerSubtaskHandler(subtaskId, subtaskHandler);
+    }
+    if (this.authTrends instanceof TwitterUserAuth) {
+      this.authTrends.registerSubtaskHandler(subtaskId, subtaskHandler);
+    }
+  }
   /**
    * Initializes auth properties using a guest token.
    * Used when creating a new instance of this class, and when logging out.
@@ -2145,6 +2233,7 @@ class Scraper {
 }
 
 exports.ApiError = ApiError;
+exports.AuthenticationError = AuthenticationError;
 exports.ErrorRateLimitStrategy = ErrorRateLimitStrategy;
 exports.Scraper = Scraper;
 exports.SearchMode = SearchMode;