nexus-fca 2.0.7 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## [2.1.0] - 2025-08-20 - SESSION RELIABILITY & PROMISE LOGIN
+### 🚀 Highlights
+Stability-focused release improving long‑running bot sessions, reducing false `not_logged_in` events, and modernizing the login flow.
+
+### Added
+- ✅ Promise support for `login()` (dual callback + Promise API)
+- 🆔 Persistent device fingerprint (saved to `persistent-device.json`) to reduce checkpoint / lock frequency
+- 🛡️ New `validateSession()` multi-endpoint heuristic (lightweight, resilient preflight)
+- ⚙️ New global option: `disablePreflight` (skip session validation if desired)
+- 🔄 Structured error types from `parseAndCheckLogin` (`login_redirect`, `html_login_page`, `network_redirect`, etc.)
+- 🧪 Example: `examples/echo-test.js` (Promise style, supports env credentials or appstate)
+
+### Changed
+- 🔁 `listenMqtt` now performs silent initial validation; only emits `not_logged_in` after a confirmatory retry
+- 🧠 `parseAndCheckLogin` now robustly handles 3xx chains & HTML login fallback pages
+- 🔐 Default behavior: device identity no longer rotates unless explicitly overridden
+- 🧩 Refactored internal cookie & session utilities (centralized in `utils.js`)
+- 📄 Rewritten documentation (README, DOCS, CHANGELOG) for concise modern onboarding
+
+### Fixed
+- ❌ Spurious `parseAndCheckLogin got status code: 302` fatal errors now classified & recovered when possible
+- 💤 False negatives from legacy preflight removed (no premature `not_logged_in` during transient redirects)
+- 🔄 Edge reconnect loop where MQTT closed before revalidation completed
+
+### Migration Notes (2.0.x → 2.1.0)
+- Existing code using callbacks continues to work. To use Promises: `const api = await login(opts);`
+- If you previously depended on device rotation, disable persistent device via option (see README) or delete `persistent-device.json`.
+- Remove any custom preflight hacks; built‑in `validateSession` supersedes them.
+
+### Developer / Internal
+- Centralized session validation pipeline
+- Added granular error classification to aid future retry/backoff strategies
+- Prepared foundation for upcoming metrics hooks in 2.2.x
+
+---
+
 ## [2.0.5] - 2025-07-29 - FULLY INTEGRATED NPM EDITION
 ### 🎯 MAJOR: Full NPM Integration
 - **✅ FULLY INTEGRATED**: Entire Nexus Login System now embedded directly in main `index.js`

package/README.md

@@ -1,334 +1,194 @@
-<div align="center">
+# Nexus-FCA v2.1.0
 
-<img src="https://i.ibb.co/LzkQMGWz/Future-Studio-Synthwave-Logo-Future-Studio-Synthwave-Logo.png" alt="Nexus-FCA Logo" width="500"/>
+<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>
 
-</div>
-
-# Nex## ⚠️## 💬 Community & Support
-- **GitHub**: [github.com/Nexus-016/Nexus-fCA](https://github.com/Nexus-016/Nexus-fCA)
-- **Docs**: See `/docs` for per-feature usage and safety guidelines
-- **Safety Tips**: Always monitor your account status and use fresh appstate cookies
-- **Contributions**: PRs and issues welcome! Safety improvements prioritized
+> 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.
 
 ---
-
-## 🏆 Why Choose Nexus-FCA Ultra-Safe Edition?
-- **50%+ Lower Ban Rate**: Advanced safety algorithms minimize Facebook account risks
-- **Intelligent Protection**: Smart human behavior simulation prevents detection
-- **Real-time Monitoring**: Continuous account health assessment and protection
-- **Future-Proof**: Regular updates to stay ahead of Facebook's detection methods
+## ✨ Highlights
+- 🔐 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)
+- 🧾 Type definitions (`index.d.ts`) & modern Promise / callback API
 
 ---
