@elizaos/plugin-bluebubbles 2.0.0-alpha.3

package/__tests__/integration.test.ts

@@ -0,0 +1,260 @@
+import { describe, expect, it, vi } from "vitest";
+
+import blueBubblesPlugin, {
+  BLUEBUBBLES_SERVICE_NAME,
+  BlueBubblesService,
+  chatContextProvider,
+  sendMessageAction,
+  sendReactionAction,
+} from "../src/index";
+
+import {
+  normalizeHandle,
+  isHandleAllowed,
+  validateConfig,
+} from "../src/environment";
+
+import {
+  DEFAULT_WEBHOOK_PATH,
+  API_ENDPOINTS,
+  DM_POLICY_OPEN,
+  DM_POLICY_DISABLED,
+  DM_POLICY_PAIRING,
+  DM_POLICY_ALLOWLIST,
+  GROUP_POLICY_OPEN,
+  GROUP_POLICY_ALLOWLIST,
+  GROUP_POLICY_DISABLED,
+} from "../src/constants";
+
+// ----------------------------------------------------------------
+// Plugin exports
+// ----------------------------------------------------------------
+
+describe("BlueBubbles plugin exports", () => {
+  it("exports plugin metadata", () => {
+    expect(blueBubblesPlugin.name).toBe(BLUEBUBBLES_SERVICE_NAME);
+    expect(blueBubblesPlugin.description).toContain("BlueBubbles");
+    expect(Array.isArray(blueBubblesPlugin.actions)).toBe(true);
+    expect(Array.isArray(blueBubblesPlugin.providers)).toBe(true);
+    expect(Array.isArray(blueBubblesPlugin.services)).toBe(true);
+  });
+
+  it("exports actions, providers, and service", () => {
+    expect(sendMessageAction).toBeDefined();
+    expect(sendReactionAction).toBeDefined();
+    expect(chatContextProvider).toBeDefined();
+    expect(BlueBubblesService).toBeDefined();
+  });
+
+  it("registers exactly 2 actions", () => {
+    expect(blueBubblesPlugin.actions).toHaveLength(2);
+  });
+
+  it("registers exactly 1 provider", () => {
+    expect(blueBubblesPlugin.providers).toHaveLength(1);
+  });
+});
+
+// ----------------------------------------------------------------
+// normalizeHandle
+// ----------------------------------------------------------------
+
+describe("normalizeHandle", () => {
+  it("normalizes a formatted US phone number", () => {
+    expect(normalizeHandle("+1 (555) 123-4567")).toBe("+15551234567");
+  });
+
+  it("normalizes a phone number without plus prefix", () => {
+    expect(normalizeHandle("555-123-4567")).toBe("+5551234567");
+  });
+
+  it("normalizes an international phone number", () => {
+    expect(normalizeHandle("+44 7700 900000")).toBe("+447700900000");
+  });
+
+  it("lowercases an email address", () => {
+    expect(normalizeHandle("User@Example.COM")).toBe("user@example.com");
+  });
+
+  it("trims whitespace from an email", () => {
+    expect(normalizeHandle("  test@test.com  ")).toBe("test@test.com");
+  });
+
+  it("handles short digit strings without adding plus", () => {
+    expect(normalizeHandle("12345")).toBe("12345");
+  });
+
+  it("handles a phone number with dots", () => {
+    expect(normalizeHandle("+1.555.123.4567")).toBe("+15551234567");
+  });
+});
+
+// ----------------------------------------------------------------
+// isHandleAllowed
+// ----------------------------------------------------------------
+
+describe("isHandleAllowed", () => {
+  it("open policy allows any handle", () => {
+    expect(isHandleAllowed("anyone@example.com", [], DM_POLICY_OPEN)).toBe(true);
+  });
+
+  it("disabled policy denies all handles", () => {
+    expect(isHandleAllowed("anyone@example.com", [], DM_POLICY_DISABLED)).toBe(false);
+  });
+
+  it("pairing with empty allowlist allows first contact", () => {
+    expect(isHandleAllowed("first@contact.com", [], DM_POLICY_PAIRING)).toBe(true);
+  });
+
+  it("pairing with non-empty allowlist only allows listed handles", () => {
+    expect(isHandleAllowed("+15551234567", ["+15551234567"], DM_POLICY_PAIRING)).toBe(true);
+    expect(isHandleAllowed("+15559999999", ["+15551234567"], DM_POLICY_PAIRING)).toBe(false);
+  });
+
+  it("allowlist matches normalized handles", () => {
+    const allowList = ["+15551234567"];
+    expect(isHandleAllowed("+1 (555) 123-4567", allowList, DM_POLICY_ALLOWLIST)).toBe(true);
+  });
+
+  it("allowlist rejects non-matching handles", () => {
+    const allowList = ["+15551234567"];
+    expect(isHandleAllowed("+15559876543", allowList, DM_POLICY_ALLOWLIST)).toBe(false);
+  });
+
+  it("group open policy allows all", () => {
+    expect(isHandleAllowed("anyone", [], GROUP_POLICY_OPEN)).toBe(true);
+  });
+
+  it("group disabled policy denies all", () => {
+    expect(isHandleAllowed("anyone", [], GROUP_POLICY_DISABLED)).toBe(false);
+  });
+
+  it("group allowlist matches normalized handles", () => {
+    expect(isHandleAllowed("+1 555 123 4567", ["+15551234567"], GROUP_POLICY_ALLOWLIST)).toBe(true);
+  });
+});
+
+// ----------------------------------------------------------------
+// validateConfig
+// ----------------------------------------------------------------
+
+describe("validateConfig", () => {
+  it("accepts a valid config", () => {
+    const config = validateConfig({
+      serverUrl: "http://localhost:1234",
+      password: "secret",
+    });
+    expect(config.serverUrl).toBe("http://localhost:1234");
+    expect(config.password).toBe("secret");
+    expect(config.webhookPath).toBe(DEFAULT_WEBHOOK_PATH);
+    expect(config.dmPolicy).toBe("pairing");
+    expect(config.groupPolicy).toBe("allowlist");
+    expect(config.sendReadReceipts).toBe(true);
+    expect(config.enabled).toBe(true);
+  });
+
+  it("rejects missing server URL", () => {
+    expect(() =>
+      validateConfig({ serverUrl: "", password: "secret" })
+    ).toThrow();
+  });
+
+  it("rejects missing password", () => {
+    expect(() =>
+      validateConfig({ serverUrl: "http://localhost:1234", password: "" })
+    ).toThrow();
+  });
+
+  it("rejects an invalid URL", () => {
+    expect(() =>
+      validateConfig({ serverUrl: "not-a-url", password: "secret" })
+    ).toThrow();
+  });
+
+  it("preserves custom webhook path", () => {
+    const config = validateConfig({
+      serverUrl: "http://localhost:1234",
+      password: "secret",
+      webhookPath: "/custom/webhook",
+    });
+    expect(config.webhookPath).toBe("/custom/webhook");
+  });
+});
+
+// ----------------------------------------------------------------
+// Action definitions
+// ----------------------------------------------------------------
+
+describe("sendMessageAction", () => {
+  it("has the correct name", () => {
+    expect(sendMessageAction.name).toBe("SEND_BLUEBUBBLES_MESSAGE");
+  });
+
+  it("has a non-empty description", () => {
+    expect(sendMessageAction.description).toBeTruthy();
+    expect(sendMessageAction.description!.length).toBeGreaterThan(10);
+  });
+
+  it("has similes", () => {
+    expect(Array.isArray(sendMessageAction.similes)).toBe(true);
+    expect(sendMessageAction.similes!.length).toBeGreaterThan(0);
+  });
+
+  it("has at least one example", () => {
+    expect(Array.isArray(sendMessageAction.examples)).toBe(true);
+    expect(sendMessageAction.examples!.length).toBeGreaterThan(0);
+  });
+
+  it("validate rejects when service is missing", async () => {
+    const mockRuntime = {
+      getService: vi.fn().mockReturnValue(null),
+    } as any;
+    const mockMessage = { content: { source: "bluebubbles" } } as any;
+    const result = await sendMessageAction.validate!(mockRuntime, mockMessage);
+    expect(result).toBe(false);
+  });
+});
+
+describe("sendReactionAction", () => {
+  it("has the correct name", () => {
+    expect(sendReactionAction.name).toBe("BLUEBUBBLES_SEND_REACTION");
+  });
+
+  it("has a non-empty description", () => {
+    expect(sendReactionAction.description).toBeTruthy();
+  });
+
+  it("has similes including BLUEBUBBLES_REACT", () => {
+    expect(sendReactionAction.similes).toContain("BLUEBUBBLES_REACT");
+  });
+
+  it("validate rejects non-bluebubbles sources", async () => {
+    const mockRuntime = {} as any;
+    const mockMessage = { content: { source: "discord" } } as any;
+    const result = await sendReactionAction.validate!(mockRuntime, mockMessage);
+    expect(result).toBe(false);
+  });
+
+  it("validate accepts bluebubbles source", async () => {
+    const mockRuntime = {} as any;
+    const mockMessage = { content: { source: "bluebubbles" } } as any;
+    const result = await sendReactionAction.validate!(mockRuntime, mockMessage);
+    expect(result).toBe(true);
+  });
+});
+
+// ----------------------------------------------------------------
+// Constants
+// ----------------------------------------------------------------
+
+describe("constants", () => {
+  it("has expected API endpoints", () => {
+    expect(API_ENDPOINTS.SEND_MESSAGE).toBeDefined();
+    expect(API_ENDPOINTS.REACT).toBeDefined();
+    expect(API_ENDPOINTS.SERVER_INFO).toBeDefined();
+  });
+
+  it("service name is bluebubbles", () => {
+    expect(BLUEBUBBLES_SERVICE_NAME).toBe("bluebubbles");
+  });
+});

