sagor-fca 0.0.5 → 0.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (234) hide show
  1. package/README.md +223 -20
  2. package/examples/login-with-cookies.js +38 -0
  3. package/examples/ping.js +36 -0
  4. package/examples/verify.js +69 -0
  5. package/index.js +2 -10
  6. package/package.json +68 -57
  7. package/src/api/{action/addExternalModule.js → addExternalModule.js} +8 -9
  8. package/src/api/addUserToGroup.js +108 -0
  9. package/src/api/changeAdminStatus.js +148 -0
  10. package/src/api/changeArchivedStatus.js +61 -0
  11. package/src/api/changeAvatar.js +103 -0
  12. package/src/api/changeBio.js +69 -0
  13. package/src/api/changeBlockedStatus.js +54 -0
  14. package/src/api/changeGroupImage.js +136 -0
  15. package/src/api/changeThreadColor.js +116 -0
  16. package/src/api/changeThreadEmoji.js +53 -0
  17. package/src/api/comment.js +207 -0
  18. package/src/api/createAITheme.js +129 -0
  19. package/src/api/createNewGroup.js +79 -0
  20. package/src/api/createPoll.js +73 -0
  21. package/src/api/deleteMessage.js +44 -0
  22. package/src/api/deleteThread.js +52 -0
  23. package/src/api/e2ee.js +17 -0
  24. package/src/api/editMessage.js +70 -0
  25. package/src/api/emoji.js +124 -0
  26. package/src/api/fetchThemeData.js +82 -0
  27. package/src/api/follow.js +81 -0
  28. package/src/api/forwardMessage.js +52 -0
  29. package/src/api/friend.js +243 -0
  30. package/src/api/gcmember.js +122 -0
  31. package/src/api/gcname.js +123 -0
  32. package/src/api/gcrule.js +119 -0
  33. package/src/api/getAccess.js +111 -0
  34. package/src/api/getBotInfo.js +88 -0
  35. package/src/api/getBotInitialData.js +43 -0
  36. package/src/api/getFriendsList.js +79 -0
  37. package/src/api/getMessage.js +423 -0
  38. package/src/api/getTheme.js +95 -0
  39. package/src/api/getThemeInfo.js +116 -0
  40. package/src/api/getThreadHistory.js +239 -0
  41. package/src/api/getThreadInfo.js +267 -0
  42. package/src/api/getThreadList.js +232 -0
  43. package/src/api/getThreadPictures.js +58 -0
  44. package/src/api/getUserID.js +117 -0
  45. package/src/api/getUserInfo.js +513 -0
  46. package/src/api/{users/getUserInfoV2.js → getUserInfoV2.js} +26 -14
  47. package/src/api/handleMessageRequest.js +50 -0
  48. package/src/api/httpGet.js +63 -0
  49. package/src/api/httpPost.js +89 -0
  50. package/src/api/httpPostFormData.js +69 -0
  51. package/src/api/listenMqtt.js +892 -0
  52. package/src/api/listenSpeed.js +179 -0
  53. package/src/api/logout.js +63 -0
  54. package/src/api/markAsDelivered.js +47 -0
  55. package/src/api/{messaging/markAsRead.js → markAsRead.js} +26 -19
  56. package/src/api/markAsReadAll.js +40 -0
  57. package/src/api/markAsSeen.js +70 -0
  58. package/src/api/mqttDeltaValue.js +278 -0
  59. package/src/api/muteThread.js +45 -0
  60. package/src/api/nickname.js +132 -0
  61. package/src/api/notes.js +163 -0
  62. package/src/api/pinMessage.js +150 -0
  63. package/src/api/produceMetaTheme.js +180 -0
  64. package/src/api/realtime.js +182 -0
  65. package/src/api/removeUserFromGroup.js +117 -0
  66. package/src/api/resolvePhotoUrl.js +58 -0
  67. package/src/api/searchForThread.js +154 -0
  68. package/src/api/sendMessage.js +354 -0
  69. package/src/api/sendMessageMqtt.js +249 -0
  70. package/src/api/sendTypingIndicator.js +48 -0
  71. package/src/api/setMessageReaction.js +27 -0
  72. package/src/api/setMessageReactionMqtt.js +61 -0
  73. package/src/api/setThreadTheme.js +260 -0
  74. package/src/api/setThreadThemeMqtt.js +94 -0
  75. package/src/api/share.js +107 -0
  76. package/src/api/shareContact.js +66 -0
  77. package/src/api/stickers.js +257 -0
  78. package/src/api/story.js +181 -0
  79. package/src/api/theme.js +233 -0
  80. package/src/api/unfriend.js +47 -0
  81. package/src/api/unsendMessage.js +17 -0
  82. package/src/database/appStateBackup.js +189 -0
  83. package/src/database/models/index.js +44 -76
  84. package/src/database/models/thread.js +3 -22
  85. package/src/database/models/user.js +3 -17
  86. package/src/database/threadData.js +53 -46
  87. package/src/database/userData.js +38 -46
  88. package/src/engine/client.js +92 -0
  89. package/src/engine/models/buildAPI.js +113 -0
  90. package/src/engine/models/loginHelper.js +487 -0
  91. package/src/engine/models/setOptions.js +88 -0
  92. package/src/security/e2ee.js +109 -0
  93. package/src/types/index.d.ts +498 -0
  94. package/src/utils/antiSuspension.js +516 -0
  95. package/src/utils/auth-helpers.js +149 -0
  96. package/src/utils/autoReLogin.js +233 -0
  97. package/src/utils/axios.js +368 -0
  98. package/src/utils/cache.js +54 -0
  99. package/src/utils/clients.js +279 -0
  100. package/src/utils/constants.js +401 -15
  101. package/src/utils/formatters/data/formatAttachment.js +370 -0
  102. package/src/utils/formatters/data/formatDelta.js +109 -0
  103. package/src/utils/formatters/index.js +159 -0
  104. package/src/utils/formatters/value/formatCookie.js +91 -0
  105. package/src/utils/formatters/value/formatDate.js +36 -0
  106. package/src/utils/formatters/value/formatID.js +16 -0
  107. package/src/utils/formatters.js +1369 -0
  108. package/src/utils/headers.js +221 -77
  109. package/src/utils/index.js +153 -0
  110. package/src/utils/monitoring.js +333 -0
  111. package/src/utils/rateLimiter.js +251 -0
  112. package/src/utils/tokenRefresh.js +291 -0
  113. package/src/utils/user-agents.js +238 -0
  114. package/src/utils/validation.js +157 -0
  115. package/func/checkUpdate.js +0 -16
  116. package/func/logAdapter.js +0 -33
  117. package/func/logger.js +0 -48
  118. package/func/utils.js +0 -5
  119. package/index.d.ts +0 -751
  120. package/module/config.js +0 -40
  121. package/module/login.js +0 -134
  122. package/module/loginHelper.js +0 -1296
  123. package/module/options.js +0 -48
  124. package/src/api/action/changeAvatar.js +0 -137
  125. package/src/api/action/changeBio.js +0 -75
  126. package/src/api/action/enableAutoSaveAppState.js +0 -73
  127. package/src/api/action/getCurrentUserID.js +0 -7
  128. package/src/api/action/handleFriendRequest.js +0 -57
  129. package/src/api/action/logout.js +0 -76
  130. package/src/api/action/refreshFb_dtsg.js +0 -48
  131. package/src/api/action/setPostReaction.js +0 -106
  132. package/src/api/action/unfriend.js +0 -54
  133. package/src/api/groups/getGroupJoinRequests.js +0 -0
  134. package/src/api/groups/handleGroupJoinRequest.js +0 -0
  135. package/src/api/http/httpGet.js +0 -46
  136. package/src/api/http/httpPost.js +0 -52
  137. package/src/api/http/postFormData.js +0 -47
  138. package/src/api/live/getLiveStreamInfo.js +0 -35
  139. package/src/api/live/reactLiveStream.js +0 -31
  140. package/src/api/marketplace/getMarketplaceItemDetail.js +0 -35
  141. package/src/api/marketplace/getMarketplaceItems.js +0 -30
  142. package/src/api/messaging/addUserToGroup.js +0 -68
  143. package/src/api/messaging/changeAdminStatus.js +0 -126
  144. package/src/api/messaging/changeArchivedStatus.js +0 -55
  145. package/src/api/messaging/changeBlockedStatus.js +0 -48
  146. package/src/api/messaging/changeGroupImage.js +0 -91
  147. package/src/api/messaging/changeNickname.js +0 -70
  148. package/src/api/messaging/changeThreadColor.js +0 -79
  149. package/src/api/messaging/changeThreadEmoji.js +0 -111
  150. package/src/api/messaging/createNewGroup.js +0 -88
  151. package/src/api/messaging/createPoll.js +0 -46
  152. package/src/api/messaging/createThemeAI.js +0 -98
  153. package/src/api/messaging/deleteMessage.js +0 -136
  154. package/src/api/messaging/deleteThread.js +0 -56
  155. package/src/api/messaging/editMessage.js +0 -68
  156. package/src/api/messaging/forwardAttachment.js +0 -57
  157. package/src/api/messaging/getEmojiUrl.js +0 -29
  158. package/src/api/messaging/getFriendsList.js +0 -82
  159. package/src/api/messaging/getMessage.js +0 -829
  160. package/src/api/messaging/getThemePictures.js +0 -62
  161. package/src/api/messaging/handleMessageRequest.js +0 -65
  162. package/src/api/messaging/markAsDelivered.js +0 -57
  163. package/src/api/messaging/markAsReadAll.js +0 -49
  164. package/src/api/messaging/markAsSeen.js +0 -61
  165. package/src/api/messaging/muteThread.js +0 -50
  166. package/src/api/messaging/removeUserFromGroup.js +0 -62
  167. package/src/api/messaging/resolvePhotoUrl.js +0 -43
  168. package/src/api/messaging/scheduler.js +0 -264
  169. package/src/api/messaging/searchForThread.js +0 -53
  170. package/src/api/messaging/sendMessage.js +0 -270
  171. package/src/api/messaging/sendTypingIndicator.js +0 -74
  172. package/src/api/messaging/sendVoiceMessage.js +0 -0
  173. package/src/api/messaging/setMessageReaction.js +0 -90
  174. package/src/api/messaging/setTitle.js +0 -124
  175. package/src/api/messaging/shareContact.js +0 -49
  176. package/src/api/messaging/threadColors.js +0 -128
  177. package/src/api/messaging/unsendMessage.js +0 -81
  178. package/src/api/messaging/uploadAttachment.js +0 -492
  179. package/src/api/privacy/getPrivacySettings.js +0 -32
  180. package/src/api/privacy/setPrivacySettings.js +0 -31
  181. package/src/api/professional/getProfessionalInfo.js +0 -35
  182. package/src/api/professional/toggleProfessionalMode.js +0 -31
  183. package/src/api/reels/getReels.js +0 -30
  184. package/src/api/reels/reactReel.js +0 -31
  185. package/src/api/socket/core/connectMqtt.js +0 -259
  186. package/src/api/socket/core/emitAuth.js +0 -103
  187. package/src/api/socket/core/getSeqID.js +0 -320
  188. package/src/api/socket/core/getTaskResponseData.js +0 -25
  189. package/src/api/socket/core/parseDelta.js +0 -377
  190. package/src/api/socket/detail/buildStream.js +0 -215
  191. package/src/api/socket/detail/constants.js +0 -28
  192. package/src/api/socket/listenMqtt.js +0 -377
  193. package/src/api/socket/middleware/index.js +0 -216
  194. package/src/api/threads/getThreadHistory.js +0 -664
  195. package/src/api/threads/getThreadInfo.js +0 -296
  196. package/src/api/threads/getThreadList.js +0 -293
  197. package/src/api/threads/getThreadPictures.js +0 -78
  198. package/src/api/users/getUserID.js +0 -74
  199. package/src/api/users/getUserInfo.js +0 -402
  200. package/src/core/sendReqMqtt.js +0 -96
  201. package/src/database/helpers.js +0 -53
  202. package/src/remote/remoteClient.js +0 -123
  203. package/src/utils/broadcast.js +0 -51
  204. package/src/utils/client.js +0 -10
  205. package/src/utils/cookies.js +0 -68
  206. package/src/utils/format/attachment.js +0 -357
  207. package/src/utils/format/cookie.js +0 -9
  208. package/src/utils/format/date.js +0 -50
  209. package/src/utils/format/decode.js +0 -44
  210. package/src/utils/format/delta.js +0 -194
  211. package/src/utils/format/ids.js +0 -64
  212. package/src/utils/format/index.js +0 -64
  213. package/src/utils/format/message.js +0 -88
  214. package/src/utils/format/presence.js +0 -132
  215. package/src/utils/format/readTyp.js +0 -44
  216. package/src/utils/format/thread.js +0 -42
  217. package/src/utils/format/utils.js +0 -141
  218. package/src/utils/loginParser/autoLogin.js +0 -125
  219. package/src/utils/loginParser/helpers.js +0 -43
  220. package/src/utils/loginParser/index.js +0 -10
  221. package/src/utils/loginParser/parseAndCheckLogin.js +0 -220
  222. package/src/utils/loginParser/textUtils.js +0 -28
  223. package/src/utils/request/client.js +0 -26
  224. package/src/utils/request/config.js +0 -24
  225. package/src/utils/request/defaults.js +0 -46
  226. package/src/utils/request/helpers.js +0 -46
  227. package/src/utils/request/index.js +0 -17
  228. package/src/utils/request/methods.js +0 -174
  229. package/src/utils/request/proxy.js +0 -21
  230. package/src/utils/request/retry.js +0 -77
  231. package/src/utils/request/sanitize.js +0 -49
  232. package/src/utils/userAgent.js +0 -28
  233. /package/src/{api/feed/commentOnPost.js → database/models/s} +0 -0
  234. /package/src/{api/feed/getPostInfo.js → engine/models/s} +0 -0
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  <div align="center">
4
4
 