-
-## ⚠️ Important Disclaimer
-Nexus-FCA is not affiliated with Facebook. This software is provided for educational and research purposes. Users are responsible for complying with Facebook's terms of service and local laws. The ultra-safe features are designed to minimize risks but cannot guarantee complete protection. Always use responsibly and monitor your account status regularly. Account Safety Notice
-Nexus-FCA Maximum Safety Edition is specifically designed to minimize Facebook account ban, lock, checkpoint, and block rates. Our advanced safety system ensures your Facebook account remains secure during bot operations.
-
-**Advanced Safety Protection:**
-- ✅ Ultra-low ban rate protection (minimizes account suspension risk)
-- ✅ Real-time lock and checkpoint detection with auto-shutdown
-- ✅ Smart request patterns that mimic human behavior
-- ✅ Advanced session management to prevent account flags
-- ✅ Intelligent delay patterns for maximum account safety
-- ✅ Enhanced error recovery without triggering Facebook security
-
-Use responsibly and at your own risk. This package is not affiliated with Facebook.Nexus-FCA (2.0.0)
-
-> **A next-generation, high-performance, developer-friendly Facebook Messenger bot framework.**
-
----
-
-## 🚀 What's New in 2.0.3 - Fully Integrated NPM Edition
-- **🎯 FULLY INTEGRATED**: Nexus Login System now built directly into main package!
-- **� NPM COMPATIBLE**: Works perfectly when installed via `npm install nexus-fca`
-- **⚡ ZERO CONFIG**: No external folders needed - everything works out of the box
-- **�🔐 NEXUS LOGIN SYSTEM**: Revolutionary auto-login with appstate generation from username/password
-- **🛡️ ULTRA-LOW BAN RATE**: Advanced protection reduces Facebook account suspension risk by 95%+
-- **🔐 2FA SUPPORT**: Full TOTP integration with Google Authenticator for maximum security
-- **⚡ ONE-LINE SETUP**: Complete bot setup with just one line of code
-- **📊 INTELLIGENT MANAGEMENT**: Auto-backup, validation, and appstate lifecycle management
-- **🛡️ MAXIMUM SAFETY**: Human-like device simulation with Android fingerprinting
-- **🔄 ENHANCED AUTO-RECONNECT**: Smart MQTT connection with safe reconnection patterns
-
-## 🎯 Integrated Nexus Login System
-
-**The most advanced Facebook login system, now fully integrated for NPM usage!**
-
-### � **NPM Installation**
+## 🚀 Install
 ```bash
 npm install nexus-fca
 ```
 
-### ⚡ **One-Line Bot Setup**
-```javascript
-const { nexusLogin } = require('nexus-fca'); // Works directly from npm!
-
-// Complete bot ready in one line!
-const result = await nexusLogin({
-    username: 'your_email@gmail.com',
-    password: 'your_password',
-    twofactor: 'YOUR_2FA_SECRET'
-});
-
-if (result.success) {
-    // Bot is ready! API available immediately
-    result.api.sendMessage('Hello World!', result.api.getCurrentUserID());
-}
-```
-
-### 🔐 **Smart Auto-Detection**
-```javascript
-// Will automatically:
-// 1. Check for existing appstate
-// 2. Use it if valid
-// 3. Generate new one if needed
-// 4. Start Nexus-FCA with ultra-safe settings
-
-const result = await nexusLogin(); // No credentials needed if appstate exists!
-```
-
-### 🛡️ **Maximum Safety Features**
-- ✅ **Human-like Android simulation** with real device fingerprints
-- ✅ **2FA TOTP auto-generation** from Google Authenticator secrets
-- ✅ **Rate limiting & safety delays** to prevent Facebook detection
-- ✅ **Automatic appstate backup** and lifecycle management
-- ✅ **Session validation** and health monitoring
-- ✅ **Error recovery** without triggering security flags
-
-### 📚 **Quick Start Guide**
-
-```
-
-2. **Create test file:**
-```javascript
-// test-bot.js
-const { nexusLogin } = require('nexus-fca');
+---
+## ⚡ Quick Start (Appstate)
+```js
+const login = require('nexus-fca');
 
 (async () => {
-    const result = await nexusLogin({
-        username: 'your_email@gmail.com',
-        password: 'your_password'
-    });
-    
-    if (result.success) {
-        console.log('✅ Bot ready!');
-        result.api.sendMessage('Hello from Nexus!', result.api.getCurrentUserID());
-    }
+  const api = await login({ appState: require('./appstate.json') });
+  console.log('Logged in as', api.getCurrentUserID());
+  api.listen((err, evt) => {
+    if (err) return console.error('Listen error:', err);
+    if (evt.body) api.sendMessage('Echo: ' + evt.body, evt.threadID);
+  });
 })();
 ```
 
-3. **Run your bot:**
-```bash
-node test-bot.js
-```
-
-### 📖 **Complete Documentation**
-- **[NPM Integration Guide](npm-integration-guide.md)** - Complete NPM usage guide
-- **[Integrated Login Guide](integrated-login-guide.md)** - All login methods
-- **[Test Files](test-*.js)** - Ready-to-use test scripts
-- **[Legacy Guide](newloginhowtouse.md)** - Previous version docs
-
----
-
-## 🔐 Legacy Appstate Support
-
-Nexus-FCA maintains full backward compatibility with traditional appstate login.
-
-### ⚡ Traditional Usage
-
-```javascript
+## 🔐 Quick Start (Credentials + 2FA)
+```js
 const login = require('nexus-fca');
 
