@elizaos/plugin-bluebubbles 2.0.0-alpha.3

package/src/actions/sendReaction.ts

@@ -0,0 +1,186 @@
+/**
+ * Send reaction action for the BlueBubbles plugin.
+ */
+
+import type { Action, ActionResult, IAgentRuntime, Memory, State, HandlerCallback } from "@elizaos/core";
+import {
+  composePromptFromState,
+  logger,
+  ModelType,
+  parseJSONObjectFromText,
+} from "@elizaos/core";
+import { BlueBubblesService } from "../service.js";
+import { BLUEBUBBLES_SERVICE_NAME } from "../constants.js";
+
+const SEND_REACTION_TEMPLATE = `# Task: Extract BlueBubbles reaction parameters
+
+Based on the conversation, determine what reaction to add or remove.
+
+Recent conversation:
+{{recentMessages}}
+
+Extract the following:
+1. emoji: The emoji reaction to add (heart, thumbsup, thumbsdown, haha, exclamation, question, or any emoji)
+2. messageId: The message ID to react to (or "last" for the last message)
+3. remove: true to remove the reaction, false to add it
+
+Respond with a JSON object:
+\`\`\`json
+{
+  "emoji": "❤️",
+  "messageId": "last",
+  "remove": false
+}
+\`\`\`
+`;
+
+interface ReactionParams {
+  emoji: string;
+  messageId: string;
+  remove: boolean;
+}
+
+export const sendReactionAction: Action = {
+  name: "BLUEBUBBLES_SEND_REACTION",
+  similes: ["BLUEBUBBLES_REACT", "BB_REACTION", "IMESSAGE_REACT"],
+  description: "Add or remove a reaction on a message via BlueBubbles",
+
+  validate: async (
+    runtime: IAgentRuntime,
+    message: Memory,
+    _state?: State
+  ): Promise<boolean> => {
+    return message.content.source === "bluebubbles";
+  },
+
+  handler: async (
+    runtime: IAgentRuntime,
+    message: Memory,
+    state: State | undefined,
+    _options?: Record<string, unknown>,
+    callback?: HandlerCallback
+  ): Promise<ActionResult> => {
+    const bbService = runtime.getService<BlueBubblesService>(BLUEBUBBLES_SERVICE_NAME);
+    const currentState = state ?? (await runtime.composeState(message));
+
+    if (!bbService || !bbService.isConnected()) {
+      if (callback) {
+        await callback({ text: "BlueBubbles service is not available.", source: "bluebubbles" });
+      }
+      return { success: false, error: "BlueBubbles service not available" };
+    }
+
+    // Extract parameters using LLM
+    const prompt = await composePromptFromState({
+      template: SEND_REACTION_TEMPLATE,
+      state: currentState,
+    });
+
+    let reactionInfo: ReactionParams | null = null;
+
+    for (let attempt = 0; attempt < 3; attempt++) {
+      const response = await runtime.useModel(ModelType.TEXT_SMALL, {
+        prompt,
+      });
+
+      const parsed = parseJSONObjectFromText(response);
+      if (parsed?.emoji) {
+        reactionInfo = {
+          emoji: String(parsed.emoji),
+          messageId: String(parsed.messageId || "last"),
+          remove: Boolean(parsed.remove),
+        };
+        break;
+      }
+    }
+
+    if (!reactionInfo || !reactionInfo.emoji) {
+      if (callback) {
+        await callback({
+          text: "I couldn't understand the reaction. Please specify an emoji.",
+          source: "bluebubbles",
+        });
+      }
+      return { success: false, error: "Could not extract reaction parameters" };
+    }
+
+    // Get chat context
+    const stateData = (currentState.data || {}) as Record<string, unknown>;
+    const chatGuid = stateData.chatGuid as string;
+    let messageGuid = reactionInfo.messageId;
+
+    if (!chatGuid) {
+      if (callback) {
+        await callback({
+          text: "I couldn't determine the chat to react in.",
+          source: "bluebubbles",
+        });
+      }
+      return { success: false, error: "Could not determine chat" };
+    }
+
+    // If "last", get the last message GUID from context
+    if (messageGuid === "last" || !messageGuid) {
+      messageGuid = stateData.lastMessageGuid as string;
+      if (!messageGuid) {
+        if (callback) {
+          await callback({
+            text: "I couldn't find the message to react to.",
+            source: "bluebubbles",
+          });
+        }
+        return { success: false, error: "Could not find message to react to" };
+      }
+    }
+
+    // Send reaction - we only support adding reactions, not removing
+    // The BlueBubbles API handles remove through a negative reaction type internally
+    const reactionValue = reactionInfo.remove ? `-${reactionInfo.emoji}` : reactionInfo.emoji;
+    const result = await bbService.sendReaction(
+      chatGuid,
+      messageGuid,
+      reactionValue
+    );
+
+    if (!result.success) {
+      if (callback) {
+        await callback({
+          text: `Failed to ${reactionInfo.remove ? "remove" : "add"} reaction.`,
+          source: "bluebubbles",
+        });
+      }
+      return { success: false, error: "Failed to send reaction" };
+    }
+
+    logger.debug(
+      `${reactionInfo.remove ? "Removed" : "Added"} reaction ${reactionInfo.emoji} on ${messageGuid}`
+    );
+
+    if (callback) {
+      await callback({
+        text: reactionInfo.remove
+          ? "Reaction removed."
+          : `Reacted with ${reactionInfo.emoji}.`,
+        source: message.content.source as string,
+      });
+    }
+
+    return { success: true };
+  },
+
+  examples: [
+    [
+      {
+        name: "{{user1}}",
+        content: { text: "React to that message with a heart" },
+      },
+      {
+        name: "{{agent}}",
+        content: {
+          text: "I'll add a heart reaction.",
+          actions: ["BLUEBUBBLES_SEND_REACTION"],
+        },
+      },
+    ],
+  ],
+};

