@dongdev/fca-unofficial 3.0.28 → 3.0.30

package/CHANGELOG.md

@@ -1,196 +1,293 @@
 # Changelog
-Too lazy to write changelog, sorry! (will write changelog in the next release, through.)
-## v1.0.10 - 2025-04-24
-- Hotfix / auto bump
 
-## v1.0.11 - 2025-04-24
-- Hotfix / auto bump
+All notable changes to this project are documented in this file.
 
-## v1.0.12 - 2025-04-28
-- Hotfix / auto bump
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) where applicable.
 
-## v1.0.13 - 2025-04-28
-- Hotfix / auto bump
+---
 
-## v1.0.14 - 2025-04-28
-- Hotfix / auto bump
+## [3.0.29] - 2026-02-22
 
-## v1.0.15 - 2025-05-03
-- Hotfix / auto bump
+- Maintenance release (hotfix / version bump).
 
-## v1.0.16 - 2025-05-07
-- Hotfix / auto bump
+## [3.0.30] - 2026-02-26
 
-## v1.0.17 - 2025-05-07
-- Hotfix / auto bump
+- **Security & supply chain**
+  - Removed legacy/self-dependency and old HTTP stack (`request`, `sqlite3`, `npmlog`), pinned `axios` to a secure version, and cleaned up `npm audit` findings (no Critical/High CVEs in runtime deps).
+  - Added `SECURITY.md`, restricted the published files via `package.json.files` (no Horizon refs, no bundled node_modules) and wired `npm publish --provenance` into CI for verifiable builds.
+- **Event-driven core**
+  - Promoted the `api` object to an `EventEmitter` with lifecycle events: `sessionExpired`, `autoLoginSuccess`, `autoLoginFailed`, `checkpoint`/`checkpoint_282`/`checkpoint_956`, `loginBlocked`, `rateLimit`, `networkError`.
+  - Hooked these into `loginParser` and the HTTP layer so consumers can react to login, checkpoint, and network conditions without brittle error-string matching.
+- **Thread/User info & DB-backed anti-get-info**
+  - Refactored `getThreadInfo` and `getUserInfo` to use GraphQL batch calls with optional SQLite caching (via Sequelize models), reducing repeated Facebook requests and aligning with Horizon-style anti-get-info behavior.
+  - Added configuration toggles in `fca-config.json` (`antiGetInfo.AntiGetThreadInfo`, `antiGetInfo.AntiGetUserInfo`) to switch between DB-backed and legacy behaviors when needed.
+- **Remote control & analytics**
+  - Introduced a lightweight WebSocket **remote control client** (`src/remote/remoteClient.js`) driven by `remoteControl` config, emitting `remoteConnected`, `remoteDisconnected`, `remoteStop`, `remoteBroadcast`, and `remoteMessage` events for integration with external dashboards.
+  - Taught the MQTT layer to update per-thread statistics in SQLite via an atomic `Thread.increment("messageCount")` on each message, enabling future analytics (e.g. “most active threads”) without impacting message latency.
+- **Docs & utilities**
+  - Updated `README.md`, `DOCS.md`, and `docs/ARCHITECTURE.md` to document the new event system, DB caching behavior, remote control, proxy configuration, and the optional `broadcast` helper.
 
-## v1.0.18 - 2025-05-22
-- Hotfix / auto bump
+## [3.0.28] - 2026-02-22
 
-## v1.0.19 - 2025-05-23
-- Hotfix / auto bump
+- Maintenance release (hotfix / version bump).
 
-## v2.0.0 - 2025-10-05
-- Hotfix / auto bump
+## [3.0.27] - 2026-02-22
 
-## v2.0.1 - 2025-10-05
-- Hotfix / auto bump
+- Maintenance release (hotfix / version bump).
 
-## v2.0.2 - 2025-10-05
-- Hotfix / auto bump
+## [3.0.25] - 2026-02-05
 
-## v2.0.3 - 2025-10-05
-- Hotfix / auto bump
+- Maintenance release (hotfix / version bump).
 
-## v2.0.4 - 2025-10-05
-- Hotfix / auto bump
+## [3.0.23] - 2026-01-30
 
