@openclaw/bluebubbles 2026.3.1 → 2026.3.7

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

@@ -0,0 +1,44 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/bluebubbles";
+import { afterEach, describe, expect, it } from "vitest";
+import { createEmptyPluginRegistry } from "../../../src/plugins/registry.js";
+import { setActivePluginRegistry } from "../../../src/plugins/runtime.js";
+import type { WebhookTarget } from "./monitor-shared.js";
+import { registerBlueBubblesWebhookTarget } from "./monitor.js";
+
+function createTarget(): WebhookTarget {
+  return {
+    account: { accountId: "default" } as WebhookTarget["account"],
+    config: {} as OpenClawConfig,
+    runtime: {},
+    core: {} as WebhookTarget["core"],
+    path: "/bluebubbles-webhook",
+  };
+}
+
+describe("registerBlueBubblesWebhookTarget", () => {
+  afterEach(() => {
+    setActivePluginRegistry(createEmptyPluginRegistry());
+  });
+
+  it("registers and unregisters plugin HTTP route at path boundaries", () => {
+    const registry = createEmptyPluginRegistry();
+    setActivePluginRegistry(registry);
+
+    const unregisterA = registerBlueBubblesWebhookTarget(createTarget());
+    const unregisterB = registerBlueBubblesWebhookTarget(createTarget());
+
+    expect(registry.httpRoutes).toHaveLength(1);
+    expect(registry.httpRoutes[0]).toEqual(
+      expect.objectContaining({
+        pluginId: "bluebubbles",
+        path: "/bluebubbles-webhook",
+        source: "bluebubbles-webhook",
+      }),
+    );
+
+    unregisterA();
+    expect(registry.httpRoutes).toHaveLength(1);
+    unregisterB();
+    expect(registry.httpRoutes).toHaveLength(0);
+  });
+});

package/src/onboarding.secret-input.test.ts

@@ -0,0 +1,89 @@
+import type { WizardPrompter } from "openclaw/plugin-sdk/bluebubbles";
+import { describe, expect, it, vi } from "vitest";
+
+vi.mock("openclaw/plugin-sdk/bluebubbles", () => ({
+  DEFAULT_ACCOUNT_ID: "default",
+  addWildcardAllowFrom: vi.fn(),
+  formatDocsLink: (_url: string, fallback: string) => fallback,
+  hasConfiguredSecretInput: (value: unknown) => {
+    if (typeof value === "string") {
+      return value.trim().length > 0;
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      return false;
+    }
+    const ref = value as { source?: unknown; provider?: unknown; id?: unknown };
+    const validSource = ref.source === "env" || ref.source === "file" || ref.source === "exec";
+    return (
+      validSource &&
+      typeof ref.provider === "string" &&
+      ref.provider.trim().length > 0 &&
+      typeof ref.id === "string" &&
+      ref.id.trim().length > 0
+    );
+  },
+  mergeAllowFromEntries: (_existing: unknown, entries: string[]) => entries,
+  createAccountListHelpers: () => ({
+    listAccountIds: () => ["default"],
+    resolveDefaultAccountId: () => "default",
+  }),
+  normalizeSecretInputString: (value: unknown) => {
+    if (typeof value !== "string") {
+      return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+  },
+  normalizeAccountId: (value?: string | null) =>
+    value && value.trim().length > 0 ? value : "default",
+  promptAccountId: vi.fn(),
+  resolveAccountIdForConfigure: async (params: {
+    accountOverride?: string;
+    defaultAccountId: string;
+  }) => params.accountOverride?.trim() || params.defaultAccountId,
+}));
+
+describe("bluebubbles onboarding SecretInput", () => {
+  it("preserves existing password SecretRef when user keeps current credential", async () => {
+    const { blueBubblesOnboardingAdapter } = await import("./onboarding.js");
+    type ConfigureContext = Parameters<
+      NonNullable<typeof blueBubblesOnboardingAdapter.configure>
+    >[0];
+    const passwordRef = { source: "env", provider: "default", id: "BLUEBUBBLES_PASSWORD" };
+    const confirm = vi
+      .fn()
+      .mockResolvedValueOnce(true) // keep server URL
+      .mockResolvedValueOnce(true) // keep password SecretRef
+      .mockResolvedValueOnce(false); // keep default webhook path
+    const text = vi.fn();
+    const note = vi.fn();
+
+    const prompter = {
+      confirm,
+      text,
+      note,
+    } as unknown as WizardPrompter;
+
+    const context = {
+      cfg: {
+        channels: {
+          bluebubbles: {
+            enabled: true,
+            serverUrl: "http://127.0.0.1:1234",
+            password: passwordRef,
+          },
+        },
+      },
+      prompter,
+      runtime: { ...console, exit: vi.fn() } as ConfigureContext["runtime"],
+      forceAllowFrom: false,
+      accountOverrides: {},
+      shouldPromptAccountIds: false,
+    } satisfies ConfigureContext;
+
+    const result = await blueBubblesOnboardingAdapter.configure(context);
+
+    expect(result.cfg.channels?.bluebubbles?.password).toEqual(passwordRef);
+    expect(text).not.toHaveBeenCalled();
+  });
+});

package/src/onboarding.ts

@@ -4,39 +4,33 @@ import type {
   OpenClawConfig,
   DmPolicy,
   WizardPrompter,
-} from "openclaw/plugin-sdk";
+} from "openclaw/plugin-sdk/bluebubbles";
 import {
   DEFAULT_ACCOUNT_ID,
-  addWildcardAllowFrom,
   formatDocsLink,
   mergeAllowFromEntries,
   normalizeAccountId,
-  promptAccountId,
-} from "openclaw/plugin-sdk";
+  resolveAccountIdForConfigure,
+  setTopLevelChannelDmPolicyWithAllowFrom,
+} from "openclaw/plugin-sdk/bluebubbles";
 import {
   listBlueBubblesAccountIds,
   resolveBlueBubblesAccount,
   resolveDefaultBlueBubblesAccountId,
 } from "./accounts.js";
