twitter-api-browser-js 0.0.3 → 0.0.5

package/dist/consts.d.ts

@@ -0,0 +1,9 @@
+export declare const REQUEST_FUNC_GLOBAL_KEY = "elonmusk_810_request";
+export declare const INITIAL_STATE_PROP_KEY = "__INITIAL_STATE__";
+export declare const INITIAL_STATE_GLOBAL_KEY = "elonmusk_810_init_state";
+export declare const OPERATIONS_GLOBAL_KEY = "elonmusk_810_operations";
+export declare const DEFAULT_USER_DATA_DIR = "./.user_data";
+export declare const METHOD_MAP: {
+    readonly query: "GET";
+    readonly mutation: "POST";
+};

package/dist/consts.js

@@ -0,0 +1,9 @@
+export const REQUEST_FUNC_GLOBAL_KEY = "elonmusk_810_request";
+export const INITIAL_STATE_PROP_KEY = "__INITIAL_STATE__";
+export const INITIAL_STATE_GLOBAL_KEY = "elonmusk_810_init_state";
+export const OPERATIONS_GLOBAL_KEY = "elonmusk_810_operations";
+export const DEFAULT_USER_DATA_DIR = "./.user_data";
+export const METHOD_MAP = {
+    query: "GET",
+    mutation: "POST",
+};

package/dist/example.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/example.js

@@ -0,0 +1,109 @@
+import { TwitterAPIBrowser } from "./main.ts";
+import { createInterface } from "node:readline";
+function prompt(question) {
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer);
+        });
+    });
+}
+function formatLog(...args) {
+    console.dir(args, { depth: null });
+}
+async function main() {
+    const userDataDir = "./.data";
+    const browser = new TwitterAPIBrowser(userDataDir);
+    console.log("Setup browser");
+    await browser.setup();
+    try {
+        if (await browser.isLoggedIn()) {
+            console.log("User is logged in");
+        }
+        else {
+            console.log("User is not logged in, please login manually");
+            await browser.manualLogin();
+        }
+        while (true) {
+            console.log("=".repeat(20));
+            const operation = await prompt("Choose operation [CreateTweet, HomeTimeline, UserByScreenName, CreateRetweet, FavoriteTweet, SearchTimeline, UsersByRestIds, exit]: ");
+            if (!operation || operation === "exit") {
+                return;
+            }
+            const request = async () => {
+                if (operation === "CreateTweet") {
+                    const res = await browser.request("CreateTweet", {
+                        tweet_text: `Hello, World! ${new Date().toISOString()}`,
+                        dark_request: false,
+                        media: { media_entities: [], possibly_sensitive: false },
+                        semantic_annotation_ids: [],
+                        disallowed_reply_options: null,
+                    });
+                    return res;
+                }
+                else if (operation === "HomeTimeline") {
+                    const res = await browser.request("HomeTimeline", {
+                        count: 20,
+                        includePromotedContent: true,
+                        latestControlAvailable: true,
+                        withCommunity: true,
+                    });
+                    return res;
+                }
+                else if (operation === "UserByScreenName") {
+                    const res = await browser.request("UserByScreenName", {
+                        screen_name: "elonmusk",
+                        withSafetyModeUserFields: true,
+                        withSuperFollowsUserFields: true,
+                        withBirdwatchPivots: false,
+                    }, {
+                        withAuxiliaryUserLabels: true,
+                    });
+                    return res;
+                }
+                else if (operation === "CreateRetweet") {
+                    const res = await browser.request("CreateRetweet", {
+                        tweet_id: "1987547856664993831",
+                        dark_request: false,
+                    });
+                    return res;
+                }
+                else if (operation === "FavoriteTweet") {
+                    const res = await browser.request("FavoriteTweet", {
+                        tweet_id: "1987547856664993831",
+                    });
+                    return res;
+                }
+                else if (operation === "SearchTimeline") {
+                    const res = await browser.request("SearchTimeline", {
+                        rawQuery: "from:elonmusk",
+                        count: 20,
+                        querySource: "typed_query",
+                        product: "Top",
+                        withGrokTranslatedBio: false,
+                    });
+                    return res;
+                }
+                else if (operation === "UsersByRestIds") {
+                    const res = await browser.request("UsersByRestIds", {
+                        userIds: ["900282258736545792"],
+                    });
+                    return res;
+                }
+                else {
+                    console.log(`Unknown operation: ${operation}`);
+                }
+            };
+            const res = await request();
+            formatLog(res);
+        }
+    }
+    finally {
+        await browser.close();
+    }
+}
+await main();

package/dist/inject.d.ts

