@openclaw/bluebubbles 2026.2.15 → 2026.2.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/bluebubbles",
-  "version": "2026.2.15",
+  "version": "2026.2.17",
   "description": "OpenClaw BlueBubbles channel plugin",
   "type": "module",
   "devDependencies": {

package/src/account-resolve.ts

@@ -0,0 +1,29 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import { resolveBlueBubblesAccount } from "./accounts.js";
+
+export type BlueBubblesAccountResolveOpts = {
+  serverUrl?: string;
+  password?: string;
+  accountId?: string;
+  cfg?: OpenClawConfig;
+};
+
+export function resolveBlueBubblesServerAccount(params: BlueBubblesAccountResolveOpts): {
+  baseUrl: string;
+  password: string;
+  accountId: string;
+} {
+  const account = resolveBlueBubblesAccount({
+    cfg: params.cfg ?? {},
+    accountId: params.accountId,
+  });
+  const baseUrl = params.serverUrl?.trim() || account.config.serverUrl?.trim();
+  const password = params.password?.trim() || account.config.password?.trim();
+  if (!baseUrl) {
+    throw new Error("BlueBubbles serverUrl is required");
+  }
+  if (!password) {
+    throw new Error("BlueBubbles password is required");
+  }
+  return { baseUrl, password, accountId: account.accountId };
+}

package/src/actions.test.ts

@@ -48,6 +48,13 @@ vi.mock("./probe.js", () => ({
 }));
 
 describe("bluebubblesMessageActions", () => {
+  const listActions = bluebubblesMessageActions.listActions!;
+  const supportsAction = bluebubblesMessageActions.supportsAction!;
+  const extractToolSend = bluebubblesMessageActions.extractToolSend!;
+  const handleAction = bluebubblesMessageActions.handleAction!;
+  const callHandleAction = (ctx: Omit<Parameters<typeof handleAction>[0], "channel">) =>
+    handleAction({ channel: "bluebubbles", ...ctx });
+
   beforeEach(() => {
     vi.clearAllMocks();
     vi.mocked(getCachedBlueBubblesPrivateApiStatus).mockReturnValue(null);
@@ -58,7 +65,7 @@ describe("bluebubblesMessageActions", () => {
       const cfg: OpenClawConfig = {
         channels: { bluebubbles: { enabled: false } },
       };
-      const actions = bluebubblesMessageActions.listActions({ cfg });
+      const actions = listActions({ cfg });
       expect(actions).toEqual([]);
     });
 
@@ -66,7 +73,7 @@ describe("bluebubblesMessageActions", () => {
       const cfg: OpenClawConfig = {
         channels: { bluebubbles: { enabled: true } },
       };
-      const actions = bluebubblesMessageActions.listActions({ cfg });
+      const actions = listActions({ cfg });
       expect(actions).toEqual([]);
     });
 
@@ -80,7 +87,7 @@ describe("bluebubblesMessageActions", () => {
           },
         },
       };
-      const actions = bluebubblesMessageActions.listActions({ cfg });
+      const actions = listActions({ cfg });
       expect(actions).toContain("react");
     });
 
@@ -95,7 +102,7 @@ describe("bluebubblesMessageActions", () => {
           },
         },
       };
-      const actions = bluebubblesMessageActions.listActions({ cfg });
+      const actions = listActions({ cfg });
       expect(actions).not.toContain("react");
       // Other actions should still be present
       expect(actions).toContain("edit");
@@ -113,7 +120,7 @@ describe("bluebubblesMessageActions", () => {
           },
         },
       };
-      const actions = bluebubblesMessageActions.listActions({ cfg });
+      const actions = listActions({ cfg });
       expect(actions).toContain("sendAttachment");
       expect(actions).not.toContain("react");
       expect(actions).not.toContain("reply");
