emusks 0.0.1

package/README.md

@@ -0,0 +1,279 @@
+# emusks — reverse-engineered Twitter API
+
+emusks is a reverse-engineered Twitter API wrapper that **just works**. beta for now.
+
+```javascript
+import emusks from "emusks";
+
+const client = new emusks({
+  authToken: "your_auth_token_here",
+});
+
+await client.login();
+
+console.log(`logged in as ${client.user.username}`);
+
+const timeline = await client.getTimeline({
+  count: 20,
+  type: "foryou", // or "following"
+});
+
+console.log(`timeline has ${timeline.tweets.length} tweets`);
+```
+
+## features
+
+- **timeline**: get "For You" and "Following" timelines with full parsing
+- **tweets**: create, delete, and fetch tweets with polls and media
+- **interactions**: like, retweet, follow, bookmark functionality
+- **search**: search for tweets and users
+- **user data**: get detailed user profiles and statistics
+- **conversations**: handle threaded conversations and replies
+- **pagination**: cursor-based pagination for all timeline endpoints
+
+## api reference
+
+### timeline
+
+get tweets from your timeline with support for both "For You" and "Following" feeds:
+
+```javascript
+const timeline = await client.getTimeline({
+  count: 20,           // tweets to fetch
+  type: "foryou",      // "foryou" or "following"
+  cursor: undefined,   // pagination cursor for next page
+  includeAds: false,   // include promoted content
+  seenTweetIds: [],    // array of tweet ids
+});
+
+// response structure:
+{
+  tweets: [...],        // array of parsed tweet objects
+  conversations: [...], // array of conversation threads
+  users: [...],         // array of suggested users
+  cursors: {
+    top: "...",         // cursor for newer tweets
+    bottom: "..."       // cursor for older tweets
+  },
+  metadata: {
+    scribeConfig: {...} // Timeline metadata
+  }
+}
+```
+
+### Tweets
+
+```javascript
+// tweet something
+
+const result = await client.tweet({
+  text: "Hello world!",
+  reply: "1234567890", // (optional)
+  poll: {
+    // (optional) add a poll
+    choices: ["Option 1", "Option 2"],
+    duration_minutes: 1440,
+  },
+
+  // TODO: media upload & quote tweets
+});
+
+// delete a tweet
+await client.deleteTweet("1234567890");
+
+// get a single tweet (no auth required)
+const tweet = await client.getTweet("1234567890");
+
+// get full tweet with replies (auth required)
+const fullTweet = await client.getFullTweet("1234567890");
+```
+
+### Interactions
+
+```javascript
+// like/unlike a tweet
+await client.likeTweet("1234567890");
+await client.unlikeTweet("1234567890");
+
+// retweet/unretweet
+await client.retweet("1234567890");
+await client.unretweet("1234567890");
+
+// follow/unfollow user
+await client.followUser("username");
+await client.unfollowUser("username");
+
+// bookmark/unbookmark
+await client.bookmarkTweet("1234567890");
+await client.unbookmarkTweet("1234567890");
+```
+
+### notifications
+
+```javascript
+const notifications = await client.getNotifications({
+  type: "All",           // "All", "Verified", "Mentions"
+  limit: 20,             // number of notifications to fetch
+  cursor: undefined,     // pagination cursor for next page
+});
+
+// response structure:
+{
+  entries: [...],        // array of notification entries
+  cursors: {
+    top: "...",          // cursor for newer notifications
+    bottom: "..."        // cursor for older notifications
+  }
+}
+
+// paginate through notifications
+const nextPage = await client.getNotifications({
+  type: "All",
+  limit: 20,
+  cursor: notifications.cursors.bottom
+});
+```
+
+### user tweets
+
+get tweets from a specific user with pagination:
+
+```javascript
+const userTweets = await client.getUserTweets("1234567890", {
+  count: 20,                     // number of tweets to fetch
+  includePromotedContent: false, // include promoted content
+  cursor: undefined              // pagination cursor
+});
+
+// response structure:
+{
+  tweets: [...],        // array of parsed tweet objects
+  cursors: {
+    top: "...",         // cursor for newer tweets
+    bottom: "..."       // cursor for older tweets
+  }
+}
+
+// or:
+const user = await client.getUser("username");
+const tweets = await user.getTweets({
+  count: 20,
+  cursor: undefined
+});
+```
+
+### tweet replies
+
+get replies to a specific tweet with pagination:
+
+```javascript
+// Get full tweet conversation with replies
+const fullTweet = await client.getFullTweet("1234567890", {
+  rankingMode: "Relevance",  // "Relevance" or "Recency"
+  includeAds: false,
+  cursor: undefined          // pagination cursor for more replies
+});
+
+// response structure:
+{
+  tweets: [...],        // array including main tweet and replies
+  cursors: {
+    top: "...",         // cursor for newer replies
+    bottom: "..."       // cursor for older replies
+  }
+}
+
+// response structure:
+{
+  mainTweet: {...},     // original tweet
+  replies: [...],       // array of reply tweets
+  cursors: {
+    top: "...",
+    bottom: "..."
+  }
+}
+
+// if you just need replies:
+const replies = await client.getTweetReplies("1234567890", {
+  rankingMode: "Relevance",
+  cursor: undefined
+});
+```
+
+### search
+
+search for tweets:
+
+```javascript
+const searchResults = await client.search("bun javascript", {
+  resultsCount: 20,      // number of results to fetch
+  product: "Latest",
+  cursor: undefined      // pagination cursor
+});
+
+// response structure:
+{
+  entries: [...],        // array of search result entries
+  cursors: {
+    top: "...",          // cursor for newer results
+    bottom: "..."        // cursor for older results
+  }
+}
+
+// paginate through search results
+const nextResults = await client.search("bun javascript", {
+  resultsCount: 20,
+  cursor: searchResults.cursors.bottom
+});
+```
+
+## requirements
+
+- twitter account auth cookie (not required for some endpoints)
+
+## installation
+
+- **bun:** `bun add emusks`
+- **yarn:** `yarn add emusks`
+- **pnpm:** `pnpm add emusks`
+- **npm:** `npm install emusks`
+
+### getting the auth cookie
+
+1. log in to https://x.com
+2. open devtools (F12)
+3. go to the "Application" tab
+4. find the "Cookies" section in the left sidebar
+5. find the "x.com" domain
+6. find the "auth_token" cookie
+7. copy the value of the "auth_token" cookie
+
+## limitations
+
+- the twitter API might change at any time, but this is unlikely to happen
+
+- emusks can **not** be used to login without an auth token. twitter has spent a lot of time and effort making it so that this is extremely hard to due to CAPTCHAs, complex flows, etc.
+
+- emusks does **not** support all possible endpoints.
+
+## faq
+
+### why?
+
+current ones are outdated, are hard to use, badly documented and such overall.
+
+### no, like why did you name it emusks?
+
+because elon is responsable for the awful state of twitter's horrible api and twitter overall.
+
+### how?
+
+endpoints are reverse-engineered from Tweetdeck Web (also known as X Pro), which uses separate endpoints that are less protected than the normal endpoints.
+
+unlike the actual X Pro, elon forgot to restrict these endpoints to premium users, so they can be used by anyone.
+
+other endpoints (mostly read ones) are reverse-engineered from other parts of twitter, such as embeds.
+
+### why not the official API?
+
+it's heavily ratelimited, hard to use, and overall very badly documented.

