nodejs-insta-private-api-mqtt 1.3.24 → 1.3.25

package/dist/mqttot/mqttot.client.js

@@ -3,11 +3,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.mqttotConnectFlow = exports.MQTToTClient = void 0;
 const shared_1 = require("../shared");
 const mqttot_connect_request_packet_1 = require("./mqttot.connect.request.packet");
-// *** Schimbare: importăm mqtts din pachet extern în loc de mqtt-shim relativ ***
+// *** Change: import the external mqtts package instead of a local mqtt-shim ***
 const mqtts_1 = require("mqtts");
 const errors_1 = require("../errors");
 const mqttot_connect_response_packet_1 = require("./mqttot.connect.response.packet");
 
+/**
+ * MQTToTClient
+ * - Subclasses the external mqtts.MqttClient implementation.
+ * - Provides Instagram-specific connect/publish helpers (Thrift payload, debug).
+ * - Keeps compatibility with options used by the original library.
+ */
 class MQTToTClient extends mqtts_1.MqttClient {
     constructor(options) {
         super({
@@ -33,6 +39,7 @@ class MQTToTClient extends mqtts_1.MqttClient {
                     additionalOptions: options.additionalOptions,
                 }),
         });
+        // small debug helper that prefixes messages with the broker url
         this.mqttotDebug = (msg, ...args) => (0, shared_1.debugChannel)('mqttot')(`${options.url}: ${msg}`, ...args);
         this.connectPayloadProvider = options.payloadProvider;
         this.mqttotDebug(`Creating client`);
@@ -48,11 +55,13 @@ class MQTToTClient extends mqtts_1.MqttClient {
                 this.mqttotDebug(`${type}: ${e.message}\n\tStack: ${e.stack}`);
             }
         };
+        // Attach basic diagnostics so errors/warnings are visible via debugChannel
         this.on('error', printErrorOrWarning('Error'));
         this.on('warning', printErrorOrWarning('Warning'));
         this.on('disconnect', e => this.mqttotDebug(`Disconnected. ${e}`));
     }
     async connect(options) {
+        // Acquire the payload (Thrift serialized connection blob) before connecting.
         this.connectPayload = await this.connectPayloadProvider();
         return super.connect(options);
     }
@@ -63,20 +72,28 @@ class MQTToTClient extends mqtts_1.MqttClient {
         return mqttotConnectFlow(this.connectPayload, this.requirePayload);
     }
     /**
-     * Compresses the payload
+     * Compresses the payload and publishes it.
+     * NOTE: Always publishes with qosLevel: 0 to avoid puback/retry instability.
+     * Rationale: Instagram/edge MQTT sometimes behaves inconsistently with QoS1 (missing PUBACKs,
+     * delayed acks, etc.). For stability we force QoS 0 here so the library avoids waiting on ACKs
+     * that may never arrive and causing reconnect loops.
+     *
      * @param {MqttMessage} message
-     * @returns {Promise<MqttMessageOutgoing>}
+     * @returns {Promise}
      */
     async mqttotPublish(message) {
         this.mqttotDebug(`Publishing ${message.payload.byteLength}bytes to topic ${message.topic}`);
         return await this.publish({
             topic: message.topic,
             payload: await (0, shared_1.compressDeflate)(message.payload),
-            qosLevel: message.qosLevel,
+            qosLevel: 0, // FORCED: QoS 0 for stability on Instagram edge
         });
     }
     /**
      * Special listener for specific topics with transformers
+     * This helper attaches a transformer that converts raw message payloads into
+     * structured data before calling the provided handler.
+     *
      * @param {Object} config - { topic, transformer }
      * @param {Function} handler - Callback to handle transformed data
      */