5
- **Unofficial Facebook Chat API for Node.js - The Ultimate Edition**
5
+ **Unofficial Facebook Chat API for Node.js**
6
6
 
7
7
  </div>
8
8
 
@@ -52,22 +52,67 @@ If you do not agree with this policy, you are free to fork the repository and ma
52
52
 
53
53
  This **sagor-fca** extends the base functionality with advanced features for a more robust and versatile Facebook automation experience:
54
54
 
55
- | Category | Feature | Description |
56
- | :--- | :--- | :--- |
57
- | **Core Messenger** | Full Messenger API | Send messages, files, stickers, and more. |
58
- | | Real-time Events | Listen to messages, reactions, and thread events. |
59
- | | User Account Support | Works with personal Facebook accounts (not just Pages). |
60
- | | AppState Support | Save login state to avoid re-authentication. |
61
- | | MQTT Protocol | Real-time messaging via MQTT. |
62
- | | TypeScript Support | Includes TypeScript definitions. |
63
- | **Story Interaction** | `getStories`, `reactStory`, `viewStory` | Friends' stories can be viewed, reacted to, and marked as 'Seen'. |
64
- | **Group Management** | `getGroupJoinRequests`, `handleGroupJoinRequest` | View and manage pending group join requests. |
65
- | **Feed Interaction** | `getPostInfo`, `commentOnPost` | Retrieve detailed information about a specific post and comment on it. |
66
- | **Advanced Messaging** | `sendVoiceMessage` | Send audio files as native voice notes. |
67
- | **Reels Interaction** | `getReels`, `reactReel` | Fetch and react to Facebook Reels. |
68
- | **Professional Mode** | `getProfessionalInfo`, `toggleProfessionalMode` | View professional profile information and toggle Professional Mode. |
69
- | **Security & Anti-Ban** | Request Throttling | Configurable delay between requests to avoid detection. |
70
- | | User-Agent Rotation | Automatic rotation of User-Agents for each request. |
55
+ **Authentication**
56
+ - Cookie array login (`appState`) the safest method for long-running bots
57
+ - Email/password login with TOTP/2FA support
58
+ - Session fingerprint locking User-Agent, Sec-Ch-Ua, locale, timezone locked per session to prevent detection
59
+ - AppState auto-backup and restore on restart
60
+
61
+ **Real-time Messaging**
62
+ - MQTT and HTTP messaging with automatic protocol fallback
63
+ - Send text, attachments, stickers, emoji, mentions, and location
64
+ - Message editing, unsend, forward, and delete
65
+ - Message reactions via HTTP and MQTT
66
+ - Pin/unpin messages, list pinned messages
67
+
68
+ **Anti-Suspension System**
69
+ - Circuit breaker halts activity after repeated suspension signals, resumes after cooldown
70
+ - 60+ suspension signal patterns: checkpoints, spam flags, rate limits, identity verification, policy violations, session expiry, and more
71
+ - Adaptive per-thread delay that increases with session volume
72
+ - Hourly and daily message volume limits with automatic warning pauses
73
+ - Warmup mode for fresh sessions — gradually increases allowed message rate
74
+ - Humanized typing simulation before every send
75
+ - Randomized request intervals and jitter to avoid periodicity detection
76
+ - Session fingerprint locking to maintain consistent browser identity
77
+ - PostSafe guard: detects auth failures and checkpoint responses in real-time
78
+ - MQTT watchdog: detects stale connections and forces clean reconnect
79
+
80
+ **Stability & Reliability**
81
+ - MQTT auto-reconnect with exponential backoff and jitter
82
+ - Auto re-login using refreshed AppState when session expires
83
+ - TokenRefreshManager with randomized intervals to keep sessions alive
84
+ - Sliding-window rate limiter with per-endpoint tracking
85
+ - SQLite-backed thread and user data cache for fast lookups
86
+
87
+ **Thread & Group Management**
88
+ - Get thread info, history, pictures, and lists
89
+ - Create groups, add/remove members, change admin status
90
+ - Update group image, name, color, emoji
91
+ - Archive, mute, delete threads
92
+ - Create polls, manage notes and rules
93
+ - Search threads by name, handle message requests
94
+
95
+ **User & Friends**
96
+ - Get user info (basic and extended), resolve user IDs
97
+ - Get full friends list, send/cancel friend requests, unfriend, block/unblock
98
+
99
+ **Social**
100
+ - Comment on posts, share posts, follow/unfollow users
101
+
102
+ **Themes & Stickers**
103
+ - Browse 90+ Messenger themes, apply themes via MQTT
104
+ - Generate AI-powered themes with text prompts
105
+ - Search stickers, browse packs, add packs, get AI stickers
106
+
107
+ **E2EE (Opt-In)**
108
+ - Application-layer end-to-end encryption for DMs using X25519 + HKDF + AES-256-GCM
109
+
110
+ **Monitoring**
111
+ - `api.getHealthStatus()` — MQTT status, token refresh stats, rate limiter metrics
112
+ - Built-in `ProductionMonitor` for request/error/performance telemetry
113
+
114
+ **Proxy Support**
115
+ - Full proxy support via the `proxy` login option
71
116
 