package/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "emusks",
+  "version": "0.0.1",
+  "description": "Reverse-engineered X Pro (Tweetdeck) API",
+  "main": "src/index.js",
+  "keywords": [
+    "twitter"
+  ],
+  "author": "Tiago",
+  "license": "Apache-2.0"
+}

package/src/index.js

@@ -0,0 +1,89 @@
+import parseUser from "./parsers/user.js";
+import headers from "./utils/headers.js";
+
+import * as tweeting from "./methods/tweet.js";
+import * as retweeting from "./methods/retweet.js";
+import * as liking from "./methods/like.js";
+import * as following from "./methods/follow.js";
+import * as bookmarks from "./methods/bookmarks.js";
+import * as notifications from "./methods/notifications.js";
+import * as search from "./methods/search.js";
+import * as users from "./methods/users.js";
+import * as timeline from "./methods/timeline.js";
+
+class Client {
+  auth = {};
+  user = null;
+
+  constructor({ authToken } = {}) {
+    if (authToken) {
+      this.auth.token = authToken;
+    }
+  }
+
+  async login() {
+    if (!this.auth.token) {
+      throw new Error("auth token is required to login");
+    }
+
+    // gets the csrf token from headers
+    const res = await fetch("https://pro.x.com/", {
+      headers: {
+        accept:
+          "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7",
+        cookie: `auth_token=${this.auth.token};`,
+
+        ...headers,
+      },
+    });
+
+    const csrfToken = res.headers
+      .get("set-cookie")
+      .split(", ct0=")[1]
+      .split(";")[0];
+
+    if (!csrfToken) {
+      throw new Error("[emusks] failed to log in");
+    }
+
+    this.auth.csrfToken = csrfToken;
+    this.auth.cookies = `auth_token=${this.auth.token}; ct0=${csrfToken};`;
+
+    const initialStateMatch = (await res.text()).match(
+      /window\.__INITIAL_STATE__\s*=\s*({.*?});/s
+    );
+
+    if (!initialStateMatch) {
+      console.error(
+        "[emusks] failed to extract initial state from response. auth will work, \n         but user data will not be available (reason: no match)"
+      );
+      return;
+    }
+
+    const usersEntities = JSON.parse(initialStateMatch[1])?.entities?.users
+      ?.entities;
+    const initialStateUser = usersEntities && Object.values(usersEntities)[0];
+
+    if (!initialStateUser) {
+      console.error(
+        "[emusks] failed to extract initial state from response. auth will work, \n         but user data will not be available (reason: user not parsed)"
+      );
+      return;
+    }
+
+    this.user = parseUser(initialStateUser);
+    return this.user;
+  }
+}
+
+Object.assign(Client.prototype, tweeting);
+Object.assign(Client.prototype, retweeting);
+Object.assign(Client.prototype, liking);
+Object.assign(Client.prototype, following);
+Object.assign(Client.prototype, bookmarks);
+Object.assign(Client.prototype, notifications);
+Object.assign(Client.prototype, search);
+Object.assign(Client.prototype, users);
+Object.assign(Client.prototype, timeline);
+
+export default Client;

