@openclaw/bluebubbles 2026.2.25 → 2026.3.2

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

@@ -0,0 +1,44 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+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,81 @@
+import type { WizardPrompter } from "openclaw/plugin-sdk";
+import { describe, expect, it, vi } from "vitest";
+
+vi.mock("openclaw/plugin-sdk", () => ({
+  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,
+  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(),
+}));
+
+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

@@ -18,6 +18,7 @@ import {
   resolveBlueBubblesAccount,
   resolveDefaultBlueBubblesAccountId,
 } from "./accounts.js";
+import { hasConfiguredSecretInput, normalizeSecretInputString } from "./secret-input.js";
 import { parseBlueBubblesAllowTarget } from "./targets.js";
 import { normalizeBlueBubblesServerUrl } from "./types.js";
 
@@ -222,8 +223,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 +251,8 @@ export const blueBubblesOnboardingAdapter: ChannelOnboardingAdapter = {
           validate: (value) => (String(value ?? "").trim() ? undefined : "Required"),
         });
         password = String(entered).trim();
+      } else if (!existingPasswordText) {
+        password = existingPassword;
       }
     }
 

package/src/probe.ts

@@ -1,4 +1,5 @@
 import type { BaseProbeResult } from "openclaw/plugin-sdk";
+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/secret-input.ts

@@ -0,0 +1,19 @@
+import {
+  hasConfiguredSecretInput,
+  normalizeResolvedSecretInputString,
+  normalizeSecretInputString,
+} from "openclaw/plugin-sdk";
+import { z } from "zod";
+
+export { hasConfiguredSecretInput, normalizeResolvedSecretInputString, normalizeSecretInputString };
+
+export function buildSecretInputSchema() {
+  return z.union([
+    z.string(),
+    z.object({
+      source: z.enum(["env", "file", "exec"]),
+      provider: z.string().min(1),
+      id: z.string().min(1),
+    }),
+  ]);
+}

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

@@ -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

@@ -7,6 +7,7 @@ import {
   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 {
@@ -372,8 +373,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");
   }

package/src/targets.ts

@@ -2,6 +2,7 @@ import {
   isAllowedParsedChatSender,
   parseChatAllowTargetPrefixes,
   parseChatTargetPrefixesOrThrow,
+  type ParsedChatTarget,
   resolveServicePrefixedAllowTarget,
   resolveServicePrefixedTarget,
 } from "openclaw/plugin-sdk";
@@ -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

@@ -75,6 +75,8 @@ export type BlueBubblesActionConfig = {
 export type BlueBubblesConfig = {
   /** Optional per-account BlueBubbles configuration (multi-account). */
   accounts?: Record<string, BlueBubblesAccountConfig>;
+  /** Optional default account id when multiple accounts are configured. */
+  defaultAccount?: string;
   /** Per-action tool gating (default: true for all). */
   actions?: BlueBubblesActionConfig;
 } & BlueBubblesAccountConfig;