-## v2.0.5 - 2025-10-06
-- Now you can turn on/off autoLogin in config file.
-- Added autoUpdate feature.
-## v2.0.6-beta - 2025-10-06
-- Hotfix / auto bump
+- Maintenance release (hotfix / version bump).
 
-## v2.0.7 - 2025-10-06
-- Hotfix / auto bump
+## [3.0.22] - 2026-01-07
 
-## v2.0.8 - 2025-10-07
-- Hotfix / auto bump
+- Maintenance release (hotfix / version bump).
 
-## v2.0.9 - 2025-10-07
-- Hotfix / auto bump
+## [3.0.21] - 2025-12-31
 
-## v2.0.9 - 2025-10-07
-- Hotfix / auto bump
+- Maintenance release (hotfix / version bump).
 
-## v2.0.10 - 2025-10-07
-- Hotfix / auto bump
+## [3.0.20] - 2025-12-31
 
-## v2.0.10 - 2025-10-07
-- Hotfix / auto bump
+- Maintenance release (hotfix / version bump).
 
-## v2.0.11 - 2025-10-07
-- Hotfix / auto bump
+## [3.0.19] - 2025-12-31
 
-## v2.0.12 - 2025-10-07
-- Hotfix / auto bump
+- Maintenance release (hotfix / version bump).
 
-## v2.0.13 - 2025-10-07
-- Hotfix / auto bump
+## [3.0.17] - 2025-12-16
 
-## v2.0.14 - 2025-10-07
-- Hotfix / auto bump
+- Maintenance release (hotfix / version bump).
 
-## v2.0.15 - 2025-10-07
-- Hotfix / auto bump
+## [3.0.15] - 2025-12-12
 
-## v2.0.16 - 2025-10-07
-- Hotfix / auto bump
+- Maintenance release (hotfix / version bump).
 
-## v2.0.17 - 2025-10-07
-- Hotfix / auto bump
+## [3.0.12] - 2025-12-05
 
-## v2.0.18 - 2025-10-07
-- Hotfix / auto bump
+- Maintenance release (hotfix / version bump).
 
-## v2.0.19 - 2025-10-07
-- Hotfix / auto bump
+## [3.0.11] - 2025-12-05
 
-## v2.0.20 - 2025-10-08
-- Hotfix / auto bump
+- Maintenance release (hotfix / version bump).
 
-## v2.0.21 - 2025-10-08
-- Hotfix / auto bump
+## [3.0.10] - 2025-12-05
 
-## v2.0.22 - 2025-10-09
-- Hotfix / auto bump
+- Maintenance release (hotfix / version bump).
 
-## v2.0.23 - 2025-10-11
-- Hotfix / auto bump
+## [3.0.9] - 2025-12-05
 
-## v2.0.24 - 2025-10-11
-- Hotfix / auto bump
+- Maintenance release (hotfix / version bump).
 
-## v2.0.25 - 2025-10-12
-- Hotfix / auto bump
+## [3.0.8] - 2025-11-27
 
-## v2.0.26 - 2025-10-16
-- Hotfix / auto bump
+- Maintenance release (hotfix / version bump).
 
-## v2.0.27 - 2025-10-18
-- Hotfix / auto bump
+## [3.0.7] - 2025-11-27
 
-## v2.0.28 - 2025-10-18
-- Hotfix / auto bump
+- Maintenance release (hotfix / version bump).
 
-## v2.0.29 - 2025-10-19
-- Hotfix / auto bump
+## [3.0.6] - 2025-11-27
 
-## v2.0.30 - 2025-10-19
-- Hotfix / auto bump
+- Maintenance release (hotfix / version bump).
 
-## v2.0.31 - 2025-10-27
-- Hotfix / auto bump
+## [3.0.5] - 2025-11-27
 
-## v2.0.32 - 2025-10-30
-- Hotfix / auto bump
+- Maintenance release (hotfix / version bump).
 
-## v3.0.2 - 2025-11-27
-- Hotfix / auto bump
+## [3.0.4] - 2025-11-27
 
-## v3.0.3 - 2025-11-27
-- Hotfix / auto bump
+- Maintenance release (hotfix / version bump).
 
-## v3.0.4 - 2025-11-27
-- Hotfix / auto bump
+## [3.0.3] - 2025-11-27
 