package/src/methods/bookmarks.js

@@ -0,0 +1,91 @@
+import headers from "../utils/headers.js";
+
+export async function bookmark(tweetId) {
+  if (!this.auth.cookies) {
+    throw new Error("you must be logged in to bookmark a tweet");
+  }
+
+  const out = await (
+    await fetch(
+      "https://pro.x.com/i/api/graphql/aoDbu3RHznuiSkQ9aNM67Q/CreateBookmark",
+      {
+        headers: {
+          Accept: "*/*",
+          "accept-language": "en-US,en;q=0.9",
+
+          authorization:
+            "Bearer AAAAAAAAAAAAAAAAAAAAAFQODgEAAAAAVHTp76lzh3rFzcHbmHVvQxYYpTw%3DckAlMINMjmCwxUcaXbAN4XqJVdgMJaHqNOFgPMK0zN1qLqLQCF",
+          "content-type": "application/json",
+
+          "x-client-transaction-id": Math.random().toString().replace("0.", ""),
+          "x-csrf-token": this.auth.csrfToken,
+
+          "x-twitter-active-user": "yes",
+          "x-twitter-auth-type": "OAuth2Session",
+          "x-twitter-client-language": "en",
+
+          cookie: this.auth.cookies,
+          ...headers,
+        },
+        body: JSON.stringify({
+          variables: { tweet_id: tweetId },
+          queryId: "aoDbu3RHznuiSkQ9aNM67Q",
+        }),
+        method: "POST",
+      }
+    )
+  ).json();
+
+  if (!out?.data?.tweet_bookmark_put) {
+    throw new Error(
+      `failed to bookmark tweet: ${JSON.stringify(out, null, 2)}`
+    );
+  }
+
+  return true;
+}
+
+export async function unbookmark(tweetId) {
+  if (!this.auth.cookies) {
+    throw new Error("you must be logged in to unbookmark a tweet");
+  }
+
+  const out = await (
+    await fetch(
+      "https://pro.x.com/i/api/graphql/Wlmlj2-xzyS1GN3a6cj-mQ/DeleteBookmark",
+      {
+        headers: {
+          Accept: "*/*",
+          "accept-language": "en-US,en;q=0.9",
+
+          authorization:
+            "Bearer AAAAAAAAAAAAAAAAAAAAAFQODgEAAAAAVHTp76lzh3rFzcHbmHVvQxYYpTw%3DckAlMINMjmCwxUcaXbAN4XqJVdgMJaHqNOFgPMK0zN1qLqLQCF",
+          "content-type": "application/json",
+
+          "x-client-transaction-id": Math.random().toString().replace("0.", ""),
+          "x-csrf-token": this.auth.csrfToken,
+
+          "x-twitter-active-user": "yes",
+          "x-twitter-auth-type": "OAuth2Session",
+          "x-twitter-client-language": "en",
+
+          cookie: this.auth.cookies,
+          ...headers,
+        },
+        body: JSON.stringify({
+          variables: { tweet_id: tweetId },
+          queryId: "Wlmlj2-xzyS1GN3a6cj-mQ",
+        }),
+        method: "POST",
+      }
+    )
+  ).json();
+
+  if (!out?.data?.tweet_bookmark_delete) {
+    throw new Error(
+      `failed to unbookmark tweet: ${JSON.stringify(out, null, 2)}`
+    );
+  }
+
+  return true;
+}