@@ -0,0 +1,27 @@
+import { METHOD_MAP } from "./consts.js";
+import { LooseType } from "./twitter-types.js";
+export declare const SETUP_SCRIPT = "\n(async () => {\n  if (globalThis.elonmusk_810_request) {\n    return;\n  }\n  const __origApply = Function.prototype.apply;\n  const client = await new Promise((resolve) => {\n    Function.prototype.apply = function (thisArg, argsArray) {\n      if (thisArg && typeof thisArg === \"object\" && thisArg.dispatch === this) {\n        resolve(thisArg);\n      }\n      return __origApply.bind(this)(thisArg, argsArray);\n    };\n  });\n  Function.prototype.apply = __origApply;\n  globalThis.elonmusk_810_request = (query) => {\n    return client.dispatch.apply(client, [query]);\n  };\n})();\n";
+export declare const INITIAL_STATE_SCRIPT = "\n(async () => {\n  const init_state_promise = new Promise((resolve) => {\n    Object.defineProperty(window, \"__INITIAL_STATE__\", {\n      configurable: true,\n      enumerable: true,\n      get() {\n        return undefined;\n      },\n      set(v) {\n        resolve(v);\n        Object.defineProperty(window, \"__INITIAL_STATE__\", {\n          value: v,\n          writable: true,\n          enumerable: true,\n          configurable: true,\n        });\n      },\n    });\n  });\n\n  globalThis.elonmusk_810_init_state = init_state_promise;\n})();\n";
+export declare const OPERATIONS_SCRIPT = "\n(async () => {\n  globalThis.elonmusk_810_operations = [];\n  const origCall = Function.prototype.call;\n  Function.prototype.call = function (thisArg, ...args) {\n    const module = args[0];\n    const ret = origCall.bind(this)(thisArg, ...args);\n    try {\n      const exp = module.exports;\n      if (exp.operationName) {\n        globalThis.elonmusk_810_operations.push(exp);\n      }\n    } catch (_) {}\n    return ret;\n  };\n  await new Promise((resolve) => setTimeout(resolve, 5000));\n  Function.prototype.call = origCall;\n})();\n";
+export type Operation = {
+    operationName: string;
+    queryId: string;
+    operationType: keyof typeof METHOD_MAP;
+    metadata: {
+        featureSwitches: string[];
+        allowFieldToggles: string[];
+        fieldToggles: string[];
+    };
+} & Record<string, LooseType>;
+type FeatureSwitchValue = {
+    value: boolean;
+} & Record<string, LooseType>;
+export type InitialState = {
+    featureSwitch: {
+        defaultConfig: Record<string, FeatureSwitchValue>;
+        user: Record<string, FeatureSwitchValue>;
+        debug: Record<string, FeatureSwitchValue>;
+        customOverrides: Record<string, FeatureSwitchValue>;
+    };
+} & Record<string, LooseType>;
+export {};

package/dist/inject.js

@@ -0,0 +1,64 @@
+import { INITIAL_STATE_GLOBAL_KEY, INITIAL_STATE_PROP_KEY, OPERATIONS_GLOBAL_KEY, REQUEST_FUNC_GLOBAL_KEY, } from "./consts.js";
+export const SETUP_SCRIPT = `
+(async () => {
+  if (globalThis.${REQUEST_FUNC_GLOBAL_KEY}) {
+    return;
+  }
+  const __origApply = Function.prototype.apply;
+  const client = await new Promise((resolve) => {
+    Function.prototype.apply = function (thisArg, argsArray) {
+      if (thisArg && typeof thisArg === "object" && thisArg.dispatch === this) {
+        resolve(thisArg);
+      }
+      return __origApply.bind(this)(thisArg, argsArray);
+    };
+  });
+  Function.prototype.apply = __origApply;
+  globalThis.${REQUEST_FUNC_GLOBAL_KEY} = (query) => {
+    return client.dispatch.apply(client, [query]);
+  };
+})();
+`;
+export const INITIAL_STATE_SCRIPT = `
+(async () => {
+  const init_state_promise = new Promise((resolve) => {
+    Object.defineProperty(window, "${INITIAL_STATE_PROP_KEY}", {
+      configurable: true,
+      enumerable: true,
+      get() {
+        return undefined;
+      },
+      set(v) {
+        resolve(v);
+        Object.defineProperty(window, "${INITIAL_STATE_PROP_KEY}", {
+          value: v,
+          writable: true,
+          enumerable: true,
+          configurable: true,
+        });
+      },
+    });
+  });
+
+  globalThis.${INITIAL_STATE_GLOBAL_KEY} = init_state_promise;
+})();
+`;
+export const OPERATIONS_SCRIPT = `
+(async () => {
+  globalThis.${OPERATIONS_GLOBAL_KEY} = [];
+  const origCall = Function.prototype.call;
+  Function.prototype.call = function (thisArg, ...args) {
+    const module = args[0];
+    const ret = origCall.bind(this)(thisArg, ...args);
+    try {
+      const exp = module.exports;
+      if (exp.operationName) {
+        globalThis.${OPERATIONS_GLOBAL_KEY}.push(exp);
+      }
+    } catch (_) {}
+    return ret;
+  };
+  await new Promise((resolve) => setTimeout(resolve, 5000));
+  Function.prototype.call = origCall;
+})();
+`;

