@elizaos/plugin-bluebubbles 2.0.0-alpha.3

package/src/environment.ts

@@ -0,0 +1,120 @@
+/**
+ * Environment and configuration validation for BlueBubbles plugin
+ */
+import { z } from "zod";
+import type { IAgentRuntime } from "@elizaos/core";
+import type { BlueBubblesConfig, DmPolicy, GroupPolicy } from "./types";
+
+const DmPolicySchema = z.enum(["open", "pairing", "allowlist", "disabled"]);
+const GroupPolicySchema = z.enum(["open", "allowlist", "disabled"]);
+
+export const BlueBubblesConfigSchema = z.object({
+  serverUrl: z.string().url("Server URL must be a valid URL"),
+  password: z.string().min(1, "Password is required"),
+  webhookPath: z.string().optional().default("/webhooks/bluebubbles"),
+  dmPolicy: DmPolicySchema.optional().default("pairing"),
+  groupPolicy: GroupPolicySchema.optional().default("allowlist"),
+  allowFrom: z.array(z.string()).optional().default([]),
+  groupAllowFrom: z.array(z.string()).optional().default([]),
+  sendReadReceipts: z.boolean().optional().default(true),
+  enabled: z.boolean().optional().default(true),
+});
+
+export type ValidatedBlueBubblesConfig = z.infer<typeof BlueBubblesConfigSchema>;
+
+/**
+ * Validates BlueBubbles configuration
+ */
+export function validateConfig(config: Partial<BlueBubblesConfig>): ValidatedBlueBubblesConfig {
+  return BlueBubblesConfigSchema.parse(config);
+}
+
+/**
+ * Gets BlueBubbles configuration from runtime settings
+ */
+export function getConfigFromRuntime(runtime: IAgentRuntime): BlueBubblesConfig | null {
+  // Helper to safely get string settings
+  const getStringSetting = (key: string): string | undefined => {
+    const value = runtime.getSetting(key);
+    return typeof value === "string" ? value : undefined;
+  };
+
+  const serverUrl = getStringSetting("BLUEBUBBLES_SERVER_URL");
+  const password = getStringSetting("BLUEBUBBLES_PASSWORD");
+
+  if (!serverUrl || !password) {
+    return null;
+  }
+
+  const allowFromRaw = getStringSetting("BLUEBUBBLES_ALLOW_FROM");
+  const groupAllowFromRaw = getStringSetting("BLUEBUBBLES_GROUP_ALLOW_FROM");
+
+  const parseAllowList = (raw: string | undefined): string[] => {
+    if (!raw) return [];
+    return raw.split(",").map((s: string) => s.trim()).filter(Boolean);
+  };
+
+  return {
+    serverUrl,
+    password,
+    webhookPath: getStringSetting("BLUEBUBBLES_WEBHOOK_PATH") ?? "/webhooks/bluebubbles",
+    dmPolicy: (getStringSetting("BLUEBUBBLES_DM_POLICY") as DmPolicy) ?? "pairing",
+    groupPolicy: (getStringSetting("BLUEBUBBLES_GROUP_POLICY") as GroupPolicy) ?? "allowlist",
+    allowFrom: parseAllowList(allowFromRaw),
+    groupAllowFrom: parseAllowList(groupAllowFromRaw),
+    sendReadReceipts: getStringSetting("BLUEBUBBLES_SEND_READ_RECEIPTS") !== "false",
+    enabled: getStringSetting("BLUEBUBBLES_ENABLED") !== "false",
+  };
+}
+
+/**
+ * Normalizes a phone number or email handle
+ */
+export function normalizeHandle(handle: string): string {
+  const trimmed = handle.trim();
+
+  // If it looks like an email, lowercase it
+  if (trimmed.includes("@") && !trimmed.startsWith("+")) {
+    return trimmed.toLowerCase();
+  }
+
+  // For phone numbers, strip non-digits except leading +
+  const startsWithPlus = trimmed.startsWith("+");
+  const digits = trimmed.replace(/\D/g, "");
+
+  // Add + prefix if it was there or if we have 10+ digits (assume international)
+  if (startsWithPlus || digits.length >= 10) {
+    return `+${digits}`;
+  }
+
+  return digits;
+}
+
+/**
+ * Checks if a handle is in the allow list
+ */
+export function isHandleAllowed(
+  handle: string,
+  allowList: string[],
+  policy: DmPolicy | GroupPolicy
+): boolean {
+  if (policy === "open") {
+    return true;
+  }
+
+  if (policy === "disabled") {
+    return false;
+  }
+
+  if (policy === "pairing" || policy === "allowlist") {
+    if (allowList.length === 0 && policy === "pairing") {
+      // Pairing mode with empty allow list allows first contact
+      return true;
+    }
+
+    const normalizedHandle = normalizeHandle(handle);
+    return allowList.some((allowed) => normalizeHandle(allowed) === normalizedHandle);
+  }
+
+  return false;
+}

