nexus-fca 3.0.1 → 3.0.3

package/README.md

@@ -147,6 +147,7 @@ const login = require('nexus-fca');
 |----------|----------|
 | Full API Reference | `DOCS.md` |
 | Feature Guides | `docs/*.md` |
+| Configuration Reference | `docs/configuration-reference.md` |
 | Safety Details | `docs/account-safety.md` |
 | Examples | `examples/` |
 

package/docs/README.md

@@ -22,6 +22,9 @@ This folder contains comprehensive documentation for all features of Nexus-FCA,
 ### 🔧 Core API Documentation
 Each `.md` file documents a single core API feature with usage examples, parameters, and safety notes.
 
+Additional references:
+- [Configuration Reference](./configuration-reference.md) — all env vars, programmatic options, and config file keys
+
 ### 🔗 Migration Guides
 - **[Migration-fca-unofficial.md](./Migration-fca-unofficial.md)** - Migrate from fca-unofficial
 - **[Migration-ws3-fca.md](./Migration-ws3-fca.md)** - Migrate from ws3-fca  

package/docs/advanced-configuration.md

@@ -0,0 +1,101 @@
+# Advanced Configuration Options for Nexus-FCA
+
+This document outlines additional configuration options available to optimize your Nexus-FCA experience.
+
+## Environment Variables
+
+Nexus-FCA supports various environment variables to fine-tune its behavior:
+
+### Session Management
+
+```
+# Device persistence
+NEXUS_PERSISTENT_DEVICE=true    # Enable consistent device fingerprinting (default)
+NEXUS_DEVICE_FILE=./device.json # Custom path to device profile file
+
+# Single-session guard (built-in)
+# Uses SingleSessionGuard with NEXUS_SESSION_LOCK_PATH and NEXUS_FORCE_LOCK
+NEXUS_SESSION_LOCK_PATH=./lock  # Path to session lock file used by SingleSessionGuard
+NEXUS_FORCE_LOCK=false          # Force acquire lock even if lock exists
+
+# Region control
+NEXUS_REGION=NA                 # Set fixed region (NA, EU, AS)
+```
+
+### Cookie Management
+
+```
+# Cookie refresher settings
+NEXUS_COOKIE_REFRESH_INTERVAL=1800000  # Refresh interval in ms (default: 30 minutes)
+NEXUS_COOKIE_EXPIRY_DAYS=90           # Days to extend cookie expiry
+NEXUS_COOKIE_BACKUP_PATH=./backups    # Path to store cookie backups
+NEXUS_COOKIE_MAX_BACKUPS=5            # Maximum number of cookie backups to keep
+```
+
+### Connection Settings
+
+```
+# Connection resilience
+NEXUS_MAX_RETRIES=5              # Maximum connection retry attempts
+NEXUS_RETRY_DELAY=5000           # Base delay between retries (ms)
+NEXUS_KEEPALIVE_INTERVAL=300000  # Keepalive interval (ms)
+```
+
+### Safety Features
+
+```
+# Safety controls
+NEXUS_FCA_SAFE_MODE=1            # Enable basic safety measures
+NEXUS_FCA_ULTRA_SAFE_MODE=1      # Enable maximum safety for stability
+NEXUS_DELIVERY_TIMEOUT=60000     # Message delivery timeout (ms)
+NEXUS_AUTO_MARK_READ=false       # Automatically mark messages as read
+```
+
+## API Configuration Options
+
+When initializing the API, you can pass additional options:
+
+```javascript
+const api = await login({
+  appState: require('./appstate.json'),
+  
+  // Session stability options
+  persistentDevice: true,           // Use consistent device fingerprinting
+  deviceFilePath: './device.json',  // Custom device profile path
+  // Single-session guard is enabled by default internally
+  // Configure via env: NEXUS_SESSION_LOCK_PATH, NEXUS_FORCE_LOCK
+  
+  // Connection options
+  region: 'NA',                     // Set fixed region
+  userAgent: 'custom-user-agent',   // Override user agent
+  
+  // Cookie management
+  cookieRefreshInterval: 1800000,   // Cookie refresh interval (ms)
+  cookieExpiryDays: 90,             // Days to extend cookie expiry
+  cookieBackupEnabled: true,        // Enable cookie backups
+  cookieMaxBackups: 5,              // Maximum cookie backups
+  
+  // Safety options
+  forceLogout: true,                // Force logout any other sessions
+  safetyLevel: 2                    // Safety level (0-2)
+});
+```
+
+## Best Practices
+
+For the most stable experience:
+
+1. **Always enable persistent device**: Use the same device fingerprint across restarts
+2. **Enable session locking**: Prevent multiple instances from using the same account
+3. **Set a fixed region**: Use the `NEXUS_REGION` environment variable
+4. **Use a modern user agent**: Let the system select an appropriate one
+5. **Keep cookie refreshing enabled**: Maintains fresh cookies
+6. **Back up working appstate files**: Keep copies of working sessions
+
+## Security Considerations
+
+- Store sensitive information like appstate files securely
+- Use environment variables for credentials instead of hardcoding
+- Use `.env` files in development (gitignored)
+- Consider using a dedicated account for automation
+- Respect Facebook's terms of service and rate limits

