nexus-fca 2.1.8 → 3.0.0

package/CHANGELOG.md

@@ -1,202 +1,21 @@
 # Changelog
+## [3.0.0] - 2025-09-11 - Advanced Core Release
 
-## [2.1.8] - 2025-09-02 - Extended Safe Refresh Window
-### Changed
-- Safe session refresh interval widened to 3–5h (adaptive: 1–1.5h when risk=high) to reduce token churn and mitigate premature cookie expiry heuristics.
-
-### Rationale
-- Frequent refreshes can accelerate cookie rotation patterns → earlier invalidation.
-- Longer, randomized window maintains stealth while heartbeats, ghost detection, and adaptive reconnect still ensure liveness.
-
-### Notes
-- Lightweight mid‑session fb_dtsg poke (≈6h ±40m) retained; heavy refresh cadence now sparser.
+### Overview
+Version 3.0.0 represents a pivotal milestone in the evolution of the Nexus-fCA platform, transitioning from the iterative stabilization efforts of the 2.1.x series to a unified, production-ready foundation. This release is the culmination of extensive engineering, rigorous validation, and a commitment to delivering enterprise-grade reliability. The legacy diagnostics harness has been formally retired, replaced by a standardized internal instrumentation framework that streamlines monitoring, troubleshooting, and ongoing maintenance. These enhancements collectively reinforce the platform’s robustness, scalability, and operational transparency.
 
----
-
-## [2.1.7] - 2025-09-01 - Session Stability Patch
 ### Added
-- User-Agent continuity (anchored single UA for entire session via safety module; eliminates mid-session UA drift increasing 20–22h expiry risk).
-- Exposed `setFixedUserAgent()` in `FacebookSafety` to allow explicit anchoring from credential phase.
-- Mid-session lightweight token poke (6h ±40m) to keep session warm without full heavy refresh cycle.
+- **Delivery Receipt Health Metrics:** Introduced a comprehensive suite of metrics for delivery receipts, encompassing attempt counts, success rates, failure rates, timeout tracking, and adaptive disablement flags. These metrics provide granular visibility into delivery performance and facilitate proactive issue resolution.
+- **Advanced Timeout Suppression Logic:** Implemented sophisticated suppression mechanisms for repeated delivery timeouts. This ensures consistent reply performance, mitigates the risk of systemic degradation, and enhances overall service reliability.
+- **Internal Instrumentation Standardization:** All diagnostic and monitoring capabilities have been consolidated under a unified instrumentation framework, simplifying maintenance and enabling more effective root cause analysis.
 
 ### Changed
-- Removed legacy mobile agent override fallback in `loginHelper` that caused mixed UA fingerprints.
-- All safe requests now inherit continuity-aware UA through `applySafeRequestOptions`.
-
-### Improved
-- Extended resilience against 20–22h cookie invalidation observed with prior dual-phase UA pattern.
-- Reduced unnecessary full refresh churn while preserving stealth (`safeRefresh` + light poke coexist).
-
----
-
-## [2.1.6] - 2025-08-31 - Memory Guard & Queue Sweeping
-### Added
-- Central lightweight memory guard sweeps: group queue pruning (idle >30m, overflow trim) and pendingEdits TTL sweeper (every 4m).
-- Health metrics extended: memoryGuardRuns, memoryGuardActions, groupQueueDroppedMessages, groupQueueExpiredQueues, groupQueuePrunedThreads, pendingEditSweeps.
-- API: `api.getMemoryMetrics()` returns focused memory-related counters.
-- Typings updated (`EditOptions`, new API methods) in `index.d.ts`.
-
-### Improved
-- Group queue now tracks `lastActive` and enforces idle purge + overflow protection with metrics.
-- Pending edits TTL enforcement separated from resend watchdog for deterministic expiry.
-
-### Notes
-- All guards are low-frequency, low-impact; no change to delivery reliability or safety – only prevention of unbounded growth.
-
----
-
-## [2.1.5] - 2025-08-28 - PendingEdits & ACK Metrics
-### Added
-- PendingEdits buffer with cap (default 200) + TTL (5m) + resend attempts (2) + ACK timeout (12s).
-- Automatic edit resend watchdog with safe limits and metrics (editResends, editFailed, pendingEditsDropped, pendingEditsExpired).
-- API: `api.setEditOptions({ maxPendingEdits, editTTLms, ackTimeoutMs, maxResendAttempts })`.
-- Edit ACK integration: pending edit removed on ACK receipt.
-- Health metrics: p95AckLatencyMs, editResends, editFailed.
-
-### Improved
-- Safer edit pipeline: prevents uncontrolled retries, bounds memory, tracks expirations.
-- Enhanced HealthMetrics with percentile latency sample retention (50-sample window).
+- **Documentation and Package Description:** The package description and README have undergone a comprehensive revision to align with professional standards and accurately reflect the platform’s positioning, capabilities, and intended use cases.
+- **Semantic Versioning:** The major version increment to 3.0.0 signifies the platform’s maturity, stability, and readiness for mission-critical deployments. Importantly, there are no breaking changes to public APIs compared to the 2.1.x series, ensuring continuity for existing integrations.
 
 ### Notes
