nexus-fca 2.1.5 → 2.1.7

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## [2.1.7] - 2025-09-01 - Session Stability Patch
+### Added
+- User-Agent continuity (anchored single UA for entire session via safety module; eliminates mid-session UA drift increasing 20–22h expiry risk).
+- Exposed `setFixedUserAgent()` in `FacebookSafety` to allow explicit anchoring from credential phase.
+- Mid-session lightweight token poke (6h ±40m) to keep session warm without full heavy refresh cycle.
+
+### Changed
+- Removed legacy mobile agent override fallback in `loginHelper` that caused mixed UA fingerprints.
+- All safe requests now inherit continuity-aware UA through `applySafeRequestOptions`.
+
+### Improved
+- Extended resilience against 20–22h cookie invalidation observed with prior dual-phase UA pattern.
+- Reduced unnecessary full refresh churn while preserving stealth (`safeRefresh` + light poke coexist).
+
+---
+
+## [2.1.6] - 2025-08-31 - Memory Guard & Queue Sweeping
+### Added
+- Central lightweight memory guard sweeps: group queue pruning (idle >30m, overflow trim) and pendingEdits TTL sweeper (every 4m).
+- Health metrics extended: memoryGuardRuns, memoryGuardActions, groupQueueDroppedMessages, groupQueueExpiredQueues, groupQueuePrunedThreads, pendingEditSweeps.
+- API: `api.getMemoryMetrics()` returns focused memory-related counters.
+- Typings updated (`EditOptions`, new API methods) in `index.d.ts`.
+
+### Improved
+- Group queue now tracks `lastActive` and enforces idle purge + overflow protection with metrics.
+- Pending edits TTL enforcement separated from resend watchdog for deterministic expiry.
+
+### Notes
+- All guards are low-frequency, low-impact; no change to delivery reliability or safety – only prevention of unbounded growth.
+
+---
+
 ## [2.1.5] - 2025-08-28 - PendingEdits & ACK Metrics
 ### Added
 - PendingEdits buffer with cap (default 200) + TTL (5m) + resend attempts (2) + ACK timeout (12s).

package/README.md

@@ -1,33 +1,75 @@
-# Nexus-FCA v2.1.5
+# Nexus-FCA v2.1.7
 
-<!-- 2.1.5 Highlights (PendingEdits & ACK Metrics) -->
-> New in 2.1.5: PendingEdits buffer (cap + TTL + safe resend), edit ACK watchdog, p95 ACK latency & edit resend/failure metrics, configurable via `api.setEditOptions()`.
+<!-- 2.1.7 Session Stability Patch -->
+> New in 2.1.7: Session Stability Patch – anchored User-Agent continuity (eliminates 20–22h silent expiry pattern), lightweight mid‑session token poke (6h ±40m) + existing adaptive safeRefresh, retains ultra‑low ban profile.
+
+<!-- 2.1.6 Memory Guard -->
+> 2.1.6: Memory Guard & Queue Sweeping – bounded group queues, pending edit TTL sweeper, memory metrics exporter.
+
+<!-- 2.1.5 PendingEdits -->
+> 2.1.5: PendingEdits buffer (cap + TTL + safe resend), edit ACK watchdog, p95 ACK latency & edit resend/failure metrics, configurable via `api.setEditOptions()`.
 
 <p align="center">
   <!-- Preview image wrapped in link (corrected ibb.co domain) -->
   <a href="https://ibb.co/8ymR1tw"><img src="https://i.ibb.co/Sk61FGg/Dragon-Fruit-1.jpg" alt="Nexus-FCA Dragon Fruit" width="520" border="0" /></a>
 </p>
 
-> Advanced, safe, modern Facebook Chat (Messenger) API with integrated secure login (ID / Password / 2FA), ultra‑low ban rate session management, MQTT listener, and TypeScript-ready developer experience.
+> Advanced, safe, modern Facebook Chat (Messenger) API with integrated secure login (ID / Password / 2FA), ultra‑low ban rate session management, adaptive MQTT resilience, memory guard, and TypeScript-ready developer experience.
 
 ---
-## ✨ Highlights
+## ✨ Highlights (Core Pillars)
 - 🔐 Integrated secure login system (username/password + TOTP 2FA) → auto appstate