-login({ appState: require('./appstate.json') }, (err, api) => {
+(async () => {
+  const api = await login({
+    email: process.env.FB_EMAIL,
+    password: process.env.FB_PASS,
+    twofactor: process.env.FB_2FA_SECRET // optional
+  });
+  api.listen((err, msg) => {
     if (err) return console.error(err);
-    console.log('✅ Bot ready with appstate!');
-});
+    if (msg.body === 'ping') api.sendMessage('pong', msg.threadID);
+  });
+})();
 ```
 
-### 📚 Migration Guide
-
-- **Existing appstate files work unchanged**
-- **New integrated system generates fresh appstate automatically**
-- **Mix and match both approaches as needed**
-
 ---
+## 🛡️ Safety Layer (v2.1.0 Improvements)
+| 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 |
 
-## 🖼️ Demo
-
-<div align="center">
-  <img src="https://i.ibb.co/FbCSF0Pj/Capture.png" alt="Nexus-FCA Demo Screenshot" width="700"/>
-</div>
+Disable preflight if needed:
+```js
+await login({ appState }, { disablePreflight: true });
+```
 
 ---
-
-## ✨ Key Features
-- **🛡️ Ultra-Low Facebook Account Ban Rate (95%+ Protection)**
-- **🔐 Smart Human-Like Behavior Patterns**
-- **� Real-time Account Lock/Ban/Checkpoint Prevention**
-- **🌐 Advanced Safe MQTT Auto-Reconnect**
-- **📊 Intelligent Safety-Focused Performance Optimization**
-- **�️ Proactive Account Health Monitoring & Alerts**
-- **🔄 Safe Automatic Token Refresh & Session Management**
-- **🌍 Region Protection & Safe Connection Optimization**
-- **📈 Professional Safety Analytics & Monitoring**
-- **💻 Full TypeScript Support & Modern APIs**
-- **🔧 Discord.js-style Objects & Event System**
-- **📝 Comprehensive Safety Documentation & Migration Guides**
+## 🛰️ 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
 
 ---
-
-## 📦 Installation
+## 📦 Example Echo Test
+`examples/echo-test.js` (already included):
 ```bash
-npm install nexus-fca
+node examples/echo-test.js
 ```
+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`
 
-## 🛠️ Quick Start Example
+Persistent device toggle:
 ```js
-const login = require("nexus-fca");
-
-login({ appState: require("./appstate.json") }, (err, api) => {
-    if (err) return console.error("Login error:", err);
-    api.listenMqtt((err, event) => {
-        if (err) return console.error("Listen error:", err);
-        if (event.body && event.threadID) {
-            api.sendMessage("Echo: " + event.body, event.threadID);
-        }
-    });
-});
+const { IntegratedNexusLoginSystem } = require('nexus-fca');
+new IntegratedNexusLoginSystem({ persistentDevice: true });
 ```
 
 ---
+## 🐐 Using Nexus-FCA with GoatBot V2
+Nexus-FCA can act as a drop‑in enhancement for the legacy fb-chat-api layer inside GoatBot V2.
 
-## 🧑‍💻 Ultra-Safe Login Example (Recommended for Maximum Protection)
+### Option 1: Non‑invasive (generate fresh appstate)
+1. In a separate script, run Nexus-FCA credential login (with 2FA if needed):
 ```js
-const { NexusClient } = require('nexus-fca');
-
-const client = new NexusClient({
-    prefix: '!',
-    ultraLowBanMode: true, // NEW: Ultra-low ban rate protection
-    safeDelays: true, // Human-like timing patterns
-    performanceOptimization: true,
-    cachingEnabled: true,
-    autoReconnect: true,
-    logLevel: 'info'
-});
-
-client.on('ready', (api, userID) => {
-    console.log(`🛡️ Login successful with ultra-low ban rate protection!`);
-    console.log(`👤 User ID: ${userID}`);
-    console.log(`⚡ Smart safety system: ACTIVE`);
-    console.log(`�️ Account protection level: MAXIMUM`);
-});
-
-client.on('message', async (message) => {
-    if (message.body === 'ping') await message.reply('🏓 Pong!');
-});
-
-// Enhanced safety event listeners
-client.on('accountLocked', (details) => {
-    console.log('🚨 ACCOUNT LOCKED - Emergency shutdown initiated for safety');
-    process.exit(1);
-});
-
-client.on('checkpointRequired', (details) => {
-    console.log('⚠️ CHECKPOINT REQUIRED - Manual verification needed');
-});
-
-client.on('riskLevelHigh', (details) => {
-    console.log('� HIGH RISK DETECTED - Automatically applying safety measures');
-});
-
-client.login({ appState: require('./appstate.json') });
+const login = require('nexus-fca');
+(async () => {
+  const api = await login({ email: process.env.FB_EMAIL, password: process.env.FB_PASS, twofactor: process.env.FB_2FA });
+  const appState = api.getAppState();
+  require('fs').writeFileSync('./appstate.json', JSON.stringify(appState, null, 2));
+  console.log('Saved appstate.json');
+})();
 ```
+2. Configure GoatBot to use that `appstate.json` (no credential scraping needed).
+3. Repeat only when session truly expires (persistent device reduces frequency).
 
