x-api.mjs

/**
 * X Chat API access via the X API SDK (XDK).
 *
 * Every REST call goes through the XDK client so request signing, models, and
 * endpoint paths stay in sync with the X API. Authentication is an OAuth2 user
 * access token (scopes dm.read + dm.write).
 */
import { Client } from "@xdevplatform/xdk";

const BASE_URL = "https://api.x.com";

/** CamelCase object keys to the snake_case the X API reads. */
function toSnake(value) {
  if (Array.isArray(value)) return value.map(toSnake);
  if (value instanceof Uint8Array) return value;
  if (value && typeof value === "object") {
    return Object.fromEntries(
      Object.entries(value).map(([key, item]) => [
        key.replace(/[A-Z]/g, (ch) => `_${ch.toLowerCase()}`),
        toSnake(item),
      ]),
    );
  }
  return value;
}

export class XChatClient {
  constructor(accessToken) {
    this.client = new Client({ accessToken });
    this.accessToken = accessToken;
  }

  async getMyUserId() {
    const resp = await this.client.users.getMe();
    return String(resp.data.id);
  }

  /**
   * Fetch a user's registered public keys (for ECIES + verification, or to
   * check your own before registering).
   *
   * Every field of the public_key resource (public_key, signing_public_key,
   * identity_public_key_signature, public_key_version, juicebox_config) is
   * always included; the route takes no public_key.fields parameter.
   */
  async getPublicKeys(userId) {
    const resp = await this.client.users.getPublicKey(userId);
    const data = resp.data ?? [];
    return Array.isArray(data) ? data : [data];
  }

  /**
   * Raised when the public-key write bucket is exhausted (HTTP 429).
   *
   * The endpoint allows only a few writes per 24h; `resetEpoch` is when the
   * window frees up. Retrying before then just fails again.
   */
  static RateLimited = class RateLimited extends Error {
    constructor(resetEpoch) {
      super("public-key registration rate limited (HTTP 429)");
      this.name = "RateLimited";
      this.resetEpoch = resetEpoch;
    }
  };

