emusks 0.0.2 → 2.0.0

package/README.md

@@ -1,279 +1,6 @@
-# emusks — reverse-engineered Twitter API
+<img src="docs/src/icon.svg" width="120">
+<h1>emusks: Reverse-engineered Twitter API client</h1>
 
-emusks is a reverse-engineered Twitter API wrapper that **just works**. beta for now.
+Log in and interact with the unofficial X API using any client identity — web, Android, iOS, or TweetDeck
 
-```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.
+[Learn more →](https://emusks.js.org)

package/build/graphql.js

@@ -0,0 +1,24 @@
+const URL = `https://raw.githubusercontent.com/fa0311/TwitterInternalAPIDocument/refs/heads/develop/docs/json/API.json`;
+
+const json = await fetch(URL).then((r) => r.json());
+const graphql = json.graphql;
+
+const buildUrl = (base, features) => {
+  const params = new URLSearchParams();
+
+  if (features && Object.keys(features).length) {
+    params.set(`features`, JSON.stringify(features));
+  }
+
+  const query = params.toString();
+  return query ? `${base}?${query}` : base;
+};
+
+const transformed = Object.fromEntries(
+  Object.entries(graphql).map(([name, data]) => {
+    const constructedUrl = buildUrl(data.url, data.features);
+    return [name, [data.method, constructedUrl]];
+  }),
+);
+
+await Bun.write(`./src/static/graphql.js`, `export default ${JSON.stringify(transformed)};`);

package/build/v1.1.js