@@ -99,7 +116,7 @@ exports.MQTToTClient = MQTToTClient;
 
 /**
  * NOTE: changed acceptance logic for CONNACK payload:
- * - Historically some connect flows expected a payload in CONNACK (requirePayload = true),
+ * - Historically the connect flow expected a payload in CONNACK (requirePayload = true),
  *   but Instagram/edge sometimes replies with an empty payload even when connection is valid.
  * - To avoid noisy 'CONNACK: no payload (payloadExpected)' errors and unnecessary disconnect logs,
  *   we now treat any successful CONNACK (packet.isSuccess) as success regardless of payload.
@@ -128,3 +145,4 @@ function mqttotConnectFlow(payload, requirePayload) {
     });
 }
 exports.mqttotConnectFlow = mqttotConnectFlow;
+

package/dist/realtime/commands/commands.js

@@ -10,22 +10,23 @@ class Commands {
 
     /**
      * Publish a compressed payload to a topic.
-     * - Will force QoS 0 (no PUBACK wait) because IG internal MQTT often
-     *   doesn't reply PUBACK for these internal topics and QoS1 causes timeouts.
-     * - Will no-op if client is not connected to avoid "Socket not writable" errors.
+     * - Forces QoS 0 (no PUBACK wait) because Instagram internal MQTT often
+     *   doesn't reply PUBACK for these internal topics and QoS1 causes timeouts
+     *   and reconnect instability.
+     * - No-op if client is not connected to avoid "Socket not writable" errors.
+     * - Defensive checks: if the client exposes .connected or .isConnected(), respect them.
      */
     async publishToTopic(topic, compressedData, qos = 0) {
         try {
-            // Guard: ensure client exists and is connected. Many mqtt clients expose
-            // .connected boolean; this is defensive — if not present, still try but safe-guard write errors.
+            // Defensive: ensure we have a client
             if (!this.client) return;
 
-            // prefer explicit connected flag if available
+            // If client exposes a boolean 'connected' flag, respect it
             if (typeof this.client.connected !== 'undefined' && !this.client.connected) {
-                // do not attempt publish when disconnected
                 return;
             }
-            // If client exposes isConnected method, respect it
+
+            // If client exposes an isConnected() method, respect it
             if (typeof this.client.isConnected === 'function' && !this.client.isConnected()) {
                 return;
             }
@@ -33,38 +34,38 @@ class Commands {
             // Build payload buffer
             const payloadBuf = compressedData instanceof Buffer ? compressedData : Buffer.from(compressedData);
 
-            // Always use QoS 0 for IG internal topics (avoid PubAck waiting)
+            // Always publish with QoS 0 for stability on IG edge MQTT
             return this.client.publish({
                 topic,
                 payload: payloadBuf,
                 qosLevel: 0,
             });
         } catch (err) {
-            // Swallow non-fatal publish errors and let higher-level watchdog handle reconnects.
-            // Avoid throwing so callers (watchdog timers) won't crash the loop.
+            // Swallow non-fatal publish errors. Upper layers/watchdog should handle reconnections.
             return;
         }
     }
 
     /**
-     * updateSubscriptions used by RealtimeClient for various keepalive / subscribe refreshes.
-     * We compress the body and publish with QoS 0.
-     * If MQTT client is not ready, we skip the call.
+     * updateSubscriptions used by RealtimeClient for keepalive / subscription refreshes.
+     * - Compresses the subscription payload and publishes with QoS 0.
+     * - Skips publishing if the MQTT client doesn't appear ready.
      */
     async updateSubscriptions(options) {
         try {
             if (!this.client) return;
 
-            // guard connection state again (defensive)
+            // Defensive connection checks
             if (typeof this.client.connected !== 'undefined' && !this.client.connected) return;
             if (typeof this.client.isConnected === 'function' && !this.client.isConnected()) return;
 
             const payload = await (0, shared_1.compressDeflate)(JSON.stringify(options.data || {}));
             return this.publishToTopic(options.topic.id, payload, 0);
         } catch (e) {
-            // Non-fatal
+            // Non-fatal — avoid bubbling errors from keepalive timers
             return;
         }
     }
 }
 exports.Commands = Commands;
+

package/dist/realtime/commands/{enhanced.direct.commands.js → ehnanced.direct.commands.js}

