@openclaw/bluebubbles 2026.3.12 → 2026.3.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/bluebubbles",
-  "version": "2026.3.12",
+  "version": "2026.3.13",
   "description": "OpenClaw BlueBubbles channel plugin",
   "type": "module",
   "dependencies": {

package/src/attachments.test.ts

@@ -82,6 +82,15 @@ describe("downloadBlueBubblesAttachment", () => {
     ).rejects.toThrow("too large");
   }
 
+  function mockSuccessfulAttachmentDownload(buffer = new Uint8Array([1])) {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      headers: new Headers(),
+      arrayBuffer: () => Promise.resolve(buffer.buffer),
+    });
+    return buffer;
+  }
+
   it("throws when guid is missing", async () => {
     const attachment: BlueBubblesAttachment = {};
     await expect(
@@ -159,12 +168,7 @@ describe("downloadBlueBubblesAttachment", () => {
   });
 
   it("encodes guid in URL", async () => {
-    const mockBuffer = new Uint8Array([1]);
-    mockFetch.mockResolvedValueOnce({
-      ok: true,
-      headers: new Headers(),
-      arrayBuffer: () => Promise.resolve(mockBuffer.buffer),
-    });
+    mockSuccessfulAttachmentDownload();
 
     const attachment: BlueBubblesAttachment = { guid: "att/with/special chars" };
     await downloadBlueBubblesAttachment(attachment, {
@@ -244,12 +248,7 @@ describe("downloadBlueBubblesAttachment", () => {
   });
 
   it("resolves credentials from config when opts not provided", async () => {
-    const mockBuffer = new Uint8Array([1]);
-    mockFetch.mockResolvedValueOnce({
-      ok: true,
-      headers: new Headers(),
-      arrayBuffer: () => Promise.resolve(mockBuffer.buffer),
-    });
+    mockSuccessfulAttachmentDownload();
 
     const attachment: BlueBubblesAttachment = { guid: "att-config" };
     const result = await downloadBlueBubblesAttachment(attachment, {
@@ -270,12 +269,7 @@ describe("downloadBlueBubblesAttachment", () => {
   });
 
   it("passes ssrfPolicy with allowPrivateNetwork when config enables it", async () => {
-    const mockBuffer = new Uint8Array([1]);
-    mockFetch.mockResolvedValueOnce({
-      ok: true,
-      headers: new Headers(),
-      arrayBuffer: () => Promise.resolve(mockBuffer.buffer),
-    });
+    mockSuccessfulAttachmentDownload();
 
     const attachment: BlueBubblesAttachment = { guid: "att-ssrf" };
     await downloadBlueBubblesAttachment(attachment, {
@@ -295,12 +289,7 @@ describe("downloadBlueBubblesAttachment", () => {
   });
 
   it("auto-allowlists serverUrl hostname when allowPrivateNetwork is not set", async () => {
-    const mockBuffer = new Uint8Array([1]);
-    mockFetch.mockResolvedValueOnce({
-      ok: true,
-      headers: new Headers(),
-      arrayBuffer: () => Promise.resolve(mockBuffer.buffer),
-    });
+    mockSuccessfulAttachmentDownload();
 
     const attachment: BlueBubblesAttachment = { guid: "att-no-ssrf" };
     await downloadBlueBubblesAttachment(attachment, {
@@ -313,12 +302,7 @@ describe("downloadBlueBubblesAttachment", () => {
   });
 
   it("auto-allowlists private IP serverUrl hostname when allowPrivateNetwork is not set", async () => {
-    const mockBuffer = new Uint8Array([1]);
-    mockFetch.mockResolvedValueOnce({
-      ok: true,
-      headers: new Headers(),
-      arrayBuffer: () => Promise.resolve(mockBuffer.buffer),
-    });
+    mockSuccessfulAttachmentDownload();
 
     const attachment: BlueBubblesAttachment = { guid: "att-private-ip" };
     await downloadBlueBubblesAttachment(attachment, {
@@ -352,6 +336,14 @@ describe("sendBlueBubblesAttachment", () => {
     return Buffer.from(body).toString("utf8");
   }
 
+  function expectVoiceAttachmentBody() {
+    const body = mockFetch.mock.calls[0][1]?.body as Uint8Array;
+    const bodyText = decodeBody(body);
+    expect(bodyText).toContain('name="isAudioMessage"');
+    expect(bodyText).toContain("true");
+    return bodyText;
+  }
+
   it("marks voice memos when asVoice is true and mp3 is provided", async () => {
     mockFetch.mockResolvedValueOnce({
       ok: true,
@@ -367,10 +359,7 @@ describe("sendBlueBubblesAttachment", () => {
       opts: { serverUrl: "http://localhost:1234", password: "test" },
     });
 
-    const body = mockFetch.mock.calls[0][1]?.body as Uint8Array;
-    const bodyText = decodeBody(body);
-    expect(bodyText).toContain('name="isAudioMessage"');
-    expect(bodyText).toContain("true");
+    const bodyText = expectVoiceAttachmentBody();
     expect(bodyText).toContain('filename="voice.mp3"');
   });
 
@@ -389,8 +378,7 @@ describe("sendBlueBubblesAttachment", () => {
       opts: { serverUrl: "http://localhost:1234", password: "test" },
     });
 
-    const body = mockFetch.mock.calls[0][1]?.body as Uint8Array;
-    const bodyText = decodeBody(body);
+    const bodyText = expectVoiceAttachmentBody();
     expect(bodyText).toContain('filename="voice.mp3"');
     expect(bodyText).toContain('name="voice.mp3"');
   });

package/src/attachments.ts

@@ -2,7 +2,7 @@ import crypto from "node:crypto";
 import path from "node:path";
 import type { OpenClawConfig } from "openclaw/plugin-sdk/bluebubbles";
 import { resolveBlueBubblesServerAccount } from "./account-resolve.js";
-import { postMultipartFormData } from "./multipart.js";
+import { assertMultipartActionOk, postMultipartFormData } from "./multipart.js";
 import {
   getCachedBlueBubblesPrivateApiStatus,
   isBlueBubblesPrivateApiStatusEnabled,
@@ -262,12 +262,7 @@ export async function sendBlueBubblesAttachment(params: {
     timeoutMs: opts.timeoutMs ?? 60_000, // longer timeout for file uploads
   });
 
-  if (!res.ok) {
-    const errorText = await res.text();
-    throw new Error(
-      `BlueBubbles attachment send failed (${res.status}): ${errorText || "unknown"}`,
-    );
-  }
+  await assertMultipartActionOk(res, "attachment send");
 
   const responseBody = await res.text();
   if (!responseBody) {

package/src/chat.test.ts

@@ -29,6 +29,11 @@ describe("chat", () => {
     });
   }
 
+  function mockTwoOkTextResponses() {
+    mockOkTextResponse();
+    mockOkTextResponse();
+  }
+
   async function expectCalledUrlIncludesPassword(params: {
     password: string;
     invoke: () => Promise<void>;
@@ -198,15 +203,7 @@ describe("chat", () => {
     });
 
     it("uses POST for start and DELETE for stop", async () => {
-      mockFetch
-        .mockResolvedValueOnce({
-          ok: true,
-          text: () => Promise.resolve(""),
-        })
-        .mockResolvedValueOnce({
-          ok: true,
-          text: () => Promise.resolve(""),
-        });
+      mockTwoOkTextResponses();
 
       await sendBlueBubblesTyping("iMessage;-;+15551234567", true, {
         serverUrl: "http://localhost:1234",
@@ -442,15 +439,7 @@ describe("chat", () => {
     });
 
     it("adds and removes participant using matching endpoint", async () => {
-      mockFetch
-        .mockResolvedValueOnce({
-          ok: true,
-          text: () => Promise.resolve(""),
-        })
-        .mockResolvedValueOnce({
-          ok: true,
-          text: () => Promise.resolve(""),
-        });
+      mockTwoOkTextResponses();
 
       await addBlueBubblesParticipant("chat-guid", "+15551234567", {
         serverUrl: "http://localhost:1234",

package/src/chat.ts

@@ -2,7 +2,7 @@ import crypto from "node:crypto";
 import path from "node:path";
 import type { OpenClawConfig } from "openclaw/plugin-sdk/bluebubbles";
 import { resolveBlueBubblesServerAccount } from "./account-resolve.js";
-import { postMultipartFormData } from "./multipart.js";
+import { assertMultipartActionOk, postMultipartFormData } from "./multipart.js";
 import { getCachedBlueBubblesPrivateApiStatus } from "./probe.js";
 import { blueBubblesFetchWithTimeout, buildBlueBubblesApiUrl } from "./types.js";
 
@@ -55,12 +55,7 @@ async function sendBlueBubblesChatEndpointRequest(params: {
     { method: params.method },
     params.opts.timeoutMs,
   );
-  if (!res.ok) {
-    const errorText = await res.text().catch(() => "");
-    throw new Error(
-      `BlueBubbles ${params.action} failed (${res.status}): ${errorText || "unknown"}`,
-    );
-  }
+  await assertMultipartActionOk(res, params.action);
 }
 
 async function sendPrivateApiJsonRequest(params: {
@@ -86,12 +81,7 @@ async function sendPrivateApiJsonRequest(params: {
   }
 
   const res = await blueBubblesFetchWithTimeout(url, request, params.opts.timeoutMs);
-  if (!res.ok) {
-    const errorText = await res.text().catch(() => "");
-    throw new Error(
-      `BlueBubbles ${params.action} failed (${res.status}): ${errorText || "unknown"}`,
-    );
-  }
+  await assertMultipartActionOk(res, params.action);
 }
 
 export async function markBlueBubblesChatRead(
@@ -329,8 +319,5 @@ export async function setGroupIconBlueBubbles(
     timeoutMs: opts.timeoutMs ?? 60_000, // longer timeout for file uploads
   });
 
-  if (!res.ok) {
-    const errorText = await res.text().catch(() => "");
-    throw new Error(`BlueBubbles setGroupIcon failed (${res.status}): ${errorText || "unknown"}`);
-  }
+  await assertMultipartActionOk(res, "setGroupIcon");
 }

package/src/media-send.test.ts

@@ -70,6 +70,70 @@ async function makeTempDir(): Promise<string> {
   return dir;
 }
 
+async function makeTempFile(
+  fileName: string,
+  contents: string,
+  dir?: string,
+): Promise<{ dir: string; filePath: string }> {
+  const resolvedDir = dir ?? (await makeTempDir());
+  const filePath = path.join(resolvedDir, fileName);
+  await fs.writeFile(filePath, contents, "utf8");
+  return { dir: resolvedDir, filePath };
+}
+
+async function sendLocalMedia(params: {
+  cfg: OpenClawConfig;
+  mediaPath: string;
+  accountId?: string;
+}) {
+  return sendBlueBubblesMedia({
+    cfg: params.cfg,
+    to: "chat:123",
+    accountId: params.accountId,
+    mediaPath: params.mediaPath,
+  });
+}
+
+async function expectRejectedLocalMedia(params: {
+  cfg: OpenClawConfig;
+  mediaPath: string;
+  error: RegExp;
+  accountId?: string;
+}) {
+  await expect(
+    sendLocalMedia({
+      cfg: params.cfg,
+      mediaPath: params.mediaPath,
+      accountId: params.accountId,
+    }),
+  ).rejects.toThrow(params.error);
+
+  expect(sendBlueBubblesAttachmentMock).not.toHaveBeenCalled();
+}
+
+async function expectAllowedLocalMedia(params: {
+  cfg: OpenClawConfig;
+  mediaPath: string;
+  expectedAttachment: Record<string, unknown>;
+  accountId?: string;
+  expectMimeDetection?: boolean;
+}) {
+  const result = await sendLocalMedia({
+    cfg: params.cfg,
+    mediaPath: params.mediaPath,
+    accountId: params.accountId,
+  });
+
+  expect(result).toEqual({ messageId: "msg-1" });
+  expect(sendBlueBubblesAttachmentMock).toHaveBeenCalledTimes(1);
+  expect(sendBlueBubblesAttachmentMock.mock.calls[0]?.[0]).toEqual(
+    expect.objectContaining(params.expectedAttachment),
+  );
+  if (params.expectMimeDetection) {
+    expect(runtimeMocks.detectMime).toHaveBeenCalled();
+  }
+}
+
 beforeEach(() => {
   const runtime = createMockRuntime();
   runtimeMocks = runtime.mocks;
@@ -110,57 +174,43 @@ describe("sendBlueBubblesMedia local-path hardening", () => {
     const outsideFile = path.join(outsideDir, "outside.txt");
     await fs.writeFile(outsideFile, "not allowed", "utf8");
 
-    await expect(
-      sendBlueBubblesMedia({
-        cfg: createConfig({ mediaLocalRoots: [allowedRoot] }),
-        to: "chat:123",
-        mediaPath: outsideFile,
-      }),
-    ).rejects.toThrow(/not under any configured mediaLocalRoots/i);
-
-    expect(sendBlueBubblesAttachmentMock).not.toHaveBeenCalled();
+    await expectRejectedLocalMedia({
+      cfg: createConfig({ mediaLocalRoots: [allowedRoot] }),
+      mediaPath: outsideFile,
+      error: /not under any configured mediaLocalRoots/i,
+    });
   });
 
   it("allows local paths that are explicitly configured", async () => {
-    const allowedRoot = await makeTempDir();
-    const allowedFile = path.join(allowedRoot, "allowed.txt");
-    await fs.writeFile(allowedFile, "allowed", "utf8");
+    const { dir: allowedRoot, filePath: allowedFile } = await makeTempFile(
+      "allowed.txt",
+      "allowed",
+    );
 
-    const result = await sendBlueBubblesMedia({
+    await expectAllowedLocalMedia({
       cfg: createConfig({ mediaLocalRoots: [allowedRoot] }),
-      to: "chat:123",
       mediaPath: allowedFile,
-    });
-
-    expect(result).toEqual({ messageId: "msg-1" });
-    expect(sendBlueBubblesAttachmentMock).toHaveBeenCalledTimes(1);
-    expect(sendBlueBubblesAttachmentMock.mock.calls[0]?.[0]).toEqual(
-      expect.objectContaining({
+      expectedAttachment: {
         filename: "allowed.txt",
         contentType: "text/plain",
-      }),
-    );
-    expect(runtimeMocks.detectMime).toHaveBeenCalled();
+      },
+      expectMimeDetection: true,
+    });
   });
 
   it("allows file:// media paths and file:// local roots", async () => {
-    const allowedRoot = await makeTempDir();
-    const allowedFile = path.join(allowedRoot, "allowed.txt");
-    await fs.writeFile(allowedFile, "allowed", "utf8");
+    const { dir: allowedRoot, filePath: allowedFile } = await makeTempFile(
+      "allowed.txt",
+      "allowed",
+    );
 
-    const result = await sendBlueBubblesMedia({
+    await expectAllowedLocalMedia({
       cfg: createConfig({ mediaLocalRoots: [pathToFileURL(allowedRoot).toString()] }),
-      to: "chat:123",
       mediaPath: pathToFileURL(allowedFile).toString(),
-    });
-
-    expect(result).toEqual({ messageId: "msg-1" });
-    expect(sendBlueBubblesAttachmentMock).toHaveBeenCalledTimes(1);
-    expect(sendBlueBubblesAttachmentMock.mock.calls[0]?.[0]).toEqual(
-      expect.objectContaining({
+      expectedAttachment: {
         filename: "allowed.txt",
-      }),
-    );
+      },
+    });
   });
 
   it("uses account-specific mediaLocalRoots over top-level roots", async () => {
@@ -213,15 +263,11 @@ describe("sendBlueBubblesMedia local-path hardening", () => {
       return;
     }
 
-    await expect(
-      sendBlueBubblesMedia({
-        cfg: createConfig({ mediaLocalRoots: [allowedRoot] }),
-        to: "chat:123",
-        mediaPath: linkPath,
-      }),
-    ).rejects.toThrow(/not under any configured mediaLocalRoots/i);
-
-    expect(sendBlueBubblesAttachmentMock).not.toHaveBeenCalled();
+    await expectRejectedLocalMedia({
+      cfg: createConfig({ mediaLocalRoots: [allowedRoot] }),
+      mediaPath: linkPath,
+      error: /not under any configured mediaLocalRoots/i,
+    });
   });
 
   it("rejects relative mediaLocalRoots entries", async () => {

package/src/monitor-normalize.test.ts

@@ -1,18 +1,24 @@
 import { describe, expect, it } from "vitest";
 import { normalizeWebhookMessage, normalizeWebhookReaction } from "./monitor-normalize.js";
 
+function createFallbackDmPayload(overrides: Record<string, unknown> = {}) {
+  return {
+    guid: "msg-1",
+    isGroup: false,
+    isFromMe: false,
+    handle: null,
+    chatGuid: "iMessage;-;+15551234567",
+    ...overrides,
+  };
+}
+
 describe("normalizeWebhookMessage", () => {
   it("falls back to DM chatGuid handle when sender handle is missing", () => {
     const result = normalizeWebhookMessage({
       type: "new-message",
-      data: {
-        guid: "msg-1",
+      data: createFallbackDmPayload({
         text: "hello",
-        isGroup: false,
-        isFromMe: false,
-        handle: null,
-        chatGuid: "iMessage;-;+15551234567",
-      },
+      }),
     });
 
     expect(result).not.toBeNull();
@@ -78,15 +84,11 @@ describe("normalizeWebhookReaction", () => {
   it("falls back to DM chatGuid handle when reaction sender handle is missing", () => {
     const result = normalizeWebhookReaction({
       type: "updated-message",
-      data: {
+      data: createFallbackDmPayload({
         guid: "msg-2",
         associatedMessageGuid: "p:0/msg-1",
         associatedMessageType: 2000,
-        isGroup: false,
-        isFromMe: false,
-        handle: null,
-        chatGuid: "iMessage;-;+15551234567",
-      },
+      }),
     });
 
     expect(result).not.toBeNull();

package/src/monitor-normalize.ts

@@ -582,6 +582,29 @@ export function parseTapbackText(params: {
     return null;
   }
 
+  const parseLeadingReactionAction = (
+    prefix: "reacted" | "removed",
+    defaultAction: "added" | "removed",
+  ) => {
+    if (!lower.startsWith(prefix)) {
+      return null;
+    }
+    const emoji = extractFirstEmoji(trimmed) ?? params.emojiHint;
+    if (!emoji) {
+      return null;
+    }
+    const quotedText = extractQuotedTapbackText(trimmed);
+    if (params.requireQuoted && !quotedText) {
+      return null;
+    }
+    const fallback = trimmed.slice(prefix.length).trim();
+    return {
+      emoji,
+      action: params.actionHint ?? defaultAction,
+      quotedText: quotedText ?? fallback,
+    };
+  };
+
   for (const [pattern, { emoji, action }] of TAPBACK_TEXT_MAP) {
     if (lower.startsWith(pattern)) {
       // Extract quoted text if present (e.g., 'Loved "hello"' -> "hello")
@@ -599,30 +622,14 @@ export function parseTapbackText(params: {
     }
   }
 
-  if (lower.startsWith("reacted")) {
-    const emoji = extractFirstEmoji(trimmed) ?? params.emojiHint;
-    if (!emoji) {
-      return null;
-    }
-    const quotedText = extractQuotedTapbackText(trimmed);
-    if (params.requireQuoted && !quotedText) {
-      return null;
-    }
-    const fallback = trimmed.slice("reacted".length).trim();
-    return { emoji, action: params.actionHint ?? "added", quotedText: quotedText ?? fallback };
+  const reacted = parseLeadingReactionAction("reacted", "added");
+  if (reacted) {
+    return reacted;
   }
 
-  if (lower.startsWith("removed")) {
-    const emoji = extractFirstEmoji(trimmed) ?? params.emojiHint;
-    if (!emoji) {
-      return null;
-    }
-    const quotedText = extractQuotedTapbackText(trimmed);
-    if (params.requireQuoted && !quotedText) {
-      return null;
-    }
-    const fallback = trimmed.slice("removed".length).trim();
-    return { emoji, action: params.actionHint ?? "removed", quotedText: quotedText ?? fallback };
+  const removed = parseLeadingReactionAction("removed", "removed");
+  if (removed) {
+    return removed;
   }
   return null;
 }

package/src/monitor.webhook-auth.test.ts

@@ -302,65 +302,102 @@ describe("BlueBubbles webhook monitor", () => {
     };
   }
 
-  describe("webhook parsing + auth handling", () => {
-    it("rejects non-POST requests", async () => {
-      const account = createMockAccount();
-      const config: OpenClawConfig = {};
-      const core = createMockRuntime();
-      setBlueBubblesRuntime(core);
+  async function dispatchWebhook(req: IncomingMessage) {
+    const res = createMockResponse();
+    const handled = await handleBlueBubblesWebhookRequest(req, res);
+    return { handled, res };
+  }
+
+  function createWebhookRequestForTest(params?: {
+    method?: string;
+    url?: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    remoteAddress?: string;
+  }) {
+    const req = createMockRequest(
+      params?.method ?? "POST",
+      params?.url ?? "/bluebubbles-webhook",
+      params?.body ?? {},
+      params?.headers,
+    );
+    if (params?.remoteAddress) {
+      setRequestRemoteAddress(req, params.remoteAddress);
+    }
+    return req;
+  }
+
+  function createHangingWebhookRequest(url = "/bluebubbles-webhook?password=test-password") {
+    const req = new EventEmitter() as IncomingMessage;
+    const destroyMock = vi.fn();
+    req.method = "POST";
+    req.url = url;
+    req.headers = {};
+    req.destroy = destroyMock as unknown as IncomingMessage["destroy"];
+    setRequestRemoteAddress(req, "127.0.0.1");
+    return { req, destroyMock };
+  }
 
-      unregister = registerBlueBubblesWebhookTarget({
+  function registerWebhookTargets(
+    params: Array<{
+      account: ResolvedBlueBubblesAccount;
+      statusSink?: (event: unknown) => void;
+    }>,
+  ) {
+    const config: OpenClawConfig = {};
+    const core = createMockRuntime();
+    setBlueBubblesRuntime(core);
+
+    const unregisterFns = params.map(({ account, statusSink }) =>
+      registerBlueBubblesWebhookTarget({
         account,
         config,
         runtime: { log: vi.fn(), error: vi.fn() },
         core,
         path: "/bluebubbles-webhook",
-      });
+        statusSink,
+      }),
+    );
 
-      const req = createMockRequest("GET", "/bluebubbles-webhook", {});
-      const res = createMockResponse();
+    unregister = () => {
+      for (const unregisterFn of unregisterFns) {
+        unregisterFn();
+      }
+    };
+  }
 
-      const handled = await handleBlueBubblesWebhookRequest(req, res);
+  async function expectWebhookStatus(
+    req: IncomingMessage,
+    expectedStatus: number,
+    expectedBody?: string,
+  ) {
+    const { handled, res } = await dispatchWebhook(req);
+    expect(handled).toBe(true);
+    expect(res.statusCode).toBe(expectedStatus);
+    if (expectedBody !== undefined) {
+      expect(res.body).toBe(expectedBody);
+    }
+    return res;
+  }
 
-      expect(handled).toBe(true);
-      expect(res.statusCode).toBe(405);
+  describe("webhook parsing + auth handling", () => {
+    it("rejects non-POST requests", async () => {
+      setupWebhookTarget();
+      const req = createWebhookRequestForTest({ method: "GET" });
+      await expectWebhookStatus(req, 405);
     });
 
     it("accepts POST requests with valid JSON payload", async () => {
       setupWebhookTarget();
       const payload = createNewMessagePayload({ date: Date.now() });
-
-      const req = createMockRequest("POST", "/bluebubbles-webhook", payload);
-      const res = createMockResponse();
-
-      const handled = await handleBlueBubblesWebhookRequest(req, res);
-
-      expect(handled).toBe(true);
-      expect(res.statusCode).toBe(200);
-      expect(res.body).toBe("ok");
+      const req = createWebhookRequestForTest({ body: payload });
+      await expectWebhookStatus(req, 200, "ok");
     });
 
     it("rejects requests with invalid JSON", async () => {
-      const account = createMockAccount();
-      const config: OpenClawConfig = {};
-      const core = createMockRuntime();
-      setBlueBubblesRuntime(core);
-
-      unregister = registerBlueBubblesWebhookTarget({
-        account,
-        config,
-        runtime: { log: vi.fn(), error: vi.fn() },
-        core,
-        path: "/bluebubbles-webhook",
-      });
-
-      const req = createMockRequest("POST", "/bluebubbles-webhook", "invalid json {{");
-      const res = createMockResponse();
-
-      const handled = await handleBlueBubblesWebhookRequest(req, res);
-
-      expect(handled).toBe(true);
-      expect(res.statusCode).toBe(400);
+      setupWebhookTarget();
+      const req = createWebhookRequestForTest({ body: "invalid json {{" });
+      await expectWebhookStatus(req, 400);
     });
 
     it("accepts URL-encoded payload wrappers", async () => {
@@ -369,42 +406,17 @@ describe("BlueBubbles webhook monitor", () => {
       const encodedBody = new URLSearchParams({
         payload: JSON.stringify(payload),
       }).toString();
-
-      const req = createMockRequest("POST", "/bluebubbles-webhook", encodedBody);
-      const res = createMockResponse();
-
-      const handled = await handleBlueBubblesWebhookRequest(req, res);
-
-      expect(handled).toBe(true);
-      expect(res.statusCode).toBe(200);
-      expect(res.body).toBe("ok");
+      const req = createWebhookRequestForTest({ body: encodedBody });
+      await expectWebhookStatus(req, 200, "ok");
     });
 
     it("returns 408 when request body times out (Slow-Loris protection)", async () => {
       vi.useFakeTimers();
       try {
-        const account = createMockAccount();
-        const config: OpenClawConfig = {};
-        const core = createMockRuntime();
-        setBlueBubblesRuntime(core);
-
-        unregister = registerBlueBubblesWebhookTarget({
-          account,
-          config,
-          runtime: { log: vi.fn(), error: vi.fn() },
-          core,
-          path: "/bluebubbles-webhook",
-        });
+        setupWebhookTarget();
 
         // Create a request that never sends data or ends (simulates slow-loris)
-        const req = new EventEmitter() as IncomingMessage;
-        req.method = "POST";
-        req.url = "/bluebubbles-webhook?password=test-password";
-        req.headers = {};
-        (req as unknown as { socket: { remoteAddress: string } }).socket = {
-          remoteAddress: "127.0.0.1",
-        };
-        req.destroy = vi.fn();
+        const { req, destroyMock } = createHangingWebhookRequest();
 
         const res = createMockResponse();
 
@@ -416,7 +428,7 @@ describe("BlueBubbles webhook monitor", () => {
         const handled = await handledPromise;
         expect(handled).toBe(true);
         expect(res.statusCode).toBe(408);
-        expect(req.destroy).toHaveBeenCalled();
+        expect(destroyMock).toHaveBeenCalled();
       } finally {
         vi.useRealTimers();
       }
@@ -424,140 +436,62 @@ describe("BlueBubbles webhook monitor", () => {
 
     it("rejects unauthorized requests before reading the body", async () => {
       const account = createMockAccount({ password: "secret-token" });
-      const config: OpenClawConfig = {};
-      const core = createMockRuntime();
-      setBlueBubblesRuntime(core);
-
-      unregister = registerBlueBubblesWebhookTarget({
-        account,
-        config,
-        runtime: { log: vi.fn(), error: vi.fn() },
-        core,
-        path: "/bluebubbles-webhook",
-      });
-
-      const req = new EventEmitter() as IncomingMessage;
-      req.method = "POST";
-      req.url = "/bluebubbles-webhook?password=wrong-token";
-      req.headers = {};
+      setupWebhookTarget({ account });
+      const { req } = createHangingWebhookRequest("/bluebubbles-webhook?password=wrong-token");
       const onSpy = vi.spyOn(req, "on");
-      (req as unknown as { socket: { remoteAddress: string } }).socket = {
-        remoteAddress: "127.0.0.1",
-      };
-
-      const res = createMockResponse();
-      const handled = await handleBlueBubblesWebhookRequest(req, res);
-
-      expect(handled).toBe(true);
-      expect(res.statusCode).toBe(401);
+      await expectWebhookStatus(req, 401);
       expect(onSpy).not.toHaveBeenCalledWith("data", expect.any(Function));
     });
 
     it("authenticates via password query parameter", async () => {
       const account = createMockAccount({ password: "secret-token" });
-
-      // Mock non-localhost request
-      const req = createMockRequest(
-        "POST",
-        "/bluebubbles-webhook?password=secret-token",
-        createNewMessagePayload(),
-      );
-      setRequestRemoteAddress(req, "192.168.1.100");
       setupWebhookTarget({ account });
-
-      const res = createMockResponse();
-      const handled = await handleBlueBubblesWebhookRequest(req, res);
-
-      expect(handled).toBe(true);
-      expect(res.statusCode).toBe(200);
+      const req = createWebhookRequestForTest({
+        url: "/bluebubbles-webhook?password=secret-token",
+        body: createNewMessagePayload(),
+        remoteAddress: "192.168.1.100",
+      });
+      await expectWebhookStatus(req, 200);
     });
 
     it("authenticates via x-password header", async () => {
       const account = createMockAccount({ password: "secret-token" });
-
-      const req = createMockRequest(
-        "POST",
-        "/bluebubbles-webhook",
-        createNewMessagePayload(),
-        { "x-password": "secret-token" }, // pragma: allowlist secret
-      );
-      setRequestRemoteAddress(req, "192.168.1.100");
       setupWebhookTarget({ account });
-
-      const res = createMockResponse();
-      const handled = await handleBlueBubblesWebhookRequest(req, res);
-
-      expect(handled).toBe(true);
-      expect(res.statusCode).toBe(200);
+      const req = createWebhookRequestForTest({
+        body: createNewMessagePayload(),
+        headers: { "x-password": "secret-token" }, // pragma: allowlist secret
+        remoteAddress: "192.168.1.100",
+      });
+      await expectWebhookStatus(req, 200);
     });
 
     it("rejects unauthorized requests with wrong password", async () => {
       const account = createMockAccount({ password: "secret-token" });
-      const req = createMockRequest(
-        "POST",
-        "/bluebubbles-webhook?password=wrong-token",
-        createNewMessagePayload(),
-      );
-      setRequestRemoteAddress(req, "192.168.1.100");
       setupWebhookTarget({ account });
-
-      const res = createMockResponse();
-      const handled = await handleBlueBubblesWebhookRequest(req, res);
-
-      expect(handled).toBe(true);
-      expect(res.statusCode).toBe(401);
+      const req = createWebhookRequestForTest({
+        url: "/bluebubbles-webhook?password=wrong-token",
+        body: createNewMessagePayload(),
+        remoteAddress: "192.168.1.100",
+      });
+      await expectWebhookStatus(req, 401);
     });
 
     it("rejects ambiguous routing when multiple targets match the same password", async () => {
       const accountA = createMockAccount({ password: "secret-token" });
       const accountB = createMockAccount({ password: "secret-token" });
-      const config: OpenClawConfig = {};
-      const core = createMockRuntime();
-      setBlueBubblesRuntime(core);
-
       const sinkA = vi.fn();
       const sinkB = vi.fn();
-
-      const req = createMockRequest("POST", "/bluebubbles-webhook?password=secret-token", {
-        type: "new-message",
-        data: {
-          text: "hello",
-          handle: { address: "+15551234567" },
-          isGroup: false,
-          isFromMe: false,
-          guid: "msg-1",
-        },
-      });
-      (req as unknown as { socket: { remoteAddress: string } }).socket = {
+      registerWebhookTargets([
+        { account: accountA, statusSink: sinkA },
+        { account: accountB, statusSink: sinkB },
+      ]);
+
+      const req = createWebhookRequestForTest({
+        url: "/bluebubbles-webhook?password=secret-token",
+        body: createNewMessagePayload(),
         remoteAddress: "192.168.1.100",
-      };
-
-      const unregisterA = registerBlueBubblesWebhookTarget({
-        account: accountA,
-        config,
-        runtime: { log: vi.fn(), error: vi.fn() },
-        core,
-        path: "/bluebubbles-webhook",
-        statusSink: sinkA,
       });
-      const unregisterB = registerBlueBubblesWebhookTarget({
-        account: accountB,
-        config,
-        runtime: { log: vi.fn(), error: vi.fn() },
-        core,
-        path: "/bluebubbles-webhook",
-        statusSink: sinkB,
-      });
-      unregister = () => {
-        unregisterA();
-        unregisterB();
-      };
-
-      const res = createMockResponse();
-      const handled = await handleBlueBubblesWebhookRequest(req, res);
-
-      expect(handled).toBe(true);
-      expect(res.statusCode).toBe(401);
+      await expectWebhookStatus(req, 401);
       expect(sinkA).not.toHaveBeenCalled();
       expect(sinkB).not.toHaveBeenCalled();
     });
@@ -565,107 +499,38 @@ describe("BlueBubbles webhook monitor", () => {
     it("ignores targets without passwords when a password-authenticated target matches", async () => {
       const accountStrict = createMockAccount({ password: "secret-token" });
       const accountWithoutPassword = createMockAccount({ password: undefined });
-      const config: OpenClawConfig = {};
-      const core = createMockRuntime();
-      setBlueBubblesRuntime(core);
-
       const sinkStrict = vi.fn();
       const sinkWithoutPassword = vi.fn();
-
-      const req = createMockRequest("POST", "/bluebubbles-webhook?password=secret-token", {
-        type: "new-message",
-        data: {
-          text: "hello",
-          handle: { address: "+15551234567" },
-          isGroup: false,
-          isFromMe: false,
-          guid: "msg-1",
-        },
-      });
-      (req as unknown as { socket: { remoteAddress: string } }).socket = {
+      registerWebhookTargets([
+        { account: accountStrict, statusSink: sinkStrict },
+        { account: accountWithoutPassword, statusSink: sinkWithoutPassword },
+      ]);
+
+      const req = createWebhookRequestForTest({
+        url: "/bluebubbles-webhook?password=secret-token",
+        body: createNewMessagePayload(),
         remoteAddress: "192.168.1.100",
-      };
-
-      const unregisterStrict = registerBlueBubblesWebhookTarget({
-        account: accountStrict,
-        config,
-        runtime: { log: vi.fn(), error: vi.fn() },
-        core,
-        path: "/bluebubbles-webhook",
-        statusSink: sinkStrict,
       });
-      const unregisterNoPassword = registerBlueBubblesWebhookTarget({
-        account: accountWithoutPassword,
-        config,
-        runtime: { log: vi.fn(), error: vi.fn() },
-        core,
-        path: "/bluebubbles-webhook",
-        statusSink: sinkWithoutPassword,
-      });
-      unregister = () => {
-        unregisterStrict();
-        unregisterNoPassword();
-      };
-
-      const res = createMockResponse();
-      const handled = await handleBlueBubblesWebhookRequest(req, res);
-
-      expect(handled).toBe(true);
-      expect(res.statusCode).toBe(200);
+      await expectWebhookStatus(req, 200);
       expect(sinkStrict).toHaveBeenCalledTimes(1);
       expect(sinkWithoutPassword).not.toHaveBeenCalled();
     });
 
     it("requires authentication for loopback requests when password is configured", async () => {
       const account = createMockAccount({ password: "secret-token" });
-      const config: OpenClawConfig = {};
-      const core = createMockRuntime();
-      setBlueBubblesRuntime(core);
+      setupWebhookTarget({ account });
       for (const remoteAddress of ["127.0.0.1", "::1", "::ffff:127.0.0.1"]) {
-        const req = createMockRequest("POST", "/bluebubbles-webhook", {
-          type: "new-message",
-          data: {
-            text: "hello",
-            handle: { address: "+15551234567" },
-            isGroup: false,
-            isFromMe: false,
-            guid: "msg-1",
-          },
-        });
-        (req as unknown as { socket: { remoteAddress: string } }).socket = {
+        const req = createWebhookRequestForTest({
+          body: createNewMessagePayload(),
           remoteAddress,
-        };
-
-        const loopbackUnregister = registerBlueBubblesWebhookTarget({
-          account,
-          config,
-          runtime: { log: vi.fn(), error: vi.fn() },
-          core,
-          path: "/bluebubbles-webhook",
         });
-
-        const res = createMockResponse();
-        const handled = await handleBlueBubblesWebhookRequest(req, res);
-        expect(handled).toBe(true);
-        expect(res.statusCode).toBe(401);
-
-        loopbackUnregister();
+        await expectWebhookStatus(req, 401);
       }
     });
 
     it("rejects targets without passwords for loopback and proxied-looking requests", async () => {
       const account = createMockAccount({ password: undefined });
-      const config: OpenClawConfig = {};
-      const core = createMockRuntime();
-      setBlueBubblesRuntime(core);
-
-      unregister = registerBlueBubblesWebhookTarget({
-        account,
-        config,
-        runtime: { log: vi.fn(), error: vi.fn() },
-        core,
-        path: "/bluebubbles-webhook",
-      });
+      setupWebhookTarget({ account });
 
       const headerVariants: Record<string, string>[] = [
         { host: "localhost" },
@@ -673,28 +538,12 @@ describe("BlueBubbles webhook monitor", () => {
         { host: "localhost", forwarded: "for=203.0.113.10;proto=https;host=example.com" },
       ];
       for (const headers of headerVariants) {
-        const req = createMockRequest(
-          "POST",
-          "/bluebubbles-webhook",
-          {
-            type: "new-message",
-            data: {
-              text: "hello",
-              handle: { address: "+15551234567" },
-              isGroup: false,
-              isFromMe: false,
-              guid: "msg-1",
-            },
-          },
+        const req = createWebhookRequestForTest({
+          body: createNewMessagePayload(),
           headers,
-        );
-        (req as unknown as { socket: { remoteAddress: string } }).socket = {
           remoteAddress: "127.0.0.1",
-        };
-        const res = createMockResponse();
-        const handled = await handleBlueBubblesWebhookRequest(req, res);
-        expect(handled).toBe(true);
-        expect(res.statusCode).toBe(401);
+        });
+        await expectWebhookStatus(req, 401);
       }
     });
 

package/src/multipart.ts

@@ -30,3 +30,11 @@ export async function postMultipartFormData(params: {
     params.timeoutMs,
   );
 }
+
+export async function assertMultipartActionOk(response: Response, action: string): Promise<void> {
+  if (response.ok) {
+    return;
+  }
+  const errorText = await response.text().catch(() => "");
+  throw new Error(`BlueBubbles ${action} failed (${response.status}): ${errorText || "unknown"}`);
+}

package/src/reactions.test.ts

@@ -19,7 +19,7 @@ describe("reactions", () => {
   });
 
   describe("sendBlueBubblesReaction", () => {
-    async function expectRemovedReaction(emoji: string) {
+    async function expectRemovedReaction(emoji: string, expectedReaction = "-love") {
       mockFetch.mockResolvedValueOnce({
         ok: true,
         text: () => Promise.resolve(""),
@@ -37,7 +37,7 @@ describe("reactions", () => {
       });
 
       const body = JSON.parse(mockFetch.mock.calls[0][1].body);
-      expect(body.reaction).toBe("-love");
+      expect(body.reaction).toBe(expectedReaction);
     }
 
     it("throws when chatGuid is empty", async () => {
@@ -327,45 +327,11 @@ describe("reactions", () => {
 
     describe("reaction removal aliases", () => {
       it("handles emoji-based removal", async () => {
-        mockFetch.mockResolvedValueOnce({
-          ok: true,
-          text: () => Promise.resolve(""),
-        });
-
-        await sendBlueBubblesReaction({
-          chatGuid: "chat-123",
-          messageGuid: "msg-123",
-          emoji: "👍",
-          remove: true,
-          opts: {
-            serverUrl: "http://localhost:1234",
-            password: "test",
-          },
-        });
-
-        const body = JSON.parse(mockFetch.mock.calls[0][1].body);
-        expect(body.reaction).toBe("-like");
+        await expectRemovedReaction("👍", "-like");
       });
 
       it("handles text alias removal", async () => {
-        mockFetch.mockResolvedValueOnce({
-          ok: true,
-          text: () => Promise.resolve(""),
-        });
-
-        await sendBlueBubblesReaction({
-          chatGuid: "chat-123",
-          messageGuid: "msg-123",
-          emoji: "haha",
-          remove: true,
-          opts: {
-            serverUrl: "http://localhost:1234",
-            password: "test",
-          },
-        });
-
-        const body = JSON.parse(mockFetch.mock.calls[0][1].body);
-        expect(body.reaction).toBe("-laugh");
+        await expectRemovedReaction("haha", "-laugh");
       });
     });
   });