package/dist/main.d.ts

@@ -0,0 +1,51 @@
+import type { LooseErrorResponse, LooseType, SuccessResponse, TwitterOpenAPIModelsMapping } from "./twitter-types.ts";
+/**
+ * @classdesc Base class for operating Twitter API Browser
+ */
+export declare class TwitterAPIBrowser {
+    private readonly userDataDir;
+    /**
+     * @description Constructor for TwitterAPIBrowser.
+     * @param userDataDir - The directory to store the user data for the browser (example: "./.user_data")
+     */
+    constructor(userDataDir?: string);
+    private browser;
+    private page;
+    private operations;
+    private initialState;
+    /**
+     * @description Launches a new browser context and page, and then injects scripts.
+     * @param waitForReady - The number of seconds to wait for the browser to be ready.
+     * @param headless - Whether to run the browser in headless mode. (Recommended: false)
+     */
+    setup(waitForReady?: number, headless?: boolean): Promise<void>;
+    /**
+     * @description Closes the browser context and page.
+     */
+    close(): Promise<void>;
+    [Symbol.asyncDispose]: () => Promise<void>;
+    /**
+     * @description Is user logged in?
+     */
+    isLoggedIn(): Promise<boolean>;
+    /**
+     * @description Manually login to Twitter.
+     */
+    manualLogin(): Promise<void>;
+    /**
+     * @description Send a GraphQL request to the Twitter API
+     * @param method - The method of the request
+     * @param path - The path of the request
+     * @param body - The body of the request
+     * @returns Response of the request
+     */
+    graphql<T extends string = string>(method: string, path: string, body: LooseType): Promise<SuccessResponse<T> | LooseErrorResponse>;
+    /**
+     * Sends a request to the Twitter API
+     * @param operationName - The name of the operation to request
+     * @param variables - The variables to pass to the operation
+     * @param fieldToggles - The fields to toggle on or off in the operation
+     * @returns Response of the request
+     */
+    request<T extends keyof TwitterOpenAPIModelsMapping = string>(operationName: T, variables: LooseType, fieldToggles?: Record<string, boolean>): Promise<SuccessResponse<T> | LooseErrorResponse>;
+}

package/dist/main.js

