nkx-fca 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,144 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [1.2.0] - 2026-03-19
+
+### Fixed
+
+**Token Refresh — Concurrency & Reliability**
+- `TokenRefreshManager.refreshTokens` was not concurrency-safe: the 10-hour scheduled refresh, 2-hour health-check-triggered refresh, and `getSeqID` emergency refresh could all fire simultaneously, sending a burst of full homepage requests to Facebook and writing half-updated tokens (`fb_dtsg`, `lsd`, `ttstamp`, `jazoest`, `__rev`) to `ctx` mid-flight. Fixed by making `refreshTokens` a deduplication wrapper: all concurrent callers share the same in-flight Promise and receive the same result. Only one HTTP round-trip is ever issued at a time.
+- Internal retry logic was ordered incorrectly: `failureCount >= MAX_FAILURES` was checked *before* exhausting internal per-call retries, so a single transient network error at the wrong moment immediately invoked `onSessionExpiry` (triggering a full re-login) without attempting the built-in 3-retry backoff. Retries now always run first; `onSessionExpiry` is only called after all retries are genuinely exhausted.
+
+**Auto Re-Login — Recovery After Outages**
+- The 15-minute recovery timer that resets `retryCount` after auto-relogin exhausts its 3 attempts now also calls `api.tokenRefreshManager.resetFailureCount()`. Previously, `failureCount` remained pinned at `MAX_FAILURES`, so the next scheduled token-refresh cycle (10-hour or 2-hour health-check) would escalate to `onSessionExpiry` on the very first transient error with no internal retries — incorrectly triggering another re-login when a simple retry would have worked.
+- `pendingRequests` queue — callers waiting for an in-progress re-login to complete had no timeout and would hang forever if `loginHelper` stopped responding. Each queued waiter now times out after 5 minutes and rejects with a clear error message.
+- Warmup timer (`enableWarmup`) — the `setTimeout` handle was not stored, so `destroy()` could not cancel it. Stored as `this._warmupTimer`; cleared on both re-call and `destroy()`.
+
+**Memory — Thread Type Cache**
+- `ctx.threadTypeCache` in `sendMessage` was a plain object that grew without bound — one entry per unique thread ID for the entire lifetime of the process. Replaced with `ctx.cache` (the existing TTL-based `SimpleCache`): thread-type lookups now expire after 24 hours and failed lookups after 1 hour.
+
+**Rate Limiter — Stuck Counter Protection**
+- `checkRateLimit` contained a `while (activeRequests >= MAX)` loop with no exit condition — the only loop in the file without a safety break. An event-loop anomaly that prevented the `setTimeout` decrement from firing would have permanently blocked every subsequent request. Added a 60-second forced exit: after 600 × 100 ms iterations the counter is reset to a safe value and a warning is logged.
+
+**MQTT API Fixes**
+- `removeUserFromGroup`: on the success path the 30-second MQTT timeout was not cleared (`clearTimeout` was missing), leaving the timer alive in the event loop until it fired, checked the `responseHandled` flag, and did nothing. Added `clearTimeout` before the success callback.
+- `listenMqtt`: orphaned `callback_Task` entries (MQTT tasks with no response) now expire after 5 minutes; the watchdog removes them and invokes their callbacks with a timeout error rather than leaking them for the process lifetime.
+- `listenMqtt`: orphaned `shareContact` callback accumulation fixed — entries now carry an `addedAt` timestamp so the watchdog can age them out.
+
+---
+
+## [1.1.0] - 2026-03-16
+
+### Fixed
+
+**MQTT Reliability**
+- `close` handler now captures `wasConnected` before clearing `ctx._mqttConnected`, so the quick-close detection window is evaluated correctly instead of always being skipped
+- Re-auth triggered by the quick-close threshold now `return`s immediately, preventing a duplicate reconnect from the normal backoff path racing against it
+- `offline` event now schedules a backoff reconnect after ending the client — previously the bot would silently stay offline with no recovery
+- Added `maxReconnectAttempts` cap (default 100): after hitting the cap the library pauses 10 minutes before resetting, preventing an indefinite 30 s retry loop that is a detectable bot pattern
+
+**Session & Auth**
+- `stopListening` now stops the token-refresh manager and session monitor — they were continuing to hit Facebook endpoints after the bot was asked to stop
+- `api.isSessionValid` replaced the full homepage fetch (~400 kB) with a lightweight presence-ping endpoint, reducing bandwidth and detection surface
+- `startSessionMonitoring(api)` moved to after `api.isSessionValid` is registered in `loginHelper`, so the health-check interval can actually invoke it (previously it was called 70 lines before `api.isSessionValid` existed)
+- `setCredentials` now resets `retryCount = 0` on every fresh login, preventing 3 prior re-login failures from permanently locking out future re-logins for the process lifetime
+
+**Core**
+- Internal `listenMqtt` function now receives `emitAuthError` as a parameter at both call sites; previously both callers omitted it, causing a `ReferenceError` whenever an auth error arrived on the MQTT connection
+
+---
+
+## [1.0.0] - 2026-03-14
+
+Initial public release of **nkx-fca** — a full rewrite/rebranding of the FCA-KEX engine.  
+Developed and maintained by [NeoKEX](https://github.com/NeoKEX).
+
+### Added
+
+**Core**
+- Login via `appState` cookie arrays (supports `name/value`, `key/value`, and cookie strings)
+- Multi-persona support: `desktop` (Chrome/Edge) and `android/mobile` personas
+- Real-time MQTT messaging with `listenMqtt` and `sendMessageMqtt`
+- HTTP send with automatic MQTT fallback (`sendMessage`)
+- MQTT auto-reconnect with exponential backoff and jitter
+- MQTT watchdog timer to detect and recover from idle/stale connections
+- `TokenRefreshManager` with randomized refresh intervals to avoid detectable periodicity
+- `AutoReLogin` using refreshed AppState on session expiry
+- AppState backup/restore to disk to survive crashes
+- SQLite-backed thread and user data caching via Sequelize
+
+**Anti-Suspension System**
+- `AntiSuspension` class with circuit breaker — trips after repeated suspension signals
+- Expanded suspension signal detection: 60+ patterns covering checkpoints, spam flags, session expiry, rate limits, policy violations, identity verification, and more
+- Adaptive per-thread message delay that scales with session volume
+- Hourly and daily volume limits with automatic warning pauses
+- `checkVolumeLimit()` called before every `sendMessage` and `sendMessageMqtt` send
+- Warmup mode — reduced hourly limit for fresh sessions
+- Session fingerprint locking: User-Agent, Sec-Ch-Ua, locale, timezone locked per session
+- `safeRetry()` with suspension-aware exponential backoff
+- `batchOperations()` for safe, sequential multi-send workflows
+- MQTT Sec-Ch-Ua header updated to Chrome 136 (matching default User-Agent)
+- PostSafe guard on HTTP post to detect auth failures in real-time
+
+**API Methods**
+- `api.sendMessage(msg, threadID)` — HTTP send with MQTT fallback
+- `api.sendMessageMqtt(msg, threadID)` — MQTT send
+- `api.listenMqtt(callback)` — real-time event listener
+- `api.editMessage(text, messageID)` — in-place message edit
+- `api.unsendMessage(messageID, threadID)` — retract a message
+- `api.forwardMessage(messageID, threadID)` — forward a message
+- `api.deleteMessage(messageIDs)` — delete locally
+- `api.setMessageReaction(reaction, messageID)` — react via HTTP
+- `api.setMessageReactionMqtt(reaction, messageID, threadID)` — react via MQTT
+- `api.pinMessage(action, threadID, messageID?)` — pin/unpin/list pins
+- `api.sendTypingIndicator(isTyping, threadID)` — typing status
+- `api.markAsRead/markAsReadAll/markAsSeen/markAsDelivered` — message status
+- `api.getThreadInfo/getThreadList/getThreadHistory/getThreadPictures` — thread data
+- `api.getMessage(messageID)` — fetch a specific message
+- `api.getUserInfo/getUserInfoV2/getUserID` — user data
+- `api.getFriendsList/friend/unfriend` — friends management
+- `api.searchForThread(name)` — search threads by name
+- `api.createNewGroup/addUserToGroup/removeUserFromGroup/changeAdminStatus` — group admin
+- `api.changeGroupImage/changeThreadColor/changeThreadEmoji` — group customization
+- `api.gcname/emoji/nickname/theme` — per-thread personalization
+- `api.muteThread/changeArchivedStatus/deleteThread` — thread management
+- `api.createPoll` — create a poll in a thread
+- `api.handleMessageRequest` — accept/decline message requests
+- `api.changeBlockedStatus/changeAvatar/changeBio` — account actions
+- `api.comment/share/follow` — social interactions
+- `api.getTheme/getThemeInfo/setThreadTheme/setThreadThemeMqtt` — Messenger themes
+- `api.createAITheme(prompt)` — generate AI-powered chat themes
+- `api.stickers.search/listPacks/getStorePacks/addPack/getStickersInPack/getAiStickers` — sticker API
+- `api.e2ee.enable/disable/getPublicKey/setPeerKey/encrypt/decrypt` — application-layer E2EE (X25519 + HKDF + AES-256-GCM)
+- `api.getHealthStatus()` — MQTT, token refresh, and rate limiter telemetry
+- `api.httpGet/httpPost/httpPostFormData` — raw HTTP helpers
+- `api.addExternalModule(moduleObj)` — extend the API at runtime
+- `api.shareContact/resolvePhotoUrl/getAccess/logout/getAppState/getCurrentUserID`
+- `api.notes/gcrule/gcmember/story/realtime/getBotInfo/getBotInitialData/getUserInfoV2` — extended APIs
+
+**TypeScript Support**
+- Full `index.d.ts` with all methods, events, options, and types exported under `declare module "nkx-fca"`
+
+**Production Monitoring**
+- `ProductionMonitor` — request counts, error rates, response times, rate limit telemetry
+- `api.getHealthStatus()` providing MQTT, token refresh, and rate limiter stats
+
+### Fixed
+- Sec-Ch-Ua MQTT header aligned with Chrome 136 User-Agent (was Chrome 131)
+- `sendMessageMqtt` now calls `prepareBeforeMessage` before every send
+- `sendMessage` now calls `prepareBeforeMessage` before every send
+- Volume limit checks (`isDailyLimitReached`, `isHourlyLimitReached`) now apply to both send paths
+- TypeScript: removed duplicate `API` interface declaration and stray closing brace
+- Database path renamed from `fca_kex_database` to `nkx_fca_database`
+- Credits function updated to reference `nkx-fca` and `github.com/NeoKEX`
+
+---
+
+> **Developed and maintained by [NeoKEX](https://github.com/NeoKEX)**  
+> Inspired by **ws3-fca** and **@dongdev/fca-unofficial**

package/COOKIE_LOGIN.md

@@ -0,0 +1,208 @@
+# Login with Cookie Array
+
+**nkx-fca** supports multiple authentication methods. This guide explains how to login using a cookie array instead of email/password credentials.
+
+> **Credits:** Developed and maintained by [NeoKEX](https://github.com/NeoKEX)
+
+---
+
+## Quick Start
+
+```javascript
+const { login } = require('nkx-fca');
+
+const cookieArray = [
+    { name: 'c_user', value: 'YOUR_USER_ID' },
+    { name: 'xs', value: 'YOUR_SESSION_TOKEN' },
+    { name: 'fr', value: 'YOUR_FR_TOKEN' },
+    { name: 'datr', value: 'YOUR_DEVICE_TOKEN' }
+];
+
+login({ appState: cookieArray }, {}, (err, api) => {
+    if (err) return console.error('Login failed:', err);
+    console.log('Logged in as:', api.getCurrentUserID());
+});
+```
+
+---
+
+## Supported Cookie Formats
+
+### 1. Cookie Array with `name` property (Recommended)
+```javascript
+const appState = [
+    { name: 'c_user', value: '123456789' },
+    { name: 'xs', value: 'abc123...' },
+    // ... more cookies
+];
+
+login({ appState });
+```
+
+### 2. Cookie Array with `key` property
+```javascript
+const appState = [
+    { key: 'c_user', value: '123456789' },
+    { key: 'xs', value: 'abc123...' },
+];
+
+login({ appState });
+```
+
+### 3. Cookie String
+```javascript
+const cookieString = 'c_user=123456789; xs=abc123...; fr=xyz...; datr=...';
+
+login({ appState: cookieString });
+```
+
+---
+
+## Essential Cookies
+
+| Cookie | Purpose | Notes |
+|--------|---------|-------|
+| `c_user` | User ID | Your Facebook user ID |
+| `xs` | Session Token | Authentication token, required |
+| `fr` | Fraud Detection | Device/browser fingerprint |
+| `datr` | Device Token | Device identifier |
+
+---
+
+## How to Extract Cookies from Browser
+
+### Chrome / Firefox / Edge
+1. Navigate to `facebook.com` and log in normally
+2. Open Developer Tools — press **F12**
+3. Go to **Application** → **Cookies** → **facebook.com**
+4. Find and copy these cookies: `c_user`, `xs`, `fr`, `datr`
+
+### Export as Array (from browser console)
+```javascript
+copy(JSON.stringify(
+    document.cookie.split('; ').map(c => {
+        const [name, ...rest] = c.split('=');
+        return { name, value: rest.join('=') };
+    })
+))
+```
+
+### Using a Browser Extension
+- **Chrome/Edge:** "C3C FbState" or "CookieEditor"
+- **Firefox:** "Cookie-Editor"
+
+Export the cookies as JSON and save as `appstate.json`.
+
+---
+
+## Complete Example
+
+```javascript
+const fs = require('fs');
+const { login } = require('nkx-fca');
+
+const appState = JSON.parse(fs.readFileSync('appstate.json', 'utf8'));
+
+login({ appState }, {
+    online: true,
+    listenEvents: true,
+    autoMarkRead: true,
+    autoReconnect: true,
+    simulateTyping: true
+}, (err, api) => {
+    if (err) return console.error('Login failed:', err);
+
+    console.log('Logged in as:', api.getCurrentUserID());
+
+    api.listenMqtt((err, event) => {
+        if (err || event.type !== 'message') return;
+        console.log(`[${event.threadID}] ${event.senderID}: ${event.body}`);
+    });
+});
+```
+
+---
+
+## Cookie Refresh
+
+Facebook cookies may expire after hours or days. If login fails:
+1. Log in to Facebook in your browser
+2. Export fresh cookies using a browser extension
+3. Replace your `appstate.json` with the new cookies
+4. Restart your bot
+
+---
+
+## Security Notes
+
+- **Never commit `appstate.json` to version control**
+- **Never share your cookies publicly**
+- Store cookies in environment variables or secure files (`.env`, secrets manager)
+- Rotate cookies periodically for long-running bots
+- Each cookie set is tied to a specific browser/device session — do not reuse across machines
+
+---
+
+## Troubleshooting
+
+### Login Fails with Cookie Array
+- Ensure `c_user` and `xs` cookies are present
+- Check if the cookies are expired — extract fresh ones from your browser
+- Verify cookie format: array of objects with `name` and `value` (or `key` and `value`)
+- Make sure you are using cookies from a logged-in Facebook session
+
+### Cookies Expire Quickly
+- Facebook cookies expire faster when used from a new IP or User-Agent
+- Use a consistent residential proxy to extend cookie life
+- Avoid switching network locations frequently
+
+### Account Suspended / Checkpoint
+- Stop all bot activity immediately
+- Complete any Facebook security check in your browser
+- Wait at least 24–48 hours before resuming
+- Reduce message frequency and enable warmup mode on restart
+
+---
+
+## Alternative: Email/Password Login
+
+> Email/password login is not recommended for bots — it triggers stricter security checks.
+
+```javascript
+login({
+    email: 'your-email@example.com',
+    password: 'your-password'
+}, {}, (err, api) => {
+    if (err) return console.error(err);
+    console.log('Logged in:', api.getCurrentUserID());
+});
+```
+
+---
+
+## AppState Backup
+
+**nkx-fca** automatically saves and restores your session state internally.  
+To manually save the current session after login:
+
+```javascript
+const fs = require('fs');
+
+login({ appState }, {}, (err, api) => {
+    if (err) return;
+    // Save refreshed appState
+    fs.writeFileSync('appstate.json', JSON.stringify(api.getAppState(), null, 2));
+});
+```
+
+---
+
+## See Also
+- [README.md](./README.md) — Full feature overview
+- [examples/](./examples/) — Working code examples
+- [CHANGELOG.md](./CHANGELOG.md) — Version history
+
+---
+
+> **Credits:** nkx-fca is developed and maintained by [NeoKEX](https://github.com/NeoKEX).  
+> Inspired by **ws3-fca** and **@dongdev/fca-unofficial**

package/LICENSE

@@ -0,0 +1,3 @@
+All rights reserved to NeoKEX(github.com/NeoKEX)
+❌ PLEASE DO NOT STOLE MY SOURCE CODES AND CLAIM AS YOURS
+Thanks for supporting ^_^