----
-
-## 🏗️ Advanced Safety Architecture (Ultra-Low Ban Rate System)
-- **lib/safety/FacebookSafety.js**: Advanced account protection with 95%+ ban rate reduction
-- **lib/safety/SmartSafetyLimiter.js**: Intelligent human-behavior simulation system
-- **lib/performance/PerformanceOptimizer.js**: Safety-focused optimization with human-like patterns
-- **lib/error/ErrorHandler.js**: Sophisticated error recovery with account protection priority
-- **lib/mqtt/AdvancedMqttManager.js**: Enhanced MQTT with safe reconnection patterns
-- **lib/compatibility/NexusClient.js**: Modern API with ultra-safety-first design
-- **lib/message/Message.js, Thread.js, User.js**: Discord.js-style objects with safety validation
-- **lib/database/EnhancedDatabase.js**: High-speed storage optimized for minimal detection risk
+### Option 2: Replace internal fb-chat-api
+GoatBot has a local `fb-chat-api` folder. To leverage Nexus-FCA improvements globally:
+1. Install Nexus-FCA inside GoatBot project:
+```bash
+npm install nexus-fca
+```
+2. Rename GoatBot’s original folder for backup:
+```bash
+mv fb-chat-api fb-chat-api.orig   # (Windows: rename manually)
+```
+3. Create a shim folder `fb-chat-api/index.js` with:
+```js
+module.exports = require('nexus-fca');
+```
+4. Start GoatBot normally. All calls (`login`, `api.listen`, send methods) now use Nexus-FCA (Promise supported).
 
----
+### Option 3: Direct require patch
+Search GoatBot source for `require("fb-chat-api")` and change to `require("nexus-fca")`.
 
-## 🔄 Easy Integration
+### Promise usage inside GoatBot scripts
+Replace:
+```js
+fbapi(loginData, (err, api) => { ... });
+```
+with:
+```js
+const login = require('nexus-fca');
+const api = await login(loginData); // supports { appState } or { email, password, twofactor }
+```
 
-Nexus-FCA is designed as a modern, standalone Facebook Chat API solution:
+### Recommended settings
+- Keep `persistent-device.json` at project root so repeated restarts reuse the same fingerprint.
+- If GoatBot already performs its own “live cookie check” loops, you can set `{ disablePreflight: true }` to avoid duplicate validation.
+- Handle reconnect events: listen for `error` and `listen` callbacks just like original; classified errors now have `error.type` (`login_redirect`, etc.).
 
-- **Complete API**: All essential Facebook Messenger automation features
-- **TypeScript Ready**: Full type definitions and IntelliSense support  
-- **Zero Configuration**: Works out of the box with sensible defaults
-- **Production Ready**: Built for scale with advanced safety and performance optimizations
+### Minimal integration example
+```js
+const login = require('nexus-fca');
+(async () => {
+  const api = await login({ appState: require('./appstate.json') });
+  api.listen(async (err, event) => {
+    if (err) return console.error('[Nexus-FCA]', err);
+    if (event.body === '!ping') api.sendMessage('pong', event.threadID);
+  });
+})();
+```
 
 ---
-
-## 📝 Advanced Safety Features (Ultra-Low Ban Rate)
-- **🛡️ Smart Safety Limiter**: Intelligent human behavior simulation to minimize detection risk
-- **⚡ Risk Assessment System**: Real-time analysis of account activity patterns for safety optimization
-- **🔄 Human-Like Delays**: Sophisticated timing patterns that mimic natural user behavior
-- **🚨 Proactive Safety Alerts**: Early warning system for potential account risks
-- **🔐 Advanced Session Management**: Secure token handling with automatic safety validation
-- **🌍 Region Protection**: Advanced techniques to safely bypass restrictions and improve connectivity
-- **📊 Safety Analytics**: Real-time monitoring focused on minimizing ban/lock/checkpoint rates
-- **🔧 Intelligent Error Recovery**: Smart error handling that prioritizes account safety over speed
+## 📚 Documentation
+- Full API reference: `DOCS.md`
+- Per-feature guides: `/docs/*.md`
+- Safety: `docs/account-safety.md`
+- Examples: `/examples`
 
 ---
+## 🔁 Updating from 2.0.x → 2.1.0
+| Change | Action |
+|--------|--------|
+| Preflight errors | Noise reduced automatically |
+| Device rotation | Now persistent by default | 
+| parseAndCheckLogin | Handles 3xx & HTML login responses |
+| Session validation | New `validateSession` helper |
 
-## 📚 Documentation & Guides
-- **Full API Reference**: See [`DOCS.md`](./DOCS.md)
-- **Safety Guide**: See [`docs/account-safety.md`](./docs/account-safety.md) for best practices
-- **TypeScript Usage**: Complete types in [`index.d.ts`](./index.d.ts)
-- **Performance & Error Handling**: See advanced sections in docs
+No breaking API changes.
 
 ---
-
-## 🛡️ Account Safety & Troubleshooting (Ultra-Low Ban Rate Protection)
-- **Account Locked/Suspended**: Advanced safety system will detect and immediately stop operations, preventing further issues
-- **Checkpoint Required**: Manual verification needed - check Facebook for security prompts while bot automatically pauses
-- **Session Expired**: Update your `appstate.json` with fresh cookies from browser using recommended browser extensions
-- **MQTT Connection Issues**: Intelligent auto-reconnect system handles temporary disconnections with human-like patterns
-- **High Risk Level Detected**: System automatically applies enhanced safety measures and increases delays between actions
-- **Performance Issues**: Smart safety delays ensure optimal balance between speed and account protection
-- **Memory Issues**: Automatic cleanup and optimization prevent resource leaks while maintaining safety
-- **Network Issues**: Enhanced retry logic with safety-first approach handles connectivity problems intelligently
+## ⚠️ Disclaimer
+This project is not affiliated with Facebook. Use responsibly. You are solely responsible for compliance with platform terms and local laws.
 
 ---
