@eryxenx/insta-chat 2.0.11 → 2.1.0

package/src/profileParse.js

@@ -0,0 +1,250 @@
+/*!
+ * insta-chat - Unofficial Instagram Chat API
+ * Copyright (c) 2026 EryXenX (https://github.com/EryXenX)
+ * Licensed under the Apache License, Version 2.0. See LICENSE and NOTICE.
+ * Original author credit must be retained in all copies and derivatives.
+ */
+
+// Parsers for the two profile sources this package can read with a web session:
+//
+//  1. /api/v1/users/web_profile_info/ - the canonical profile JSON
+//     (`data.user` with edge_followed_by.count, biography, is_verified, ...).
+//  2. the profile page HTML - www.instagram.com/<username>/ embeds a
+//     `["PolarisViewer",[],{"data":{...}}]` blob with biography, full_name,
+//     profile_pic_url_hd and the account flags, but no follower counts.
+//
+// Both are normalized to one rich object so callers never branch on the source.
+// The /api/v1/users/<id>/info/ REST path is deliberately not used: for a web
+// session Instagram 302s it to the login page (which the HTTP layer reads as an
+// expired session) or 429s it.
+
+// Walks a JSON object literal starting at the first `{` at/after `from`,
+// honouring strings and escapes, and returns the parsed value (or null).
+function parseJsonAt(text, from) {
+  let i = text.indexOf("{", from);
+  if (i < 0) return null;
+  const start = i;
+  let depth = 0;
+  let inStr = false;
+  let esc = false;
+  for (; i < text.length; i++) {
+    const c = text[i];
+    if (inStr) {
+      if (esc) esc = false;
+      else if (c === "\\") esc = true;
+      else if (c === '"') inStr = false;
+      continue;
+    }
+    if (c === '"') inStr = true;
+    else if (c === "{") depth++;
+    else if (c === "}") {
+      depth--;
+      if (depth === 0) {
+        try {
+          return JSON.parse(text.slice(start, i + 1));
+        } catch (_) {
+          return null;
+        }
+      }
+    }
+  }
+  return null;
+}
+
+function countOf(edge) {
+  const n = edge && edge.count;
+  return Number.isFinite(Number(n)) ? Number(n) : null;
+}
+
+// Accepts either a Relay field-count edge (`{ count: n }`) or a plain number.
+function countOrEdge(v) {
+  if (v == null) return null;
+  if (typeof v === "object") return countOf(v);
+  return Number.isFinite(Number(v)) ? Number(v) : null;
+}
+
+// Maps a web_profile_info `data.user` (REST) to the normalized shape.
+function normalizeWebProfileInfo(user) {
+  if (!user || typeof user !== "object") return null;
+  return normalize({
+    id: user.id || user.pk,
+    username: user.username,
+    fullName: user.full_name,
+    biography: user.biography,
+    externalUrl: user.external_url,
+    category: user.category_name || user.category,
+    isVerified: user.is_verified,
+    isPrivate: user.is_private,
+    isBusinessAccount: user.is_business_account,
+    isProfessionalAccount: user.is_professional_account,
+    profilePicUrl: user.profile_pic_url,
+    profilePicUrlHd: user.profile_pic_url_hd || user.profile_pic_url,
+    fbid: user.fbid,
+    followerCount: countOf(user.edge_followed_by),
+    followingCount: countOf(user.edge_follow),
+    mediaCount: countOf(user.edge_owner_to_timeline_media),
+    highlightReelCount: user.highlight_reel_count,
+    businessEmail: user.business_email,
+    businessPhone: user.business_phone_number,
+    publicEmail: user.public_email,
+    publicPhone: user.public_phone_number,
+    hasProfilePic: user.has_profile_pic,
+    raw: user
+  });
+}
+
+// Maps the GraphQL profile response (`data.user` from PolarisProfilePageContent-
+// Query / PolarisUserRootQuery) to the normalized shape. The field names are the
+// Relay ones, and the counts come back either as an edge or as a plain number,
+// so both are accepted.
+function normalizeGraphqlUser(user) {
+  if (!user || typeof user !== "object") return null;
+  const follower = user.follower_count ?? user.edge_followed_by;
+  const following = user.following_count ?? user.edge_follow;
+  const media = user.media_count ?? user.edge_owner_to_timeline_media;
+  return normalize({
+    id: user.id || user.pk || user.strong_id__,
+    username: user.username,
+    fullName: user.full_name,
+    biography: user.biography,
+    externalUrl: user.external_url || user.bio_links?.[0]?.url,
+    category: user.category_name || user.category,
+    isVerified: user.is_verified,
+    isPrivate: user.is_private,
+    isBusinessAccount: user.is_business_account,
+    isProfessionalAccount: user.is_professional_account,
+    profilePicUrl: user.profile_pic_url,
+    profilePicUrlHd: user.hd_profile_pic_url_info?.url || user.profile_pic_url_hd || user.profile_pic_url,
+    fbid: user.fbid,
+    followerCount: countOrEdge(follower),
+    followingCount: countOrEdge(following),
+    mediaCount: countOrEdge(media),
+    businessEmail: user.business_email,
+    businessPhone: user.business_phone_number,
+    publicEmail: user.public_email,
+    publicPhone: user.public_phone_number,
+    hasProfilePic: user.has_profile_pic ?? (!!user.profile_pic_url),
+    raw: user
+  });
+}
+
+// Maps the HTML-embedded PolarisViewer `data` to the normalized shape.
+function normalizePolarisViewer(data) {
+  if (!data || typeof data !== "object" || !data.username) return null;
+  return normalize({
+    id: data.id,
+    username: data.username,
+    fullName: data.full_name,
+    biography: data.biography,
+    externalUrl: data.external_url,
+    category: data.category_name,
+    isVerified: data.is_verified,
+    isPrivate: data.is_private,
+    isBusinessAccount: data.is_business_account,
+    isProfessionalAccount: data.is_professional_account,
+    profilePicUrl: data.profile_pic_url,
+    profilePicUrlHd: data.profile_pic_url_hd || data.profile_pic_url,
+    fbid: data.fbid,
+    hasProfilePic: data.has_profile_pic,
+    raw: data
+  });
+}
+
+// Maps an inbox/thread introspection user record (id, username, full_name,
+// profile_pic_url, is_verified, interop_messaging_user_fbid) to the normalized
+// shape. This is the data the DM GraphQL surface reliably returns for the
+// people a bot actually talks to, when the profile REST paths rate-limit.
+function normalizeInboxUser(u) {
+  if (!u || typeof u !== "object") return null;
+  const username = u.username || null;
+  const id = u.id || u.pk || u.interop_messaging_user_fbid || null;
+  if (!username && !id) return null;
+  return normalize({
+    id,
+    username,
+    fullName: u.full_name,
+    profilePicUrl: u.profile_pic_url,
+    profilePicUrlHd: u.profile_pic_url_hd || u.profile_pic_url,
+    isVerified: u.is_verified,
+    isPrivate: u.is_private,
+    fbid: u.interop_messaging_user_fbid,
+    raw: u
+  });
+}
+
+// Pulls the profile out of a profile page's HTML. Returns null when the page is
+// a login wall or carries no profile blob. `expectUsername`, when given, guards
+// against the SPA shell embedding the *viewer's* profile for a page Instagram
+// did not server-render: the blob is only trusted when it is the requested user.
+function parseProfilePage(html, expectUsername) {
+  const text = typeof html === "string" ? html : "";
+  if (!text || /accounts\/login/i.test(text.slice(0, 2000))) return null;
+  for (const marker of ['"PolarisViewer",[],', '"PolarisProfilePageContentQuery"']) {
+    const at = text.indexOf(marker);
+    if (at < 0) continue;
+    const obj = parseJsonAt(text, at + marker.length);
+    const data = obj && (obj.data || obj);
+    const profile = normalizePolarisViewer(data);
+    if (!profile) continue;
+    if (expectUsername && String(profile.username).toLowerCase() !== String(expectUsername).toLowerCase()) {
+      continue;
+    }
+    return profile;
+  }
+  return null;
+}
+
+// The single normalized profile shape every source maps to. Fields a source
+// cannot supply stay null, so a caller can tell "unknown" from "false".
+function normalize(p) {
+  if (!p) return null;
+  const id = p.id != null ? String(p.id) : null;
+  return {
+    id,
+    pk: id,
+    username: p.username || null,
+    fullName: p.fullName || null,
+    biography: p.biography || "",
+    externalUrl: p.externalUrl || null,
+    category: p.category || null,
+    isVerified: p.isVerified === true,
+    isPrivate: p.isPrivate === true,
+    isBusinessAccount: p.isBusinessAccount === true,
+    isProfessionalAccount: p.isProfessionalAccount === true,
+    hasProfilePic: p.hasProfilePic === true,
+    profilePicUrl: p.profilePicUrl || null,
+    profilePicUrlHd: p.profilePicUrlHd || p.profilePicUrl || null,
+    fbid: p.fbid != null ? String(p.fbid) : null,
+    followerCount: p.followerCount != null ? p.followerCount : null,
+    followingCount: p.followingCount != null ? p.followingCount : null,
+    mediaCount: p.mediaCount != null ? p.mediaCount : null,
+    highlightReelCount: p.highlightReelCount != null ? p.highlightReelCount : null,
+    businessEmail: p.businessEmail || null,
+    businessPhone: p.businessPhone || null,
+    publicEmail: p.publicEmail || null,
+    publicPhone: p.publicPhone || null,
+    raw: p.raw || null
+  };
+}
+
+// Instagram's CDN resizes a profile picture from the URL's stp= parameter. This
+// returns the same picture at a requested square size, so callers get a crisp
+// avatar without a second API call.
+function profilePictureAtSize(url, size) {
+  if (!url || !size) return url;
+  const px = Math.max(1, Math.round(Number(size) || 0));
+  if (!px) return url;
+  const stp = `dst-jpg_s${px}x${px}_tt6`;
+  if (/[?&]stp=[^&]+/.test(url)) return url.replace(/([?&])stp=[^&]+/, `$1stp=${stp}`);
+  return `${url}${url.includes("?") ? "&" : "?"}stp=${stp}`;
+}
+
+module.exports = {
+  parseProfilePage,
+  normalizeWebProfileInfo,
+  normalizeGraphqlUser,
+  normalizePolarisViewer,
+  normalizeInboxUser,
+  normalize,
+  profilePictureAtSize
+};