  /**
   * Register a public key: POST /2/users/{id}/public_keys.
   *
   * `payload` is the registration object from `generateKeypairs` in its
   * snake_case wire form (the `public_key` object).
   * Sent with a direct fetch — chat auth is a plain OAuth2 bearer token, so
   * this is equivalent to what the XDK would send. Throws `RateLimited` on 429
   * so the caller can stop instead of burning the strict daily budget.
   */
  async addUserPublicKey(userId, payload) {
    const resp = await fetch(`${BASE_URL}/2/users/${encodeURIComponent(userId)}/public_keys`, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${this.accessToken}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(payload),
    });
    if (resp.status === 429) {
      const reset = resp.headers.get("x-user-limit-24hour-reset");
      throw new XChatClient.RateLimited(reset ? Number(reset) : null);
    }
    if (!resp.ok) {
      throw new Error(`add public key failed: HTTP ${resp.status} ${await resp.text()}`);
    }
    const text = await resp.text();
    return text ? JSON.parse(text) : {};
  }

  /**
   * Build the Juicebox config JSON + latest key version for `unlock`/`setup`.
   *
   * The browser-safe WASM binding has no key export, so the registration
   * example persists the identity in Juicebox rather than a local blob; this
   * fetches the `juicebox_config` object the SDK needs to reach the realms.
   */
  async getJuiceboxConfig(userId) {
    const resp = await this.client.users.getPublicKey(userId);
    const data = resp.data ?? [];
    const items = Array.isArray(data) ? data : [data];
    const versionOf = (d) => Number(d.publicKeyVersion ?? d.public_key_version ?? 0);
    const latest = items.reduce(
      (best, d) => (versionOf(d) >= versionOf(best) ? d : best),
      items[0] ?? {},
    );
    const config = latest.juiceboxConfig ?? latest.juicebox_config;
    if (!config) {
      throw new Error(
        "no juicebox_config on the account yet. It is created by " +
          "POST /2/users/:id/public_keys, so register a public key first — " +
          "src/register.mjs does this: createChat with no config, " +
          "generateKeypairs, POST, then updateConfig + setup(pin). Once " +
          "provisioned, juicebox_config is always returned.",
      );
    }
    // Passed to the SDK as-is: it reads `key_store_token_map_json` verbatim.
    return {
      configJson: JSON.stringify(config),
      version: String(latest.publicKeyVersion ?? latest.public_key_version ?? ""),
    };
  }

  /** GET the raw (encrypted) events for a conversation. */
  async getEvents(conversationId, { maxResults = 50, paginationToken } = {}) {
    return this.client.chat.getConversationEvents(conversationId.replaceAll(":", "-"), {
      maxResults,
      paginationToken,
    });
  }

  /** POST an encrypted message produced by ChatCore.encryptReply. */
  async sendMessage(conversationId, body) {
    return this.client.chat.sendMessage(conversationId.replaceAll(":", "-"), {
      messageId: body.message_id,
      encodedMessageCreateEvent: body.encoded_message_create_event,
      encodedMessageEventSignature: body.encoded_message_event_signature,
      xdkVersion: body.xdk_version,
      conversationToken: body.conversation_token,
    });
  }

  // -- Conversation / key management ----------------------------------------

  /**
   * POST a prepared conversation-key change (initialize or rotate).
   * `body` is the request shape built by `prepToRequest`. For a 1:1,
   * `conversationId` may be the recipient's user ID; the server derives
   * (and returns) the canonical conversation ID.
   */
  async addConversationKeys(conversationId, body) {
    return this.client.chat.addConversationKeys(
      conversationId.replaceAll(":", "-"),
      body,
    );
  }

  /** Mint a new group conversation id (`g…`). */
  async initializeGroup() {
    const resp = await this.client.chat.initializeGroup();
    return String(resp.data?.conversationId ?? "");
  }

  /**
   * Create a group conversation. `body` carries `conversationId`,
   * `groupMembers`, `groupAdmins`, and the two-signature key change from
   * `ChatCore.prepareGroupCreate`.
   */
  async createConversation(body) {
    return this.client.chat.createConversation(body);
  }

  /**
   * Add members to a group. `body` carries `userIds` plus the rotated key
   * change from `ChatCore.prepareGroupMembersChange`.
   */
  async addGroupMembers(conversationId, body) {
    return this.client.chat.addGroupMembers(conversationId, body);
  }

  /**
   * Remove members from a group. `body` is the camelCase shape from
   * `removalToRequest`: `userIds`, both `actionSignatures`, and
   * `groupKeyRotationData`. The published XDK client has no method for
   * `POST /2/chat/conversations/{id}/members/remove`, so this posts the
   * snake_case wire body directly.
   */
  async removeGroupMembers(conversationId, body) {
    const wire = {
      user_ids: body.userIds,
      action_signatures: toSnake(body.actionSignatures),
      group_key_rotation_data: {
        conversation_key_version: body.groupKeyRotationData.conversationKeyVersion,
        conversation_participant_keys: toSnake(body.groupKeyRotationData.conversationParticipantKeys),
      },
    };
    const resp = await fetch(
      `${BASE_URL}/2/chat/conversations/${encodeURIComponent(conversationId)}/members/remove`,
      {
        method: "POST",
        headers: {
          Authorization: `Bearer ${this.accessToken}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify(wire),
      },
    );
    if (!resp.ok) {
      throw new Error(`remove group members failed: HTTP ${resp.status} ${await resp.text()}`);
    }
    const text = await resp.text();
    return text ? JSON.parse(text) : {};
  }

  // -- Media (encrypted files) ------------------------------------------------

  static UPLOAD_CHUNK = 3 * 1024 * 1024;

  /**
   * Start an upload; returns `{ sessionId, mediaHashKey }`.
   *
   * `totalBytes` is the encrypted size, `ChatCore.encryptedFileSize` of the
   * plaintext size. The media hash key names the file in the message's
   * attachments; encrypt the file once the message is built, then
   * `finishMediaUpload`. The media endpoints take the colon form of the
   * conversation id in the body.
   */
  async startMediaUpload(conversationId, totalBytes) {
    const conv = conversationId.replaceAll("-", ":");
    const init = await this.client.chat.mediaUploadInitialize({
      conversationId: conv,
      totalBytes,
    });
    const sessionId = init.data?.sessionId ?? init.data?.session_id;
    const mediaHashKey = init.data?.mediaHashKey ?? init.data?.media_hash_key;
    if (!sessionId || !mediaHashKey) {
      throw new Error(`media upload initialize failed: ${JSON.stringify(init)}`);
    }
    return { sessionId: String(sessionId), mediaHashKey: String(mediaHashKey) };
  }

  /** Upload the encrypted file in 3 MB segments, then finalize. */
  async finishMediaUpload(conversationId, { sessionId, mediaHashKey }, ciphertext) {
    const conv = conversationId.replaceAll("-", ":");
    let segment = 0;
    for (let offset = 0; offset < ciphertext.length; offset += XChatClient.UPLOAD_CHUNK) {
      const chunk = ciphertext.subarray(offset, offset + XChatClient.UPLOAD_CHUNK);
      await this.client.chat.mediaUploadAppend(sessionId, {
        conversationId: conv,
        mediaHashKey,
        segmentIndex: String(segment),
        media: Buffer.from(chunk).toString("base64"),
      });
      segment++;
    }

    await this.client.chat.mediaUploadFinalize(sessionId, {
      conversationId: conv,
      mediaHashKey,
      numParts: String(segment),
    });
  }

  /**
   * Download an encrypted media blob as raw bytes.
   *
   * Uses fetch directly: the body is binary ciphertext and must be read as
   * an ArrayBuffer — any text decoding corrupts bytes above 0x7f. The
   * download path takes the hyphen form of the conversation id.
   */
  async downloadMedia(conversationId, mediaHashKey) {
    const conv = encodeURIComponent(conversationId.replaceAll(":", "-"));
    const hashKey = encodeURIComponent(mediaHashKey);
    const resp = await fetch(`${BASE_URL}/2/chat/media/${conv}/${hashKey}`, {
      headers: { Authorization: `Bearer ${this.accessToken}` },
    });
    if (!resp.ok) {
      throw new Error(`media download failed: HTTP ${resp.status}`);
    }
    return new Uint8Array(await resp.arrayBuffer());
  }
}