package/docs/configuration-reference.md

@@ -0,0 +1,195 @@
+# Configuration Reference (Nexus-FCA 3.0)
+
+This document lists every supported configuration surface across the project: programmatic options, config file keys, and environment variables. Use this as a single source of truth when deploying locally or to PaaS.
+
+---
+## 1) Programmatic options (api.setOptions / login options)
+
+These map to `globalOptions` and are available via `api.setOptions({ ... })` or by passing as the second argument to `login(credentials, options)`.
+
+- Booleans
+  - `online` (default: true) – Advertise chat availability when connected
+  - `selfListen` – Receive your own sent messages
+  - `listenEvents` – Emit non-message events (nicknames, pins, joins, etc.)
+  - `listenTyping` – Emit typing events
+  - `updatePresence` – Enable presence updates processing
+  - `forceLogin` – Force legacy login behavior where applicable
+  - `autoMarkDelivery` – Auto mark delivery for inbound messages
+  - `autoMarkRead` – Auto mark read for inbound messages
+  - `autoReconnect` (default: true) – Reconnect MQTT after disconnect
+  - `emitReady` – Emit a synthetic `ready` event after connect
+
+- Strings
+  - `logLevel`: 'silent' | 'error' | 'warn' | 'info' | 'verbose'
+  - `pageID`: string – Page scope for actions
+  - `userAgent`: string – Overrides UA for outbound requests
+  - `proxy`: string – HTTP(S) proxy URL
+  - `acceptLanguage`: string – Accept-Language header for MQTT/Web requests
+
+- Numbers
+  - `logRecordSize` – npmlog ring buffer size
+
+- Advanced (set via helper methods)
+  - `api.setBackoffOptions({ base, factor, max, jitter })` – Adaptive MQTT reconnect backoff tuning
+  - `api.setEditOptions({ maxPendingEdits, editTTLms, ackTimeoutMs, maxResendAttempts })` – Message edit safety controls
+  - `api.enableLazyPreflight(enable=true)` – When true, preflight is lighter/skipped if recent successful connect
+  - Group queue controls for large group threads:
+    - `api.enableGroupQueue(enable=true)`
+    - `api.setGroupQueueCapacity(n)`
+    - Internals: `groupQueueIdleMs` (default 30m) – idle purge window
+
+Notes:
+- Unknown keys passed to `setOptions` are warned and ignored.
+- `api.listen` is an alias of `api.listenMqtt`.
+
+---
+## 2) Config file: fca-config.json
+
+Auto-created in project root on first run and merged with defaults. Good for project-wide non-secret settings.
+
+Example keys (merge-safe):
+
+```json
+{
+  "autoUpdate": true,
+  "mqtt": { "enabled": true, "reconnectInterval": 3600 },
+  "logLevel": "warn",
+  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...",
+  "proxy": "http://user:pass@host:port"
+}
+```
+
+For secrets and per-deploy toggles, prefer environment variables.
+
+---
+## 3) Environment variables
+
+Environment variables are the primary way to configure behavior in production. They override defaults and complement programmatic options.
+
+### 3.1 Storage & persistence
+- `NEXUS_DATA_DIR` – Base directory for persistent files (fallback: `RENDER_DATA_DIR` or CWD)
+- `NEXUS_APPSTATE_PATH` – Path to appstate.json
+- `NEXUS_CREDENTIALS_PATH` – Path to credentials.json (integrated login)
+- `NEXUS_BACKUP_PATH` – Directory for appstate backups
+- `NEXUS_DEVICE_FILE` – Path to persistent-device.json
+- `NEXUS_PERSISTENT_DEVICE` = true|false – Keep stable device fingerprint
+
+### 3.2 Networking & headers
+- `NEXUS_PROXY` – HTTP(S) proxy URL (also respects `HTTPS_PROXY` / `HTTP_PROXY`)
+- `NEXUS_ACCEPT_LANGUAGE` – Example: `en-US,en;q=0.9`
+- `NEXUS_UA` – Override User-Agent
+- `NEXUS_REGION` – Force MQTT region (e.g., `HIL`)
+
+### 3.3 Stability & preflight
+- `NEXUS_DISABLE_PREFLIGHT` = true|false – Skip heavy preflight validation
+- `NEXUS_ONLINE` = true|false – Override chat availability flag
+- `NEXUS_VERBOSE_MQTT` = true|false – Extra MQTT diagnostics logging
+
+### 3.4 Single-session guard (prevents concurrent runs)
+- `NEXUS_SESSION_LOCK_PATH` – Path for session lock file (default: `<DATA_DIR>/session.lock`)
+- `NEXUS_SESSION_TTL_MS` – Lock stale timeout (default: 900000 = 15m)
+- `NEXUS_FORCE_LOCK` = true|false – Force takeover if lock present
+
+### 3.5 Safety layer & allow/block lists
+- `NEXUS_FCA_ULTRA_SAFE_MODE` = '1' – Maximum protection presets
+- `NEXUS_FCA_SAFE_MODE` = '1' – Safe mode presets
+- `NEXUS_FCA_ALLOW_LIST` – Comma-separated userIDs allowed
+- `NEXUS_FCA_BLOCK_LIST` – Comma-separated userIDs blocked
+
+### 3.6 Example-only envs (for quick scripts)
+Used in example snippets and README demos; not used by the core library itself:
+- `FB_EMAIL` – Facebook username/email
+- `FB_PASS` / `FB_PASSWORD` – Facebook password
+- `FB_2FA_SECRET` – TOTP secret for 2FA (if used)
+- `EMAIL` / `PASSWORD` – Alternative names used in example scripts
+- `DEBUG` – e.g. `nexus-fca:*` to enable debug output in certain examples
+
+---
+## 4) Integrated Nexus Login System options
+
+Used internally for credential-based login; also exported for direct use via `IntegratedNexusLoginSystem`. Options can be provided in code or via the env overrides above.
+
+- Paths & persistence
+  - `appstatePath` (env: `NEXUS_APPSTATE_PATH`)
+  - `credentialsPath` (env: `NEXUS_CREDENTIALS_PATH`)
+  - `backupPath` (env: `NEXUS_BACKUP_PATH`)
+  - `persistentDevice` (env: `NEXUS_PERSISTENT_DEVICE`)
+  - `persistentDeviceFile` (env: `NEXUS_DEVICE_FILE`)
+
+- Behavior
+  - `autoLogin` (default: true)
+  - `autoSave` (default: true)
+  - `safeMode` (default: true)
+  - `maxRetries` (default: 3)
+  - `retryDelay` (default: 5000 ms)
+
+---
+## 5) MQTT & connection behavior
+
+Controlled via programmatic options and envs:
+
+- `autoReconnect` (default true) – Reconnect on close/error
+- Backoff: `api.setBackoffOptions({ base, factor, max, jitter })`
+- Keepalives & diagnostics: `NEXUS_VERBOSE_MQTT` for extra logs
+- Headers: `acceptLanguage`, `userAgent`, `proxy`
+- Region override: `NEXUS_REGION`
+
+---
+## 6) Delivery & read behavior
+
+- `autoMarkDelivery` – Calls `markAsDelivered` for inbound messages
+- `autoMarkRead` – Optional follow-up read marking
+- Adaptive suppression & retries are built-in; metrics accessible via `api.getHealthMetrics()`
+
+---
+## 7) Health and memory metrics
+
+- `api.getHealthMetrics()` – ACKs, reconnect counts, delivery stats, last connect timestamps, etc.
+- `api.getMemoryMetrics()` – Pending edits, outbound queue depth, group queue prunes, memory guard actions
+
+---
+## 8) Logging
+
+- `logLevel`: 'silent' | 'error' | 'warn' | 'info' | 'verbose'
+- `logRecordSize`: ring buffer size
+- Temporarily increase MQTT verbosity with `NEXUS_VERBOSE_MQTT=true` when debugging
+
+---
+## 9) Quick matrix (where to set)
+
+| Setting                        | setOptions | login options | fca-config.json | ENV |
+|--------------------------------|------------|---------------|-----------------|-----|
+| online                         | ✅         | ✅            |                 | ✅ (`NEXUS_ONLINE`) |
+| selfListen / listenEvents      | ✅         | ✅            |                 |     |
+| updatePresence                 | ✅         | ✅            |                 |     |
+| autoMarkDelivery / autoMarkRead| ✅         | ✅            |                 |     |
+| autoReconnect                  | ✅         | ✅            |                 |     |
+| userAgent                      | ✅         | ✅            | ✅               | ✅ (`NEXUS_UA`) |
+| proxy                          | ✅         | ✅            | ✅               | ✅ (`NEXUS_PROXY`/`HTTPS_PROXY`/`HTTP_PROXY`) |
+| acceptLanguage                 | ✅         | ✅            |                 | ✅ (`NEXUS_ACCEPT_LANGUAGE`) |
+| disablePreflight               | via `enableLazyPreflight(false)` | ✅ |       | ✅ (`NEXUS_DISABLE_PREFLIGHT`) |
+| pageID                         | ✅         | ✅            |                 |     |
+| backoff/edit settings          | helper fns |               |                 |     |
+| data/appstate/backup/device    |            | via Integrated Login |         | ✅ (`NEXUS_*` paths) |
+| session guard (lock/ttl/force) |            |               |                 | ✅ |
+| safety modes / lists           |            |               |                 | ✅ |
+
+---
+## 10) Recommended PaaS baseline
+
+Set at minimum:
+
+```
+NEXUS_DATA_DIR=/var/data/nexus-fca
+NEXUS_APPSTATE_PATH=/var/data/nexus-fca/appstate.json
+NEXUS_DEVICE_FILE=/var/data/nexus-fca/persistent-device.json
+NEXUS_PERSISTENT_DEVICE=true
+NEXUS_ACCEPT_LANGUAGE=en-US,en;q=0.9
+# Optional hardening
+NEXUS_DISABLE_PREFLIGHT=true
+# Optional proxy/region
+# NEXUS_PROXY=http://user:pass@host:port
+# NEXUS_REGION=HIL
+```
+
+See also: `docs/deployment-config.md` for end-to-end deployment steps.