@@ -0,0 +1,28 @@
+const URL = `https://raw.githubusercontent.com/fa0311/TwitterInternalAPIDocument/refs/heads/develop/docs/json/v1.1.json`;
+
+const json = await fetch(URL).then((r) => r.json());
+
+const seen = new Set();
+const duplicates = new Set();
+
+for (const entry of json) {
+  const queryId = entry.queryId.replace(/^\//, "");
+  if (seen.has(queryId)) {
+    duplicates.add(queryId);
+  }
+  seen.add(queryId);
+}
+
+const transformed = {};
+
+for (const entry of json) {
+  const queryId = entry.queryId.replace(/^\//, "");
+  const method = entry.dispatch[0];
+  const urlTemplate = entry.dispatch[2];
+  const url = urlTemplate.replace("{queryId}", queryId);
+
+  const key = duplicates.has(queryId) ? `${method}:${queryId}` : queryId;
+  transformed[key] = [method, url];
+}
+
+await Bun.write(`./src/static/v1.1.js`, `export default ${JSON.stringify(transformed)};`);

package/build/v2.js

@@ -0,0 +1,28 @@
+const URL = `https://raw.githubusercontent.com/fa0311/TwitterInternalAPIDocument/refs/heads/develop/docs/json/v2.json`;
+
+const json = await fetch(URL).then((r) => r.json());
+
+const seen = new Set();
+const duplicates = new Set();
+
+for (const entry of json) {
+  const queryId = entry.queryId.replace(/^\//, "");
+  if (seen.has(queryId)) {
+    duplicates.add(queryId);
+  }
+  seen.add(queryId);
+}
+
+const transformed = {};
+
+for (const entry of json) {
+  const queryId = entry.queryId.replace(/^\//, "");
+  const method = entry.dispatch[0];
+  const urlTemplate = entry.dispatch[2];
+  const url = urlTemplate.replace("{queryId}", queryId);
+
+  const key = duplicates.has(queryId) ? `${method}:${queryId}` : queryId;
+  transformed[key] = [method, url];
+}
+
+await Bun.write(`./src/static/v2.js`, `export default ${JSON.stringify(transformed)};`);

package/package.json

@@ -1,11 +1,19 @@
 {
   "name": "emusks",
-  "version": "0.0.2",
-  "description": "Reverse-engineered X Pro (Tweetdeck) API",
-  "main": "src/index.js",
-  "keywords": [
-    "twitter"
-  ],
-  "author": "Tiago",
-  "license": "Apache-2.0"
+  "version": "2.0.0",
+  "description": "Reverse-engineered Twitter API client. Log in and interact with the unofficial X API using any client identity — web, Android, iOS, or TweetDeck",
+  "keywords": ["twitter", "twitter-api", "x", "x-api", "reverse-engineering", "client"],
+  "homepage": "https://github.com/tiagozip/cap",
+  "bugs": {
+    "url": "https://github.com/tiagozip/cap/issues"
+  },
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tiagozip/cap.git"
+  },
+  "dependencies": {
+    "cycletls": "^2.0.5",
+    "x-client-transaction-id": "^0.1.9"
+  }
 }

package/src/clients.js

@@ -0,0 +1,62 @@
+const chrome_fingerprint = {
+  "user-agent":
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/144.0.0.0 Safari/537.36",
+  ja3: "771,4865-4866-4867-49195-49199-49196-49200-52393-52392-49171-49172-156-157-47-53,35-5-27-16-0-10-13-23-45-65037-17613-18-65281-51-43-11,4588-29-23-24,0",
+  ja4r: "t13d1516h2_002f,0035,009c,009d,1301,1302,1303,c013,c014,c02b,c02c,c02f,c030,cca8,cca9_0005,000a,000b,000d,0012,0017,001b,0023,002b,002d,0033,44cd,fe0d,ff01_0403,0804,0401,0503,0805,0501,0806,0601",
+};
+
+const android_fingerprint = {
+  ja3: "771,4865-4866-4867-49195-49199-49196-49200-52393-52392-49171-49172-156-157-47-53,23-0-16-11-17613-27-43-35-13-65037-51-18-65281-45-5-10-41,4588-29-23-24,0",
+  ja4r: "t13d1517h2_002f,0035,009c,009d,1301,1302,1303,c013,c014,c02b,c02c,c02f,c030,cca8,cca9_0005,000a,000b,000d,0012,0017,001b,0023,0029,002b,002d,0033,44cd,fe0d,ff01_0403,0804,0401,0503,0805,0501,0806,0601",
+
+  userAgent: "TwitterAndroid/10.93.0-release.00 (Android 14; Google Pixel 7 Pro)",
+};
+
+const iphone_fingerprint = {
+  ja3: "771,4865-4866-4867-49195-49199-49196-49200-52393-52392-49171-49172-156-157-47-53,23-0-16-11-17613-27-43-35-13-65037-51-18-65281-45-5-10-41,4588-29-23-24,0",
+  ja4r: "t13d1517h2_002f,0035,009c,009d,1301,1302,1303,c013,c014,c02b,c02c,c02f,c030,cca8,cca9_0005,000a,000b,000d,0012,0017,001b,0023,0029,002b,002d,0033,44cd,fe0d,ff01_0403,0804,0401,0503,0805,0501,0806,0601",
+
+  userAgent: "Twitter-iPhone/10.93.0-release.00 (iPhone; iOS 16.5.1; Scale/3.00)",
+};
+
+export default {
+  android: {
+    // beware! this might get your account locked when tweeting
+    bearer:
+      "AAAAAAAAAAAAAAAAAAAAAFXzAwAAAAAAMHCxpeSDG1gLNLghVe8d74hl6k4%3DRUMF4xAQLsbeBhTSRrCiQpJtxoGWeyHrDb5te2jpGskWDFW82F",
+    fingerprints: android_fingerprint,
+  },
+  iphone: {
+    bearer:
+      "AAAAAAAAAAAAAAAAAAAAAAj4AQAAAAAAPraK64zCZ9CSzdLesbE7LB%2Bw4uE%3DVJQREvQNCZJNiz3rHO7lOXlkVOQkzzdsgu6wWgcazdMUaGoUGm",
+    fingerprints: iphone_fingerprint,
+  },
+  ipad: {
+    bearer:
+      "AAAAAAAAAAAAAAAAAAAAAGHtAgAAAAAA%2Bx7ILXNILCqkSGIzy6faIHZ9s3Q%3DQy97w6SIrzE7lQwPJEYQBsArEE2fC25caFwRBvAGi456G09vGR",
+    fingerprints: iphone_fingerprint,
+  },
+  mac: {
+    bearer:
+      "AAAAAAAAAAAAAAAAAAAAAIWCCAAAAAAA2C25AxqI%2BYCS7pdfJKRH8Xh19zA%3D8vpDZzPHaEJhd20MKVWp3UR38YoPpuTX7UD2cVYo3YNikubuxd",
+    fingerprints: iphone_fingerprint,
+  },
+
+  old: {
+    // doesn't seem to work
+    bearer:
+      "AAAAAAAAAAAAAAAAAAAAAPYXBAAAAAAACLXUNDekMxqa8h%2F40K4moUkGsoc%3DTYfbDKbT3jJPCEVnMYqilB28NHfOPqkca3qaAxGfsyKCs0wRbw",
+    fingerprints: chrome_fingerprint,
+  },
+  web: {
+    bearer:
+      "AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D1Zv7ttfk8LF81IUq16cHjhLTvJu4FA33AGWWjCpTnA",
+    fingerprints: chrome_fingerprint,
+  },
+  tweetdeck: {
+    // requires premium
+    bearer:
+      "AAAAAAAAAAAAAAAAAAAAAFQODgEAAAAAVHTp76lzh3rFzcHbmHVvQxYYpTw%3DckAlMINMjmCwxUcaXbAN4XqJVdgMJaHqNOFgPMK0zN1qLqLQCF",
+    fingerprints: chrome_fingerprint,
+  },
+};

package/src/cycletls.js

@@ -0,0 +1,26 @@
+import initCycleTLS from "cycletls";
+
+let cycleTLS;
+
+initCycleTLS().then((c) => {
+  cycleTLS = c;
+});
+
+export default async function getCycleTLS() {
+  if (!cycleTLS) {
+    await new Promise((r) => {
+      const c = setInterval(() => {
+        if (cycleTLS) {
+          clearInterval(c);
+          r();
+        }
+      }, 10);
+    });
+  }
+
+  return cycleTLS;
+}
+
+process.on("exit", () => {
+  if (cycleTLS) cycleTLS.exit();
+});