package/src/index.ts

@@ -0,0 +1,68 @@
+/**
+ * BlueBubbles Plugin for ElizaOS
+ *
+ * Provides iMessage integration via the BlueBubbles macOS app and REST API,
+ * supporting text messages, reactions, effects, and more.
+ */
+
+import type { Plugin, IAgentRuntime } from "@elizaos/core";
+import { logger } from "@elizaos/core";
+import { BlueBubblesService } from "./service.js";
+import { sendMessageAction, sendReactionAction } from "./actions/index.js";
+import { chatContextProvider } from "./providers/index.js";
+import { BLUEBUBBLES_SERVICE_NAME } from "./constants.js";
+
+// Re-export types and service
+export * from "./types.js";
+export * from "./constants.js";
+export { BlueBubblesService };
+export { sendMessageAction, sendReactionAction };
+export { chatContextProvider };
+
+/**
+ * BlueBubbles plugin for ElizaOS agents.
+ */
+const blueBubblesPlugin: Plugin = {
+  name: "bluebubbles",
+  description: "BlueBubbles iMessage bridge plugin for ElizaOS agents",
+
+  services: [BlueBubblesService],
+  actions: [sendMessageAction, sendReactionAction],
+  providers: [chatContextProvider],
+  tests: [],
+
+  init: async (config: Record<string, string>, runtime: IAgentRuntime): Promise<void> => {
+    logger.info("Initializing BlueBubbles plugin...");
+
+    const hasServerUrl = Boolean(
+      config.BLUEBUBBLES_SERVER_URL || process.env.BLUEBUBBLES_SERVER_URL
+    );
+    const hasPassword = Boolean(
+      config.BLUEBUBBLES_PASSWORD || process.env.BLUEBUBBLES_PASSWORD
+    );
+
+    logger.info("BlueBubbles plugin configuration:");
+    logger.info(`  - Server URL configured: ${hasServerUrl ? "Yes" : "No"}`);
+    logger.info(`  - Password configured: ${hasPassword ? "Yes" : "No"}`);
+    logger.info(
+      `  - DM policy: ${config.BLUEBUBBLES_DM_POLICY || process.env.BLUEBUBBLES_DM_POLICY || "pairing"}`
+    );
+    logger.info(
+      `  - Group policy: ${config.BLUEBUBBLES_GROUP_POLICY || process.env.BLUEBUBBLES_GROUP_POLICY || "allowlist"}`
+    );
+
+    if (!hasServerUrl) {
+      logger.warn(
+        "BlueBubbles server URL not configured. Set BLUEBUBBLES_SERVER_URL."
+      );
+    }
+
+    if (!hasPassword) {
+      logger.warn("BlueBubbles password not configured. Set BLUEBUBBLES_PASSWORD.");
+    }
+
+    logger.info("BlueBubbles plugin initialized");
+  },
+};
+
+export default blueBubblesPlugin;

package/src/providers/chatContext.ts