@@ -58,7 +58,7 @@ class EnhancedDirectCommands {
             const json = JSON.stringify(command);
             const payload = await shared_1.compressDeflate(json);
             
-            // Send to MQTT (QoS 1 for message reliability)
+            // Send to MQTT (QoS 0 for stability)
             this.enhancedDebug(`Publishing to MQTT topic ${constants_1.Topics.SEND_MESSAGE.id}`);
             const result = await mqtt.publish({
                 topic: constants_1.Topics.SEND_MESSAGE.id,
@@ -101,7 +101,7 @@ class EnhancedDirectCommands {
             this.enhancedDebug(`Publishing delete command to MQTT topic ${constants_1.Topics.SEND_MESSAGE.id}`);
             const result = await mqtt.publish({
                 topic: constants_1.Topics.SEND_MESSAGE.id,
-                qosLevel: 1,
+                qosLevel: 0,
                 payload: payload,
             });
             
@@ -141,7 +141,7 @@ class EnhancedDirectCommands {
             this.enhancedDebug(`Publishing edit command to MQTT topic ${constants_1.Topics.SEND_MESSAGE.id}`);
             const result = await mqtt.publish({
                 topic: constants_1.Topics.SEND_MESSAGE.id,
-                qosLevel: 1,
+                qosLevel: 0,
                 payload: payload,
             });
             
@@ -182,7 +182,7 @@ class EnhancedDirectCommands {
             this.enhancedDebug(`Publishing reply command to MQTT topic ${constants_1.Topics.SEND_MESSAGE.id}`);
             const result = await mqtt.publish({
                 topic: constants_1.Topics.SEND_MESSAGE.id,
-                qosLevel: 1,
+                qosLevel: 0,
                 payload: payload,
             });
             
@@ -220,7 +220,7 @@ class EnhancedDirectCommands {
             this.enhancedDebug(`Publishing follow subscription to MQTT`);
             const result = await mqtt.publish({
                 topic: constants_1.Topics.SEND_MESSAGE.id,
-                qosLevel: 1,
+                qosLevel: 0,
                 payload: payload,
             });
             
@@ -258,7 +258,7 @@ class EnhancedDirectCommands {
             this.enhancedDebug(`Publishing mention subscription to MQTT`);
             const result = await mqtt.publish({
                 topic: constants_1.Topics.SEND_MESSAGE.id,
-                qosLevel: 1,
+                qosLevel: 0,
                 payload: payload,
             });
             
@@ -296,7 +296,7 @@ class EnhancedDirectCommands {
             this.enhancedDebug(`Publishing call subscription to MQTT`);
             const result = await mqtt.publish({
                 topic: constants_1.Topics.SEND_MESSAGE.id,
-                qosLevel: 1,
+                qosLevel: 0,
                 payload: payload,
             });
             
@@ -335,7 +335,7 @@ class EnhancedDirectCommands {
             this.enhancedDebug(`Publishing add member command to MQTT`);
             const result = await mqtt.publish({
                 topic: constants_1.Topics.SEND_MESSAGE.id,
-                qosLevel: 1,
+                qosLevel: 0,
                 payload: payload,
             });
             
@@ -374,7 +374,7 @@ class EnhancedDirectCommands {
             this.enhancedDebug(`Publishing remove member command to MQTT`);
             const result = await mqtt.publish({
                 topic: constants_1.Topics.SEND_MESSAGE.id,
-                qosLevel: 1,
+                qosLevel: 0,
                 payload: payload,
             });
             
@@ -416,7 +416,7 @@ class EnhancedDirectCommands {
             this.enhancedDebug(`Publishing reaction to MQTT`);
             const result = await mqtt.publish({
                 topic: constants_1.Topics.SEND_MESSAGE.id,
-                qosLevel: 1,
+                qosLevel: 0,
                 payload: payload,
             });
             
@@ -455,7 +455,7 @@ class EnhancedDirectCommands {
             this.enhancedDebug(`Publishing mark as seen to MQTT`);
             const result = await mqtt.publish({
                 topic: constants_1.Topics.SEND_MESSAGE.id,
-                qosLevel: 1,
+                qosLevel: 0,
                 payload: payload,
             });
             
@@ -494,7 +494,7 @@ class EnhancedDirectCommands {
             this.enhancedDebug(`Publishing activity indicator to MQTT`);
             const result = await mqtt.publish({
                 topic: constants_1.Topics.SEND_MESSAGE.id,
-                qosLevel: 1,
+                qosLevel: 0,
                 payload: payload,
             });
             
@@ -535,7 +535,7 @@ class EnhancedDirectCommands {
             this.enhancedDebug(`Publishing media to MQTT`);
             const result = await mqtt.publish({
                 topic: constants_1.Topics.SEND_MESSAGE.id,
-                qosLevel: 1,
+                qosLevel: 0,
                 payload: payload,
             });
             
@@ -576,7 +576,7 @@ class EnhancedDirectCommands {
             this.enhancedDebug(`Publishing location to MQTT`);
             const result = await mqtt.publish({
                 topic: constants_1.Topics.SEND_MESSAGE.id,
-                qosLevel: 1,
+                qosLevel: 0,
                 payload: payload,
             });
             
@@ -617,7 +617,7 @@ class EnhancedDirectCommands {
             this.enhancedDebug(`Publishing profile to MQTT`);
             const result = await mqtt.publish({
                 topic: constants_1.Topics.SEND_MESSAGE.id,
-                qosLevel: 1,
+                qosLevel: 0,
                 payload: payload,
             });
             
@@ -658,7 +658,7 @@ class EnhancedDirectCommands {
             this.enhancedDebug(`Publishing hashtag to MQTT`);
             const result = await mqtt.publish({
                 topic: constants_1.Topics.SEND_MESSAGE.id,
-                qosLevel: 1,
+                qosLevel: 0,
                 payload: payload,
             });
             
@@ -697,7 +697,7 @@ class EnhancedDirectCommands {
             this.enhancedDebug(`Publishing like to MQTT`);
             const result = await mqtt.publish({
                 topic: constants_1.Topics.SEND_MESSAGE.id,
-                qosLevel: 1,
+                qosLevel: 0,
                 payload: payload,
             });
             
@@ -738,7 +738,7 @@ class EnhancedDirectCommands {
             this.enhancedDebug(`Publishing story to MQTT`);
             const result = await mqtt.publish({
                 topic: constants_1.Topics.SEND_MESSAGE.id,
-                qosLevel: 1,
+                qosLevel: 0,
                 payload: payload,
             });
             

package/dist/realtime/realtime.client.js

@@ -1,12 +1,24 @@
 // realtime.client.js
 'use strict';
 
-// (păstrează headerele module imports la fel ca în codul tău original)
+/*
+  RealtimeClient
+  --------------
+  This file implements the RealtimeClient which manages:
+    - constructing the FBNS/MQTT connection payload
+    - starting the MQTT client (MQTToTClient)
+    - attaching lifecycle handlers (connect/close/error)
+    - keepalives, message-sync refresh and traffic watchdogs
+    - wiring MQTT messages into higher-level events (message, iris, receive)
+  Comments below are English explanations added next to the existing logic.
+*/
+
+// (keep module imports headers the same as in your original code)
 const constants_1 = require("../constants");
 const commands_1 = require("./commands");
 const shared_1 = require("../shared");
 const mqttot_1 = require("../mqttot");
-// IMPORT MQTTS în loc de shim local
+// IMPORT MQTTS instead of the local shim (we're using mqtts package)
 const mqtts_1 = require("mqtts");
 const errors_1 = require("../errors");
 const eventemitter3_1 = require("eventemitter3");
@@ -20,20 +32,40 @@ const gap_handler_1 = require("./features/gap-handler");
 const enhanced_direct_commands_1 = require("./commands/enhanced.direct.commands");
 const presence_typing_mixin_1 = require("./mixins/presence-typing.mixin");
 
+/**
+ * RealtimeClient
+ * - Extends EventEmitter to emit high-level events for consumers.
+ * - Responsible for constructing the thrift payload, creating the MQTToTClient and wiring its events.
+ */
 class RealtimeClient extends eventemitter3_1.EventEmitter {
+    // getter to expose the underlying mqtt client instance
     get mqtt() {
         return this._mqtt;
     }
+
+    /**
+     * constructor(ig, mixins)
+     * - ig: instance of instagram client (used for building payloads & fetching inbox)
+     * - mixins: collection of mixins applied to this realtime client (message-sync, realtime-sub, presence/typing)
+     */
     constructor(ig, mixins = [new mixins_1.MessageSyncMixin(), new mixins_1.RealtimeSubMixin(), new presence_typing_mixin_1.PresenceTypingMixin()]) {
         super();
+        // debug helpers
         this.realtimeDebug = (0, shared_1.debugChannel)('realtime');
         this.messageDebug = this.realtimeDebug.extend('message');
+
+        // safeDisconnect flag used when user intentionally disconnects
         this.safeDisconnect = false;
+
+        // convenience wrappers to emit events
         this.emitError = (e) => this.emit('error', e);
         this.emitWarning = (e) => this.emit('warning', e);
+
+        // persistent references
         this.ig = ig;
         this.threads = new Map();
-        
+
+        // instantiate features / protocols / mixins
         this.irisHandshake = new iris_handshake_1.IrisHandshake(this);
         this.skywalkerProtocol = new skywalker_protocol_1.SkywalkerProtocol(this);
         this.presenceManager = new presence_manager_1.PresenceManager(this);
@@ -41,8 +73,9 @@ class RealtimeClient extends eventemitter3_1.EventEmitter {
         this.errorHandler = new error_handler_1.ErrorHandler(this);
         this.gapHandler = new gap_handler_1.GapHandler(this);
         this.directCommands = new enhanced_direct_commands_1.EnhancedDirectCommands(this);
-        
+
         this.realtimeDebug(`Applying mixins: ${mixins.map(m => m.name).join(', ')}`);
+        // apply mixins to this instance (keeps modular features separated)
         (0, mixins_1.applyMixins)(mixins, this, this.ig);
 
         // internal flags & timers
@@ -82,6 +115,11 @@ class RealtimeClient extends eventemitter3_1.EventEmitter {
         const fs = require('fs');
         const path = require('path');
 
+        /**
+         * waitForMqttCredentials(auth, timeoutMs, pollMs)
+         * - Poll the auth state for device / mqtt credentials before proceeding with auto-connect.
+         * - This ensures the saved auth state contains the fields required to build the MQTT payload.
+         */
         const waitForMqttCredentials = async (auth, timeoutMs = 15000, pollMs = 250) => {
             const start = Date.now();
             const hasCreds = () => {
@@ -103,6 +141,7 @@ class RealtimeClient extends eventemitter3_1.EventEmitter {
             return false;
         };
 
+        // Auto-start if saved creds exist on disk (non-blocking)
         if (fs.existsSync(path.join(folder, 'creds.json'))) {
             setTimeout(async () => {
                 try {
@@ -134,6 +173,10 @@ class RealtimeClient extends eventemitter3_1.EventEmitter {
         }
     }
 
+    /**
+     * startRealTimeListener(options)
+     * - Convenience method to fetch initial inbox (IRIS) and connect with those subscriptions.
+     */
     async startRealTimeListener(options = {}) {
         try {
             console.log('[REALTIME] Starting Real-Time Listener...');
@@ -164,6 +207,7 @@ class RealtimeClient extends eventemitter3_1.EventEmitter {
         }
     }
 
+    // Attach convenience handlers that convert raw message events into higher-level events
     _setupMessageHandlers() {
         this.on('message', (data) => {
             const msg = this._parseMessage(data);
@@ -175,6 +219,7 @@ class RealtimeClient extends eventemitter3_1.EventEmitter {
         });
     }
 
+    // Parse a standard realtime message packet into a simplified message object
     _parseMessage(data) {
         try {
             const msg = data.message;
@@ -198,6 +243,7 @@ class RealtimeClient extends eventemitter3_1.EventEmitter {
         }
     }
 
+    // Parse IRIS message data into a simplified message object
     _parseIrisMessage(data) {
         try {
             if (data.event !== 'message_create' && !data.type?.includes('message')) return null;
@@ -216,6 +262,10 @@ class RealtimeClient extends eventemitter3_1.EventEmitter {
         }
     }
 
+    /**
+     * setInitOptions(initOptions)
+     * - Normalizes init options for connect calls (accepts array or object)
+     */
     setInitOptions(initOptions) {
         if (Array.isArray(initOptions))
             initOptions = { graphQlSubs: initOptions };
@@ -227,6 +277,7 @@ class RealtimeClient extends eventemitter3_1.EventEmitter {
         };
     }
 
+    // Extract session ID from a JWT-like authorization header if present
     extractSessionIdFromJWT() {
         try {
             const authHeader = this.ig.state.authorization;
@@ -254,6 +305,11 @@ class RealtimeClient extends eventemitter3_1.EventEmitter {
         }
     }
 
+    /**
+     * constructConnection()
+     * - Build the MQTToTConnection payload (thrift object) used to connect.
+     * - Pulls deviceId, sessionid, device secrets and app-specific headers to populate the payload.
+     */
     constructConnection() {
         const userAgent =
             typeof this.ig.state.userAgent === 'string'
@@ -319,6 +375,7 @@ class RealtimeClient extends eventemitter3_1.EventEmitter {
             }
         } catch (e) {}
 
+        // mqtt JWT token if available (preferred)
         let mqttJwt = null;
         try {
             if (this._attachedAuthState && typeof this._attachedAuthState.getData === 'function') {
@@ -350,6 +407,7 @@ class RealtimeClient extends eventemitter3_1.EventEmitter {
 
         const subscribeTopics = [88, 135, 149, 150, 133, 146];
 
+        // Build the thrift connection object using mqttot.MQTToTConnection
         this.connection = new mqttot_1.MQTToTConnection({
             clientIdentifier: deviceId.substring(0, 20),
             clientInfo: {
@@ -388,12 +446,20 @@ class RealtimeClient extends eventemitter3_1.EventEmitter {
         });
     }
 
+    /**
+     * connect(options)
+     * - Creates the MQTToTClient using mqttot.MQTToTClient and the payloadProvider.
+     * - Attaches idempotent lifecycle handlers for connect/close/error.
+     * - Starts keepalive/watchdog timers and message listeners after successful connect.
+     */
     async connect(options) {
         this.setInitOptions(options);
         this.constructConnection();
         const { MQTToTClient } = require("../mqttot");
         const { compressDeflate } = require("../shared");
-        
+
+        // Create the MQTT client used by the runtime.
+        // requirePayload set to false to avoid treating empty CONNACK payload as fatal.
         this._mqtt = new MQTToTClient({
             url: 'edge-mqtt.facebook.com',
             payloadProvider: async () => {
@@ -402,8 +468,8 @@ class RealtimeClient extends eventemitter3_1.EventEmitter {
             autoReconnect: true,
             requirePayload: false,
         });
-        
-        // attach lifecycle handlers idempotent
+
+        // attach lifecycle handlers idempotent (create once)
         try {
             if (typeof this._attachMqttLifecycle !== 'function') {
                 this._attachMqttLifecycle = async () => {
@@ -415,6 +481,7 @@ class RealtimeClient extends eventemitter3_1.EventEmitter {
                         });
                     } catch (e) {}
                     try {
+                        // handle close -> schedule reconnect attempt with debounce
                         this._mqtt.on('close', async () => {
                             this.realtimeDebug('[MQTT] client close event');
                             this._lastMessageAt = Date.now();
@@ -425,6 +492,7 @@ class RealtimeClient extends eventemitter3_1.EventEmitter {
                         });
                     } catch (e) {}
                     try {
+                        // handle error -> schedule reconnect attempt with debounce
                         this._mqtt.on('error', (err) => {
                             this.realtimeDebug('[MQTT] client error:', err?.message || err);
                             if (this._reconnectTimeoutId) clearTimeout(this._reconnectTimeoutId);
@@ -438,11 +506,13 @@ class RealtimeClient extends eventemitter3_1.EventEmitter {
             try { await this._attachMqttLifecycle(); } catch (e) {}
         } catch (e) {}
 
+        // actually connect the mqtt client (this will emit connect when done)
         await this._mqtt.connect();
-        
-        // Commands uses mqtt client; we changed Commands.updateSubscriptions to qos 0 (see file)
+
+        // Commands uses mqtt client; Commands.updateSubscriptions has been set to use qos 0.
         this.commands = new commands_1.Commands(this._mqtt);
-        
+
+        // Notify higher-level code that we are connected
         this.emit('connected');
 
         // WATCHDOG / KEEPALIVE / TRAFFIC MONITOR
@@ -459,6 +529,7 @@ class RealtimeClient extends eventemitter3_1.EventEmitter {
             const TRAFFIC_INACTIVITY_MS = (this.initOptions && this.initOptions.trafficInactivityMs) ? this.initOptions.trafficInactivityMs : 90000;
 
             try {
+                // Foreground keepalive - periodically send a small "foreground true" subscription update
                 if (this._foregroundTimer) clearInterval(this._foregroundTimer);
                 this._foregroundTimer = setInterval(async () => {
                     try {
@@ -477,6 +548,7 @@ class RealtimeClient extends eventemitter3_1.EventEmitter {
             }
 
             try {
+                // MESSAGE_SYNC refresh - re-subscribe GraphQL subscriptions periodically to keep message-sync fresh
                 if (this._syncTimer) clearInterval(this._syncTimer);
                 this._syncTimer = setInterval(async () => {
                     try {
@@ -493,6 +565,7 @@ class RealtimeClient extends eventemitter3_1.EventEmitter {
             }
 
             try {
+                // Traffic watchdog - if no activity for TRAFFIC_INACTIVITY_MS, attempt reconnect
                 if (this._trafficWatchdog) clearInterval(this._trafficWatchdog);
                 this._trafficWatchdog = setInterval(async () => {
                     try {
@@ -513,6 +586,11 @@ class RealtimeClient extends eventemitter3_1.EventEmitter {
             this.realtimeDebug('[WATCHDOG] initialization error:', e?.message || e);
         }
 
+        /**
+         * Set up on-message handler:
+         * - Messages arriving from low-level MQTT are looked up in mqtt.topicMap,
+         *   then parsed by the topic's parser if available. Otherwise payload is emitted as raw.
+         */
         this._mqtt.on('message', async (msg) => {
             const topicMap = this.mqtt?.topicMap;
             const topic = topicMap?.get(msg.topic);
@@ -529,10 +607,12 @@ class RealtimeClient extends eventemitter3_1.EventEmitter {
                 } catch(e) {}
             }
         });
+        // propagate mqtt errors to RealtimeClient error handler
         this._mqtt.on('error', this.emitError);
 
         try { await this._afterConnectHandlers(); } catch (e) { this.realtimeDebug('[MQTT] afterConnectHandlers failed', e?.message || e); }
 
+        // Initial subscriptions / iris
         await (0, shared_1.delay)(100);
         if (this.initOptions.graphQlSubs && this.initOptions.graphQlSubs.length > 0) {
             await this.graphQlSubscribe(this.initOptions.graphQlSubs);
@@ -567,6 +647,11 @@ class RealtimeClient extends eventemitter3_1.EventEmitter {
         this._setupMessageHandlers();
     }
 
+    /**
+     * _attemptReconnectSafely()
+     * - Ensure only a single reconnect flow runs at once.
+     * - Disconnects existing mqtt client, waits briefly, and calls connect() again.
+     */
     async _attemptReconnectSafely() {
         if (this._reconnectInProgress) return;
         this._reconnectInProgress = true;
@@ -586,6 +671,11 @@ class RealtimeClient extends eventemitter3_1.EventEmitter {
         }
     }
 
+    /**
+     * _ensureIrisSnapshotAndSubscribe()
+     * - Ensure IRIS snapshot is present and subscribe to it.
+     * - Tries a fresh fetch after connect to get the latest snapshot.
+     */
     async _ensureIrisSnapshotAndSubscribe() {
         try {
             let iris = this.initOptions?.irisData || null;
@@ -616,6 +706,10 @@ class RealtimeClient extends eventemitter3_1.EventEmitter {
         }
     }
 
+    /**
+     * Attach message_sync listener to mqtt if available
+     * - Some mqtt clients provide a listen() helper; attach to both numeric id and string names for compatibility.
+     */
     async _ensureMessageSyncListener() {
         try {
             if (this._messageSyncAttached) return;
@@ -647,6 +741,11 @@ class RealtimeClient extends eventemitter3_1.EventEmitter {
         }
     }
 
+    /**
+     * connectFromSavedSession(authStateHelper, options)
+     * - Reconstructs connect options from saved authState and then calls connect()
+     * - Attempts to fetch a fresh IRIS snapshot (up to a few attempts) for safety.
+     */
     async connectFromSavedSession(authStateHelper, options = {}) {
         if (!authStateHelper) {
             throw new Error('authStateHelper is required - use useMultiFileAuthState()');
@@ -723,6 +822,11 @@ class RealtimeClient extends eventemitter3_1.EventEmitter {
 
         return this;
     }
+
+    /**
+     * saveSession(authStateHelper)
+     * - Helper to persist current MQTT session to auth helper if available.
+     */
     async saveSession(authStateHelper) {
         if (!authStateHelper || !authStateHelper.saveMqttSession) {
             console.warn('[RealtimeClient] No authStateHelper provided');
@@ -731,6 +835,11 @@ class RealtimeClient extends eventemitter3_1.EventEmitter {
         await authStateHelper.saveMqttSession(this);
         return true;
     }
+
+    /**
+     * disconnect()
+     * - Perform a graceful shutdown: clear timers and disconnect mqtt client.
+     */
     disconnect() {
         this.safeDisconnect = true;
         try {
@@ -749,6 +858,11 @@ class RealtimeClient extends eventemitter3_1.EventEmitter {
         } catch (e) {}
         return this.mqtt?.disconnect() ?? Promise.resolve();
     }
+
+    /**
+     * graphQlSubscribe(sub)
+     * - Helper that delegates to Commands.updateSubscriptions (which uses qos 0).
+     */
     graphQlSubscribe(sub) {
         sub = typeof sub === 'string' ? [sub] : sub;
         if (!this.commands) {
@@ -762,6 +876,11 @@ class RealtimeClient extends eventemitter3_1.EventEmitter {
             },
         });
     }
+
+    /**
+     * skywalkerSubscribe(sub)
+     * - Delegate to Commands.updateSubscriptions (pubsub topic).
+     */
     skywalkerSubscribe(sub) {
         sub = typeof sub === 'string' ? [sub] : sub;
         if (!this.commands) {
@@ -775,6 +894,11 @@ class RealtimeClient extends eventemitter3_1.EventEmitter {
             },
         });
     }
+
+    /**
+     * irisSubscribe({ seq_id, snapshot_at_ms })
+     * - Subscribe to IRIS using the provided snapshot properties.
+     */
     irisSubscribe({ seq_id, snapshot_at_ms, }) {
         if (!this.commands) {
             throw new mqtts_1.IllegalStateError('connect() must be called before irisSubscribe()');
@@ -791,3 +915,4 @@ class RealtimeClient extends eventemitter3_1.EventEmitter {
     }
 }
 exports.RealtimeClient = RealtimeClient;
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nodejs-insta-private-api-mqtt",
-  "version": "1.3.24",
+  "version": "1.3.25",
   "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": {