package/src/methods/follow.js

@@ -0,0 +1,88 @@
+import parseUser from "../parsers/user.js";
+import headers from "../utils/headers.js";
+
+export async function follow(userId) {
+  if (!this.auth.cookies) {
+    throw new Error("you must be logged in to follow someone");
+  }
+
+  const out = await (
+    await fetch("https://pro.x.com/i/api/1.1/friendships/create.json", {
+      headers: {
+        Accept: "*/*",
+        "accept-language": "en-US,en;q=0.9",
+
+        authorization:
+          "Bearer AAAAAAAAAAAAAAAAAAAAAFQODgEAAAAAVHTp76lzh3rFzcHbmHVvQxYYpTw%3DckAlMINMjmCwxUcaXbAN4XqJVdgMJaHqNOFgPMK0zN1qLqLQCF",
+        "content-type": "application/x-www-form-urlencoded",
+
+        "x-client-transaction-id": Math.random().toString().replace("0.", ""),
+        "x-csrf-token": this.auth.csrfToken,
+
+        "x-twitter-active-user": "yes",
+        "x-twitter-auth-type": "OAuth2Session",
+        "x-twitter-client-language": "en",
+
+        cookie: this.auth.cookies,
+        ...headers,
+      },
+
+      // i'm too lazy to make form data manually and this works
+      // well so i'm just gonna use that
+      body: `include_profile_interstitial_type=1&include_blocking=1&include_blocked_by=1&include_followed_by=1&include_want_retweets=1&include_mute_edge=1&include_can_dm=1&include_can_media_tag=1&include_ext_is_blue_verified=1&include_ext_verified_type=1&include_ext_profile_image_shape=1&skip_status=1&user_id=${encodeURIComponent(
+        userId
+      )}`,
+      method: "POST",
+    })
+  ).json();
+
+  if (!out?.id) {
+    throw new Error(`failed to follow user: ${JSON.stringify(out, null, 2)}`);
+  }
+
+  return {
+    user: parseUser(out),
+  };
+}
+
+export async function unfollow(userId) {
+  if (!this.auth.cookies) {
+    throw new Error("you must be logged in to follow someone");
+  }
+
+  const out = await (
+    await fetch("https://pro.x.com/i/api/1.1/friendships/destroy.json", {
+      headers: {
+        Accept: "*/*",
+        "accept-language": "en-US,en;q=0.9",
+
+        authorization:
+          "Bearer AAAAAAAAAAAAAAAAAAAAAFQODgEAAAAAVHTp76lzh3rFzcHbmHVvQxYYpTw%3DckAlMINMjmCwxUcaXbAN4XqJVdgMJaHqNOFgPMK0zN1qLqLQCF",
+        "content-type": "application/x-www-form-urlencoded",
+
+        "x-client-transaction-id": Math.random().toString().replace("0.", ""),
+        "x-csrf-token": this.auth.csrfToken,
+
+        "x-twitter-active-user": "yes",
+        "x-twitter-auth-type": "OAuth2Session",
+        "x-twitter-client-language": "en",
+
+        cookie: this.auth.cookies,
+        ...headers,
+      },
+
+      body: `include_profile_interstitial_type=1&include_blocking=1&include_blocked_by=1&include_followed_by=1&include_want_retweets=1&include_mute_edge=1&include_can_dm=1&include_can_media_tag=1&include_ext_is_blue_verified=1&include_ext_verified_type=1&include_ext_profile_image_shape=1&skip_status=1&user_id=${encodeURIComponent(
+        userId
+      )}`,
+      method: "POST",
+    })
+  ).json();
+
+  if (!out?.id) {
+    throw new Error(`failed to unfollow user: ${JSON.stringify(out, null, 2)}`);
+  }
+
+  return {
+    user: parseUser(out),
+  };
+}