@@ -0,0 +1,203 @@
+/**
+ * Twitter API Browser for JavaScript
+ * @module
+ * @exports TwitterAPIBrowser
+ */
+import * as fs from "node:fs";
+import { INITIAL_STATE_SCRIPT, OPERATIONS_SCRIPT, SETUP_SCRIPT, } from "./inject.js";
+import { DEFAULT_USER_DATA_DIR, INITIAL_STATE_GLOBAL_KEY, METHOD_MAP, OPERATIONS_GLOBAL_KEY, REQUEST_FUNC_GLOBAL_KEY, } from "./consts.js";
+import { chromium } from "playwright";
+import { pickFirstItem, removeNullRecursively, sleep } from "./utils.js";
+/**
+ * @classdesc Base class for operating Twitter API Browser
+ */
+export class TwitterAPIBrowser {
+    userDataDir;
+    /**
+     * @description Constructor for TwitterAPIBrowser.
+     * @param userDataDir - The directory to store the user data for the browser (example: "./.user_data")
+     */
+    constructor(userDataDir = DEFAULT_USER_DATA_DIR) {
+        this.userDataDir = userDataDir;
+        if (!fs.existsSync(userDataDir)) {
+            fs.mkdirSync(userDataDir, { recursive: true });
+        }
+    }
+    browser;
+    page;
+    operations;
+    initialState;
+    /**
+     * @description Launches a new browser context and page, and then injects scripts.
+     * @param waitForReady - The number of seconds to wait for the browser to be ready.
+     * @param headless - Whether to run the browser in headless mode. (Recommended: false)
+     */
+    async setup(waitForReady = 5, headless = false) {
+        if (this.browser && this.page) {
+            await this.close();
+        }
+        const { resolve, reject, promise: browserPromise, } = Promise.withResolvers();
+        chromium
+            .launchPersistentContext(this.userDataDir, {
+            headless: headless,
+            viewport: null,
+            args: [
+                "--disable-blink-features=AutomationControlled",
+                "--no-sandbox",
+                "--disable-dev-shm-usage",
+                "--disable-gpu",
+            ],
+        })
+            .then(resolve)
+            .catch(reject);
+        const raceResult = await Promise.race([
+            browserPromise,
+            sleep(waitForReady * 1000, new Error("Browser launch timed out")),
+        ]);
+        if (raceResult instanceof Error) {
+            throw raceResult;
+        }
+        this.browser = raceResult;
+        this.page = await this.browser.newPage();
+        await this.page.addInitScript(SETUP_SCRIPT);
+        await this.page.addInitScript(OPERATIONS_SCRIPT);
+        await this.page.addInitScript(INITIAL_STATE_SCRIPT);
+        await this.page.goto("https://x.com/home");
+        await sleep(waitForReady * 1000);
+        this.operations = await this.page.evaluate(`globalThis.${OPERATIONS_GLOBAL_KEY}`);
+        this.initialState = await this.page.evaluate(`globalThis.${INITIAL_STATE_GLOBAL_KEY}`);
+    }
+    /**
+     * @description Closes the browser context and page.
+     */
+    async close() {
+        if (this.browser && this.page) {
+            await this.page.close();
+            await this.browser.close();
+        }
+        // NOTE: Patch memory leak
+        this.browser = undefined;
+        this.page = undefined;
+        this.operations = undefined;
+        this.initialState = undefined;
+    }
+    [Symbol.asyncDispose] = this.close;
+    /**
+     * @description Is user logged in?
+     */
+    async isLoggedIn() {
+        const cookies = await this.browser?.cookies("https://x.com");
+        if (!cookies) {
+            return false;
+        }
+        return cookies.some((cookie) => cookie.name === "auth_token");
+    }
+    /**
+     * @description Manually login to Twitter.
+     */
+    async manualLogin() {
+        if (!this.page) {
+            throw new Error("Maybe you forgot to call setup()?");
+        }
+        await this.page.goto("https://x.com/login");
+        await sleep(1000);
+        // NOTE: Wait for the page to load the home page after login
+        await this.page.waitForURL("https://x.com/home", {
+            timeout: 0,
+        });
+    }
+    /**
+     * @description Send a GraphQL request to the Twitter API
+     * @param method - The method of the request
+     * @param path - The path of the request
+     * @param body - The body of the request
+     * @returns Response of the request
+     */
+    async graphql(method, path, body) {
+        if (!this.page) {
+            throw new Error("Maybe you forgot to call setup()?");
+        }
+        const args = {
+            headers: {
+                "content-type": "application/json",
+            },
+            method,
+            path,
+            params: null,
+            data: null,
+        };
+        if (method === "GET") {
+            const params = Object.fromEntries(Object.entries(body).map(([k, v]) => [k, JSON.stringify(v)]));
+            args["params"] = {
+                queryId: body.queryId,
+                variables: JSON.stringify(body.variables),
+            };
+            if (body.features) {
+                args["params"]["features"] = JSON.stringify(body.features);
+            }
+            if (body.fieldToggle) {
+                args["params"]["fieldToggle"] = JSON.stringify(body.fieldToggle);
+            }
+        }
+        else if (method === "POST") {
+            args["data"] = body;
+        }
+        await this.page.evaluate(SETUP_SCRIPT);
+        await sleep(500);
+        const response = [await this.page.evaluate(`globalThis.${REQUEST_FUNC_GLOBAL_KEY}(${JSON.stringify(removeNullRecursively(args))})`)].flat();
+        const result = pickFirstItem(response, "response");
+        if (result instanceof Error) {
+            console.log(`!!! Please report this error to the developer !!!`);
+            throw result;
+        }
+        // TODO: more strict type check
+        return result;
+    }
+    /**
+     * Sends a request to the Twitter API
+     * @param operationName - The name of the operation to request
+     * @param variables - The variables to pass to the operation
+     * @param fieldToggles - The fields to toggle on or off in the operation
+     * @returns Response of the request
+     */
+    async request(operationName, variables, fieldToggles = {}) {
+        if (!this.page || !this.operations || !this.initialState) {
+            throw new Error("Maybe you forgot to call setup()?");
+        }
+        const exp = pickFirstItem(this.operations.filter((x) => x.operationName === operationName) ?? [], "operation");
+        if (exp instanceof Error) {
+            throw exp;
+        }
+        const queryId = exp.queryId;
+        const operationType = exp.operationType;
+        const featureSwitches = exp.metadata.featureSwitches;
+        const allowFieldToggles = exp.metadata.allowFieldToggles;
+        const fieldToggle = {};
+        for (const [k, v] of Object.entries(fieldToggles)) {
+            if (allowFieldToggles && allowFieldToggles.includes(k)) {
+                fieldToggle[k] = v;
+            }
+        }
+        const method = METHOD_MAP[operationType];
+        const featureSwitch = {
+            ...this.initialState.featureSwitch.defaultConfig,
+            ...this.initialState.featureSwitch.user,
+            ...this.initialState.featureSwitch.debug,
+            ...this.initialState.featureSwitch.customOverrides,
+        };
+        const featureSwitchesMap = Object.fromEntries(Object.entries(featureSwitch).filter(([k]) => featureSwitches.includes(k)).map(([k, v]) => [k, v.value]));
+        const body = {
+            variables: variables,
+            queryId: queryId,
+            features: null,
+            fieldToggle: null,
+        };
+        if (featureSwitchesMap && Object.keys(featureSwitchesMap).length > 0) {
+            body.features = featureSwitchesMap;
+        }
+        if (fieldToggle && Object.keys(fieldToggle).length > 0) {
+            body.fieldToggle = fieldToggle;
+        }
+        return await this.graphql(method, `/graphql/${queryId}/${operationName}`, body);
+    }
+}