-## v3.0.5 - 2025-11-27
-- Hotfix / auto bump
+- Maintenance release (hotfix / version bump).
 
-## v3.0.6 - 2025-11-27
-- Hotfix / auto bump
+## [3.0.2] - 2025-11-27
 
-## v3.0.7 - 2025-11-27
-- Hotfix / auto bump
+- Maintenance release (hotfix / version bump).
 
-## v3.0.8 - 2025-11-27
-- Hotfix / auto bump
+## [2.0.32] - 2025-10-30
 
-## v3.0.9 - 2025-12-05
-- Hotfix / auto bump
+- Maintenance release (hotfix / version bump).
 
-## v3.0.10 - 2025-12-05
-- Hotfix / auto bump
+## [2.0.31] - 2025-10-27
 
-## v3.0.11 - 2025-12-05
-- Hotfix / auto bump
+- Maintenance release (hotfix / version bump).
 
-## v3.0.12 - 2025-12-05
-- Hotfix / auto bump
+## [2.0.30] - 2025-10-19
 
-## v3.0.15 - 2025-12-12
-- Hotfix / auto bump
+- Maintenance release (hotfix / version bump).
 
-## v3.0.17 - 2025-12-16
-- Hotfix / auto bump
+## [2.0.29] - 2025-10-19
 
-## v3.0.19 - 2025-12-31
-- Hotfix / auto bump
+- Maintenance release (hotfix / version bump).
 
-## v3.0.20 - 2025-12-31
-- Hotfix / auto bump
+## [2.0.28] - 2025-10-18
 
-## v3.0.21 - 2025-12-31
-- Hotfix / auto bump
+- Maintenance release (hotfix / version bump).
 
-## v3.0.22 - 2026-01-07
-- Hotfix / auto bump
+## [2.0.27] - 2025-10-18
 
-## v3.0.23 - 2026-01-30
-- Hotfix / auto bump
+- Maintenance release (hotfix / version bump).
 
-## v3.0.25 - 2026-02-05
-- Hotfix / auto bump
+## [2.0.26] - 2025-10-16
 