+import { applyBlueBubblesConnectionConfig } from "./config-apply.js";
+import { hasConfiguredSecretInput, normalizeSecretInputString } from "./secret-input.js";
 import { parseBlueBubblesAllowTarget } from "./targets.js";
 import { normalizeBlueBubblesServerUrl } from "./types.js";
 
 const channel = "bluebubbles" as const;
 
 function setBlueBubblesDmPolicy(cfg: OpenClawConfig, dmPolicy: DmPolicy): OpenClawConfig {
-  const allowFrom =
-    dmPolicy === "open" ? addWildcardAllowFrom(cfg.channels?.bluebubbles?.allowFrom) : undefined;
-  return {
-    ...cfg,
-    channels: {
-      ...cfg.channels,
-      bluebubbles: {
-        ...cfg.channels?.bluebubbles,
-        dmPolicy,
-        ...(allowFrom ? { allowFrom } : {}),
-      },
-    },
-  };
+  return setTopLevelChannelDmPolicyWithAllowFrom({
+    cfg,
+    channel: "bluebubbles",
+    dmPolicy,
+  });
 }
 
 function setBlueBubblesAllowFrom(
@@ -158,21 +152,16 @@ export const blueBubblesOnboardingAdapter: ChannelOnboardingAdapter = {
     };
   },
   configure: async ({ cfg, prompter, accountOverrides, shouldPromptAccountIds }) => {
-    const blueBubblesOverride = accountOverrides.bluebubbles?.trim();
     const defaultAccountId = resolveDefaultBlueBubblesAccountId(cfg);
-    let accountId = blueBubblesOverride
-      ? normalizeAccountId(blueBubblesOverride)
-      : defaultAccountId;
-    if (shouldPromptAccountIds && !blueBubblesOverride) {
-      accountId = await promptAccountId({
-        cfg,
-        prompter,
-        label: "BlueBubbles",
-        currentId: accountId,
-        listAccountIds: listBlueBubblesAccountIds,
-        defaultAccountId,
-      });
-    }
+    const accountId = await resolveAccountIdForConfigure({
+      cfg,
+      prompter,
+      label: "BlueBubbles",
+      accountOverride: accountOverrides.bluebubbles,
+      shouldPromptAccountIds,
+      listAccountIds: listBlueBubblesAccountIds,
+      defaultAccountId,
+    });
 
     let next = cfg;
     const resolvedAccount = resolveBlueBubblesAccount({ cfg: next, accountId });
@@ -222,8 +211,11 @@ export const blueBubblesOnboardingAdapter: ChannelOnboardingAdapter = {
     }
 
     // Prompt for password
-    let password = resolvedAccount.config.password?.trim();
-    if (!password) {
+    const existingPassword = resolvedAccount.config.password;
+    const existingPasswordText = normalizeSecretInputString(existingPassword);
+    const hasConfiguredPassword = hasConfiguredSecretInput(existingPassword);
+    let password: unknown = existingPasswordText;
+    if (!hasConfiguredPassword) {
       await prompter.note(
         [
           "Enter the BlueBubbles server password.",
@@ -247,6 +239,8 @@ export const blueBubblesOnboardingAdapter: ChannelOnboardingAdapter = {
           validate: (value) => (String(value ?? "").trim() ? undefined : "Required"),
         });
         password = String(entered).trim();
+      } else if (!existingPasswordText) {
+        password = existingPassword;
       }
     }
 
@@ -277,42 +271,16 @@ export const blueBubblesOnboardingAdapter: ChannelOnboardingAdapter = {
     }
 
     // Apply config
-    if (accountId === DEFAULT_ACCOUNT_ID) {
-      next = {
-        ...next,
-        channels: {
-          ...next.channels,
-          bluebubbles: {
-            ...next.channels?.bluebubbles,
-            enabled: true,
-            serverUrl,
-            password,
-            webhookPath,
-          },
-        },
-      };
-    } else {
-      next = {
-        ...next,
-        channels: {
-          ...next.channels,
-          bluebubbles: {
-            ...next.channels?.bluebubbles,
-            enabled: true,
-            accounts: {
-              ...next.channels?.bluebubbles?.accounts,
-              [accountId]: {
-                ...next.channels?.bluebubbles?.accounts?.[accountId],
-                enabled: next.channels?.bluebubbles?.accounts?.[accountId]?.enabled ?? true,
-                serverUrl,
-                password,
-                webhookPath,
-              },
-            },
-          },
-        },
-      };
-    }
+    next = applyBlueBubblesConnectionConfig({
+      cfg: next,
+      accountId,
+      patch: {
+        serverUrl,
+        password,
+        webhookPath,
+      },
+      accountEnabled: "preserve-or-true",
+    });
 
     await prompter.note(
       [

package/src/probe.ts

@@ -1,4 +1,5 @@
-import type { BaseProbeResult } from "openclaw/plugin-sdk";
+import type { BaseProbeResult } from "openclaw/plugin-sdk/bluebubbles";
+import { normalizeSecretInputString } from "./secret-input.js";
 import { buildBlueBubblesApiUrl, blueBubblesFetchWithTimeout } from "./types.js";
 
 export type BlueBubblesProbe = BaseProbeResult & {
@@ -35,8 +36,8 @@ export async function fetchBlueBubblesServerInfo(params: {
   accountId?: string;
   timeoutMs?: number;
 }): Promise<BlueBubblesServerInfo | null> {
-  const baseUrl = params.baseUrl?.trim();
-  const password = params.password?.trim();
+  const baseUrl = normalizeSecretInputString(params.baseUrl);
+  const password = normalizeSecretInputString(params.password);
   if (!baseUrl || !password) {
     return null;
   }
@@ -138,8 +139,8 @@ export async function probeBlueBubbles(params: {
   password?: string | null;
   timeoutMs?: number;
 }): Promise<BlueBubblesProbe> {
-  const baseUrl = params.baseUrl?.trim();
-  const password = params.password?.trim();
+  const baseUrl = normalizeSecretInputString(params.baseUrl);
+  const password = normalizeSecretInputString(params.password);
   if (!baseUrl) {
     return { ok: false, error: "serverUrl not configured" };
   }

package/src/reactions.ts

@@ -1,4 +1,4 @@
-import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/bluebubbles";
 import { resolveBlueBubblesServerAccount } from "./account-resolve.js";
 import { getCachedBlueBubblesPrivateApiStatus } from "./probe.js";
 import { blueBubblesFetchWithTimeout, buildBlueBubblesApiUrl } from "./types.js";

package/src/request-url.ts

@@ -1,12 +1 @@
-export function resolveRequestUrl(input: RequestInfo | URL): string {
-  if (typeof input === "string") {
-    return input;
-  }
-  if (input instanceof URL) {
-    return input.toString();
-  }
-  if (typeof input === "object" && input && "url" in input && typeof input.url === "string") {
-    return input.url;
-  }
-  return String(input);
-}
+export { resolveRequestUrl } from "openclaw/plugin-sdk/bluebubbles";

package/src/runtime.ts

@@ -1,4 +1,4 @@
-import type { PluginRuntime } from "openclaw/plugin-sdk";
+import type { PluginRuntime } from "openclaw/plugin-sdk/bluebubbles";
 
 let runtime: PluginRuntime | null = null;
 type LegacyRuntimeLogShape = { log?: (message: string) => void };

package/src/secret-input.ts

@@ -0,0 +1,13 @@
+import {
+  buildSecretInputSchema,
+  hasConfiguredSecretInput,
+  normalizeResolvedSecretInputString,
+  normalizeSecretInputString,
+} from "openclaw/plugin-sdk/bluebubbles";
+
+export {
+  buildSecretInputSchema,
+  hasConfiguredSecretInput,
+  normalizeResolvedSecretInputString,
+  normalizeSecretInputString,
+};

package/src/send-helpers.ts

@@ -23,31 +23,43 @@ export function extractBlueBubblesMessageId(payload: unknown): string {
   if (!payload || typeof payload !== "object") {
     return "unknown";
   }
-  const record = payload as Record<string, unknown>;
-  const data =
-    record.data && typeof record.data === "object"
-      ? (record.data as Record<string, unknown>)
+
+  const asRecord = (value: unknown): Record<string, unknown> | null =>
+    value && typeof value === "object" && !Array.isArray(value)
+      ? (value as Record<string, unknown>)
       : null;
-  const candidates = [
-    record.messageId,
-    record.messageGuid,
-    record.message_guid,
-    record.guid,
-    record.id,
-    data?.messageId,
-    data?.messageGuid,
-    data?.message_guid,
-    data?.message_id,
-    data?.guid,
-    data?.id,
-  ];
-  for (const candidate of candidates) {
-    if (typeof candidate === "string" && candidate.trim()) {
-      return candidate.trim();
+
+  const record = payload as Record<string, unknown>;
+  const dataRecord = asRecord(record.data);
+  const resultRecord = asRecord(record.result);
+  const payloadRecord = asRecord(record.payload);
+  const messageRecord = asRecord(record.message);
+  const dataArrayFirst = Array.isArray(record.data) ? asRecord(record.data[0]) : null;
+
+  const roots = [record, dataRecord, resultRecord, payloadRecord, messageRecord, dataArrayFirst];
+
+  for (const root of roots) {
+    if (!root) {
+      continue;
     }
-    if (typeof candidate === "number" && Number.isFinite(candidate)) {
-      return String(candidate);
+    const candidates = [
+      root.message_id,
+      root.messageId,
+      root.messageGuid,
+      root.message_guid,
+      root.guid,
+      root.id,
+      root.uuid,
+    ];
+    for (const candidate of candidates) {
+      if (typeof candidate === "string" && candidate.trim()) {
+        return candidate.trim();
+      }
+      if (typeof candidate === "number" && Number.isFinite(candidate)) {
+        return String(candidate);
+      }
     }
   }
+
   return "unknown";
 }

package/src/send.test.ts

@@ -1,4 +1,4 @@
-import type { PluginRuntime } from "openclaw/plugin-sdk";
+import type { PluginRuntime } from "openclaw/plugin-sdk/bluebubbles";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import "./test-mocks.js";
 import { getCachedBlueBubblesPrivateApiStatus } from "./probe.js";
@@ -721,6 +721,30 @@ describe("send", () => {
       expect(result.messageId).toBe("msg-guid-789");
     });
 
+    it("extracts top-level message_id from response payload", async () => {
+      mockResolvedHandleTarget();
+      mockSendResponse({ message_id: "bb-msg-321" });
+
+      const result = await sendMessageBlueBubbles("+15551234567", "Hello", {
+        serverUrl: "http://localhost:1234",
+        password: "test",
+      });
+
+      expect(result.messageId).toBe("bb-msg-321");
+    });
+
+    it("extracts nested result.message_id from response payload", async () => {
+      mockResolvedHandleTarget();
+      mockSendResponse({ result: { message_id: "bb-msg-654" } });
+
+      const result = await sendMessageBlueBubbles("+15551234567", "Hello", {
+        serverUrl: "http://localhost:1234",
+        password: "test",
+      });
+
+      expect(result.messageId).toBe("bb-msg-654");
+    });
+
     it("resolves credentials from config", async () => {
       mockResolvedHandleTarget();
       mockSendResponse({ data: { guid: "msg-123" } });

package/src/send.ts

@@ -1,12 +1,13 @@
 import crypto from "node:crypto";
-import type { OpenClawConfig } from "openclaw/plugin-sdk";
-import { stripMarkdown } from "openclaw/plugin-sdk";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/bluebubbles";
+import { stripMarkdown } from "openclaw/plugin-sdk/bluebubbles";
 import { resolveBlueBubblesAccount } from "./accounts.js";
 import {
   getCachedBlueBubblesPrivateApiStatus,
   isBlueBubblesPrivateApiStatusEnabled,
 } from "./probe.js";
 import { warnBlueBubbles } from "./runtime.js";
+import { normalizeSecretInputString } from "./secret-input.js";
 import { extractBlueBubblesMessageId, resolveBlueBubblesSendTarget } from "./send-helpers.js";
 import { extractHandleFromChatGuid, normalizeBlueBubblesHandle } from "./targets.js";
 import {
@@ -107,6 +108,19 @@ function resolvePrivateApiDecision(params: {
   };
 }
 
+async function parseBlueBubblesMessageResponse(res: Response): Promise<BlueBubblesSendResult> {
+  const body = await res.text();
+  if (!body) {
+    return { messageId: "ok" };
+  }
+  try {
+    const parsed = JSON.parse(body) as unknown;
+    return { messageId: extractBlueBubblesMessageId(parsed) };
+  } catch {
+    return { messageId: "ok" };
+  }
+}
+
 type BlueBubblesChatRecord = Record<string, unknown>;
 
 function extractChatGuid(chat: BlueBubblesChatRecord): string | null {
@@ -341,16 +355,7 @@ async function createNewChatWithMessage(params: {
     }
     throw new Error(`BlueBubbles create chat failed (${res.status}): ${errorText || "unknown"}`);
   }
-  const body = await res.text();
-  if (!body) {
-    return { messageId: "ok" };
-  }
-  try {
-    const parsed = JSON.parse(body) as unknown;
-    return { messageId: extractBlueBubblesMessageId(parsed) };
-  } catch {
-    return { messageId: "ok" };
-  }
+  return parseBlueBubblesMessageResponse(res);
 }
 
 export async function sendMessageBlueBubbles(
@@ -372,8 +377,12 @@ export async function sendMessageBlueBubbles(
     cfg: opts.cfg ?? {},
     accountId: opts.accountId,
   });
-  const baseUrl = opts.serverUrl?.trim() || account.config.serverUrl?.trim();
-  const password = opts.password?.trim() || account.config.password?.trim();
+  const baseUrl =
+    normalizeSecretInputString(opts.serverUrl) ||
+    normalizeSecretInputString(account.config.serverUrl);
+  const password =
+    normalizeSecretInputString(opts.password) ||
+    normalizeSecretInputString(account.config.password);
   if (!baseUrl) {
     throw new Error("BlueBubbles serverUrl is required");
   }
@@ -459,14 +468,5 @@ export async function sendMessageBlueBubbles(
     const errorText = await res.text();
     throw new Error(`BlueBubbles send failed (${res.status}): ${errorText || "unknown"}`);
   }
-  const body = await res.text();
-  if (!body) {
-    return { messageId: "ok" };
-  }
-  try {
-    const parsed = JSON.parse(body) as unknown;
-    return { messageId: extractBlueBubblesMessageId(parsed) };
-  } catch {
-    return { messageId: "ok" };
-  }
+  return parseBlueBubblesMessageResponse(res);
 }

package/src/targets.ts

@@ -2,9 +2,10 @@ import {
   isAllowedParsedChatSender,
   parseChatAllowTargetPrefixes,
   parseChatTargetPrefixesOrThrow,
+  type ParsedChatTarget,
   resolveServicePrefixedAllowTarget,
   resolveServicePrefixedTarget,
-} from "openclaw/plugin-sdk";
+} from "openclaw/plugin-sdk/bluebubbles";
 
 export type BlueBubblesService = "imessage" | "sms" | "auto";
 
@@ -14,11 +15,7 @@ export type BlueBubblesTarget =
   | { kind: "chat_identifier"; chatIdentifier: string }
   | { kind: "handle"; to: string; service: BlueBubblesService };
 
-export type BlueBubblesAllowTarget =
-  | { kind: "chat_id"; chatId: number }
-  | { kind: "chat_guid"; chatGuid: string }
-  | { kind: "chat_identifier"; chatIdentifier: string }
-  | { kind: "handle"; handle: string };
+export type BlueBubblesAllowTarget = ParsedChatTarget | { kind: "handle"; handle: string };
 
 const CHAT_ID_PREFIXES = ["chat_id:", "chatid:", "chat:"];
 const CHAT_GUID_PREFIXES = ["chat_guid:", "chatguid:", "guid:"];

package/src/types.ts

@@ -1,6 +1,6 @@
-import type { DmPolicy, GroupPolicy } from "openclaw/plugin-sdk";
+import type { DmPolicy, GroupPolicy } from "openclaw/plugin-sdk/bluebubbles";
 
-export type { DmPolicy, GroupPolicy } from "openclaw/plugin-sdk";
+export type { DmPolicy, GroupPolicy } from "openclaw/plugin-sdk/bluebubbles";
 
 export type BlueBubblesGroupConfig = {
   /** If true, only respond in this group when mentioned. */