package/src/client.ts

@@ -0,0 +1,389 @@
+/**
+ * BlueBubbles API client for interacting with the BlueBubbles server
+ */
+import { logger } from "@elizaos/core";
+import { API_ENDPOINTS } from "./constants";
+import type {
+  BlueBubblesChat,
+  BlueBubblesConfig,
+  BlueBubblesMessage,
+  BlueBubblesProbeResult,
+  BlueBubblesServerInfo,
+  SendAttachmentOptions,
+  SendMessageOptions,
+  SendMessageResult,
+} from "./types";
+
+export class BlueBubblesClient {
+  private baseUrl: string;
+  private password: string;
+
+  constructor(config: BlueBubblesConfig) {
+    this.baseUrl = config.serverUrl.replace(/\/$/, "");
+    this.password = config.password;
+  }
+
+  private async request<T>(
+    endpoint: string,
+    options: RequestInit = {},
+  ): Promise<T> {
+    const url = `${this.baseUrl}${endpoint}`;
+    const separator = endpoint.includes("?") ? "&" : "?";
+    const urlWithPassword = `${url}${separator}password=${encodeURIComponent(this.password)}`;
+
+    const response = await fetch(urlWithPassword, {
+      ...options,
+      headers: {
+        "Content-Type": "application/json",
+        ...options.headers,
+      },
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(
+        `BlueBubbles API error (${response.status}): ${errorText}`,
+      );
+    }
+
+    return response.json() as Promise<T>;
+  }
+
+  /**
+   * Probes the BlueBubbles server to check connectivity and capabilities
+   */
+  async probe(timeoutMs = 5000): Promise<BlueBubblesProbeResult> {
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+      const info = await this.request<{ data: BlueBubblesServerInfo }>(
+        API_ENDPOINTS.SERVER_INFO,
+        { signal: controller.signal },
+      );
+
+      clearTimeout(timeoutId);
+
+      return {
+        ok: true,
+        serverVersion: info.data.server_version,
+        osVersion: info.data.os_version,
+        privateApiEnabled: info.data.private_api,
+        helperConnected: info.data.helper_connected,
+      };
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      logger.error(`BlueBubbles probe failed: ${errorMessage}`);
+      return {
+        ok: false,
+        error: errorMessage,
+      };
+    }
+  }
+
+  /**
+   * Sends a text message
+   */
+  async sendMessage(
+    chatGuid: string,
+    text: string,
+    options: SendMessageOptions = {},
+  ): Promise<SendMessageResult> {
+    const response = await this.request<{ data: BlueBubblesMessage }>(
+      API_ENDPOINTS.SEND_MESSAGE,
+      {
+        method: "POST",
+        body: JSON.stringify({
+          chatGuid,
+          message: text,
+          tempGuid: options.tempGuid,
+          method: options.method ?? "apple-script",
+          subject: options.subject,
+          effectId: options.effectId,
+          partIndex: options.partIndex,
+          ddScan: options.ddScan,
+        }),
+      },
+    );
+
+    return {
+      guid: response.data.guid,
+      tempGuid: options.tempGuid,
+      status: "sent",
+      dateCreated: response.data.dateCreated,
+      text: response.data.text ?? text,
+    };
+  }
+
+  /**
+   * Sends an attachment
+   */
+  async sendAttachment(
+    chatGuid: string,
+    attachmentPath: string,
+    options: SendAttachmentOptions = {},
+  ): Promise<SendMessageResult> {
+    const formData = new FormData();
+    formData.append("chatGuid", chatGuid);
+    formData.append("attachment", attachmentPath);
+
+    if (options.tempGuid) {
+      formData.append("tempGuid", options.tempGuid);
+    }
+    if (options.name) {
+      formData.append("name", options.name);
+    }
+    if (options.isAudioMessage !== undefined) {
+      formData.append("isAudioMessage", String(options.isAudioMessage));
+    }
+
+    const url = `${this.baseUrl}${API_ENDPOINTS.SEND_ATTACHMENT}?password=${encodeURIComponent(this.password)}`;
+    const response = await fetch(url, {
+      method: "POST",
+      body: formData,
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`Failed to send attachment: ${errorText}`);
+    }
+
+    const result = (await response.json()) as { data: BlueBubblesMessage };
+
+    return {
+      guid: result.data.guid,
+      tempGuid: options.tempGuid,
+      status: "sent",
+      dateCreated: result.data.dateCreated,
+      text: result.data.text ?? "",
+    };
+  }
+
+  /**
+   * Sends an attachment from a buffer
+   */
+  async sendAttachmentBuffer(
+    chatGuid: string,
+    buffer: Uint8Array,
+    filename: string,
+    mimeType: string,
+    caption?: string,
+  ): Promise<SendMessageResult> {
+    const blob = new Blob([buffer], { type: mimeType });
+    const formData = new FormData();
+    formData.append("chatGuid", chatGuid);
+    formData.append("attachment", blob, filename);
+    if (caption) {
+      formData.append("message", caption);
+    }
+
+    const url = `${this.baseUrl}${API_ENDPOINTS.SEND_ATTACHMENT}?password=${encodeURIComponent(this.password)}`;
+    const response = await fetch(url, {
+      method: "POST",
+      body: formData,
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`Failed to send attachment: ${errorText}`);
+    }
+
+    const result = (await response.json()) as { data: BlueBubblesMessage };
+
+    return {
+      guid: result.data.guid,
+      status: "sent",
+      dateCreated: result.data.dateCreated,
+      text: caption ?? "",
+    };
+  }
+
+  /**
+   * Gets information about a chat
+   */
+  async getChat(chatGuid: string): Promise<BlueBubblesChat> {
+    const response = await this.request<{ data: BlueBubblesChat }>(
+      `${API_ENDPOINTS.CHAT_INFO}/${encodeURIComponent(chatGuid)}`,
+    );
+    return response.data;
+  }
+
+  /**
+   * Lists all chats
+   */
+  async listChats(limit = 100, offset = 0): Promise<BlueBubblesChat[]> {
+    const response = await this.request<{ data: BlueBubblesChat[] }>(
+      `${API_ENDPOINTS.CHATS}?limit=${limit}&offset=${offset}&with=lastMessage,participants`,
+    );
+    return response.data;
+  }
+
+  /**
+   * Gets messages for a chat
+   */
+  async getMessages(
+    chatGuid: string,
+    limit = 50,
+    offset = 0,
+  ): Promise<BlueBubblesMessage[]> {
+    const response = await this.request<{ data: BlueBubblesMessage[] }>(
+      `${API_ENDPOINTS.CHAT_INFO}/${encodeURIComponent(chatGuid)}/message?limit=${limit}&offset=${offset}`,
+    );
+    return response.data;
+  }
+
+  /**
+   * Marks a chat as read
+   */
+  async markChatRead(chatGuid: string): Promise<void> {
+    const endpoint = API_ENDPOINTS.MARK_READ.replace(
+      ":guid",
+      encodeURIComponent(chatGuid),
+    );
+    await this.request(endpoint, {
+      method: "POST",
+    });
+  }
+
+  /**
+   * Sends a reaction to a message
+   */
+  async reactToMessage(
+    chatGuid: string,
+    messageGuid: string,
+    reaction: string,
+  ): Promise<void> {
+    await this.request(API_ENDPOINTS.REACT, {
+      method: "POST",
+      body: JSON.stringify({
+        chatGuid,
+        messageGuid,
+        reaction,
+      }),
+    });
+  }
+
+  /**
+   * Edits a message (requires private API)
+   */
+  async editMessage(
+    messageGuid: string,
+    newText: string,
+    backwardsCompatMessage?: string,
+  ): Promise<void> {
+    const endpoint = API_ENDPOINTS.EDIT.replace(
+      ":guid",
+      encodeURIComponent(messageGuid),
+    );
+    await this.request(endpoint, {
+      method: "POST",
+      body: JSON.stringify({
+        editedMessage: newText,
+        backwardsCompatibilityMessage: backwardsCompatMessage ?? newText,
+      }),
+    });
+  }
+
+  /**
+   * Unsends a message (requires private API)
+   */
+  async unsendMessage(messageGuid: string): Promise<void> {
+    const endpoint = API_ENDPOINTS.UNSEND.replace(
+      ":guid",
+      encodeURIComponent(messageGuid),
+    );
+    await this.request(endpoint, {
+      method: "POST",
+    });
+  }
+
+  /**
+   * Resolves a target (handle or chat GUID) to a chat GUID
+   */
+  async resolveTarget(target: string): Promise<string> {
+    // If it already looks like a chat GUID, return it
+    if (target.startsWith("iMessage;") || target.startsWith("SMS;")) {
+      return target;
+    }
+
+    // If it looks like a chat ID or identifier, query for it
+    if (target.startsWith("chat_")) {
+      const chats = await this.listChats();
+      const chat = chats.find(
+        (c) =>
+          c.chatIdentifier === target ||
+          c.guid === target ||
+          c.chatIdentifier.includes(target),
+      );
+      if (chat) {
+        return chat.guid;
+      }
+    }
+
+    // Otherwise, construct a DM chat GUID
+    // First try as iMessage, which is most common
+    return `iMessage;-;${target}`;
+  }
+
+  /**
+   * Creates a new group chat
+   */
+  async createGroupChat(
+    participants: string[],
+    name?: string,
+    message?: string,
+  ): Promise<BlueBubblesChat> {
+    const response = await this.request<{ data: BlueBubblesChat }>(
+      API_ENDPOINTS.CHATS,
+      {
+        method: "POST",
+        body: JSON.stringify({
+          participants,
+          name,
+          message,
+        }),
+      },
+    );
+    return response.data;
+  }
+
+  /**
+   * Adds a participant to a group chat
+   */
+  async addParticipant(chatGuid: string, handle: string): Promise<void> {
+    await this.request(
+      `${API_ENDPOINTS.CHAT_INFO}/${encodeURIComponent(chatGuid)}/participant`,
+      {
+        method: "POST",
+        body: JSON.stringify({ address: handle }),
+      },
+    );
+  }
+
+  /**
+   * Removes a participant from a group chat
+   */
+  async removeParticipant(chatGuid: string, handle: string): Promise<void> {
+    await this.request(
+      `${API_ENDPOINTS.CHAT_INFO}/${encodeURIComponent(chatGuid)}/participant`,
+      {
+        method: "DELETE",
+        body: JSON.stringify({ address: handle }),
+      },
+    );
+  }
+
+  /**
+   * Renames a group chat
+   */
+  async renameGroupChat(chatGuid: string, newName: string): Promise<void> {
+    await this.request(
+      `${API_ENDPOINTS.CHAT_INFO}/${encodeURIComponent(chatGuid)}`,
+      {
+        method: "PATCH",
+        body: JSON.stringify({ displayName: newName }),
+      },
+    );
+  }
+}