72
117
  ---
73
118
 
@@ -113,7 +158,7 @@ login({ appState: [] }, (err, api) => {
113
158
  }
114
159
 
115
160
  const yourID = "000000000000000"; // Replace with actual Facebook ID
116
- const msg = "Hello from sagor-fca! 👋";
161
+ const msg = "Hello from Sagor-fca! 👋";
117
162
 
118
163
  api.sendMessage(msg, yourID, (err) => {
119
164
  if (err) console.error("Message Sending Error:", err);
@@ -124,12 +169,170 @@ login({ appState: [] }, (err, api) => {
124
169
 
125
170
  ---
126
171
 
127
- ## 📚 API Reference
172
+ ## Anti-Suspension Configuration
173
+
174
+ The anti-suspension system is active by default. You can tune it through login options:
175
+
176
+ ```js
177
+ login({ appState }, {
178
+ autoReconnect: true,
179
+ listenEvents: true,
180
+ autoMarkRead: true,
181
+ simulateTyping: true, // humanized typing delays before send
182
+ randomUserAgent: true, // rotate user agent on each session
183
+ persona: "desktop", // "desktop" or "android"
184
+ maxConcurrentRequests: 5, // max parallel HTTP requests
185
+ maxRequestsPerMinute: 50, // sliding-window rate cap
186
+ requestCooldownMs: 60000, // per-endpoint cooldown duration
187
+ errorCacheTtlMs: 300000 // how long to suppress repeated errors
188
+ }, (err, api) => {
189
+ if (err) throw err;
190
+
191
+ console.log(api.getHealthStatus());
192
+ });
193
+ ```
128
194
 
129
- Detailed documentation for each API endpoint, including parameters and return types, can be found within the `src/api` directory of this repository. Key modules include `action`, `messaging`, `threads`, `users`, `stories`, `groups`, `feed`, `reels`, and `professional`.
195
+
196
+ ## API Reference
197
+
198
+ ### Authentication
199
+ | Method | Description |
200
+ |---|---|
201
+ | `login(credentials, options, callback)` | Log in and receive the API object |
202
+ | `api.logout()` | End the session |
203
+ | `api.getAppState()` | Get current session cookies |
204
+ | `api.getCurrentUserID()` | Get logged-in user ID |
205
+
206
+ ### Messaging
207
+ | Method | Description |
208
+ |---|---|
209
+ | `api.sendMessage(msg, threadID)` | Send (HTTP + MQTT fallback) |
210
+ | `api.sendMessageMqtt(msg, threadID)` | Send over MQTT |
211
+ | `api.editMessage(text, messageID)` | Edit a message |
212
+ | `api.unsendMessage(messageID, threadID)` | Retract a message |
213
+ | `api.forwardMessage(messageID, threadID)` | Forward a message |
214
+ | `api.deleteMessage(messageIDs)` | Delete locally |
215
+ | `api.shareContact(senderID, threadID)` | Share a contact card |
216
+
217
+ ### Reactions & Status
218
+ | Method | Description |
219
+ |---|---|
220
+ | `api.setMessageReaction(reaction, messageID)` | React via HTTP |
221
+ | `api.setMessageReactionMqtt(reaction, messageID, threadID)` | React via MQTT |
222
+ | `api.sendTypingIndicator(isTyping, threadID)` | Show/hide typing |
223
+ | `api.markAsRead(threadID)` | Mark thread as read |
224
+ | `api.markAsReadAll()` | Mark all threads as read |
225
+ | `api.markAsSeen()` | Mark as seen |
226
+ | `api.markAsDelivered(threadID, messageID)` | Mark as delivered |
227
+
228
+ ### Threads
229
+ | Method | Description |
230
+ |---|---|
231
+ | `api.getThreadInfo(threadID)` | Thread metadata |
232
+ | `api.getThreadList(limit, timestamp, tags)` | List threads |
233
+ | `api.getThreadHistory(threadID, amount, timestamp)` | Message history |
234
+ | `api.getThreadPictures(threadID, offset, limit)` | Thread images |
235
+ | `api.searchForThread(name)` | Search by name |
236
+ | `api.createNewGroup(participantIDs, name?)` | Create group |
237
+ | `api.deleteThread(threadID)` | Delete thread |
238
+ | `api.muteThread(threadID, muteSeconds)` | Mute thread |
239
+ | `api.changeArchivedStatus(threadID, archive)` | Archive/unarchive |
240
+ | `api.pinMessage(action, threadID, messageID?)` | Pin/unpin/list |
241
+ | `api.createPoll(title, threadID, options?)` | Create poll |
242
+ | `api.handleMessageRequest(threadID, accept)` | Accept/decline |
243
+
244
+ ### Group Admin
245
+ | Method | Description |
246
+ |---|---|
247
+ | `api.addUserToGroup(userID, threadID)` | Add member |
248
+ | `api.removeUserFromGroup(userID, threadID)` | Remove member |
249
+ | `api.changeAdminStatus(threadID, userID, isAdmin)` | Promote/demote |
250
+ | `api.changeGroupImage(image, threadID)` | Group photo |
251
+ | `api.gcname(name, threadID)` | Rename group |
252
+
253
+ ### Users
254
+ | Method | Description |
255
+ |---|---|
256
+ | `api.getUserInfo(id)` | Basic user info |
257
+ | `api.getUserInfoV2(id)` | Extended user info |
258
+ | `api.getUserID(name)` | Resolve name to ID |
259
+ | `api.getFriendsList()` | Friends list |
260
+ | `api.getBotInfo()` | Bot account info |
261
+
262
+ ### Themes & Customization
263
+ | Method | Description |
264
+ |---|---|
265
+ | `api.getTheme(threadID)` | List available themes |
266
+ | `api.getThemeInfo(threadID)` | Current theme |
267
+ | `api.setThreadThemeMqtt(threadID, themeID)` | Apply theme |
268
+ | `api.createAITheme(prompt)` | AI theme |
269
+ | `api.changeThreadColor(color, threadID)` | Thread color |
270
+ | `api.changeThreadEmoji(emoji, threadID)` | Thread emoji |
271
+ | `api.nickname(nickname, threadID, participantID)` | Set nickname |
272
+ | `api.emoji(emoji, threadID)` | Thread emoji shorthand |
273
+
274
+ ### Stickers
275
+ | Method | Description |
276
+ |---|---|
277
+ | `api.stickers.search(query)` | Search stickers |
278
+ | `api.stickers.listPacks()` | Installed packs |
279
+ | `api.stickers.getStorePacks()` | Sticker store |
280
+ | `api.stickers.addPack(packID)` | Add pack |
281
+ | `api.stickers.getStickersInPack(packID)` | Stickers in pack |
282
+ | `api.stickers.getAiStickers(options?)` | AI stickers |
283
+
284
+ ### E2EE
285
+ | Method | Description |
286
+ |---|---|
287
+ | `api.e2ee.enable()` | Enable E2EE |
288
+ | `api.e2ee.disable()` | Disable E2EE |
289
+ | `api.e2ee.getPublicKey()` | Get public key |
290
+ | `api.e2ee.setPeerKey(threadID, key)` | Set peer key |
291
+ | `api.e2ee.hasPeer(threadID)` | Has peer key |
292
+ | `api.e2ee.clearPeerKey(threadID)` | Remove peer key |
293
+
294
+ ### Social
295
+ | Method | Description |
296
+ |---|---|
297
+ | `api.comment(msg, postID)` | Comment on post |
298
+ | `api.share(postID)` | Share post |
299
+ | `api.follow(userID, follow)` | Follow/unfollow |
300
+ | `api.unfriend(userID)` | Unfriend |
301
+ | `api.changeBlockedStatus(userID, block)` | Block/unblock |
302
+
303
+ ### Health
304
+ | Method | Description |
305
+ |---|---|
306
+ | `api.getHealthStatus()` | MQTT, token, rate limiter stats |
130
307
 
131
308
  ---
132
309
 
310
+ ## Login Options
311
+
312
+ | Option | Type | Default | Description |
313
+ |---|---|---|---|
314
+ | `online` | `boolean` | `true` | Appear online |
315
+ | `selfListen` | `boolean` | `false` | Receive own messages |
316
+ | `listenEvents` | `boolean` | `true` | Receive thread events |
317
+ | `listenTyping` | `boolean` | `false` | Receive typing events |
318
+ | `updatePresence` | `boolean` | `false` | Broadcast presence |
319
+ | `autoMarkDelivery` | `boolean` | `false` | Auto-mark delivered |
320
+ | `autoMarkRead` | `boolean` | `true` | Auto-mark read |
321
+ | `autoReconnect` | `boolean` | `true` | MQTT auto-reconnect |
322
+ | `simulateTyping` | `boolean` | `true` | Humanized typing delays |
323
+ | `randomUserAgent` | `boolean` | `false` | Random User-Agent |
324
+ | `persona` | `"desktop"\|"android"` | `"desktop"` | Browser persona |
325
+ | `proxy` | `string` | — | Proxy URL |
326
+ | `forceLogin` | `boolean` | `false` | Force fresh login |
327
+ | `maxConcurrentRequests` | `number` | `5` | Max parallel requests |
328
+ | `maxRequestsPerMinute` | `number` | `50` | Rate cap per minute |
329
+ | `requestCooldownMs` | `number` | `60000` | Endpoint cooldown |
330
+ | `errorCacheTtlMs` | `number` | `300000` | Error suppression TTL |
331
+ | `stealthMode` | `boolean` | `false` | Extra stealth headers |
332
+
333
+ ---
334
+
335
+
133
336
  ## 💾 AppState Management
134
337
 
135
338
  AppState is crucial for maintaining login sessions without re-authenticating with email/password. It helps prevent frequent logouts and reduces the risk of account flags.
@@ -0,0 +1,38 @@
1
+ #!/usr/bin/env node
2
+ "use strict";
3
+
4
+ /**
5
+ * Example: Login with Cookie Array
6
+ *
7
+ * Demonstrates how to authenticate using a browser cookie array
8
+ * instead of email/password credentials.
9
+ *
10
+ * Usage:
11
+ * 1. Export cookies from your browser (c_user, xs, fr, datr)
12
+ * 2. Replace the placeholder values below
13
+ * 3. Run: node examples/login-with-cookies.js
14
+ */
15
+
16
+ const { login } = require("goat-fca");
17
+
18
+ const cookieArray = [
19
+ { name: "c_user", value: "YOUR_USER_ID_HERE" },
20
+ { name: "xs", value: "YOUR_XS_TOKEN_HERE" },
21
+ { name: "fr", value: "YOUR_FR_TOKEN_HERE" },
22
+ { name: "datr", value: "YOUR_DATR_TOKEN_HERE" }
23
+ ];
24
+
25
+ login({ appState: cookieArray }, {
26
+ listenEvents: true,
27
+ autoMarkRead: true,
28
+ selfListen: false
29
+ }, (err, api) => {
30
+ if (err) return console.error("Login failed:", err);
31
+
32
+ console.log("Logged in as:", api.getCurrentUserID());
33
+
34
+ api.listenMqtt((err, event) => {
35
+ if (err || event.type !== "message" || !event.body) return;
36
+ console.log("Message from", event.senderID, ":", event.body);
37
+ });
38
+ });
@@ -0,0 +1,36 @@
1
+ #!/usr/bin/env node
2
+ "use strict";
3
+
4
+ /**
5
+ * Example: Simple Ping Bot
6
+ *
7
+ * Listens for "/ping" in any thread and replies with "pong!".
8
+ *
9
+ * Usage:
10
+ * 1. Save your cookies to appstate.json
11
+ * 2. Run: node examples/ping.js
12
+ */
13
+
14
+ const fs = require("fs");
15
+ const { login } = require("goat-fca");
16
+
17
+ const appState = JSON.parse(fs.readFileSync("appstate.json", "utf8"));
18
+
19
+ login({ appState }, {
20
+ online: true,
21
+ listenEvents: true,
22
+ autoReconnect: true,
23
+ simulateTyping: true
24
+ }, (err, api) => {
25
+ if (err) return console.error("Login error:", err);
26
+
27
+ console.log("Logged in as:", api.getCurrentUserID());
28
+
29
+ api.listenMqtt((err, event) => {
30
+ if (err || event.type !== "message" || !event.body) return;
31
+
32
+ if (event.body.toLowerCase() === "/ping") {
33
+ api.sendMessage("pong!", event.threadID);
34
+ }
35
+ });
36
+ });
@@ -0,0 +1,69 @@
1
+ #!/usr/bin/env node
2
+ "use strict";
3
+
4
+ /**
5
+ * Quick sanity check — verifies the library loads correctly and
6
+ * prints the anti-suspension and rate limiter configuration. Run with:
7
+ * node examples/verify.js
8
+ */
9
+
10
+ const fca = require("goat-fca");
11
+ const { globalAntiSuspension } = require("goat-fca/src/utils/antiSuspension");
12
+ const { globalRateLimiter } = require("goat-fca/src/utils/rateLimiter");
13
+
14
+ console.log("goat-fca Library Verification");
15
+ console.log("==============================\n");
16
+
17
+ console.log("Library entry point:", typeof fca.login === "function" ? "OK" : "FAIL");
18
+
19
+ const config = globalAntiSuspension.getConfig();
20
+ console.log("\nAnti-Suspension Configuration:");
21
+ console.log(` Message Delay : ${config.messageDelayMs}ms`);
22
+ console.log(` Thread Delay : ${config.threadDelayMs}ms`);
23
+ console.log(` Max Login Tries : ${config.maxLoginAttempts}`);
24
+ console.log(` Login Cooldown : ${config.loginCooldownMs}ms`);
25
+ console.log(` Daily Msg Limit : ${config.dailyStats.maxDailyMessages}`);
26
+ console.log(` Hourly Msg Limit : ${config.hourlyStats.maxPerHour}`);
27
+
28
+ console.log("\nEnabled Features:");
29
+ Object.entries(config.features).forEach(([feature, enabled]) => {
30
+ console.log(` ${enabled ? "[x]" : "[ ]"} ${feature}`);
31
+ });
32
+
33
+ const activityPattern = globalAntiSuspension.getRealisticActivityPattern();
34
+ console.log("\nActivity Pattern:");
35
+ console.log(` Current activity : ${activityPattern.messageFrequency}`);
36
+ console.log(` Next action delay : ${activityPattern.nextActionDelayMs.toFixed(0)}ms`);
37
+ console.log(` Is active hours : ${activityPattern.isActiveHours}`);
38
+
39
+ console.log("\nCircuit Breaker:");
40
+ console.log(` Tripped : ${globalAntiSuspension.isCircuitBreakerTripped()}`);
41
+ console.log(` Signal count : ${globalAntiSuspension.suspensionCircuitBreaker.signalCount}`);
42
+
43
+ const rateLimiterStats = globalRateLimiter.getStats();
44
+ console.log("\nRate Limiter:");
45
+ console.log(` Max concurrent : ${rateLimiterStats.maxConcurrentRequests}`);
46
+ console.log(` Max per minute : ${rateLimiterStats.maxRequestsPerMinute}`);
47
+ console.log(` Requests (1 min) : ${rateLimiterStats.requestsInLastMinute}`);
48
+
49
+ const testSignals = [
50
+ { text: "Everything is fine, message sent", expectSuspicion: false },
51
+ { text: "Your account has been suspended due to policy violation", expectSuspicion: true },
52
+ { text: "checkpoint required to verify identity", expectSuspicion: true },
53
+ { text: "Too many requests - rate limited", expectSuspicion: true },
54
+ { text: "Unusual activity detected on your account", expectSuspicion: true },
55
+ ];
56
+ console.log("\nSuspension Signal Detection:");
57
+ testSignals.forEach(({ text, expectSuspicion }) => {
58
+ globalAntiSuspension.resetCircuitBreaker();
59
+ const detected = globalAntiSuspension.detectSuspensionSignal(text);
60
+ const passed = detected === expectSuspicion;
61
+ globalAntiSuspension.resetCircuitBreaker();
62
+ console.log(` ${passed ? "[x]" : "[!]"} "${text.substring(0, 40)}" → ${detected ? "SUSPICIOUS" : "CLEAN"}`);
63
+ });
64
+ globalAntiSuspension.resetCircuitBreaker();
65
+
66
+ console.log("\nAll checks passed. Library is ready to use.");
67
+ console.log("==============================\n");
68
+
69
+ process.exit(0);
package/index.js CHANGED
@@ -1,10 +1,2 @@
1
- const login = require("./module/login");
2
-
3
- // CommonJS default export
4
- module.exports = login;
5
- // Support require('{ login }') named import pattern
6
- module.exports.login = login;
7
- // Support ESM default import interop
8
- module.exports.default = login;
9
- module.exports.getRandomUserAgent = require("./src/utils/userAgent").getRandomUserAgent;
10
- module.exports.userAgents = require("./src/utils/userAgent").userAgents;
1
+ "use strict";
2
+ module.exports = require('./src/engine/client');
package/package.json CHANGED
@@ -1,84 +1,95 @@
1
1
  {
2
2
  "name": "sagor-fca",
3
- "version": "0.0.5",
4
- "description": "The most powerful and updated Facebook Chat API (FCA).Enhanced by SaGor.",
3
+ "version": "0.0.6",
4
+ "type": "commonjs",
5
+ "types": "src/types/index.d.ts",
6
+ "description": "Advanced Facebook Chat API.",
5
7
  "main": "index.js",
6
- "types": "index.d.ts",
7
- "exports": {
8
- ".": {
9
- "require": "./index.js",
10
- "default": "./index.js",
11
- "types": "./index.d.ts"
12
- }
13
- },
14
8
  "files": [
15
9
  "index.js",
16
- "index.d.ts",
17
- "module/",
18
- "func/",
19
10
  "src/",
20
- "DOCS.md",
21
- "README.md",
11
+ "examples/",
22
12
  "LICENSE",
23
- "CHANGELOG.md"
13
+ "README.md",
14
+ "CHANGELOG.md",
15
+ "COOKIE_LOGIN.md"
24
16
  ],
25
- "scripts": {
26
- "test": "mocha",
27
- "lint": "eslint ."
28
- },
29
17
  "repository": {
30
18
  "type": "git",
31
19
  "url": "git+https://github.com/SAGOR-KINGx/sagor-fca.git"
32
20
  },
33
- "keywords": [
34
- "facebook",
35
- "chat",
36
- "api",
37
- "messenger",
38
- "bot",
39
- "unofficial",
40
- "automation",
41
- "facebook-api",
42
- "facebook-chat",
43
- "facebook-messenger",
44
- "chatbot",
45
- "nodejs",
46
- "fca",
47
- "sagor-fca"
21
+ "author": "SaGor",
22
+ "contributors": [
23
+ "XxX"
48
24
  ],
49
- "author": {
50
- "name": "SAGOR",
51
- "url": "https://github.com/SAGOR-KINGx"
52
- },
53
25
  "license": "MIT",
54
26
  "bugs": {
55
27
  "url": "https://github.com/SAGOR-KINGx/sagor-fca/issues"
56
28
  },
57
29
  "homepage": "https://github.com/SAGOR-KINGx/sagor-fca#readme",
58
- "engines": {
59
- "node": ">=12.0.0"
30
+ "publishConfig": {
31
+ "access": "public",
32
+ "registry": "https://registry.npmjs.org/"
60
33
  },
34
+ "keywords": [
35
+ "facebook",
36
+ "messenger",
37
+ "chat",
38
+ "bot",
39
+ "fca",
40
+ "sagor-fca",
41
+ "mqtt",
42
+ "messaging",
43
+ "api",
44
+ "automation",
45
+ "facebook-chat-api",
46
+ "anti-suspension",
47
+ "SaGor",
48
+ "e2ee"
49
+ ],
61
50
  "dependencies": {
62
- "axios": "^1.13.5",
63
- "axios-cookiejar-support": "^5.0.5",
51
+ "axios": "^1.7.9",
52
+ "axios-cookiejar-support": "^4.0.7",
64
53
  "bluebird": "^3.7.2",
65
- "chalk": "^4.1.2",
66
- "cheerio": "^1.0.0-rc.10",
67
- "duplexify": "^4.1.3",
68
- "gradient-string": "^2.0.2",
69
- "https-proxy-agent": "^4.0.0",
70
- "mqtt": "^4.3.8",
71
- "sequelize": "^6.37.6",
54
+ "cheerio": "^1.0.0",
55
+ "deepdash": "^5.3.9",
56
+ "form-data": "^4.0.4",
57
+ "https-proxy-agent": "^7.0.6",
58
+ "jsonpath-plus": "^10.3.0",
59
+ "lodash": "^4.17.21",
60
+ "mqtt": "^4.3.7",
61
+ "node-cron": "^3.0.3",
62
+ "npmlog": "^7.0.1",
63
+ "sequelize": "^6.37.5",
72
64
  "sqlite3": "^5.1.7",
73
- "totp-generator": "^1.0.0",
74
- "ws": "^8.18.1"
65
+ "totp-generator": "^2.0.1",
66
+ "tough-cookie": "^4.1.4",
67
+ "undici": "^6.21.0",
68
+ "uuid": "^9.0.1",
69
+ "websocket-stream": "^5.3.0",
70
+ "ws": "^8.18.0"
75
71
  },
76
72
  "devDependencies": {
77
- "eslint": "^8.50.0",
78
- "mocha": "^10.2.0"
73
+ "@types/form-data": "^2.2.1",
74
+ "@types/node": "^20.17.6",
75
+ "@types/tough-cookie": "^4.0.5",
76
+ "eslint": "^9.15.0",
77
+ "mocha": "^10.7.3",
78
+ "prettier": "^3.4.2",
79
+ "ts-node": "^10.9.2",
80
+ "typescript": "^5.7.2"
79
81
  },
80
- "publishConfig": {
81
- "access": "public",
82
- "registry": "https://registry.npmjs.org/"
82
+ "engines": {
83
+ "node": ">=18.0.0"
84
+ },
85
+ "scripts": {
86
+ "validate": "npm pack --dry-run",
87
+ "prepack": "echo 'Preparing package for npm...'",
88
+ "test": "echo 'No tests configured yet'"
89
+ },
90
+ "overrides": {
91
+ "websocket-stream": {
92
+ "ws": "^8.18.0"
93
+ }
83
94
  }
84
95
  }
@@ -1,24 +1,23 @@
1
1
  "use strict";
2
+ const utils = require('../utils');
2
3
 
3
- const { getType } = require("../../utils/format");
4
-
5
- module.exports = function(defaultFuncs, api, ctx) {
4
+ module.exports = function (defaultFuncs, api, ctx) {
6
5
  return function addExternalModule(moduleObj) {
7
- if (getType(moduleObj) == "Object") {
6
+ if (utils.getType(moduleObj) == "Object") {
8
7
  for (const apiName in moduleObj) {
9
- if (getType(moduleObj[apiName]) == "Function") {
8
+ if (utils.getType(moduleObj[apiName]) == "Function") {
10
9
  api[apiName] = moduleObj[apiName](defaultFuncs, api, ctx);
11
10
  } else {
12
11
  throw new Error(
13
- `Item "${apiName}" in moduleObj must be a function, not ${getType(
14
- moduleObj[apiName]
15
- )}!`
12
+ `Item "${apiName}" in moduleObj must be a function, not ${utils.getType(
13
+ moduleObj[apiName],
14
+ )}!`,
16
15
  );
17
16
  }
18
17
  }
19
18
  } else {
20
19
  throw new Error(
21
- `moduleObj must be an object, not ${getType(moduleObj)}!`
20
+ `moduleObj must be an object, not ${utils.getType(moduleObj)}!`,
22
21
  );
23
22
  }
24
23
  };