-## v3.0.27 - 2026-02-22
-- Hotfix / auto bump
+- Maintenance release (hotfix / version bump).
+
+## [2.0.25] - 2025-10-12
+
+- Maintenance release (hotfix / version bump).
+
+## [2.0.24] - 2025-10-11
+
+- Maintenance release (hotfix / version bump).
+
+## [2.0.23] - 2025-10-11
+
+- Maintenance release (hotfix / version bump).
+
+## [2.0.22] - 2025-10-09
+
+- Maintenance release (hotfix / version bump).
+
+## [2.0.21] - 2025-10-08
+
+- Maintenance release (hotfix / version bump).
+
+## [2.0.20] - 2025-10-08
+
+- **Added:** Config option to enable/disable `autoLogin`.
+- **Added:** Auto-update feature (configurable).
+
+## [2.0.19] - 2025-10-07
+
+- Maintenance release (hotfix / version bump).
+
+## [2.0.18] - 2025-10-07
+
+- Maintenance release (hotfix / version bump).
+
+## [2.0.17] - 2025-10-07
+
+- Maintenance release (hotfix / version bump).
+
+## [2.0.16] - 2025-10-07
+
+- Maintenance release (hotfix / version bump).
+
+## [2.0.15] - 2025-10-07
+
+- Maintenance release (hotfix / version bump).
+
+## [2.0.14] - 2025-10-07
+
+- Maintenance release (hotfix / version bump).
+
+## [2.0.13] - 2025-10-07
+
+- Maintenance release (hotfix / version bump).
+
+## [2.0.12] - 2025-10-07
+
+- Maintenance release (hotfix / version bump).
+
+## [2.0.11] - 2025-10-07
+
+- Maintenance release (hotfix / version bump).
+
+## [2.0.10] - 2025-10-07
+
+- Maintenance release (hotfix / version bump).
+
+## [2.0.9] - 2025-10-07
+
+- Maintenance release (hotfix / version bump).
+
+## [2.0.8] - 2025-10-07
+
+- Maintenance release (hotfix / version bump).
+
+## [2.0.7] - 2025-10-06
+
+- Maintenance release (hotfix / version bump).
+
+## [2.0.6-beta] - 2025-10-06
+
+- Beta release (hotfix / version bump).
+
+## [2.0.5] - 2025-10-06
+
+- **Added:** Toggle for `autoLogin` in config.
+- **Added:** Auto-update feature.
+
+## [2.0.4] - 2025-10-05
+
+- Maintenance release (hotfix / version bump).
+
+## [2.0.3] - 2025-10-05
+
+- Maintenance release (hotfix / version bump).
+
+## [2.0.2] - 2025-10-05
+
+- Maintenance release (hotfix / version bump).
+
+## [2.0.1] - 2025-10-05
+
+- Maintenance release (hotfix / version bump).
+
+## [2.0.0] - 2025-10-05
+
+- Major version bump (hotfix / version bump).
+
+## [1.0.19] - 2025-05-23
+
+- Maintenance release (hotfix / version bump).
+
+## [1.0.18] - 2025-05-22
+
+- Maintenance release (hotfix / version bump).
+
+## [1.0.17] - 2025-05-07
+
+- Maintenance release (hotfix / version bump).
+
+## [1.0.16] - 2025-05-07
+
+- Maintenance release (hotfix / version bump).
+
+## [1.0.15] - 2025-05-03
+
+- Maintenance release (hotfix / version bump).
+
+## [1.0.14] - 2025-04-28
+
+- Maintenance release (hotfix / version bump).
+
+## [1.0.13] - 2025-04-28
+
+- Maintenance release (hotfix / version bump).
+
+## [1.0.12] - 2025-04-28
+
+- Maintenance release (hotfix / version bump).
+
+## [1.0.11] - 2025-04-24
+
+- Maintenance release (hotfix / version bump).
+
+## [1.0.10] - 2025-04-24
+
+- Maintenance release (hotfix / version bump).
+
+---
+
+[3.0.29]: https://github.com/Donix-VN/fca-unofficial/compare/v3.0.28...v3.0.29
+[3.0.28]: https://github.com/Donix-VN/fca-unofficial/compare/v3.0.27...v3.0.28
+[3.0.27]: https://github.com/Donix-VN/fca-unofficial/compare/v3.0.25...v3.0.27
+[1.0.10]: https://github.com/Donix-VN/fca-unofficial/releases/tag/v1.0.10

package/DOCS.md

@@ -1,8 +1,24 @@
-# FCA-Unofficial - Complete API Documentation
+# FCA-Unofficial — API Documentation
 
 ## Introduction
 
-**@dongdev/fca-unofficial** is an unofficial Node.js library for interacting with Facebook Messenger by emulating browser behavior. This library allows you to create chat bots and automate tasks on Facebook Messenger.
+**@dongdev/fca-unofficial** is an unofficial Node.js library for interacting with Facebook Messenger by emulating browser behavior. It lets you build chatbots and automate messaging on personal Facebook accounts (not just Pages).
+
+## Project structure
+
+| Path | Description |
+|------|--------------|
+| `index.js` | Package entry point; exports `login`. |
+| `index.d.ts` | TypeScript definitions for the public API. |
+| `module/` | Login flow: `login.js`, `loginHelper.js`, `config.js`, `options.js`. |
+| `src/api/` | API implementations: `messaging/`, `threads/`, `users/`, `action/`, `http/`, `socket/`. |
+| `src/api/socket/` | MQTT/WebSocket real-time listening (`listenMqtt.js`, `core/`, `middleware/`). |
+| `src/utils/` | Shared utilities: `request.js`, `client.js`, `format.js`, `headers.js`, `cookies.js`, `broadcast.js` (optional helper). |
+| `src/database/` | Optional Sequelize models and data access for threads/users (used for caching and statistics). |
+| `src/remote/` | Lightweight WebSocket client for remote control (dashboard/server). |
+| `func/` | Logger, check-update, and other helpers. |
+
+For a concise codebase overview, see [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md).
 
 ## Installation
 
