nexus-fca 3.2.3 → 3.3.0

package/README.md

@@ -187,6 +187,7 @@ const login = require('nexus-fca');
 ## 📚 Documentation Map
 | Resource | Location |
 |----------|----------|
+| **Usage Guide (Examples)** | `USAGE-GUIDE.md` |
 | Full API Reference | `DOCS.md` |
 | Feature Guides | `docs/*.md` |
 | Configuration Reference | `docs/configuration-reference.md` |

package/index.js

@@ -85,6 +85,7 @@ const { CookieManager } = require('./lib/safety/CookieManager');
 const EmailPasswordLogin = require('./lib/auth/EmailPasswordLogin');
 const ProxyManager = require('./lib/network/ProxyManager');
 const UserAgentManager = require('./lib/network/UserAgentManager');
+const HealthServer = require('./lib/network/HealthServer');
 
 // Core compatibility imports
 const MqttManager = require('./lib/mqtt/MqttManager');
@@ -131,6 +132,12 @@ if (!fs.existsSync(configPath)) {
 global.fca = {
   config: config
 };
+
+// Start Health Server if on cloud platform or enabled
+if (process.env.PORT || process.env.NEXUS_ENABLE_HEALTH_SERVER === '1') {
+  const healthServer = new HealthServer();
+  healthServer.start();
+}
 const Boolean_Option = [
   "online",
   "selfListen",
@@ -712,6 +719,8 @@ class IntegratedNexusLoginSystem {
       });
 
       fs.writeFileSync(this.options.appstatePath, JSON.stringify(fixedAppstate, null, 2));
+      metadata.appStatePath = this.options.appstatePath;
+      this.logger(`Session saved to: ${path.basename(this.options.appstatePath)}`, '💾');
 
       // Create backup
       const backupName = `appstate_${new Date().toISOString().replace(/[:.]/g, '-')}.json`;
@@ -859,7 +868,8 @@ class IntegratedNexusLoginSystem {
                   family_device_id: androidDevice.familyDeviceId
                 },
                 generated_at: new Date().toISOString(),
-                persistent_device: !!this.options.persistentDevice
+                persistent_device: !!this.options.persistentDevice,
+                appStatePath: this.options.appstatePath
               };
 
               this.saveAppstate(appstate, result);
@@ -948,6 +958,8 @@ class IntegratedNexusLoginSystem {
                 });
               }
 
+              const appStatePath = credentials.appStatePath || credentials.appstatePath;
+
               const result = {
                 success: true,
                 appstate: appstate,
@@ -957,6 +969,7 @@ class IntegratedNexusLoginSystem {
                   user_agent: androidDevice.userAgent
                 },
                 method: '2FA',
+                appStatePath: appStatePath,
                 generated_at: new Date().toISOString()
               };
 
@@ -1131,6 +1144,7 @@ async function integratedNexusLogin(credentials = null, options = {}) {
         proxy: process.env.NEXUS_PROXY || process.env.HTTPS_PROXY || process.env.HTTP_PROXY,
         acceptLanguage: process.env.NEXUS_ACCEPT_LANGUAGE || 'en-US,en;q=0.9',
         disablePreflight: process.env.NEXUS_DISABLE_PREFLIGHT === '1' || process.env.NEXUS_DISABLE_PREFLIGHT === 'true',
+        appStatePath: result.appStatePath,
         ...options
       };
 
@@ -1149,6 +1163,12 @@ async function integratedNexusLogin(credentials = null, options = {}) {
               botError: err.message
             });
           } else {
+            // VERCEL STABILITY WARNING
+            if (process.env.VERCEL || process.env.NOW_REGION) {
+              Logger.warn('PLATFORM', 'Vercel/Serverless detected. listenMqtt is NOT supported here.');
+              Logger.warn('PLATFORM', 'Bot will work for outbound actions (sending) only.');
+            }
+
             Logger.success('BOT-INIT', 'Bot initialized successfully');
             Logger.success('READY', '🚀 Nexus-FCA is now ready for use');
             Logger.info('STATUS', `Bot online | User ID: ${api.getCurrentUserID()}`);
@@ -1232,7 +1252,8 @@ async function login(loginData, options = {}, callback) {
         password: loginData.password,
         twofactor: loginData.twofactor || loginData.otp || undefined,
         _2fa: loginData._2fa || undefined,
-        appstate: loginData.appState || loginData.appstate || undefined
+        appstate: loginData.appState || loginData.appstate || undefined,
+        appStatePath: loginData.appStatePath || loginData.appstatePath || undefined
       }, { autoStartBot: false }); // ONLY generate cookies, NO bot startup
 
       if (!result.success || !result.appstate) {
@@ -1277,6 +1298,7 @@ async function login(loginData, options = {}, callback) {
         online: true,
         emitReady: false,
         userAgent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36",
+        appStatePath: result.appStatePath,
         ...options
       };
 

package/lib/factory/ApiFactory.js

@@ -169,6 +169,7 @@ class ApiFactory {
             wsReqNumber: 0,
             wsTaskNumber: 0,
             globalSafety: this.globalSafety,
+            appStatePath: globalOptions.appStatePath || null,
             pendingEdits: new Map()
         };
     }
@@ -183,6 +184,9 @@ class ApiFactory {
                     globalOptions[key] = options[key];
                 });
             },