package/build.ts

@@ -0,0 +1,16 @@
+import { execSync } from "node:child_process";
+import { rmSync } from "node:fs";
+import { join } from "node:path";
+
+const distDir = join(import.meta.dirname, "dist");
+
+// Clean
+rmSync(distDir, { recursive: true, force: true });
+
+// Build
+execSync("npx tsc -p tsconfig.json", {
+  cwd: import.meta.dirname,
+  stdio: "inherit",
+});
+
+console.log("Build complete: plugin-bluebubbles");

package/dist/index.js

@@ -0,0 +1,46 @@
+/**
+ * BlueBubbles Plugin for ElizaOS
+ *
+ * Provides iMessage integration via the BlueBubbles macOS app and REST API,
+ * supporting text messages, reactions, effects, and more.
+ */
+import { logger } from "@elizaos/core";
+import { sendMessageAction, sendReactionAction } from "./actions/index.js";
+import { chatContextProvider } from "./providers/index.js";
+import { BlueBubblesService } from "./service.js";
+export * from "./constants.js";
+// Re-export types and service
+export * from "./types.js";
+export { BlueBubblesService };
+export { sendMessageAction, sendReactionAction };
+export { chatContextProvider };
+/**
+ * BlueBubbles plugin for ElizaOS agents.
+ */
+const blueBubblesPlugin = {
+    name: "bluebubbles",
+    description: "BlueBubbles iMessage bridge plugin for ElizaOS agents",
+    services: [BlueBubblesService],
+    actions: [sendMessageAction, sendReactionAction],
+    providers: [chatContextProvider],
+    tests: [],
+    init: async (config, _runtime) => {
+        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;
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@elizaos/plugin-bluebubbles",
+  "version": "2.0.0-alpha.3",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "bun run build.ts",
+    "test": "vitest run",
+    "lint": "biome check --write --unsafe src"
+  },
+  "dependencies": {
+    "@elizaos/core": "2.0.0-alpha.3",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.0.0"
+  },
+  "milaidy": {
+    "platforms": [
+      "node"
+    ],
+    "runtime": "node",
+    "platformDetails": {
+      "node": "Node.js via main entry point"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/actions/index.ts

@@ -0,0 +1,5 @@
+/**
+ * BlueBubbles actions export
+ */
+export { sendMessageAction } from "./sendMessage";
+export { sendReactionAction } from "./sendReaction";

package/src/actions/sendMessage.ts

@@ -0,0 +1,175 @@
+/**
+ * Send message action for BlueBubbles
+ */
+import {
+  type Action,
+  type ActionExample,
+  type ActionResult,
+  type Content,
+  composePromptFromState,
+  type HandlerCallback,
+  type IAgentRuntime,
+  logger,
+  type Memory,
+  ModelType,
+  type State,
+} from "@elizaos/core";
+import { BLUEBUBBLES_SERVICE_NAME } from "../constants";
+import type { BlueBubblesService } from "../service";
+
+const sendMessageTemplate = `
+# Task: Generate a response to send via iMessage (BlueBubbles)
+{{recentMessages}}
+
+# Instructions: Write a response to send to the user via iMessage. Be conversational and friendly.
+Your response should be appropriate for iMessage - keep it relatively concise but engaging.
+`;
+
+const examples: ActionExample[][] = [
+  [
+    {
+      name: "{{user1}}",
+      content: {
+        text: "Can you send a message to John saying I'll be late?",
+      },
+    },
+    {
+      name: "{{agentName}}",
+      content: {
+        text: "I'll send that message to John for you.",
+        action: "SEND_BLUEBUBBLES_MESSAGE",
+      },
+    },
+  ],
+  [
+    {
+      name: "{{user1}}",
+      content: {
+        text: "Reply to this iMessage for me",
+      },
+    },
+    {
+      name: "{{agentName}}",
+      content: {
+        text: "I'll compose and send a reply for you.",
+        action: "SEND_BLUEBUBBLES_MESSAGE",
+      },
+    },
+  ],
+];
+
+export const sendMessageAction: Action = {
+  name: "SEND_BLUEBUBBLES_MESSAGE",
+  description: "Send a message via iMessage through BlueBubbles",
+  similes: [
+    "SEND_IMESSAGE",
+    "TEXT_MESSAGE",
+    "IMESSAGE_REPLY",
+    "BLUEBUBBLES_SEND",
+    "APPLE_MESSAGE",
+  ],
+  examples,
+
+  validate: async (
+    runtime: IAgentRuntime,
+    _message: Memory,
+  ): Promise<boolean> => {
+    const service = runtime.getService<BlueBubblesService>(
+      BLUEBUBBLES_SERVICE_NAME,
+    );
+    return service?.getIsRunning() ?? false;
+  },
+
+  handler: async (
+    runtime: IAgentRuntime,
+    message: Memory,
+    state: State | undefined,
+    _options: Record<string, unknown> | undefined,
+    callback?: HandlerCallback,
+  ): Promise<ActionResult> => {
+    const service = runtime.getService<BlueBubblesService>(
+      BLUEBUBBLES_SERVICE_NAME,
+    );
+    const currentState = state ?? (await runtime.composeState(message));
+
+    if (!service || !service.getIsRunning()) {
+      logger.error("BlueBubbles service is not available");
+      if (callback) {
+        await callback({
+          text: "Sorry, the iMessage service is currently unavailable.",
+        });
+      }
+      return { success: false, error: "BlueBubbles service not available" };
+    }
+
+    try {
+      // Get the room to find the target
+      const room = await runtime.getRoom(message.roomId);
+      if (!room?.channelId) {
+        logger.error("No channel ID found for room");
+        if (callback) {
+          await callback({
+            text: "Unable to determine the message recipient.",
+          });
+        }
+        return { success: false, error: "No channel ID" };
+      }
+
+      // Generate response if state is available
+      const prompt = composePromptFromState({
+        state: currentState,
+        template: sendMessageTemplate,
+      });
+
+      const response = await runtime.useModel(ModelType.TEXT_LARGE, {
+        prompt,
+      });
+
+      const responseText =
+        typeof response === "string"
+          ? response
+          : ((response as { text?: string }).text ?? "");
+
+      if (!responseText.trim()) {
+        logger.warn("Generated empty response, skipping send");
+        return { success: false, error: "Empty response generated" };
+      }
+
+      // Send the message
+      const result = await service.sendMessage(
+        room.channelId,
+        responseText,
+        message.content.inReplyTo as string | undefined,
+      );
+
+      logger.info(`Sent BlueBubbles message: ${result.guid}`);
+
+      const content: Content = {
+        text: responseText,
+        source: "bluebubbles",
+        metadata: {
+          messageGuid: result.guid,
+          chatGuid: room.channelId,
+        },
+      };
+
+      if (callback) {
+        await callback(content);
+      }
+
+      return { success: true, text: responseText };
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      logger.error(`Failed to send BlueBubbles message: ${errorMessage}`);
+
+      if (callback) {
+        await callback({
+          text: "Failed to send the iMessage. Please try again.",
+        });
+      }
+
+      return { success: false, error: errorMessage };
+    }
+  },
+};