package/docs/cookie-management.md

@@ -0,0 +1,87 @@
+# Cookie Expiry and Session Management Guide
+
+This document explains how Nexus-FCA handles cookie management to prevent rapid session expiry and improve overall stability.
+
+## Understanding the Issue
+
+Facebook cookies may expire rapidly (within hours) due to several reasons:
+
+1. **Missing Expiry Dates**: Some cookies don't have proper expiry timestamps
+2. **Short-lived Sessions**: Facebook may issue cookies with short expiry times
+3. **Device Inconsistency**: Using different device profiles between sessions
+4. **Multiple Sessions**: Running multiple bots with the same account
+5. **Security Triggers**: Suspicious activities triggering Facebook safety mechanisms
+
+## Nexus-FCA Solution
+
+Nexus-FCA implements a robust multi-layered approach to maintain session stability:
+
+### 1. Cookie Expiry Extension
+
+The system automatically extends cookie expiry dates:
+
+- Critical cookies (`c_user`, `xs`, `fr`, `datr`, `sb`) are extended to 90 days
+- All cookies are validated at startup and fixed if needed
+- Proper expiry format is enforced using the standard RFC format
+
+### 2. Persistent Device Profile
+
+To maintain consistency across restarts:
+
+- Device fingerprints (device ID, user agent, family device ID) are preserved
+- The same device profile is used for all requests
+- Configuration option: `persistentDevice: true` (enabled by default)
+
+### 3. Cookie Refresher
+
+An active background service keeps your session fresh:
+
+- Periodically refreshes cookies (every 30 minutes)
+- Makes lightweight requests to maintain session activity
+- Extends cookie expiry dates automatically
+- Creates backups of working sessions
+
+### 4. Single Session Guard
+
+Prevents multiple instances from using the same account:
+
+- File-based locking mechanism prevents duplicate sessions
+- Ensures Facebook sees consistent device information
+- Configuration via `NEXUS_SESSION_LOCK_PATH` and `NEXUS_FORCE_LOCK`
+
+## Best Practices
+
+For maximum session stability:
+
+1. **Use Persistent Device**: Always enable persistentDevice (default)
+2. **Keep Proxy Consistent**: Use the same proxy for extended periods
+3. **Set Region**: Use `NEXUS_REGION` to maintain a consistent region
+4. **Avoid Multiple Instances**: Never run multiple bots with the same account
+5. **Regular Backups**: Keep backups of working appstate files
+
+## Configuration
+
+Key environment variables for session stability:
+
+```
+# Session stability
+NEXUS_PERSISTENT_DEVICE=true    # Keep device fingerprint consistent (default)
+NEXUS_DEVICE_FILE=./device.json # Custom device profile path
+NEXUS_SESSION_LOCK_PATH=./lock  # Single session lock file location
+NEXUS_REGION=NA                 # Fixed region (NA, EU, AS, etc.)
+
+# Safety settings
+NEXUS_FCA_ULTRA_SAFE_MODE=1     # Maximum safety for stability
+```
+
+## Troubleshooting
+
+If you still experience session expiry:
+
+1. **Check Logs**: Look for warnings about cookie expiry or checkpoint
+2. **Monitor Activity**: High message volume can trigger Facebook limits
+3. **Fresh Login**: Generate a completely new appstate if needed
+4. **API Limits**: Respect Facebook rate limits with delay between actions
+5. **Secure Network**: Use residential IPs rather than datacenter IPs
+
+The new cookie management system should significantly improve stability and prevent the rapid expiry issues previously encountered.

