nodejs-insta-private-api-mqt 1.4.7 → 1.4.8

package/README.md

@@ -53,7 +53,7 @@ By leveraging MQTT instead of Instagram's REST API, this library achieves sub-50
 - **View-Once Media** - Download disappearing photos/videos before they expire
 - **Raven (View-Once) Sending** - Send view-once and replayable photos/videos via REST
 - **sendPhoto() / sendVideo()** - Upload and send media directly via MQTT
-- **Session persistence** - Multi-file auth state like Baileys (WhatsApp library)
+- **Session persistence** - Multi-file auth state for seamless reconnects
 - **Automatic reconnection** - Smart error classification with type-specific backoff
 - **Session health monitoring** - Auto-relogin, uptime tracking
 - **Persistent logging** - File-based logging with rotation
@@ -954,7 +954,7 @@ await realtime.directCommands.sendForegroundState({
 
 ## Download Media from Messages
 
-This feature provides Baileys-style media download for Instagram DM messages.
+This feature provides persistent media download for Instagram DM messages.
 
 ### Quick Start: Save View-Once Photo
 
@@ -1012,93 +1012,461 @@ realtime.on('message', async (data) => {
 
 ## Building Instagram Bots
 
-### Auto-Reply Bot Example
+The core of any bot built with this library is the `connection.update` event. It fires every time the MQTT connection state changes and tells you exactly what happened — whether you just connected, got disconnected, or the session expired. Combined with the `message` event for incoming DMs, these two hooks are all you need for most bots.
+
+Both `client.on('connection.update', ...)` and `client.ev.on('connection.update', ...)` do exactly the same thing. The `.ev` property is just an alias for the client itself — use whichever style you prefer.
+
+---
+
+### Minimal Working Bot
+
+The smallest complete bot you can write: logs in, connects to MQTT, replies "pong" to any "ping" message, and handles session expiry gracefully.
 
 ```javascript
-const { IgApiClient, RealtimeClient } = require('nodejs-insta-private-api-mqt');
-const fs = require('fs');
+const {
+  IgApiClient,
+  RealtimeClient,
+  useMultiFileAuthState,
+  GraphQLSubscriptions,
+  DisconnectReason,
+} = require('nodejs-insta-private-api-mqt');
 
-(async () => {
+async function main() {
   const ig = new IgApiClient();
-  const session = JSON.parse(fs.readFileSync('session.json'));
-  await ig.state.deserialize(session);
+  const auth = await useMultiFileAuthState('./session');
+
+  ig.state.usePresetDevice('Samsung Galaxy S25 Ultra');
+
+  if (auth.hasSession()) {
+    await auth.loadCreds(ig);
+    const valid = await auth.isSessionValid(ig).catch(() => false);
+    if (!valid) {
+      const result = await ig.login({ username: 'your_username', password: 'your_password' });
+      await auth.saveCreds(ig);
+    }
+  } else {
+    const result = await ig.login({ username: 'your_username', password: 'your_password' });
+    await auth.saveCreds(ig);
+  }
 
   const realtime = new RealtimeClient(ig);
-  const inbox = await ig.direct.getInbox();
-  
+
+  realtime.ev.on('connection.update', ({ connection, lastDisconnect }) => {
+    if (connection === 'connecting') {
+      console.log('Connecting to Instagram MQTT...');
+    } else if (connection === 'open') {
+      console.log('Connected! Bot is live.');
+    } else if (connection === 'close') {
+      const code = lastDisconnect?.error?.output?.statusCode;
+      if (code === DisconnectReason.loggedOut) {
+        console.log('Session expired. Delete the ./session folder and re-run the bot.');
+        process.exit(1);
+      } else {
+        console.log('Disconnected, will reconnect automatically...');
+      }
+    }
+  });
+
+  realtime.on('message', async (data) => {
+    const msg = data.message || data.parsed;
+    if (!msg?.text || !msg.thread_id) return;
+
+    if (msg.text.toLowerCase() === 'ping') {
+      await realtime.directCommands.sendText({ threadId: msg.thread_id, text: 'pong!' });
+    }
+  });
+
+  const userId = ig.state.cookieUserId;
   await realtime.connect({
-    graphQlSubs: ['ig_sub_direct', 'ig_sub_direct_v2_message_sync'],
-    irisData: inbox
+    graphQlSubs: [
+      userId && GraphQLSubscriptions.getDirectTypingSubscription(userId),
+      GraphQLSubscriptions.getAppPresenceSubscription(),
+      GraphQLSubscriptions.getDirectStatusSubscription(),
+    ].filter(Boolean),
+  });
+
+  await new Promise(() => {});
+}
+
+main().catch(console.error);
+```
+
+---
+
+### Production Bot — Full Lifecycle Handling
+
+A production bot needs to survive everything: sessions that expire without warning, rate limits, network drops, and server hiccups. This example shows the full setup with every disconnect reason handled and a graceful shutdown on Ctrl+C.
+
+```javascript
+const {
+  IgApiClient,
+  RealtimeClient,
+  useMultiFileAuthState,
+  GraphQLSubscriptions,
+  DisconnectReason,
+} = require('nodejs-insta-private-api-mqt');
+
+const SESSION_FOLDER = './bot_session';
+const USERNAME = 'your_username';
+const PASSWORD = 'your_password';
+
+async function startBot() {
+  const ig = new IgApiClient();
+  const auth = await useMultiFileAuthState(SESSION_FOLDER);
+
+  ig.state.usePresetDevice('Samsung Galaxy S25 Ultra');
+
+  // Restore or create session
+  if (auth.hasSession()) {
+    await auth.loadCreds(ig);
+    const valid = await auth.isSessionValid(ig).catch(() => false);
+    if (!valid) {
+      console.log('Session expired, logging in again...');
+      const result = await ig.login({ username: USERNAME, password: PASSWORD });
+      await auth.saveCreds(ig);
+      console.log('Logged in, session saved.');
+    } else {
+      console.log('Session restored.');
+    }
+  } else {
+    console.log('No session found, logging in...');
+    const result = await ig.login({ username: USERNAME, password: PASSWORD });
+    await auth.saveCreds(ig);
+    console.log('Logged in, session saved.');
+  }
+
+  const realtime = new RealtimeClient(ig);
+  const userId = ig.state.cookieUserId;
+
+  // Connection lifecycle — this is how you react to every state change
+  realtime.ev.on('connection.update', ({ connection, lastDisconnect, isNewLogin }) => {
+    if (connection === 'connecting') {
+      console.log('[BOT] Connecting...');
+      return;
+    }
+
+    if (connection === 'open') {
+      console.log(`[BOT] Connected${isNewLogin ? ' (first login)' : ''}`);
+      return;
+    }
+
+    if (connection === 'close') {
+      const code = lastDisconnect?.error?.output?.statusCode;
+      const msg  = lastDisconnect?.error?.message;
+
+      switch (code) {
+        case DisconnectReason.loggedOut:
+          // Instagram invalidated the session — must log in fresh
+          console.error('[BOT] Logged out by Instagram. Delete session and re-run.');
+          process.exit(1);
+          break;
+
+        case DisconnectReason.rateLimited:
+          // Too many requests — library backs off automatically
+          console.warn('[BOT] Rate limited. Backing off before next reconnect...');
+          break;
+
+        case DisconnectReason.connectionClosed:
+          // You called realtime.disconnect() — expected
+          console.log('[BOT] Disconnected intentionally.');
+          break;
+
+        case DisconnectReason.timedOut:
+          // Keepalive ping failed — library will reconnect
+          console.warn('[BOT] Connection timed out, reconnecting...');
+          break;
+
+        case DisconnectReason.reconnectFailed:
+          // All retry attempts exhausted
+          console.error(`[BOT] Reconnect failed after all attempts: ${msg}`);
+          process.exit(1);
+          break;
+
+        default:
+          // Network drop, server error, etc. — library auto-reconnects
+          console.warn(`[BOT] Disconnected (code ${code}): ${msg}`);
+      }
+    }
+  });
+
+  // Fires when the library successfully reconnects after a drop
+  realtime.on('reconnected', ({ attempt }) => {
+    console.log(`[BOT] Reconnected on attempt #${attempt}`);
   });
 
-  console.log('Bot Active\n');
+  // Fires when all reconnect attempts have been exhausted
+  realtime.on('reconnect_failed', ({ attempts, lastErrorType }) => {
+    console.error(`[BOT] Failed to reconnect after ${attempts} attempts. Last error type: ${lastErrorType}`);
+    process.exit(1);
+  });
+
+  // Fires after 3+ consecutive auth failures
+  realtime.on('auth_failure', ({ count }) => {
+    console.error(`[BOT] Auth failed ${count} times in a row. Session is probably expired.`);
+  });
+
+  // Non-fatal warnings (bad payload, unknown topic, etc.)
+  realtime.on('warning', (w) => {
+    console.warn('[BOT] Warning:', w?.message || w);
+  });
 
+  // Incoming DMs
   realtime.on('message', async (data) => {
-    const msg = data.message;
-    if (!msg?.text) return;
+    const msg = data.message || data.parsed;
+    if (!msg?.text || !msg.thread_id) return;
 
-    console.log(`[${msg.from_user_id}]: ${msg.text}`);
+    const threadId = msg.thread_id;
+    const itemId   = msg.item_id || msg.messageId;
+    const text     = msg.text.trim();
 
-    if (msg.text.toLowerCase().includes('hello')) {
-      await realtime.directCommands.sendText({
-        threadId: msg.thread_id,
-        text: 'Hey! Thanks for reaching out!'
-      });
+    // Mark as seen
+    if (itemId) {
+      await realtime.directCommands.markAsSeen({ threadId, itemId }).catch(() => {});
+    }
+
+    console.log(`[MSG] ${msg.from_user_id || msg.userId}: "${text}"`);
+
+    if (text.toLowerCase() === 'ping') {
+      await realtime.directCommands.sendText({ threadId, text: 'pong!' });
     }
   });
 
+  // Typing indicators
+  realtime.on('typing', (data) => {
+    console.log(`[TYPING] Thread ${data?.thread_id || data?.threadId}`);
+  });
+
+  // Fetch inbox for iris data (needed for full message sync)
+  let irisData = null;
+  try {
+    irisData = await ig.request.send({ url: '/api/v1/direct_v2/inbox/', method: 'GET' });
+  } catch (_) {}
+
+  // Connect with subscriptions
+  await realtime.connect({
+    irisData: irisData || undefined,
+    graphQlSubs: [
+      userId && GraphQLSubscriptions.getDirectTypingSubscription(userId),
+      GraphQLSubscriptions.getAppPresenceSubscription(),
+      GraphQLSubscriptions.getDirectStatusSubscription(),
+      userId && GraphQLSubscriptions.getAsyncAdSubscription(userId),
+      GraphQLSubscriptions.getClientConfigUpdateSubscription(),
+    ].filter(Boolean),
+  });
+
+  console.log('[BOT] Bot is running. Send it a DM to test.');
+
+  // Graceful shutdown
+  process.on('SIGINT', () => {
+    console.log('[BOT] Shutting down...');
+    realtime.disconnect();
+    process.exit(0);
+  });
+
   await new Promise(() => {});
-})();
+}
+
+startBot().catch(console.error);
 ```
 
-### Smart Bot with Reactions and Typing
+---
+
+### Smart Bot with Typing, Read Receipts, and Reactions
+
+This pattern is what makes a bot feel human: mark the message as seen right away, show a typing indicator while "thinking", send the reply, then react to the original message.
 
 ```javascript
 realtime.on('message', async (data) => {
-  const msg = data.message;
-  if (!msg?.text) return;
+  const msg = data.message || data.parsed;
+  if (!msg?.text || !msg.thread_id) return;
 
-  // Mark as seen
-  await realtime.directCommands.markAsSeen({
-    threadId: msg.thread_id,
-    itemId: msg.item_id
-  });
+  const threadId = msg.thread_id;
+  const itemId   = msg.item_id || msg.messageId;
+  const text     = msg.text.toLowerCase().trim();
 
-  // Show typing
-  await realtime.directCommands.indicateActivity({
-    threadId: msg.thread_id,
-    isActive: true
-  });
+  // 1. Mark as seen immediately (sender sees blue "Seen")
+  if (itemId) {
+    await realtime.directCommands.markAsSeen({ threadId, itemId }).catch(() => {});
+  }
+
+  // 2. Show typing indicator
+  await realtime.directCommands.indicateActivity({ threadId, isActive: true });
 
-  await new Promise(r => setTimeout(r, 2000));
+  // 3. Small delay to look human
+  await new Promise(r => setTimeout(r, 1500 + Math.random() * 1500));
 
-  if (msg.text.toLowerCase().includes('hi')) {
+  // 4. Send reply based on message content
+  if (text === 'hi' || text === 'hello' || text === 'hey') {
+    await realtime.directCommands.sendText({ threadId, text: 'Hey! What can I do for you?' });
+
+    // React to the greeting
+    if (itemId) {
+      await realtime.directCommands.sendReaction({
+        threadId,
+        itemId,
+        reactionType: 'emoji',
+        emoji: '👋',
+      });
+    }
+  } else if (text === 'ping') {
+    await realtime.directCommands.sendText({ threadId, text: 'pong!' });
+  } else if (text === 'status') {
     await realtime.directCommands.sendText({
-      threadId: msg.thread_id,
-      text: 'Hello there!'
+      threadId,
+      text: `I'm online. MQTT connected: ${realtime._mqttConnected ? 'yes' : 'no'}`,
     });
-
-    // React with emoji
-    await realtime.directCommands.sendReaction({
-      threadId: msg.thread_id,
-      itemId: msg.item_id,
-      emoji: '👋'
+  } else {
+    // Default reply
+    await realtime.directCommands.sendText({
+      threadId,
+      text: "I got your message! I don't know how to respond to that yet.",
     });
   }
 
-  // Stop typing
-  await realtime.directCommands.indicateActivity({
-    threadId: msg.thread_id,
-    isActive: false
-  });
+  // 5. Stop typing indicator
+  await realtime.directCommands.indicateActivity({ threadId, isActive: false });
 });
 ```
 
 ---
 
+### Checking the Disconnect Reason Programmatically
+
+When the connection drops, `lastDisconnect.error.output.statusCode` gives you a numeric code. The `DisconnectReason` enum maps every code to a human-readable name so you don't have to remember the numbers:
+
+```javascript
+const { DisconnectReason } = require('nodejs-insta-private-api-mqt');
+
+realtime.ev.on('connection.update', ({ connection, lastDisconnect }) => {
+  if (connection !== 'close') return;
+
+  const code = lastDisconnect?.error?.output?.statusCode;
+  const message = lastDisconnect?.error?.message;
+  const when = lastDisconnect?.date;
+
+  console.log('Disconnected at:', when?.toISOString());
+  console.log('Reason code:', code);
+  console.log('Message:', message);
+
+  if (code === DisconnectReason.loggedOut) {
+    // 401 — Instagram says your session is invalid
+    // Only fix: delete the session folder and log in again
+    console.log('Need to re-login');
+
+  } else if (code === DisconnectReason.rateLimited) {
+    // 429 — sent too many requests too fast
+    // The library automatically applies a longer backoff for rate limits
+
+  } else if (code === DisconnectReason.connectionLost) {
+    // 408 — connection dropped with no specific reason
+    // This is the most common disconnect — usually just a network blip
+
+  } else if (code === DisconnectReason.connectionClosed) {
+    // 428 — you called realtime.disconnect() intentionally
+
+  } else if (code === DisconnectReason.timedOut) {
+    // 504 — MQTT keepalive ping timed out
+
+  } else if (code === DisconnectReason.networkError) {
+    // 503 — ECONNRESET, ETIMEDOUT, DNS failure, etc.
+
+  } else if (code === DisconnectReason.protocolError) {
+    // 500 — Thrift or MQTT parsing failed
+
+  } else if (code === DisconnectReason.serverError) {
+    // 502 — Instagram server returned a 5xx
+
+  } else if (code === DisconnectReason.reconnectFailed) {
+    // 503 — all automatic reconnect attempts were exhausted
+    process.exit(1);
+  }
+});
+```
+
+**All DisconnectReason values at a glance:**
+
+| Name | Code | When it happens |
+|------|------|-----------------|
+| `loggedOut` | 401 | Session invalid — fresh login required |
+| `rateLimited` | 429 | Too many requests — library backs off automatically |
+| `connectionLost` | 408 | Unexpected drop, no specific error info |
+| `connectionClosed` | 428 | You called `disconnect()` yourself |
+| `timedOut` | 504 | MQTT ping/keepalive timeout |
+| `networkError` | 503 | ECONNRESET, ETIMEDOUT, or DNS failure |
+| `protocolError` | 500 | Thrift or MQTT parse error |
+| `serverError` | 502 | Instagram returned a 5xx response |
+| `reconnectFailed` | 503 | All auto-reconnect attempts exhausted |
+
+---
+
+### Using startRealTimeListener() (Simpler Connect Method)
+
+`startRealTimeListener()` is a convenience wrapper around `connect()` that automatically builds the recommended set of GraphQL subscriptions for you. It also accepts optional health monitor and logger config:
+
+```javascript
+const realtime = new RealtimeClient(ig);
+
+realtime.ev.on('connection.update', ({ connection, lastDisconnect }) => {
+  // same as above
+});
+
+realtime.on('message', async (data) => {
+  // handle incoming DMs
+});
+
+// Simplest connect — auto-builds subscriptions
+await realtime.startRealTimeListener();
+
+// Or with health monitoring and file logging enabled:
+await realtime.startRealTimeListener({
+  credentials: { username: 'your_username', password: 'your_password' },
+  enablePersistentLogger: true,
+  logDir: './mqtt-logs',
+});
+```
+
+The health monitor periodically calls `/api/v1/accounts/current_user/` to check if the session is still valid and automatically re-logs in if it detects expiry. The persistent logger writes all MQTT events to rotating files in `logDir`, which is useful for debugging disconnects that happen when you're not watching.
+
+---
+
+### Session Health Events
+
+When the health monitor is enabled, these additional events fire on `realtime`:
+
+```javascript
+realtime.on('health_check', ({ status, stats }) => {
+  // status: 'ok' or 'failed'
+  // stats: { totalUptimeHuman, uptimePercent, reconnects, ... }
+  console.log(`Health: ${status}, uptime: ${stats.totalUptimeHuman}`);
+});
+
+realtime.on('session_expired', () => {
+  console.log('Session detected as expired by health monitor');
+});
+
+realtime.on('relogin_success', () => {
+  console.log('Automatically re-logged in after session expiry');
+});
+
+realtime.on('relogin_failed', ({ error }) => {
+  console.error('Auto re-login failed:', error?.message);
+});
+```
+
+You can also pull stats at any time:
+
+```javascript
+const health = realtime.getHealthStats();
+console.log('Uptime:', health.uptimePercent + '%');
+console.log('Reconnects so far:', health.reconnects);
+console.log('Session started:', health.sessionStart);
+```
+
+---
+
 ## Session Management
 
-### Multi-File Auth State (Baileys Style)
+### Multi-File Auth State
 
 ```javascript
 const authState = await useMultiFileAuthState('./auth_folder');
@@ -2565,10 +2933,144 @@ Here's every repository and what it covers at a glance.
 
 ---
 
+### connection.update — Unified Connection State Event
+
+All three clients (`RealtimeClient`, `FbnsClient`, `MQTToTClient`) emit a `connection.update` event whenever the connection state changes. Each client also exposes an `ev` property that is an alias for itself, so both `client.on(...)` and `client.ev.on(...)` work identically.
+
+**Event shape:**
+
+```typescript
+{
+  connection: 'connecting' | 'open' | 'close';
+  lastDisconnect?: {
+    error: BoomError;   // @hapi/boom wrapped error
+    date: Date;
+  };
+  isNewLogin?: boolean; // true on the first successful connect (RealtimeClient only)
+}
+```
+
+**Usage with RealtimeClient:**
+
+```javascript
+const { RealtimeClient } = require('nodejs-insta-private-api-mqt');
+
+const realtime = new RealtimeClient(ig);
+
+// Both forms work identically:
+realtime.on('connection.update', (update) => {
+  const { connection, lastDisconnect } = update;
+  if (connection === 'connecting') {
+    // attempting to connect
+  } else if (connection === 'open') {
+    console.log('Connected');
+  } else if (connection === 'close') {
+    const statusCode = lastDisconnect?.error?.output?.statusCode;
+    const message = lastDisconnect?.error?.message;
+    console.log('Disconnected:', statusCode, message);
+  }
+});
+
+// Using .ev alias:
+realtime.ev.on('connection.update', ({ connection }) => {
+  console.log('State:', connection);
+});
+
+await realtime.connect({ /* options */ });
+```
+
+**Usage with FbnsClient:**
+
+```javascript
+const fbns = ig.fbns; // or new FbnsClient(ig)
+
+fbns.ev.on('connection.update', ({ connection, lastDisconnect }) => {
+  if (connection === 'open') {
+    console.log('FBNS connected');
+  } else if (connection === 'close') {
+    console.log('FBNS disconnected:', lastDisconnect?.error?.message);
+  }
+});
+```
+
+**Inspecting the Boom error:**
+
+```javascript
+realtime.ev.on('connection.update', ({ connection, lastDisconnect }) => {
+  if (connection === 'close' && lastDisconnect) {
+    const err = lastDisconnect.error;
+    console.log(err.message);                       // human-readable message
+    console.log(err.output.statusCode);             // HTTP status code (503, 408, etc.)
+    console.log(err.isBoom);                        // always true
+    console.log(lastDisconnect.date.toISOString()); // when the disconnect happened
+  }
+});
+```
+
+**DisconnectReason — structured disconnect codes:**
+
+The library exports a `DisconnectReason` enum so you can branch on the precise cause without string-matching error messages:
+
+```javascript
+const { DisconnectReason } = require('nodejs-insta-private-api-mqt');
+
+realtime.on('connection.update', ({ connection, lastDisconnect }) => {
+  if (connection !== 'close') return;
+
+  const code = lastDisconnect?.error?.output?.statusCode;
+
+  switch (code) {
+    case DisconnectReason.loggedOut:
+      // Credentials expired — re-login required
+      break;
+    case DisconnectReason.rateLimited:
+      // Too many requests — back off before reconnecting
+      break;
+    case DisconnectReason.connectionLost:
+    case DisconnectReason.networkError:
+      // Network drop — library will auto-reconnect
+      break;
+    case DisconnectReason.connectionClosed:
+      // You called disconnect() intentionally
+      break;
+    case DisconnectReason.reconnectFailed:
+      // All reconnect attempts exhausted
+      break;
+    case DisconnectReason.timedOut:
+      // MQTT keepalive / ping timeout
+      break;
+    case DisconnectReason.protocolError:
+      // Thrift/MQTT parse error
+      break;
+    case DisconnectReason.serverError:
+      // Instagram backend returned 5xx
+      break;
+  }
+});
+```
+
+**Full DisconnectReason reference:**
+
+| Key | HTTP status code | When it fires |
+|-----|-----------------|---------------|
+| `loggedOut` | 401 | Auth / session invalid — re-login required |
+| `rateLimited` | 429 | Instagram rate-limited the connection |
+| `connectionLost` | 408 | Unexpected connection drop (no error info) |
+| `connectionClosed` | 428 | You called `disconnect()` intentionally |
+| `timedOut` | 504 | MQTT keepalive / ping failure |
+| `networkError` | 503 | Network-level failure (ECONNRESET, ETIMEDOUT…) |
+| `protocolError` | 500 | Thrift / MQTT protocol parse error |
+| `serverError` | 502 | Instagram backend returned a 5xx response |
+| `reconnectFailed` | 503 | All automatic reconnect attempts exhausted |
+| `unknown` | 500 | Unclassified error |
+
+---
+
 ### RealtimeClient Events
 
 | Event | Description |
 |-------|-------------|
+| `connection.update` | Connection state changed (`connecting` / `open` / `close`) |
 | `connected` | MQTT connected |
 | `disconnected` | MQTT disconnected |
 | `message` | New message received |
@@ -2656,60 +3158,130 @@ realtime.on('liveRealtimeComments', (data) => {
 
 #### Complete Example: Multi-Event Listener
 
-Here's a complete example showing how to listen to multiple events:
+A full bot that uses every major event — connection lifecycle, messages, typing, presence, and raw MQTT data for debugging. This is a good starting template to copy and trim down to what you actually need.
 
 ```javascript
-const { IgApiClient, RealtimeClient, useMultiFileAuthState } = require('nodejs-insta-private-api-mqt');
+const {
+  IgApiClient,
+  RealtimeClient,
+  useMultiFileAuthState,
+  GraphQLSubscriptions,
+  DisconnectReason,
+} = require('nodejs-insta-private-api-mqt');
 
 async function startAdvancedBot() {
   const ig = new IgApiClient();
   const auth = await useMultiFileAuthState('./auth_info_ig');
-  
+
   ig.state.usePresetDevice('Samsung Galaxy S25 Ultra');
-  
+
+  if (auth.hasSession()) {
+    await auth.loadCreds(ig);
+    const valid = await auth.isSessionValid(ig).catch(() => false);
+    if (!valid) {
+      const result = await ig.login({ username: 'your_username', password: 'your_password' });
+      await auth.saveCreds(ig);
+    }
+  } else {
+    const result = await ig.login({ username: 'your_username', password: 'your_password' });
+    await auth.saveCreds(ig);
+  }
+
   const realtime = new RealtimeClient(ig);
+  const userId = ig.state.cookieUserId;
+
+  // Connection lifecycle — fires on every state change
+  realtime.ev.on('connection.update', ({ connection, lastDisconnect, isNewLogin }) => {
+    if (connection === 'connecting') {
+      console.log('[CONN] Connecting...');
+    } else if (connection === 'open') {
+      console.log(`[CONN] Connected${isNewLogin ? ' (new session)' : ''}`);
+    } else if (connection === 'close') {
+      const code = lastDisconnect?.error?.output?.statusCode;
+      const msg  = lastDisconnect?.error?.message;
+
+      if (code === DisconnectReason.loggedOut) {
+        console.error('[CONN] Session invalid — need to re-login');
+        process.exit(1);
+      } else if (code === DisconnectReason.rateLimited) {
+        console.warn('[CONN] Rate limited, backing off...');
+      } else if (code === DisconnectReason.reconnectFailed) {
+        console.error('[CONN] All reconnect attempts failed:', msg);
+        process.exit(1);
+      } else {
+        console.warn(`[CONN] Disconnected (${code}): ${msg}`);
+      }
+    }
+  });
 
-  // Standard message handling
+  realtime.on('reconnected', ({ attempt }) => {
+    console.log(`[CONN] Reconnected on attempt #${attempt}`);
+  });
+
+  // Standard parsed message
   realtime.on('message_live', (msg) => {
-    console.log(`[${msg.username}]: ${msg.text}`);
+    if (msg?.text) {
+      console.log(`[MSG] ${msg.username || msg.userId}: "${msg.text}"`);
+    }
   });
 
-  // Advanced: Raw MQTT data (useful for debugging)
-  realtime.on('realtimeSub', ({ data }) => {
-    console.log('[Debug] Raw MQTT:', JSON.stringify(data).substring(0, 200));
+  // Full message with raw data (catches all item types)
+  realtime.on('message', async (data) => {
+    const msg = data.message || data.parsed;
+    if (!msg?.thread_id) return;
+
+    const threadId = msg.thread_id;
+    const text = msg.text?.toLowerCase().trim();
+
+    if (text === 'ping') {
+      await realtime.directCommands.sendText({ threadId, text: 'pong!' });
+    }
   });
 
-  // Direct message updates with parsed data
+  // Direct message patch operations (add/replace/remove on thread items)
   realtime.on('direct', (data) => {
     if (data.op === 'add') {
-      console.log('[Direct] New item added');
+      console.log('[DIRECT] New item in thread');
+    } else if (data.op === 'remove') {
+      console.log('[DIRECT] Item removed from thread');
     }
   });
 
   // Typing indicators
   realtime.on('directTyping', (data) => {
-    console.log('[Typing] Someone is typing...');
+    console.log('[TYPING] Someone is typing...');
   });
 
   // User presence (online/offline)
   realtime.on('appPresence', (data) => {
-    console.log('[Presence] User status changed');
+    console.log('[PRESENCE] User status changed:', data?.user_id);
   });
 
-  // Login and connect
-  if (!auth.hasSession()) {
-    await ig.login({
-      username: 'your_username',
-      password: 'your_password'
-    });
-    await auth.saveCreds(ig);
-  } else {
-    await auth.loadCreds(ig);
-  }
+  // Raw MQTT — useful for debugging unknown events
+  realtime.on('realtimeSub', ({ data, topic }) => {
+    // Only uncomment this when debugging — it's very noisy
+    // console.log('[RAW MQTT]', topic, JSON.stringify(data).substring(0, 100));
+  });
 
-  await realtime.startRealTimeListener();
-  
-  console.log('Advanced bot with full MQTT events is running!');
+  // Connect with full subscription set
+  await realtime.connect({
+    graphQlSubs: [
+      userId && GraphQLSubscriptions.getDirectTypingSubscription(userId),
+      GraphQLSubscriptions.getAppPresenceSubscription(),
+      GraphQLSubscriptions.getDirectStatusSubscription(),
+      userId && GraphQLSubscriptions.getAsyncAdSubscription(userId),
+      GraphQLSubscriptions.getClientConfigUpdateSubscription(),
+    ].filter(Boolean),
+  });
+
+  console.log('[BOT] All event listeners active. Send a DM to test.');
+
+  process.on('SIGINT', () => {
+    realtime.disconnect();
+    process.exit(0);
+  });
+
+  await new Promise(() => {});
 }
 
 startAdvancedBot().catch(console.error);
@@ -2771,29 +3343,47 @@ All delays include random jitter (0-2s) to prevent multiple bots from hammering
 
 ### Listening for Error Events
 
+The cleanest way to handle all error scenarios is through `connection.update` with `DisconnectReason`. But there are also a few standalone error events that fire in specific situations:
+
 ```javascript
-const { IgApiClient, RealtimeClient } = require('nodejs-insta-private-api-mqt');
+const { IgApiClient, RealtimeClient, DisconnectReason } = require('nodejs-insta-private-api-mqt');
 
 const ig = new IgApiClient();
 const realtime = new RealtimeClient(ig);
 
-// fires after 3 consecutive auth failures - probably time to re-login
+// The main lifecycle hook — every disconnect comes through here with a reason code
+realtime.ev.on('connection.update', ({ connection, lastDisconnect }) => {
+  if (connection !== 'close') return;
+
+  const code = lastDisconnect?.error?.output?.statusCode;
+
+  if (code === DisconnectReason.loggedOut) {
+    // Session is dead — only a fresh login can fix this
+    console.log('Session expired, logging in again...');
+    // re-login logic here
+  } else if (code === DisconnectReason.rateLimited) {
+    console.log('Rate limited — the library is backing off automatically');
+  } else if (code === DisconnectReason.reconnectFailed) {
+    console.log('All reconnect attempts exhausted');
+    process.exit(1);
+  }
+});
+
+// Fires after 3+ consecutive auth failures — session is almost certainly dead
 realtime.on('auth_failure', ({ count, error }) => {
-  console.log(`Auth failed ${count} times: ${error}`);
-  console.log('Session is probably expired, need to login again');
-  // your re-login logic here
+  console.log(`Auth failed ${count} times in a row: ${error}`);
+  console.log('Session expired — need to log in again');
 });
 
-// fires when all 15 retry attempts are used up
+// Fires for unexpected low-level errors
 realtime.on('error', (err) => {
-  if (err.message.includes('Max retries')) {
-    console.log('Gave up reconnecting. Maybe restart the process.');
-  }
+  console.error('MQTT error:', err?.message || err);
 });
 
-// non-fatal stuff - good to log but usually not actionable
-realtime.on('warning', ({ type, topic, error }) => {
-  console.log(`Warning [${type}] on ${topic}: ${error}`);
+// Non-fatal issues — payload parse errors, unknown topics, etc.
+// Good to log for debugging, usually not actionable
+realtime.on('warning', (w) => {
+  console.warn('Warning:', w?.message || w);
 });
 ```
 
@@ -2825,13 +3415,27 @@ The `ReconnectManager` works together with the error handler. When the connectio
 All delays include up to 30% jitter so if you're running multiple bots they don't all reconnect at the exact same second.
 
 ```javascript
-realtime.on('reconnected', () => {
-  console.log('Back online after a disconnect');
+realtime.ev.on('connection.update', ({ connection, lastDisconnect }) => {
+  if (connection === 'open') {
+    console.log('Back online');
+  }
+
+  if (connection === 'close') {
+    const code = lastDisconnect?.error?.output?.statusCode;
+    // DisconnectReason.reconnectFailed (503) means all attempts are used up
+    if (code === DisconnectReason.reconnectFailed) {
+      console.log('Could not reconnect after all attempts');
+      // restart the process, send yourself a notification, etc.
+    }
+  }
 });
 
-realtime.on('reconnect_failed', () => {
-  console.log('Could not reconnect after all attempts');
-  // maybe send yourself a notification, restart the process, etc.
+realtime.on('reconnected', ({ attempt }) => {
+  console.log(`Back online after ${attempt} attempt(s)`);
+});
+
+realtime.on('reconnect_failed', ({ attempts, lastErrorType }) => {
+  console.log(`Gave up after ${attempts} attempts. Last error type: ${lastErrorType}`);
 });
 ```
 
@@ -3060,6 +3664,19 @@ async function startFbns() {
   // create the FBNS client and wire up events
   const fbns = new FbnsClient(ig);
 
+  // Connection lifecycle — same pattern as RealtimeClient
+  fbns.ev.on('connection.update', ({ connection, lastDisconnect }) => {
+    if (connection === 'connecting') {
+      console.log('FBNS connecting...');
+    } else if (connection === 'open') {
+      console.log('FBNS connected, push notifications active');
+    } else if (connection === 'close') {
+      const code = lastDisconnect?.error?.output?.statusCode;
+      const msg  = lastDisconnect?.error?.message;
+      console.log(`FBNS disconnected (${code}): ${msg}`);
+    }
+  });
+
   fbns.on('push', (notification) => {
     console.log('Got push notification!');
     console.log('Title:', notification.title);
@@ -3067,10 +3684,6 @@ async function startFbns() {
     console.log('Type:', notification.collapseKey);
   });
 
-  fbns.on('error', (err) => {
-    console.error('FBNS error:', err.message);
-  });
-
   // connect - this handles everything: TLS handshake, device auth,
   // token registration, and push subscription
   await fbns.connect();
@@ -3150,7 +3763,14 @@ fbns.on('push', (notification) => {
 You can run both FBNS (push notifications) and RealtimeClient (DM messaging) side by side. They use different MQTT connections - Realtime connects to `edge-mqtt.facebook.com` for DMs, while FBNS connects to `mqtt-mini.facebook.com` for push notifications.
 
 ```javascript
-const { IgApiClient, RealtimeClient, FbnsClient, useMultiFileAuthState } = require('nodejs-insta-private-api-mqt');
+const {
+  IgApiClient,
+  RealtimeClient,
+  FbnsClient,
+  useMultiFileAuthState,
+  GraphQLSubscriptions,
+  DisconnectReason,
+} = require('nodejs-insta-private-api-mqt');
 
 async function startBot() {
   const ig = new IgApiClient();
@@ -3160,26 +3780,75 @@ async function startBot() {
 
   if (auth.hasSession()) {
     await auth.loadCreds(ig);
+    const valid = await auth.isSessionValid(ig).catch(() => false);
+    if (!valid) {
+      const result = await ig.login({ username: 'your_username', password: 'your_password' });
+      await auth.saveCreds(ig);
+    }
   } else {
-    await ig.login({ username: 'your_username', password: 'your_password' });
+    const result = await ig.login({ username: 'your_username', password: 'your_password' });
     await auth.saveCreds(ig);
   }
 
-  // start realtime for DMs
+  const userId = ig.state.cookieUserId;
+
+  // Realtime MQTT for DMs
   const realtime = new RealtimeClient(ig);
+
+  realtime.ev.on('connection.update', ({ connection, lastDisconnect }) => {
+    if (connection === 'open') {
+      console.log('[REALTIME] Connected');
+    } else if (connection === 'close') {
+      const code = lastDisconnect?.error?.output?.statusCode;
+      if (code === DisconnectReason.loggedOut) {
+        console.error('[REALTIME] Session expired — re-login required');
+        process.exit(1);
+      } else {
+        console.warn(`[REALTIME] Disconnected (${code}), reconnecting...`);
+      }
+    }
+  });
+
   realtime.on('message_live', (msg) => {
-    console.log(`DM from ${msg.username}: ${msg.text}`);
+    if (msg?.text) {
+      console.log(`[DM] ${msg.username}: ${msg.text}`);
+    }
   });
-  await realtime.startRealTimeListener();
 
-  // start FBNS for push notifications
+  await realtime.connect({
+    graphQlSubs: [
+      userId && GraphQLSubscriptions.getDirectTypingSubscription(userId),
+      GraphQLSubscriptions.getAppPresenceSubscription(),
+      GraphQLSubscriptions.getDirectStatusSubscription(),
+    ].filter(Boolean),
+  });
+
+  // FBNS for push notifications
   const fbns = new FbnsClient(ig);
+
+  fbns.ev.on('connection.update', ({ connection, lastDisconnect }) => {
+    if (connection === 'open') {
+      console.log('[FBNS] Connected, push notifications active');
+    } else if (connection === 'close') {
+      const code = lastDisconnect?.error?.output?.statusCode;
+      console.warn(`[FBNS] Disconnected (${code}): ${lastDisconnect?.error?.message}`);
+    }
+  });
+
   fbns.on('push', (notif) => {
-    console.log(`Push [${notif.collapseKey}]:`, notif.message || notif.title);
+    console.log(`[PUSH] [${notif.collapseKey}]`, notif.message || notif.title);
   });
+
   await fbns.connect();
 
   console.log('Both Realtime and FBNS are running!');
+
+  process.on('SIGINT', async () => {
+    realtime.disconnect();
+    await fbns.disconnect();
+    process.exit(0);
+  });
+
   await new Promise(() => {});
 }
 
@@ -3491,7 +4160,7 @@ console.log(`Uptime: ${stats.uptimePercent}%, ${stats.reconnects} reconnects`);
 - switchPlatform() for easy platform switching
 
 ### v5.60.8
-- downloadContentFromMessage() - Baileys-style media download
+- downloadContentFromMessage() - Persistent media download from DM messages
 - View-once media extraction support
 - downloadMediaBuffer() and extractMediaUrls()
 
@@ -3503,7 +4172,7 @@ console.log(`Uptime: ${stats.uptimePercent}%, ${stats.reconnects} reconnects`);
 - sendPhoto() and sendVideo() for media uploads
 
 ### v5.60.2
-- useMultiFileAuthState() - Baileys-style session persistence
+- useMultiFileAuthState() - Multi-file session persistence
 - connectFromSavedSession() method
 
 ### v5.60.0