package/src/realtime/bridge.js

@@ -0,0 +1,76 @@
+/*!
+ * insta-chat - Unofficial Instagram Chat API
+ * Copyright (c) 2026 EryXenX (https://github.com/EryXenX)
+ * Licensed under the Apache License, Version 2.0. See LICENSE and NOTICE.
+ * Original author credit must be retained in all copies and derivatives.
+ */
+
+// Turns a realtime MQTT message-sync patch into the same raw inbox event the
+// poller produces, so listen() can hand either source to the same callback and
+// the EventNormalizer never needs to know which one delivered it.
+//
+// The broker pushes a patch per Direct change:
+//   { op: "add", path: "/direct_v2/threads/<tid>/items/<iid>",
+//     value: "<json item>" }
+// Only a new item under /items/ is an inbound message; activity indicators,
+// seen state and reactions share the /direct_v2/threads/ prefix and are ignored.
+
+"use strict";
+
+const { attachmentsFromContent } = require("../messageContent");
+
+const ITEM_PATH_RE = /^\/direct_v2\/threads\/([^/]+)\/items\/([^/]+)$/;
+
+function isMessagePatch(path, op) {
+  if (!ITEM_PATH_RE.test(String(path || ""))) return false;
+  // op is "add" for a new item; older captures omit it, so an absent op is fine.
+  return !op || String(op).toLowerCase() === "add";
+}
+
+// Builds a raw event from a message-sync patch, or null when the patch is not an
+// actionable inbound message (our own send, a reaction, a non-item change).
+function rawEventFromMessageSync(event, selfId) {
+  const message = event && event.message ? event.message : event;
+  if (!message || typeof message !== "object") return null;
+
+  const match = String(message.path || "").match(ITEM_PATH_RE);
+  if (!match || !isMessagePatch(message.path, message.op)) return null;
+
+  const threadID = String(match[1]);
+  const messageID = String(message.item_id || match[2]);
+
+  const senderID = message.user_id != null ? String(message.user_id) : null;
+  // The broker echoes our own sends back over message-sync; drop them.
+  if (senderID && selfId && senderID === String(selfId)) return null;
+
+  const itemType = String(message.item_type || message.content_type || "text").toLowerCase();
+  if (/reaction|action_log|like|video_call/.test(itemType)) return null;
+
+  const body = message.text || message.text_body || "";
+  let attachments = [];
+  if (itemType !== "text") {
+    attachments = attachmentsFromContent(message.media || message.content || message);
+  }
+  if (itemType !== "text" && attachments.length === 0) {
+    // The item carried no parseable media URL; let the normalizer/bot fetch the
+    // thread history instead of emitting a message with nothing actionable.
+    return null;
+  }
+
+  return {
+    type: "message",
+    threadID,
+    senderID,
+    messageID,
+    body,
+    attachments,
+    itemType,
+    repliedToItemId: message.replied_to_item_id || null,
+    repliedToMessage: null,
+    clientContext: message.client_context || null,
+    offlineThreadingId: message.offline_threading_id != null ? String(message.offline_threading_id) : null,
+    timestamp: Number(message.timestamp || message.timestamp_ms) || Date.now()
+  };
+}
+
+module.exports = { rawEventFromMessageSync, isMessagePatch, ITEM_PATH_RE };