+            autoTyping: (enable = true) => {
+                globalOptions.autoTyping = !!enable;
+            },
             getAppState: function () {
                 const appState = utils.getAppState(ctx.jar);
                 return appState.filter((item, index, self) =>
@@ -217,6 +221,11 @@ class ApiFactory {
             }
         };
 
+        // Default options
+        if (typeof globalOptions.autoTyping === 'undefined') {
+            globalOptions.autoTyping = true; // Enabled by default for safety
+        }
+
         // Default edit settings
         if (!globalOptions.editSettings) {
             globalOptions.editSettings = {
@@ -293,9 +302,9 @@ class ApiFactory {
         globalOptions.groupQueueIdleMs = 30 * 60 * 1000;
 
         api._sendMessageDirect = DIRECT_FN;
-        api.sendMessage = function (message, threadID, cb) {
+        api.sendMessage = function (message, threadID, cb, replyToMessage) {
             if (!globalOptions.groupQueueEnabled || !isGroupThread(threadID)) {
-                return api._sendMessageDirect(message, threadID, cb);
+                return api._sendMessageDirect(message, threadID, cb, replyToMessage);
             }
             let entry = groupQueues.get(threadID);
             if (!entry) { entry = { q: [], sending: false, lastActive: Date.now() }; groupQueues.set(threadID, entry); }
@@ -304,7 +313,7 @@ class ApiFactory {
                 entry.q.shift();
                 if (ctx.health) ctx.health.recordGroupQueuePrune(0, 0, 1);
             }
-            entry.q.push({ message, threadID, cb });
+            entry.q.push({ message, threadID, cb, replyToMessage });
             processQueue(threadID, entry);
         };
 
@@ -312,13 +321,13 @@ class ApiFactory {
             if (entry.sending) return;
             if (!entry.q.length) return;
             entry.sending = true;
-            const { message, threadID: tid, cb } = entry.q.shift();
-            api._sendMessageDirect(message, tid, function (err, res) {
+            const item = entry.q.shift();
+            api._sendMessageDirect(item.message, item.threadID, function (err, res) {
                 try { if (!err && this.globalSafety) this.globalSafety.recordEvent(); } catch (_) { }
-                if (typeof cb === 'function') cb(err, res);
+                if (typeof item.cb === 'function') item.cb(err, res);
                 entry.sending = false;
                 setImmediate(() => processQueue(threadID, entry));
-            }.bind(this));
+            }.bind(this), item.replyToMessage);
         }
 
         api._flushGroupQueue = function (threadID) {

package/lib/mqtt/MqttManager.js

@@ -22,7 +22,7 @@ class MqttManager extends EventEmitter {
         this.heartbeatInterval = null;
         this.connectionTimeout = null;
         this.lastActivity = Date.now();
-        
+
         // Performance metrics
         this.metrics = {
             messagesReceived: 0,
@@ -49,13 +49,13 @@ class MqttManager extends EventEmitter {
             }
 
             logger('🔄 Connecting to MQTT...', 'info');
-            
+
             const options = this._buildConnectionOptions();
             this.client = mqtt.connect(this.ctx.mqttEndpoint, options);
-            
+
             this._setupEventHandlers();
             this._startHeartbeat();
-            
+
             // Connection timeout
             this.connectionTimeout = setTimeout(() => {
                 if (!this.isConnected) {
@@ -81,7 +81,7 @@ class MqttManager extends EventEmitter {
             clean: true,
             connectTimeout: 10000,
             reconnectPeriod: 0, // Disable auto-reconnect, we handle it
-            keepalive: 60,
+            keepalive: 10,
             protocolVersion: 4,
             username: JSON.stringify({
                 "u": this.ctx.userID,
@@ -150,15 +150,15 @@ class MqttManager extends EventEmitter {
         this.reconnectDelay = 1000;
         this.metrics.lastConnected = Date.now();
         this.metrics.reconnections++;
-        
+
         clearTimeout(this.connectionTimeout);
-        
+
         logger('✅ MQTT connected successfully', 'info');
         logger(`📊 Connection metrics: Reconnections: ${this.metrics.reconnections}, Errors: ${this.metrics.errors}`, 'info');
-        
+
         this._subscribeToTopics();
         this._processMessageQueue();
-        
+
         this.emit('connected');
     }
 
@@ -169,7 +169,7 @@ class MqttManager extends EventEmitter {
     _subscribeToTopics() {
         const topics = [
             "/ls_req",
-            "/ls_resp", 
+            "/ls_resp",
             "/legacy_web",
             "/webrtc",
             "/rtc_multi",
@@ -208,10 +208,10 @@ class MqttManager extends EventEmitter {
         try {
             this.lastActivity = Date.now();
             this.metrics.messagesReceived++;
-            
+
             const messageStr = message.toString();
             let parsedMessage;
-            
+
             try {
                 parsedMessage = JSON.parse(messageStr);
             } catch (parseError) {
@@ -221,7 +221,7 @@ class MqttManager extends EventEmitter {
 
             // Enhanced message processing with caching
             this._processMessage(topic, parsedMessage);
-            
+
         } catch (error) {
             logger(`❌ Error processing MQTT message: ${error.message}`, 'error');
             this.metrics.errors++;
@@ -245,7 +245,7 @@ class MqttManager extends EventEmitter {
         if (message.syncToken) {
             this.ctx.syncToken = message.syncToken;
         }
-        
+
         if (message.lastIssuedSeqId) {
             this.ctx.lastSeqId = parseInt(message.lastIssuedSeqId);
         }
@@ -270,7 +270,7 @@ class MqttManager extends EventEmitter {
         logger('🔌 MQTT connection closed', 'warn');
         this._stopHeartbeat();
         this.emit('disconnected');
-        
+
         // Auto-reconnect if not intentionally closed
         if (this.client && !this.client.disconnecting) {
             this._handleReconnect();
@@ -308,9 +308,9 @@ class MqttManager extends EventEmitter {
 
         this.reconnectAttempts++;
         const delay = Math.min(this.reconnectDelay * Math.pow(2, this.reconnectAttempts - 1), this.maxReconnectDelay);
-        
+
         logger(`🔄 MQTT reconnecting in ${delay}ms (attempt ${this.reconnectAttempts}/${this.maxReconnectAttempts})`, 'warn');
-        
+
         setTimeout(() => {
             this.connect();
         }, delay);
@@ -350,7 +350,7 @@ class MqttManager extends EventEmitter {
             this.messageQueue.shift(); // Remove oldest message
             logger('⚠️ Message queue full, dropping oldest message', 'warn');
         }
-        
+
         this.messageQueue.push(messageData);
         logger(`📦 Queued message for ${messageData.topic} (queue size: ${this.messageQueue.length})`, 'info');
     }
@@ -361,12 +361,12 @@ class MqttManager extends EventEmitter {
      */
     _processMessageQueue() {
         if (this.messageQueue.length === 0) return;
-        
+
         logger(`📦 Processing ${this.messageQueue.length} queued messages`, 'info');
-        
+
         const messages = [...this.messageQueue];
         this.messageQueue = [];
-        
+
         messages.forEach(messageData => {
             this.publish(messageData.topic, messageData.message, messageData.options);
         });
@@ -385,7 +385,7 @@ class MqttManager extends EventEmitter {
                     logger('💓 MQTT heartbeat - inactive for 5 minutes, sending ping', 'info');
                     this.client.ping();
                 }
-                
+
                 // Update uptime
                 if (this.metrics.lastConnected) {
                     this.metrics.uptime = Date.now() - this.metrics.lastConnected;
@@ -422,9 +422,9 @@ class MqttManager extends EventEmitter {
      */
     disconnect() {
         logger('🔌 Disconnecting MQTT gracefully...', 'info');
-        
+
         this._stopHeartbeat();
-        
+
         if (this.client) {
             this.client.publish("/browser_close", "{}", { qos: 0 });
             this.client.end(false, () => {
@@ -432,7 +432,7 @@ class MqttManager extends EventEmitter {
                 this.emit('disconnected');
             });
         }
-        
+
         this.isConnected = false;
     }
 
@@ -441,13 +441,13 @@ class MqttManager extends EventEmitter {
      */
     forceDisconnect() {
         logger('⚡ Force disconnecting MQTT...', 'warn');
-        
+
         this._stopHeartbeat();
-        
+
         if (this.client) {
             this.client.end(true);
         }
-        
+
         this.isConnected = false;
         this.emit('disconnected');
     }

package/lib/network/HealthServer.js

@@ -0,0 +1,71 @@
+"use strict";
+
+const http = require('http');
+const log = require('npmlog');
+const pkg = require('../../package.json');
+
+/**
+ * Minimal Health Server for Render/Railway/Cloud compatibility.
+ * Responds to platform health checks on the assigned PORT.
+ */
+class HealthServer {
+    constructor(options = {}) {
+        this.port = process.env.PORT || options.port || 10000;
+        this.server = null;
+        this.active = false;
+    }
+
+    start() {
+        if (this.active) return;
+
+        this.server = http.createServer((req, res) => {
+            if (req.url === '/health' || req.url === '/') {
+                res.writeHead(200, { 'Content-Type': 'text/html' });
+                const html = `
+                <!DOCTYPE html>
+                <html>
+                <head>
+                    <title>Nexus-FCA Status</title>
+                    <style>
+                        body { background: #0f172a; color: #f8fafc; font-family: sans-serif; display: flex; align-items: center; justify-content: center; height: 100vh; margin: 0; }
+                        .card { background: #1e293b; padding: 2rem; border-radius: 1rem; box-shadow: 0 10px 15px -3px rgba(0, 0, 0, 0.1); border: 1px solid #334155; text-align: center; }
+                        h1 { color: #38bdf8; margin-top: 0; }
+                        .status { display: inline-block; padding: 0.25rem 0.75rem; background: #065f46; color: #34d399; border-radius: 9999px; font-size: 0.875rem; font-weight: 600; }
+                        .version { color: #64748b; font-size: 0.75rem; margin-top: 1rem; }
+                    </style>
+                </head>
+                <body>
+                    <div class="card">
+                        <h1>✨ Nexus-FCA</h1>
+                        <div class="status">● System Operational</div>
+                        <div class="version">Core v${pkg.version} | Stability: 99.9%</div>
+                    </div>
+                </body>
+                </html>
+                `;
+                res.end(html);
+            } else {
+                res.writeHead(404);
+                res.end();
+            }
+        });
+
+        this.server.listen(this.port, () => {
+            log.info("HealthServer", `System health endpoint active on port ${this.port}`);
+            this.active = true;
+        });
+
+        this.server.on('error', (err) => {
+            log.error("HealthServer", `Failed to start: ${err.message}`);
+        });
+    }
+
+    stop() {
+        if (this.server) {
+            this.server.close();
+            this.active = false;
+        }
+    }
+}
+
+module.exports = HealthServer;

package/lib/safety/CookieManager.js

@@ -20,45 +20,51 @@ class CookieManager {
     if (!Array.isArray(cookies) || cookies.length === 0) {
       return cookies;
     }
-    
+
     const {
       defaultExpiryDays = 90,
       criticalExpiryDays = 90,
       refreshExisting = true
     } = options;
-    
+
     const now = new Date();
     const criticalCookies = ['c_user', 'xs', 'fr', 'datr', 'sb', 'spin'];
     let fixedCount = 0;
-    
+
     for (const cookie of cookies) {
       // Skip cookies with no key
       if (!cookie.key) continue;
-      
+
       const isCritical = criticalCookies.includes(cookie.key);
       const days = isCritical ? criticalExpiryDays : defaultExpiryDays;
-      
+
       // Check if cookie needs expiry fix
-      const needsFix = !cookie.expires || 
-                      refreshExisting || 
-                      !this._isValidDate(cookie.expires) ||
-                      this._getRemainingDays(cookie.expires) < 7;
-      
+      const needsFix = !cookie.expires ||
+        refreshExisting ||
+        !this._isValidDate(cookie.expires) ||
+        this._getRemainingDays(cookie.expires) < 7;
+
       if (needsFix) {
+        // STICKY COOKIES: If it's a critical cookie (sb, datr, c_user) and still has > 60 days, skip refresh
+        const stickyCookies = ['sb', 'datr', 'c_user'];
+        if (stickyCookies.includes(cookie.key) && this._getRemainingDays(cookie.expires) > 60) {
+          continue;
+        }
+
         // Set expiry to future date
         const futureDate = new Date(now.getTime() + (days * 24 * 60 * 60 * 1000));
         cookie.expires = futureDate.toUTCString();
         fixedCount++;
       }
     }
-    
+
     if (fixedCount > 0) {
       logger(`Fixed expiry dates for ${fixedCount} cookies`, 'info');
     }
-    
+
     return cookies;
   }
-  
+
   /**
    * Check if cookie expiry is a valid date
    * @param {string} dateStr - Date string to check
@@ -69,7 +75,7 @@ class CookieManager {
     const date = new Date(dateStr);
     return !isNaN(date.getTime());
   }
-  
+
   /**
    * Get days remaining until expiry
    * @param {string} dateStr - Date string to check
@@ -85,7 +91,7 @@ class CookieManager {
       return 0;
     }
   }
-  
+
   /**
    * Check if appstate has critical cookies
    * @param {Array} cookies - Cookies to check
@@ -95,22 +101,23 @@ class CookieManager {
     if (!Array.isArray(cookies) || cookies.length === 0) {
       return { valid: false, missing: ['all'] };
     }
-    
-    const criticalCookies = ['c_user', 'xs', 'datr', 'sb'];
+
+    const criticalCookies = ['c_user', 'xs', 'datr', 'sb', 'fr', 'spin'];
     const missing = [];
-    
+
     for (const critical of criticalCookies) {
-      if (!cookies.some(c => c.key === critical)) {
+      const found = cookies.find(c => c.key === critical);
+      if (!found || !found.value || found.value === 'deleted') {
         missing.push(critical);
       }
     }
-    
+
     return {
       valid: missing.length === 0,
       missing
     };
   }
-  
+
   /**
    * Generate default cookie expiry date
    * @param {string} cookieName - Name of cookie
@@ -119,13 +126,13 @@ class CookieManager {
   static getDefaultExpiry(cookieName) {
     const now = new Date();
     const criticalCookies = ['c_user', 'xs', 'fr', 'datr', 'sb'];
-    
+
     // Critical cookies get 90 days, others get 30 days
     const days = criticalCookies.includes(cookieName) ? 90 : 30;
     const future = new Date(now.getTime() + (days * 24 * 60 * 60 * 1000));
     return future.toUTCString();
   }
-  
+
   /**
    * Load and fix appstate file
    * @param {string} appstatePath - Path to appstate.json
@@ -137,26 +144,26 @@ class CookieManager {
         logger(`Appstate file not found: ${appstatePath}`, 'error');
         return null;
       }
-      
+
       const cookies = JSON.parse(fs.readFileSync(appstatePath, 'utf8'));
       if (!Array.isArray(cookies)) {
         logger('Invalid appstate format: not an array', 'error');
         return null;
       }
-      
+
       // Fix expiry dates
       const fixed = this.fixCookieExpiry(cookies);
-      
+
       // Validate critical cookies
       const validation = this.validateCriticalCookies(fixed);
       if (!validation.valid) {
         logger(`Missing critical cookies: ${validation.missing.join(', ')}`, 'warn');
       }
-      
+
       // Save back fixed cookies
       fs.writeFileSync(appstatePath, JSON.stringify(fixed, null, 2));
       logger(`Fixed and saved appstate with ${fixed.length} cookies`, 'info');
-      
+
       return fixed;
     } catch (err) {
       logger(`Failed to load and fix appstate: ${err.message}`, 'error');

package/lib/safety/FacebookSafety.js

@@ -6,6 +6,7 @@
 const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
+const log = require('npmlog');
 // StealthMode module has been removed to avoid global human-like pauses
 // that can harm perceived stability. FacebookSafety now relies on
 // lightweight adaptive delays and backoff only.
@@ -49,13 +50,13 @@ class FacebookSafety {
         this.regions = ['ASH', 'ATL', 'DFW', 'ORD', 'PHX', 'SJC', 'IAD'];
         this.currentRegion = this.regions[Math.floor(Math.random() * this.regions.length)];
 
-        // ULTRA-SAFE human delay patterns - Relaxed for usability
+        // ULTRA-SAFE human delay patterns - More conservative
         this.humanDelayPatterns = {
-            typing: { min: 500, max: 1500 },         // Normal typing (0.5-1.5s)
-            reading: { min: 1000, max: 3000 },       // Normal reading (1-3s)
-            thinking: { min: 1000, max: 4000 },      // Normal thinking (1-4s)
-            browsing: { min: 500, max: 2000 },       // Normal browsing (0.5-2s)
-            messageDelay: { min: 1000, max: 3000 }   // 1-3s between messages (much faster)
+            typing: { min: 800, max: 2500 },         // Normal typing (0.8-2.5s)
+            reading: { min: 1500, max: 5000 },       // Normal reading (1.5-5s)
+            thinking: { min: 1500, max: 6000 },      // Normal thinking (1.5-6s)
+            browsing: { min: 1000, max: 3000 },      // Normal browsing (1-3s)
+            messageDelay: { min: 1500, max: 4000 }   // 1.5-4s between messages (Conservative)
         };
 
         this.sessionMetrics = {
@@ -96,6 +97,9 @@ class FacebookSafety {
         this._dynamicHeartbeatTimer = null; // replaces fixed interval heartbeat for risk-tier tuning
         this._riskLast = 'low';
 
+        // Safety Store for Token Mirroring (Recovery on ephemeral platforms)
+        this.safetyStorePath = path.join(process.cwd(), 'lib', 'safety', 'safety_store.json');
+
         this.initSafety();
     }
 
@@ -105,9 +109,14 @@ class FacebookSafety {
             this.setupSafeRefresh();
         }
 
+        // Recovery from safety store
+        this._loadFromSafetyStore();
+
         // Setup session monitoring
         this.setupSessionMonitoring();
         this._schedulePeriodicRecycle();
+        this.scheduleLightPoke();
+        this.scheduleSessionBreath();
     }
 
     /**
@@ -328,9 +337,25 @@ class FacebookSafety {
                 maxMs = 90 * 60 * 1000;          // 90m
             }
             const interval = minMs + Math.random() * (maxMs - minMs);
-            console.log(`🔒 Next token refresh in ${Math.floor(interval / (60 * 1000))}m (keep-alive mode)`);
+            log.info("FacebookSafety", `Next token refresh in ${Math.floor(interval / (60 * 1000))}m (keep-alive mode)`);
             const t = setTimeout(async () => {
                 await this.refreshSafeSession();
+
+                // Extra: Explicitly refresh and save fb_dtsg every ~2 hours
+                if (Date.now() - this._lastHeavyMaintenanceTs > 2 * 60 * 60 * 1000) {
+                    try {
+                        if (this.api && typeof this.api.refreshFb_dtsg === 'function') {
+                            const newDtsg = await this.api.refreshFb_dtsg();
+                            if (newDtsg && this.ctx && this.ctx.appStatePath) {
+                                // Auto-save will be triggered by saveCookies inside refreshFb_dtsg (if it calls post)
+                                // But we force a saveAppState here just to be sure
+                                require('../../utils').saveAppState(this.ctx);
+                                log.info("FacebookSafety", 'Critical token (fb_dtsg) refreshed and saved to disk');
+                            }
+                        }
+                    } catch (_) { }
+                }
+
                 schedule();
             }, interval);
             this._registerTimer(t);
@@ -474,6 +499,38 @@ class FacebookSafety {
         this._periodicRecycleTimer = t;
     }
 
+    /**
+     * Lightweight poke (fb_dtsg refresh only) integrated to remove duplicate logic in index.js
+     */
+    scheduleLightPoke() {
+        if (this._lightPokeTimer || this._destroyed) return;
+        const base = 30 * 60 * 1000; // 30m (Tuned for proactive health)
+        const jitter = (Math.random() * 20 - 10) * 60 * 1000; // ±10m
+        const schedule = () => {
+            if (this._destroyed) return;
+            const t = setTimeout(async () => {
+                if (this._destroyed) return;
+                // Respect spacing: skip if recent heavy refresh
+                if (Date.now() - this._lastRefreshTs < this._minSpacingMs / 2) {
+                    schedule();
+                    return;
+                }
+                try {
+                    if (this.api && typeof this.api.refreshFb_dtsg === 'function') {
+                        await this.api.refreshFb_dtsg().catch(() => { });
+                        this._lastRefreshTs = Date.now();
+                        this._lastLightPokeTs = Date.now();
+                        this.safetyEmit('lightPoke', { ts: Date.now() });
+                    }
+                } catch (_) { }
+                schedule();
+            }, base + (Math.random() * 20 - 10) * 60 * 1000);
+            this._registerTimer(t);
+            this._lightPokeTimer = t;
+        };
+        schedule();
+    }
+
     // Heartbeat ping & watchdog - ULTRA SAFE VERSION
     _startHeartbeat() {
         if (this._heartbeatTimer) clearInterval(this._heartbeatTimer);
@@ -576,11 +633,12 @@ class FacebookSafety {
         let preMqttConnected = this.ctx && this.ctx.mqttClient && this.ctx.mqttClient.connected;
         let preLastEvent = this._lastEventTs;
         try {
-            console.log('🔄 Performing safe session refresh...');
+            log.info("FacebookSafety", 'Performing safe session refresh...');
             if (!this.api || typeof this.api.refreshFb_dtsg !== 'function') {
-                console.log('⚠️ Safe refresh skipped: api.refreshFb_dtsg not available');
+                log.warn("FacebookSafety", 'Safe refresh skipped: api.refreshFb_dtsg not available');
                 return;
             }
+
             // Abort protection if takes too long (network hang)
             const timeoutMs = 25 * 1000;
             const controller = new AbortController();
@@ -588,6 +646,11 @@ class FacebookSafety {
             let res;
             try {
                 res = await this.api.refreshFb_dtsg({ signal: controller.signal });
+                this._saveToSafetyStore(); // Mirror to safety store
+            } catch (fbErr) {
+                log.warn("FacebookSafety", 'Primary fb_dtsg refresh failed, attempting Business fallback...');
+                res = await this.refreshFb_dtsgBusiness().catch(() => null);
+                if (!res) throw fbErr;
             } finally { clearTimeout(timeout); }
             this.sessionMetrics.errorCount = Math.max(0, this.sessionMetrics.errorCount - 1);
             this.sessionMetrics.lastActivity = Date.now();
@@ -639,35 +702,25 @@ class FacebookSafety {
     }
 
     /**
-     * Lightweight poke (fb_dtsg refresh only) integrated to remove duplicate logic in index.js
+     * Fallback Token Refresh via Business Suite
+     * Business endpoints are often more stable for bots.
      */
-    scheduleLightPoke() {
-        if (this._lightPokeTimer || this._destroyed) return;
-        const base = 45 * 60 * 1000; // 45m (Reduced from 6h to keep session alive)
-        const jitter = (Math.random() * 20 - 10) * 60 * 1000; // ±10m
-        const schedule = () => {
-            if (this._destroyed) return;
-            const t = setTimeout(async () => {
-                if (this._destroyed) return;
-                // Respect spacing: skip if recent heavy refresh
-                if (Date.now() - this._lastRefreshTs < this._minSpacingMs / 2) {
-                    schedule();
-                    return;
-                }
-                try {
-                    if (this.api && typeof this.api.refreshFb_dtsg === 'function') {
-                        await this.api.refreshFb_dtsg().catch(() => { });
-                        this._lastRefreshTs = Date.now();
-                        this._lastLightPokeTs = Date.now();
-                        this.safetyEmit('lightPoke', { ts: Date.now() });
-                    }
-                } catch (_) { }
-                schedule();
-            }, base + (Math.random() * 20 - 10) * 60 * 1000);
-            this._registerTimer(t);
-            this._lightPokeTimer = t;
-        };
-        schedule();
+    async refreshFb_dtsgBusiness() {
+        if (!this.api || !this.ctx) return null;
+        try {
+            const utils = require('../../utils');
+            const res = await utils.get("https://business.facebook.com/business_locations", this.ctx.jar, null, { noRef: true }, this.ctx);
+            const html = res.body;
+            const match = html.match(/\["DTSGInitialData",\[\],\{"token":"(.*?)"\},/);
+            if (match && match[1]) {
+                this.ctx.fb_dtsg = match[1];
+                log.info("FacebookSafety", 'Refreshed fb_dtsg via Business fallback');
+                return match[1];
+            }
+        } catch (e) {
+            log.verbose("FacebookSafety", 'Business refresh failed: ' + e.message);
+        }
+        return null;
     }
 
     _registerTimer(t) {
@@ -678,7 +731,7 @@ class FacebookSafety {
     // Cleanup / destroy resources (to prevent dangling timers)
     destroy() {
         this._destroyed = true;
-        const timers = [this._safeRefreshInterval, this._safeRefreshTimer, this._heartbeatTimer, this._watchdogTimer, this._periodicRecycleTimer, this._lightPokeTimer];
+        const timers = [this._safeRefreshInterval, this._safeRefreshTimer, this._heartbeatTimer, this._watchdogTimer, this._periodicRecycleTimer, this._lightPokeTimer, this._breathTimer];
         timers.forEach(t => t && clearTimeout(t));
         // Clear any registered anonymous timers
         this._timerRegistry.forEach(t => clearTimeout(t));
@@ -800,16 +853,17 @@ class FacebookSafety {
         const risk = this.sessionMetrics.riskLevel;
         const since = Date.now() - this._lastHeavyMaintenanceTs;
         const inWindow = since < this._adaptivePacingWindowMs;
-        let min = 0, max = 0;
-        if (inWindow) {
-            if (risk === 'high') { min = 600; max = 1500; }
-            else if (risk === 'medium') { min = 200; max = 800; }
-            else { min = 0; max = 300; }
-        } else {
-            // outside pacing window only high risk adds mild delay
-            if (risk === 'high') { min = 150; max = 600; }
+
+        let min = 1000, max = 2500; // Default baseline human pace
+
+        if (risk === 'high') {
+            min = 3500; max = 6500;
+        } else if (risk === 'medium') {
+            min = 2000; max = 4500;
+        } else if (inWindow) {
+            min = 1500; max = 3000;
         }
-        if (max <= 0) return 0;
+
         return Math.floor(min + Math.random() * (max - min));
     }
 
@@ -833,6 +887,71 @@ class FacebookSafety {
     setSafetyEventHandler(handler) {
         this.onSafetyEvent = handler;
     }
+
+    /**
+     * ULTRA-LIGHTWEIGHT "Session Breath"
+     * Performs a tiny request to maintain session activity without heavy overhead or detection risk.
+     */
+    scheduleSessionBreath() {
+        if (this._breathTimer || this._destroyed) return;
+        const base = 20 * 60 * 1000; // 20m (Breath cycle)
+        const schedule = () => {
+            if (this._destroyed) return;
+            const t = setTimeout(async () => {
+                if (this._destroyed) return;
+                try {
+                    const utils = require('../../utils');
+                    // Hit a static lightweight FB asset or GraphQL endpoint
+                    await utils.get("https://www.facebook.com/rsrc.php/v3/yO/r/688pC_S3Y6X.png", this.ctx.jar, null, { noRef: true }, this.ctx).catch(() => { });
+                    this.safetyEmit('sessionBreath', { ts: Date.now() });
+                } catch (_) { }
+                schedule();
+            }, base + (Math.random() * 5 * 60 * 1000)); // 20-25m
+            this._registerTimer(t);
+            this._breathTimer = t;
+        };
+        schedule();
+    }
+
+
+    /**
+     * Mirror critical tokens to a separate store for recovery on ephemeral platforms.
+     */
+    _saveToSafetyStore() {
+        if (!this.ctx || !this.ctx.fb_dtsg) return;
+        try {
+            const data = {
+                fb_dtsg: this.ctx.fb_dtsg,
+                jazoest: this.ctx.jazoest,
+                updatedAt: new Date().toISOString()
+            };
+            const dir = require('path').dirname(this.safetyStorePath);
+            const fs = require('fs');
+            if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(this.safetyStorePath, JSON.stringify(data, null, 2));
+        } catch (e) {
+            log.verbose("FacebookSafety", "Safety store save failed: " + e.message);
+        }
+    }
+
+    /**
+     * Recovery logic from safety store.
+     */
+    _loadFromSafetyStore() {
+        try {
+            const fs = require('fs');
+            if (fs.existsSync(this.safetyStorePath)) {
+                const data = JSON.parse(fs.readFileSync(this.safetyStorePath, 'utf8'));
+                if (data.fb_dtsg && (!this.ctx.fb_dtsg || this.ctx.fb_dtsg === 'undefined')) {
+                    this.ctx.fb_dtsg = data.fb_dtsg;
+                    this.ctx.jazoest = data.jazoest;
+                    log.info("FacebookSafety", "Recovered tokens from safety store");
+                }
+            }
+        } catch (e) {
+            log.verbose("FacebookSafety", "Safety store load failed: " + e.message);
+        }
+    }
 }
 
 module.exports = FacebookSafety;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nexus-fca",
-  "version": "3.2.3",
-  "description": "Nexus-FCA 3.2.3 – Advanced, Secure & Stable Facebook Messenger API.",
+  "version": "3.3.0",
+  "description": "Nexus-FCA 3.3.0 – Advanced, Secure & Stable Facebook Messenger API.",
   "main": "index.js",
   "repository": {
     "type": "git",

package/src/listenMqtt.js

@@ -203,11 +203,18 @@ function startForegroundRefresh(ctx) {
     clearInterval(ctx._foregroundRefreshInterval);
     ctx._foregroundRefreshInterval = null;
   }
+  if (ctx._presenceRefreshInterval) {
+    clearInterval(ctx._presenceRefreshInterval);
+    ctx._presenceRefreshInterval = null;
+  }
   const options = ctx.globalOptions || {};
   if (options.foregroundRefreshEnabled === false) return;
+  
+  // Foreground state refresh - reduced from 15min to 1min for better activity signal
   const minutes = Number.isFinite(options.foregroundRefreshMinutes)
-    ? Math.max(1, options.foregroundRefreshMinutes)
-    : 15;
+    ? Math.max(0.5, options.foregroundRefreshMinutes)
+    : 1; // Changed: 15 → 1 minute (like ws3-fca approach)
+  
   ctx._foregroundRefreshInterval = setInterval(() => {
     if (!ctx.mqttClient || !ctx.mqttClient.connected) return;
     try {
@@ -224,12 +231,33 @@ function startForegroundRefresh(ctx) {
       }
     }
   }, minutes * 60 * 1000);
+  
+  // ws3-fca style presence signal - sends activity indicator every 50s
+  // This prevents Facebook from marking connection as idle/background
+  const presenceIntervalSec = Number.isFinite(options.presenceRefreshSeconds)
+    ? Math.max(30, options.presenceRefreshSeconds)
+    : 50; // ws3-fca uses 50 seconds
+  
+  ctx._presenceRefreshInterval = setInterval(() => {
+    if (!ctx.mqttClient || !ctx.mqttClient.connected) return;
+    try {
+      // Generate presence payload like ws3-fca
+      const presencePayload = utils.generatePresence(ctx.userID);
+      ctx.mqttClient.publish("/t_p", presencePayload, { qos: 0, retain: false });
+    } catch (err) {
+      // Silent fail for presence - not critical
+    }
+  }, presenceIntervalSec * 1000);
 }
 function stopForegroundRefresh(ctx) {
   if (ctx && ctx._foregroundRefreshInterval) {
     clearInterval(ctx._foregroundRefreshInterval);
     ctx._foregroundRefreshInterval = null;
   }
+  if (ctx && ctx._presenceRefreshInterval) {
+    clearInterval(ctx._presenceRefreshInterval);
+    ctx._presenceRefreshInterval = null;
+  }
 }
 function getStormGuard(ctx) {
   if (!ctx._mqttStorm) {
@@ -503,8 +531,17 @@ function listenMqtt(defaultFuncs, api, ctx, globalCallback) {
   }
   const chatOn = (ctx.globalOptions && ctx.globalOptions.online === false) ? false : true;
   const foreground = getForegroundState(ctx);
+  
+  // ws3-fca style: Generate fresh sessionID and clientID on EACH reconnect
+  // This prevents Facebook from detecting "stale" sessions and force-disconnecting
   const sessionID = Math.floor(Math.random() * Number.MAX_SAFE_INTEGER) + 1;
+  const clientID = utils.generateClientID ? utils.generateClientID() : `mqttwsclient_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
   const GUID = utils.getGUID();
+  
+  // Store for debugging/tracking
+  ctx._lastSessionID = sessionID;
+  ctx._lastClientID = clientID;
+  
   const username = {
     u: ctx.userID,
     s: sessionID,
@@ -528,16 +565,26 @@ function listenMqtt(defaultFuncs, api, ctx, globalCallback) {
   };
   // jitter user agent keep consistent
   const cookies = ctx.jar.getCookies("https://www.facebook.com").join("; ");
+  
+  // MQTT Host Selection - ws3-fca uses messenger.com, we support both with option
+  // messenger.com endpoint appears more stable for some accounts
   let host;
+  const useMessengerDomain = ctx.globalOptions.mqttUseMessengerDomain;
+  const baseDomain = useMessengerDomain ? 'edge-chat.messenger.com' : 'edge-chat.facebook.com';
+  
   if (ctx.mqttEndpoint) {
-    host = `${ctx.mqttEndpoint}&sid=${sessionID}&cid=${GUID}`;
+    host = `${ctx.mqttEndpoint}&sid=${sessionID}&cid=${clientID}`;
   } else if (ctx.region) {
-    host = `wss://edge-chat.facebook.com/chat?region=${ctx.region.toLowerCase()}&sid=${sessionID}&cid=${GUID}`;
+    host = `wss://${baseDomain}/chat?region=${ctx.region.toLowerCase()}&sid=${sessionID}&cid=${clientID}`;
   } else {
-    host = `wss://edge-chat.facebook.com/chat?sid=${sessionID}&cid=${GUID}`;
+    host = `wss://${baseDomain}/chat?sid=${sessionID}&cid=${clientID}`;
   }
+  
+  // Determine Host header based on domain used
+  const hostHeader = useMessengerDomain ? 'edge-chat.messenger.com' : 'edge-chat.facebook.com';
+  
   const options = {
-    clientId: "mqttwsclient",
+    clientId: clientID, // Use dynamic clientID instead of static "mqttwsclient"
     protocolId: "MQIsdp",
     protocolVersion: 3,
     username: JSON.stringify(username),
@@ -550,7 +597,7 @@ function listenMqtt(defaultFuncs, api, ctx, globalCallback) {
           ctx.globalOptions.userAgent ||
           "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
         Referer: "https://www.facebook.com/",
-        Host: "edge-chat.facebook.com",
+        Host: hostHeader,
         Connection: "Upgrade",
         Pragma: "no-cache",
         "Cache-Control": "no-cache",
@@ -783,16 +830,16 @@ function listenMqtt(defaultFuncs, api, ctx, globalCallback) {
     ctx.health.onConnect();
 
     // WS3-style randomized proactive reconnect (tunable window).
-    // Changed: 2-4h → 6-8h to reduce unnecessary reconnects and improve stability
-    // Proactive reconnect prevents long-session forced disconnects by Facebook
+    // CRITICAL FIX: Changed from 6-8h to 45-90min based on ws3-fca analysis (26-60min)
+    // Long sessions (2h+) cause Facebook to force-disconnect, proactive reconnect prevents this
     if (ctx._reconnectTimer) clearTimeout(ctx._reconnectTimer);
     let reconnectTime = null;
     const opts = ctx.globalOptions || {};
     const proactiveEnabled = opts.mqttProactiveReconnectEnabled;
 
     if (proactiveEnabled !== false) {
-      const minM = Number.isFinite(opts.mqttProactiveReconnectMinMinutes) ? opts.mqttProactiveReconnectMinMinutes : 360; // Changed: 120min → 360min (6h)
-      const maxM = Number.isFinite(opts.mqttProactiveReconnectMaxMinutes) ? opts.mqttProactiveReconnectMaxMinutes : 480; // Changed: 240min → 480min (8h)
+      const minM = Number.isFinite(opts.mqttProactiveReconnectMinMinutes) ? opts.mqttProactiveReconnectMinMinutes : 45; // ws3-fca: 26min, we use 45min for safety margin
+      const maxM = Number.isFinite(opts.mqttProactiveReconnectMaxMinutes) ? opts.mqttProactiveReconnectMaxMinutes : 90; // ws3-fca: 60min, we use 90min for safety margin
       const min = Math.min(minM, maxM);
       const max = Math.max(minM, maxM);
       const intervalMinutes = Math.floor(Math.random() * (max - min + 1)) + min;

package/src/sendMessage.js

@@ -269,7 +269,7 @@ module.exports = function (defaultFuncs, api, ctx) {
 		// Changing this to accomodate an array of users
 		if (threadIDType !== "Array" && threadIDType !== "Number" && threadIDType !== "String") return callback({ error: "ThreadID should be of type number, string, or array and not " + threadIDType + "." });
 
-		if (replyToMessage && messageIDType !== 'String') return callback({ error: "MessageID should be of type string and not " + threadIDType + "." });
+		if (replyToMessage && messageIDType !== 'String') return callback({ error: "MessageID should be of type string and not " + messageIDType + "." });
 
 		if (msgType === "String") msg = { body: msg };
 		var disallowedProperties = Object.keys(msg).filter(prop => !allowedProperties[prop]);
@@ -308,11 +308,11 @@ module.exports = function (defaultFuncs, api, ctx) {
 			has_attachment: !!(msg.attachment || msg.url || msg.sticker),
 			signatureID: utils.getSignatureID(),
 			replied_to_message_id: replyToMessage,
-			reply_metadata: replyToMessage ? {
+			reply_metadata: replyToMessage ? JSON.stringify({
 				reply_source_id: replyToMessage,
 				reply_source_type: 1, // 1: Message
 				reply_type: 0 // 0: Reply
-			} : undefined
+			}) : undefined
 		};
 
 		handleLocation(msg, form, callback, () =>

package/utils.js

@@ -87,23 +87,53 @@ function getJar() {
 }
 
 function getHeaders(url, options, ctx, customHeader) {
+    const ua = (options?.userAgent || "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36");
+    const isWindows = ua.includes("Windows NT");
+    const isAndroid = ua.includes("Android");
+    const isChrome = ua.includes("Chrome") && !ua.includes("Edg");
+
     var headers = {
         Referer: "https://www.facebook.com/",
         Host: url.replace("https://", "").split("/")[0],
         Origin: "https://www.facebook.com",
-        "user-agent": (options?.userAgent || "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36"),
+        "user-agent": ua,
         Connection: "keep-alive",
-        "sec-fetch-site": 'same-origin',
-        "sec-fetch-mode": 'cors',
-        "sec-fetch-dest": "empty",
         "accept": "*/*",
         "accept-language": "en-US,en;q=0.9",
-        "sec-ch-ua": '"Google Chrome";v="131", "Chromium";v="131", "Not_A Brand";v="24"',
-        "sec-ch-ua-mobile": "?0",
-        "sec-ch-ua-platform": '"Windows"',
         "dnt": "1",
         "upgrade-insecure-requests": "1"
     };
+
+    // Human-like Fetch headers
+    if (url.includes("/api/graphql/") || url.includes("/messaging/")) {
+        headers["sec-fetch-site"] = 'same-origin';
+        headers["sec-fetch-mode"] = 'cors';
+        headers["sec-fetch-dest"] = "empty";
+    } else {
+        headers["sec-fetch-site"] = 'none';
+        headers["sec-fetch-mode"] = 'navigate';
+        headers["sec-fetch-dest"] = "document";
+    }
+
+    // Dynamic Referer Pattern
+    if (url.includes('graphql')) {
+        headers.Referer = 'https://www.facebook.com/';
+    } else if (url.includes('messages/')) {
+        headers.Referer = 'https://www.facebook.com/messages/';
+    } else if (url.includes('business')) {
+        headers.Referer = 'https://business.facebook.com/';
+    }
+
+    // Dynamic Client Hints - CRITICAL: Must match User-Agent
+    if (isChrome && isWindows) {
+        headers["sec-ch-ua"] = '"Google Chrome";v="131", "Chromium";v="131", "Not_A Brand";v="24"';
+        headers["sec-ch-ua-mobile"] = "?0";
+        headers["sec-ch-ua-platform"] = '"Windows"';
+    } else if (isAndroid) {
+        headers["sec-ch-ua-mobile"] = "?1";
+        // Remove Windows-specific headers for Android UAs
+    }
+
     if (customHeader) Object.assign(headers, customHeader);
     if (ctx && ctx.region) headers["X-MSGR-Region"] = ctx.region;
 
@@ -146,6 +176,7 @@ async function get(url, jar, qs, options, ctx) {
     if (qs) op.searchParams = cleanObject(qs);
 
     return got(url, op).then(function (res) {
+        saveCookies(jar, ctx)(res);
         return res;
     });
 }
@@ -162,6 +193,7 @@ async function get2(url, jar, headers, options, ctx) {
     };
 
     return got(url, op).then(function (res) {
+        saveCookies(jar, ctx)(res);
         return res;
     });
 }
@@ -209,6 +241,7 @@ async function post(url, jar, form, options, ctx, customHeader) {
     }
 
     return got(url, op).then(function (res) {
+        saveCookies(jar, ctx)(res);
         return res;
     });
 }
@@ -235,6 +268,7 @@ async function postFormData(url, jar, form, qs, options, ctx) {
     if (qs) op.searchParams = cleanObject(qs);
 
     return got(url, op).then(function (res) {
+        saveCookies(jar, ctx)(res);
         return res;
     });
 }
@@ -366,6 +400,19 @@ function generatePresence(userID) {
     );
 }
 
+/**
+ * Generate a unique MQTT client ID for each connection
+ * ws3-fca style: Fresh clientID on each reconnect prevents Facebook from
+ * detecting "stale" sessions and force-disconnecting
+ * @returns {string} Unique client identifier
+ */
+function generateClientID() {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).substr(2, 9);
+    const counter = (global.__NEXUS_CLIENT_COUNTER__ = (global.__NEXUS_CLIENT_COUNTER__ || 0) + 1);
+    return `mqttwsclient_${timestamp}_${random}_${counter}`;
+}
+
 function getGUID() {
     // 1. Check Environment Variable (Best for Render/Heroku/Replit)
     if (process.env.NEXUS_DEVICE_ID) {
@@ -1290,9 +1337,11 @@ function parseAndCheckLogin(ctx, defaultFuncs, retryCount = 0, sourceCall) {
         });
     };
 }
-function saveCookies(jar) {
+function saveCookies(jar, ctx) {
     return function (res) {
         var cookies = res.headers["set-cookie"] || [];
+        if (cookies.length === 0) return res;
+
         cookies.forEach(function (c) {
             if (c.indexOf(".facebook.com") > -1 || c.indexOf("facebook.com") > -1) {
                 try {
@@ -1307,10 +1356,50 @@ function saveCookies(jar) {
                 } catch (e) { }
             }
         });
+
+        // AUTO-PERSISTENCE: If ctx has appStatePath, save to disk immediately
+        if (ctx && ctx.appStatePath) {
+            saveAppState(ctx);
+        }
+
         return res;
     };
 }
 
+function saveAppState(ctx) {
+    if (!ctx || !ctx.jar || !ctx.appStatePath) return;
+    try {
+        const appState = getAppState(ctx.jar);
+        const fs = require('fs');
+        const path = require('path');
+
+        // Ensure directory exists
+        const dir = path.dirname(ctx.appStatePath);
+        if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+        fs.writeFileSync(ctx.appStatePath, JSON.stringify(appState, null, 2));
+
+        // Optional: Mirror to environment-ready file for cloud platforms
+        const envPath = ctx.appStatePath.replace('.json', '.env.json');
+        if (process.env.NEXUS_SYNC_ENV_FILE === '1') {
+            fs.writeFileSync(envPath, JSON.stringify(appState));
+        }
+
+        // EXTERNAL PERSISTENCE: If NEXUS_EXTERNAL_SAVE_URL is set, POST there
+        if (process.env.NEXUS_EXTERNAL_SAVE_URL) {
+            const axios = require('axios');
+            axios.post(process.env.NEXUS_EXTERNAL_SAVE_URL, appState, {
+                headers: { 'Content-Type': 'application/json', 'User-Agent': 'Nexus-FCA-Persistence' },
+                timeout: 10000
+            }).catch(err => {
+                log.verbose("utils", "External appstate sync failed: " + err.message);
+            });
+        }
+    } catch (e) {
+        log.verbose("utils", "Auto-save appstate failed: " + e.message);
+    }
+}
+
 var NUM_TO_MONTH = [
     "Jan",
     "Feb",
@@ -1790,6 +1879,15 @@ module.exports = {
     setData_Path,
     getPaths,
     saveCookies,
+    saveAppState,
+    getAppState,
+    getAppStateB64: function () {
+        if (process.env.NEXUS_APPSTATE_B64) {
+            try { return JSON.parse(Buffer.from(process.env.NEXUS_APPSTATE_B64, 'base64').toString('utf8')); }
+            catch (e) { log.error("utils", "Failed to parse NEXUS_APPSTATE_B64"); return null; }
+        }
+        return null;
+    },
     getType,
     _formatAttachment,
     formatHistoryMessage,
@@ -1806,6 +1904,7 @@ module.exports = {
     formatReadReceipt,
     formatRead,
     generatePresence,
+    generateClientID,
     formatDate,
     decodeClientPayload,
     getAppState,