@fcamt/fca

v2.1.0-rc.7

Published

11 days ago

MT FCA - CommonJS Facebook Chat API compatibility fork for Mirai on Node.js 20/22

0High
0Medium
0Low

minhtri15022

fcamt mt-fca facebook-chat-api mirai commonjs node20 node22

MT-FCA

Giới thiệu

@fcamt/fca là phiên bản Facebook Chat API được nâng cấp và duy trì bởi Minh Trí (MT), hướng tới khả năng hoạt động ổn định với Mirai Bot trên Node.js 20 và Node.js 22.

MT-FCA giữ nguyên cấu trúc API/callback quen thuộc của FCA, đồng thời bổ sung AutoLogin, tự khôi phục MQTT, hàng đợi gửi tin nhắn, database nhóm và nhiều lớp xử lý lỗi nhằm hạn chế tình trạng bot hoạt động nhưng không phản hồi.

| Thông tin | Liên kết | | ---------- | ------------------------------------------------------------------- | | npm | @fcamt/fca | | GitHub | devminhtri15022/MT-FCA | | Website | ntmtstudio.com | | Maintainer | Minh Trí (MT) | | Phiên bản | 2.1.0-rc.6 |

MT-FCA sử dụng các endpoint riêng của Facebook. Những endpoint này có thể thay đổi bất kỳ lúc nào. Hãy thử nghiệm bằng tài khoản phụ và tuân thủ các điều khoản của nền tảng.

Tính năng nổi bật

Hỗ trợ CommonJS trên Node.js 20 và 22.
Tương thích với cấu trúc bot Mirai hiện có.
AutoLogin bằng Cookie, AppState hoặc tài khoản/mật khẩu.
Tự động khôi phục khi phiên đăng nhập hết hạn.
MQTT reconnect có giới hạn, tránh reconnect liên tục.
Chỉ duy trì một MQTT listener đang hoạt động.
Lọc sự kiện trùng lặp theo messageID.
Hàng đợi gửi tin nhắn tuần tự.
Tự động gửi lại khi gặp lỗi mạng tạm thời.
Exponential backoff kết hợp jitter.
Phân loại lỗi với thông báo tiếng Việt.
Tự động lưu AppState bằng atomic write.
Khởi tạo database nhóm khi FCA hoạt động.
Tự tạo dữ liệu cho nhóm chưa tồn tại.
Không phụ thuộc SQLite, better-sqlite3, deasync hoặc node-gyp.
Có sẵn TypeScript declarations.
Logger và terminal đồng nhất thương hiệu MT-FCA.
Hỗ trợ protected build cho các file lõi quan trọng.

Yêu cầu hệ thống

| Thành phần | Yêu cầu | | --------------- | ---------------------------------- | | Node.js | 20.x hoặc 22.x | | Module system | CommonJS | | Hệ điều hành | Windows, Windows Server hoặc Linux | | Package manager | npm | | Database | JSON |

Kiểm tra môi trường:

node -v
npm -v

Không khuyến nghị sử dụng Node.js 18 hoặc Node.js 24 cho phiên bản hiện tại.

Cài đặt

Cài phiên bản mới nhất:

npm install @fcamt/fca

Cài chính xác phiên bản hiện tại:

npm install @fcamt/[email protected]

Sau khi cài đặt, package nằm tại:

node_modules/@fcamt/fca

Sử dụng cơ bản

const login = require("@fcamt/fca");

login({}, {
  selfListen: false,
  listenEvents: true,
  autoReconnect: true
}, (error, api) => {
  if (error) {
    console.error("[MT-FCA] Đăng nhập thất bại:", error);
    return;
  }

  console.log("[MT-FCA] Đăng nhập thành công");

  api.listenMqtt((listenError, event) => {
    if (listenError) {
      console.error("[MT-FCA MQTT]", listenError);
      return;
    }

    if (event.type === "message") {
      console.log(`${event.senderID}: ${event.body}`);
    }
  });
});

Đăng nhập bằng Cookie

Tạo file cookie.txt trong thư mục chính của bot:

c_user=YOUR_USER_ID; xs=YOUR_XS_COOKIE; datr=YOUR_DATR_COOKIE;

MT-FCA sẽ kiểm tra định dạng Cookie trước khi sử dụng. Cookie cần có ít nhất c_user và xs để xác định phiên đăng nhập.

Không đăng tải cookie.txt lên GitHub hoặc gửi cho người khác.

Đăng nhập bằng AppState

const login = require("@fcamt/fca");
const appState = require("./appstate.json");

login({ appState }, {
  selfListen: false,
  listenEvents: true,
  autoReconnect: true
}, (error, api) => {
  if (error) {
    console.error("[MT-FCA] Đăng nhập thất bại:", error);
    return;
  }

  console.log("[MT-FCA] Đăng nhập thành công");
});

AutoLogin bằng tài khoản và mật khẩu

Cấu hình AutoLogin được quản lý trong FastConfigFca.json. MT-FCA không sử dụng file fca-config.json.

{
  "AutoLogin": true,
  "AutoLoginConfig": {
    "Email": "your-account",
    "Password": "your-password",
    "CookiePath": "cookie.txt",
    "AppStatePath": "appstate.json",
    "CooldownMs": 30000,
    "SaveAppState": true
  }
}

Thứ tự khôi phục đăng nhập:

Kiểm tra phiên đăng nhập hiện tại.
Thử đọc dữ liệu từ cookie.txt.
Thử đọc dữ liệu từ appstate.json.
Sử dụng tài khoản và mật khẩu trong cấu hình.
Lưu lại AppState mới sau khi đăng nhập thành công.

FastConfigFca.json có thể chứa mật khẩu. Tuyệt đối không đưa file này lên GitHub.

MQTT Listener

api.listenMqtt((error, event) => {
  if (error) {
    console.error("[MT-FCA MQTT]", error);
    return;
  }

  switch (event.type) {
    case "message":
    case "message_reply":
      console.log(event.body);
      break;

    case "event":
      console.log("[MT-FCA EVENT]", event);
      break;
  }
});

MT-FCA có cơ chế xử lý:

MQTT mất kết nối.
Sync sequence bị thiếu.
Payload MQTT không hợp lệ.
Sự kiện bị gửi trùng.
Listener cũ chưa được dừng.
Kết nối mạng bị timeout.
Reconnect storm.
Lỗi phát sinh trong event handler.

Mirai Adapter

const login = require("@fcamt/fca");
const { startListener } = require("@fcamt/fca/mirai");

login({}, {}, (error, api) => {
  if (error) return console.error(error);

  const stopListener = startListener(
    api,
    async event => {
      // Đưa event vào handler của Mirai tại đây.
      console.log(event);
    },
    {
      maxRestarts: 5
    }
  );

  process.on("SIGINT", () => {
    stopListener();
    process.exit(0);
  });
});

Mirai Adapter giới hạn số lần khởi động lại, cô lập lỗi trong handler và hỗ trợ dừng listener an toàn.

Gửi tin nhắn

Sử dụng callback:

api.sendMessage(
  "MT-FCA đã hoạt động!",
  event.threadID,
  error => {
    if (error) {
      console.error("[MT-FCA] Gửi tin nhắn thất bại:", error);
    }
  }
);

Sử dụng Promise:

try {
  const result = await api.sendMessage(
    "MT-FCA đã hoạt động!",
    event.threadID
  );

  console.log(result);
} catch (error) {
  console.error("[MT-FCA] Gửi tin nhắn thất bại:", error);
}

Hệ thống gửi tin nhắn hỗ trợ:

Hàng đợi tuần tự.
Khoảng cách an toàn giữa các lần gửi.
Tự động thử lại khi timeout.
Exponential backoff.
Jitter hạn chế gửi đồng loạt.
Phân biệt lỗi tạm thời và lỗi vĩnh viễn.

Database nhóm

MT-FCA tự khởi tạo database nhóm dạng JSON khi listener bắt đầu hoạt động.

Nếu quá trình quét danh sách nhóm ban đầu thất bại, bot vẫn tiếp tục nhận và xử lý tin nhắn. Nhóm chưa tồn tại trong database sẽ được tạo khi có sự kiện mới phát sinh.