@@ -130,31 +137,31 @@ describe("bluebubblesMessageActions", () => {
 
   describe("supportsAction", () => {
     it("returns true for react action", () => {
-      expect(bluebubblesMessageActions.supportsAction({ action: "react" })).toBe(true);
+      expect(supportsAction({ action: "react" })).toBe(true);
     });
 
     it("returns true for all supported actions", () => {
-      expect(bluebubblesMessageActions.supportsAction({ action: "edit" })).toBe(true);
-      expect(bluebubblesMessageActions.supportsAction({ action: "unsend" })).toBe(true);
-      expect(bluebubblesMessageActions.supportsAction({ action: "reply" })).toBe(true);
-      expect(bluebubblesMessageActions.supportsAction({ action: "sendWithEffect" })).toBe(true);
-      expect(bluebubblesMessageActions.supportsAction({ action: "renameGroup" })).toBe(true);
-      expect(bluebubblesMessageActions.supportsAction({ action: "setGroupIcon" })).toBe(true);
-      expect(bluebubblesMessageActions.supportsAction({ action: "addParticipant" })).toBe(true);
-      expect(bluebubblesMessageActions.supportsAction({ action: "removeParticipant" })).toBe(true);
-      expect(bluebubblesMessageActions.supportsAction({ action: "leaveGroup" })).toBe(true);
-      expect(bluebubblesMessageActions.supportsAction({ action: "sendAttachment" })).toBe(true);
+      expect(supportsAction({ action: "edit" })).toBe(true);
+      expect(supportsAction({ action: "unsend" })).toBe(true);
+      expect(supportsAction({ action: "reply" })).toBe(true);
+      expect(supportsAction({ action: "sendWithEffect" })).toBe(true);
+      expect(supportsAction({ action: "renameGroup" })).toBe(true);
+      expect(supportsAction({ action: "setGroupIcon" })).toBe(true);
+      expect(supportsAction({ action: "addParticipant" })).toBe(true);
+      expect(supportsAction({ action: "removeParticipant" })).toBe(true);
+      expect(supportsAction({ action: "leaveGroup" })).toBe(true);
+      expect(supportsAction({ action: "sendAttachment" })).toBe(true);
     });
 
     it("returns false for unsupported actions", () => {
-      expect(bluebubblesMessageActions.supportsAction({ action: "delete" })).toBe(false);
-      expect(bluebubblesMessageActions.supportsAction({ action: "unknown" })).toBe(false);
+      expect(supportsAction({ action: "delete" as never })).toBe(false);
+      expect(supportsAction({ action: "unknown" as never })).toBe(false);
     });
   });
 
   describe("extractToolSend", () => {
     it("extracts send params from sendMessage action", () => {
-      const result = bluebubblesMessageActions.extractToolSend({
+      const result = extractToolSend({
         args: {
           action: "sendMessage",
           to: "+15551234567",
@@ -168,14 +175,14 @@ describe("bluebubblesMessageActions", () => {
     });
 
     it("returns null for non-sendMessage action", () => {
-      const result = bluebubblesMessageActions.extractToolSend({
+      const result = extractToolSend({
         args: { action: "react", to: "+15551234567" },
       });
       expect(result).toBeNull();
     });
 
     it("returns null when to is missing", () => {
-      const result = bluebubblesMessageActions.extractToolSend({
+      const result = extractToolSend({
         args: { action: "sendMessage" },
       });
       expect(result).toBeNull();
@@ -193,8 +200,8 @@ describe("bluebubblesMessageActions", () => {
         },
       };
       await expect(
-        bluebubblesMessageActions.handleAction({
-          action: "unknownAction",
+        callHandleAction({
+          action: "unknownAction" as never,
           params: {},
           cfg,
           accountId: null,
@@ -212,7 +219,7 @@ describe("bluebubblesMessageActions", () => {
         },
       };
       await expect(
-        bluebubblesMessageActions.handleAction({
+        callHandleAction({
           action: "react",
           params: { messageId: "msg-123" },
           cfg,
@@ -232,7 +239,7 @@ describe("bluebubblesMessageActions", () => {
         },
       };
       await expect(
-        bluebubblesMessageActions.handleAction({
+        callHandleAction({
           action: "react",
           params: { emoji: "❤️", messageId: "msg-123", chatGuid: "iMessage;-;+15551234567" },
           cfg,
@@ -251,7 +258,7 @@ describe("bluebubblesMessageActions", () => {
         },
       };
       await expect(
-        bluebubblesMessageActions.handleAction({
+        callHandleAction({
           action: "react",
           params: { emoji: "❤️" },
           cfg,
@@ -273,7 +280,7 @@ describe("bluebubblesMessageActions", () => {
         },
       };
       await expect(
-        bluebubblesMessageActions.handleAction({
+        callHandleAction({
           action: "react",
           params: { emoji: "❤️", messageId: "msg-123", to: "+15551234567" },
           cfg,
@@ -293,7 +300,7 @@ describe("bluebubblesMessageActions", () => {
           },
         },
       };
-      const result = await bluebubblesMessageActions.handleAction({
+      const result = await callHandleAction({
         action: "react",
         params: {
           emoji: "❤️",
@@ -328,7 +335,7 @@ describe("bluebubblesMessageActions", () => {
           },
         },
       };
-      const result = await bluebubblesMessageActions.handleAction({
+      const result = await callHandleAction({
         action: "react",
         params: {
           emoji: "❤️",
@@ -364,7 +371,7 @@ describe("bluebubblesMessageActions", () => {
           },
         },
       };
-      await bluebubblesMessageActions.handleAction({
+      await callHandleAction({
         action: "react",
         params: {
           emoji: "👍",
@@ -394,7 +401,7 @@ describe("bluebubblesMessageActions", () => {
           },
         },
       };
-      await bluebubblesMessageActions.handleAction({
+      await callHandleAction({
         action: "react",
         params: {
           emoji: "😂",
@@ -426,7 +433,7 @@ describe("bluebubblesMessageActions", () => {
           },
         },
       };
-      await bluebubblesMessageActions.handleAction({
+      await callHandleAction({
         action: "react",
         params: {
           emoji: "👍",
@@ -465,7 +472,7 @@ describe("bluebubblesMessageActions", () => {
         },
       };
 
-      await bluebubblesMessageActions.handleAction({
+      await callHandleAction({
         action: "react",
         params: {
           emoji: "❤️",
@@ -500,7 +507,7 @@ describe("bluebubblesMessageActions", () => {
       };
 
       await expect(
-        bluebubblesMessageActions.handleAction({
+        callHandleAction({
           action: "react",
           params: {
             emoji: "❤️",
@@ -525,7 +532,7 @@ describe("bluebubblesMessageActions", () => {
         },
       };
 
-      await bluebubblesMessageActions.handleAction({
+      await callHandleAction({
         action: "edit",
         params: { messageId: "msg-123", message: "updated" },
         cfg,
@@ -551,7 +558,7 @@ describe("bluebubblesMessageActions", () => {
         },
       };
 
-      const result = await bluebubblesMessageActions.handleAction({
+      const result = await callHandleAction({
         action: "sendWithEffect",
         params: {
           message: "peekaboo",
@@ -586,7 +593,7 @@ describe("bluebubblesMessageActions", () => {
 
       const base64Buffer = Buffer.from("voice").toString("base64");
 
-      await bluebubblesMessageActions.handleAction({
+      await callHandleAction({
         action: "sendAttachment",
         params: {
           to: "+15551234567",
@@ -619,7 +626,7 @@ describe("bluebubblesMessageActions", () => {
       };
 
       await expect(
-        bluebubblesMessageActions.handleAction({
+        callHandleAction({
           action: "setGroupIcon",
           params: { chatGuid: "iMessage;-;chat-guid" },
           cfg,
@@ -644,7 +651,7 @@ describe("bluebubblesMessageActions", () => {
       const testBuffer = Buffer.from("fake-image-data");
       const base64Buffer = testBuffer.toString("base64");
 
-      const result = await bluebubblesMessageActions.handleAction({
+      const result = await callHandleAction({
         action: "setGroupIcon",
         params: {
           chatGuid: "iMessage;-;chat-guid",
@@ -681,7 +688,7 @@ describe("bluebubblesMessageActions", () => {
 
       const base64Buffer = Buffer.from("test").toString("base64");
 
-      await bluebubblesMessageActions.handleAction({
+      await callHandleAction({
         action: "setGroupIcon",
         params: {
           chatGuid: "iMessage;-;chat-guid",

package/src/actions.ts

@@ -10,7 +10,6 @@ import {
   type ChannelMessageActionName,
   type ChannelToolSend,
 } from "openclaw/plugin-sdk";
-import type { BlueBubblesSendTarget } from "./types.js";
 import { resolveBlueBubblesAccount } from "./accounts.js";
 import { sendBlueBubblesAttachment } from "./attachments.js";
 import {
@@ -27,6 +26,7 @@ import { getCachedBlueBubblesPrivateApiStatus, isMacOS26OrHigher } from "./probe
 import { sendBlueBubblesReaction } from "./reactions.js";
 import { resolveChatGuidForTarget, sendMessageBlueBubbles } from "./send.js";
 import { normalizeBlueBubblesHandle, parseBlueBubblesTarget } from "./targets.js";
+import type { BlueBubblesSendTarget } from "./types.js";
 
 const providerId = "bluebubbles";
 

package/src/attachments.test.ts

@@ -1,38 +1,18 @@
-import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
-import type { BlueBubblesAttachment } from "./types.js";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import "./test-mocks.js";
 import { downloadBlueBubblesAttachment, sendBlueBubblesAttachment } from "./attachments.js";
 import { getCachedBlueBubblesPrivateApiStatus } from "./probe.js";
-
-vi.mock("./accounts.js", () => ({
-  resolveBlueBubblesAccount: vi.fn(({ cfg, accountId }) => {
-    const config = cfg?.channels?.bluebubbles ?? {};
-    return {
-      accountId: accountId ?? "default",
-      enabled: config.enabled !== false,
-      configured: Boolean(config.serverUrl && config.password),
-      config,
-    };
-  }),
-}));
-
-vi.mock("./probe.js", () => ({
-  getCachedBlueBubblesPrivateApiStatus: vi.fn().mockReturnValue(null),
-}));
+import { installBlueBubblesFetchTestHooks } from "./test-harness.js";
+import type { BlueBubblesAttachment } from "./types.js";
 
 const mockFetch = vi.fn();
 
-describe("downloadBlueBubblesAttachment", () => {
-  beforeEach(() => {
-    vi.stubGlobal("fetch", mockFetch);
-    mockFetch.mockReset();
-    vi.mocked(getCachedBlueBubblesPrivateApiStatus).mockReset();
-    vi.mocked(getCachedBlueBubblesPrivateApiStatus).mockReturnValue(null);
-  });
-
-  afterEach(() => {
-    vi.unstubAllGlobals();
-  });
+installBlueBubblesFetchTestHooks({
+  mockFetch,
+  privateApiStatusMock: vi.mocked(getCachedBlueBubblesPrivateApiStatus),
+});
 
+describe("downloadBlueBubblesAttachment", () => {
   it("throws when guid is missing", async () => {
     const attachment: BlueBubblesAttachment = {};
     await expect(

package/src/attachments.ts

@@ -1,7 +1,7 @@
-import type { OpenClawConfig } from "openclaw/plugin-sdk";
 import crypto from "node:crypto";
 import path from "node:path";
-import { resolveBlueBubblesAccount } from "./accounts.js";
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import { resolveBlueBubblesServerAccount } from "./account-resolve.js";
 import { postMultipartFormData } from "./multipart.js";
 import { getCachedBlueBubblesPrivateApiStatus } from "./probe.js";
 import { extractBlueBubblesMessageId, resolveBlueBubblesSendTarget } from "./send-helpers.js";
@@ -54,19 +54,7 @@ function resolveVoiceInfo(filename: string, contentType?: string) {
 }
 
 function resolveAccount(params: BlueBubblesAttachmentOpts) {
-  const account = resolveBlueBubblesAccount({
-    cfg: params.cfg ?? {},
-    accountId: params.accountId,
-  });
-  const baseUrl = params.serverUrl?.trim() || account.config.serverUrl?.trim();
-  const password = params.password?.trim() || account.config.password?.trim();
-  if (!baseUrl) {
-    throw new Error("BlueBubbles serverUrl is required");
-  }
-  if (!password) {
-    throw new Error("BlueBubbles password is required");
-  }
-  return { baseUrl, password, accountId: account.accountId };
+  return resolveBlueBubblesServerAccount(params);
 }
 
 export async function downloadBlueBubblesAttachment(

package/src/chat.test.ts

@@ -1,37 +1,17 @@
-import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+import { describe, expect, it, vi } from "vitest";
+import "./test-mocks.js";
 import { markBlueBubblesChatRead, sendBlueBubblesTyping, setGroupIconBlueBubbles } from "./chat.js";
 import { getCachedBlueBubblesPrivateApiStatus } from "./probe.js";
-
-vi.mock("./accounts.js", () => ({
-  resolveBlueBubblesAccount: vi.fn(({ cfg, accountId }) => {
-    const config = cfg?.channels?.bluebubbles ?? {};
-    return {
-      accountId: accountId ?? "default",
-      enabled: config.enabled !== false,
-      configured: Boolean(config.serverUrl && config.password),
-      config,
-    };
-  }),
-}));
-
-vi.mock("./probe.js", () => ({
-  getCachedBlueBubblesPrivateApiStatus: vi.fn().mockReturnValue(null),
-}));
+import { installBlueBubblesFetchTestHooks } from "./test-harness.js";
 
 const mockFetch = vi.fn();
 
-describe("chat", () => {
-  beforeEach(() => {
-    vi.stubGlobal("fetch", mockFetch);
-    mockFetch.mockReset();
-    vi.mocked(getCachedBlueBubblesPrivateApiStatus).mockReset();
-    vi.mocked(getCachedBlueBubblesPrivateApiStatus).mockReturnValue(null);
-  });
-
-  afterEach(() => {
-    vi.unstubAllGlobals();
-  });
+installBlueBubblesFetchTestHooks({
+  mockFetch,
+  privateApiStatusMock: vi.mocked(getCachedBlueBubblesPrivateApiStatus),
+});
 
+describe("chat", () => {
   describe("markBlueBubblesChatRead", () => {
     it("does nothing when chatGuid is empty", async () => {
       await markBlueBubblesChatRead("", {

package/src/chat.ts

@@ -1,7 +1,7 @@
-import type { OpenClawConfig } from "openclaw/plugin-sdk";
 import crypto from "node:crypto";
 import path from "node:path";
-import { resolveBlueBubblesAccount } from "./accounts.js";
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import { resolveBlueBubblesServerAccount } from "./account-resolve.js";
 import { postMultipartFormData } from "./multipart.js";
 import { getCachedBlueBubblesPrivateApiStatus } from "./probe.js";
 import { blueBubblesFetchWithTimeout, buildBlueBubblesApiUrl } from "./types.js";
@@ -15,19 +15,7 @@ export type BlueBubblesChatOpts = {
 };
 
 function resolveAccount(params: BlueBubblesChatOpts) {
-  const account = resolveBlueBubblesAccount({
-    cfg: params.cfg ?? {},
-    accountId: params.accountId,
-  });
-  const baseUrl = params.serverUrl?.trim() || account.config.serverUrl?.trim();
-  const password = params.password?.trim() || account.config.password?.trim();
-  if (!baseUrl) {
-    throw new Error("BlueBubbles serverUrl is required");
-  }
-  if (!password) {
-    throw new Error("BlueBubbles password is required");
-  }
-  return { baseUrl, password, accountId: account.accountId };
+  return resolveBlueBubblesServerAccount(params);
 }
 
 function assertPrivateApiEnabled(accountId: string, feature: string): void {

package/src/media-send.test.ts

@@ -1,8 +1,8 @@
-import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
+import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { sendBlueBubblesMedia } from "./media-send.js";
 import { setBlueBubblesRuntime } from "./runtime.js";

package/src/monitor-normalize.ts

@@ -1,5 +1,5 @@
-import type { BlueBubblesAttachment } from "./types.js";
 import { normalizeBlueBubblesHandle } from "./targets.js";
+import type { BlueBubblesAttachment } from "./types.js";
 
 function asRecord(value: unknown): Record<string, unknown> | null {
   return value && typeof value === "object" && !Array.isArray(value)