-- Durable outbound queue & metrics exporter planned next.
-
----
-
-## [2.1.4] - Adaptive Backoff & Core Metrics
-### Added
-- Adaptive reconnect backoff with jitter (caps at 5 minutes) for safer, stealthier recovery loops.
-- Lazy preflight session validation (skips heavy validation if a recent successful connect occurred) toggle via `api.enableLazyPreflight()`.
-- Health metrics collector (uptime, idle time, reconnect counts, failures, message/ack counters, synthetic keepalives) accessible with `api.getHealthMetrics()` and included in `api.healthCheck()`.
-- Randomized synthetic keepalive interval (55-75s) to reduce detection patterns.
-- Backoff configuration hook: `api.setBackoffOptions()`.
-
-### Improved
-- Reduced noisy session validation on every `listenMqtt` invocation unless needed.
-- More structured error classification feeding metrics (`session_invalid`, `timeout_no_t_ms`, `mqtt_error`, `message_parse`, `not_logged_in`).
-
-### Planned (Next)
-- ACK tracking refinement & resend logic.
-- Pending edits buffer with TTL and cap.
-- Durable outbound queue & health exporter.
-
----
-
-## [2.1.2] - CONTINUOUS IDLE RECOVERY
-### Added
-- Soft-stale probing at 2 minutes idle (ping + conditional forced reconnect if no events within 5-8s)
-- Wrapper around `listenMqtt` to automatically feed events into safety heartbeat (`recordEvent`) for precise idle detection
-- Ghost connection detection (10m silent but socket connected triggers forced reconnect after probe)
-- Periodic connection recycle every ~6h ±30m to prevent long-lived silent degradation
-- Force reconnect API: `globalSafety.forceReconnect(tag)`
-
-### Improved
-- Faster recovery from silent idle states (previously required >5 min or external trigger)
-- Reduced chance of appearing online but unresponsive after short inactivity
-- Added keepalive foreground_state publishes each heartbeat
-
----
-
-## [2.1.1] - 2025-08-27 - ADVANCED SESSION STABILITY
-### 🛠 Added
-- Adaptive safe session refresh interval (dynamic based on risk level)
-- Heartbeat + watchdog timers to detect stale MQTT connections early
-- Progressive backoff with jitter for MQTT reconnect attempts
-- Layered post-refresh health checks (1s / 10s / 30s) to catch silent drops
-- Abortable refresh with timeout safeguard (25s) to prevent hangs
-- Automatic reconnection trigger if no events within thresholds (2m soft, 15m hard)
-- `destroy()` method to cleanup timers/listeners (prevents memory leaks)
-
-### 🔄 Changed
-- Safe refresh now records in‑flight ID and supersedes outdated checks
-- Reconnect logic centralized in `_reconnectMqttWithBackoff`
-
-### ✅ Improved
-- Stability after long runtimes / multiple token refresh cycles
-- Reduced risk of listener not resuming after refresh
-
----
-
-## [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`
-- **📦 NPM COMPATIBLE**: Works perfectly when installed via `npm install nexus-fca` - no external folder dependencies
-- **⚡ ZERO CONFIG**: Everything works out of the box - no separate folder setup required
-- **🔄 SEAMLESS MIGRATION**: Existing code continues to work, new code benefits from integration
-
-### Added
-- 🎯 **Direct exports**: `nexusLogin` and `IntegratedNexusLoginSystem` available directly from main package
-- 🧪 **Updated test files**: All test scripts now use integrated system (`require('nexus-fca')` instead of `./nexloginsystem`)
-- 📖 **New documentation**: `npm-integration-guide.md` with complete NPM usage guide
-- 🛠️ **NPM scripts**: Added `test:login`, `test:simple`, `test:2fa`, `test:all` for easy testing
-- 📦 **Enhanced package.json**: Updated keywords, description, and version for NPM integration
-
-### Changed
-- 🏗️ **Architecture**: Moved entire Nexus Login System from external folder into main index.js (lines 372-860+)
-- 📝 **Documentation**: Updated README.md to reflect NPM installation and integrated usage
-- 🔧 **Test files**: Fixed all test imports to use main package instead of external folder
-- 📦 **Package info**: Updated to v2.0.5 with new description highlighting NPM integration
-
-### Fixed
-- ❌ **NPM module errors**: Eliminated "Cannot find module './nexloginsystem'" when using as npm package
-- 🔗 **Import paths**: All test files and examples now use correct import paths for npm usage
-- 🎯 **Distribution**: Package now works identically whether used locally or installed via npm
-
-## [2.0.4] - 2025-07-29
-### Fixed
-- 🐛 **Missing nexloginsystem folder**: Added `nexloginsystem/` to npm package files array to fix "Cannot find module './nexloginsystem'" error
-- 🔄 **Legacy login fallback**: Added automatic fallback to appstate-only login when Nexus Login System is not available
-- 🛡️ **Backward compatibility**: Enhanced compatibility for users using nexus-fca as npm dependency without full login system
-
-### Changed
-- Updated package.json to include nexloginsystem folder in published package
-- Enhanced error handling with graceful fallback mechanisms
-
-## [2.0.1] - 2025-07-28
-### Added
-- 🚀 **Nexus Login System**: Advanced, safe, and automatic Facebook login system added under `/nexloginsystem`.
-- 🔐 **Appstate auto-generation**: Login with username/password/2FA, auto-save appstate, and seamless bot start.
-- 🛡️ **Maximum safety**: Human-like device simulation, TOTP/2FA support, and advanced error handling.
-- 📦 **Auto-backup & validation**: Appstate backup, validation, and lifecycle management.
-- 📚 **Full documentation**: Usage, API, and safety docs in `/nexloginsystem/README.md`.
-
-### Changed
-- Updated main `README.md` with Nexus Login System quick start and features.
+- **Upgrade Path:** Transitioning from 2.1.x to 3.0.0 is seamless. All documented interfaces remain unchanged, and the upgrade process requires no code modifications for existing consumers. The major version bump reflects strategic lifecycle consolidation and a renewed focus on long-term maintainability, rather than disruptive changes.
+- **Lifecycle Consolidation:** This release unifies prior stabilization efforts, setting a new baseline for future enhancements and support. Users can expect ongoing improvements in reliability, observability, and operational efficiency.
 
-### Removed
-- Old test files and legacy appstate generator scripts (now replaced by Nexus Login System).
+### Historical Logs
+Version logs for the 2.1.x series have been archived and are available upon request for reference and audit purposes.

package/README.md

@@ -1,77 +1,30 @@
-# Nexus-FCA v2.1.7
-
-<!-- 2.1.7 Session Stability Patch -->
-> New in 2.1.7: Session Stability Patch – anchored User-Agent continuity (eliminates 20–22h silent expiry pattern), lightweight mid‑session token poke (6h ±40m) + existing adaptive safeRefresh, retains ultra‑low ban profile.
-
-<!-- 2.1.6 Memory Guard -->
-> 2.1.6: Memory Guard & Queue Sweeping – bounded group queues, pending edit TTL sweeper, memory metrics exporter.
-
-<!-- 2.1.5 PendingEdits -->
-> 2.1.5: PendingEdits buffer (cap + TTL + safe resend), edit ACK watchdog, p95 ACK latency & edit resend/failure metrics, configurable via `api.setEditOptions()`.
-
 <p align="center">
-  <!-- Preview image wrapped in link (corrected ibb.co domain) -->
-  <a href="https://ibb.co/8ymR1tw"><img src="https://i.ibb.co/Sk61FGg/Dragon-Fruit-1.jpg" alt="Nexus-FCA Dragon Fruit" width="520" border="0" /></a>
+  <img src="https://i.ibb.co/Sk61FGg/Dragon-Fruit-1.jpg" alt="Nexus-FCA" width="520" />
 </p>
 
-> Advanced, safe, modern Facebook Chat (Messenger) API with integrated secure login (ID / Password / 2FA), ultra‑low ban rate session management, adaptive MQTT resilience, memory guard, and TypeScript-ready developer experience.
+# Nexus-FCA v3.0.0 – Advanced Core Release
 
----
-## ✨ Highlights (Core Pillars)
-- 🔐 Integrated secure login system (username/password + TOTP 2FA) → auto appstate
-- 🛡️ Ultra-low ban rate design (human timing, safety limiter, anchored UA, risk heuristics)
-- 🔄 Resilient MQTT listener (adaptive backoff + idle / ghost detection + periodic recycle)
-- ♻️ Session continuity: anchored UA + adaptive safe refresh + lightweight mid-session poke
-- 🧠 Smart session validation (lazy preflight, multi-endpoint retry, reduced false logouts)
-- 📊 Live health & memory metrics (`api.getHealthMetrics()`, `api.getMemoryMetrics()`)
-- 🧾 Type definitions (`index.d.ts`) & modern Promise / callback API
-- 🧩 Modular architecture (safety, performance, error, mqtt managers)
+Modern, safe, production‑ready Messenger (Facebook Chat) API layer with integrated secure login (credentials + 2FA), adaptive session & connection resilience, delivery reliability safeguards, memory protection, and rich runtime metrics. Promise + callback compatible, TypeScript typed, minimal friction.
 
 ---