@@ -0,0 +1,105 @@
+/**
+ * Chat context provider for the BlueBubbles plugin.
+ */
+
+import type {
+  IAgentRuntime,
+  Memory,
+  Provider,
+  ProviderResult,
+  State,
+} from "@elizaos/core";
+import { BLUEBUBBLES_SERVICE_NAME } from "../constants.js";
+import type { BlueBubblesService } from "../service.js";
+
+/**
+ * Extract handle from a chat GUID
+ */
+function extractHandleFromChatGuid(chatGuid: string): string | null {
+  if (!chatGuid) return null;
+  // Format: iMessage;-;+1234567890 or iMessage;+;group_id
+  const parts = chatGuid.split(";");
+  if (parts.length >= 3 && parts[1] === "-") {
+    return parts[2];
+  }
+  return null;
+}
+
+export const chatContextProvider: Provider = {
+  name: "bluebubblesChatContext",
+  description:
+    "Provides information about the current BlueBubbles/iMessage chat context",
+
+  get: async (
+    runtime: IAgentRuntime,
+    message: Memory,
+    state: State,
+  ): Promise<ProviderResult> => {
+    // Only provide context for BlueBubbles messages
+    if (message.content.source !== "bluebubbles") {
+      return { text: "" };
+    }
+
+    const bbService = runtime.getService<BlueBubblesService>(
+      BLUEBUBBLES_SERVICE_NAME,
+    );
+
+    if (!bbService || !bbService.isConnected()) {
+      return {
+        values: { connected: false },
+        text: "",
+      };
+    }
+
+    const agentName = state.values?.agentName?.toString() || "The agent";
+    const stateData = (state.data || {}) as Record<string, unknown>;
+
+    const chatGuid = stateData.chatGuid as string | undefined;
+    const handle = stateData.handle as string | undefined;
+    const displayName = stateData.displayName as string | undefined;
+
+    // Determine chat type from GUID
+    let chatType = "direct";
+    let chatDescription = "";
+
+    if (chatGuid) {
+      if (chatGuid.includes(";+;")) {
+        chatType = "group";
+        chatDescription = displayName
+          ? `group chat "${displayName}"`
+          : "a group chat";
+      } else {
+        const extractedHandle = extractHandleFromChatGuid(chatGuid);
+        chatDescription = extractedHandle
+          ? `direct message with ${extractedHandle}`
+          : handle
+            ? `direct message with ${handle}`
+            : "a direct message";
+      }
+    } else if (handle) {
+      chatDescription = `direct message with ${handle}`;
+    } else {
+      chatDescription = "an iMessage conversation";
+    }
+
+    const responseText =
+      `${agentName} is chatting via iMessage (BlueBubbles) in ${chatDescription}. ` +
+      "This channel supports reactions, effects (slam, balloons, confetti, etc.), editing, and replying to messages.";
+
+    return {
+      values: {
+        chatGuid,
+        handle,
+        displayName,
+        chatType,
+        connected: true,
+        platform: "bluebubbles",
+        supportsReactions: true,
+        supportsEffects: true,
+        supportsEdit: true,
+        supportsReply: true,
+      },
+      text: responseText,
+    };
+  },
+};

package/src/providers/chatState.ts

@@ -0,0 +1,90 @@
+/**
+ * Chat state provider for BlueBubbles
+ */
+import {
+  type IAgentRuntime,
+  logger,
+  type Memory,
+  type Provider,
+  type ProviderResult,
+  type State,
+} from "@elizaos/core";
+import { BLUEBUBBLES_SERVICE_NAME } from "../constants";
+import { BlueBubblesService } from "../service";
+import type { BlueBubblesChatState } from "../types";
+
+export const chatStateProvider: Provider = {
+  name: "BLUEBUBBLES_CHAT_STATE",
+  description: "Provides information about the current BlueBubbles/iMessage chat context",
+
+  get: async (
+    runtime: IAgentRuntime,
+    message: Memory,
+    _state: State
+  ): Promise<ProviderResult> => {
+    const service = runtime.getService<BlueBubblesService>(BLUEBUBBLES_SERVICE_NAME);
+
+    if (!service || !service.getIsRunning()) {
+      return { text: "" };
+    }
+
+    try {
+      const room = await runtime.getRoom(message.roomId);
+      if (!room?.channelId) {
+        return { text: "" };
+      }
+
+      // Only provide state for BlueBubbles channels
+      if (room.source !== "bluebubbles") {
+        return { text: "" };
+      }
+
+      const chatState = await service.getChatState(room.channelId);
+      if (!chatState) {
+        return { text: "" };
+      }
+
+      return { text: formatChatState(chatState) };
+    } catch (error) {
+      logger.debug(
+        `Failed to get BlueBubbles chat state: ${error instanceof Error ? error.message : String(error)}`
+      );
+      return { text: "" };
+    }
+  },
+};
+
+/**
+ * Formats the chat state for inclusion in prompts
+ */
+function formatChatState(state: BlueBubblesChatState): string {
+  const lines: string[] = [
+    "# iMessage Chat Context (BlueBubbles)",
+    "",
+    `- Chat Type: ${state.isGroup ? "Group Chat" : "Direct Message"}`,
+  ];
+
+  if (state.displayName) {
+    lines.push(`- Chat Name: ${state.displayName}`);
+  }
+
+  if (state.isGroup) {
+    lines.push(`- Participants: ${state.participants.join(", ")}`);
+  } else {
+    lines.push(`- Contact: ${state.participants[0] ?? state.chatIdentifier}`);
+  }
+
+  if (state.lastMessageAt) {
+    const lastMessageDate = new Date(state.lastMessageAt);
+    lines.push(`- Last Message: ${lastMessageDate.toLocaleString()}`);
+  }
+
+  if (state.hasUnread) {
+    lines.push("- Has Unread Messages: Yes");
+  }
+
+  lines.push("");
+  lines.push("Note: This conversation is happening through iMessage. Be conversational and friendly.");
+
+  return lines.join("\n");
+}

package/src/providers/index.ts

@@ -0,0 +1,5 @@
+/**
+ * BlueBubbles providers export
+ */
+export { chatStateProvider } from "./chatState";
+export { chatContextProvider } from "./chatContext";