@eryxenx/insta-chat 2.1.2 → 2.2.0

package/CHANGELOG.md

@@ -6,6 +6,43 @@ The format follows [Keep a Changelog](https://keepachangelog.com/) and uses
 
 ## [Unreleased]
 
+## [2.2.0] - 2026-11-06
+
+### Added
+
+- **Push/poller id reconciliation (`src/realtime/reconcile.js`).** The realtime
+  push and the inbox poll name the same DM differently — the poller uses the
+  message mid (`mid.$...`), the push carries the numeric `item_id` and, when the
+  broker includes it, the same mid. `buildKeys()` returns every key a message can
+  be recognised by and `MessageDeduper` drops the second copy, so both paths can
+  run at once without the bot replying twice. Exposed as
+  `require("@eryxenx/insta-chat").reconcile`.
+- **`InboxMethods.startSafetyPoll(callback, intervalMs)`.** Runs the inbox poll on
+  its own timer with its own 429 backoff, independently of the realtime listener,
+  so a caller can keep a warm polling fallback under a push path. Returns a cancel
+  function. With realtime on, `listen()` now uses it internally instead of relying
+  on the pre-subscribe fallback alone.
+- **`InstaClient.resolveThreadID()` / `InboxMethods.getThreadIdMap()`.** The push
+  names a thread by its internal `thread_id`; the poller, thread-detail read and
+  commands use the inbox id. The map is learned from every inbox snapshot so a
+  pushed event can be rewritten to the id the rest of the bot uses.
+- **`bridge` and `reconcile` are exported** from the package root for consumers
+  that build their own listener.
+
+### Fixed
+
+- **One MQTT connection per session, shared by every consumer.** Instagram's
+  broker routes the Direct message-sync stream to a single subscriber per device
+  id, so a second connection with the same device id silently takes the stream
+  away from the first — the "connects and subscribes but receives nothing"
+  deafness. `realtimeConnect()` and `sharedRealtimeClient()` now return the same
+  live client and serialise concurrent connects, so the inbox listener and the
+  reaction push ride one connection instead of two.
+- **`normalizeEvent` no longer blocks on a live `getUserInfo()`.** The sender-name
+  lookup used to make a rate-limited REST round trip on the critical path before
+  every command. It now prefers the name the client already learned from the
+  inbox/thread views and only falls back to the live call.
+
 ## [2.1.2] - 2026-11-06
 
 ### Fixed

package/index.js

@@ -113,5 +113,7 @@ module.exports.constants = constants;
 module.exports.moduleLogin = moduleLogin;
 module.exports.RealtimeClient = RealtimeClient;
 module.exports.RealtimeListener = RealtimeListener;
+module.exports.reconcile = require("./src/realtime/reconcile");
+module.exports.bridge = require("./src/realtime/bridge");
 module.exports.antiSuspension = require("./src/utils/antiSuspension");
 module.exports.sessionGuard = require("./src/utils/sessionGuard");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eryxenx/insta-chat",
-  "version": "2.1.2",
+  "version": "2.2.0",
   "description": " Unofficial Instagram Chat API for Node.js | Build Instagram DM bots on personal accounts — send messages, media, voice notes, reactions, edit & unsend, listen for incoming chats. No browser at runtime",
   "main": "index.js",
   "types": "index.d.ts",
@@ -23,7 +23,7 @@
     "CHANGELOG.md"
   ],
   "scripts": {
-    "test": "node test/smoke.js && node test/antiSuspension.test.js && node test/replyContent.test.js && node test/edit.test.js && node test/sendReply.test.js && node test/client.test.js && node test/relayError.test.js && node test/safetyWiring.test.js && node test/mediaOrder.test.js && node test/sessionSafety.test.js && node test/emptySend.test.js && node test/pollFloor.test.js && node test/userLookup.test.js && node test/profile.test.js && node test/unsend.test.js && node test/unsendGraphQL.test.js && node test/realtime.test.js",
+    "test": "node test/smoke.js && node test/antiSuspension.test.js && node test/replyContent.test.js && node test/edit.test.js && node test/sendReply.test.js && node test/client.test.js && node test/relayError.test.js && node test/safetyWiring.test.js && node test/mediaOrder.test.js && node test/sessionSafety.test.js && node test/emptySend.test.js && node test/pollFloor.test.js && node test/userLookup.test.js && node test/profile.test.js && node test/unsend.test.js && node test/unsendGraphQL.test.js && node test/realtime.test.js && node test/reconcile.test.js && node test/hybridSafetyPoll.test.js",
     "build": "node scripts/build.js"
   },
   "keywords": [

package/src/api.js

@@ -51,7 +51,13 @@ class InstaAPI {
     this.inbox = new InboxMethods(this.http, () => this.userID, {
       minPollIntervalMs: options.minPollIntervalMs,
       identity: this.identity,
-      realtime: options.realtime
+      realtime: options.realtime,
+      // Both the inbox listener and a caller that wants reaction/typing push
+      // (e.g. a bot's reaction watcher) must share one MQTT connection: the
+      // broker delivers the Direct message-sync stream to only the most-recent
+      // subscriber on a session, so a second connection with the same device id
+      // silently steals the stream from the first.
+      getSharedClient: () => this.sharedRealtimeClient()
     });
     this.media = new MediaMethods(this.http, this.identity);
 
@@ -310,6 +316,11 @@ class InstaAPI {
     return this.inbox.getInbox(cursor);
   }
 
+  // internal thread_id -> inbox thread id, learned from every inbox snapshot.
+  getThreadIdMap() {
+    return this.inbox.getThreadIdMap();
+  }
+
   listen(callback, intervalMs) {
     return this.inbox.listen(callback, intervalMs || this.options.pollInterval);
   }
@@ -338,19 +349,33 @@ class InstaAPI {
   }
 
   async realtimeConnect(options = {}) {
-    // A dropped client stays on the instance until something replaces it; reuse
-    // it only while it is actually connected, otherwise the caller gets a dead
-    // client back and believes the reconnect succeeded (the watcher's flapping
-    // loop). A new RealtimeClient is cheap: the MQTT/TLS connection is made by
-    // connect().
-    if (!this._realtime || !this._realtime.connected) {
-      if (this._realtime) {
-        try { this._realtime.disconnect(); } catch (_) {}
-      }
-      this._realtime = this.realtimeClient(options);
+    return this.sharedRealtimeClient(options);
+  }
+
+  // The one MQTT client a session may keep open. Instagram's broker routes the
+  // Direct message-sync stream to a single subscriber per device id, so a second
+  // connection with the same id silently takes the stream away from the first —
+  // the "connects but receives nothing" deafness. Every internal consumer
+  // (listen(), the reaction push) shares this client instead of dialing its own.
+  // Rebuilt only when the previous one is gone or dropped. Concurrent callers
+  // (the listener and the watcher start together) share one connect().
+  async sharedRealtimeClient(options = {}) {
+    if (this._realtime && this._realtime.connected) return this._realtime;
+    if (this._realtimeConnecting) return this._realtimeConnecting;
+    if (this._realtime) {
+      try { this._realtime.disconnect(); } catch (_) {}
     }
-    await this._realtime.connect();
-    return this._realtime;
+    const client = this.realtimeClient(options);
+    this._realtime = client;
+    this._realtimeConnecting = (async () => {
+      try {
+        await client.connect();
+        return client;
+      } finally {
+        this._realtimeConnecting = null;
+      }
+    })();
+    return this._realtimeConnecting;
   }
 
   realtimeOn(event, handler) {

package/src/app/InstaClient.js

@@ -169,6 +169,22 @@ class InstaClient {
     return Array.isArray(members) ? members.slice() : [];
   }
 
+  // The realtime push names a thread by its internal thread_id; the poller,
+  // thread-detail read and frozen commands use the inbox id. Map one onto the
+  // other so a pushed event is handled with the same thread id the rest of the
+  // bot uses. An unknown id (the map is cold, or a brand-new thread) is returned
+  // unchanged.
+  resolveThreadID(threadID) {
+    const key = String(threadID);
+    if (this.api && typeof this.api.getThreadIdMap === "function") {
+      const mapped = this.api.getThreadIdMap().get(key);
+      if (mapped) return String(mapped);
+    }
+    const known = this._threadMembers.get(key);
+    if (known) return key;
+    return key;
+  }
+
   // Indexes one Instagram user record (inbox/thread shape: id, username,
   // full_name, interop_messaging_user_fbid, profile_pic_url) under every key a
   // command may look it up by.

package/src/events/normalizeEvent.js

@@ -79,11 +79,24 @@ class EventNormalizer {
     const senderID = String(raw.senderID || "");
     const body = raw.body || "";
 
-    let senderName = senderID;
-    try {
-      const u = await this.client.api.getUserInfo(senderID);
-      if (u) senderName = u.full_name || u.username || senderID;
-    } catch (_) {}
+    let senderName = raw.senderName || null;
+    // Prefer the name the client already learned from the inbox/thread views.
+    // A live getUserInfo() on the critical path is a web REST call Instagram
+    // answers with a 302/429 for this session, so it costs a round trip and then
+    // fails — and the command dispatch waits on it. The offline index is free.
+    if (!senderName && typeof this.client.getUserByUsername === "function") {
+      try {
+        const known = this.client.getUserByUsername(senderID);
+        if (known) senderName = known.full_name || known.username || null;
+      } catch (_) {}
+    }
+    if (!senderName) {
+      try {
+        const u = await this.client.api.getUserInfo(senderID);
+        if (u) senderName = u.full_name || u.username || null;
+      } catch (_) {}
+    }
+    if (!senderName) senderName = senderID;
 
     const event = {
       type: "message",

package/src/methods/inbox.js

@@ -31,12 +31,17 @@ class InboxMethods {
     this.identity = options.identity || {};
     // { enabled, fallback } — realtime is opt-in via listen(); see listen().
     this.realtimeOptions = options.realtime || null;
+    // Returns the session's single shared MQTT client (see InstaAPI). When
+    // present, listen() rides that connection instead of dialing its own, so a
+    // second consumer cannot steal the Direct stream from it.
+    this.getSharedClient = typeof options.getSharedClient === "function" ? options.getSharedClient : null;
     // Lowest poll interval listen() will honour, in ms. Instagram has no DM
     // push, so reply latency is bounded by one poll cycle. The 15000 default is
     // the conservative safe floor for a personal account; operators on a
     // residential/mobile proxy can lower it (e.g. 2000) for snappier replies.
     this.minPollIntervalMs = Math.max(2000, Number(options.minPollIntervalMs) || 15000);
     this._seen = new Map();
+    this._threadIdMap = new Map();
     this._pollTimer = null;
     this._selfFbid = null;
     // threadID -> participant igids from the latest inbox snapshot. The inbox
@@ -70,9 +75,28 @@ class InboxMethods {
       const tid = String(t.id || t.thread_id);
       if (tid) this._members.set(tid, (t.users || []).map((u) => String(u.id || u.pk)).filter(Boolean));
     }
+    this._learnThreadIds(threads);
     return { threads };
   }
 
+  // The realtime push names a thread by its internal `thread_id` (e.g.
+  // 340282366841710301244259277549563001902) while the poller, the thread-detail
+  // read and the frozen commands all use the inbox id (e.g. 1102531985914926).
+  // Learn the mapping from every inbox snapshot so the listener can hand the rest
+  // of the bot one consistent thread id.
+  _learnThreadIds(threads) {
+    for (const t of threads) {
+      const internal = t.thread_id != null ? String(t.thread_id) : null;
+      const inbox = t.id != null ? String(t.id) : (t.thread_fbid != null ? String(t.thread_fbid) : null);
+      if (internal && inbox) this._threadIdMap.set(internal, inbox);
+    }
+  }
+
+  // internal thread_id -> inbox thread id, from the latest inbox snapshot.
+  getThreadIdMap() {
+    return new Map(this._threadIdMap);
+  }
+
   // Participant igids for a thread, from the latest inbox snapshot.
   getThreadMemberIDs(threadID) {
     const members = this._members.get(String(threadID));
@@ -357,6 +381,11 @@ class InboxMethods {
           seqId: rtOpts.seqId,
           snapshotAtMs: rtOpts.snapshotAtMs,
           getRealtimeState: rtOpts.getRealtimeState || (() => this.fetchRealtimeState()),
+          // Share the session's single MQTT connection. A second connection on
+          // the same device id steals the Direct stream from the first, so the
+          // inbox listener and any other consumer (reaction push) must ride the
+          // same client.
+          getClient: rtOpts.getClient || (this.getSharedClient ? () => this.getSharedClient() : undefined),
           onReady: rtOpts.onReady,
           onError: (err) => {
             // Before the subscription is confirmed a failure means realtime is
@@ -386,6 +415,16 @@ class InboxMethods {
     return this._stopListen;
   }
 
+  // Runs the inbox poller as an independent stream, for a caller that uses
+  // realtime push as the primary path and wants a polling safety net beneath it
+  // (the broker can connect, subscribe, and then silently stop delivering). The
+  // poller keeps its own cursor and its own rate-limit backoff, so a 429 here
+  // does not disturb the push path. Returns a stop function. The caller is
+  // expected to dedupe events that both sources deliver.
+  startSafetyPoll(callback, intervalMs) {
+    return this._startPolling(callback, intervalMs);
+  }
+
   // The iris (Direct message-sync) subscription cursor: seq_id + snapshot time.
   // Read from the inbox query when it exposes them; otherwise the listener
   // connects without a subscription (a live message still opens the stream).

package/src/realtime/bridge.js

@@ -37,21 +37,32 @@ function rawEventFromMessageSync(event, selfId) {
   if (!match || !isMessagePatch(message.path, message.op)) return null;
 
   const threadID = String(match[1]);
-  const messageID = String(message.item_id || match[2]);
+  const itemID = String(message.item_id || match[2]);
+  // The poller names a message by its mid ("mid.$..."); the push carries the
+  // numeric item id and, when the broker includes it, the same mid. Prefer the
+  // mid so both sources produce the same messageID and a dedupe on it works.
+  const mid = message.message_id != null ? String(message.message_id) : null;
+  const messageID = mid || itemID;
 
   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;
+  // item_type is a number on the wire (text = 1) and a string elsewhere; treat
+  // only the known non-message kinds as non-actionable and everything else as
+  // text, so a numeric type is not misread as an attachment with no URL.
+  const rawType = message.item_type != null ? message.item_type : message.content_type;
+  const typeText = typeof rawType === "string" ? rawType.toLowerCase() : String(rawType ?? "");
+  if (/reaction|action_log|like|video_call/.test(typeText)) return null;
+  const isText = typeText === "" || typeText === "1" || typeText === "text" || typeText === "text_content";
+  const itemType = isText ? "text" : typeText;
 
   const body = message.text || message.text_body || "";
   let attachments = [];
-  if (itemType !== "text") {
+  if (!isText) {
     attachments = attachmentsFromContent(message.media || message.content || message);
   }
-  if (itemType !== "text" && attachments.length === 0) {
+  if (!isText && 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;
@@ -62,6 +73,8 @@ function rawEventFromMessageSync(event, selfId) {
     threadID,
     senderID,
     messageID,
+    itemID,
+    mid,
     body,
     attachments,
     itemType,

package/src/realtime/listener.js

@@ -55,15 +55,32 @@ class RealtimeListener {
 
   async start(callback) {
     this._callback = callback;
-    this._client = new RealtimeClient(this.context, this.options);
-    this._client.on("message", (event) => this._handleMessageSync(event));
-    this._client.on("error", (err) => this._emitError(err));
-    this._client.on("disconnected", () => {
+    // Prefer a caller-supplied client (the session's single shared MQTT
+    // connection). A second connection on the same device id silently steals the
+    // Direct message-sync stream from the first, so when one is offered we attach
+    // to it rather than dialing our own.
+    let owned = true;
+    if (typeof this.options.getClient === "function") {
+      this._client = await this.options.getClient();
+      owned = false;
+    } else {
+      this._client = new RealtimeClient(this.context, this.options);
+    }
+    this._owned = owned;
+
+    // Keep per-instance handler references so stop() can detach exactly its own
+    // listeners from a shared client without disturbing the other consumers.
+    this._onMessage = (event) => this._handleMessageSync(event);
+    this._onError = (err) => this._emitError(err);
+    this._onDisconnected = () => {
       this.connected = false;
       if (!this._stopped) this._emitError(new Error("Realtime MQTT connection closed"));
-    });
+    };
+    this._client.on("message", this._onMessage);
+    this._client.on("error", this._onError);
+    this._client.on("disconnected", this._onDisconnected);
 
-    await this._client.connect();
+    if (!this._client.connected) await this._client.connect();
     this.connected = true;
 
     const cursor = await this._resolveCursor();
@@ -79,7 +96,15 @@ class RealtimeListener {
   stop() {
     this._stopped = true;
     this.connected = false;
-    if (this._client) this._client.disconnect();
+    if (!this._client) return;
+    if (typeof this._client.removeListener === "function") {
+      if (this._onMessage) this._client.removeListener("message", this._onMessage);
+      if (this._onError) this._client.removeListener("error", this._onError);
+      if (this._onDisconnected) this._client.removeListener("disconnected", this._onDisconnected);
+    }
+    // Only tear down a connection this listener owns; a shared client belongs to
+    // the session and other consumers may still be using it.
+    if (this._owned !== false) this._client.disconnect();
   }
 }
 

package/src/realtime/reconcile.js

@@ -0,0 +1,135 @@
+/*!
+ * 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.
+ */
+
+// Id reconciliation between the two inbound sources.
+//
+// A Direct message reaches the bot twice: once on the realtime MQTT push (fast,
+// ~1s) and once on the next inbox poll (the safety net). The two name the same
+// message differently:
+//
+//   poller  node.id            = "mid.$cAH8..."   (Instagram's mid)
+//   push    item value.item_id = "330934783..."   (the numeric item id)
+//   push    item value.message_id = "mid.$..."    (the mid, when the broker sends it)
+//
+// So a dedupe keyed on one id alone would treat the two copies as two messages
+// and the bot would reply twice. buildKeys() returns every key a message can be
+// recognised by, and MessageDeduper treats two arrivals as the same message when
+// any key matches. The content fingerprint (thread + sender + body + a coarse
+// timestamp bucket) is the fallback for a push payload that omits the mid.
+
+"use strict";
+
+const crypto = require("crypto");
+
+const MID_RE = /^mid\./;
+// Instagram timestamps appear in ms (13 digits) and microseconds (16 digits).
+function toMillis(ts) {
+  const n = Number(ts);
+  if (!Number.isFinite(n) || n <= 0) return 0;
+  return n > 1e14 ? Math.round(n / 1000) : Math.round(n);
+}
+
+function sha1(text) {
+  return crypto.createHash("sha1").update(String(text)).digest("hex").slice(0, 16);
+}
+
+// The mid, from whichever field the source used. A poller node exposes it as
+// `id`; a push item may expose `message_id`, `mid` or an item_id shaped like one.
+function extractMid(source = {}) {
+  const candidates = [source.messageID, source.message_id, source.mid, source.item_id, source.itemID, source.id];
+  for (const c of candidates) {
+    if (c != null && MID_RE.test(String(c))) return String(c);
+  }
+  return null;
+}
+
+// The numeric item id, from whichever field the source used.
+function extractItemId(source = {}) {
+  const candidates = [source.item_id, source.itemID, source.id, source.messageID, source.message_id];
+  for (const c of candidates) {
+    if (c != null && /^\d+$/.test(String(c))) return String(c);
+  }
+  return null;
+}
+
+// Every key an inbound message can be recognised by. `timestamp` may be in ms or
+// microseconds; the fingerprint bucket normalises it and tolerates ~1s of skew
+// between the push and the poll.
+function buildKeys(msg = {}) {
+  const keys = new Set();
+  const threadID = msg.threadID != null ? String(msg.threadID) : "";
+  const senderID = msg.senderID != null ? String(msg.senderID) : "";
+
+  const mid = extractMid(msg);
+  if (mid) keys.add(`mid:${mid}`);
+  const itemID = extractItemId(msg);
+  if (itemID) keys.add(`item:${itemID}`);
+  if (msg.offlineThreadingId != null && String(msg.offlineThreadingId)) {
+    keys.add(`otd:${msg.offlineThreadingId}`);
+  }
+
+  // Content fingerprint, only when there is a sender and a body: two genuinely
+  // different messages from the same sender rarely share a body in the same
+  // second, and without it a push that carries no mid could never be matched to
+  // its poller copy.
+  const body = msg.body == null ? "" : String(msg.body);
+  if (threadID && senderID && body) {
+    const bucket = Math.floor(toMillis(msg.timestamp) / 1000);
+    keys.add(`fp:${sha1(`${threadID}|${senderID}|${body}|${bucket}`)}`);
+  }
+  return keys;
+}
+
+// Sliding window of recently-seen message keys. Bounded so a long-running bot
+// does not grow it without limit.
+class MessageDeduper {
+  constructor({ ttlMs = 10 * 60 * 1000, max = 5000 } = {}) {
+    this.ttlMs = ttlMs;
+    this.max = max;
+    this._seen = new Map(); // key -> seenAt
+  }
+
+  _prune(now) {
+    for (const [key, at] of this._seen) {
+      if (now - at > this.ttlMs) this._seen.delete(key);
+    }
+    while (this._seen.size > this.max) {
+      const oldest = this._seen.keys().next().value;
+      this._seen.delete(oldest);
+    }
+  }
+
+  has(keys) {
+    const now = Date.now();
+    this._prune(now);
+    for (const key of keys) if (this._seen.has(key)) return true;
+    return false;
+  }
+
+  add(keys) {
+    const now = Date.now();
+    for (const key of keys) this._seen.set(key, now);
+    this._prune(now);
+  }
+
+  // true when the message is new (and records it), false when it is a duplicate.
+  accept(keys) {
+    if (this.has(keys)) return false;
+    this.add(keys);
+    return true;
+  }
+
+  clear() {
+    this._seen.clear();
+  }
+
+  get size() {
+    return this._seen.size;
+  }
+}
+
+module.exports = { buildKeys, extractMid, extractItemId, toMillis, MessageDeduper };

package/src/utils/antiSuspension.js

@@ -243,9 +243,12 @@ class SendPacer extends EventEmitter {
     const sinceGlobal = now - this.lastSendAt;
     const sinceThread = now - (this.perThreadLastSendAt.get(key) || 0);
     const base = Math.max(gap - sinceGlobal, this.perThreadMinGapMs - sinceThread, 0);
-    const jitter = this.jitterMs > 0 ? this.jitterMs * (0.3 + Math.random() * 0.7) : 0;
+    // Jitter only breaks up back-to-back sends. When nothing is queued (the first
+    // reply to a message after a quiet spell) base is 0 and the send goes out
+    // immediately, instead of always paying 0.3-1.0x jitterMs.
+    const jitter = base > 0 && this.jitterMs > 0 ? this.jitterMs * (0.3 + Math.random() * 0.7) : 0;
 
-    await this._sleep(base + jitter);
+    if (base + jitter > 0) await this._sleep(base + jitter);
 
     const stamp = Date.now();
     this.lastSendAt = stamp;