@theophilusdev/conduit

A lightweight TypeScript wrapper around @dongdev/fca-unofficial with a clean, middleware-based event system.

import { ConduitClient } from "@theophilusdev/conduit";

const client = new ConduitClient({ listenEvents: true });
await client.login({ appstate });

client.on("message:create", async (ctx) => {
  await ctx.reply(`hey, you said: ${ctx.body}`);
});

Install

npm install @theophilusdev/conduit

Quick Start

import { ConduitClient } from "@theophilusdev/conduit";
import fs from "fs";

const appstate = fs.readFileSync("./appstate.json", "utf-8");
const client = new ConduitClient({ listenEvents: true });

await client.login({ appstate });

client.on("message:create", async (ctx, next) => {
  if (ctx.body === "ping") {
    await ctx.reply("pong");
    return;
  }

  await next();
});

Authentication

Pass one of the following to .login():

Strategy	Field	Notes
App state	appstate	Recommended
Raw cookies	cookies	Cookie header string
Email + password	account.email / account.password	Triggers checkpoints easily — avoid in production

// appstate (recommended)
await client.login({ appstate: [...] });

// raw cookies
await client.login({ cookies: "c_user=...; xs=..." });

// email/password (not recommended)
await client.login({
  account: { email: "...", password: "..." },
});

Events

Register handlers with .on(event, ...middlewares).

Handlers receive a context object and an optional next() function for middleware chaining.

All events include:

• send(body) — send a message to the same thread

Message events additionally include:

• reply(body) — quoted reply to the triggering message
• react(emoji) — react to the triggering message

Both send() and reply() accept a plain string or a ConduitMessageBody object for rich messages with attachments and mentions.

Message Events

Event	Description
message:create	New message received
message:respond	Reply to an existing message
message:remove	Message unsent by sender
message:react	Reaction added or removed
message:writing	Typing indicator (requires listenTyping: true)
message:read	Thread or message marked as read

User Events

Event	Description
user:create	User added to a group thread
user:remove	User left or was removed from a group thread

Thread Events

Event	Description
thread:update	Catch-all for thread updates
thread:title_change	Group title updated
thread:photo_replaced	Group photo changed
thread:theme_changed	Chat theme changed
thread:nickname_changed	Participant nickname updated
thread:admin_changed	Admin role changed

Middleware

.on() accepts multiple handlers. Each must call next() to continue the chain.

client.on(
  "message:create",
  async (ctx, next) => {
    console.log("middleware 1");
    await next();
  },
  async (ctx, next) => {
    console.log("middleware 2");
    await next();
  },
);

Raw FCA Access

Drop down to FCA when needed:

// raw FCA event
client.onFca("presence", async (data) => {
  console.log(data);
});

// raw FCA API (no type safety)
client.api.getThreadList(10, null, ["INBOX"]);

API Reference

See docs/DOCS.md or TypeDoc Documentation for full API details:

• client.messages
• client.threads
• client.users
• client.account

License

GNU GPL v3 © theophilusdev

---

Official GitHub repository: TheophilusWorks/conduit NPM Package: @theophilusdev/conduit Built on top of @dongdev/fca-unofficial FCA.