package/src/constants.ts

@@ -0,0 +1,41 @@
+/**
+ * Constants for the BlueBubbles plugin
+ */
+
+export const BLUEBUBBLES_SERVICE_NAME = "bluebubbles";
+export const DEFAULT_WEBHOOK_PATH = "/webhooks/bluebubbles";
+export const DEFAULT_TEXT_CHUNK_LIMIT = 4000;
+
+// DM Policy options
+export const DM_POLICY_OPEN = "open";
+export const DM_POLICY_PAIRING = "pairing";
+export const DM_POLICY_ALLOWLIST = "allowlist";
+export const DM_POLICY_DISABLED = "disabled";
+
+// Group Policy options
+export const GROUP_POLICY_OPEN = "open";
+export const GROUP_POLICY_ALLOWLIST = "allowlist";
+export const GROUP_POLICY_DISABLED = "disabled";
+
+// API endpoints
+export const API_ENDPOINTS = {
+  SERVER_INFO: "/api/v1/server/info",
+  SEND_MESSAGE: "/api/v1/message/text",
+  SEND_ATTACHMENT: "/api/v1/message/attachment",
+  CHAT_INFO: "/api/v1/chat",
+  CHATS: "/api/v1/chat",
+  MESSAGES: "/api/v1/message",
+  MARK_READ: "/api/v1/chat/:guid/read",
+  HANDLE_INFO: "/api/v1/handle",
+  REACT: "/api/v1/message/react",
+  EDIT: "/api/v1/message/:guid/edit",
+  UNSEND: "/api/v1/message/:guid/unsend",
+} as const;
+
+// Message types
+export const MESSAGE_TYPES = {
+  TEXT: "text",
+  ATTACHMENT: "attachment",
+  REACTION: "reaction",
+  GROUP_ACTION: "group_action",
+} as const;