tetroxide-fca

Developed by Redwan Ahemed (xemonbae01) · WS method contributed by hoangquyet

Dual-mode Facebook Chat API client for Node.js. Runs on a private WebSocket backend (fastest, E2EE support) with automatic fallback to a direct raw FCA connection if WS is unreachable. Features runtime mode switching, WS auto-recovery, a unified event bridge, and real-time health monitoring — your bot stays alive no matter what.

Install

npm install tetroxide-fca

Requires Node.js >= 18.18.0.

Quick Start

const fca = require("tetroxide-fca");

const api = await fca.connect({ key: "YOUR_API_KEY" });

console.log("Mode:", api.mode);          // "ws" or "raw"
console.log("Bot ID:", api.botInfo.userID);

// Unified listener — works the same in both WS and Raw mode
api.listen((err, event) => {
    if (err) return;
    if (event.type === "message") {
        api.sendMessage(`Echo: ${event.body}`, event.threadID);
    }
});

Connection Modes

| Mode | Behaviour | |---|---| | "auto" (default) | Tries WS first, falls back to raw FCA automatically. Periodically retries WS in the background and switches back when it recovers. | | "ws" | WebSocket only. Fastest, supports E2EE. Throws if unavailable. | | "raw" | Raw FCA (MQTT) only. No WS backend required. |

const api = await fca.connect({ key: "YOUR_KEY" });            // auto
const api = await fca.connect({ mode: "ws", key: "YOUR_KEY" }); // ws only
const api = await fca.connect({ mode: "raw" });                 // raw only

Unified Event Bridge

The bridge (api.ws) is shared across the entire session lifetime. Handlers never get lost during mode switches.

// Works in both modes — no if/else on api.mode needed
api.listen((err, event) => { ... });   // shorthand for bridge.on("*", ...)

api.ws.on("message", (e) => { ... });  // specific event type
api.ws.once("message", (e) => { ... }); // one-shot
const key = api.ws.on("typ", cb);
api.ws.off(key);                        // clean removal

// Promise-based event wait
const event = await api.ws.waitFor("message", 10000); // optional timeout ms

Runtime Mode Switching

Switch modes live while the bot runs. All event handlers survive the switch.

// Force switch to raw FCA right now
await api.switchToRaw({ reason: "maintenance" });

// Switch back to WS when ready
await api.switchToWs({ reason: "upgrade" });

// All method calls route to the current mode automatically — no code changes needed
await api.sendMessage("Still works!", threadID);  // works in WS or raw

Health Monitoring

const h = api.health();

console.log(h.mode);               // "ws" | "raw"
console.log(h.uptime);             // ms since session started
console.log(h.ws.connected);       // WebSocket connection state
console.log(h.ws.failures);        // total WS permanent failures
console.log(h.recovery.active);    // background WS recovery running?
console.log(h.recovery.attempts);  // recovery attempts so far
console.log(h.switches);           // total mode switches
console.log(h.lastSwitch);         // { from, to, reason, at } or null

WS Auto-Recovery

In "auto" mode, when WS permanently fails:

1. Falls back to raw FCA instantly — bot keeps running
2. Background timer retries WS every 5 minutes (configurable)
3. Switches back silently when WS recovers

const api = await fca.connect({
    key: "YOUR_KEY",
    wsRecoveryIntervalMs: 2 * 60 * 1000  // retry every 2 minutes
});

api.on("tetroxide.mode_switch", (e) => {
    console.log(`${e.from} → ${e.to} (${e.reason})`);
});

Session Events

Listen to session lifecycle events via the bridge:

| Event | When | |---|---| | "tetroxide.session_ready" | Session fully initialized | | "tetroxide.mode_switch" | Mode switched (in either direction) | | "tetroxide.ws_fail" | WS permanently failed | | "tetroxide.ws_recovery" | WS recovered | | "tetroxide.session_error" | Fatal error |

Exports

const fca = require("tetroxide-fca");

fca.connect(config)       // main entry point
fca.initFCA(config)       // alias for connect
fca.FCAApi                // WS API class
fca.LocalBridge           // UnifiedBridge class
fca.PrivateWsClient       // WS transport client
fca.SESSION_EVENTS        // session event type constants

Environment Variables

| Variable | Effect | |---|---| | TETROXIDE_LOG_TIMESTAMPS=1 | Add HH:MM:SS timestamps to log lines | | NO_COLOR=1 | Disable ANSI color output | | TETROXIDE_FCA_DISABLE_VERSION_CHECK=1 | Skip npm update check on startup |

Full Documentation

See usage.md for the complete guide: all 147 API methods, all config options, authentication, auto-login, E2EE, runtime switching, health monitoring, examples, and more.

License

MIT — Redwan Ahemed (xemonbae01)