-- 🛡️ Ultra-low ban rate design (human timing, safety limiter, risk heuristics)
-- 🔄 Resilient MQTT listener (improved session validation + graceful reconnect)
-- 🔁 Persistent device fingerprint (no random rotation → fewer checkpoints)
-- 🧠 Smart session validation (multi-endpoint retry, reduced false logouts)
-- ⚙️ Zero-config appstate reuse & automatic backup/versioned snapshots
-- 🧩 Modular architecture (safety, performance, error, mqtt managers)
-- 🗂️ Rich feature docs in `/docs` (thread, message, reactions, attachments)
+- 🛡️ Ultra-low ban rate design (human timing, safety limiter, anchored UA, risk heuristics)
+- 🔄 Resilient MQTT listener (adaptive backoff + idle / ghost detection + periodic recycle)
+- ♻️ Session continuity: anchored UA + adaptive safe refresh + lightweight mid-session poke
+- 🧠 Smart session validation (lazy preflight, multi-endpoint retry, reduced false logouts)
+- 📊 Live health & memory metrics (`api.getHealthMetrics()`, `api.getMemoryMetrics()`)
 - 🧾 Type definitions (`index.d.ts`) & modern Promise / callback API
+- 🧩 Modular architecture (safety, performance, error, mqtt managers)
 
 ---
-## 🚀 Install
-```bash
-npm install nexus-fca
+## 🚀 Recent Stability Enhancements (2.1.7 / 2.1.6 / 2.1.5)
+| Version | Focus | Key Additions |
+|---------|-------|---------------|
+| 2.1.7 | Session Longevity | UA continuity anchor, lightweight token poke, removal of mid-login UA drift |
+| 2.1.6 | Memory Safety | Group queue idle purge + overflow trim, pendingEdits TTL sweeper, memory guard metrics |
+| 2.1.5 | Edit Reliability | PendingEdits buffer (cap+TTL), ACK watchdog, resend limits, p95 ACK latency |
+
+### Why UA Continuity Matters
+Previously, dual-phase login could swap user agents (mobile → desktop) causing server-side heuristic expiry near 20–22h. Anchoring a single UA eliminates the inconsistent device fingerprint pattern and extends stable runtime under identical safety posture.
+
+### Lightweight Mid-Session Poke
+A subtle `fb_dtsg` refresh every ~6h ±40m (in addition to adaptive risk-based safeRefresh) keeps tokens warm without aggressive churn, lowering validation friction while avoiding noisy traffic patterns.
+
+---
+## 🧪 Key API Additions
+```js
+api.setEditOptions({ maxPendingEdits, editTTLms, ackTimeoutMs, maxResendAttempts });
+api.setBackoffOptions({ base, factor, max, jitter });
+api.enableLazyPreflight(true); // Skip heavy validation if a recent good connect exists
+api.getHealthMetrics(); // uptime, reconnect stats, ack latency, synthetic keepalives
+api.getMemoryMetrics(); // queue depths, drops, guard run counters
+```
+
+---
+## 🔍 Monitoring Example
+```js
+setInterval(() => {
+  const h = api.getHealthMetrics();
+  const m = api.getMemoryMetrics();
+  console.log('[HEALTH]', h?.status, 'acks', h?.ackCount, 'p95Ack', h?.p95AckLatencyMs);
+  console.log('[MEM]', m);
+}, 60000);
 ```
 
+---
+## 🧷 Long Session Best Practices
+1. Use appstate login when possible (avoid frequent credential logins).
+2. Keep `persistent-device.json` – do not rotate unless forced.
+3. Avoid changing UA manually; continuity is automatic post‑2.1.7.
+4. Inspect health metrics before manually forcing reconnects.
+5. Let adaptive backoff handle transient network instability.
+
 ---
 ## ⚡ Quick Start (Appstate)
 ```js
@@ -61,14 +103,17 @@ const login = require('nexus-fca');
 ```
 
 ---
-## 🛡️ Safety Layer (v2.1.0 Improvements)
+## 🛡️ Safety Layer (Updated)
 | Feature | Benefit |
 |---------|---------|
-| Persistent device profile | Prevents repeated “new device” flags & locks |
-| Smarter session preflight | Eliminates noisy false `not_logged_in` errors |
-| Redirect & HTML detection | Accurate login checkpoint identification |
-| Controlled retries (5xx)  | Backoff without hammering endpoints |
-| Human-like delays          | Reduces automated pattern detection |
+| Anchored User-Agent | Eliminates fingerprint drift (prevents 20–22h expiry) |
+| Adaptive Safe Refresh | Risk‑sensitive token renewal bands |
+| Lightweight Token Poke | Quiet longevity without churn |
+| Idle / Ghost Detection | Auto probe + reconnect on silent stalls |
+| Periodic Recycle | 6h ± jitter connection rejuvenation |
+| Persistent Device Profile | Fewer checkpoints / trust continuity |
+| Lazy Preflight | Skips heavy validation when recently healthy |
+| Human-like Timing | Reduces automation signal surface |
 
 Disable preflight if needed:
 ```js