-## 🚀 Recent Stability Enhancements (2.1.7 / 2.1.6 / 2.1.5)
-| Version | Focus | Key Additions |
-|---------|-------|---------------|
-| 2.1.7 | Session Longevity | UA continuity anchor, lightweight token poke, removal of mid-login UA drift |
-| 2.1.6 | Memory Safety | Group queue idle purge + overflow trim, pendingEdits TTL sweeper, memory guard metrics |
-| 2.1.5 | Edit Reliability | PendingEdits buffer (cap+TTL), ACK watchdog, resend limits, p95 ACK latency |
-
-### Why UA Continuity Matters
-Previously, dual-phase login could swap user agents (mobile → desktop) causing server-side heuristic expiry near 20–22h. Anchoring a single UA eliminates the inconsistent device fingerprint pattern and extends stable runtime under identical safety posture.
-
-### Lightweight Mid-Session Poke
-A subtle `fb_dtsg` refresh every ~6h ±40m (in addition to adaptive risk-based safeRefresh) keeps tokens warm without aggressive churn, lowering validation friction while avoiding noisy traffic patterns.
+## ✅ Core Value
+| Pillar | What You Get |
+|--------|--------------|
+| Integrated Secure Login | Username / Password / TOTP 2FA → stable appstate generation & reuse |
+| Session Resilience | Anchored User‑Agent continuity, adaptive safe refresh, lightweight token poke, periodic recycle |
+| Connection Stability | Adaptive MQTT backoff, idle & ghost detection, layered post-refresh health probes, synthetic keepalives |
+| Delivery Reliability | Multi-path message send fallback (MQTT → HTTP → direct) + delivery receipt timeout suppression |
+| Memory Guard | Bounded queues, edit TTL sweeps, controlled resend limits |
+| Observability | Health + memory + delivery metrics (`api.getHealthMetrics()`, `api.getMemoryMetrics()`) |
+| Edit Safety | Pending edit buffer, ACK watchdog, p95 ACK latency tracking |
+| Type Definitions | First-class `index.d.ts` with modern Promise signatures |
 
 ---
-## 🧪 Key API Additions
-```js
-api.setEditOptions({ maxPendingEdits, editTTLms, ackTimeoutMs, maxResendAttempts });
-api.setBackoffOptions({ base, factor, max, jitter });
-api.enableLazyPreflight(true); // Skip heavy validation if a recent good connect exists
-api.getHealthMetrics(); // uptime, reconnect stats, ack latency, synthetic keepalives
-api.getMemoryMetrics(); // queue depths, drops, guard run counters
-```
+## 🔄 What Changed in 3.0.0
+Major version signals maturity & consolidation. No breaking public API changes versus late 2.1.x – upgrade is drop‑in. Temporary diagnostic harness removed; internal instrumentation formalized. Delivery receipt timeouts now intelligently retried & optionally auto-suppressed to protect outbound responsiveness.
 
 ---
-## 🔍 Monitoring Example
-```js
-setInterval(() => {
-  const h = api.getHealthMetrics();
-  const m = api.getMemoryMetrics();
-  console.log('[HEALTH]', h?.status, 'acks', h?.ackCount, 'p95Ack', h?.p95AckLatencyMs);
-  console.log('[MEM]', m);
-}, 60000);
-```
-
----
-## 🧷 Long Session Best Practices
-1. Use appstate login when possible (avoid frequent credential logins).
-2. Keep `persistent-device.json` – do not rotate unless forced.
-3. Avoid changing UA manually; continuity is automatic post‑2.1.7.
-4. Inspect health metrics before manually forcing reconnects.
-5. Let adaptive backoff handle transient network instability.
-
----
-## ⚡ Quick Start (Appstate)
+## 🚀 Quick Start (Appstate Preferred)
 ```js
 const login = require('nexus-fca');
 
@@ -85,15 +38,14 @@ const login = require('nexus-fca');
 })();
 ```
 
-## 🔐 Quick Start (Credentials + 2FA)
+### Credentials + 2FA Flow
 ```js
 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_SECRET // optional
+    twofactor: process.env.FB_2FA_SECRET // optional TOTP secret
   });
   api.listen((err, msg) => {
     if (err) return console.error(err);
@@ -103,142 +55,132 @@ const login = require('nexus-fca');
 ```
 
 ---
-## 🛡️ Safety Layer (Updated)
-| Feature | Benefit |
-|---------|---------|
-| Anchored User-Agent | Eliminates fingerprint drift (prevents 20–22h expiry) |
-| Adaptive Safe Refresh | Risk‑sensitive token renewal bands |
-| Lightweight Token Poke | Quiet longevity without churn |
-| Idle / Ghost Detection | Auto probe + reconnect on silent stalls |
-| Periodic Recycle | 6h ± jitter connection rejuvenation |
-| Persistent Device Profile | Fewer checkpoints / trust continuity |
-| Lazy Preflight | Skips heavy validation when recently healthy |
-| Human-like Timing | Reduces automation signal surface |
-
-Disable preflight if needed:
+## 🧪 Key Runtime APIs
 ```js
-await login({ appState }, { disablePreflight: true });
+api.setEditOptions({ maxPendingEdits, editTTLms, ackTimeoutMs, maxResendAttempts });
+api.setBackoffOptions({ base, factor, max, jitter });
+api.enableLazyPreflight(true);       // Skip heavy validation if recent success
+api.getHealthMetrics();              // uptime, reconnects, ack latency, delivery stats
+api.getMemoryMetrics();              // queue sizes & guard counters
 ```
 
----
-## 🛰️ MQTT Listener Enhancements
-- Adaptive exponential backoff with jitter (caps 5m)
-- Soft-stale probing (2m30s) + hard watchdog tiers
-- Layered post-refresh health checks (1s / 10s / 30s) after token renewal
-- Synthetic keepalives (randomized 55–75s) feeding metrics
-
----
-## 📦 Example Echo Test
-`examples/echo-test.js`:
-```bash
-node examples/echo-test.js
+### Monitoring Snippet
+```js
+setInterval(() => {
+  const h = api.getHealthMetrics();
+  const m = api.getMemoryMetrics();
+  console.log('[HEALTH]', h?.status, 'acks', h?.ackCount, 'p95Ack', h?.p95AckLatencyMs);
+  console.log('[DELIVERY]', {
+    attempts: h?.deliveryAttempts,
+    success: h?.deliverySuccess,
+    failed: h?.deliveryFailed,
+    timeouts: h?.deliveryTimeouts,
+    disabledSince: h?.deliveryDisabledSince
+  });
+  console.log('[MEM]', m);
+}, 60000);
 ```
-Provide `appstate.json` or set `EMAIL` / `PASSWORD` env variables.
 
 ---
-## 🧠 Advanced Login Flow
-1. Integrated system safely generates / refreshes cookies (if credentials supplied)
-2. Core consumes resulting appstate for stable API behavior
-3. Persistent device JSON: `persistent-device.json`
+## 🛡️ Safety & Stability Architecture
+| Layer | Mechanism | Purpose |
+|-------|-----------|---------|
+| UA Continuity | Single anchored fingerprint | Avoid heuristic expiry & drift |
+| Adaptive Refresh | Risk-aware timing bands | Token longevity without bursts |
+| Lightweight Poke | Subtle `fb_dtsg` renewal | Keeps session warm quietly |
+| Collision Guard | 45m spacing window | Prevent clustered maintenance events |
+| Idle / Ghost Probe | Timed silent detection | Force reconnect on stale sockets |
+| Periodic Recycle | Randomized (~6h ±30m) | Pre-empt silent degradation |
+| Backoff Strategy | Exponential + jitter | Graceful network recovery |
+| Delivery Suppression | Disable after repeated timeouts | Preserve send latency |
 
-Persistent device toggle:
+Disable heavy preflight if embedding inside a framework already doing checks:
 ```js
