@theophilusdev/conduit 1.0.1 → 1.1.2

package/README.md

@@ -5,10 +5,12 @@
 > A lightweight TypeScript wrapper around [`@dongdev/fca-unofficial`](https://github.com/dongp06/fca-unofficial) with a clean, middleware-based event system.
 
 ```ts
-const conduit = new ConduitClient({ listenEvents: true });
-await conduit.login({ appstate });
+import { ConduitClient } from "@theophilusdev/conduit";
 
-conduit.on("message:create", async (ctx) => {
+const client = new ConduitClient({ listenEvents: true });
+await client.login({ appstate });
+
+client.on("message:create", async (ctx) => {
   await ctx.reply(`hey, you said: ${ctx.body}`);
 });
 ```
@@ -22,18 +24,19 @@ npm install @theophilusdev/conduit
 ## Quick Start
 
 ```ts
-import { ConduitClient } from "conduit";
+import { ConduitClient } from "@theophilusdev/conduit";
 import appstate from "./appstate.json" assert { type: "json" };
 
-const conduit = new ConduitClient({ listenEvents: true });
+const client = new ConduitClient({ listenEvents: true });
 
-await conduit.login({ appstate });
+await client.login({ appstate });
 
-conduit.on("message:create", async (ctx, next) => {
+client.on("message:create", async (ctx, next) => {
   if (ctx.body === "ping") {
     await ctx.reply("pong");
     return;
   }
+
   await next();
 });
 ```
@@ -50,56 +53,69 @@ Pass **one** of the following to `.login()`:
 
 ```ts
 // appstate (recommended)
-await conduit.login({ appstate: [...] });
+await client.login({ appstate: [...] });
 
 // raw cookies
-await conduit.login({ cookies: "c_user=...; xs=..." });
+await client.login({ cookies: "c_user=...; xs=..." });
 
 // email/password (not recommended)
-await conduit.login({ account: { email: "...", password: "..." } });
+await client.login({
+  account: { email: "...", password: "..." },
+});
 ```
 
 ## Events
 
-Register handlers with `.on(event, ...middlewares)`. Handlers receive an enriched context object and an optional `next` function to pass control down the stack.
+Register handlers with `.on(event, ...middlewares)`.
+
+Handlers receive a context object and an optional `next()` function for middleware chaining.
+
+All events include:
 
-All events include a `send(body)` helper. Events in the `message:*` namespace additionally include `reply(body)` and `react(emoji)`.
+- `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             | Trigger                                                        |
-| ----------------- | -------------------------------------------------------------- |
-| `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` | User started or stopped typing (requires `listenTyping: true`) |
-| `message:read`    | Thread or message marked as read                               |
+| 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         | Trigger                                      |
+| Event         | Description                                  |
 | ------------- | -------------------------------------------- |
 | `user:create` | User added to a group thread                 |
 | `user:remove` | User left or was removed from a group thread |
 
 ### Thread Events
 
-| Event                     | Trigger                                    |
-| ------------------------- | ------------------------------------------ |
-| `thread:update`           | Any thread metadata change (catch-all)     |
-| `thread:title_change`     | Group title updated                        |
-| `thread:photo_replaced`   | Group photo changed                        |
-| `thread:theme_changed`    | Chat theme or color changed                |
-| `thread:nickname_changed` | A participant's nickname changed           |
-| `thread:admin_changed`    | A participant promoted or demoted as admin |
+| 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 pass control to the next one.
+`.on()` accepts multiple handlers. Each must call `next()` to continue the chain.
 
 ```ts
-conduit.on(
+client.on(
   "message:create",
   async (ctx, next) => {
     console.log("middleware 1");
@@ -114,26 +130,31 @@ conduit.on(
 
 ## Raw FCA Access
 
-For events or methods not yet covered by conduit, you can drop down to the raw FCA layer:
+Drop down to FCA when needed:
 
 ```ts
 // raw FCA event
-conduit.onFca("presence", async (data) => {
+client.onFca("presence", async (data) => {
   console.log(data);
 });
 
-// raw FCA api (no type safety)
-conduit.api.getThreadList(10, null, ["INBOX"]);
+// raw FCA API (no type safety)
+client.api.getThreadList(10, null, ["INBOX"]);
 ```
 
 ## API Reference
 
-See [docs/DOCS.md](docs/DOCS.md) for the full API reference covering `client.messages`, `client.threads`, `client.users`, and `client.account`.
+See [docs/DOCS.md](docs/DOCS.md) for full API details:
+
+- `client.messages`
+- `client.threads`
+- `client.users`
+- `client.account`
 
 ## License
 
-GNU GPL v3 © [theophilusdev](https://github.com/TheophilusWorks)
+GNU GPL v3 © theophilusdev
 
 ---
 
-Built on top of [`@dongdev/fca-unofficial`](https://github.com/dongp06/fca-unofficial). Credit to dongp06 and all contributors to the fca-unofficial project.
+Built on top of [`@dongdev/fca-unofficial`](https://github.com/dongp06/fca-unofficial).

package/docs/DOCS.md

@@ -1,6 +1,6 @@
-# conduit — API Reference
+# Conduit — API Reference
 
-Full reference for all namespaced APIs exposed by `ConduitClient`.
+Full reference for all APIs exposed by `ConduitClient`.
 
 ## Table of Contents
 
@@ -16,28 +16,33 @@ Full reference for all namespaced APIs exposed by `ConduitClient`.
 ## ConduitClient
 
 ```ts
-import { ConduitClient } from "conduit";
+import { ConduitClient } from "@theophilusdev/conduit";
 
-const conduit = new ConduitClient(config);
-await conduit.login(credentials);
+const client = new ConduitClient(config);
+await client.login(credentials);
 ```
 
+---
+
 ### Constructor
 
 ```ts
 new ConduitClient(config: ConduitClientConfig)
 ```
 
-`ConduitClientConfig` extends `MessengerBotOptions` from `@dongdev/fca-unofficial`. The `logLevel` defaults to `"silent"` if not provided.
+Creates a new Conduit client instance.
+
+- Extends `MessengerBotOptions` from `@dongdev/fca-unofficial`
+- `logLevel` defaults to `"silent"`
 
 ---
 
 ### `.login(credentials)`
 
-Authenticates with Messenger and initialises the underlying FCA bot. Must be called before any events can be received.
+Authenticates with Messenger and initializes the client.
 
 ```ts
-await conduit.login(credentials: ConduitCredentials): Promise<ConduitClient>
+await client.login(credentials: ConduitCredentials): Promise<ConduitClient>
 ```
 
 Returns the client instance for chaining.
@@ -46,14 +51,14 @@ Returns the client instance for chaining.
 
 ### `.on(event, ...middlewares)`
 
-Registers one or more middleware handlers for a Conduit event. The first call for a given event also binds the corresponding FCA listener internally.
+Registers one or more middleware handlers for a Conduit event.
 
 ```ts
-conduit.on(event: keyof ConduitEvents, ...middlewares: Middleware[]): this
+client.on(event: keyof ConduitEvents, ...middlewares: Middleware[]): this
 ```
 
 ```ts
-conduit.on("message:create", async (ctx, next) => {
+client.on("message:create", async (ctx, next) => {
   await ctx.reply("hello!");
   await next();
 });
@@ -63,56 +68,80 @@ conduit.on("message:create", async (ctx, next) => {
 
 ### `.onFca(event, ...middlewares)`
 
-Registers middleware directly against a raw FCA event, bypassing the Conduit abstraction. Useful for events not yet mapped by conduit.
+Registers middleware directly on raw FCA events.
 
 ```ts
-conduit.onFca(event: string, ...middlewares): this
+client.onFca(event: string, ...middlewares): this
 ```
 
 ---
 
 ### `.api`
 
-Direct access to the raw FCA api context. No type safety or autocompletion — use as a last resort.
+Direct access to the raw FCA API. No type safety — use as a last resort.
 
 ```ts
-conduit.api.getThreadList(10, null, ["INBOX"]);
+client.api.getThreadList(10, null, ["INBOX"]);
 ```
 
 ---
 
 ## client.messages
 
-Accessible via `conduit.messages`. Handles all message-level operations.
+Accessible via:
+
+```ts
+client.messages;
+```
+
+Handles message-level operations.
 
 ---
 
 ### `.send(body, threadID)`
 
-Sends a plain text message to a thread.
+Sends a message to a thread. Accepts a plain string or a `ConduitMessageBody` for rich messages.
 
 ```ts
-await conduit.messages.send("hello", threadID);
+await client.messages.send("hello", threadID);
+
+await client.messages.send(
+  {
+    body: "hey @user",
+    mentions: [{ tag: "@user", id: "uid", fromIndex: 4 }],
+    attachment: [stream],
+  },
+  threadID,
+);
 ```
 
 ---
 
 ### `.reply(body, threadID, messageID)`
 
-Sends a quoted reply to a specific message.
+Sends a quoted reply to a specific message. Accepts a plain string or a `ConduitMessageBody`.
 
 ```ts
-await conduit.messages.reply("got it", threadID, messageID);
+await client.messages.reply("got it", threadID, messageID);
+
+await client.messages.reply(
+  {
+    body: "got it",
+    attachment: [stream],
+  },
+  threadID,
+  messageID,
+);
 ```
 
 ---
 
 ### `.edit(messageID, body)`
 
-Edits an existing message sent by the bot.
+Edits an existing message.
 
 ```ts
-await conduit.messages.edit(messageID, "updated text");
+await client.messages.edit(messageID, "updated text");
 ```
 
 ---
@@ -122,7 +151,7 @@ await conduit.messages.edit(messageID, "updated text");
 Retracts a message sent by the bot.
 
 ```ts
-await conduit.messages.unsend(messageID);
+await client.messages.unsend(messageID);
 ```
 
 ---
@@ -132,7 +161,7 @@ await conduit.messages.unsend(messageID);
 Deletes a message.
 
 ```ts
-await conduit.messages.delete(messageID);
+await client.messages.delete(messageID);
 ```
 
 ---
@@ -142,17 +171,17 @@ await conduit.messages.delete(messageID);
 Adds or removes a reaction on a message.
 
 ```ts
-await conduit.messages.react("👍", messageID, threadID);
+await client.messages.react("👍", messageID, threadID);
 ```
 
 ---
 
 ### `.sendTypingIndicator(threadID)`
 
-Sends a typing indicator to a thread.
+Sends a typing indicator.
 
 ```ts
-await conduit.messages.sendTypingIndicator(threadID);
+await client.messages.sendTypingIndicator(threadID);
 ```
 
 ---
@@ -162,205 +191,209 @@ await conduit.messages.sendTypingIndicator(threadID);
 Marks a message as read.
 
 ```ts
-await conduit.messages.markAsRead(messageID);
+await client.messages.markAsRead(messageID);
 ```
 
 ---
 
 ### `.uploadAttachment(file)`
 
-Uploads a file attachment and returns an attachment object that can be used in subsequent sends.
+Uploads a file attachment.
 
 ```ts
-const attachment = await conduit.messages.uploadAttachment(stream);
+const attachment = await client.messages.uploadAttachment(stream);
 ```
 
 ---
 
 ### `.forwardAttachment(attachmentID, threadID)`
 
-Forwards an existing attachment to another thread.
+Forwards an attachment to another thread.
 
 ```ts
-await conduit.messages.forwardAttachment(attachmentID, threadID);
+await client.messages.forwardAttachment(attachmentID, threadID);
 ```
 
 ---
 
 ### `.shareContact(userID, threadID)`
 
-Shares a contact card to a thread.
+Shares a contact card.
 
 ```ts
-await conduit.messages.shareContact(userID, threadID);
+await client.messages.shareContact(userID, threadID);
 ```
 
 ---
 
 ### `.changeThreadColor(color, threadID)`
 
-Changes the color theme of a thread.
+Changes thread color.
 
 ```ts
-await conduit.messages.changeThreadColor("#FF0000", threadID);
+await client.messages.changeThreadColor("#FF0000", threadID);
 ```
 
 ---
 
 ### `.changeThreadEmoji(emoji, threadID)`
 
-Changes the quick-reaction emoji of a thread.
+Changes thread emoji.
 
 ```ts
-await conduit.messages.changeThreadEmoji("🔥", threadID);
+await client.messages.changeThreadEmoji("🔥", threadID);
 ```
 
 ---
 
 ### `.getMessage(messageID)`
 
-Fetches a specific message by ID.
+Fetches a message by ID.
 
 ```ts
-const message = await conduit.messages.getMessage(messageID);
+const message = await client.messages.getMessage(messageID);
 ```
 
 ---
 
 ### `.getThreadColors()`
 
-Returns all available thread color themes.
+Returns available thread colors.
 
 ```ts
-const colors = await conduit.messages.getThreadColors();
+const colors = await client.messages.getThreadColors();
 ```
 
 ---
 
 ## client.threads
 
-Accessible via `conduit.threads`. Handles thread-level operations.
+Accessible via:
+
+```ts
+client.threads;
+```
+
+Handles thread-level operations.
 
 ---
 
 ### `.getInfo(threadID)`
 
-Fetches detailed info about a thread including participants, name, and settings.
+Fetches thread information.
 
 ```ts
-const info = await conduit.threads.getInfo(threadID);
+const info = await client.threads.getInfo(threadID);
 ```
 
 ---
 
 ### `.getList(limit, cursor, folders)`
 
-Fetches a paginated list of threads.
+Fetches a list of threads.
 
 ```ts
-const threads = await conduit.threads.getList(10, null, ["INBOX"]);
+const threads = await client.threads.getList(10, null, ["INBOX"]);
 ```
 
 ---
 
 ### `.getHistory(threadID, limit)`
 
-Fetches message history for a thread.
+Fetches message history.
 
 ```ts
-const history = await conduit.threads.getHistory(threadID, 20);
+const history = await client.threads.getHistory(threadID, 20);
 ```
 
 ---
 
 ### `.search(query)`
 
-Searches for threads by name or keyword.
+Searches threads.
 
 ```ts
-const results = await conduit.threads.search("dev chat");
+const results = await client.threads.search("dev chat");
 ```
 
 ---
 
 ### `.createGroup(userIDs, name?)`
 
-Creates a new group conversation.
+Creates a group conversation.
 
 ```ts
-const thread = await conduit.threads.createGroup(["uid1", "uid2"], "my group");
+const thread = await client.threads.createGroup(["uid1", "uid2"], "my group");
 ```
 
 ---
 
 ### `.addUser(userID, threadID)`
 
-Adds a user to an existing group thread.
+Adds a user to a thread.
 
 ```ts
-await conduit.threads.addUser(userID, threadID);
+await client.threads.addUser(userID, threadID);
 ```
 
 ---
 
 ### `.removeUser(userID, threadID)`
 
-Removes a user from a group thread.
+Removes a user from a thread.
 
 ```ts
-await conduit.threads.removeUser(userID, threadID);
+await client.threads.removeUser(userID, threadID);
 ```
 
 ---
 
 ### `.changeAdminStatus(userID, threadID, admin)`
 
-Promotes or demotes a user's admin status in a group.
+Changes admin status.
 
 ```ts
-await conduit.threads.changeAdminStatus(userID, threadID, true); // promote
-await conduit.threads.changeAdminStatus(userID, threadID, false); // demote
+await client.threads.changeAdminStatus(userID, threadID, true);
 ```
 
 ---
 
 ### `.changeGroupImage(image, threadID)`
 
-Updates the group's profile image.
+Updates group image.
 
 ```ts
-await conduit.threads.changeGroupImage(stream, threadID);
+await client.threads.changeGroupImage(stream, threadID);
 ```
 
 ---
 
 ### `.changeNickname(nickname, threadID, userID)`
 
-Sets a participant's nickname. Pass an empty string to clear.
+Sets nickname.
 
 ```ts
-await conduit.threads.changeNickname("nick", threadID, userID);
-await conduit.threads.changeNickname("", threadID, userID); // clear
+await client.threads.changeNickname("nick", threadID, userID);
 ```
 
 ---
 
 ### `.setTitle(title, threadID)`
 
-Changes the title of a group thread.
+Changes thread title.
 
 ```ts
-await conduit.threads.setTitle("new title", threadID);
+await client.threads.setTitle("new title", threadID);
 ```
 
 ---
 
 ### `.createPoll(title, threadID, options)`
 
-Creates a poll in a thread.
+Creates a poll.
 
 ```ts
-await conduit.threads.createPoll("Favourite language?", threadID, [
+await client.threads.createPoll("Favourite language?", threadID, [
   "TypeScript",
   "Python",
 ]);
@@ -373,55 +406,59 @@ await conduit.threads.createPoll("Favourite language?", threadID, [
 Deletes a thread.
 
 ```ts
-await conduit.threads.delete(threadID);
+await client.threads.delete(threadID);
 ```
 
 ---
 
 ### `.mute(threadID, muteUntil)`
 
-Mutes or unmutes notifications for a thread.
+Mutes or unmutes a thread. Pass `-1` to mute indefinitely, `0` to unmute.
 
 ```ts
-await conduit.threads.mute(threadID, -1); // mute indefinitely
-await conduit.threads.mute(threadID, 0); // unmute
+await client.threads.mute(threadID, -1); // mute forever
+await client.threads.mute(threadID, 0); // unmute
 ```
 
 ---
 
 ### `.handleMessageRequest(threadID, accept)`
 
-Accepts or declines a message request.
+Handles message requests.
 
 ```ts
-await conduit.threads.handleMessageRequest(threadID, true);
+await client.threads.handleMessageRequest(threadID, true);
 ```
 
 ---
 
 ## client.users
 
-Accessible via `conduit.users`. Handles user-related operations.
+Accessible via:
+
+```ts
+client.users;
+```
 
 ---
 
 ### `.getInfo(userID)`
 
-Fetches info for one or more users by ID.
+Fetches user info. Accepts a single ID or an array.
 
 ```ts
-const user = await conduit.users.getInfo("uid");
-const users = await conduit.users.getInfo(["uid1", "uid2"]);
+const user = await client.users.getInfo("uid");
+const users = await client.users.getInfo(["uid1", "uid2"]);
 ```
 
 ---
 
 ### `.getID(vanity)`
 
-Resolves a vanity URL or username to a Facebook user ID.
+Resolves a vanity username to a Facebook user ID.
 
 ```ts
-const id = await conduit.users.getID("zuck");
+const id = await client.users.getID("zuck");
 ```
 
 ---
@@ -431,23 +468,27 @@ const id = await conduit.users.getID("zuck");
 Returns the authenticated user's friends list.
 
 ```ts
-const friends = await conduit.users.getFriendsList();
+const friends = await client.users.getFriendsList();
 ```
 
 ---
 
 ## client.account
 
-Accessible via `conduit.account`. Handles account-level operations for the authenticated user.
+Accessible via:
+
+```ts
+client.account;
+```
 
 ---
 
 ### `.getCurrentUserID()`
 
-Returns the logged-in user's Facebook ID synchronously.
+Returns current user ID. Synchronous.
 
 ```ts
-const myID = conduit.account.getCurrentUserID();
+const myID = client.account.getCurrentUserID();
 ```
 
 ---
@@ -457,8 +498,8 @@ const myID = conduit.account.getCurrentUserID();
 Blocks or unblocks a user.
 
 ```ts
-await conduit.account.blockUser(userID, true); // block
-await conduit.account.blockUser(userID, false); // unblock
+await client.account.blockUser(userID, true); // block
+await client.account.blockUser(userID, false); // unblock
 ```
 
 ---
@@ -468,7 +509,7 @@ await conduit.account.blockUser(userID, false); // unblock
 Accepts or declines a friend request.
 
 ```ts
-await conduit.account.handleFriendRequest(userID, true);
+await client.account.handleFriendRequest(userID, true);
 ```
 
 ---
@@ -478,25 +519,23 @@ await conduit.account.handleFriendRequest(userID, true);
 Removes a user from the friends list.
 
 ```ts
-await conduit.account.unfriend(userID);
+await client.account.unfriend(userID);
 ```
 
 ---
 
 ### `.logout()`
 
-Ends the current session and invalidates cookies.
+Ends the session and invalidates cookies.
 
 ```ts
-await conduit.account.logout();
+await client.account.logout();
 ```
 
 ---
 
 ## Types
 
-Key types exported from conduit. See `src/types.ts` for the full source.
-
 ### `ConduitCredentials`
 
 ```ts
@@ -510,6 +549,22 @@ interface ConduitCredentials {
 }
 ```
 
+---
+
+### `ConduitMessageBody`
+
+Used by `send()` and `reply()` for rich messages with attachments and mentions.
+
+```ts
+interface ConduitMessageBody {
+  body?: string;
+  mentions?: { tag: string; id: string; fromIndex: number }[];
+  attachment?: any[];
+}
+```
+
+---
+
 ### `Message`
 
 ```ts
@@ -525,6 +580,8 @@ interface Message {
 }
 ```
 
+---
+
 ### `Middleware<K>`
 
 ```ts
@@ -534,6 +591,8 @@ type Middleware<K extends keyof ConduitEvents> = (
 ) => Promise<void>;
 ```
 
+---
+
 ### `ConduitEvents`
 
-The full map of event names to their payload types. See `src/types.ts` for all payload shapes (`MessageCreatePayload`, `ThreadTitleChangePayload`, etc.).
+Full event map is defined in `src/types.ts`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@theophilusdev/conduit",
   "description": "A simple FCA wrapper library with typescript support",
-  "version": "1.0.1",
+  "version": "1.1.2",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",