@eryxenx/insta-chat 2.0.11 → 2.1.1

package/CHANGELOG.md

@@ -4,6 +4,60 @@ All notable changes to `@eryxenx/insta-chat` are documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/) and uses
 [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+## [2.1.0] - 2026-10-14
+
+### Added
+
+- **Realtime MQTT listening.** `listen()` can now receive DMs over Instagram's
+  realtime broker (`edge-mqtt.facebook.com`) instead of polling the inbox, so
+  replies are pushed the moment Instagram delivers them. Opt in with
+  `login(cookie, { realtime: { enabled: true } })`; the callback and event shape
+  are identical to polling, and a broker that will not connect falls back to the
+  poller (unless `realtime.fallback` is `false`).
+  - `src/realtime/mqttot.js` — a dependency-free MQTToT codec: the Thrift-compact
+    CONNECT struct, MQTT packet framing, zlib payloads and a TLS transport.
+  - `src/realtime/client.js` — `RealtimeClient`: cookie-auth connect, keepalive,
+    and decoding of message-sync (`/direct_v2/threads/<id>/items/<id>`) and
+    realtime-sub payloads into `message`, `typing`, `seen` and `presence` events.
+  - `src/realtime/bridge.js` — turns a message-sync patch into the same raw inbox
+    event the poller produces, so `EventNormalizer` is unchanged.
+  - `src/realtime/listener.js` — `RealtimeListener`, which `listen()` drives.
+  - Native `InstaAPI` gains `realtimeClient`, `realtimeConnect`, `realtimeOn`,
+    `realtimeSubscribe`, `realtimePing`, `realtimeDisconnect`; `RealtimeClient`
+    and `RealtimeListener` are exported from the package root.
+- `examples/realtime-bot.js` — the tiny DM bot over realtime push.
+- `test/realtime.test.js` — codec, bridge, dispatch and `listen()` fallback.
+- **V2 profile plugins.** `src/api/users/` gains `getUserInfoV2`,
+  `getProfilePictureV2`, `getUserProfile`, `getUserID`, `getProfileBio`,
+  `getUserFriendship` and `getSelfInfo` (FCA surface + `users` / `account`
+  namespaces). `getUserInfoV2` returns the *complete* profile — username, full
+  name, biography, follower/following/media counts, verified/private/business
+  flags, external url, category, business contact and the square + HD picture —
+  not just the fca subset V1 returned. `getProfilePictureV2` returns the picture
+  at any square size (derived from the CDN `stp=` param, no extra request) plus
+  the HD original. The native `InstaAPI` gains `getUserProfile` /
+  `getProfilePicture`.
+  - `src/profileParse.js` — normalizes the `web_profile_info` REST JSON, the
+    profile GraphQL `data.user`, the HTML-embedded `PolarisViewer` blob and the
+    inbox user record into one shape, and resizes a picture URL.
+  - `test/profile.test.js` — normalization, the logout-safe resolver and the
+    plugins.
+
+### Fixed
+
+- **A profile lookup can no longer masquerade as a dead session (the logout
+  bug).** `getInfo` reads `/api/v1/users/<id>/info/`, which Instagram 302s to the
+  login page for a web session — the HTTP layer classifies any 3xx as an auth
+  failure, so any command that looked up a profile could trip the session guard
+  and log the bot out. Profile reads now go through a resolver that tries the
+  users already learned from the inbox/thread views, `web_profile_info`, the
+  profile GraphQL query and the account's own server-rendered page, and swallows
+  a 429 / 302 from any of them. It never throws and returns `null` when nothing
+  resolves. `init()` also resolves the logged-in username from the home shell
+  instead of the same 302'ing REST path.
+
 ## [2.0.10] - 2026-10-11
 
 ### Added

package/DOCS.md

@@ -47,8 +47,9 @@ commands call). Pass `{ native: true }` to get the bare `InstaAPI` instead.
 | `sessionParams` | – | Pre-harvested browser session params. |
 | `sessionParamsFile` | `./session-params.json` | Load params from disk. |
 | `deviceFile` | `./device.json` | Persisted device identity. |
-| `pollInterval` | `15000` | `listen()` poll interval (ms). |
+| `pollInterval` | `15000` | `listen()` poll interval (ms), used when realtime is off. |
 | `minPollIntervalMs` | `15000` | Lowest interval `listen()` will honour (floor, min 2000). |
