LEGIFCA 1.0.0 — LEGISTUDIO

LEGIFCA là thư viện Facebook Chat API dành cho Node.js của LEGISTUDIO. Bản 1.0.0 được phát hành ở dạng mã nguồn rõ, không Obfuscator, tích hợp License WEB LEGI, AUTOLOGIN, quản lý AppState/Cookie, MQTT realtime và bộ API Messenger/Thread/User.

LEGIFCA sử dụng các giao diện web/nội bộ của Facebook. Facebook có thể thay đổi endpoint, payload hoặc cơ chế xác thực bất kỳ lúc nào. Chỉ sử dụng với tài khoản và dữ liệu mà bạn có quyền quản lý.

Thông tin phát hành

| Thành phần | Giá trị | |---|---| | Package | @legidev/legifca | | Phiên bản | 1.0.0 | | Node.js | >= 20.17.0 | | Product License | legifca | | Website License/AUTOLOGIN | https://legistudio.net | | Kiểu mã nguồn | Clear source, không Obfuscator | | File cấu hình | fca-config.json | | .env | Không sử dụng |

Chức năng chính

• Xác minh License LEGIFCA bằng License Key của WEB LEGI.
• AUTOLOGIN bằng API Key Login riêng (LEGI-FB-...).
• Đăng nhập bằng AppState/Cookie đã có trước, giảm số lần phải AUTOLOGIN.
• MQTT realtime để nhận tin nhắn và sự kiện Facebook.
• Gửi tin nhắn, attachment, reaction, typing, forward/edit/unsend/delete message.
• Quản lý nhóm/thread: thêm/xóa thành viên, QTV, nickname, màu, emoji, tên nhóm, ảnh nhóm.
• Lấy thông tin user/thread, lịch sử hội thoại, danh sách bạn bè và tìm kiếm.
• HTTP helper dùng cùng phiên Facebook.
• Middleware cho sự kiện.
• Tự lưu AppState có thể mã hóa.
• Backup session mã hóa AES-256-GCM khi bật cấu hình backup.
• Tự reconnect MQTT có delay/backoff.
• API License được bảo vệ trong từng API instance.
• Cache riêng theo từng phiên đăng nhập, tránh trộn CookieJar giữa nhiều tài khoản.

Cài đặt

Cài từ npm

npm install @legidev/[email protected]

Kiểm tra Node.js:

node -v

Khuyến nghị dùng Node.js 20 LTS hoặc mới hơn, nhưng không thấp hơn 20.17.0.

Cấu hình fca-config.json

LEGIFCA không cần .env. Tạo fca-config.json tại thư mục chạy bot. Bản mẫu đầy đủ nằm ở examples/fca-config.example.json.

Các khóa quan trọng nhất:

{
  "autoUpdate": false,
  "apiServer": "https://legistudio.net",
  "apiKeyLicense": "",
  "autoLogin": true,
  "apiKeyLogin": "",
  "credentials": {
    "email": "",
    "password": "",
    "twofactor": ""
  },
  "mqtt": {
    "enabled": true,
    "reconnectInterval": 3600,
    "reconnectDelayMs": 5000,
    "maxReconnectDelayMs": 60000,
    "requestTimeoutMs": 30000
  },
  "console": {
    "level": "info",
    "showTime": true,
    "showDebug": false,
    "saveLog": true
  }
}

Phân biệt hai loại khóa

apiKeyLicense và apiKeyLogin không phải cùng một khóa.

• apiKeyLicense: License của sản phẩm legifca, dùng để xác minh quyền sử dụng thư viện.
• apiKeyLogin: API Key dành riêng cho WEB-AUTOLOGIN, thường có dạng LEGI-FB-....

Không lấy License Key đưa vào apiKeyLogin, và không lấy API Key Login đưa vào apiKeyLicense.

AUTOLOGIN và AppState

Thứ tự ưu tiên đăng nhập:

1. AppState/Cookie được truyền trực tiếp vào login().
2. Phiên backup mã hóa đúng UID nếu bạn đã bật backup.
3. WEB-AUTOLOGIN khi autoLogin=true và có đủ email, password, apiKeyLogin.

Khuyến nghị vận hành production: ưu tiên AppState ổn định, không AUTOLOGIN lại liên tục. Nếu Facebook trả lỗi dạng The action attempted has been deemed abusive or is otherwise disallowed, dừng retry liên tục và đăng nhập/xác minh tài khoản thủ công trước khi thử lại.

credentials.twofactor phải là secret Base32 của 2FA, không phải mã 6 chữ số đang hiển thị trong ứng dụng xác thực.