package/src/methods/like.js

@@ -0,0 +1,87 @@
+import headers from "../utils/headers.js";
+
+export async function like(tweetId) {
+  if (!this.auth.cookies) {
+    throw new Error("you must be logged in to like a tweet");
+  }
+
+  const out = await (
+    await fetch(
+      "https://pro.x.com/i/api/graphql/lI07N6Otwv1PhnEgXILM7A/FavoriteTweet",
+      {
+        headers: {
+          Accept: "*/*",
+          "accept-language": "en-US,en;q=0.9",
+
+          authorization:
+            "Bearer AAAAAAAAAAAAAAAAAAAAAFQODgEAAAAAVHTp76lzh3rFzcHbmHVvQxYYpTw%3DckAlMINMjmCwxUcaXbAN4XqJVdgMJaHqNOFgPMK0zN1qLqLQCF",
+          "content-type": "application/json",
+
+          "x-client-transaction-id": Math.random().toString().replace("0.", ""),
+          "x-csrf-token": this.auth.csrfToken,
+
+          "x-twitter-active-user": "yes",
+          "x-twitter-auth-type": "OAuth2Session",
+          "x-twitter-client-language": "en",
+
+          cookie: this.auth.cookies,
+          ...headers,
+        },
+        body: JSON.stringify({
+          variables: { tweet_id: tweetId },
+          queryId: "lI07N6Otwv1PhnEgXILM7A",
+        }),
+        method: "POST",
+      }
+    )
+  ).json();
+
+  if (!out?.data?.favorite_tweet) {
+    throw new Error(`failed to like tweet: ${JSON.stringify(out, null, 2)}`);
+  }
+
+  return true;
+}
+
+export async function dislike(tweetId) {
+  if (!this.auth.cookies) {
+    throw new Error("you must be logged in to dislike a tweet");
+  }
+
+  const out = await (
+    await fetch(
+      "https://pro.x.com/i/api/graphql/ZYKSe-w7KEslx3JhSIk5LA/UnfavoriteTweet",
+      {
+        headers: {
+          Accept: "*/*",
+          "accept-language": "en-US,en;q=0.9",
+
+          authorization:
+            "Bearer AAAAAAAAAAAAAAAAAAAAAFQODgEAAAAAVHTp76lzh3rFzcHbmHVvQxYYpTw%3DckAlMINMjmCwxUcaXbAN4XqJVdgMJaHqNOFgPMK0zN1qLqLQCF",
+          "content-type": "application/json",
+
+          "x-client-transaction-id": Math.random().toString().replace("0.", ""),
+          "x-csrf-token": this.auth.csrfToken,
+
+          "x-twitter-active-user": "yes",
+          "x-twitter-auth-type": "OAuth2Session",
+          "x-twitter-client-language": "en",
+
+          cookie: this.auth.cookies,
+          ...headers,
+        },
+        body: JSON.stringify({
+          variables: { tweet_id: tweetId },
+          queryId: "ZYKSe-w7KEslx3JhSIk5LA",
+        }),
+        method: "POST",
+      }
+    )
+  ).json();
+
+  if (!out?.data?.unfavorite_tweet) {
+    throw new Error(`failed to dislike tweet: ${JSON.stringify(out, null, 2)}`);
+  }
+
+  return true;
+}