@@ -77,13 +122,14 @@ await login({ appState }, { disablePreflight: true });
 
 ---
 ## 🛰️ MQTT Listener Enhancements
-- Preflight now async & tolerant (second-stage check only logs failure)
-- Classified errors: `login_redirect`, `html_login_page`, `not_logged_in`
-- Automatic cookie/token refresh propagation
+- Adaptive exponential backoff with jitter (caps 5m)
+- Soft-stale probing (2m30s) + hard watchdog tiers
+- Layered post-refresh health checks (1s / 10s / 30s) after token renewal
+- Synthetic keepalives (randomized 55–75s) feeding metrics
 
 ---
 ## 📦 Example Echo Test
-`examples/echo-test.js` (already included):
+`examples/echo-test.js`:
 ```bash
 node examples/echo-test.js
 ```
@@ -91,9 +137,9 @@ Provide `appstate.json` or set `EMAIL` / `PASSWORD` env variables.
 
 ---
 ## 🧠 Advanced Login Flow
-1. New integrated system safely generates / refreshes cookies (if credentials supplied)
-2. Legacy core consumes resulting appstate for stable API behavior
-3. Optional persistent device JSON: `persistent-device.json`
+1. Integrated system safely generates / refreshes cookies (if credentials supplied)
+2. Core consumes resulting appstate for stable API behavior
+3. Persistent device JSON: `persistent-device.json`
 
 Persistent device toggle:
 ```js
@@ -174,15 +220,16 @@ const login = require('nexus-fca');
 - Examples: `/examples`
 
 ---
-## 🔁 Updating from 2.0.x → 2.1.0
+## 🔁 Updating from 2.0.x → 2.1.x
 | Change | Action |
 |--------|--------|
-| Preflight errors | Noise reduced automatically |
-| Device rotation | Now persistent by default | 
-| parseAndCheckLogin | Handles 3xx & HTML login responses |
-| Session validation | New `validateSession` helper |
+| UA Continuity (2.1.7) | No action; auto applied |
+| Memory Guard (2.1.6) | Inspect `api.getMemoryMetrics()` periodically |
+| PendingEdits (2.1.5) | Tune via `api.setEditOptions()` if needed |
+| Lazy Preflight | Optionally disable when embedding in other frameworks |
+| Persistent Device | Keep file unless forced reset required |
 
-No breaking API changes.
+No breaking API changes across 2.1.x line.
 
 ---
 ## ⚠️ Disclaimer

package/index.d.ts

@@ -395,6 +395,11 @@ declare module 'nexus-fca' {
         setMessageReaction: (reaction: string, messageID: string, callback?: (err?: Error) => void, forceCustomReaction?: boolean) => Promise<void>,
         setMessageReactionMqtt: (reaction: string, messageID: string, threadID: string, callback?: (err?: Error) => void) => Promise<void>,
         setOptions: (options: Partial<IFCAU_Options>) => void,
+        setEditOptions: (opts: EditOptions) => void,
+        setBackoffOptions: (opts: { base?: number; max?: number; factor?: number; jitter?: number }) => void,
+        enableLazyPreflight: (enable?: boolean) => void,
+        getHealthMetrics: () => any,
+        getMemoryMetrics: () => { pendingEdits: number; pendingEditsDropped: number; pendingEditsExpired: number; outboundQueueDepth: number; groupQueueDroppedMessages: number; memoryGuardRuns: number; memoryGuardActions: number } | null,
         setTitle: (newTitle: string, threadID: string, callback?: (err?: Error) => void) => Promise<void>,
         setTheme: (themeID?: string, threadID: string, callback?: (err?: Error) => void) => Promise<void>,
         unsendMessage: (messageID: string, callback?: (err?: Error) => void) => Promise<void>,

package/index.js

@@ -273,7 +273,20 @@ function buildAPI(globalOptions, html, jar) {
     getHealthMetrics: function(){ return ctx.health ? ctx.health.snapshot() : null; },
     enableLazyPreflight(enable=true){ ctx.globalOptions.disablePreflight = !enable; },
     setBackoffOptions(opts={}){ ctx.globalOptions.backoff = Object.assign(ctx.globalOptions.backoff||{}, opts); },
-    setEditOptions(opts={}){ Object.assign(ctx.globalOptions.editSettings, opts); }
+    setEditOptions(opts={}){ Object.assign(ctx.globalOptions.editSettings, opts); },
+    getMemoryMetrics(){
+      if(!ctx.health) return null;
+      const snap = ctx.health.snapshot();
+      return {
+        pendingEdits: snap.pendingEdits,
+        pendingEditsDropped: snap.pendingEditsDropped,
+        pendingEditsExpired: snap.pendingEditsExpired,
+        outboundQueueDepth: snap.outboundQueueDepth,
+        groupQueueDroppedMessages: snap.groupQueueDroppedMessages,
+        memoryGuardRuns: snap.memoryGuardRuns,
+        memoryGuardActions: snap.memoryGuardActions
+      };
+    }
   };
   const defaultFuncs = utils.makeDefaults(html, i_userID || userID, ctx);
   require("fs")
@@ -315,7 +328,7 @@ function buildAPI(globalOptions, html, jar) {
   }, 1000 * 60 * 60 * 24);
   // === Group Queue (No Cooldown, Sequential per group) ===
   (function initGroupQueue(){
-    const groupQueues = new Map(); // threadID -> { q: [], sending: false }
+    const groupQueues = new Map(); // threadID -> { q: [], sending: false, lastActive: number }
     const isGroupThread = (tid) => typeof tid === 'string' && tid.length >= 15; // simple heuristic
     const DIRECT_FN = api.sendMessage; // original
 
@@ -325,6 +338,8 @@ function buildAPI(globalOptions, html, jar) {
     api.setGroupQueueCapacity = function(n){ globalOptions.groupQueueMax = n; };
     api.enableGroupQueue(true);
     api.setGroupQueueCapacity(100); // allow up to 100 pending per group
+    // New: group queue retention policy
+    globalOptions.groupQueueIdleMs = 30*60*1000; // 30m idle purge
 
     api._sendMessageDirect = DIRECT_FN;
     api.sendMessage = function(message, threadID, cb){
@@ -332,10 +347,12 @@ function buildAPI(globalOptions, html, jar) {
         return api._sendMessageDirect(message, threadID, cb);
       }
       let entry = groupQueues.get(threadID);
-      if(!entry){ entry = { q: [], sending: false }; groupQueues.set(threadID, entry); }
+      if(!entry){ entry = { q: [], sending: false, lastActive: Date.now() }; groupQueues.set(threadID, entry); }
+      entry.lastActive = Date.now();
       if(entry.q.length >= (globalOptions.groupQueueMax||100)) {
         // drop oldest (keep newest) to avoid unbounded growth
         entry.q.shift();
+        if(ctx.health) ctx.health.recordGroupQueuePrune(0,0,1);
       }
       entry.q.push({ message, threadID, cb });
       processQueue(threadID, entry);
@@ -364,6 +381,33 @@ function buildAPI(globalOptions, html, jar) {
       }
       entry.sending = false;
     };
+
+    // Memory guard sweeper (lightweight)
+    if(!globalOptions._groupQueueSweeper){
+      globalOptions._groupQueueSweeper = setInterval(()=>{
+        const now = Date.now();
+        let prunedThreads = 0; let expiredQueues = 0; let dropped = 0; let actions = 0;
+        for(const [tid, entry] of groupQueues.entries()){
+          // Idle purge
+            if(now - entry.lastActive > (globalOptions.groupQueueIdleMs||1800000) && !entry.sending){
+              if(entry.q.length){ dropped += entry.q.length; }
+              groupQueues.delete(tid); expiredQueues++; actions++;
+              continue;
+            }
+          // Hard cap queue length (just in case capacity changed lower)
+          const cap = globalOptions.groupQueueMax||100;
+          if(entry.q.length > cap){
+            const overflow = entry.q.length - cap;
+            entry.q.splice(0, overflow); // drop oldest overflow
+            dropped += overflow; actions++;
+          }
+        }
+        if((prunedThreads||expiredQueues||dropped) && ctx.health){
+          ctx.health.recordGroupQueuePrune(prunedThreads, expiredQueues, dropped);
+          ctx.health.recordMemoryGuardRun(actions);
+        }
+      }, 5*60*1000); // every 5 minutes
+    }
   })();
   // === End Group Queue ===
   return {
@@ -384,7 +428,8 @@ function loginHelper(appState, email, password, globalOptions, callback, prCallb
     return callback(new Error(`Login Safety Check Failed: ${safetyCheck.reason}`));
   }
   
-  // Apply safe user agent from safety module
+  // Establish continuity user agent ONCE (credential/appstate phase)
+  if(!globalSafety._fixedUA){ globalSafety.setFixedUserAgent(globalSafety.getSafeUserAgent()); }
   globalOptions.userAgent = globalSafety.getSafeUserAgent();
   
   if (appState) {
@@ -404,7 +449,7 @@ function loginHelper(appState, email, password, globalOptions, callback, prCallb
         jar.setCookie(str, "http://" + c.domain);
       });
 
-      // Apply safety headers and no delays for maximum safety
+      // Apply safety headers with continuity UA
       mainPromise = utils.get('https://www.facebook.com/', jar, null, 
         globalSafety.applySafeRequestOptions(globalOptions), { noRef: true })
         .then(utils.saveCookies(jar));
@@ -419,7 +464,7 @@ function loginHelper(appState, email, password, globalOptions, callback, prCallb
     const reg = /<meta http-equiv="refresh" content="0;url=([^"]+)[^>]+>/;
     const redirect = reg.exec(res.body);
     if (redirect && redirect[1]) {
-      return utils.get(redirect[1], jar, null, globalOptions).then(utils.saveCookies(jar));
+      return utils.get(redirect[1], jar, null, globalSafety.applySafeRequestOptions(globalOptions)).then(utils.saveCookies(jar));
     }
     return res;
   }
@@ -428,11 +473,7 @@ function loginHelper(appState, email, password, globalOptions, callback, prCallb
   mainPromise = mainPromise
     .then(handleRedirect)
     .then(res => {
-      const mobileAgentRegex = /MPageLoadClientMetrics/gs;
-      if (!mobileAgentRegex.test(res.body)) {
-        globalOptions.userAgent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36";
-        return utils.get('https://www.facebook.com/', jar, null, globalOptions, { noRef: true }).then(utils.saveCookies(jar));
-      }
+      // Remove UA override logic to maintain continuity (previous mobileAgentRegex swap)
       return res;
     })
     .then(handleRedirect)
@@ -464,6 +505,22 @@ function loginHelper(appState, email, password, globalOptions, callback, prCallb
       logger('✅ Session authenticated successfully', 'info');
       // Initialize safety monitoring
       globalSafety.startMonitoring(ctx, api);
+      // Schedule mid-session lightweight token poke (~ every 6h ±40m) to keep cookies warm
+      if(!globalOptions._lightRefreshTimer){
+        const scheduleLight = () => {
+          const base = 6 * 60 * 60 * 1000; // 6h
+          const jitter = (Math.random()*80 - 40) * 60 * 1000; // ±40m
+            globalOptions._lightRefreshTimer = setTimeout(async () => {
+              try {
+                if(api && typeof api.refreshFb_dtsg === 'function'){
+                  await api.refreshFb_dtsg().catch(()=>{});
+                }
+              } catch(_) {}
+              scheduleLight();
+            }, base + jitter);
+        };
+        scheduleLight();
+      }
       // Post-login identity banner
       try {
         const uid = api.getCurrentUserID && api.getCurrentUserID();

package/lib/health/HealthMetrics.js

@@ -1,5 +1,5 @@
 "use strict";
-// Lightweight health & metrics tracker for Nexus-FCA (extended Stage 2)
+// Lightweight health & metrics tracker for Nexus-FCA (extended Stage 2 + Memory Guard)
 class HealthMetrics {
   constructor() {
     const now = Date.now();
@@ -26,6 +26,14 @@ class HealthMetrics {
     this.p95AckLatencyMs = null;
     this.editResends = 0;
     this.editFailed = 0;
+    // Memory / queue guard metrics (Stage 3)
+    this.memoryGuardRuns = 0;
+    this.memoryGuardLastRun = 0;
+    this.memoryGuardActions = 0;
+    this.groupQueuePrunedThreads = 0;
+    this.groupQueueExpiredQueues = 0;
+    this.groupQueueDroppedMessages = 0;
+    this.pendingEditSweeps = 0;
   }
   onConnect() { this.lastConnectTs = Date.now(); this.consecutiveFailures = 0; }
   onDisconnect() { this.lastDisconnectTs = Date.now(); }
@@ -64,9 +72,16 @@ class HealthMetrics {
     for(const [mid, val] of this.pendingEditMap.entries()){
       if(now - val.ts > ttlMs){ this.pendingEditMap.delete(mid); expired++; }
     }
-    if(expired) { this.incPendingEditExpired(expired); }
+    if(expired) { this.incPendingEditExpired(expired); this.pendingEditSweeps++; }
     this.pendingEdits = this.pendingEditMap.size;
   }
+  // Memory guard helpers
+  recordMemoryGuardRun(actions=0){ this.memoryGuardRuns++; this.memoryGuardLastRun = Date.now(); this.memoryGuardActions += actions; }
+  recordGroupQueuePrune(threads, expiredQueues, droppedMsgs){
+    if(threads) this.groupQueuePrunedThreads += threads;
+    if(expiredQueues) this.groupQueueExpiredQueues += expiredQueues;
+    if(droppedMsgs) this.groupQueueDroppedMessages += droppedMsgs;
+  }
   snapshot(){
     const now = Date.now();
     const idleMs = now - (this.lastMessageTs || this.lastConnectTs || now);
@@ -92,6 +107,13 @@ class HealthMetrics {
       editFailed: this.editFailed,
       outboundQueueDepth: this.outboundQueueDepth,
       outboundQueueDropped: this.outboundQueueDropped,
+      memoryGuardRuns: this.memoryGuardRuns,
+      memoryGuardLastRun: this.memoryGuardLastRun,
+      memoryGuardActions: this.memoryGuardActions,
+      groupQueuePrunedThreads: this.groupQueuePrunedThreads,
+      groupQueueExpiredQueues: this.groupQueueExpiredQueues,
+      groupQueueDroppedMessages: this.groupQueueDroppedMessages,
+      pendingEditSweeps: this.pendingEditSweeps,
       healthy: this.isHealthy(idleMs)
     };
   }

package/lib/safety/FacebookSafety.js

@@ -18,6 +18,8 @@ class FacebookSafety {
             enableSafeDelays: true,
             bypassRegionLock: true,
             ultraLowBanMode: true,
+            // NEW: ensure a single stable UA across entire session lifecycle
+            enableUAContinuity: true,
             ...options
         };
 
@@ -29,6 +31,8 @@ class FacebookSafety {
             'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
             'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/118.0.0.0 Safari/537.36'
         ];
+        // NEW: fixed user agent anchor (set once per session)
+        this._fixedUA = null;
 
         this.safeDomains = [
             'https://www.facebook.com',
@@ -88,9 +92,23 @@ class FacebookSafety {
     }
 
     /**
-     * Get safe user agent that reduces detection risk
+     * Allow external code to explicitly anchor the session UA (e.g. carry over from credential phase)
+     */
+    setFixedUserAgent(ua){
+        if(!ua || typeof ua !== 'string') return;
+        this._fixedUA = ua;
+    }
+
+    /**
+     * Get safe user agent that reduces detection risk (now continuity‑aware)
      */
     getSafeUserAgent() {
+        if (this.options.enableUAContinuity) {
+            if (this._fixedUA) return this._fixedUA;
+            // choose once then cache
+            this._fixedUA = this.safeUserAgents[Math.floor(Math.random() * this.safeUserAgents.length)];
+            return this._fixedUA;
+        }
         return this.safeUserAgents[Math.floor(Math.random() * this.safeUserAgents.length)];
     }
 
@@ -146,7 +164,7 @@ class FacebookSafety {
             maxRedirects: 5
         };
 
-        // Apply safe user agent
+        // Apply stable user agent (continuity aware)
         safeOptions.userAgent = this.getSafeUserAgent();
 
         return safeOptions;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexus-fca",
-  "version": "2.1.5",
+  "version": "2.1.7",
   "description": "A modern, safe, and advanced Facebook Chat API for Node.js with fully integrated Nexus Login System. NPM-ready with ID/password/2FA support, ultra-low ban rate protection, and zero external dependencies.",
   "main": "index.js",
   "repository": {