-const { IntegratedNexusLoginSystem } = require('nexus-fca');
-new IntegratedNexusLoginSystem({ persistentDevice: true });
+await login({ appState }, { disablePreflight: 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.
-
-### Option 1: Non‑invasive (generate fresh appstate)
-1. In a separate script, run Nexus-FCA credential login (with 2FA if needed):
-```js
-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).
-
-### 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).
+## 🛰️ MQTT Enhancements (Since 2.1.x)
+- Adaptive reconnect curve (caps 5m)
+- Layered post-refresh probes (1s / 10s / 30s)
+- Synthetic randomized keepalives (55–75s)
+- Structured error classification feeding metrics
 
-### Option 3: Direct require patch
-Search GoatBot source for `require("fb-chat-api")` and change to `require("nexus-fca")`.
+---
+## ✉️ Delivery Reliability
+- Multi-path send fallback (MQTT publish → HTTP send → direct fallback)
+- Per-attempt timeout & retry for message delivery receipts
+- Automatic classification of transient timeouts (ETIMEDOUT / ECONNRESET / EAI_AGAIN)
+- Adaptive suppression of delivery receipt calls when environment unstable (protects primary send throughput)
 
-### 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 }
-```
+---
+## 🧠 Long Session Best Practices
+1. Prefer appstate reuse (minimal credential logins).
+2. Preserve `persistent-device.json` (only delete if forced challenge).
+3. Don’t manually rotate User-Agent – built-in continuity handles it.
+4. Inspect metrics before forcing reconnect; let backoff work.
+5. Keep dependencies updated; review CHANGELOG for operational notes.
 
-### 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.).
+---
+## 🐐 Using with GoatBot V2 (Summary)
+| Goal | Steps |
+|------|-------|
+| Generate appstate | Run credential login script → save `appstate.json` → configure GoatBot |
+| Full replacement | Install `nexus-fca` → shim `fb-chat-api/index.js` exporting module |
+| Direct require swap | Replace `require('fb-chat-api')` with `require('nexus-fca')` |
 
-### Minimal integration example
+Minimal 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);
+  api.listen((err, event) => {
+    if (err) return console.error(err);
     if (event.body === '!ping') api.sendMessage('pong', event.threadID);
   });
 })();
 ```
 
 ---
-## 📚 Documentation
-- Full API reference: `DOCS.md`
-- Per-feature guides: `/docs/*.md`
-- Safety: `docs/account-safety.md`
-- Examples: `/examples`
+## 📚 Documentation Map
+| Resource | Location |
+|----------|----------|
+| Full API Reference | `DOCS.md` |
+| Feature Guides | `docs/*.md` |
+| Safety Details | `docs/account-safety.md` |
+| Examples | `examples/` |
+
+---
+## � Migrating 2.1.x → 3.0.0
+| Area | Action Needed |
+|------|---------------|
+| Public API | None (fully compatible) |
+| Diagnostics Harness | Removed (no action) |
+| Delivery Metrics | Optionally surface in dashboards |
+| Safety Manager (legacy) | Keep removed / unused |
 
 ---
-## 🔁 Updating from 2.0.x → 2.1.x
-| Change | Action |
-|--------|--------|
-| UA Continuity (2.1.7) | No action; auto applied |
-| Memory Guard (2.1.6) | Inspect `api.getMemoryMetrics()` periodically |
-| PendingEdits (2.1.5) | Tune via `api.setEditOptions()` if needed |
-| Lazy Preflight | Optionally disable when embedding in other frameworks |
-| Persistent Device | Keep file unless forced reset required |
+## 🗂 Previous 2.1.x Highlights (Condensed)
+| Version | Focus | Key Additions |
+|---------|-------|---------------|
+| 2.1.10 | Stabilization | Final 2.1.x meta adjustments |
+| 2.1.8 | Safety Consolidation | Unified orchestrator, collision spacing, recycle suppression |
+| 2.1.7 | Session Longevity | UA continuity, lightweight poke |
+| 2.1.6 | Memory Guard | Queue pruning, edit TTL sweeps |
+| 2.1.5 | Edit Reliability | PendingEdits buffer, ACK watchdog |
 
-No breaking API changes across 2.1.x line.
+Full details remain in `CHANGELOG.md`.
 
 ---
 ## ⚠️ Disclaimer
-This project is not affiliated with Facebook. Use responsibly. You are solely responsible for compliance with platform terms and local laws.
+Not affiliated with Facebook. Use responsibly and comply with platform terms & local laws.
 
 ---
-## 🤝 Contribute
-PRs for safety, stability, perf, and updated GraphQL doc_ids welcome.
+## 🤝 Contributing
+Focused PRs improving stability, safety heuristics, protocol coverage, or typings are welcome.
 
 ---
 ## 📜 License
-MIT © 2025 Nexus-FCA Contributors
+[Team Nexus](https://www.facebook.com/profile.php?id=61572587854836)
+
+MIT © 2025 Nexus (Team Nexus)

package/docs/account-safety.md

@@ -11,6 +11,8 @@ Nexus-FCA Ultra-Safe Edition is designed to minimize Facebook account ban, lock,
 - **Proactive Safety Alerts:** If a risk is detected (lock, checkpoint, block), the bot will pause or stop to prevent further issues
 - **Session & Token Management:** Automatic session validation and safe token refresh keep your login secure
 - **Region & Connection Protection:** Advanced region bypass and safe reconnection logic avoid suspicious activity triggers
+- **Unified Safety Orchestrator (2.1.8+):** Single scheduler coordinates safe refresh, light poke (~6h ±40m), and periodic recycle (~6h ±30m) with collision spacing (45m) to prevent clustered token actions
+- **Ghost / Idle Detection:** Soft-stale probing (2m30s) and ghost recovery before full disconnect patterns emerge
 
 ---
 
@@ -24,6 +26,7 @@ Nexus-FCA Ultra-Safe Edition is designed to minimize Facebook account ban, lock,
   - Always use cookies less than 7 days old for best results
 - **Monitor Risk Level:**
   - Listen for `riskLevelHigh`, `accountLocked`, `checkpointRequired` events and take action if triggered
+- **Avoid Deprecated Manager:** Do not instantiate `FacebookSafetyManager` (legacy); consolidated `FacebookSafety` handles everything automatically.
 
 ---
 
@@ -34,6 +37,8 @@ Nexus-FCA Ultra-Safe Edition is designed to minimize Facebook account ban, lock,
 - **Update your appstate.json regularly**
 - **Monitor your Facebook account for security notifications**
 - **If you see a checkpoint or lock, stop the bot and verify your account manually**
+- **Do not schedule custom token poke timers; built‑in orchestrator already manages safe refresh cadence & spacing**
+- **Keep `persistent-device.json` stable—don’t delete unless forced by actual session invalidation**
 
 ---
 
@@ -55,6 +60,13 @@ client.login({ appState: require('./appstate.json') });
 - `checkpointRequired` — Facebook requires manual verification
 - `riskLevelHigh` — High risk detected, bot will increase delays and reduce activity
 - `sessionExpired` — Session expired, update your appstate.json
+- `safeRefresh` — Safe token refresh attempted (payload includes success/failure, duration)
+- `lightPoke` — Lightweight fb_dtsg keep-alive executed
+- `mqttReconnect` — Reconnect cycle triggered (reason + attempt)
+- `heartbeat` — Periodic keepalive ping succeeded
+
+### Event Spacing (2.1.8+)
+The orchestrator enforces a minimum spacing window (~45m) between maintenance actions (refresh, recycle, light poke). If a recycle is scheduled too soon after a refresh/poke it defers 20–30m automatically to avoid clustering patterns.
 
 ---
 
@@ -66,7 +78,16 @@ client.login({ appState: require('./appstate.json') });
 > Stop the bot immediately, log in to Facebook manually, and follow the verification steps. Only restart the bot after your account is fully restored.
 
 **Q: How often should I update my appstate.json?**
-> At least once a week, or whenever you see a session expired or checkpoint event.
+> At least once a week, or whenever you see a session expired or checkpoint event (less often if persistent device + long stable runs).
+
+**Q: How often are tokens refreshed now?**
+> Adaptive. Low risk uses multi‑hour windows; high risk shortens interval. Lightweight mid-session poke (~6h ±40m) and periodic recycle (~6h ±30m) are collision‑guarded with 45m spacing.
+
+**Q: Do I need to keep my own refresh timers?**
+> No. Remove custom refresh/poke loops—duplication increases clustering risk.
+
+**Q: Is legacy `FacebookSafetyManager` still required?**
+> No. It is deprecated and only logs a warning if used. Migrate entirely to the integrated safety layer (automatic on login).
 
 ---
 

package/index.js

@@ -271,6 +271,7 @@ function buildAPI(globalOptions, html, jar) {
       });
     },
     getHealthMetrics: function(){ return ctx.health ? ctx.health.snapshot() : null; },
+  getMqttDiagnostics: function(){ return ctx.getMqttDiagnostics ? ctx.getMqttDiagnostics() : (ctx._mqttDiag || null); },
     enableLazyPreflight(enable=true){ ctx.globalOptions.disablePreflight = !enable; },
     setBackoffOptions(opts={}){ ctx.globalOptions.backoff = Object.assign(ctx.globalOptions.backoff||{}, opts); },
     setEditOptions(opts={}){ Object.assign(ctx.globalOptions.editSettings, opts); },
@@ -296,6 +297,15 @@ function buildAPI(globalOptions, html, jar) {
       api[v.replace(".js", "")] = require("./src/" + v)(defaultFuncs, api, ctx);
     });
   api.listen = api.listenMqtt;
+  // Adaptive outbound pacing wrapper (dynamic risk + post-maintenance window)
+  if (!api._adaptivePacingWrapped && typeof api.sendMessage === 'function') {
+    const _origSend = api.sendMessage;
+    api.sendMessage = async function(message, threadID, callback){
+      try { if (globalSafety && typeof globalSafety.applyAdaptiveSendDelay === 'function') await globalSafety.applyAdaptiveSendDelay(); } catch(_) {}
+      return _origSend(message, threadID, callback);
+    };
+    api._adaptivePacingWrapped = true;
+  }
   // Safety wrapper: ensure every inbound MQTT event updates safety lastEvent timestamp
   if (!api._safetyWrappedListen) {
     const _origListen = api.listenMqtt;
@@ -505,21 +515,10 @@ function loginHelper(appState, email, password, globalOptions, callback, prCallb
       logger('✅ Session authenticated successfully', 'info');
       // Initialize safety monitoring
       globalSafety.startMonitoring(ctx, api);
-      // Schedule mid-session lightweight token poke (~ every 6h ±40m) to keep cookies warm
-      if(!globalOptions._lightRefreshTimer){
-        const scheduleLight = () => {
-          const base = 6 * 60 * 60 * 1000; // 6h
-          const jitter = (Math.random()*80 - 40) * 60 * 1000; // ±40m
-            globalOptions._lightRefreshTimer = setTimeout(async () => {
-              try {
-                if(api && typeof api.refreshFb_dtsg === 'function'){
-                  await api.refreshFb_dtsg().catch(()=>{});
-                }
-              } catch(_) {}
-              scheduleLight();
-            }, base + jitter);
-        };
-        scheduleLight();
+  try { globalSafety.startDynamicSystems(); } catch(_) {}
+      // Consolidated: delegate light poke to unified safety module (prevents duplicate refresh scheduling)
+      if (globalSafety && typeof globalSafety.scheduleLightPoke === 'function') {
+        globalSafety.scheduleLightPoke();
       }
       // Post-login identity banner
       try {

package/lib/health/HealthMetrics.js

@@ -34,6 +34,12 @@ class HealthMetrics {
     this.groupQueueExpiredQueues = 0;
     this.groupQueueDroppedMessages = 0;
     this.pendingEditSweeps = 0;
+  // Delivery receipt metrics
+  this.deliveryAttempts = 0;
+  this.deliverySuccess = 0;
+  this.deliveryFailed = 0;
+  this.deliveryTimeouts = 0;
+  this.deliveryDisabledSince = 0; // timestamp if adaptive disable engaged
   }
   onConnect() { this.lastConnectTs = Date.now(); this.consecutiveFailures = 0; }
   onDisconnect() { this.lastDisconnectTs = Date.now(); }
@@ -57,6 +63,7 @@ class HealthMetrics {
     this.p95AckLatencyMs = sorted[idx];
   }
   onError(type){ this.lastErrorTs = Date.now(); this.lastErrorType = type || 'unknown'; }
+  incFailure(){ this.consecutiveFailures++; }
   onReconnectScheduled(delay){ this.reconnects++; this.currentBackoffDelay = delay; if(delay > (this.maxObservedBackoff||0)) this.maxObservedBackoff = delay; }
   trackOutbound(depth){ this.outboundQueueDepth = depth; }
   incOutboundDropped(){ this.outboundQueueDropped++; }
@@ -114,6 +121,11 @@ class HealthMetrics {
       groupQueueExpiredQueues: this.groupQueueExpiredQueues,
       groupQueueDroppedMessages: this.groupQueueDroppedMessages,
       pendingEditSweeps: this.pendingEditSweeps,
+  deliveryAttempts: this.deliveryAttempts,
+  deliverySuccess: this.deliverySuccess,
+  deliveryFailed: this.deliveryFailed,
+  deliveryTimeouts: this.deliveryTimeouts,
+  deliveryDisabled: !!this.deliveryDisabledSince,
       healthy: this.isHealthy(idleMs)
     };
   }

package/lib/mqtt/MqttDiagnostics.js

@@ -0,0 +1,20 @@
+"use strict";
+// Lightweight diagnostics helper for MQTT/WebSocket connection lifecycle.
+// Captures low-level events so we can understand repeated reconnect loops.
+module.exports = function attachMqttDiagnostics(ws, ctx, log){
+  if(!ws || typeof ws.on !== 'function') return;
+  const diag = ctx._mqttDiag = ctx._mqttDiag || { attempts:0, events:[] };
+  function push(evt){
+    try {
+      diag.events.push({ t: Date.now(), ...evt });
+      if(diag.events.length > 50) diag.events.shift();
+    } catch(_) {}
+  }
+  ws.on('upgrade', (res)=>{ push({ type:'upgrade', status: res.statusCode, headers: safeHeaders(res.headers) }); });
+  ws.on('unexpected-response', (req, res)=>{ push({ type:'unexpected_response', status: res && res.statusCode, headers: res && safeHeaders(res.headers) }); });
+  ws.on('close', (code, reason)=>{ push({ type:'close', code, reason: reason && reason.toString() }); });
+  ws.on('error', (err)=>{ push({ type:'error', message: err && (err.message||err.code||'').toString(), code: err && err.code }); });
+  function safeHeaders(h){ if(!h) return {}; const out={}; for(const k of Object.keys(h)){ if(k.startsWith('cookie')) continue; out[k]=h[k]; } return out; }
+  // expose a snapshot method
+  ctx.getMqttDiagnostics = () => ({ attempts: diag.attempts, recent: [...diag.events] });
+};

package/lib/safety/FacebookSafety.js

@@ -76,6 +76,17 @@ class FacebookSafety {
         this._ghostChecking = false;
         // Periodic recycle timer
         this._periodicRecycleTimer = null;
+    // Consolidation additions
+    this._lastRefreshTs = 0; // track last successful refresh-like action
+    this._lastRecycleTs = 0;
+    this._lastLightPokeTs = 0;
+    this._timerRegistry = new Set();
+    this._minSpacingMs = 45 * 60 * 1000; // 45m guard between heavy/light actions
+    // Adaptive pacing + dynamic tuning additions
+    this._lastHeavyMaintenanceTs = 0; // last refresh OR successful reconnect
+    this._adaptivePacingWindowMs = 2 * 60 * 1000; // apply outbound pacing first 2m after heavy maintenance
+    this._dynamicHeartbeatTimer = null; // replaces fixed interval heartbeat for risk-tier tuning
+    this._riskLast = 'low';
 
         this.initSafety();
     }
@@ -282,10 +293,12 @@ class FacebookSafety {
                 maxMs = 5 * 60 * 60 * 1000;      // 5h
             }
             const interval = minMs + Math.random() * (maxMs - minMs);
-            this._safeRefreshTimer = setTimeout(async () => {
+            const t = setTimeout(async () => {
                 await this.refreshSafeSession();
                 schedule();
             }, interval);
+            this._registerTimer(t);
+            this._safeRefreshTimer = t;
         };
         schedule();
     }
@@ -305,13 +318,17 @@ class FacebookSafety {
     updateRiskLevel() {
         const timeSinceLastActivity = Date.now() - this.sessionMetrics.lastActivity;
         const errorRate = this.sessionMetrics.errorCount / Math.max(1, this.sessionMetrics.requestCount);
-
+        let next;
         if (errorRate > 0.3 || timeSinceLastActivity < 1000) {
-            this.sessionMetrics.riskLevel = 'high';
+            next = 'high';
         } else if (errorRate > 0.1 || timeSinceLastActivity < 5000) {
-            this.sessionMetrics.riskLevel = 'medium';
+            next = 'medium';
         } else {
-            this.sessionMetrics.riskLevel = 'low';
+            next = 'low';
+        }
+        if (next !== this.sessionMetrics.riskLevel) {
+            this.sessionMetrics.riskLevel = next;
+            this._onRiskLevelChanged(next);
         }
     }
 
@@ -371,10 +388,7 @@ class FacebookSafety {
             const now = Date.now();
             if (now < this._backoff.next) { return; }
             const attempt = ++this._backoff.attempt;
-            // Stealth backoff: 1.2s * 1.8^n capped ~20s, add jitter 0-500ms
-            const baseDelay = Math.min(20000, 1200 * Math.pow(1.8, Math.min(attempt, 6)));
-            const jitter = Math.random() * 500;
-            const delay = baseDelay + jitter;
+            const delay = this._computeBackoffDelay(attempt);
             this._backoff.next = now + delay;
             await new Promise(r => setTimeout(r, delay));
             if (this._activeListenerStop && typeof this._activeListenerStop === 'function') { try { this._activeListenerStop(); } catch(_) {} }
@@ -382,6 +396,7 @@ class FacebookSafety {
                 const stop = this.api.listenMqtt((err, event) => { if (!err && event) this.recordEvent(); });
                 this._activeListenerStop = stop;
                 this.safetyEmit('mqttReconnect', { success: true, reason, attempt, delay });
+                this._markHeavyMaintenance();
             }
             setTimeout(() => {
                 if (this.ctx && this.ctx.mqttClient && this.ctx.mqttClient.connected) { this._backoff.attempt = 0; }
@@ -405,11 +420,22 @@ class FacebookSafety {
         const base = 6 * 60 * 60 * 1000; // 6h
         const jitter = (Math.random() * 60 - 30) * 60 * 1000; // ±30m
         const delay = base + jitter;
-        this._periodicRecycleTimer = setTimeout(() => {
+        const t = setTimeout(() => {
             if (this._destroyed) return;
+            // Suppress recycle if a refresh/poke just happened inside spacing window
+            if (Date.now() - this._lastRefreshTs < this._minSpacingMs) {
+                // reschedule shorter backoff (add 20m) to avoid clustering
+                const defer = 20 * 60 * 1000 + Math.random() * 10 * 60 * 1000; // 20–30m
+                const dt = setTimeout(()=> this._schedulePeriodicRecycle(), defer);
+                this._registerTimer(dt);
+                return;
+            }
+            this._lastRecycleTs = Date.now();
             this.forceReconnect('periodic');
             this._schedulePeriodicRecycle();
         }, delay);
+        this._registerTimer(t);
+        this._periodicRecycleTimer = t;
     }
 
     // Heartbeat ping & watchdog
@@ -504,6 +530,10 @@ class FacebookSafety {
     async refreshSafeSession() {
         // Improved safe session refresh implementation
         if (this._refreshing) return; // prevent concurrent refreshes
+        // Collision guard – skip if a refresh/poke happened very recently
+        if (Date.now() - this._lastRefreshTs < this._minSpacingMs / 2) {
+            return;
+        }
         this._refreshing = true;
         const refreshId = ++this._inFlightRefreshId;
         const startedAt = Date.now();
@@ -532,6 +562,8 @@ class FacebookSafety {
                 durationMs: Date.now() - startedAt,
                 message: 'Session tokens refreshed'
             });
+            this._lastRefreshTs = Date.now();
+            this._markHeavyMaintenance();
             // Immediate MQTT health ensure
             await this._ensureMqttAlive();
             // Schedule layered post-refresh checks (1s, 10s, 30s) to catch silent drops
@@ -570,11 +602,51 @@ class FacebookSafety {
         }
     }
 
+    /**
+     * Lightweight poke (fb_dtsg refresh only) integrated to remove duplicate logic in index.js
+     */
+    scheduleLightPoke() {
+        if (this._lightPokeTimer || this._destroyed) return;
+        const base = 6 * 60 * 60 * 1000; // 6h
+        const jitter = (Math.random()*80 - 40) * 60 * 1000; // ±40m
+        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()*80 - 40) * 60 * 1000);
+            this._registerTimer(t);
+            this._lightPokeTimer = t;
+        };
+        schedule();
+    }
+
+    _registerTimer(t){
+        if (!t) return;
+        this._timerRegistry.add(t);
+    }
+
     // Cleanup / destroy resources (to prevent dangling timers)
     destroy() {
         this._destroyed = true;
-        const timers = [this._safeRefreshInterval, this._safeRefreshTimer, this._heartbeatTimer, this._watchdogTimer, this._periodicRecycleTimer];
+        const timers = [this._safeRefreshInterval, this._safeRefreshTimer, this._heartbeatTimer, this._watchdogTimer, this._periodicRecycleTimer, this._lightPokeTimer];
         timers.forEach(t => t && clearTimeout(t));
+        // Clear any registered anonymous timers
+        this._timerRegistry.forEach(t => clearTimeout(t));
+        this._timerRegistry.clear();
         if (this._activeListenerStop) {
             try { this._activeListenerStop(); } catch (_) {}
             this._activeListenerStop = null;
@@ -622,6 +694,99 @@ class FacebookSafety {
         }
     }
 
+    /* ======================== Dynamic Tuning & Pacing ======================== */
+    _onRiskLevelChanged(risk){
+        // Adjust spacing guard slightly (high risk allow earlier refresh to recover)
+        if (risk === 'high') this._minSpacingMs = 30 * 60 * 1000; else this._minSpacingMs = 45 * 60 * 1000;
+        // Reschedule heartbeat dynamically
+        this._scheduleDynamicHeartbeat(true);
+        this.safetyEmit('riskLevelChanged', { risk });
+    }
+
+    _computeBackoffDelay(attempt){
+        const risk = this.sessionMetrics.riskLevel;
+        const a = Math.min(attempt, 6);
+        let base;
+        if (risk === 'high') {
+            base = 900 * Math.pow(1.6, a); // faster recovery
+        } else if (risk === 'medium') {
+            base = 1100 * Math.pow(1.7, a);
+        } else { // low
+            base = 1500 * Math.pow(1.9, a); // slower to reduce noise
+        }
+        const cap = (risk === 'low') ? 25000 : (risk === 'medium' ? 22000 : 18000);
+        const delay = Math.min(cap, base) + Math.random()*600; // jitter
+        return delay;
+    }
+
+    _scheduleDynamicHeartbeat(reset){
+        if (reset && this._dynamicHeartbeatTimer){ clearTimeout(this._dynamicHeartbeatTimer); this._dynamicHeartbeatTimer = null; }
+        if (this._destroyed) return;
+        const interval = this._computeHeartbeatInterval();
+        this._dynamicHeartbeatTimer = setTimeout(()=>{
+            if (this._destroyed) return;
+            try {
+                if (this.ctx && this.ctx.mqttClient && this.ctx.mqttClient.connected) {
+                    if (this.ctx.mqttClient.ping) this.ctx.mqttClient.ping();
+                    try { this.ctx.mqttClient.publish('/foreground_state', JSON.stringify({ foreground: true })); } catch(_) {}
+                    this.safetyEmit('heartbeat', { ts: Date.now(), dynamic: true });
+                }
+            } catch(_) {}
+            // Watchdog like check
+            this._runDynamicWatchdog();
+            this._scheduleDynamicHeartbeat(false);
+        }, interval);
+        this._registerTimer(this._dynamicHeartbeatTimer);
+    }
+
+    _computeHeartbeatInterval(){
+        const risk = this.sessionMetrics.riskLevel;
+        if (risk === 'high') return (55 + Math.random()*20) * 1000; // 55–75s
+        if (risk === 'medium') return (70 + Math.random()*20) * 1000; // 70–90s
+        return (80 + Math.random()*20) * 1000; // 80–100s
+    }
+
+    _runDynamicWatchdog(){
+        const idle = Date.now() - this._lastEventTs;
+        // escalate thresholds slightly by risk (high risk shorter tolerance)
+        const hard = (this.sessionMetrics.riskLevel === 'high') ? 8*60*1000 : 12*60*1000;
+        if (idle > hard) {
+            this._backoff.attempt = 0;
+            this._ensureMqttAlive();
+        }
+    }
+
+    _markHeavyMaintenance(){
+        this._lastHeavyMaintenanceTs = Date.now();
+    }
+
+    computeAdaptiveSendDelay(){
+        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; }
+        }
+        if (max<=0) return 0;
+        return Math.floor(min + Math.random()*(max-min));
+    }
+
+    applyAdaptiveSendDelay(){
+        const d = this.computeAdaptiveSendDelay();
+        if (!d) return Promise.resolve();
+        return new Promise(r=> setTimeout(r, d));
+    }
+
+    startDynamicSystems(){
+        this._scheduleDynamicHeartbeat(true);
+    }
+
     /**
      * Set safety event handler
      */
