nodejs-insta-private-api-mqtt 1.2.10 → 1.3.10

package/dist/useMultiFileAuthState.js

@@ -26,7 +26,16 @@ const FILE_NAMES = {
   // Added utility files
   loginHistory: 'login-history.json',
   usageStats: 'usage-stats.json',
-  accountsIndex: 'accounts.json'
+  accountsIndex: 'accounts.json',
+
+  // MQTT helpers files
+  mqttHealth: 'mqtt-health.json',
+  mqttReconnect: 'mqtt-reconnect.json',
+  mqttMessageCache: 'mqtt-message-cache.json',
+  mqttOutbox: 'mqtt-outbox.json',
+  mqttSubscriptionHealth: 'mqtt-subscription-health.json',
+  mqttTraffic: 'mqtt-traffic.json',
+  mqttRisk: 'mqtt-risk.json'
 };
 
 class MultiFileAuthState extends EventEmitter {
@@ -42,6 +51,11 @@ class MultiFileAuthState extends EventEmitter {
     this._autoRefreshIntervalMs = 5 * 60 * 1000; // default 5 minutes
     this._autoRefreshClient = null;
 
+    // Reconnect/backoff runtime
+    this._reconnectBackoff = [2000, 5000, 15000, 60000];
+    this._reconnectAttempts = 0;
+    this._reconnectTimer = null;
+
     this.data = {
       creds: null,
       device: null,
@@ -61,7 +75,16 @@ class MultiFileAuthState extends EventEmitter {
       // utility
       loginHistory: null,
       usageStats: null,
-      accountsIndex: null
+      accountsIndex: null,
+
+      // mqtt helpers
+      mqttHealth: null,
+      mqttReconnect: null,
+      mqttMessageCache: null,
+      mqttOutbox: null,
+      mqttSubscriptionHealth: null,
+      mqttTraffic: null,
+      mqttRisk: null
     };
 
     // ensure folder structure
@@ -90,6 +113,80 @@ class MultiFileAuthState extends EventEmitter {
     }
   }
 
+  // sanitize state to avoid nulls for key fields (useful to ensure instant non-null)
+  _sanitizeForSave(key, data) {
+    try {
+      if (!data) return data;
+      if (key === 'creds') {
+        if (typeof data.userId === 'undefined' || data.userId === null) data.userId = data.userId || 'pending';
+        if (typeof data.username === 'undefined' || data.username === null) data.username = data.username || 'pending';
+        if (typeof data.sessionId === 'undefined' || data.sessionId === null) data.sessionId = data.sessionId || `pending-${Date.now()}`;
+        if (typeof data.csrfToken === 'undefined' || data.csrfToken === null) data.csrfToken = data.csrfToken || 'pending';
+        if (typeof data.isLoggedIn === 'undefined') data.isLoggedIn = !!data.sessionId || !!data.authorization;
+        if (!data.loginAt) data.loginAt = data.loginAt || new Date().toISOString();
+      }
+      if (key === 'mqttSession') {
+        if (!data.sessionId) data.sessionId = data.sessionId || `local-mqtt-${Date.now()}`;
+        if (!data.mqttSessionId) data.mqttSessionId = data.mqttSessionId || 'boot';
+        if (!data.lastConnected) data.lastConnected = new Date().toISOString();
+      }
+      if (key === 'seqIds') {
+        if (typeof data.seq_id === 'undefined' || data.seq_id === null) data.seq_id = data.seq_id || 0;
+        if (typeof data.snapshot_at_ms === 'undefined' || data.snapshot_at_ms === null) data.snapshot_at_ms = data.snapshot_at_ms || Date.now();
+      }
+      if (key === 'mqttTopics') {
+        if (!data.topics) data.topics = data.topics || ['ig_sub_direct', 'ig_sub_direct_v2_message_sync', 'presence_subscribe'];
+        if (!data.updatedAt) data.updatedAt = new Date().toISOString();
+      }
+      if (key === 'mqttCapabilities') {
+        data.supportsTyping = Boolean(data.supportsTyping ?? true);
+        data.supportsReactions = Boolean(data.supportsReactions ?? true);
+        data.supportsVoice = Boolean(data.supportsVoice ?? false);
+        data.protocolVersion = data.protocolVersion || 3;
+        data.collectedAt = data.collectedAt || new Date().toISOString();
+      }
+      if (key === 'mqttHealth') {
+        data.lastPingAt = data.lastPingAt || null;
+        data.lastPongAt = data.lastPongAt || null;
+        data.latencyMs = data.latencyMs || 0;
+        data.missedPings = data.missedPings || 0;
+        data.status = data.status || 'unknown';
+      }
+      if (key === 'mqttMessageCache') {
+        if (!Array.isArray(data.lastIds)) data.lastIds = [];
+        if (!data.max) data.max = data.max || 500;
+      }
+      if (key === 'mqttOutbox') {
+        if (!Array.isArray(data)) return [];
+      }
+      if (key === 'mqttSubscriptionHealth') {
+        data.expected = data.expected || (this.getMqttTopics()?.topics || ['ig_sub_direct']);
+        data.active = data.active || data.expected.slice();
+        data.lastCheck = data.lastCheck || new Date().toISOString();
+        data.needsResubscribe = data.needsResubscribe || false;
+      }
+      if (key === 'mqttTraffic') {
+        data.messagesInPerMin = data.messagesInPerMin || 0;
+        data.messagesOutPerMin = data.messagesOutPerMin || 0;
+        data.lastReset = data.lastReset || new Date().toISOString();
+      }
+      if (key === 'mqttReconnect') {
+        data.attempts = data.attempts || 0;
+        data.lastReason = data.lastReason || null;
+        data.lastAttemptAt = data.lastAttemptAt || null;
+        data.nextRetryInMs = data.nextRetryInMs || 0;
+      }
+      if (key === 'mqttRisk') {
+        data.riskScore = typeof data.riskScore === 'number' ? data.riskScore : 0;
+        data.level = data.level || 'low';
+        data.updatedAt = data.updatedAt || new Date().toISOString();
+      }
+    } catch (e) {
+      // ignore sanitize errors
+    }
+    return data;
+  }
+
   // create a timestamped backup of existing file (if present)
   async _createBackup(key) {
     try {
@@ -133,9 +230,11 @@ class MultiFileAuthState extends EventEmitter {
     this._ensureFolder();
     const filePath = this._getFilePath(key);
     try {
+      // sanitize to avoid nulls for key fields
+      const sanitized = this._sanitizeForSave(key, JSON.parse(JSON.stringify(data)));
       // create backup before overwriting existing file
       await this._createBackup(key);
-      await this._writeFileAtomic(filePath, data);
+      await this._writeFileAtomic(filePath, sanitized);
       return true;
     } catch (e) {
       console.error(`[MultiFileAuthState] Error writing ${key}:`, e.message);
@@ -189,6 +288,15 @@ class MultiFileAuthState extends EventEmitter {
     };
     if (!this.data.accountsIndex) this.data.accountsIndex = {};
 
+    // ensure mqtt helper objects exist
+    if (!this.data.mqttHealth) this.data.mqttHealth = { lastPingAt: null, lastPongAt: null, latencyMs: 0, missedPings: 0, status: 'unknown' };
+    if (!this.data.mqttReconnect) this.data.mqttReconnect = { attempts: 0, lastReason: null, lastAttemptAt: null, nextRetryInMs: 0 };
+    if (!this.data.mqttMessageCache) this.data.mqttMessageCache = { lastIds: [], max: 500 };
+    if (!this.data.mqttOutbox) this.data.mqttOutbox = [];
+    if (!this.data.mqttSubscriptionHealth) this.data.mqttSubscriptionHealth = { expected: (this.data.mqttTopics?.topics || ['ig_sub_direct']), active: (this.data.mqttTopics?.topics || ['ig_sub_direct']).slice(), lastCheck: new Date().toISOString(), needsResubscribe: false };
+    if (!this.data.mqttTraffic) this.data.mqttTraffic = { messagesInPerMin: 0, messagesOutPerMin: 0, lastReset: new Date().toISOString() };
+    if (!this.data.mqttRisk) this.data.mqttRisk = { riskScore: 0, level: 'low', updatedAt: new Date().toISOString() };
+
     return {
       creds: this.data.creds,
       device: this.data.device,
@@ -205,6 +313,13 @@ class MultiFileAuthState extends EventEmitter {
       loginHistory: this.data.loginHistory,
       usageStats: this.data.usageStats,
       accountsIndex: this.data.accountsIndex,
+      mqttHealth: this.data.mqttHealth,
+      mqttReconnect: this.data.mqttReconnect,
+      mqttMessageCache: this.data.mqttMessageCache,
+      mqttOutbox: this.data.mqttOutbox,
+      mqttSubscriptionHealth: this.data.mqttSubscriptionHealth,
+      mqttTraffic: this.data.mqttTraffic,
+      mqttRisk: this.data.mqttRisk,
       hasSession: !!(this.data.creds && this.data.cookies)
     };
   }
@@ -225,6 +340,15 @@ class MultiFileAuthState extends EventEmitter {
     if (this.data.accountsIndex) {
       try { await this._writeFile('accountsIndex', this.data.accountsIndex); } catch (e) {}
     }
+    // mqtt helpers
+    try { await this._writeFile('mqttHealth', this.data.mqttHealth); } catch (e) {}
+    try { await this._writeFile('mqttReconnect', this.data.mqttReconnect); } catch (e) {}
+    try { await this._writeFile('mqttMessageCache', this.data.mqttMessageCache); } catch (e) {}
+    try { await this._writeFile('mqttOutbox', this.data.mqttOutbox); } catch (e) {}
+    try { await this._writeFile('mqttSubscriptionHealth', this.data.mqttSubscriptionHealth); } catch (e) {}
+    try { await this._writeFile('mqttTraffic', this.data.mqttTraffic); } catch (e) {}
+    try { await this._writeFile('mqttRisk', this.data.mqttRisk); } catch (e) {}
+
     await Promise.all(savePromises);
   }
 
@@ -254,6 +378,15 @@ class MultiFileAuthState extends EventEmitter {
     if (this.data.mqttAuth) promises.push(this._writeFile('mqttAuth', this.data.mqttAuth));
     if (this.data.lastPublishIds) promises.push(this._writeFile('lastPublishIds', this.data.lastPublishIds));
 
+    // mqtt helpers
+    promises.push(this._writeFile('mqttHealth', this.data.mqttHealth));
+    promises.push(this._writeFile('mqttReconnect', this.data.mqttReconnect));
+    promises.push(this._writeFile('mqttMessageCache', this.data.mqttMessageCache));
+    promises.push(this._writeFile('mqttOutbox', this.data.mqttOutbox));
+    promises.push(this._writeFile('mqttSubscriptionHealth', this.data.mqttSubscriptionHealth));
+    promises.push(this._writeFile('mqttTraffic', this.data.mqttTraffic));
+    promises.push(this._writeFile('mqttRisk', this.data.mqttRisk));
+
     await Promise.all(promises);
     this.emit('mqtt-state-saved');
   }
@@ -382,6 +515,445 @@ class MultiFileAuthState extends EventEmitter {
     this._debouncedSave(['usageStats']);
   }
 
+  // --- MQTT helper methods ---
+
+  // update mqtt health and persist
+  _updateMqttHealth(partial) {
+    try {
+      if (!this.data.mqttHealth) this.data.mqttHealth = {};
+      Object.assign(this.data.mqttHealth, partial);
+      // recompute status
+      if (this.data.mqttHealth.missedPings > 3) {
+        this.data.mqttHealth.status = 'degraded';
+      } else if (this.data.mqttHealth.lastPongAt) {
+        this.data.mqttHealth.status = 'ok';
+      } else {
+        this.data.mqttHealth.status = this.data.mqttHealth.status || 'unknown';
+      }
+      this._debouncedSave(['mqttHealth']);
+    } catch (e) {}
+  }
+
+  // mark ping sent
+  markPing() {
+    this._updateMqttHealth({ lastPingAt: new Date().toISOString() });
+  }
+
+  // mark pong received and update latency
+  markPong() {
+    const now = Date.now();
+    const lastPing = this.data.mqttHealth?.lastPingAt ? new Date(this.data.mqttHealth.lastPingAt).getTime() : null;
+    const latency = lastPing ? (now - lastPing) : 0;
+    const missed = Math.max(0, (this.data.mqttHealth?.missedPings || 0) - 1);
+    this._updateMqttHealth({ lastPongAt: new Date().toISOString(), latencyMs: latency, missedPings: missed });
+  }
+
+  // increment missed ping
+  markMissedPing() {
+    const missed = (this.data.mqttHealth?.missedPings || 0) + 1;
+    this._updateMqttHealth({ missedPings: missed });
+  }
+
+  // message deduplication: return true if duplicate
+  isDuplicateMessage(messageId) {
+    if (!messageId) return false;
+    if (!this.data.mqttMessageCache) this.data.mqttMessageCache = { lastIds: [], max: 500 };
+    const idx = this.data.mqttMessageCache.lastIds.indexOf(messageId);
+    if (idx !== -1) return true;
+    // push and cap
+    this.data.mqttMessageCache.lastIds.push(messageId);
+    if (this.data.mqttMessageCache.lastIds.length > (this.data.mqttMessageCache.max || 500)) {
+      this.data.mqttMessageCache.lastIds.shift();
+    }
+    this._debouncedSave(['mqttMessageCache']);
+    return false;
+  }
+
+  // enqueue outgoing message to outbox
+  enqueueOutbox(item) {
+    if (!this.data.mqttOutbox) this.data.mqttOutbox = [];
+    // item: { topic, payload, qos, createdAt, tries }
+    const i = Object.assign({ qos: 1, createdAt: new Date().toISOString(), tries: 0 }, item);
+    this.data.mqttOutbox.push(i);
+    this._debouncedSave(['mqttOutbox']);
+    this.emit('outbox-enqueued', i);
+    return i;
+  }
+
+  // flush outbox (attempt send). Tries to use common publish/send methods on client
+  async flushOutbox(realtimeClient, maxPerRun = 50) {
+    if (!this.data.mqttOutbox || !this.data.mqttOutbox.length) return 0;
+    const sent = [];
+    const keep = [];
+    let processed = 0;
+    for (const item of this.data.mqttOutbox) {
+      if (processed >= maxPerRun) {
+        keep.push(item);
+        continue;
+      }
+      processed++;
+      try {
+        item.tries = (item.tries || 0) + 1;
+        // try publish methods in order of likelihood
+        let ok = false;
+        if (realtimeClient && typeof realtimeClient.publish === 'function') {
+          // mqtt.js style
+          try {
+            realtimeClient.publish(item.topic, typeof item.payload === 'string' ? item.payload : JSON.stringify(item.payload), { qos: item.qos });
+            ok = true;
+          } catch (e) {
+            ok = false;
+          }
+        } else if (realtimeClient && typeof realtimeClient.send === 'function') {
+          try {
+            realtimeClient.send(item.topic, item.payload);
+            ok = true;
+          } catch (e) { ok = false; }
+        } else if (realtimeClient && typeof realtimeClient.sendMessage === 'function') {
+          try {
+            realtimeClient.sendMessage(item.payload);
+            ok = true;
+          } catch (e) { ok = false; }
+        } else {
+          // cannot send: keep in outbox
+          ok = false;
+        }
+
+        if (ok) {
+          sent.push(item);
+          this.incrementStat('mqttMessages', 1);
+        } else {
+          // keep for retry, but if tries exceed threshold move to dead-letter (drop)
+          if (item.tries >= 10) {
+            this.emit('outbox-dropped', item);
+          } else {
+            keep.push(item);
+          }
+        }
+      } catch (e) {
+        keep.push(item);
+      }
+    }
+    // replace queue
+    this.data.mqttOutbox = keep.concat(this.data.mqttOutbox.slice(processed));
+    this._debouncedSave(['mqttOutbox']);
+    this.emit('outbox-flushed', { sentCount: sent.length, remaining: this.data.mqttOutbox.length });
+    return sent.length;
+  }
+
+  // subscription watchdog: check and attempt resubscribe
+  async checkSubscriptions(realtimeClient) {
+    try {
+      const expected = this.data.mqttSubscriptionHealth?.expected || (this.data.mqttTopics?.topics || []);
+      let active = [];
+      // try to read from client
+      if (realtimeClient?.connection?.subscribedTopics) active = realtimeClient.connection.subscribedTopics;
+      else if (realtimeClient?._subscribedTopics) active = realtimeClient._subscribedTopics;
+      else if (Array.isArray(this.data.mqttTopics?.topics)) active = this.data.mqttTopics.topics;
+
+      const needs = expected.filter(t => !active.includes(t));
+      this.data.mqttSubscriptionHealth = {
+        expected,
+        active,
+        lastCheck: new Date().toISOString(),
+        needsResubscribe: needs.length > 0
+      };
+      this._debouncedSave(['mqttSubscriptionHealth']);
+
+      if (needs.length && realtimeClient) {
+        for (const t of needs) {
+          try {
+            // call common subscribe methods
+            if (typeof realtimeClient.subscribe === 'function') {
+              realtimeClient.subscribe(t);
+            } else if (realtimeClient.connection && typeof realtimeClient.connection.subscribe === 'function') {
+              realtimeClient.connection.subscribe(t);
+            } else if (typeof realtimeClient.subscriptions === 'function') {
+              realtimeClient.subscriptions([t]);
+            }
+            // update active
+            if (!this.data.mqttSubscriptionHealth.active.includes(t)) this.data.mqttSubscriptionHealth.active.push(t);
+            this.emit('resubscribe-attempt', { topic: t });
+          } catch (e) {
+            this.emit('resubscribe-failed', { topic: t, error: e.message });
+          }
+        }
+        this._debouncedSave(['mqttSubscriptionHealth']);
+      }
+      return this.data.mqttSubscriptionHealth;
+    } catch (e) {
+      return null;
+    }
+  }
+
+  // traffic profiler: update incoming/outgoing counters
+  _updateTraffic(incoming = 0, outgoing = 0) {
+    try {
+      if (!this.data.mqttTraffic) this.data.mqttTraffic = { messagesInPerMin: 0, messagesOutPerMin: 0, lastReset: new Date().toISOString() };
+      const lastReset = new Date(this.data.mqttTraffic.lastReset).getTime();
+      if (Date.now() - lastReset > 60 * 1000) {
+        // reset every minute
+        this.data.mqttTraffic.messagesInPerMin = 0;
+        this.data.mqttTraffic.messagesOutPerMin = 0;
+        this.data.mqttTraffic.lastReset = new Date().toISOString();
+      }
+      this.data.mqttTraffic.messagesInPerMin += incoming;
+      this.data.mqttTraffic.messagesOutPerMin += outgoing;
+      this._debouncedSave(['mqttTraffic']);
+    } catch (e) {}
+  }
+
+  // compute simple risk score from reconnects, errors, traffic
+  _computeRiskScore() {
+    try {
+      const reconnects = this.data.usageStats?.reconnects || 0;
+      const errors = this.data.usageStats?.errors || 0;
+      const outPerMin = this.data.mqttTraffic?.messagesOutPerMin || 0;
+      // simple heuristic
+      let score = 0;
+      score += Math.min(1, reconnects / 10) * 0.4;
+      score += Math.min(1, errors / 20) * 0.3;
+      score += Math.min(1, outPerMin / 200) * 0.3;
+      const level = score > 0.7 ? 'high' : score > 0.35 ? 'medium' : 'low';
+      this.data.mqttRisk = { riskScore: Number(score.toFixed(3)), level, updatedAt: new Date().toISOString() };
+      this._debouncedSave(['mqttRisk']);
+      this.emit('risk-updated', this.data.mqttRisk);
+      return this.data.mqttRisk;
+    } catch (e) {
+      return null;
+    }
+  }
+
+  // schedule auto reconnect using backoff; will attempt to call client.reconnect() if available or emit event
+  _scheduleReconnect(realtimeClient, reason = 'unknown') {
+    try {
+      this._reconnectAttempts = (this._reconnectAttempts || 0) + 1;
+      const idx = Math.min(this._reconnectAttempts - 1, this._reconnectBackoff.length - 1);
+      const delay = this._reconnectBackoff[idx] || this._reconnectBackoff[this._reconnectBackoff.length - 1];
+      this.data.mqttReconnect = {
+        attempts: this._reconnectAttempts,
+        lastReason: reason,
+        lastAttemptAt: new Date().toISOString(),
+        nextRetryInMs: delay
+      };
+      this.incrementStat('reconnects', 1);
+      this._debouncedSave(['mqttReconnect']);
+      if (this._reconnectTimer) clearTimeout(this._reconnectTimer);
+      this._reconnectTimer = setTimeout(async () => {
+        try {
+          if (realtimeClient) {
+            if (typeof realtimeClient.reconnect === 'function') {
+              realtimeClient.reconnect();
+            } else if (typeof realtimeClient.connect === 'function') {
+              // some libs have connect
+              realtimeClient.connect();
+            } else {
+              // can't auto-call: emit event so app can handle
+              this.emit('should-reconnect', { reason });
+            }
+          } else {
+            this.emit('should-reconnect', { reason });
+          }
+        } catch (e) {
+          this.emit('reconnect-failed', { reason, error: e.message });
+        }
+      }, delay);
+    } catch (e) {}
+  }
+
+  // reset reconnect attempts after successful connect
+  _resetReconnect() {
+    this._reconnectAttempts = 0;
+    if (this._reconnectTimer) {
+      clearTimeout(this._reconnectTimer);
+      this._reconnectTimer = null;
+    }
+    if (this.data.mqttReconnect) {
+      this.data.mqttReconnect.attempts = 0;
+      this.data.mqttReconnect.nextRetryInMs = 0;
+      this._debouncedSave(['mqttReconnect']);
+    }
+  }
+
+  // warm-restore: apply saved options into realtimeClient before connect to speed startup
+  warmRestoreClient(realtimeClient) {
+    try {
+      const opts = this.getMqttConnectOptions();
+      if (!opts) return false;
+      // Merge irisData, mqttAuthToken etc. into client init options if possible
+      if (realtimeClient.initOptions && typeof realtimeClient.initOptions === 'object') {
+        Object.assign(realtimeClient.initOptions, opts);
+      } else {
+        realtimeClient.initOptions = opts;
+      }
+      // also set connection clientInfo if supported
+      if (realtimeClient.connection && realtimeClient.connection.clientInfo && this.data.mqttSession?.mqttSessionId) {
+        realtimeClient.connection.clientInfo.clientMqttSessionId = this.data.mqttSession.mqttSessionId;
+      }
+      this.emit('warm-restore', { options: opts });
+      return true;
+    } catch (e) {
+      return false;
+    }
+  }
+
+  // attach runtime helpers to realtimeClient to manage instant improvements
+  attachRealtimeClient(realtimeClient, opts = {}) {
+    try {
+      if (!realtimeClient) return;
+
+      // warm restore immediately
+      try { this.warmRestoreClient(realtimeClient); } catch (e) {}
+
+      // ping/pong monitoring
+      const pingIntervalMs = opts.pingIntervalMs || 30 * 1000; // 30s
+      let pingTimer = null;
+      const startPing = () => {
+        if (pingTimer) clearInterval(pingTimer);
+        pingTimer = setInterval(() => {
+          try {
+            this.markPing();
+            if (typeof realtimeClient.ping === 'function') {
+              realtimeClient.ping();
+            } else if (typeof realtimeClient.pingReq === 'function') {
+              realtimeClient.pingReq();
+            } else if (typeof realtimeClient.pingServer === 'function') {
+              realtimeClient.pingServer();
+            } else {
+              // some libraries use publish to $SYS topic or nothing; we still mark ping
+            }
+            // after ping, schedule missed ping detection
+            setTimeout(() => {
+              // if lastPongAt older than lastPingAt, consider missed
+              const lastPing = new Date(this.data.mqttHealth?.lastPingAt || 0).getTime();
+              const lastPong = new Date(this.data.mqttHealth?.lastPongAt || 0).getTime();
+              if (lastPing && (!lastPong || lastPong < lastPing)) {
+                this.markMissedPing();
+              }
+            }, Math.min(5000, Math.floor(pingIntervalMs / 2)));
+          } catch (e) {}
+        }, pingIntervalMs);
+      };
+      const stopPing = () => { if (pingTimer) clearInterval(pingTimer); pingTimer = null; };
+
+      // event handlers (subscribe to multiple common event names)
+      const onConnect = async (...args) => {
+        this._resetReconnect();
+        this.data.mqttSession = this.data.mqttSession || {};
+        this.data.mqttSession.lastConnected = new Date().toISOString();
+        this._debouncedSave(['mqttSession']);
+        this._updateMqttHealth({ status: 'ok', lastPongAt: new Date().toISOString(), missedPings: 0 });
+        this.emit('realtime-connected', { args });
+        // flush outbox on connect
+        try { await this.flushOutbox(realtimeClient); } catch (e) {}
+        // check subscriptions
+        try { await this.checkSubscriptions(realtimeClient); } catch (e) {}
+        startPing();
+      };
+
+      const onClose = (...args) => {
+        stopPing();
+        this._updateMqttHealth({ status: 'dead' });
+        this._scheduleReconnect(realtimeClient, 'close');
+        this.emit('realtime-closed', { args });
+      };
+
+      const onReconnect = (...args) => {
+        this.emit('realtime-reconnect', { args });
+      };
+
+      const onOffline = (...args) => {
+        this._updateMqttHealth({ status: 'degraded' });
+        this._scheduleReconnect(realtimeClient, 'offline');
+        this.emit('realtime-offline', { args });
+      };
+
+      const onError = (err) => {
+        this.incrementStat('errors', 1);
+        this._scheduleReconnect(realtimeClient, err?.message || 'error');
+        this.emit('realtime-error', { error: err?.message || String(err) });
+      };
+
+      const onMessage = async (topic, payload, packet) => {
+        // generic message handler: try to extract id for dedupe
+        // Many IG messages contain an id field in JSON payload; try to parse
+        let messageId = null;
+        try {
+          const s = (typeof payload === 'string') ? payload : (payload && payload.toString ? payload.toString() : null);
+          if (s) {
+            const j = JSON.parse(s);
+            if (j && (j.message_id || j.id || j.msg_id)) messageId = j.message_id || j.id || j.msg_id;
+          }
+        } catch (e) {
+          // not json, ignore
+        }
+        if (messageId && this.isDuplicateMessage(messageId)) {
+          this.emit('message-duplicate', { topic, messageId });
+          return;
+        }
+        // update traffic counters
+        this._updateTraffic(1, 0);
+        this.incrementStat('mqttMessages', 1);
+        // mark pong if message looks like pong or heartbeat
+        if (topic && topic.includes('pong')) this.markPong();
+        this.emit('realtime-message', { topic, payload, packet });
+      };
+
+      // wire up events safely for common handlers
+      try {
+        // mqtt.js style
+        if (typeof realtimeClient.on === 'function') {
+          realtimeClient.on('connect', onConnect);
+          realtimeClient.on('reconnect', onReconnect);
+          realtimeClient.on('close', onClose);
+          realtimeClient.on('offline', onOffline);
+          realtimeClient.on('error', onError);
+          realtimeClient.on('message', onMessage);
+        }
+        // websockets or other: attempt to attach possible event names
+        if (realtimeClient.addEventListener && typeof realtimeClient.addEventListener === 'function') {
+          try { realtimeClient.addEventListener('open', onConnect); } catch (e) {}
+          try { realtimeClient.addEventListener('close', onClose); } catch (e) {}
+          try { realtimeClient.addEventListener('error', onError); } catch (e) {}
+          try { realtimeClient.addEventListener('message', (ev) => onMessage(ev.topic || ev.type, ev.data || ev.payload, ev)); } catch (e) {}
+        }
+      } catch (e) {}
+
+      // also attach one-time status: if the client supports events differently, let app listen to 'should-reconnect'
+      // attach a cleanup handle
+      const cleanup = () => {
+        stopPing();
+        try {
+          if (typeof realtimeClient.off === 'function') {
+            realtimeClient.off('connect', onConnect);
+            realtimeClient.off('reconnect', onReconnect);
+            realtimeClient.off('close', onClose);
+            realtimeClient.off('offline', onOffline);
+            realtimeClient.off('error', onError);
+            realtimeClient.off('message', onMessage);
+          }
+        } catch (e) {}
+        this.emit('realtime-detach');
+      };
+
+      // expose cleanup on client for convenience
+      try { realtimeClient._authStateCleanup = cleanup; } catch (e) {}
+
+      // return helper object to caller
+      return {
+        pingIntervalMs,
+        stop: cleanup,
+        flushOutbox: async (max) => { return await this.flushOutbox(realtimeClient, max); },
+        checkSubscriptions: async () => { return await this.checkSubscriptions(realtimeClient); },
+        warmRestore: () => { return this.warmRestoreClient(realtimeClient); }
+      };
+    } catch (e) {
+      // emit attach failure
+      this.emit('attach-failed', { error: e.message });
+      return null;
+    }
+  }
+
   // --- Getters ---
   getCreds() { return this.data.creds; }
   getDevice() { return this.data.device; }
@@ -398,6 +970,13 @@ class MultiFileAuthState extends EventEmitter {
   getLoginHistory() { return this.data.loginHistory || []; }
   getUsageStats() { return this.data.usageStats || {}; }
   getAccountsIndex() { return this.data.accountsIndex || {}; }
+  getMqttHealth() { return this.data.mqttHealth || {}; }
+  getMqttReconnect() { return this.data.mqttReconnect || {}; }
+  getMqttMessageCache() { return this.data.mqttMessageCache || {}; }
+  getMqttOutbox() { return this.data.mqttOutbox || []; }
+  getMqttSubscriptionHealth() { return this.data.mqttSubscriptionHealth || {}; }
+  getMqttTraffic() { return this.data.mqttTraffic || {}; }
+  getMqttRisk() { return this.data.mqttRisk || {}; }
 
   hasValidSession() {
     return !!(this.data.creds && this.data.cookies && this.data.creds.authorization);
@@ -517,7 +1096,9 @@ class MultiFileAuthState extends EventEmitter {
       lastLogin: (this.data.loginHistory && this.data.loginHistory[0]?.date) || null,
       usageStats: this.getUsageStats(),
       accountStatus: this.data.creds?.accountStatus || 'ok',
-      deviceLocked: !!this.data.device?.locked
+      deviceLocked: !!this.data.device?.locked,
+      mqttHealth: this.getMqttHealth(),
+      mqttRisk: this.getMqttRisk()
     };
   }
 }
@@ -947,7 +1528,15 @@ async function useMultiFileAuthState(folder) {
 
   const getMqttConnectOptions = () => {
     if (!authState.hasMqttSession()) {
-      return null;
+      // still return a warm default to help warm-restore
+      const defaultTopics = ['ig_sub_direct', 'ig_sub_direct_v2_message_sync'];
+      return {
+        graphQlSubs: defaultTopics,
+        skywalkerSubs: ['presence_subscribe', 'typing_subscribe'],
+        irisData: { seq_id: authState.getSeqIds()?.seq_id || 0, snapshot_at_ms: authState.getSeqIds()?.snapshot_at_ms || Date.now() },
+        mqttAuthToken: authState.getMqttAuth()?.jwt || null,
+        mqttAuthExpiresAt: authState.getMqttAuth()?.expiresAt || null
+      };
     }
 
     const subs = authState.getSubscriptions() || {};
@@ -960,7 +1549,7 @@ async function useMultiFileAuthState(folder) {
       irisData: seqIds.seq_id ? {
         seq_id: seqIds.seq_id,
         snapshot_at_ms: seqIds.snapshot_at_ms
-      } : null,
+      } : { seq_id: 0, snapshot_at_ms: Date.now() },
       mqttAuthToken: mqttAuth?.jwt || null,
       mqttAuthExpiresAt: mqttAuth?.expiresAt || null
     };
@@ -1101,6 +1690,23 @@ async function useMultiFileAuthState(folder) {
     return authState.getHealth();
   };
 
+  // --- MQTT helpers exposing internal features ---
+  const attachRealtimeClient = (realtimeClient, opts = {}) => {
+    return authState.attachRealtimeClient(realtimeClient, opts);
+  };
+
+  const enqueueOutbox = (item) => authState.enqueueOutbox(item);
+  const flushOutbox = (client, max) => authState.flushOutbox(client, max);
+  const checkSubscriptions = (client) => authState.checkSubscriptions(client);
+  const computeRisk = () => authState._computeRiskScore();
+  const warmRestore = (client) => authState.warmRestoreClient(client);
+  const getMqttHealth = () => authState.getMqttHealth();
+  const getMqttTraffic = () => authState.getMqttTraffic();
+  const getMqttRisk = () => authState.getMqttRisk();
+  const isDuplicateMessage = (id) => authState.isDuplicateMessage(id);
+  const markPing = () => authState.markPing();
+  const markPong = () => authState.markPong();
+
   // --- Misc helpers: loginHistory & usageStats getters ---
   const getLoginHistory = () => authState.getLoginHistory();
   const getUsageStats = () => authState.getUsageStats();
@@ -1151,7 +1757,21 @@ async function useMultiFileAuthState(folder) {
     verifyDeviceFingerprint,
     registerAccount,
     listAccounts,
-    getHealth
+    getHealth,
+
+    // mqtt helpers
+    attachRealtimeClient,
+    enqueueOutbox,
+    flushOutbox,
+    checkSubscriptions,
+    computeRisk,
+    warmRestore,
+    getMqttHealth,
+    getMqttTraffic,
+    getMqttRisk,
+    isDuplicateMessage,
+    markPing,
+    markPong
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nodejs-insta-private-api-mqtt",
-  "version": "1.2.10",
+  "version": "1.3.10",
   "description": "Complete Instagram MQTT protocol with FULL iOS + Android support. 33 device presets (21 iOS + 12 Android). iPhone 16/15/14/13/12, iPad Pro, Samsung, Pixel, Huawei. Real-time DM messaging, view-once media extraction, sub-500ms latency.",
   "main": "dist/index.js",
   "scripts": {