package/dist/twitter-types.d.ts

@@ -0,0 +1,16 @@
+import type * as TwitterOpenAPIModels from "twitter-openapi-typescript-generated/dist/models/index.d.ts";
+export type LooseType = any;
+export type TwitterOpenAPIModelsMapping = {
+    "CreateTweet": TwitterOpenAPIModels.CreateTweet;
+    "HomeTimeline": TwitterOpenAPIModels.HomeTimelineHome;
+    "UserByScreenName": TwitterOpenAPIModels.UserResultByScreenName;
+    "CreateRetweet": TwitterOpenAPIModels.CreateRetweet;
+    "FavoriteTweet": TwitterOpenAPIModels.FavoriteTweet;
+    "SearchTimeline": TwitterOpenAPIModels.SearchTimeline;
+    "UsersByRestIds": TwitterOpenAPIModels.UsersResponse;
+} & Record<string, LooseType>;
+export type SuccessResponse<T extends string> = TwitterOpenAPIModelsMapping[T];
+export type LooseErrorResponse = {
+    erros: TwitterOpenAPIModels.ErrorResponse[];
+    data: {};
+} & Record<string, LooseType>;

package/dist/twitter-types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,7 @@
+export declare const pickFirstItem: <T>(values: T[], itemName?: string) => T | Error;
+export declare const sleep: <T>(ms: number, value?: T) => Promise<T>;
+type RemoveNullRecursively<T> = T extends null ? never : T extends (infer U)[] ? RemoveNullRecursively<U>[] : T extends Record<string, unknown> ? {
+    [K in keyof T as T[K] extends null ? never : K]: RemoveNullRecursively<T[K]>;
+} : T;
+export declare const removeNullRecursively: <T>(obj: T) => RemoveNullRecursively<T>;
+export {};

package/dist/utils.js

@@ -0,0 +1,35 @@
+export const pickFirstItem = (values, itemName = "item") => {
+    if (values.length === 0) {
+        return new Error(`No ${itemName} provided`);
+    }
+    else if (values.length > 1) {
+        return new Error(`Multiple ${itemName} provided`);
+    }
+    return values[0];
+};
+export const sleep = (ms, value = undefined) => {
+    return new Promise((resolve) => setTimeout(() => resolve(value), ms));
+};
+export const removeNullRecursively = (obj) => {
+    if (obj === null || obj === undefined) {
+        return obj;
+    }
+    if (Array.isArray(obj)) {
+        return obj
+            .map((item) => removeNullRecursively(item))
+            .filter((item) => item !== null);
+    }
+    if (typeof obj === "object") {
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            if (value !== null) {
+                const cleanedValue = removeNullRecursively(value);
+                if (cleanedValue !== null) {
+                    result[key] = cleanedValue;
+                }
+            }
+        }
+        return result;
+    }
+    return obj;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "twitter-api-browser-js",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "type": "module",
   "exports": {
     ".": {
@@ -8,6 +8,7 @@
       "types": "./dist/index.d.ts"
     }
   },
+  "types": "./dist/index.d.ts",
   "dependencies": {
     "playwright": "npm:patchright@^1.57.0",
     "twitter-openapi-typescript-generated": "^0.0.38"