nexus-fca 2.1.10 → 3.0.0

package/CHANGELOG.md

@@ -1,235 +1,21 @@
 # Changelog
+## [3.0.0] - 2025-09-11 - Advanced Core Release
 
-## [2.1.10] - 2025-09-08 - Publish Meta Bump
-### Changed
-- Fixed Major Problems found in 2.1.9 and Its the last version of 2.1.xxx
-
-### Notes
-- 2.1.8 And 2.1.10 is the most stable verion!
-
----
-
-## [2.1.9] - 2025-09-08 - Advanced Stability Prep
-### Added
-- Dynamic risk-tier tuning: heartbeat interval, backoff delay, spacing guard adjust automatically on risk changes.
-- Adaptive outbound pacing: micro-delays after heavy maintenance (refresh/reconnect) to reduce burst patterns (2m adaptive window).
-
-### Changed
-- Reconnect backoff now computed via risk-aware curve (faster recovery in high risk, quieter in low risk).
-
-### Notes
-- Optional, transparent; no API break. Can expose stats later via planned getSafetyTimingStats.
-
----
-
-## [2.1.8] - 2025-09-08 - Safety Consolidation & Collision Guard
-### Added
-- Unified safety orchestrator (single module coordinates safe refresh, light poke, periodic recycle) with timer registry and structured teardown.
-- Collision spacing guard (45m) preventing clustered token operations (refresh/poke/recycle).
-- Recycle suppression logic (defers 20–30m if a refresh/poke occurred inside spacing window).
-- Light poke integration moved inside `FacebookSafety.scheduleLightPoke()` (duplicate inline scheduling removed).
-- Deprecation warning emitted when legacy `FacebookSafetyManager` is instantiated.
-
-### Changed
-- Removed duplicate mid-session poke timer from `index.js`.
-- Safe refresh participates in collision guard and spacing tracking (`_lastRefreshTs`).
-- Periodic recycle respects `_minSpacingMs` and defers if necessary.
-
-### Improved
-- Lower probability of rapid successive token / connection maintenance clustering.
-- Simplified lifecycle cleanup through timer registry.
-
-### Deprecated
-- `FacebookSafetyManager` (legacy) – retained for backward compatibility only.
+### 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.
 
-### Notes
-- No public API break; users should remove custom light poke timers.
-
----
-
-## [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.
+- **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
-- 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).
-
-### 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
-- 🧩 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,84 +1,30 @@
-# Nexus-FCA v2.1.10
-<!-- 2.1.10 Safety Consolidation -->
->Fixed Major Problems found in 2.1.9 and Its the last version of 2.1.xxx
-
-<!-- 2.1.9 Safety Consolidation -->
-> New in 2.1.9: Safety Consolidation & Collision Guard – unified safety orchestrator (single scheduler for safe refresh, light poke, periodic recycle) + 45m spacing guard (prevents clustered token actions), timer registry cleanup, recycle suppression after recent refresh, deprecates legacy FacebookSafetyManager.
-
-<!-- 2.1.7 Session Stability Patch -->
-> 2.1.7: Session Stability Patch – anchored User-Agent continuity (eliminates 20–22h silent expiry pattern), lightweight mid‑session token poke (6h ±40m randomized) + 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 + integrated 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.8 / 2.1.7 / 2.1.6 / 2.1.5)
-| Version | Focus | Key Additions |
-|---------|-------|---------------|
-| 2.1.8 | Safety Consolidation | Unified orchestrator, collision spacing (45m), timer registry, recycle suppression, legacy manager deprecated |
-| 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 (Integrated)
-Originally introduced in 2.1.7, now centrally scheduled inside the unified safety orchestrator (no duplicate inline timers). A subtle `fb_dtsg` refresh every ~6h (±40m randomized, alongside adaptive risk-based safe refresh) keeps tokens warm without aggressive churn while avoiding noisy traffic patterns. Collision guard ensures it never triggers too close to a full safe refresh or periodic recycle.
+## ✅ 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.
-6. Avoid using deprecated `FacebookSafetyManager`; the consolidated safety layer activates automatically when `login()` resolves.
-
----
-## ⚡ Quick Start (Appstate)
+## 🚀 Quick Start (Appstate Preferred)
 ```js
 const login = require('nexus-fca');
 
@@ -92,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);
@@ -110,147 +55,132 @@ const login = require('nexus-fca');
 ```
 
 ---
-## 🛡️ Safety Layer (Updated 2.1.8)
-| Feature | Benefit |
-|---------|---------|
-| Anchored User-Agent | Eliminates fingerprint drift (prevents 20–22h expiry) |
-| Unified Orchestrator | Single scheduler for refresh, light poke, recycle (no overlap clashes) |
-| Adaptive Safe Refresh | Risk‑sensitive token renewal bands (multi‑hour low risk, shorter high risk) |
-| Lightweight Token Poke | Quiet longevity without churn (integrated + collision guarded) |
-| Idle / Ghost Detection | Auto probe + reconnect on silent stalls |
-| Periodic Recycle | ~6h (±30m) randomized connection rejuvenation (suppressed if recent refresh) |
-| Persistent Device Profile | Fewer checkpoints / trust continuity |
-| Lazy Preflight | Skips heavy validation when recently healthy |
-| Human-like Timing | Reduces automation signal surface |
-
-### Consolidation / Collision Guard (2.1.8)
-The unified safety module keeps a registry of all scheduled timers (safe refresh, light poke, post-refresh health checks, periodic recycle) and enforces a minimum 45 minute spacing window so heavy or light token actions never cluster. Legacy `FacebookSafetyManager` now only emits a deprecation warning and should not be instantiated going forward.
-
-Disable preflight if needed:
+## 🧪 Key Runtime APIs
 ```js
-await login({ appState }, { disablePreflight: true });
-```
-
----
-## 🛰️ 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
+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
 ```
-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`
-
-Persistent device toggle:
+### Monitoring Snippet
 ```js
-const { IntegratedNexusLoginSystem } = require('nexus-fca');
-new IntegratedNexusLoginSystem({ persistentDevice: true });
+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);
 ```
 
 ---
-## 🐐 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.
+## 🛡️ 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 |
 
-### Option 1: Non‑invasive (generate fresh appstate)
-1. In a separate script, run Nexus-FCA credential login (with 2FA if needed):
+Disable heavy preflight if embedding inside a framework already doing checks:
 ```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');
-})();
+await login({ appState }, { disablePreflight: true });
 ```
-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` (unified orchestrator & deprecation note)
-- 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 |
-| Safety Consolidation (2.1.8) | Remove any manual timers/light poke code – handled internally |
-| 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/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); },

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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nexus-fca",
-  "version": "2.1.10",
-  "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;
 	};