package/src/realtime/client.js

@@ -0,0 +1,376 @@
+/*!
+ * insta-chat - Unofficial Instagram Chat API
+ * Copyright (c) 2026 EryXenX (https://github.com/EryXenX)
+ * Licensed under the Apache License, Version 2.0. See LICENSE and NOTICE.
+ * Original author credit must be retained in all copies and derivatives.
+ */
+
+// Instagram's realtime broker (edge-mqtt.facebook.com) speaks MQTToT with
+// cookie_auth: the CONNECT password is "sessionid=<sessionid>" and the session
+// cookie authenticates the connection, so no app login is needed. This client
+// keeps that connection open and turns the broker's Direct message-sync and
+// realtime-sub publishes into plain events.
+//
+// Message-sync (topic 146) is the Direct stream: the broker pushes Relay-style
+// patches ({ path: "/direct_v2/threads/<threadID>", op, value }) as messages
+// arrive, which is what makes listen() push instead of poll. Topics:
+//   88 pubsub · 133 send-response · 135 iris-sub-response
+//   146 message-sync · 149 realtime-sub · 150 region-hint
+
+"use strict";
+
+const { EventEmitter } = require("events");
+const crypto = require("crypto");
+
+const {
+  MQTToTConnection,
+  SocketMQTToTTransport,
+  compressPayload,
+  writeConnectPacket,
+  writeDisconnectPacket,
+  writePingreqPacket,
+  writePublishPacket,
+  writeSubscribePacket,
+  decodePacket,
+  tryDecompressPayload,
+  parseJsonPayload
+} = require("./mqttot");
+
+const REALTIME_HOST = "edge-mqtt.facebook.com";
+const IG_REALTIME_APP_ID = 567067343352427;
+const REALTIME_SUBSCRIBE_TOPICS = [88, 135, 149, 150, 133, 146];
+
+// An Android app identity. The broker expects the app's own UA + app version in
+// the CONNECT's appSpecificInfo; a web UA is rejected.
+const ANDROID_UA =
+  "Instagram 449.0.0.52.84 Android (34/14; 480dpi; 1344x2992; Google/google; Pixel 8 Pro; husky; husky; en_US; 1079242191)";
+const APP_VERSION = "449.0.0.52.84";
+const CAPABILITIES = "3brTv10=";
+const LOCALE = "en_US";
+
+const TOPICS = {
+  PUBSUB: "88",
+  SEND_MESSAGE: "132",
+  SEND_MESSAGE_RESPONSE: "133",
+  IRIS_SUB: "134",
+  IRIS_SUB_RESPONSE: "135",
+  MESSAGE_SYNC: "146",
+  REALTIME_SUB: "149",
+  REGION_HINT: "150"
+};
+
+class RealtimeClient extends EventEmitter {
+  constructor(context, options = {}) {
+    super();
+    this.context = context || {};
+    this.options = options;
+    this.host = options.host || REALTIME_HOST;
+    this.transport = options.transport || new SocketMQTToTTransport(this.host, 443, { timeout: options.socketTimeout || 30000 });
+    this.connected = false;
+    this._packetId = 0;
+    this._loop = null;
+    this._pingTimer = null;
+    this._stopRequested = false;
+  }
+
+  _deviceId() {
+    const id = this.context.deviceId || this.context.phoneId || this.context.uuid || "";
+    if (!id) throw new Error("realtime: deviceId is required");
+    return String(id);
+  }
+
+  _sessionId() {
+    const raw = this.context.sessionid;
+    if (!raw) throw new Error("realtime: sessionid is required");
+    // The browser stores the sessionid URL-encoded (32715034217%3A...); the
+    // broker wants the decoded value.
+    try {
+      return decodeURIComponent(String(raw));
+    } catch (_) {
+      return String(raw);
+    }
+  }
+
+  buildConnection() {
+    const deviceId = this._deviceId();
+    const userAgent = this.context.userAgent || ANDROID_UA;
+    const appVersion = this.context.appVersion || APP_VERSION;
+    return new MQTToTConnection({
+      clientIdentifier: deviceId.slice(0, 20),
+      clientInfo: {
+        userId: this.context.userId || 0,
+        userAgent,
+        clientCapabilities: 183,
+        endpointCapabilities: 0,
+        publishFormat: 1,
+        noAutomaticForeground: false,
+        makeUserAvailableInForeground: true,
+        deviceId,
+        isInitiallyForeground: true,
+        networkType: 1,
+        networkSubtype: 0,
+        clientMqttSessionId: Date.now() & 0xffffffff,
+        subscribeTopics: REALTIME_SUBSCRIBE_TOPICS,
+        clientType: "cookie_auth",
+        appId: IG_REALTIME_APP_ID,
+        deviceSecret: "",
+        clientStack: 3
+      },
+      password: `sessionid=${this._sessionId()}`,
+      appSpecificInfo: {
+        app_version: appVersion,
+        "X-IG-Capabilities": CAPABILITIES,
+        everclear_subscriptions: JSON.stringify({
+          inapp_notification_subscribe_comment: "17899377895239777",
+          inapp_notification_subscribe_comment_mention_and_reply: "17899377895239777",
+          video_call_participant_state_delivery: "17977239895057311",
+          presence_subscribe: "17846944882223835"
+        }),
+        "User-Agent": userAgent,
+        "Accept-Language": LOCALE.replace("_", "-"),
+        platform: "android",
+        ig_mqtt_route: "django",
+        pubsub_msg_type_blacklist: "direct, typing_type",
+        auth_cache_enabled: "0"
+      }
+    });
+  }
+
+  async connect() {
+    if (this.connected) return this;
+    await this.transport.connect();
+    await this.transport.send(writeConnectPacket(this.buildConnection()));
+    const packet = decodePacket(await this.transport.recvPacket());
+    if (packet.packetType !== "connack" || packet.returnCode !== 0) {
+      throw new Error(`Realtime MQTT connect failed (return code ${packet.returnCode})`);
+    }
+    this.connected = true;
+    this._stopRequested = false;
+    this.emit("connected", { host: this.host });
+    this._startPing();
+    this._startLoop();
+    return this;
+  }
+
+  _startPing() {
+    const keepAliveMs = this.options.keepAliveMs || 30000;
+    this._pingTimer = setInterval(() => {
+      if (this.connected) this.transport.send(writePingreqPacket()).catch(() => {});
+    }, keepAliveMs);
+    if (this._pingTimer.unref) this._pingTimer.unref();
+  }
+
+  _startLoop() {
+    this._loop = (async () => {
+      while (this.connected) {
+        let packet;
+        try {
+          packet = decodePacket(await this.transport.recvPacket());
+        } catch (err) {
+          if (!this._stopRequested) this.emit("error", err);
+          break;
+        }
+        try {
+          this._handlePacket(packet);
+        } catch (err) {
+          this.emit("error", err);
+        }
+      }
+      this.connected = false;
+      this.emit("disconnected", {});
+    })();
+  }
+
+  _handlePacket(packet) {
+    if (packet.packetType !== "publish" || packet.topic == null) return;
+    this.dispatch(packet.topic, packet.payload);
+    if (packet.qos === 1 && packet.packetId != null) {
+      this.transport.send(Buffer.concat([Buffer.from([0x40, 0x02]), uint16(packet.packetId)])).catch(() => {});
+    }
+  }
+
+  dispatch(topic, payload) {
+    const body = tryDecompressPayload(payload);
+    let parsed;
+    if (
+      topic === TOPICS.SEND_MESSAGE_RESPONSE ||
+      topic === TOPICS.IRIS_SUB_RESPONSE ||
+      topic === TOPICS.REALTIME_SUB ||
+      topic === TOPICS.MESSAGE_SYNC
+    ) {
+      parsed = safeJson(body);
+    } else {
+      parsed = safeJson(payload);
+    }
+    this.emit("receive", { topic, payload: parsed });
+    if (topic === TOPICS.SEND_MESSAGE_RESPONSE) this.emit("send_response", parsed);
+    if (topic === TOPICS.IRIS_SUB_RESPONSE) this.emit("iris_sub_response", parsed);
+    if (topic === TOPICS.MESSAGE_SYNC) this._dispatchMessageSync(parsed);
+    if (topic === TOPICS.REALTIME_SUB) this._dispatchRealtimeSub(parsed);
+    return parsed;
+  }
+
+  // message-sync payloads are a list of { data: [ { path, op, value } ] } patches.
+  _dispatchMessageSync(payload) {
+    if (!Array.isArray(payload)) return this.emit("iris", payload);
+    for (const item of payload) {
+      if (!item || typeof item !== "object" || !Array.isArray(item.data)) {
+        this.emit("iris", item);
+        continue;
+      }
+      const meta = {};
+      for (const [k, v] of Object.entries(item)) if (k !== "data") meta[k] = v;
+      for (const patch of item.data) {
+        if (!patch || typeof patch !== "object") continue;
+        const path = patch.path;
+        if (!path || patch.value == null) {
+          this.emit("iris", { ...meta, ...patch });
+          continue;
+        }
+        const value = parseMaybeJson(patch.value);
+        const threadID = threadIdFromPath(path);
+        const wrapped = {
+          ...meta,
+          message: {
+            path,
+            op: patch.op,
+            thread_id: threadID,
+            ...(value && typeof value === "object" ? value : { value })
+          }
+        };
+        this.emit(path.startsWith("/direct_v2/threads/") ? "message" : "thread_update", wrapped);
+        this._dispatchDirectEvent({ path, op: patch.op, value, threadID });
+      }
+    }
+  }
+
+  _dispatchRealtimeSub(payload) {
+    this.emit("realtime_sub", payload);
+    if (!payload || typeof payload !== "object") return;
+    let message = payload.message;
+    if (typeof message === "string") message = safeJson(Buffer.from(message));
+    if (!message || typeof message !== "object") return;
+    if (message.topic !== "direct") return;
+    let direct = message.json || message.payload;
+    if (typeof direct === "string") direct = safeJson(Buffer.from(direct));
+    this._dispatchDirectPayload(direct);
+  }
+
+  _dispatchDirectPayload(payload) {
+    if (!payload || typeof payload !== "object") return this._dispatchDirectEvent({ value: payload });
+    if (!Array.isArray(payload.data)) return this._dispatchDirectEvent(payload);
+    const meta = {};
+    for (const [k, v] of Object.entries(payload)) if (k !== "data") meta[k] = v;
+    for (const item of payload.data) {
+      this._dispatchDirectEvent(item && typeof item === "object" ? { ...meta, ...item } : { ...meta, value: item });
+    }
+  }
+
+  _dispatchDirectEvent(event) {
+    const out = { ...event };
+    let value = out.value;
+    if (typeof value === "string") value = safeJson(Buffer.from(value));
+    out.value = value;
+    if (out.path && !out.threadID) out.threadID = threadIdFromPath(out.path);
+    this.emit("direct", out);
+    const kind = classifyDirectEvent(out);
+    if (kind) this.emit(kind, out);
+  }
+
+  publishBytes(topic, payload) {
+    this._packetId += 1;
+    const packet = writePublishPacket(topic, payload, 1, this._packetId);
+    return this.transport.send(packet);
+  }
+
+  publishJson(topic, data) {
+    return this.publishBytes(topic, compressPayload(Buffer.from(JSON.stringify(data))));
+  }
+
+  irisSubscribe(seqId, snapshotAtMs, appVersion) {
+    return this.publishJson(TOPICS.IRIS_SUB, {
+      seq_id: seqId,
+      snapshot_at_ms: snapshotAtMs,
+      snapshot_app_version: appVersion || this.context.appVersion || APP_VERSION
+    });
+  }
+
+  graphQlSubscribe(subscriptions) {
+    return this.publishJson(TOPICS.REALTIME_SUB, { sub: [].concat(subscriptions) });
+  }
+
+  skywalkerSubscribe(subscriptions) {
+    return this.publishJson(TOPICS.PUBSUB, { sub: [].concat(subscriptions) });
+  }
+
+  async ping() {
+    if (!this.connected) throw new Error("Realtime client is not connected");
+    await this.transport.send(writePingreqPacket());
+    return true;
+  }
+
+  disconnect() {
+    this._stopRequested = true;
+    this.connected = false;
+    if (this._pingTimer) clearInterval(this._pingTimer);
+    this._pingTimer = null;
+    try { this.transport.send(writeDisconnectPacket()); } catch (_) {}
+    this.transport.disconnect();
+    return this;
+  }
+}
+
+// Extracts the thread id from a message-sync path such as
+// "/direct_v2/threads/1234/items/..." or "/direct_v2/inbox/threads/1234".
+function threadIdFromPath(path) {
+  const p = String(path || "");
+  let m = p.match(/^\/direct_v2\/threads\/([^/]+)/);
+  if (m) return m[1];
+  m = p.match(/^\/direct_v2\/inbox\/threads\/([^/]+)/);
+  if (m) return m[1];
+  return null;
+}
+
+function classifyDirectEvent(event) {
+  const path = String(event.path || "").toLowerCase();
+  const action = String(event.action || "").toLowerCase();
+  const value = event.value;
+  const valueText = value && typeof value === "object" ? JSON.stringify(value).toLowerCase() : String(value || "").toLowerCase();
+  if (valueText.includes("activity_status") || path.includes("activity_indicator") || path.includes("typing")) return "typing";
+  if (path.includes("presence") || valueText.includes("is_active") || valueText.includes("last_active")) return "presence";
+  if (action === "mark_seen" || path.includes("/seen") || valueText.includes("seen")) return "seen";
+  return null;
+}
+
+function parseMaybeJson(value) {
+  if (typeof value !== "string") return value;
+  const parsed = safeJson(Buffer.from(value));
+  return parsed === undefined ? value : parsed;
+}
+
+function safeJson(buffer) {
+  try {
+    return JSON.parse(buffer.toString("utf8"));
+  } catch (_) {
+    return buffer;
+  }
+}
+
+function uint16(value) {
+  const buf = Buffer.alloc(2);
+  buf.writeUInt16BE(value & 0xffff, 0);
+  return buf;
+}
+
+module.exports = {
+  RealtimeClient,
+  REALTIME_HOST,
+  IG_REALTIME_APP_ID,
+  REALTIME_SUBSCRIBE_TOPICS,
+  TOPICS,
+  ANDROID_UA,
+  APP_VERSION,
+  threadIdFromPath,
+  classifyDirectEvent,
+  newClientContext: () => crypto.randomUUID()
+};