emusks 2.1.1 → 2.2.1

package/README.md

@@ -1,7 +1,7 @@
 <img src="https://emusks.tiago.zip/icon.svg" width="120">
 <h1>emusks: Reverse-engineered Twitter API client</h1>
 
-Log in and interact with the unofficial X API using any client identity - web, Android, iOS, or TweetDeck. Covers tweets, users, DMs, communities, spaces, and XChat (X's end-to-end encrypted chat): send encrypted DMs in one call.
+Log in and interact with the unofficial X API using any client identity - web, Android, iOS, or TweetDeck. Covers tweets, users, DMs, communities, spaces, articles, Grok (X's built-in AI), and XChat (X's end-to-end encrypted chat): send encrypted DMs in one call.
 
 officially dmca'd by twitter™ 🏆  •  includes a few leaked ads bearers
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "emusks",
-  "version": "2.1.1",
+  "version": "2.2.1",
   "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": [
     "client",

package/src/grok.js

@@ -0,0 +1,77 @@
+import { ClientTransaction, handleXMigration } from "x-client-transaction-id";
+import getCycleTLS from "./cycletls.js";
+
+const GROK_BASE = "https://api.x.com/2/grok";
+
+export default async function grokApi(route, opts = {}) {
+  if (!this.auth) throw new Error("must be logged in before calling grok");
+
+  const { method = "POST", body, params, headers } = opts;
+
+  const cleanRoute = String(route).replace(/^\/+/, "");
+  let finalUrl = `${GROK_BASE}/${cleanRoute}`;
+
+  if (params && Object.keys(params).length) {
+    const searchParams = new URLSearchParams(params);
+    const separator = finalUrl.includes("?") ? "&" : "?";
+    finalUrl = `${finalUrl}${separator}${searchParams.toString()}`;
+  }
+
+  const pathname = new URL(finalUrl).pathname;
+
+  if (!this.auth.generateTransactionId) {
+    const document = await handleXMigration();
+    const transaction = new ClientTransaction(document);
+    await transaction.initialize();
+    this.auth.generateTransactionId = transaction.generateTransactionId.bind(transaction);
+  }
+
+  const requestHeaders = {
+    accept: "*/*",
+    "accept-language": "en-US,en;q=0.9",
+    authorization: `Bearer ${this.auth.client.bearer}`,
+    "content-type": "application/json",
+    "x-csrf-token": this.auth.csrfToken,
+    "x-twitter-active-user": "yes",
+    "x-twitter-auth-type": "OAuth2Session",
+    "x-twitter-client-language": "en",
+    "x-client-transaction-id": await this.auth.generateTransactionId(method.toUpperCase(), pathname),
+    priority: "u=1, i",
+    "sec-ch-ua": '"Not(A:Brand";v="8", "Chromium";v="144"',
+    "sec-ch-ua-mobile": "?0",
+    "sec-ch-ua-platform": '"macOS"',
+    "sec-fetch-dest": "empty",
+    "sec-fetch-mode": "cors",
+    "sec-fetch-site": "same-site",
+    "sec-gpc": "1",
+    cookie:
+      this.auth.client.headers.cookie + (this.elevatedCookies ? `; ${this.elevatedCookies}` : ""),
+    ...headers,
+  };
+
+  const requestBody =
+    body == null ? undefined : typeof body === "string" ? body : JSON.stringify(body);
+
+  const cycleTLS = await getCycleTLS();
+  const res = await cycleTLS(
+    finalUrl,
+    {
+      headers: requestHeaders,
+      userAgent: this.auth.client.fingerprints.userAgent,
+      ja3: this.auth.client.fingerprints.ja3,
+      ja4r: this.auth.client.fingerprints.ja4r,
+      body: requestBody,
+      proxy: this.proxy || undefined,
+      referrer: "https://x.com/",
+    },
+    method,
+  );
+
+  const text = await res.text();
+  return {
+    status: res.status,
+    headers: res.headers,
+    text,
+    json: () => JSON.parse(text),
+  };
+}

package/src/helpers/articles.js

@@ -0,0 +1,90 @@
+import parseTimeline from "../parsers/timeline.js";
+
+export async function get(articleEntityId) {
+  if (!articleEntityId) throw new Error("get requires an articleEntityId");
+  const res = await this.graphql("ArticleEntityResultByRestId", {
+    variables: { articleEntityId },
+  });
+  return res?.data?.article_result_by_rest_id?.result ?? res;
+}
+
+export async function byUser(userId, opts = {}) {
+  if (!userId) throw new Error("byUser requires a userId");
+  const res = await this.graphql("UserArticlesTweets", {
+    variables: {
+      userId,
+      count: opts.count || 20,
+      cursor: opts.cursor,
+      includePromotedContent: false,
+      withVoice: false,
+      ...opts.variables,
+    },
+  });
+  if (opts.raw) return res;
+  return parseTimeline(res);
+}
+
+export async function slice(userId, lifecycle = "Published", opts = {}) {
+  if (!userId) throw new Error("slice requires a userId");
+  const res = await this.graphql("ArticleEntitiesSlice", {
+    variables: { userId, lifecycle, cursor: opts.cursor, ...opts.variables },
+  });
+  return res?.data ?? res;
+}
+
+export async function drafts(userId, opts = {}) {
+  return await slice.call(this, userId, "Draft", opts);
+}
+
+export async function published(userId, opts = {}) {
+  return await slice.call(this, userId, "Published", opts);
+}
+
+export async function createDraft(contentState, opts = {}) {
+  if (!contentState) throw new Error("createDraft requires a content_state");
+  return await this.graphql("ArticleEntityDraftCreate", {
+    body: { variables: { content_state: contentState, ...opts.variables } },
+  });
+}
+
+export async function updateTitle(articleEntityId, title) {
+  if (!articleEntityId) throw new Error("updateTitle requires an articleEntityId");
+  return await this.graphql("ArticleEntityUpdateTitle", {
+    body: { variables: { articleEntityId, title } },
+  });
+}
+
+export async function updateContent(articleEntityId, contentState) {
+  if (!articleEntityId) throw new Error("updateContent requires an articleEntityId");
+  return await this.graphql("ArticleEntityUpdateContent", {
+    body: { variables: { articleEntityId, content_state: contentState } },
+  });
+}
+
+export async function updateCoverMedia(articleEntityId, coverMediaId) {
+  if (!articleEntityId) throw new Error("updateCoverMedia requires an articleEntityId");
+  return await this.graphql("ArticleEntityUpdateCoverMedia", {
+    body: { variables: { articleEntityId, cover_media_id: coverMediaId } },
+  });
+}
+
+export async function publish(articleEntityId) {
+  if (!articleEntityId) throw new Error("publish requires an articleEntityId");
+  return await this.graphql("ArticleEntityPublish", {
+    body: { variables: { articleEntityId } },
+  });
+}
+
+export async function unpublish(articleEntityId) {
+  if (!articleEntityId) throw new Error("unpublish requires an articleEntityId");
+  return await this.graphql("ArticleEntityUnpublish", {
+    body: { variables: { articleEntityId } },
+  });
+}
+
+export async function remove(articleEntityId) {
+  if (!articleEntityId) throw new Error("remove requires an articleEntityId");
+  return await this.graphql("ArticleEntityDelete", {
+    body: { variables: { articleEntityId } },
+  });
+}

package/src/helpers/grok.js

@@ -0,0 +1,139 @@
+import parseGrokStream from "../parsers/grok.js";
+
+const DEFAULT_MODEL = "grok-3-latest";
+
+export async function createConversation() {
+  const res = await this.graphql("CreateGrokConversation", { body: { variables: {} } });
+  return res?.data?.create_grok_conversation?.conversation_id ?? res;
+}
+
+export async function respond(conversationId, message, opts = {}) {
+  if (!conversationId) throw new Error("respond requires a conversationId");
+
+  const body = {
+    responses: [
+      {
+        message: message ?? "",
+        sender: 1,
+        promptSource: opts.promptSource ?? "",
+        fileAttachments: opts.fileAttachments || [],
+      },
+      ...(opts.responses || []),
+    ],
+    systemPromptName: opts.systemPromptName ?? "",
+    grokModelOptionId: opts.model || DEFAULT_MODEL,
+    conversationId,
+    returnSearchResults: opts.returnSearchResults ?? true,
+    returnCitations: opts.returnCitations ?? true,
+    promptMetadata: opts.promptMetadata || { promptSource: "NATURAL", action: "INPUT" },
+    imageGenerationCount: opts.imageGenerationCount ?? 4,
+    requestFeatures: opts.requestFeatures || { eagerTweets: true, serverHistory: true },
+    enableSideBySide: opts.enableSideBySide ?? true,
+    toolOverrides: opts.toolOverrides || {},
+    isDeepsearch: opts.deepsearch ?? false,
+    isReasoning: opts.reasoning ?? false,
+    ...opts.body,
+  };
+
+  const res = await this.grokApi("add_response.json", { method: "POST", body });
+  if (res.status !== 200) {
+    let detail = res.text;
+    try {
+      detail = res.json()?.errors?.map((e) => e.message).join(", ") || res.text;
+    } catch {}
+    throw new Error(`grok add_response failed (${res.status}): ${detail}`);
+  }
+
+  if (opts.raw) return res.text;
+  return parseGrokStream(res.text);
+}
+
+export async function ask(message, opts = {}) {
+  const conversationId = opts.conversationId || (await createConversation.call(this));
+  const result = await respond.call(this, conversationId, message, opts);
+  if (opts.raw) return result;
+  return { ...result, conversationId: result.conversationId || conversationId };
+}
+
+export async function home() {
+  const res = await this.graphql("GrokHome", { variables: {} });
+  return res?.data?.grok_home ?? res;
+}
+
+export async function models() {
+  const h = await home.call(this);
+  return h?.grok_model_options ?? [];
+}
+
+export async function history(opts = {}) {
+  const res = await this.graphql("GrokHistory", {
+    variables: { count: opts.count, cursor: opts.cursor, ...opts.variables },
+  });
+  return res?.data?.grok_conversation_history ?? res;
+}
+
+export async function mediaHistory(opts = {}) {
+  const res = await this.graphql("GrokMediaHistory", {
+    variables: { count: opts.count, cursor: opts.cursor, ...opts.variables },
+  });
+  return res?.data ?? res;
+}
+
+export async function conversation(restId, opts = {}) {
+  if (!restId) throw new Error("conversation requires a rest id");
+  const res = await this.graphql("GrokConversationItemsByRestId", {
+    variables: { restId, ...opts.variables },
+  });
+  return res?.data ?? res;
+}
+
+export async function search(query, opts = {}) {
+  const res = await this.graphql("SearchGrokConversations", {
+    variables: { query, ...opts.variables },
+  });
+  return res?.data ?? res;
+}
+
+export async function pinned() {
+  const res = await this.graphql("GrokPinnedConversations", { variables: {} });
+  return res?.data?.grok_pinned_conversations ?? res;
+}
+
+export async function pin(conversationId) {
+  if (!conversationId) throw new Error("pin requires a conversationId");
+  const res = await this.graphql("GrokPinConversation", {
+    body: { variables: { conversationId } },
+  });
+  return res?.data?.grokconversation_pin ?? res;
+}
+
+export async function unpin(conversationId) {
+  if (!conversationId) throw new Error("unpin requires a conversationId");
+  const res = await this.graphql("GrokUnpinConversation", {
+    body: { variables: { conversationId } },
+  });
+  return res?.data?.grokconversation_unpin ?? res;
+}
+
+export async function deleteMessage(conversationId, chatItemId) {
+  if (!conversationId || !chatItemId) {
+    throw new Error("deleteMessage requires (conversationId, chatItemId)");
+  }
+  return await this.graphql("DeleteGrokMessage", {
+    body: { variables: { conversation_id: conversationId, chat_item_id: chatItemId } },
+  });
+}
+
+export async function clear() {
+  return await this.graphql("ClearGrokConversations", { body: { variables: {} } });
+}
+
+export async function share(shareId) {
+  if (!shareId) throw new Error("share requires a grok_share_id");
+  const res = await this.graphql("GrokShare", { variables: { grok_share_id: shareId } });
+  return res?.data ?? res;
+}
+
+export async function setPreferences(params = {}) {
+  return await this.graphql("SetGrokPreferences", { body: { variables: { ...params } } });
+}

package/src/helpers/index.js

@@ -1,7 +1,9 @@
 import * as account from "./account.js";
+import * as articles from "./articles.js";
 import * as bookmarks from "./bookmarks.js";
 import * as communities from "./communities.js";
 import * as dms from "./dms.js";
+import * as grok from "./grok.js";
 import * as jetfuel from "./jetfuel.js";
 import * as lists from "./lists.js";
 import * as media from "./media.js";
@@ -52,4 +54,6 @@ export default function initHelpers(proto) {
   namespace(proto, "syndication", syndication);
   namespace(proto, "xchat", xchat);
   namespace(proto, "jetfuel", jetfuel);
+  namespace(proto, "grok", grok);
+  namespace(proto, "articles", articles);
 }

package/src/index.js

@@ -3,6 +3,7 @@ import clients from "./clients.js";
 import getCycleTLS from "./cycletls.js";
 import flowLogin from "./flow.js";
 import graphql, { GRAPHQL_ENDPOINTS } from "./graphql.js";
+import grokApi from "./grok.js";
 import initHelpers from "./helpers/index.js";
 import jetfuel from "./jetfuel.js";
 import parseUser from "./parsers/user.js";
@@ -195,4 +196,5 @@ Emusks.prototype.graphql = graphql;
 Emusks.prototype.v1_1 = v1_1;
 Emusks.prototype.v2 = v2;
 Emusks.prototype.jf = jetfuel;
+Emusks.prototype.grokApi = grokApi;
 initHelpers(Emusks.prototype);

package/src/parsers/grok.js

@@ -0,0 +1,65 @@
+export default function parseGrokStream(text) {
+  const result = {
+    conversationId: null,
+    userChatItemId: null,
+    agentChatItemId: null,
+    message: "",
+    reasoning: "",
+    softStop: false,
+    followUpSuggestions: [],
+    webResults: [],
+    citations: [],
+    images: [],
+    cards: [],
+    requestEntities: null,
+    responseEntities: null,
+    chunks: [],
+  };
+
+  for (const line of String(text).split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+
+    let obj;
+    try {
+      obj = JSON.parse(trimmed);
+    } catch {
+      continue;
+    }
+    result.chunks.push(obj);
+
+    if (obj.conversationId && !obj.result) {
+      result.conversationId = obj.conversationId;
+      result.userChatItemId = obj.userChatItemId ?? result.userChatItemId;
+      result.agentChatItemId = obj.agentChatItemId ?? result.agentChatItemId;
+      continue;
+    }
+
+    const r = obj.result;
+    if (!r) continue;
+
+    if (r.responseChatItemId) result.agentChatItemId = r.responseChatItemId;
+    if (r.isSoftStop) result.softStop = true;
+    if (Array.isArray(r.followUpSuggestions)) {
+      result.followUpSuggestions.push(...r.followUpSuggestions);
+    }
+    if (Array.isArray(r.citations)) result.citations.push(...r.citations);
+    if (Array.isArray(r.webResults)) result.webResults.push(...r.webResults);
+    if (Array.isArray(r.cards)) result.cards.push(...r.cards);
+    if (r.requestEntities) result.requestEntities = r.requestEntities;
+    if (r.responseEntities) result.responseEntities = r.responseEntities;
+
+    const image = r.imageAttachment || r.attachment || r.generatedImage;
+    if (image) result.images.push(image);
+
+    if (typeof r.message === "string") {
+      if (r.isThinking || r.messageTag === "header") {
+        result.reasoning += r.message;
+      } else if (r.messageTag === "final" || (!r.messageTag && r.message)) {
+        result.message += r.message;
+      }
+    }
+  }
+
+  return result;
+}