Ví dụ đăng nhập

const login = require("@legidev/legifca");

async function start() {
  const api = await login({});

  const listener = api.listenMqtt((error, event) => {
    if (error) {
      console.error(error);
      return;
    }

    if (event?.type === "message" && event.body === "ping") {
      api.sendMessage("pong", event.threadID).catch(console.error);
    }
  });

  process.once("SIGINT", async () => {
    await listener.stopListeningAsync();
    process.exit(0);
  });
}

start().catch(console.error);

Có thể truyền cấu hình cho riêng phiên đăng nhập:

const api = await login({
  appState,
  apiServer: "https://legistudio.net",
  apiKeyLicense: "LEGI-...",
  apiKeyLogin: "LEGI-FB-...",
  autoLogin: true,
  email: "email-hoac-uid",
  password: "mat-khau",
  twoFactor: "BASE32_SECRET"
});

MQTT

const listener = api.listenMqtt((error, event) => {
  if (error) return console.error(error);
  console.log(event);
});

Emitter trả về hỗ trợ:

listener.stopListening();
await listener.stopListeningAsync();

Các tùy chọn quan trọng:

• mqtt.enabled: bật quản lý reconnect/refresh MQTT.
• mqtt.reconnectInterval: chu kỳ làm mới, tính bằng giây.
• mqtt.reconnectDelayMs: delay ban đầu khi reconnect.
• mqtt.maxReconnectDelayMs: giới hạn delay backoff.
• mqtt.requestTimeoutMs: timeout các thao tác liên quan MQTT.

API chính

Messaging

sendMessage, uploadAttachment, forwardAttachment, editMessage, unsendMessage, deleteMessage, getMessage, setMessageReaction, setPostReaction, sendTypingIndicator, shareContact.

Group / Thread

addUserToGroup, removeUserFromGroup, createNewGroup, changeAdminStatus, changeGroupImage, changeNickname, changeThreadColor, changeThreadEmoji, setTitle, getThreadInfo, getThreadList, getThreadHistory, getThreadPictures, searchForThread, changeArchivedStatus, changeBlockedStatus, deleteThread, muteThread, handleMessageRequest.

User

getUserInfo, getUserInfoV2, getUserID, getUID, getFriendsList, handleFriendRequest, unfriend, changeAvatar, changeBio.

Session / License

getCurrentUserID, getAppState, getCookies, getAutologinInfo, getLicenseInfo, enableAutoSaveAppState, logout.

Xem chữ ký đầy đủ trong index.d.ts và danh sách API tại DOCS.md.

License WEB LEGI

LEGIFCA gửi License Key của sản phẩm legifca tới License Center. License được ràng buộc fingerprint máy và có heartbeat định kỳ. Bản mã nguồn rõ không dùng cơ chế manifest chống sửa code của bản protected; trạng thái integrity được đánh dấu clear-source.

Không sửa productSlug hoặc dùng key của sản phẩm khác.

Lưu AppState

api.enableAutoSaveAppState({
  filePath: "storage/session/appstate.json",
  interval: 10 * 60 * 1000,
  saveOnLogin: true
});

Để mã hóa file:

api.enableAutoSaveAppState({
  filePath: "storage/session/appstate.enc",
  interval: 10 * 60 * 1000,
  encryptionKey: "KHOA-MA-HOA-RIENG"
});

Không commit AppState, Cookie, License Key, API Key Login hoặc secret 2FA lên GitHub/NPM.

Kiểm tra bản phát hành

npm run check
npm test
npm run typecheck
npm run verify

Tạo package npm:

npm pack --ignore-scripts

Tài liệu kèm theo

• docs/CAI-DAT.md — cài đặt và chạy thử.
• docs/CAU-HINH.md — giải thích toàn bộ cấu hình.
• docs/AUTOLOGIN.md — AUTOLOGIN, 2FA, AppState và lỗi Facebook hạn chế.
• docs/MQTT.md — listener, reconnect và lỗi MQTT.
• docs/XU-LY-LOI.md — lỗi thường gặp và cách kiểm tra.
• DOCS.md — API reference.
• SECURITY.md — lưu ý an toàn.
• CHANGELOG.md — lịch sử phiên bản.

Lưu ý

LEGIFCA không phải sản phẩm chính thức của Meta/Facebook. Endpoint nội bộ có thể thay đổi, vì vậy khi API Facebook cập nhật, hãy bật debug ở ứng dụng tích hợp và thu thập lỗi/status/payload đã che dữ liệu nhạy cảm trước khi sửa mã nguồn.