@openclaw/bluebubbles 2026.2.21 → 2026.2.22

package/src/send.ts

@@ -2,7 +2,11 @@ import crypto from "node:crypto";
 import type { OpenClawConfig } from "openclaw/plugin-sdk";
 import { stripMarkdown } from "openclaw/plugin-sdk";
 import { resolveBlueBubblesAccount } from "./accounts.js";
-import { getCachedBlueBubblesPrivateApiStatus } from "./probe.js";
+import {
+  getCachedBlueBubblesPrivateApiStatus,
+  isBlueBubblesPrivateApiStatusEnabled,
+} from "./probe.js";
+import { warnBlueBubbles } from "./runtime.js";
 import { extractBlueBubblesMessageId, resolveBlueBubblesSendTarget } from "./send-helpers.js";
 import { extractHandleFromChatGuid, normalizeBlueBubblesHandle } from "./targets.js";
 import {
@@ -71,6 +75,38 @@ function resolveEffectId(raw?: string): string | undefined {
   return raw;
 }
 
+type PrivateApiDecision = {
+  canUsePrivateApi: boolean;
+  throwEffectDisabledError: boolean;
+  warningMessage?: string;
+};
+
+function resolvePrivateApiDecision(params: {
+  privateApiStatus: boolean | null;
+  wantsReplyThread: boolean;
+  wantsEffect: boolean;
+}): PrivateApiDecision {
+  const { privateApiStatus, wantsReplyThread, wantsEffect } = params;
+  const needsPrivateApi = wantsReplyThread || wantsEffect;
+  const canUsePrivateApi =
+    needsPrivateApi && isBlueBubblesPrivateApiStatusEnabled(privateApiStatus);
+  const throwEffectDisabledError = wantsEffect && privateApiStatus === false;
+  if (!needsPrivateApi || privateApiStatus !== null) {
+    return { canUsePrivateApi, throwEffectDisabledError };
+  }
+  const requested = [
+    wantsReplyThread ? "reply threading" : null,
+    wantsEffect ? "message effects" : null,
+  ]
+    .filter(Boolean)
+    .join(" + ");
+  return {
+    canUsePrivateApi,
+    throwEffectDisabledError,
+    warningMessage: `Private API status unknown; sending without ${requested}. Run a status probe to restore private-api features.`,
+  };
+}
+
 type BlueBubblesChatRecord = Record<string, unknown>;
 
 function extractChatGuid(chat: BlueBubblesChatRecord): string | null {
@@ -372,30 +408,36 @@ export async function sendMessageBlueBubbles(
   const effectId = resolveEffectId(opts.effectId);
   const wantsReplyThread = Boolean(opts.replyToMessageGuid?.trim());
   const wantsEffect = Boolean(effectId);
-  const needsPrivateApi = wantsReplyThread || wantsEffect;
-  const canUsePrivateApi = needsPrivateApi && privateApiStatus !== false;
-  if (wantsEffect && privateApiStatus === false) {
+  const privateApiDecision = resolvePrivateApiDecision({
+    privateApiStatus,
+    wantsReplyThread,
+    wantsEffect,
+  });
+  if (privateApiDecision.throwEffectDisabledError) {
     throw new Error(
       "BlueBubbles send failed: reply/effect requires Private API, but it is disabled on the BlueBubbles server.",
     );
   }
+  if (privateApiDecision.warningMessage) {
+    warnBlueBubbles(privateApiDecision.warningMessage);
+  }
   const payload: Record<string, unknown> = {
     chatGuid,
     tempGuid: crypto.randomUUID(),
     message: strippedText,
   };
-  if (canUsePrivateApi) {
+  if (privateApiDecision.canUsePrivateApi) {
     payload.method = "private-api";
   }
 
   // Add reply threading support
-  if (wantsReplyThread && canUsePrivateApi) {
+  if (wantsReplyThread && privateApiDecision.canUsePrivateApi) {
     payload.selectedMessageGuid = opts.replyToMessageGuid;
     payload.partIndex = typeof opts.replyToPartIndex === "number" ? opts.replyToPartIndex : 0;
   }
 
   // Add message effects support
-  if (effectId) {
+  if (effectId && privateApiDecision.canUsePrivateApi) {
     payload.effectId = effectId;
   }
 

package/src/targets.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 import {
+  isAllowedBlueBubblesSender,
   looksLikeBlueBubblesTargetId,
   normalizeBlueBubblesMessagingTarget,
   parseBlueBubblesTarget,
@@ -181,3 +182,21 @@ describe("parseBlueBubblesAllowTarget", () => {
     });
   });
 });
+
+describe("isAllowedBlueBubblesSender", () => {
+  it("denies when allowFrom is empty", () => {
+    const allowed = isAllowedBlueBubblesSender({
+      allowFrom: [],
+      sender: "+15551234567",
+    });
+    expect(allowed).toBe(false);
+  });
+
+  it("allows wildcard entries", () => {
+    const allowed = isAllowedBlueBubblesSender({
+      allowFrom: ["*"],
+      sender: "+15551234567",
+    });
+    expect(allowed).toBe(true);
+  });
+});

package/src/targets.ts

@@ -78,6 +78,40 @@ function looksLikeRawChatIdentifier(value: string): boolean {
   return CHAT_IDENTIFIER_UUID_RE.test(trimmed) || CHAT_IDENTIFIER_HEX_RE.test(trimmed);
 }
 
+function parseGroupTarget(params: {
+  trimmed: string;
+  lower: string;
+  requireValue: boolean;
+}): { kind: "chat_id"; chatId: number } | { kind: "chat_guid"; chatGuid: string } | null {
+  if (!params.lower.startsWith("group:")) {
+    return null;
+  }
+  const value = stripPrefix(params.trimmed, "group:");
+  const chatId = Number.parseInt(value, 10);
+  if (Number.isFinite(chatId)) {
+    return { kind: "chat_id", chatId };
+  }
+  if (value) {
+    return { kind: "chat_guid", chatGuid: value };
+  }
+  if (params.requireValue) {
+    throw new Error("group target is required");
+  }
+  return null;
+}
+
+function parseRawChatIdentifierTarget(
+  trimmed: string,
+): { kind: "chat_identifier"; chatIdentifier: string } | null {
+  if (/^chat\d+$/i.test(trimmed)) {
+    return { kind: "chat_identifier", chatIdentifier: trimmed };
+  }
+  if (looksLikeRawChatIdentifier(trimmed)) {
+    return { kind: "chat_identifier", chatIdentifier: trimmed };
+  }
+  return null;
+}
+
 export function normalizeBlueBubblesHandle(raw: string): string {
   const trimmed = raw.trim();
   if (!trimmed) {
@@ -239,16 +273,9 @@ export function parseBlueBubblesTarget(raw: string): BlueBubblesTarget {
     return chatTarget;
   }
 
-  if (lower.startsWith("group:")) {
-    const value = stripPrefix(trimmed, "group:");
-    const chatId = Number.parseInt(value, 10);
-    if (Number.isFinite(chatId)) {
-      return { kind: "chat_id", chatId };
-    }
-    if (!value) {
-      throw new Error("group target is required");
-    }
-    return { kind: "chat_guid", chatGuid: value };
+  const groupTarget = parseGroupTarget({ trimmed, lower, requireValue: true });
+  if (groupTarget) {
+    return groupTarget;
   }
 
   const rawChatGuid = parseRawChatGuid(trimmed);
@@ -256,15 +283,9 @@ export function parseBlueBubblesTarget(raw: string): BlueBubblesTarget {
     return { kind: "chat_guid", chatGuid: rawChatGuid };
   }
 
-  // Handle chat<digits> pattern (e.g., "chat660250192681427962") as chat_identifier
-  // These are BlueBubbles chat identifiers (the third part of a chat GUID), not numeric IDs
-  if (/^chat\d+$/i.test(trimmed)) {
-    return { kind: "chat_identifier", chatIdentifier: trimmed };
-  }
-
-  // Handle UUID/hex chat identifiers (e.g., "8b9c1a10536d4d86a336ea03ab7151cc")
-  if (looksLikeRawChatIdentifier(trimmed)) {
-    return { kind: "chat_identifier", chatIdentifier: trimmed };
+  const rawChatIdentifierTarget = parseRawChatIdentifierTarget(trimmed);
+  if (rawChatIdentifierTarget) {
+    return rawChatIdentifierTarget;
   }
 
   return { kind: "handle", to: trimmed, service: "auto" };
@@ -298,26 +319,14 @@ export function parseBlueBubblesAllowTarget(raw: string): BlueBubblesAllowTarget
     return chatTarget;
   }
 
-  if (lower.startsWith("group:")) {
-    const value = stripPrefix(trimmed, "group:");
-    const chatId = Number.parseInt(value, 10);
-    if (Number.isFinite(chatId)) {
-      return { kind: "chat_id", chatId };
-    }
-    if (value) {
-      return { kind: "chat_guid", chatGuid: value };
-    }
-  }
-
-  // Handle chat<digits> pattern (e.g., "chat660250192681427962") as chat_identifier
-  // These are BlueBubbles chat identifiers (the third part of a chat GUID), not numeric IDs
-  if (/^chat\d+$/i.test(trimmed)) {
-    return { kind: "chat_identifier", chatIdentifier: trimmed };
+  const groupTarget = parseGroupTarget({ trimmed, lower, requireValue: false });
+  if (groupTarget) {
+    return groupTarget;
   }
 
-  // Handle UUID/hex chat identifiers (e.g., "8b9c1a10536d4d86a336ea03ab7151cc")
-  if (looksLikeRawChatIdentifier(trimmed)) {
-    return { kind: "chat_identifier", chatIdentifier: trimmed };
+  const rawChatIdentifierTarget = parseRawChatIdentifierTarget(trimmed);
+  if (rawChatIdentifierTarget) {
+    return rawChatIdentifierTarget;
   }
 
   return { kind: "handle", handle: normalizeBlueBubblesHandle(trimmed) };

package/src/test-harness.ts

@@ -1,6 +1,31 @@
 import type { Mock } from "vitest";
 import { afterEach, beforeEach, vi } from "vitest";
 
+export const BLUE_BUBBLES_PRIVATE_API_STATUS = {
+  enabled: true,
+  disabled: false,
+  unknown: null,
+} as const;
+
+type BlueBubblesPrivateApiStatusMock = {
+  mockReturnValue: (value: boolean | null) => unknown;
+  mockReturnValueOnce: (value: boolean | null) => unknown;
+};
+
+export function mockBlueBubblesPrivateApiStatus(
+  mock: Pick<BlueBubblesPrivateApiStatusMock, "mockReturnValue">,
+  value: boolean | null,
+) {
+  mock.mockReturnValue(value);
+}
+
+export function mockBlueBubblesPrivateApiStatusOnce(
+  mock: Pick<BlueBubblesPrivateApiStatusMock, "mockReturnValueOnce">,
+  value: boolean | null,
+) {
+  mock.mockReturnValueOnce(value);
+}
+
 export function resolveBlueBubblesAccountFromConfig(params: {
   cfg?: { channels?: { bluebubbles?: Record<string, unknown> } };
   accountId?: string;
@@ -22,11 +47,15 @@ export function createBlueBubblesAccountsMockModule() {
 
 type BlueBubblesProbeMockModule = {
   getCachedBlueBubblesPrivateApiStatus: Mock<() => boolean | null>;
+  isBlueBubblesPrivateApiStatusEnabled: Mock<(status: boolean | null) => boolean>;
 };
 
 export function createBlueBubblesProbeMockModule(): BlueBubblesProbeMockModule {
   return {
-    getCachedBlueBubblesPrivateApiStatus: vi.fn().mockReturnValue(null),
+    getCachedBlueBubblesPrivateApiStatus: vi
+      .fn()
+      .mockReturnValue(BLUE_BUBBLES_PRIVATE_API_STATUS.unknown),
+    isBlueBubblesPrivateApiStatusEnabled: vi.fn((status: boolean | null) => status === true),
   };
 }
 
@@ -41,7 +70,7 @@ export function installBlueBubblesFetchTestHooks(params: {
     vi.stubGlobal("fetch", params.mockFetch);
     params.mockFetch.mockReset();
     params.privateApiStatusMock.mockReset();
-    params.privateApiStatusMock.mockReturnValue(null);
+    params.privateApiStatusMock.mockReturnValue(BLUE_BUBBLES_PRIVATE_API_STATUS.unknown);
   });
 
   afterEach(() => {