@@ -630,4 +795,4 @@ class FacebookSafety {
     }
 }
 
-module.exports = FacebookSafety;
+module.exports = FacebookSafety;

package/lib/safety/FacebookSafetyManager.js

@@ -13,7 +13,8 @@ class FacebookSafetyManager extends EventEmitter {
     constructor(options = {}) {
         super();
         
-        this.options = {
+    console.warn('[DEPRECATION] FacebookSafetyManager is deprecated. The unified FacebookSafety module now handles all safety logic. Avoid using this manager.');
+    this.options = {
             // Auto re-login detection
             autoReloginEnabled: options.autoReloginEnabled !== false,
             autoReloginRetries: options.autoReloginRetries || 3,
@@ -112,7 +113,7 @@ class FacebookSafetyManager extends EventEmitter {
             this.startUserAgentRotation();
         }
         
-        logger('🛡️ Facebook Safety Manager initialized with maximum protection', 'info');
+    logger('🛡️ (Deprecated) Facebook Safety Manager initialized (prefer unified FacebookSafety)', 'info');
     }
     
     /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nexus-fca",
-  "version": "2.1.8",
-  "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.",
+  "version": "3.0.0",
+  "description": "Nexus-FCA 3.0 – stable, low-risk Facebook Messenger automation API with integrated secure login (ID / Password / 2FA), adaptive MQTT core, safety orchestration, metrics, and TypeScript support.",
   "main": "index.js",
   "repository": {
     "type": "git",

package/src/listenMqtt.js

@@ -166,9 +166,15 @@ function buildStream(options, WebSocket, Proxy) {
   return Stream;
 }
 function listenMqtt(defaultFuncs, api, ctx, globalCallback) {
+  const attemptStartTs = Date.now();
   // Attach health metrics container lazily
   if(!ctx.health) ctx.health = new (require('../lib/health/HealthMetrics').HealthMetrics)();
+  // Ensure tasks map exists to track ls_req -> ls_resp correlations (avoid TypeError on undefined)
+  if(!ctx.tasks) ctx.tasks = new Map();
   const backoff = getBackoffState(ctx);
+  if(!ctx._mqttDiag) ctx._mqttDiag = { attempts:0, events:[] }; 
+  ctx._mqttDiag.attempts++;
+  log.info('listenMqtt', `Attempt #${ctx._mqttDiag.attempts} starting (backoffCurrent=${backoff.current||0})`);
   const runPreflight = shouldRunPreflight(ctx);
   if (runPreflight) {
     (async () => {
@@ -263,20 +269,27 @@ function listenMqtt(defaultFuncs, api, ctx, globalCallback) {
       log.error("listenMqtt", `Failed to create proxy agent: ${error.message}`);
     }
   }
+  // Create raw WebSocket first so we can attach diagnostics hooks.
+  const rawWs = new WebSocket(host, options.wsOptions);
+  try { require('../lib/mqtt/MqttDiagnostics')(rawWs, ctx, log); } catch(_) {}
   ctx.mqttClient = new mqtt.Client(
-    () =>
-      buildStream(
-        options,
-        new WebSocket(host, options.wsOptions),
-        buildProxy()
-      ),
+    () => buildStream(options, rawWs, buildProxy()),
     options
   );
+  log.info('listenMqtt', `Connecting to ${host}`);
   const mqttClient = ctx.mqttClient;
   global.mqttClient = mqttClient;
   mqttClient.on('error', function (err) {
     const errMsg = (err && (err.error || err.message || "")).toString();
     ctx.health.onError(errMsg.includes('not logged in') ? 'not_logged_in' : 'mqtt_error');
+    // Increment failure counter for health tracking
+    if(ctx.health && typeof ctx.health.incFailure === 'function') ctx.health.incFailure();
+    if(!errMsg){
+      log.error('listenMqtt', 'Empty error message (mqtt error event). Raw err object: ' + JSON.stringify(Object.getOwnPropertyNames(err || {}).reduce((a,k)=>{a[k]=err[k];return a;},{})));
+    }
+    else {
+      log.error('listenMqtt', `MQTT error after ${(Date.now()-attemptStartTs)}ms: ${errMsg}`);
+    }
     log.error("listenMqtt", errMsg);
     try { mqttClient.end(true); } catch(_){ }
     if (/not logged in|login_redirect|html_login_page/i.test(errMsg)) {
@@ -294,6 +307,8 @@ function listenMqtt(defaultFuncs, api, ctx, globalCallback) {
   // Ensure reconnection also triggers on unexpected close without prior error
   mqttClient.on('close', function () {
     ctx.health.onDisconnect();
+  if(ctx.health && typeof ctx.health.incFailure === 'function'){ ctx.health.incFailure(); }
+  log.warn('listenMqtt', `Socket closed after ${(Date.now()-attemptStartTs)}ms (attempt #${ctx._mqttDiag.attempts}).`);
     if (!ctx.loggedIn) return; // avoid loops if logged out
     if (ctx.globalOptions.autoReconnect) {
       scheduleAdaptiveReconnect(defaultFuncs, api, ctx, globalCallback);
@@ -301,6 +316,8 @@ function listenMqtt(defaultFuncs, api, ctx, globalCallback) {
   });
   mqttClient.on('disconnect', function(){
     ctx.health.onDisconnect();
+  if(ctx.health && typeof ctx.health.incFailure === 'function'){ ctx.health.incFailure(); }
+  log.warn('listenMqtt', `MQTT disconnect event after ${(Date.now()-attemptStartTs)}ms (attempt #${ctx._mqttDiag.attempts}).`);
     if (!ctx.loggedIn) return;
     if (ctx.globalOptions.autoReconnect) {
       scheduleAdaptiveReconnect(defaultFuncs, api, ctx, globalCallback);
@@ -309,6 +326,7 @@ function listenMqtt(defaultFuncs, api, ctx, globalCallback) {
   mqttClient.on("connect", function () {
     resetBackoff(backoff);
     ctx.health.onConnect();
+  log.info('listenMqtt', `Connected in ${(Date.now()-attemptStartTs)}ms (attempt #${ctx._mqttDiag.attempts}).`);
     if (ctx.globalSafety) { try { ctx.globalSafety.recordEvent(); } catch(_) {} }
     if (process.env.OnStatus === undefined) {
       logger("Nexus-FCA premium features works only with Nexus-Bot framework(Kidding)", "info");
@@ -418,7 +436,8 @@ function listenMqtt(defaultFuncs, api, ctx, globalCallback) {
       } else if (topic == "/ls_resp") {
         const parsedPayload = JSON.parse(jsonMessage.payload);
         const reqID = jsonMessage.request_id;
-        if (ctx["tasks"].has(reqID)) {
+  // Guard: ctx.tasks may be empty; only proceed if it's a Map and contains the reqID
+  if (ctx.tasks && typeof ctx.tasks.has === 'function' && ctx.tasks.has(reqID)) {
           const taskData = ctx["tasks"].get(reqID);
           const { type: taskType, callback: taskCallback } = taskData;
           const taskRespData = getTaskResponseData(taskType, parsedPayload);

package/src/markAsDelivered.js

@@ -30,28 +30,61 @@ module.exports = function (defaultFuncs, api, ctx) {
 		form["message_ids[0]"] = messageID;
 		form["thread_ids[" + threadID + "][0]"] = messageID;
 
-		defaultFuncs
-			.post(
-				"https://www.facebook.com/ajax/mercury/delivery_receipts.php",
-				ctx.jar,
-				form
-			)
-			.then(utils.saveCookies(ctx.jar))
-			.then(utils.parseAndCheckLogin(ctx, defaultFuncs))
-			.then(function (resData) {
-				if (resData.error) {
-					throw resData;
-				}
-
+		// Lightweight retry with exponential backoff for transient network timeouts.
+		const maxAttempts = 3;
+		let attempt = 0;
+		const baseDelay = 500; // ms
+		const transientCodes = ['ETIMEDOUT','ECONNRESET','EAI_AGAIN'];
+		if(ctx.health){
+			ctx.health.deliveryAttempts++;
+			// If we previously disabled delivery receipts due to repeated timeouts, short-circuit success.
+			if(ctx.health.deliveryDisabledSince){
 				return callback();
-			})
-			.catch(function (err) {
-				log.error("markAsDelivered", err);
-				if (utils.getType(err) == "Object" && err.error === "Not logged in.") {
-					ctx.loggedIn = false;
-				}
-				return callback(err);
-			});
+			}
+		}
+		function doPost(){
+			attempt++;
+			defaultFuncs
+				.post(
+					"https://www.facebook.com/ajax/mercury/delivery_receipts.php",
+					ctx.jar,
+					form
+				)
+				.then(utils.saveCookies(ctx.jar))
+				.then(utils.parseAndCheckLogin(ctx, defaultFuncs))
+				.then(function (resData) {
+					if (resData.error) { throw resData; }
+					if(ctx.health){ ctx.health.deliverySuccess++; }
+					return callback();
+				})
+				.catch(function (err) {
+					const code = err && (err.code || err.errno || (err.error && err.error.code));
+					const isTransient = code && transientCodes.includes(code);
+					if(code === 'ETIMEDOUT' && ctx.health){ ctx.health.deliveryTimeouts++; }
+					if(isTransient && attempt < maxAttempts){
+						const delay = Math.round(baseDelay * Math.pow(2, attempt-1) * (1 + Math.random()*0.2));
+						log.warn('markAsDelivered', `Transient ${code} attempt ${attempt}/${maxAttempts} -> retrying in ${delay}ms`);
+						return setTimeout(doPost, delay);
+					}
+					// Suppress noisy timeout logs after final retry unless verbose
+					if(!(isTransient && attempt >= maxAttempts)){
+						log.error("markAsDelivered", err);
+					}else{
+						log.warn('markAsDelivered', `Giving up after ${attempt} attempts (${code})`);
+						// Adaptive disable: if too many timeouts overall, stop calling delivery receipts for this run
+						if(code === 'ETIMEDOUT' && ctx.health && ctx.health.deliveryTimeouts >= 5){
+							ctx.health.deliveryDisabledSince = Date.now();
+							log.warn('markAsDelivered', 'Adaptive disable engaged after repeated ETIMEDOUT. Further receipts suppressed.');
+						}
+					}
+					if (utils.getType(err) == "Object" && err.error === "Not logged in.") {
+						ctx.loggedIn = false;
+					}
+					if(ctx.health){ ctx.health.deliveryFailed++; }
+					return callback(err);
+				});
+		}
+		doPost();
 
 		return returnPromise;
 	};