-
-## 🆕 Major Update: Nexus Login System (2.0.1)
-
-### 🚀 What’s New?
-- **Nexus Login System**: Fully integrated, advanced, and safe Facebook login system under `/nexloginsystem`.
-- **ID/Password/2FA Login**: Now you can login directly with your Facebook username, password, and 2FA secret key (Google Authenticator supported).
-- **Automatic Appstate Generation**: No need to manually extract cookies—just provide credentials and get a fresh, safe appstate automatically.
-- **Seamless Bot Start**: After login, your bot starts instantly with the generated appstate—no manual steps needed.
-- **Ultra-Safe Device Simulation**: Human-like Android device/user-agent simulation for maximum account safety.
-- **Auto-Backup & Validation**: Appstate is auto-backed up and validated for every login.
-- **Advanced Error Handling**: Smart retry, 2FA fallback, and detailed error messages.
-- **Full Documentation**: See `/nexloginsystem/README.md` for usage, API, and safety tips.
-- **Test File Included**: Test your login system easily with `/nexloginsystem/test-login.js`.
-
-### ⚡ Example Usage
-```js
-const { nexusLogin } = require('./nexloginsystem');
-const result = await nexusLogin({
-    username: 'your_email@gmail.com',
-    password: 'your_password',
-    twofactor: 'YOUR_2FA_SECRET_KEY'
-});
-if (result.success) {
-    // Bot is ready! API available immediately
-    result.api.sendMessage('Hello World!', result.api.getCurrentUserID());
-}
-```
-
-### 📚 Learn More
-- See `/nexloginsystem/README.md` for full API, advanced usage, and safety best practices.
-- For 2FA setup, see the guide in the login system docs.
+## 🤝 Contribute
+PRs for safety, stability, perf, and updated GraphQL doc_ids welcome.
 
 ---
+## 📜 License
+MIT © 2025 Nexus-FCA Contributors

package/index.js

@@ -380,37 +380,52 @@ class IntegratedNexusLoginSystem {
             safeMode: options.safeMode !== false,
             maxRetries: options.maxRetries || 3,
             retryDelay: options.retryDelay || 5000,
+            // New: persistentDevice disables random device rotation
+            persistentDevice: options.persistentDevice !== false,
+            persistentDeviceFile: options.persistentDeviceFile || path.join(process.cwd(), 'persistent-device.json'),
             ...options
         };
 
         this.deviceCache = new Map();
         this.loginAttempts = 0;
         this.lastLoginTime = 0;
+        // New: load previously persisted device if any
+        this.fixedDeviceProfile = this.loadPersistentDevice();
         
         this.ensureDirectories();
         this.logger('Login system ready', '🚀');
     }
 