Cơ chế này giúp hạn chế tình trạng bot khởi động thành công nhưng im lặng do thiếu dữ liệu nhóm.

Theo dõi trạng thái FCA

Xem tình trạng hoạt động:

console.log(api.getHealth());

Làm mới phiên đăng nhập:

await api.refreshSession();

Lưu AppState:

api.saveAppState("appstate.json");

Xem thông tin chẩn đoán:

console.log(login.mt.diagnostics.format());

Thông tin nhạy cảm như Cookie, token và mật khẩu sẽ được che khỏi log chẩn đoán.

Protected Build

MT-FCA hỗ trợ tạo bản phát hành đã làm rối các file lõi quan trọng.

Cài đặt dependencies:

npm install

Tạo protected build:

npm run protect

Kết quả được tạo tại:

dist/MT-FCA-protected

Các thành phần được bảo vệ:

Khởi tạo FCA.
AutoLogin.
MQTT Listener.
Gửi tin nhắn.
Reliability Layer.
Database nhóm.

Loader, cấu hình, typings và public API được giữ nguyên nhằm hạn chế lỗi tương thích.

Protected build tự động loại trừ:

cookie.txt
appstate.json
FastConfigFca.json
Horizon_Database
node_modules

Làm rối mã nguồn chỉ tăng độ khó khi đọc và chỉnh sửa. Đây không phải hình thức mã hóa tuyệt đối.

Kiểm tra dự án

npm install
npm run check
npm test

Kiểm tra những file được đóng gói:

npm pack --dry-run

Tạo và kiểm tra protected build:

npm run protect
cd dist/MT-FCA-protected
npm test

Bảo mật

Thêm các mục sau vào .gitignore:

node_modules/
dist/
cookie.txt
appstate.json
FastConfigFca.json
Horizon_Database/
*.log
.env

Không đăng tải công khai:

Cookie Facebook.
AppState.
Mật khẩu tài khoản.
Access token.
File cấu hình có thông tin đăng nhập.
Database đang sử dụng.
Log chứa thông tin phiên đăng nhập.

Xử lý lỗi thường gặp

Bot đăng nhập nhưng không phản hồi

Kiểm tra listenEvents đã được bật.
Kiểm tra MQTT listener có đang chạy.
Kiểm tra api.getHealth().
Kiểm tra database nhóm.
Khởi động lại listener thay vì tạo nhiều listener cùng lúc.

Không gửi được tin nhắn

Kiểm tra tài khoản còn trong nhóm.
Kiểm tra threadID.
Kiểm tra trạng thái phiên đăng nhập.
Chờ hàng đợi thử lại khi gặp lỗi mạng tạm thời.

AutoLogin thất bại

Kiểm tra cookie.txt có c_user và xs.
Kiểm tra đường dẫn Cookie/AppState.
Kiểm tra cấu hình AutoLogin.
Không để khoảng trắng sai trong tên trường cấu hình.

Node.js không được hỗ trợ

Cài Node.js 20 hoặc 22 rồi kiểm tra:

node -v

Liên hệ và hỗ trợ

Website: ntmtstudio.com
GitHub: github.com/devminhtri15022
Issues: github.com/devminhtri15022/MT-FCA/issues

Khi báo lỗi, vui lòng cung cấp:

Phiên bản Node.js.
Phiên bản MT-FCA.
Hệ điều hành.
Đoạn log lỗi đã che thông tin nhạy cảm.
Các bước khiến lỗi xuất hiện.

Credits

Minh Trí (MT): Maintainer và developer.
Schmavery cùng các contributor: Nền tảng facebook-chat-api ban đầu.
KanzuWakazaki / HZI Team: Các đóng góp từ nhánh FCA Horizon.

Giấy phép

MT-FCA được phát hành theo giấy phép GPL-3.0-only.

Các thông báo bản quyền gốc và file LICENSE vẫn được giữ lại. Khi phân phối protected build, cần cung cấp hoặc duy trì quyền truy cập tới mã nguồn tương ứng theo yêu cầu của GPL-3.0.