@@ -123,12 +139,46 @@ login(credentials, (err, api) => {
 });
 ```
 
-**Note:** You can use [c3c-fbstate](https://github.com/c3cbot/c3c-fbstate) tool to get AppState from browser.
+You can use the [c3c-fbstate](https://github.com/c3cbot/c3c-fbstate) tool to obtain AppState from your browser.
+
+### 1.4. Auto Login (session recovery)
+
+When the session (AppState) expires, the library can automatically re-login using credentials from **`fca-config.json`**, so the bot can recover without manual restart.
+
+1. Create **`fca-config.json`** in your project root (the directory from which you run your bot):
+
+```json
+{
+  "autoLogin": true,
+  "apiServer": "https://minhdong.site",
+  "apiKey": "",
+  "credentials": {
+    "email": "your_email_or_phone",
+    "password": "your_password",
+    "twofactor": ""
+  }
+}
+```
+
+2. Log in with AppState as usual. When the session expires, the library will use these credentials (and optionally the external API at `apiServer`) to log in again and retry the failed request.
+
+| Option | Description |
+|--------|-------------|
+| `autoLogin` | `true` (default) or `false`. Set to `false` to disable automatic re-login when session expires. |
+| `apiServer` | Base URL for external login API (e.g. iOS-style login). Default: `https://minhdong.site`. |
+| `apiKey` | Optional API key for the external login server (e.g. `x-api-key` header). |
+| `credentials.email` | Facebook email or phone number. |
+| `credentials.password` | Facebook password. |
+| `credentials.twofactor` | Base32 secret for 2FA (TOTP). Leave empty if you do not use 2FA. Do not put the 6-digit code here. |
+
+**Security:** Add `fca-config.json` to `.gitignore`; it contains sensitive credentials.
 
 ---
 
 ## 2. CONFIGURATION (Options)
 
+### 2.1. Runtime options (api.setOptions)
+
 After login, you can configure API options:
 
 ```javascript
@@ -153,6 +203,21 @@ api.setOptions({
 });
 ```
 
+### 2.2. File config (fca-config.json)
+
+Optional config file in the project root (see [§ 1.4. Auto Login](#14-auto-login-session-recovery)):
+
+| Key | Description |
+|-----|-------------|
+| `autoLogin` | Enable/disable automatic re-login when session expires (default: `true`). |
+| `autoUpdate` | Check for package updates on startup (default: `true`). |
+| `mqtt` | `{ enabled, reconnectInterval }` for MQTT. |
+| `apiServer` | Base URL for external login API (default: `https://minhdong.site`). |
+| `apiKey` | Optional API key for the login server. |
+| `credentials` | `{ email, password, twofactor }` for auto-login and external API login. |
+| `antiGetInfo` | `{ AntiGetThreadInfo, AntiGetUserInfo }` switches between DB-backed anti-get-info and legacy behavior. |
+| `remoteControl` | `{ enabled, url, token, autoReconnect }` enables remote control over WebSocket. |
+
 ---
 
 ## 3. DETAILED API METHODS
@@ -634,6 +699,14 @@ api.getUserInfo(["100012345678901", "100012345678902"], (err, userInfo) => {
 });
 ```
 
+#### Caching and Anti-Get-Info
+
+- `getUserInfo` uses GraphQL to fetch profiles and stores normalized data in the `User` table (see `src/database/userData.js`).
+- On each call:
+  - The library first checks the DB for existing entries.
+  - Missing or stale entries are fetched from Facebook and persisted back to SQLite.
+- If `antiGetInfo.AntiGetUserInfo` is set to `true` in `fca-config.json`, the implementation falls back to the legacy `/chat/user_info/` endpoint and logs a Horizon-style warning when spam/limits are detected.
+
 ---
 
 ### 3.4. Message Scheduler - Schedule Messages
@@ -925,6 +998,12 @@ api.getThreadInfo("1234567890", (err, threadInfo) => {
 });
 ```
 
+#### Caching and Anti-Get-Info
+
+- `getThreadInfo` uses a GraphQL batch endpoint and caches responses in the `Thread` table (see `src/database/threadData.js`).
+- Subsequent calls within a short time window may be served from SQLite to reduce pressure on Facebook endpoints.
+- When Facebook signals spam/limits, a Horizon-style warning is logged and the error is surfaced to your callback/Promise.
+
 ---
 
 ### 3.5. changeThreadColor - Change Chat Color