package/docs/deployment-config.md

@@ -0,0 +1,178 @@
+# Deployment & Configuration Guide (Nexus-FCA 3.0)
+
+This guide shows how to use Nexus-FCA as an npm package, configure it via file and environment variables, deploy safely on platforms like Render, and avoid the “you couldn't create multiple sessions” warning.
+
+---
+## 1) Using as an npm package
+
+Install:
+
+```bash
+npm install nexus-fca
+```
+
+Basic appstate usage:
+
+```js
+const login = require('nexus-fca');
+
+(async () => {
+  const api = await login({ appState: require('./appstate.json') });
+  api.listen((err, evt) => {
+    if (err) return console.error(err);
+    if (evt.body) api.sendMessage('Echo: ' + evt.body, evt.threadID);
+  });
+})();
+```
+
+---
+## 2) Configuration options
+
+You can control behavior via:
+- Programmatic options: `api.setOptions({ ... })`
+- Config file: `fca-config.json` (auto-created on first run)
+- Environment variables (recommended for hosting)
+
+### 2.1 Programmatic options (common)
+```js
+api.setOptions({
+  autoReconnect: true,
+  updatePresence: false,
+  selfListen: false,
+  logLevel: 'warn',           // npmlog level: silly|verbose|info|warn|error
+  userAgent: '...Chrome/...',
+  proxy: 'http://user:pass@host:port',
+});
+```
+
+### 2.2 Config file: `fca-config.json`
+A default file is stored at project root and merged with internal defaults. You can keep project-wide settings here:
+
+```json
+{
+  "autoUpdate": true,
+  "mqtt": { "enabled": true, "reconnectInterval": 3600 },
+  "logLevel": "warn",
+  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
+  "proxy": "http://user:pass@host:port"
+}
+```
+
+Note: For secrets and deployment toggles, prefer environment variables below.
+
+### 2.3 Environment variables (hosting-friendly)
+These are read at runtime and override defaults:
+
+- Storage & persistence
+  - `NEXUS_DATA_DIR` → base directory for persistent files
+  - `NEXUS_APPSTATE_PATH` → path to `appstate.json`
+  - `NEXUS_DEVICE_FILE` → path to `persistent-device.json`
+  - `NEXUS_BACKUP_PATH` → directory for appstate backups
+  - `NEXUS_PERSISTENT_DEVICE` → `true|false` (keep same device fingerprint)
+
+- Networking & headers
+  - `NEXUS_PROXY` (or `HTTPS_PROXY` / `HTTP_PROXY`) → Proxy URL
+  - `NEXUS_ACCEPT_LANGUAGE` → e.g. `en-US,en;q=0.9`
+  - `NEXUS_UA` → override User-Agent
+  - `NEXUS_REGION` → force MQTT region (e.g., `HIL`)
+
+- Stability & preflight
+  - `NEXUS_DISABLE_PREFLIGHT` → `true|false` (skip heavy session preflight)
+  - `NEXUS_ONLINE` → `true|false`
+  - `NEXUS_VERBOSE_MQTT` → `true|false` (extra MQTT logs only when needed)
+
+Example (Render):
+```
+NEXUS_DATA_DIR=/var/data/nexus-fca
+NEXUS_APPSTATE_PATH=/var/data/nexus-fca/appstate.json
+NEXUS_DEVICE_FILE=/var/data/nexus-fca/persistent-device.json
+NEXUS_BACKUP_PATH=/var/data/nexus-fca/backups
+NEXUS_PERSISTENT_DEVICE=true
+
+NEXUS_ACCEPT_LANGUAGE=en-US,en;q=0.9
+NEXUS_UA=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36
+NEXUS_DISABLE_PREFLIGHT=true
+NEXUS_ONLINE=false
+# Optional region & proxy
+# NEXUS_REGION=HIL
+# NEXUS_PROXY=http://user:pass@host:port
+```
+
+---
+## 3) Deploying on Render (or other PaaS)
+
+1) Persistent disk
+- Mount a disk and point `NEXUS_DATA_DIR` to it.
+- Ensure `appstate.json` and `persistent-device.json` live on this disk.
+
+2) Single instance per account
+- Run only one service instance for a given account.
+- Disable autoscaling/replicas for this worker.
+
+3) Environment hardening
+- Set `NEXUS_PERSISTENT_DEVICE=true` to anchor device fingerprint.
+- Set `NEXUS_DISABLE_PREFLIGHT=true` to reduce heavy checks.
+- Optionally use a reputable residential/mobile proxy via `NEXUS_PROXY`.
+
+4) Keep your appstate fresh
+- Generate appstate locally on a trusted network, then deploy it.
+- Avoid frequent credential logins from the server itself.
+
+---
+## 4) "You couldn't create multiple sessions" – what it means and fixes
+
+This warning typically appears when Facebook detects concurrent or rapidly rotating logins for the same account, often from:
+- Multiple bots/instances using the same account at the same time
+- Different IPs or device fingerprints in quick succession
+- Frequent logouts/re-logins (or unstable appstate)
+
+How to avoid:
+- Run exactly one bot instance per account.
+- Reuse the same `appstate.json` and `persistent-device.json` (set `NEXUS_PERSISTENT_DEVICE=true`).
+- Avoid logging in with username/password from multiple places—generate appstate once and reuse it.
+- Use a stable IP. If your PaaS IPs rotate or look like a datacenter bot, use a reputable residential/mobile proxy.
+- Keep preflight light on PaaS (`NEXUS_DISABLE_PREFLIGHT=true`).
+
+Recovery steps when you see the warning:
+- Stop all other running instances for the same account.
+- Log in manually in a browser, pass any checkpoint, verify recent logins.
+- Regenerate a fresh appstate (locally), deploy, and keep it persistent.
+
+---
+## 5) Minimal config-first example
+
+`fca-config.json` (project root):
+```json
+{
+  "logLevel": "warn",
+  "mqtt": { "enabled": true, "reconnectInterval": 3600 },
+  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/121.0.0.0 Safari/537.36"
+}
+```
+
+Bot code:
+```js
+const login = require('nexus-fca');
+(async () => {
+  const api = await login({ appState: require(process.env.NEXUS_APPSTATE_PATH || './appstate.json') });
+  // Optional fine-tuning
+  api.setOptions({
+    autoReconnect: true,
+    updatePresence: false,
+    proxy: process.env.NEXUS_PROXY,
+  });
+  api.listen((err, evt) => {
+    if (err) return console.error(err);
+    if (evt.body) api.sendMessage('Echo: ' + evt.body, evt.threadID);
+  });
+})();
+```
+
+---
+## 6) Troubleshooting quick tips
+- Rapid cookie expiry: ensure persistence paths are on mounted disk; set `NEXUS_PERSISTENT_DEVICE=true`.
+- Frequent reconnect warnings: let adaptive backoff work; keep `autoReconnect=true`.
+- No replies sent: check proxy/network egress; use delivery metrics via `api.getHealthMetrics()`.
+- Noisy logs: avoid `NEXUS_VERBOSE_MQTT` unless debugging; prefer `logLevel=warn`.
+
+For full API details, see `DOCS.md` and other files in `docs/`.