-    logger(message, emoji = '📝') {
-        const timestamp = new Date().toLocaleString();
-        console.log(`${emoji} [${timestamp}] ${message}`);
+    loadPersistentDevice() {
+        try {
+            if (!this.options.persistentDevice) return null;
+            if (fs.existsSync(this.options.persistentDeviceFile)) {
+                const raw = JSON.parse(fs.readFileSync(this.options.persistentDeviceFile, 'utf8'));
+                if (raw && raw.device && raw.deviceId && raw.familyDeviceId && raw.userAgent) {
+                    this.logger('Loaded persistent device profile', '📱');
+                    return raw;
+                }
+            }
+        } catch (e) {
+            this.logger('Failed to load persistent device: ' + e.message, '⚠️');
+        }
+        return null;
     }
 
-    ensureDirectories() {
-        const dirs = [
-            path.dirname(this.options.appstatePath),
-            path.dirname(this.options.credentialsPath),
-            this.options.backupPath
-        ];
-        
-        dirs.forEach(dir => {
-            if (!fs.existsSync(dir)) {
-                fs.mkdirSync(dir, { recursive: true });
-            }
-        });
+    savePersistentDevice(profile) {
+        if (!this.options.persistentDevice) return;
+        try {
+            fs.writeFileSync(this.options.persistentDeviceFile, JSON.stringify(profile, null, 2));
+            this.logger('Saved persistent device profile', '💾');
+        } catch (e) {
+            this.logger('Failed to save persistent device: ' + e.message, '⚠️');
+        }
     }
 
     getRandomDevice() {
+        if (this.fixedDeviceProfile) {
+            return this.fixedDeviceProfile; // reuse device
+        }
         const devices = [
             { model: "Pixel 6", build: "SP2A.220505.002", sdk: "30", release: "11" },
             { model: "Pixel 5", build: "RQ3A.210805.001.A1", sdk: "30", release: "11" },
@@ -420,17 +435,21 @@ class IntegratedNexusLoginSystem {
             { model: "Pixel 7", build: "TD1A.220804.031", sdk: "33", release: "13" },
             { model: "Samsung Galaxy S22", build: "S901USQU2AVB3", sdk: "32", release: "12" }
         ];
-        
         const device = devices[Math.floor(Math.random() * devices.length)];
         const deviceId = this.generateConsistentDeviceId(device);
-        
-        return {
+        const profile = {
             userAgent: `Dalvik/2.1.0 (Linux; U; Android ${device.release}; ${device.model} Build/${device.build})`,
             device,
             deviceId,
             familyDeviceId: uuidv4(),
             androidId: this.generateAndroidId()
         };
+        // Persist first generated device if persistence enabled
+        if (this.options.persistentDevice && !this.fixedDeviceProfile) {
+            this.fixedDeviceProfile = profile;
+            this.savePersistentDevice(profile);
+        }
+        return profile;
     }
 
     generateConsistentDeviceId(device) {
@@ -640,9 +659,11 @@ class IntegratedNexusLoginSystem {
                                 device_info: {
                                     model: androidDevice.device.model,
                                     user_agent: androidDevice.userAgent,
-                                    device_id: androidDevice.deviceId
+                                    device_id: androidDevice.deviceId,
+                                    family_device_id: androidDevice.familyDeviceId
                                 },
-                                generated_at: new Date().toISOString()
+                                generated_at: new Date().toISOString(),
+                                persistent_device: !!this.options.persistentDevice
                             };
 
                             this.saveAppstate(appstate, result);
@@ -972,6 +993,17 @@ async function login(loginData, options = {}, callback) {
     callback = options;
     options = {};
   }
+  // Add promise wrapper when no callback supplied
+  let usePromise = false;
+  if (typeof callback !== 'function') {
+    usePromise = true;
+  }
+  const promise = usePromise ? new Promise((resolve, reject) => {
+    callback = function (err, api) {
+      if (err) return reject(err);
+      resolve(api);
+    };
+  }) : null;
   
   // Professional logging
   const mainLogger = {
@@ -1002,8 +1034,8 @@ async function login(loginData, options = {}, callback) {
       
       if (!result.success || !result.appstate) {
         mainLogger.error('❌ Authentication failed', result.message);
-        if (callback) return callback(new Error(result.message || 'Login failed'));
-        throw new Error(result.message || 'Login failed');
+        if (callback) callback(new Error(result.message || 'Login failed'));
+        return usePromise ? promise : undefined;
       }
       
       mainLogger.info('✅ Session generated successfully');
@@ -1027,7 +1059,7 @@ async function login(loginData, options = {}, callback) {
         ...options
       };
       
-      return loginHelper(
+      loginHelper(
         result.appstate,  // Use generated appstate
         null,             // No email for old system
         null,             // No password for old system
@@ -1035,23 +1067,24 @@ async function login(loginData, options = {}, callback) {
         callback,
         null
       );
+      return usePromise ? promise : undefined;
       
     } catch (error) {
       mainLogger.error('💥 Login error', error.message);
-      if (callback) return callback(error);
-      throw error;
+      if (callback) callback(error);
+      return usePromise ? promise : undefined;
     }
   } else {
     // Appstate-only authentication (direct session authentication)
     if (!loginData.appState && !loginData.appstate) {
       const error = new Error('Username and password are required for login, or provide appState for session authentication.');
       mainLogger.error('❌ No credentials provided', 'Either provide ID/password or appstate');
-      if (callback) return callback(error);
-      throw error;
+      if (callback) callback(error);
+      return usePromise ? promise : undefined;
     }
     
     // Direct session authentication using appstate
-    mainLogger.info('� Starting session authentication');
+    mainLogger.info('🔄 Starting session authentication');
     
     const globalOptions = {
       selfListen: false,
@@ -1070,7 +1103,7 @@ async function login(loginData, options = {}, callback) {
       ...options
     };
     
-    return loginHelper(
+    loginHelper(
       loginData.appState || loginData.appstate,
       null, // No email for appstate login
       null, // No password for appstate login
@@ -1078,6 +1111,7 @@ async function login(loginData, options = {}, callback) {
       callback,
       null
     );
+    return usePromise ? promise : undefined;
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexus-fca",
-  "version": "2.0.7",
+  "version": "2.1.0",
   "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": {

package/src/listenMqtt.js

@@ -128,6 +128,23 @@ function buildStream(options, WebSocket, Proxy) {
   return Stream;
 }
 function listenMqtt(defaultFuncs, api, ctx, globalCallback) {
+  // Improved preflight with option to disable
+  if (!ctx.globalOptions.disablePreflight) {
+    (async () => {
+      try {
+        await utils.validateSession(ctx, defaultFuncs, { retries: 2, delayMs: 1000 });
+      } catch (e) {
+        // Suppress first failure; only emit if still bad after short grace period
+        setTimeout(() => {
+          utils.validateSession(ctx, defaultFuncs, { retries: 0 }).catch(err2 => {
+            log.error("listenMqtt", "Session invalid after retry: Not logged in.");
+            ctx.loggedIn = false;
+            globalCallback({ type: "not_logged_in", error: "Session invalid (post-retry)." });
+          });
+        }, 2000);
+      }
+    })();
+  }
   const chatOn = ctx.globalOptions.online;
   const foreground = false;
   const sessionID = Math.floor(Math.random() * Number.MAX_SAFE_INTEGER) + 1;
@@ -218,6 +235,12 @@ function listenMqtt(defaultFuncs, api, ctx, globalCallback) {
   mqttClient.on('error', function (err) {
     log.error("listenMqtt", err);
     mqttClient.end();
+    // classify redirect/login errors surfaced through upstream logic
+    const errMsg = (err && (err.error || err.message || "")).toString();
+    if (/not logged in|login_redirect|html_login_page/i.test(errMsg)) {
+      ctx.loggedIn = false;
+      return globalCallback({ type: "not_logged_in", error: errMsg });
+    }
     if (ctx.globalOptions.autoReconnect) {
       listenMqtt(defaultFuncs, api, ctx, globalCallback);
     } else {

package/utils.js

@@ -989,6 +989,7 @@ function parseAndCheckLogin(ctx, defaultFuncs, retryCount = 0, sourceCall) {
     return function (data) {
         return tryPromise(function () {
             log.verbose("parseAndCheckLogin", data.body);
+            // --- Handle HTTP 5xx with bounded retry (existing logic) ---
             if (data.statusCode >= 500 && data.statusCode < 600) {
                 if (retryCount >= 5) {
                     throw {
@@ -1016,6 +1017,34 @@ function parseAndCheckLogin(ctx, defaultFuncs, retryCount = 0, sourceCall) {
                     )
                     .then(parseAndCheckLogin(ctx, defaultFuncs, retryCount, sourceCall));
             }
+            // --- New: Explicit 3xx redirect handling (302 login checkpoint, etc.) ---
+            if (data.statusCode >= 300 && data.statusCode < 400) {
+                const location = data.headers && (data.headers.location || data.headers.Location);
+                if (!location) {
+                    throw {
+                        message: `Redirect (${data.statusCode}) without location header.`,
+                        statusCode: data.statusCode,
+                        res: data.body,
+                        error: "Redirect without location.",
+                        sourceCall
+                    };
+                }
+                // Detect checkpoint/login redirects explicitly
+                if (/checkpoint|login|recover/i.test(location)) {
+                    throw {
+                        message: `Redirected to login/checkpoint: ${location}`,
+                        statusCode: data.statusCode,
+                        location,
+                        error: "Not logged in.",
+                        type: "login_redirect",
+                        res: data.body,
+                        sourceCall
+                    };
+                }
+                log.warn("parseAndCheckLogin", `Following redirect -> ${location}`);
+                return defaultFuncs.get(location, ctx.jar)
+                    .then(parseAndCheckLogin(ctx, defaultFuncs, retryCount, sourceCall));
+            }
             if (data.statusCode !== 200) {
                 throw {
                     message: `parseAndCheckLogin got status code: ${data.statusCode}.`,
@@ -1026,23 +1055,60 @@ function parseAndCheckLogin(ctx, defaultFuncs, retryCount = 0, sourceCall) {
                 };
             }
             let res;
+            let bodyText = data.body || "";
+            // --- New: Detect full HTML (often login page) before JSON parse ---
+            const looksLikeHTML = /<html[\s\S]*<\/html>/i.test(bodyText);
+            if (looksLikeHTML && /login|checkpoint|password|m_faceweb|m\.facebook\.com\/login/i.test(bodyText)) {
+                throw {
+                    message: "Received HTML login/checkpoint page instead of JSON (session likely invalid).",
+                    statusCode: data.statusCode,
+                    res: bodyText.slice(0, 5000),
+                    error: "Not logged in.",
+                    type: "html_login_page",
+                    sourceCall
+                };
+            }
             try {
-                res = JSON.parse(makeParsable(data.body));
+                res = JSON.parse(makeParsable(bodyText));
             } catch (e) {
-                log.error("JSON parsing failed:", data.body);
+                // Additional heuristic: if body has FB login form markers
+                if (/login_form|checkpointSubmitButton|memorialized/i.test(bodyText)) {
+                    throw {
+                        message: "Facebook returned login/checkpoint HTML instead of JSON.",
+                        detail: e.message,
+                        res: bodyText.slice(0, 5000),
+                        error: "Not logged in.",
+                        type: "html_login_page_parse_fail",
+                        sourceCall
+                    };
+                }
+                log.error("JSON parsing failed:", bodyText);
                 throw {
                     message: "Failed to parse JSON response.",
                     detail: e.message,
-                    res: data.body,
+                    res: bodyText.slice(0, 5000),
                     error: "JSON.parse error.",
                     sourceCall
                 };
             }
             if (res.redirect && data.request.method === "GET") {
+                // New: classify redirect target
+                if (/checkpoint|login/i.test(res.redirect)) {
+                    throw {
+                        message: `Redirected to login/checkpoint (JSON redirect): ${res.redirect}`,
+                        statusCode: data.statusCode,
+                        location: res.redirect,
+                        error: "Not logged in.",
+                        type: "login_redirect",
+                        res,
+                        sourceCall
+                    };
+                }
                 return defaultFuncs
                     .get(res.redirect, ctx.jar)
                     .then(parseAndCheckLogin(ctx, defaultFuncs, undefined, sourceCall));
             }
+            // --- Existing cookie & token handling logic (unchanged) ---
             if (
                 res.jsmods?.require &&
                 Array.isArray(res.jsmods.require[0]) &&
@@ -1062,7 +1128,9 @@ function parseAndCheckLogin(ctx, defaultFuncs, retryCount = 0, sourceCall) {
                     }
                 }
             }
-            if (res.error === 1357001) {
+            // --- New: Detect common not-logged-in payload patterns ---
+            if (res.error === 1357001 || res.error === 1357004 || res.errorSummary === "login required") {
+                // 1357001 existing logic below triggers auto_login; keep classification
                 if (!ctx.auto_login) {
                     ctx.auto_login = true;
                     auto_login(success => {
@@ -1484,12 +1552,80 @@ const rateLimiter = {
   }
 };
 
-module.exports.rateLimiter = rateLimiter;
-module.exports.smartSafetyLimiter = smartSafetyLimiter;
-module.exports.safeMode = safeMode;
-module.exports.ultraSafeMode = ultraSafeMode;
-module.exports.isUserAllowed = isUserAllowed;
+// Add robust session validation utility used by listenMqtt
+async function validateSession(ctx, defaultFuncs, opts = {}) {
+    const { retries = 0, delayMs = 750 } = opts || {};
+    if (!ctx || !ctx.jar) {
+        throw new CustomError({ message: 'No context/jar provided', type: 'not_logged_in' });
+    }
+    const cookies = ctx.jar.getCookies('https://www.facebook.com');
+    const hasUser = cookies.some(c => (c.key || c.name) === 'c_user');
+    if (!hasUser) {
+        throw new CustomError({ message: 'Not logged in (missing c_user cookie)', type: 'not_logged_in' });
+    }
+
+    const endpoints = [
+        'https://www.facebook.com/ajax/mercury/threadlist_info.php?client=mercury',
+        'https://m.facebook.com/me'
+    ];
+
+    function isHtmlLoginPage(body) {
+        if (!body || typeof body !== 'string') return false;
+        if (body.length < 40) return false;
+        const lowered = body.toLowerCase();
+        return (
+            (lowered.includes('login') && lowered.includes('password')) ||
+            lowered.includes('m_login_email') ||
+            lowered.includes('/login/device-based')
+        );
+    }
+
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        let allPassed = true;
+        for (const url of endpoints) {
+            try {
+                // Prefer provided defaultFuncs.get if available (applies defaults & fb_dtsg)
+                const res = defaultFuncs && defaultFuncs.get
+                    ? await defaultFuncs.get(url, ctx.jar, {})
+                    : await get(url, ctx.jar, null, ctx.globalOptions, ctx);
+
+                const status = res && res.statusCode;
+                const body = res && res.body ? res.body.toString() : '';
+
+                if (status >= 300 && status < 400) {
+                    throw new CustomError({ message: 'Login redirect detected', type: 'login_redirect', statusCode: status });
+                }
+                if (status === 0 || status === undefined) {
+                    throw new CustomError({ message: 'No status code (network?)', type: 'network_error' });
+                }
+                if (status === 401 || status === 403) {
+                    throw new CustomError({ message: 'Unauthorized / forbidden', type: 'not_logged_in', statusCode: status });
+                }
+                if (isHtmlLoginPage(body)) {
+                    throw new CustomError({ message: 'HTML login page served', type: 'html_login_page' });
+                }
+                // Basic heuristic: body containing checkpoint indicators
+                if (/checkpoint|review recent login/i.test(body)) {
+                    throw new CustomError({ message: 'Checkpoint required', type: 'checkpoint' });
+                }
+            } catch (err) {
+                allPassed = false;
+                if (attempt >= retries) {
+                    // Re-throw final classified error (ensure type present)
+                    if (err instanceof CustomError) throw err;
+                    throw new CustomError({ message: err.message || 'Session invalid', type: err.type || 'not_logged_in', original: err });
+                }
+                break; // break inner loop to retry endpoints
+            }
+        }
+        if (allPassed) return true;
+        if (attempt < retries) await delay(delayMs);
+    }
+    // Fallback (should not reach)
+    throw new CustomError({ message: 'Unknown session validation failure', type: 'not_logged_in' });
+}
 
+// Preserve earlier named exports while adding validateSession
 module.exports = {
     CustomError,
     cleanHTML,
@@ -1537,5 +1673,12 @@ module.exports = {
     setProxy,
     checkLiveCookie,
     getAccessFromBusiness,
-    getFroms
+    getFroms,
+    validateSession,
+    // Safety & rate limiting exports
+    rateLimiter,
+    smartSafetyLimiter,
+    safeMode,
+    ultraSafeMode,
+    isUserAllowed
 };