@theophilusdev/conduit 1.0.0

package/dist/index.cjs

@@ -0,0 +1,648 @@
+'use strict';
+
+var fcaUnofficial = require('@dongdev/fca-unofficial');
+
+// src/client/ConduitClient.ts
+
+// src/utils/toFcaEvent.ts
+var FCA_EVENT_MAP = {
+  "message:create": "message",
+  "message:remove": "message_unsend",
+  "message:react": "message_reaction",
+  "message:respond": "message_reply",
+  "message:writing": "typ",
+  "message:read": "read_receipt",
+  "user:create": "event",
+  // log:subscribe
+  "user:remove": "event",
+  // log:unsubscribe
+  "thread:update": "event",
+  "thread:title_change": "event",
+  // log:thread-name
+  "thread:photo_replaced": "event",
+  // log:thread-image
+  "thread:theme_changed": "event",
+  // log:thread-color
+  "thread:nickname_changed": "event",
+  // log:user-nickname
+  "thread:admin_changed": "event"
+  // log:admin-text
+};
+function toFcaEvent(event) {
+  return FCA_EVENT_MAP[event];
+}
+
+// src/errors/ConduitError.ts
+var ConduitError = class _ConduitError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConduitError";
+  }
+  static new(message) {
+    return new _ConduitError(message);
+  }
+  static uninitializedClient() {
+    return _ConduitError.new(
+      "Conduit client not yet initialized. Please call the .login(credentials) method"
+    );
+  }
+};
+
+// src/api/ConduitMessagesAPI.ts
+var ConduitMessagesAPI = class {
+  constructor(bot) {
+    this.bot = bot;
+  }
+  bot;
+  /**
+   * Sends a message to a thread.
+   * @param body - The message text.
+   * @param threadID - The target thread ID.
+   */
+  send(body, threadID) {
+    return this.bot.ctx.api.sendMessage({ body }, threadID);
+  }
+  /**
+   * Sends a quoted reply to a specific message.
+   * @param body - The reply text.
+   * @param threadID - The target thread ID.
+   * @param messageID - The message ID to reply to.
+   */
+  reply(body, threadID, messageID) {
+    return this.bot.ctx.api.sendMessage(
+      { body },
+      threadID,
+      void 0,
+      messageID
+    );
+  }
+  /**
+   * Edits an existing message.
+   * @param messageID - The message ID to edit.
+   * @param body - The new message text.
+   */
+  edit(messageID, body) {
+    return this.bot.ctx.api.editMessage(body, messageID);
+  }
+  /**
+   * Unsends (retracts) a message sent by the bot.
+   * @param messageID - The message ID to unsend.
+   */
+  unsend(messageID) {
+    return this.bot.ctx.api.unsendMessage(messageID);
+  }
+  /**
+   * Deletes a message.
+   * @param messageID - The message ID to delete.
+   */
+  delete(messageID) {
+    return this.bot.ctx.api.deleteMessage(messageID);
+  }
+  /**
+   * Adds or removes a reaction on a message.
+   * @param emoji - The emoji reaction string.
+   * @param messageID - The target message ID.
+   * @param threadID - The thread the message belongs to.
+   */
+  react(emoji, messageID, threadID) {
+    return this.bot.ctx.api.setMessageReaction(emoji, messageID, threadID);
+  }
+  /**
+   * Sends a typing indicator to a thread.
+   * @param threadID - The target thread ID.
+   */
+  sendTypingIndicator(threadID) {
+    return this.bot.ctx.api.sendTypingIndicator(threadID);
+  }
+  /**
+   * Marks a message as read.
+   * @param messageID - The message ID to mark as read.
+   */
+  markAsRead(messageID) {
+    return this.bot.ctx.api.markAsRead(messageID);
+  }
+  /**
+   * Uploads a file attachment and returns an attachment object.
+   * @param file - A readable stream or file buffer.
+   */
+  uploadAttachment(file) {
+    return this.bot.ctx.api.uploadAttachment(file);
+  }
+  /**
+   * Forwards an existing attachment to another thread.
+   * @param attachmentID - The attachment ID to forward.
+   * @param threadID - The target thread ID.
+   */
+  forwardAttachment(attachmentID, threadID) {
+    return this.bot.ctx.api.forwardAttachment(attachmentID, threadID);
+  }
+  /**
+   * Shares a contact card to a thread.
+   * @param userID - The user ID of the contact to share.
+   * @param threadID - The target thread ID.
+   */
+  shareContact(userID, threadID) {
+    return this.bot.ctx.api.shareContact(userID, threadID);
+  }
+  /**
+   * Changes the color theme of a thread.
+   * @param color - The color hex string.
+   * @param threadID - The target thread ID.
+   */
+  changeThreadColor(color, threadID) {
+    return this.bot.ctx.api.changeThreadColor(color, threadID);
+  }
+  /**
+   * Changes the quick-reaction emoji of a thread.
+   * @param emoji - The emoji string.
+   * @param threadID - The target thread ID.
+   */
+  changeThreadEmoji(emoji, threadID) {
+    return this.bot.ctx.api.changeThreadEmoji(emoji, threadID);
+  }
+  /**
+   * Fetches a specific message by ID.
+   * @param messageID - The message ID to fetch.
+   */
+  getMessage(messageID) {
+    return this.bot.ctx.api.getMessage(messageID);
+  }
+  /**
+   * Returns all available thread color themes.
+   */
+  getThreadColors() {
+    return this.bot.ctx.api.getThreadColors();
+  }
+};
+
+// src/api/ConduitThreadsAPI.ts
+var ConduitThreadsAPI = class {
+  constructor(bot) {
+    this.bot = bot;
+  }
+  bot;
+  /**
+   * Fetches detailed info about a thread.
+   * @param threadID - The thread ID to query.
+   */
+  getInfo(threadID) {
+    return this.bot.ctx.api.getThreadInfo(threadID);
+  }
+  /**
+   * Fetches a paginated list of threads.
+   * @param limit - Number of threads to return.
+   * @param cursor - Pagination cursor, or `null` for the first page.
+   * @param folders - Folder filters e.g. `["INBOX"]`.
+   */
+  getList(limit, cursor, folders) {
+    return this.bot.ctx.api.getThreadList(limit, cursor, folders);
+  }
+  /**
+   * Fetches message history for a thread.
+   * @param threadID - The thread ID to query.
+   * @param limit - Number of messages to return.
+   */
+  getHistory(threadID, limit) {
+    return this.bot.ctx.api.getThreadHistory(threadID, limit);
+  }
+  /**
+   * Searches for threads by name or keyword.
+   * @param query - The search query string.
+   */
+  search(query) {
+    return this.bot.ctx.api.searchForThread(query);
+  }
+  /**
+   * Creates a new group conversation.
+   * @param userIDs - Array of user IDs to add to the group.
+   * @param name - Optional group name.
+   */
+  createGroup(userIDs, name) {
+    return this.bot.ctx.api.createNewGroup(userIDs, name);
+  }
+  /**
+   * Adds a user to an existing group thread.
+   * @param userID - The user ID to add.
+   * @param threadID - The target group thread ID.
+   */
+  addUser(userID, threadID) {
+    return this.bot.ctx.api.addUserToGroup(userID, threadID);
+  }
+  /**
+   * Removes a user from a group thread.
+   * @param userID - The user ID to remove.
+   * @param threadID - The target group thread ID.
+   */
+  removeUser(userID, threadID) {
+    return this.bot.ctx.api.removeUserFromGroup(userID, threadID);
+  }
+  /**
+   * Promotes or demotes a user's admin status in a group.
+   * @param userID - The target user ID.
+   * @param threadID - The group thread ID.
+   * @param admin - `true` to promote, `false` to demote.
+   */
+  changeAdminStatus(userID, threadID, admin) {
+    return this.bot.ctx.api.changeAdminStatus(userID, threadID, admin);
+  }
+  /**
+   * Updates the group's profile image.
+   * @param image - A readable stream or file buffer.
+   * @param threadID - The target group thread ID.
+   */
+  changeGroupImage(image, threadID) {
+    return this.bot.ctx.api.changeGroupImage(image, threadID);
+  }
+  /**
+   * Sets a participant's nickname in a thread.
+   * @param nickname - The new nickname. Pass an empty string to clear.
+   * @param threadID - The thread ID.
+   * @param userID - The target user ID.
+   */
+  changeNickname(nickname, threadID, userID) {
+    return this.bot.ctx.api.changeNickname(nickname, threadID, userID);
+  }
+  /**
+   * Changes the title of a group thread.
+   * @param title - The new group title.
+   * @param threadID - The target group thread ID.
+   */
+  setTitle(title, threadID) {
+    return this.bot.ctx.api.setTitle(title, threadID);
+  }
+  /**
+   * Creates a poll in a thread.
+   * @param title - The poll question.
+   * @param threadID - The target thread ID.
+   * @param options - Array of answer options.
+   */
+  createPoll(title, threadID, options) {
+    return this.bot.ctx.api.createPoll(title, threadID, options);
+  }
+  /**
+   * Deletes a thread.
+   * @param threadID - The thread ID to delete.
+   */
+  delete(threadID) {
+    return this.bot.ctx.api.deleteThread(threadID);
+  }
+  /**
+   * Mutes or unmutes notifications for a thread.
+   * @param threadID - The target thread ID.
+   * @param muteUntil - Timestamp (ms) to mute until. Pass `-1` to mute indefinitely, `0` to unmute.
+   */
+  mute(threadID, muteUntil) {
+    return this.bot.ctx.api.muteThread(threadID, muteUntil);
+  }
+  /**
+   * Accepts or declines a message request.
+   * @param threadID - The thread ID of the request.
+   * @param accept - `true` to accept, `false` to decline.
+   */
+  handleMessageRequest(threadID, accept) {
+    return this.bot.ctx.api.handleMessageRequest(threadID, accept);
+  }
+};
+
+// src/api/ConduitUsersAPI.ts
+var ConduitUsersAPI = class {
+  constructor(bot) {
+    this.bot = bot;
+  }
+  bot;
+  /**
+   * Fetches info for one or more users by ID.
+   * @param userID - A single user ID or an array of user IDs.
+   */
+  getInfo(userID) {
+    return this.bot.ctx.api.getUserInfo(userID);
+  }
+  /**
+   * Resolves a vanity URL or username to a Facebook user ID.
+   * @param vanity - The vanity name or profile URL slug.
+   */
+  getID(vanity) {
+    return this.bot.ctx.api.getUserID(vanity);
+  }
+  /**
+   * Returns the authenticated user's friends list.
+   */
+  getFriendsList() {
+    return this.bot.ctx.api.getFriendsList();
+  }
+};
+
+// src/api/ConduitAccountAPI.ts
+var ConduitAccountAPI = class {
+  constructor(bot) {
+    this.bot = bot;
+  }
+  bot;
+  /**
+   * Returns the logged-in user's Facebook ID.
+   */
+  getCurrentUserID() {
+    return this.bot.ctx.api.getCurrentUserID();
+  }
+  /**
+   * Blocks or unblocks a user.
+   * @param userID - The target user ID.
+   * @param block - `true` to block, `false` to unblock.
+   */
+  blockUser(userID, block) {
+    return this.bot.ctx.api.changeBlockedStatus(userID, block);
+  }
+  /**
+   * Accepts or declines a friend request.
+   * @param userID - The user ID who sent the request.
+   * @param accept - `true` to accept, `false` to decline.
+   */
+  handleFriendRequest(userID, accept) {
+    return this.bot.ctx.api.handleFriendRequest(userID, accept);
+  }
+  /**
+   * Removes a user from the friends list.
+   * @param userID - The target user ID.
+   */
+  unfriend(userID) {
+    return this.bot.ctx.api.unfriend(userID);
+  }
+  /**
+   * Ends the current session and invalidates cookies.
+   */
+  logout() {
+    return this.bot.ctx.api.logout();
+  }
+};
+
+// src/client/ConduitClient.ts
+var FANOUT_EVENTS = /* @__PURE__ */ new Set([
+  "user:create",
+  "user:remove",
+  "thread:update",
+  "thread:title_change",
+  "thread:photo_replaced",
+  "thread:theme_changed",
+  "thread:nickname_changed",
+  "thread:admin_changed"
+]);
+var LOG_MESSAGE_TYPE_MAP = {
+  "log:subscribe": "user:create",
+  "log:unsubscribe": "user:remove",
+  "log:thread-name": "thread:title_change",
+  "log:thread-image": "thread:photo_replaced",
+  "log:thread-color": "thread:theme_changed",
+  "log:user-nickname": "thread:nickname_changed",
+  "log:thread-admins": "thread:admin_changed"
+};
+var ConduitClient = class {
+  /** Underlying FCA bot instance. `null` until {@link login} resolves. */
+  _client;
+  /** Lazily-initialized messages API wrapper. */
+  _messages = null;
+  /** Lazily-initialized threads API wrapper. */
+  _threads = null;
+  /** Lazily-initialized users API wrapper. */
+  _users = null;
+  /** Lazily-initialized account API wrapper. */
+  _account = null;
+  /** Configuration forwarded to the FCA layer on login. */
+  config;
+  /**
+   * Registry of middleware stacks keyed by Conduit event name.
+   * Each stack is executed in insertion order via {@link runStack}.
+   */
+  middlewares;
+  /**
+   * Guards against registering the `threadUpdate` fan-out listener more than once,
+   * regardless of how many fan-out events are subscribed to.
+   */
+  fanOutBound;
+  /**
+   * @param config - Client configuration passed through to the FCA bot.
+   */
+  constructor(config) {
+    this._client = null;
+    this.config = {
+      ...config,
+      logLevel: config.logLevel ?? "silent"
+    };
+    this.middlewares = /* @__PURE__ */ new Map();
+    this.fanOutBound = false;
+  }
+  /**
+   * API for message operations.
+   *
+   * Provides methods for sending messages, replying to threads,
+   * reacting to messages, editing content, deleting messages,
+   * and other message-level interactions.
+   */
+  get messages() {
+    return this._messages ??= new ConduitMessagesAPI(this.client);
+  }
+  /**
+   * API for thread management operations.
+   *
+   * Includes functionality for retrieving thread data,
+   * managing participants, updating thread metadata (such as title),
+   * and handling thread-level features like polls.
+   */
+  get threads() {
+    return this._threads ??= new ConduitThreadsAPI(this.client);
+  }
+  /**
+   * API for user-related operations.
+   *
+   * Supports fetching user profiles, resolving user IDs,
+   * and accessing social graph data such as friends or connections.
+   */
+  get users() {
+    return this._users ??= new ConduitUsersAPI(this.client);
+  }
+  /**
+   * API for account-level operations.
+   *
+   * Exposes actions tied to the authenticated account such as
+   * retrieving the current user ID, managing friend requests,
+   * blocking users, and logging out.
+   */
+  get account() {
+    return this._account ??= new ConduitAccountAPI(this.client);
+  }
+  /**
+   * Authenticates with Messenger and initialises the underlying FCA bot.
+   * Must be called before any events can be received.
+   *
+   * @param credentials - App-state, cookies, or email/password credentials.
+   * @returns The current instance for chaining.
+   */
+  async login(credentials) {
+    this._client = await fcaUnofficial.createMessengerBot(
+      {
+        appState: credentials.appstate,
+        Cookie: credentials.cookies,
+        email: credentials.account?.email,
+        password: credentials.account?.password
+      },
+      this.config
+    );
+    return this;
+  }
+  /**
+   * Registers one or more middleware handlers for a Conduit event.
+   *
+   * The first call for a given event also binds the corresponding FCA listener.
+   * Fan-out events share a single `threadUpdate` FCA binding; all others get
+   * their own dedicated listener via {@link bindConduitEvent}.
+   *
+   * @param event - The Conduit event name to subscribe to.
+   * @param middlewares - Ordered middleware functions to push onto the stack.
+   * @returns The current instance for chaining.
+   */
+  on(event, ...middlewares) {
+    if (!this.middlewares.has(event)) {
+      this.middlewares.set(event, []);
+      if (FANOUT_EVENTS.has(event)) {
+        this.bindFanOutEvents();
+      } else {
+        this.bindConduitEvent(event);
+      }
+    }
+    this.middlewares.get(event).push(...middlewares);
+    return this;
+  }
+  /**
+   * Registers middleware directly against a raw FCA event, bypassing the
+   * Conduit event abstraction entirely. Useful for events not yet mapped
+   * by the Conduit layer.
+   *
+   * @param event - Raw FCA event name.
+   * @param middlewares - Middleware functions receiving the raw FCA payload.
+   * @returns The current instance for chaining.
+   */
+  onFca(event, ...middlewares) {
+    this.client.on(event, async (data) => {
+      await this.runStack(
+        middlewares,
+        data
+      );
+    });
+    return this;
+  }
+  /**
+   * Uses the raw legacy api. Not recommended as this do not
+   * have any type safety and auto-completion features. Use
+   * at your own risk.
+   *
+   * @returns The raw api context.
+   * */
+  get api() {
+    return this.client.ctx.api;
+  }
+  /**
+   * Translates a single Conduit event to its FCA equivalent and attaches a
+   * listener that enriches the raw payload before running the middleware stack.
+   *
+   * @param event - The Conduit event to bind.
+   */
+  bindConduitEvent(event) {
+    const fcaEvent = toFcaEvent(event);
+    this.client.on(fcaEvent, async (raw) => {
+      const stack = this.middlewares.get(event) ?? [];
+      await this.runStack(stack, this.enrich(event, raw));
+    });
+  }
+  /**
+   * Returns the initialized Messenger client instance.
+   *
+   * This getter enforces the client lifecycle by ensuring that the underlying
+   * FCA bot has been created via {@link login} before any access is allowed.
+   *
+   * @throws {ConduitError} If the client has not been initialized yet (login not called).
+   * @returns {MessengerBot} The active Messenger bot instance.
+   */
+  get client() {
+    if (this._client) return this._client;
+    throw ConduitError.uninitializedClient();
+  }
+  /**
+   * Attaches a single `threadUpdate` FCA listener that fans out to all
+   * relevant Conduit events based on the incoming `logMessageType`.
+   *
+   * `thread:update` always fires with the raw payload when its stack is
+   * non-empty. Specific sub-events (e.g. `thread:title_change`) fire only
+   * when their stack is also non-empty and a matching `logMessageType` exists.
+   *
+   * Calling this method more than once is a no-op.
+   */
+  bindFanOutEvents() {
+    if (this.fanOutBound) return;
+    this.fanOutBound = true;
+    this.client.on("threadUpdate", async (raw) => {
+      const { logMessageType } = raw;
+      const updateStack = this.middlewares.get("thread:update") ?? [];
+      if (updateStack.length > 0) {
+        await this.runStack(updateStack, this.enrich("thread:update", raw));
+      }
+      const conduitEvent = LOG_MESSAGE_TYPE_MAP[logMessageType];
+      if (!conduitEvent) return;
+      const stack = this.middlewares.get(conduitEvent) ?? [];
+      if (stack.length === 0) return;
+      await this.runStack(stack, this.enrich(conduitEvent, raw));
+    });
+  }
+  /**
+   * Augments a raw FCA payload with convenience helpers scoped to the event.
+   *
+   * All events receive a `send` helper for replying to the source thread.
+   * Events in the `message:` namespace additionally receive:
+   * - `reply` — sends a quoted reply to the triggering message.
+   * - `react` — sets an emoji reaction on the triggering message.
+   *
+   * @param event - The Conduit event being enriched.
+   * @param raw - The raw FCA payload.
+   * @returns The enriched context object passed to middleware.
+   */
+  enrich(event, raw) {
+    const threadID = raw.threadID;
+    const messageID = raw.messageID;
+    const sendable = {
+      send: (body) => this.messages.send(body, threadID)
+    };
+    if (event.startsWith("message:")) {
+      return {
+        ...raw,
+        ...sendable,
+        reply: (body) => this.messages.reply(body, threadID, messageID),
+        react: (emoji) => this.messages.react(emoji, messageID, threadID)
+      };
+    }
+    return { ...raw, ...sendable };
+  }
+  /**
+   * Executes a middleware stack sequentially, where each handler must call
+   * `next()` to advance to the following handler.
+   *
+   * @param stack - Ordered array of middleware functions to execute.
+   * @param data - The enriched event payload threaded through the stack.
+   */
+  async runStack(stack, data) {
+    let i = 0;
+    const next = async () => {
+      if (i < stack.length) {
+        await stack[i++](data, next);
+      }
+    };
+    await next();
+  }
+};
+
+exports.ConduitAccountAPI = ConduitAccountAPI;
+exports.ConduitClient = ConduitClient;
+exports.ConduitError = ConduitError;
+exports.ConduitMessagesAPI = ConduitMessagesAPI;
+exports.ConduitThreadsAPI = ConduitThreadsAPI;
+exports.ConduitUsersAPI = ConduitUsersAPI;
+exports.toFcaEvent = toFcaEvent;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map