+| `realtime` | – | `{ enabled, fallback, host, keepAliveMs }` — realtime MQTT push for `listen()`. |
 
 ## `InstaClient` (FCA surface)
 
@@ -60,9 +61,9 @@ Facebook-Chat-API shape. Its methods live one-per-file under
 |-------|---------|
 | messaging | `sendMessage(form, threadID, cb?, replyToMessage?)`, `sendMessageSync`, `editMessage(text, messageID)`, `unsendMessage(messageID, cb?, threadID?)`, `setMessageReaction(emoji, messageID, cb?, threadID?)`, `sendTypingIndicator`, `markAsRead`, `shareContact`, `resolvePhotoUrl` |
 | threads | `getThreadInfo`, `getThreadList`, `getThreadHistory` |
-| users | `getUserInfo`, `getUID`, `getProfilePictureUrl` |
-| account | `getCurrentUserID`, `getAppState`, `getCookies`, `setOptions` |
-| realtime | `listen`, `stopListening`, `getInbox` |
+| users | `getUserInfo`, `getUserInfoV2`, `getUserProfile`, `getProfilePictureV2`, `getProfileBio`, `getUserFriendship`, `getUserID`, `getUID`, `getProfilePictureUrl` |
+| account | `getCurrentUserID`, `getSelfInfo`, `getAppState`, `getCookies`, `setOptions` |
+| realtime | `listen`, `stopListening`, `getInbox`, `realtimeConnect`, `realtimeOn`, `realtimeSubscribe`, `realtimePing`, `realtimeDisconnect` |
 | media | `sendPhoto`, `sendPhotoFromUrl`, `sendVideoFromUrl`, `sendVoiceFromUrl` |
 
 Group-management calls Instagram DMs cannot do (`changeNickname`, `setTitle`,
@@ -135,15 +136,53 @@ All take `(threadID, source, options)` where `options = { filename, text }`.
 
 ### Users
 
-`getUserInfo(userID)`, `getUserInfoByUsername(username)`, `searchUsers(query, limit)`.
+`getUserInfo(userID)`, `getUserInfoByUsername(username)`, `searchUsers(query, limit)`,
+`getUserProfile(idOrUsername, opts?)`, `getProfilePicture(idOrUsername, opts?)`.
+
+`getUserProfile` returns the complete merged profile (see
+`README.md` -> *Full profiles*): id, username, full name, biography,
+follower/following/media counts, verified/private/business flags, external url,
+category, business contact, `profilePicUrl` and `profilePicUrlHd`. It is
+logout-safe — it merges the users learned from the inbox/thread views with
+`web_profile_info`, the profile GraphQL query and the account's own page, and
+swallows a 429 / 302 from any source, so a profile read never trips the session
+guard. Returns `null` when nothing resolves.
+
+`getProfilePicture(idOrUsername, { size })` returns the best picture URL at the
+requested square size.
 
 ### Inbox / listening
 
-`getInbox()` returns `{ threads }`. `listen(callback, intervalMs)` polls and
-emits normalized `message` events; it returns a `stop()` function.
-`stopListening()` also stops polling. The interval is raised to the client's
-`minPollIntervalMs` floor (set via the constructor options; default 15000 ms,
-minimum 2000 ms), so pass that option if you want a shorter cycle than 15 s.
+`getInbox()` returns `{ threads }`. `listen(callback, intervalMs)` emits
+normalized `message` events and returns a `stop()` function. `stopListening()`
+also stops it.
+
+By default `listen` polls the inbox; the interval is raised to the client's
+`minPollIntervalMs` floor (default 15000 ms, minimum 2000 ms). Pass
+`{ realtime: { enabled: true } }` to `login` and `listen` instead subscribes to
+Instagram's realtime MQTT stream, so each new DM is pushed the moment Instagram
+delivers it. The callback and event shape are the same either way, and a realtime
+connection that cannot be established falls back to polling unless you set
+`realtime: { enabled: true, fallback: false }`.
+
+### Realtime (MQTT)
+
+The realtime broker (`edge-mqtt.facebook.com`) is an MQTToT connection whose
+CONNECT payload is a Thrift-compact struct and whose password is
+`sessionid=<sessionid>`; the session cookie authenticates it, so there is no app
+login. Message-sync publishes (`/direct_v2/threads/<id>/items/<id>`) are decoded
+into the same raw inbox events the poller produces and normalized identically.
+
+| Method | Description |
+|--------|-------------|
+| `realtimeClient(options?)` | Build a raw `RealtimeClient` without connecting. |
+| `realtimeConnect(options?)` | Open the MQTT connection. Resolves to the client. |
+| `realtimeOn(event, handler)` | Subscribe to `message`, `typing`, `seen`, `presence`, `direct`, `receive`, `error`, `disconnected`. |
+| `realtimeSubscribe()` | Subscribe to the Direct message-sync stream (reads the cursor from the inbox query). |
+| `realtimePing()` | Send a keepalive ping. |
+| `realtimeDisconnect()` | Close the connection. |
+
+`RealtimeClient` and `RealtimeListener` are also exported from the package root.
 
 ### Event shape
 
@@ -242,7 +281,10 @@ Instagram rejects sends whose id does not decode to a recent timestamp.
 
 ## Limitations
 
-- **Polling** inbox, not MQTT — there is a short delay before events arrive.
+- **Realtime is best-effort.** `listen({ realtime: { enabled: true } })` subscribes
+  to Instagram's MQTT push stream for near-instant delivery; if the broker is
+  unreachable (or the process runs on a host that blocks it) it falls back to
+  polling. Polling has a short delay before events arrive.
 - Instagram rate-limits aggressively; keep a sane `pollInterval` and avoid
   tight send loops.
 - Only works for **personal** accounts with a valid browser session cookie.

package/README.md

@@ -23,7 +23,7 @@ your own personal account:
 
 - ✅ **Send** text, photos, videos, voice notes
 - ✅ **React**, edit and unsend messages
-- ✅ **Listen** for incoming DMs (polling) and dispatch them to your own commands
+- ✅ **Listen** for incoming DMs — realtime MQTT push or polling — and dispatch them to your own commands
 - ✅ **Typing** indicators, mark-seen, mute/unmute, hide
 - ✅ **Users** — lookup by id / username, search
 - ✅ **Pure HTTP at runtime** — no Puppeteer, no browser, no native build
@@ -111,7 +111,17 @@ go stale use `api.refreshSession()`.
 | `login(cookie, { native: true })` | Returns the bare `InstaAPI` instead. |
 | `createClient(cookie, [options])` | Alias of `login`. |
 
-`options`: `{ native, sessionParams, sessionParamsFile, deviceFile, pollInterval }`.
+`options`: `{ native, sessionParams, sessionParamsFile, deviceFile, pollInterval, minPollIntervalMs, realtime }`.
+
+To make `listen()` push instead of poll, opt into realtime MQTT:
+
+```javascript
+const api = await login(cookie, { realtime: { enabled: true } });
+```
+
+`realtime` is `{ enabled, fallback, host, keepAliveMs }`. With `fallback !== false`
+(the default) a broker that will not connect degrades to the inbox poller, so the
+bot still gets events. See [Listening](#listening).
 
 ### Two layers
 
@@ -136,6 +146,11 @@ binds a thread. `EventNormalizer` maps raw inbox events to the FCA event shape.
 | `sendTypingIndicator(threadID)` | Typing indicator. |
 | `getThreadInfo` / `getThreadList` / `getThreadHistory` | Thread reads. |
 | `getUserInfo` / `getUID` | User lookup. |
+| `getUserInfoV2(idOrIds)` | Full profile (all details) for one id or an array of ids. |
+| `getUserProfile(idOrHandle)` | The complete merged profile object. |
+| `getProfilePictureV2(idOrHandle, opts)` | Profile picture at any size (square + HD). |
+| `getProfileBio(idOrHandle)` / `getUserID(idOrHandle)` / `getUserFriendship(id)` | Bio, id, friendship state. |
+| `getSelfInfo()` | The logged-in account's own profile. |
 | `getAppState` / `getCookies` | Cookie jar. |
 
 ### Messaging (native `InstaAPI`)
@@ -173,6 +188,39 @@ binds a thread. `EventNormalizer` maps raw inbox events to the FCA event shape.
 | `muteThread` / `unmuteThread` / `hideThread` | Thread state. |
 | `getUserInfo(userID)` / `getUserInfoByUsername(username)` | User lookup. |
 | `searchUsers(query, limit)` | Search users. |
+| `getUserProfile(idOrUsername, [opts])` | Complete profile merged from every source (see below). |
+| `getProfilePicture(idOrUsername, [opts])` | Best picture URL; `opts.size` resizes via the CDN. |
+
+### Full profiles (`getUserInfoV2` / `getUserProfile`)
+
+V1 `getUserInfo` returns a small fca-shaped subset. V2 returns **every detail a
+web session can read**, and it is *logout-safe*: profile lookups go through a
+resolver that tries several sources and never turns a rate-limit (429) or a
+login redirect (302) into a dead-session error - the bug that used to log the
+bot out whenever a command looked up a profile.
+
+Sources, merged in order (a field a source cannot supply stays `null`):
+
+1. **Inbox/thread record** - the users the client has already seen in the DM
+   views. Free, needs no request, and the only source that still answers once
+   the profile REST paths 429. `getInbox()` populates it automatically.
+2. **`web_profile_info` REST** - canonical counts (followers/following/media),
+   biography, verified/private/business flags, external url, category.
+3. **Profile GraphQL** (`PolarisProfilePageContentQuery`) - richest payload when
+   Instagram answers it.
+4. **The account's own page** - the home shell Instagram server-renders embeds
+   the logged-in account's full profile, so self always resolves.
+
+```javascript
+const info = await api.getUserInfoV2("32715034217");
+// info["32715034217"] => { id, username, name, biography, followerCount,
+//   followingCount, mediaCount, isVerified, isPrivate, isBusinessAccount,
+//   externalUrl, category, profilePicUrl, profilePicUrlHd, fbid, ... }
+
+const profile = await api.getUserProfile("@someuser");   // the raw merged object
+const pic     = await api.getProfilePictureV2("someuser", { size: 640 });
+// pic => { url, hd, thumb, sizes: { "150": ..., "320": ..., "640": ..., "1080": ... } }
+```
 
 ### Listening
 
@@ -187,7 +235,35 @@ const stop = api.listen((err, event) => {
 stop();
 ```
 
-`listen` polls the inbox (default every 15s, override with `options.pollInterval`).
+`listen` uses the realtime MQTT stream when you pass
+`{ realtime: { enabled: true } }` to `login` — Instagram pushes each new DM over
+the broker, so replies are near-instant. Without it, `listen` polls the inbox
+(default every 15s, override with `options.pollInterval`). Either way the callback
+and event shape are identical, and a realtime connection that fails falls back to
+polling unless you set `realtime: { enabled: true, fallback: false }`.
+
+### Realtime (MQTT)
+
+Instagram's realtime broker (`edge-mqtt.facebook.com`) is an MQTToT connection
+authenticated by the same `sessionid` cookie — no app login. `listen()` drives it
+when realtime is enabled; you can also use it directly:
+
+```javascript
+const api = await login(cookie, { native: true });
+
+api.realtimeOn("message", (e) => console.log(e.message));
+api.realtimeOn("typing", (e) => console.log(e.threadID, "is typing"));
+api.realtimeOn("seen", (e) => console.log(e.threadID, "read"));
+api.realtimeOn("presence", (e) => console.log(e.value));
+
+await api.realtimeConnect();
+await api.realtimeSubscribe();   // reads seq_id/snapshot_at_ms from the inbox query
+// ...later
+api.realtimeDisconnect();
+```
+
+`RealtimeClient` (the raw client) and `RealtimeListener` (the listen() wrapper)
+are exported too, for callers that want to drive the socket themselves.
 
 ---
 
@@ -230,6 +306,10 @@ const login = require("@eryxenx/insta-chat");
 | `src/session.js` | Browser session-param harvesting (`puppeteer-core`). |
 | `src/deviceIdentity.js` | Persisted device identity. |
 | `src/methods/` | Native: `message`, `media`, `reactions`, `thread`, `user`, `inbox`, `typing`. |
+| `src/realtime/mqttot.js` | Dependency-free MQTToT codec (Thrift compact + MQTT packets + TLS transport). |
+| `src/realtime/client.js` | Realtime MQTT client: connect, dispatch, direct events. |
+| `src/realtime/bridge.js` | Message-sync patch → raw inbox event. |
+| `src/realtime/listener.js` | Wires realtime into `listen()` with poller fallback. |
 
 See [DOCS.md](./DOCS.md) for the full protocol notes (GraphQL doc_ids, send /
 upload / reaction flows).

package/index.d.ts

@@ -10,10 +10,36 @@ export interface InstaChatOptions {
   deviceFile?: string;
   /** Polling interval in ms for listen(). Defaults to 15000. */
   pollInterval?: number;
+  /** Lowest interval listen() will honour (ms, min 2000). Defaults to 15000. */
+  minPollIntervalMs?: number;
+  /** Opt listen() into the realtime MQTT push stream. */
+  realtime?: RealtimeOptions;
   /** login() resolves the native InstaAPI instead of the FCA-shaped InstaClient. */
   native?: boolean;
 }
 
+export interface RealtimeOptions {
+  /** Turn realtime MQTT on for listen(). */
+  enabled?: boolean;
+  /** Fall back to polling when the broker is unreachable. Defaults to true. */
+  fallback?: boolean;
+  /** Broker host. Defaults to edge-mqtt.facebook.com */
+  host?: string;
+  /** Keepalive ping interval (ms). Defaults to 30000. */
+  keepAliveMs?: number;
+  /** Pre-known iris subscription cursor; otherwise read from the inbox query. */
+  seqId?: number;
+  snapshotAtMs?: number;
+  /** Resolve the cursor yourself: () => ({ seqId, snapshotAtMs }). */
+  getRealtimeState?: () => Promise<{ seqId: number; snapshotAtMs: number } | null> | { seqId: number; snapshotAtMs: number } | null;
+  /** Android app version sent in the CONNECT. */
+  appVersion?: string;
+  /** Android User-Agent sent in the CONNECT. */
+  userAgent?: string;
+  /** Fired when the connection + subscription are ready. */
+  onReady?: (listener: any) => void;
+}
+
 export interface SendOptions {
   filename?: string;
   text?: string;
@@ -79,6 +105,52 @@ export interface InboxResult {
   threads: any[];
 }
 
+// The complete profile Instagram exposes, merged from every source the session
+// can read. Fields a source cannot supply stay null.
+export interface ProfileInfo {
+  id: string | null;
+  pk: string | null;
+  username: string | null;
+  fullName: string | null;
+  biography: string;
+  externalUrl: string | null;
+  category: string | null;
+  isVerified: boolean;
+  isPrivate: boolean;
+  isBusinessAccount: boolean;
+  isProfessionalAccount: boolean;
+  hasProfilePic: boolean;
+  profilePicUrl: string | null;
+  profilePicUrlHd: string | null;
+  fbid: string | null;
+  followerCount: number | null;
+  followingCount: number | null;
+  mediaCount: number | null;
+  highlightReelCount: number | null;
+  businessEmail: string | null;
+  businessPhone: string | null;
+  publicEmail: string | null;
+  publicPhone: string | null;
+  raw: any;
+}
+
+export interface ProfilePictureOptions {
+  /** Square size for the returned `url` (default 320). */
+  size?: number;
+  /** Square sizes to populate under `sizes` (default [150, 320, 640, 1080]). */
+  sizes?: number[];
+}
+
+export interface ProfilePicture {
+  id: string | null;
+  userID: string | null;
+  username: string | null;
+  url: string | null;
+  hd: string | null;
+  thumb: string | null;
+  sizes: Record<string, string>;
+}
+
 export interface CookieUtils {
   parse(input: string): Record<string, string>;
 }
@@ -120,8 +192,17 @@ export declare class InstaClient {
   getUID(input: string): string | null;
   getProfilePictureUrl(idOrUsername: string): Promise<string | null>;
 
+  // users (V2 profile surface — see ProfileInfo)
+  getUserInfoV2(ids: string | string[], callback?: (err: any, info: any) => void): Promise<Record<string, any>>;
+  getProfilePictureV2(idOrUsername: string, options?: ProfilePictureOptions, callback?: (err: any, info: any) => void): Promise<ProfilePicture | null>;
+  getUserProfile(idOrUsername: string, callback?: (err: any, info: ProfileInfo | null) => void): Promise<ProfileInfo | null>;
+  getUserID(idOrUsername: string, callback?: (err: any, id: string | null) => void): Promise<string | null>;
+  getProfileBio(idOrUsername: string, callback?: (err: any, info: any) => void): Promise<{ id: string | null; userID: string | null; username: string | null; name: string | null; biography: string }>;
+  getUserFriendship(userID: string, callback?: (err: any, info: any) => void): Promise<Record<string, boolean | string | null> | null>;
+
   // account
   getCurrentUserID(): string | null;
+  getSelfInfo(callback?: (err: any, info: any) => void): Promise<Record<string, any> | null>;
   getAppState(): Array<{ key: string; value: string; domain?: string; path?: string }>;
   getCookies(): Array<{ key: string; value: string; domain?: string; path?: string }>;
   setOptions(...args: any[]): boolean;
@@ -145,6 +226,14 @@ export declare class InstaClient {
   stopListening(): void;
   getInbox(cursor?: string): Promise<InboxResult>;
   rememberThread(messageID: string, threadID: string): void;
+
+  // realtime (MQTT) — also on the native client
+  realtimeClient(options?: RealtimeOptions): any;
+  realtimeConnect(options?: RealtimeOptions): Promise<any>;
+  realtimeOn(event: string, handler: (payload: any) => void): this;
+  realtimeSubscribe(): Promise<{ seqId: number; snapshotAtMs: number }>;
+  realtimePing(): Promise<boolean>;
+  realtimeDisconnect(): void;
 }
 
 /** Per-thread convenience view over an InstaClient. */
@@ -201,11 +290,15 @@ export interface LoginExport {
   findChromium(): string | undefined;
   constants: any;
   moduleLogin: LoginExport;
+  RealtimeClient: any;
+  RealtimeListener: any;
 }
 
 export const InstaClient: typeof InstaClient;
 export const InstaContext: typeof InstaContext;
 export const EventNormalizer: typeof EventNormalizer;
+export const RealtimeClient: any;
+export const RealtimeListener: any;
 export const createFcaClient: typeof createFcaClient;
 export const loadApiMethods: typeof loadApiMethods;
 export const wrap: typeof wrap;
@@ -246,6 +339,8 @@ export declare class InstaAPI {
   getUserInfo(userID: string): Promise<any>;
   getUserInfoByUsername(username: string): Promise<any>;
   searchUsers(query: string, limit?: number): Promise<any[]>;
+  getUserProfile(idOrUsername: string, opts?: { refresh?: boolean }): Promise<ProfileInfo | null>;
+  getProfilePicture(idOrUsername: string, opts?: ProfilePictureOptions): Promise<string | null>;
 
   // media
   sendPhoto(threadID: string, filePath: string, options?: SendOptions): Promise<any>;
@@ -262,6 +357,14 @@ export declare class InstaAPI {
   getInbox(cursor?: string): Promise<InboxResult>;
   listen(callback: (err: Error | null, event: IncomingEvent | null) => void, intervalMs?: number): () => void;
   stopListening(): void;
+
+  // realtime (MQTT)
+  realtimeClient(options?: RealtimeOptions): any;
+  realtimeConnect(options?: RealtimeOptions): Promise<any>;
+  realtimeOn(event: string, handler: (payload: any) => void): this;
+  realtimeSubscribe(): Promise<{ seqId: number; snapshotAtMs: number }>;
+  realtimePing(): Promise<boolean>;
+  realtimeDisconnect(): void;
 }
 
 declare const login: LoginExport;

package/index.js

@@ -17,6 +17,8 @@ const { createFcaClient } = require("./src/app/createFcaClient");
 const EventNormalizer = require("./src/events/normalizeEvent");
 const loadApiMethods = require("./src/app/loadApiMethods");
 const moduleLogin = require("./module/login");
+const { RealtimeClient } = require("./src/realtime/client");
+const { RealtimeListener } = require("./src/realtime/listener");
 
 /**
  * Log in to Instagram with a browser cookie / sessionid and return a ready
@@ -88,6 +90,8 @@ login.CookieUtils = { parse: normalizeCookie };
 login.harvestSessionParams = harvestSessionParams;
 login.findChromium = findChromium;
 login.moduleLogin = moduleLogin;
+login.RealtimeClient = RealtimeClient;
+login.RealtimeListener = RealtimeListener;
 
 module.exports = login;
 
@@ -107,5 +111,7 @@ module.exports.harvestSessionParams = harvestSessionParams;
 module.exports.findChromium = findChromium;
 module.exports.constants = constants;
 module.exports.moduleLogin = moduleLogin;
+module.exports.RealtimeClient = RealtimeClient;
+module.exports.RealtimeListener = RealtimeListener;
 module.exports.antiSuspension = require("./src/utils/antiSuspension");
 module.exports.sessionGuard = require("./src/utils/sessionGuard");

package/package.json

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

package/src/api/realtime/listen.js

@@ -5,7 +5,9 @@
  * Original author credit must be retained in all copies and derivatives.
  */
 
-// fca.listen(callback) - the Instagram inbox poller.
+// fca.listen(callback) - the Instagram inbox listener. Realtime MQTT push when
+// options.realtime.enabled is set (see InstaChatOptions), otherwise the inbox
+// poller. Both feed the same callback.
 module.exports = function (client) {
   return function listen(callback, intervalMs) {
     return client.api.listen(callback, intervalMs || client.options.pollInterval);

package/src/api/users/getProfileBio.js

@@ -0,0 +1,33 @@
+/*!
+ * insta-chat - Unofficial Instagram Chat API
+ * Copyright (c) 2026 EryXenX (https://github.com/EryXenX)
+ * Licensed under the Apache License, Version 2.0. See LICENSE and NOTICE.
+ * Original author credit must be retained in all copies and derivatives.
+ */
+
+// fca.getProfileBio(idOrUsername, callback) -> { id, username, name, biography }.
+//
+// The biography is the profile "about" text. Sourced from the same logout-safe
+// profile resolver as getUserInfoV2, so a rate-limited profile endpoint yields
+// an empty bio rather than an error.
+module.exports = function (client) {
+  return async function getProfileBio(idOrUsername, callback) {
+    const cb = typeof callback === "function" ? callback : null;
+    const key = String(idOrUsername == null ? "" : idOrUsername).replace(/^@/, "");
+    try {
+      const profile = await client.getProfile(key).catch(() => null);
+      const out = {
+        id: profile?.id || null,
+        userID: profile?.id || null,
+        username: profile?.username || null,
+        name: profile?.fullName || null,
+        biography: profile?.biography || ""
+      };
+      if (cb) cb(null, out);
+      return out;
+    } catch (error) {
+      if (cb) cb(error, null);
+      return { id: null, userID: null, username: null, name: null, biography: "" };
+    }
+  };
+};

package/src/api/users/getProfilePictureV2.js

@@ -0,0 +1,54 @@
+/*!
+ * insta-chat - Unofficial Instagram Chat API
+ * Copyright (c) 2026 EryXenX (https://github.com/EryXenX)
+ * Licensed under the Apache License, Version 2.0. See LICENSE and NOTICE.
+ * Original author credit must be retained in all copies and derivatives.
+ */
+
+// fca.getProfilePictureV2(idOrUsername, [options], callback)
+//   -> { id, userID, username, url, hd, thumb, sizes: { <px>: url } }
+//
+// Returns the user's profile picture at every size a caller may want, resolved
+// from whichever source answers (inbox-learned record, web_profile_info or the
+// account's own page). Instagram's CDN resizes a picture from its URL, so the
+// size variants are derived without extra requests.
+//
+// options: { size }   -> `url` is returned at that square size (default 320).
+//          { sizes: [n, ...] } -> a map of square sizes under `sizes`.
+module.exports = function (client) {
+  return async function getProfilePictureV2(idOrUsername, options, callback) {
+    if (typeof options === "function") { callback = options; options = {}; }
+    options = options || {};
+    const cb = typeof callback === "function" ? callback : null;
+    const key = String(idOrUsername == null ? "" : idOrUsername).replace(/^@/, "");
+    try {
+      const profile = await client.getProfile(key).catch(() => null);
+      if (!profile || (!profile.profilePicUrl && !profile.profilePicUrlHd)) {
+        const empty = { id: profile?.id || null, userID: profile?.id || null, username: profile?.username || null, url: null, hd: null, thumb: null, sizes: {} };
+        if (cb) cb(null, empty);
+        return empty;
+      }
+      const { profilePictureAtSize } = require("../../profileParse");
+      const hd = profile.profilePicUrlHd || profile.profilePicUrl;
+      const base = profile.profilePicUrl || hd;
+      const size = Number(options.size) || 320;
+      const wanted = Array.isArray(options.sizes) && options.sizes.length ? options.sizes : [150, 320, 640, 1080];
+      const sizes = {};
+      for (const px of wanted) sizes[String(px)] = profilePictureAtSize(hd, px);
+      const out = {
+        id: profile.id,
+        userID: profile.id,
+        username: profile.username,
+        url: profilePictureAtSize(base, size),
+        hd,
+        thumb: profilePictureAtSize(base, 150),
+        sizes
+      };
+      if (cb) cb(null, out);
+      return out;
+    } catch (error) {
+      if (cb) cb(error, null);
+      return null;
+    }
+  };
+};

package/src/api/users/getSelfInfo.js

@@ -0,0 +1,27 @@
+/*!
+ * insta-chat - Unofficial Instagram Chat API
+ * Copyright (c) 2026 EryXenX (https://github.com/EryXenX)
+ * Licensed under the Apache License, Version 2.0. See LICENSE and NOTICE.
+ * Original author credit must be retained in all copies and derivatives.
+ */
+
+// fca.getSelfInfo(callback) -> the logged-in account's own profile.
+//
+// Convenience wrapper over getUserInfoV2 for the bot's own id. Unlike another
+// user's profile this always resolves: the session cookie carries the account
+// id and the account's own page embeds its full PolarisViewer blob.
+module.exports = function (client) {
+  return async function getSelfInfo(callback) {
+    const cb = typeof callback === "function" ? callback : null;
+    const selfID = typeof client.getCurrentUserID === "function" ? client.getCurrentUserID() : client.userID;
+    try {
+      const info = await client.getUserInfoV2(selfID);
+      const profile = info && info[String(selfID)] ? info[String(selfID)] : null;
+      if (cb) cb(null, profile);
+      return profile;
+    } catch (error) {
+      if (cb) cb(error, null);
+      return null;
+    }
+  };
+};

package/src/api/users/getUserFriendship.js

@@ -0,0 +1,42 @@
+/*!
+ * insta-chat - Unofficial Instagram Chat API
+ * Copyright (c) 2026 EryXenX (https://github.com/EryXenX)
+ * Licensed under the Apache License, Version 2.0. See LICENSE and NOTICE.
+ * Original author credit must be retained in all copies and derivatives.
+ */
+
+// fca.getUserFriendship(userID, callback) -> { id, blocking, isRestricted,
+// isFollowedBy, follows }.
+//
+// Instagram's DM GraphQL user records carry a `friendship_status` for every
+// participant ({ blocking, is_restricted, ... }). This exposes that state from
+// data the client already learned, so it needs no extra request and cannot look
+// like a dead session. Returns null when the user has not been observed.
+module.exports = function (client) {
+  return async function getUserFriendship(userID, callback) {
+    const cb = typeof callback === "function" ? callback : null;
+    const key = String(userID == null ? "" : userID).replace(/^@/, "");
+    try {
+      const learned = client.api && typeof client.api._learnedUser === "function"
+        ? client.api._learnedUser(key)
+        : null;
+      const fs = learned && learned.friendship_status;
+      const out = {
+        id: learned ? String(learned.id || learned.pk || key) : null,
+        userID: learned ? String(learned.id || learned.pk || key) : null,
+        username: learned ? learned.username || null : null,
+        blocking: fs ? fs.blocking === true : null,
+        isRestricted: fs ? fs.is_restricted === true : null,
+        isFollowedBy: fs ? fs.is_followed_by === true : null,
+        follows: fs ? fs.following === true : null,
+        incomingRequest: fs ? fs.incoming_request === true : null,
+        outgoingRequest: fs ? fs.outgoing_request === true : null
+      };
+      if (cb) cb(null, out);
+      return out;
+    } catch (error) {
+      if (cb) cb(error, null);
+      return null;
+    }
+  };
+};