@openclaw/bluebubbles 2026.3.1 → 2026.3.7

package/README.md

@@ -10,7 +10,7 @@ If you’re looking for **how to use BlueBubbles as an agent/tool user**, see:
 
 - Extension package: `extensions/bluebubbles/` (entry: `index.ts`).
 - Channel implementation: `extensions/bluebubbles/src/channel.ts`.
-- Webhook handling: `extensions/bluebubbles/src/monitor.ts` (register via `api.registerHttpHandler`).
+- Webhook handling: `extensions/bluebubbles/src/monitor.ts` (register per-account route via `registerPluginHttpRoute`).
 - REST helpers: `extensions/bluebubbles/src/send.ts` + `extensions/bluebubbles/src/probe.ts`.
 - Runtime bridge: `extensions/bluebubbles/src/runtime.ts` (set via `api.runtime`).
 - Catalog entry for onboarding: `src/channels/plugins/catalog.ts`.

package/index.ts

@@ -1,7 +1,6 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
-import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/bluebubbles";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk/bluebubbles";
 import { bluebubblesPlugin } from "./src/channel.js";
-import { handleBlueBubblesWebhookRequest } from "./src/monitor.js";
 import { setBlueBubblesRuntime } from "./src/runtime.js";
 
 const plugin = {
@@ -12,7 +11,6 @@ const plugin = {
   register(api: OpenClawPluginApi) {
     setBlueBubblesRuntime(api.runtime);
     api.registerChannel({ plugin: bluebubblesPlugin });
-    api.registerHttpHandler(handleBlueBubblesWebhookRequest);
   },
 };
 

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@openclaw/bluebubbles",
-  "version": "2026.3.1",
+  "version": "2026.3.7",
   "description": "OpenClaw BlueBubbles channel plugin",
   "type": "module",
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
   "openclaw": {
     "extensions": [
       "./index.ts"

package/src/account-resolve.ts

@@ -1,5 +1,6 @@
-import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/bluebubbles";
 import { resolveBlueBubblesAccount } from "./accounts.js";
+import { normalizeResolvedSecretInputString } from "./secret-input.js";
 
 export type BlueBubblesAccountResolveOpts = {
   serverUrl?: string;
@@ -18,8 +19,24 @@ export function resolveBlueBubblesServerAccount(params: BlueBubblesAccountResolv
     cfg: params.cfg ?? {},
     accountId: params.accountId,
   });
-  const baseUrl = params.serverUrl?.trim() || account.config.serverUrl?.trim();
-  const password = params.password?.trim() || account.config.password?.trim();
+  const baseUrl =
+    normalizeResolvedSecretInputString({
+      value: params.serverUrl,
+      path: "channels.bluebubbles.serverUrl",
+    }) ||
+    normalizeResolvedSecretInputString({
+      value: account.config.serverUrl,
+      path: `channels.bluebubbles.accounts.${account.accountId}.serverUrl`,
+    });
+  const password =
+    normalizeResolvedSecretInputString({
+      value: params.password,
+      path: "channels.bluebubbles.password",
+    }) ||
+    normalizeResolvedSecretInputString({
+      value: account.config.password,
+      path: `channels.bluebubbles.accounts.${account.accountId}.password`,
+    });
   if (!baseUrl) {
     throw new Error("BlueBubbles serverUrl is required");
   }

package/src/accounts.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+import { resolveBlueBubblesAccount } from "./accounts.js";
+
+describe("resolveBlueBubblesAccount", () => {
+  it("treats SecretRef passwords as configured when serverUrl exists", () => {
+    const resolved = resolveBlueBubblesAccount({
+      cfg: {
+        channels: {
+          bluebubbles: {
+            enabled: true,
+            serverUrl: "http://localhost:1234",
+            password: {
+              source: "env",
+              provider: "default",
+              id: "BLUEBUBBLES_PASSWORD",
+            },
+          },
+        },
+      },
+    });
+
+    expect(resolved.configured).toBe(true);
+    expect(resolved.baseUrl).toBe("http://localhost:1234");
+  });
+});

package/src/accounts.ts

@@ -1,9 +1,6 @@
-import type { OpenClawConfig } from "openclaw/plugin-sdk";
-import {
-  DEFAULT_ACCOUNT_ID,
-  normalizeAccountId,
-  normalizeOptionalAccountId,
-} from "openclaw/plugin-sdk/account-id";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+import { createAccountListHelpers, type OpenClawConfig } from "openclaw/plugin-sdk/bluebubbles";
+import { hasConfiguredSecretInput, normalizeSecretInputString } from "./secret-input.js";
 import { normalizeBlueBubblesServerUrl, type BlueBubblesAccountConfig } from "./types.js";
 
 export type ResolvedBlueBubblesAccount = {
@@ -15,36 +12,11 @@ export type ResolvedBlueBubblesAccount = {
   baseUrl?: string;
 };
 
-function listConfiguredAccountIds(cfg: OpenClawConfig): string[] {
-  const accounts = cfg.channels?.bluebubbles?.accounts;
-  if (!accounts || typeof accounts !== "object") {
-    return [];
-  }
-  return Object.keys(accounts).filter(Boolean);
-}
-
-export function listBlueBubblesAccountIds(cfg: OpenClawConfig): string[] {
-  const ids = listConfiguredAccountIds(cfg);
-  if (ids.length === 0) {
-    return [DEFAULT_ACCOUNT_ID];
-  }
-  return ids.toSorted((a, b) => a.localeCompare(b));
-}
-
-export function resolveDefaultBlueBubblesAccountId(cfg: OpenClawConfig): string {
-  const preferred = normalizeOptionalAccountId(cfg.channels?.bluebubbles?.defaultAccount);
-  if (
-    preferred &&
-    listBlueBubblesAccountIds(cfg).some((accountId) => normalizeAccountId(accountId) === preferred)
-  ) {
-    return preferred;
-  }
-  const ids = listBlueBubblesAccountIds(cfg);
-  if (ids.includes(DEFAULT_ACCOUNT_ID)) {
-    return DEFAULT_ACCOUNT_ID;
-  }
-  return ids[0] ?? DEFAULT_ACCOUNT_ID;
-}
+const {
+  listAccountIds: listBlueBubblesAccountIds,
+  resolveDefaultAccountId: resolveDefaultBlueBubblesAccountId,
+} = createAccountListHelpers("bluebubbles");
+export { listBlueBubblesAccountIds, resolveDefaultBlueBubblesAccountId };
 
 function resolveAccountConfig(
   cfg: OpenClawConfig,
@@ -79,9 +51,9 @@ export function resolveBlueBubblesAccount(params: {
   const baseEnabled = params.cfg.channels?.bluebubbles?.enabled;
   const merged = mergeBlueBubblesAccountConfig(params.cfg, accountId);
   const accountEnabled = merged.enabled !== false;
-  const serverUrl = merged.serverUrl?.trim();
-  const password = merged.password?.trim();
-  const configured = Boolean(serverUrl && password);
+  const serverUrl = normalizeSecretInputString(merged.serverUrl);
+  const password = normalizeSecretInputString(merged.password);
+  const configured = Boolean(serverUrl && hasConfiguredSecretInput(merged.password));
   const baseUrl = serverUrl ? normalizeBlueBubblesServerUrl(serverUrl) : undefined;
   return {
     accountId,

package/src/actions.test.ts

@@ -1,4 +1,4 @@
-import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/bluebubbles";
 import { describe, expect, it, vi, beforeEach } from "vitest";
 import { bluebubblesMessageActions } from "./actions.js";
 import { getCachedBlueBubblesPrivateApiStatus } from "./probe.js";

package/src/actions.ts

@@ -5,11 +5,12 @@ import {
   extractToolSend,
   jsonResult,
   readNumberParam,
+  readBooleanParam,
   readReactionParams,
   readStringParam,
   type ChannelMessageActionAdapter,
   type ChannelMessageActionName,
-} from "openclaw/plugin-sdk";
+} from "openclaw/plugin-sdk/bluebubbles";
 import { resolveBlueBubblesAccount } from "./accounts.js";
 import { sendBlueBubblesAttachment } from "./attachments.js";
 import {
@@ -24,6 +25,7 @@ import {
 import { resolveBlueBubblesMessageId } from "./monitor.js";
 import { getCachedBlueBubblesPrivateApiStatus, isMacOS26OrHigher } from "./probe.js";
 import { sendBlueBubblesReaction } from "./reactions.js";
+import { normalizeSecretInputString } from "./secret-input.js";
 import { resolveChatGuidForTarget, sendMessageBlueBubbles } from "./send.js";
 import { normalizeBlueBubblesHandle, parseBlueBubblesTarget } from "./targets.js";
 import type { BlueBubblesSendTarget } from "./types.js";
@@ -52,23 +54,6 @@ function readMessageText(params: Record<string, unknown>): string | undefined {
   return readStringParam(params, "text") ?? readStringParam(params, "message");
 }
 
-function readBooleanParam(params: Record<string, unknown>, key: string): boolean | undefined {
-  const raw = params[key];
-  if (typeof raw === "boolean") {
-    return raw;
-  }
-  if (typeof raw === "string") {
-    const trimmed = raw.trim().toLowerCase();
-    if (trimmed === "true") {
-      return true;
-    }
-    if (trimmed === "false") {
-      return false;
-    }
-  }
-  return undefined;
-}
-
 /** Supported action names for BlueBubbles */
 const SUPPORTED_ACTIONS = new Set<ChannelMessageActionName>(BLUEBUBBLES_ACTION_NAMES);
 const PRIVATE_API_ACTIONS = new Set<ChannelMessageActionName>([
@@ -118,8 +103,8 @@ export const bluebubblesMessageActions: ChannelMessageActionAdapter = {
       cfg: cfg,
       accountId: accountId ?? undefined,
     });
-    const baseUrl = account.config.serverUrl?.trim();
-    const password = account.config.password?.trim();
+    const baseUrl = normalizeSecretInputString(account.config.serverUrl);
+    const password = normalizeSecretInputString(account.config.password);
     const opts = { cfg: cfg, accountId: accountId ?? undefined };
     const assertPrivateApiEnabled = () => {
       if (getCachedBlueBubblesPrivateApiStatus(account.accountId) === false) {

package/src/attachments.test.ts

@@ -1,4 +1,4 @@
-import type { PluginRuntime } from "openclaw/plugin-sdk";
+import type { PluginRuntime } from "openclaw/plugin-sdk/bluebubbles";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import "./test-mocks.js";
 import { downloadBlueBubblesAttachment, sendBlueBubblesAttachment } from "./attachments.js";

package/src/attachments.ts

@@ -1,6 +1,6 @@
 import crypto from "node:crypto";
 import path from "node:path";
-import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/bluebubbles";
 import { resolveBlueBubblesServerAccount } from "./account-resolve.js";
 import { postMultipartFormData } from "./multipart.js";
 import {

package/src/channel.ts

@@ -1,18 +1,29 @@
-import type { ChannelAccountSnapshot, ChannelPlugin, OpenClawConfig } from "openclaw/plugin-sdk";
+import type {
+  ChannelAccountSnapshot,
+  ChannelPlugin,
+  OpenClawConfig,
+} from "openclaw/plugin-sdk/bluebubbles";
 import {
   applyAccountNameToChannelSection,
   buildChannelConfigSchema,
+  buildComputedAccountStatusSnapshot,
+  buildProbeChannelStatusSummary,
   collectBlueBubblesStatusIssues,
   DEFAULT_ACCOUNT_ID,
   deleteAccountFromConfigSection,
-  formatPairingApproveHint,
   migrateBaseNameToDefaultAccount,
   normalizeAccountId,
   PAIRING_APPROVED_MESSAGE,
   resolveBlueBubblesGroupRequireMention,
   resolveBlueBubblesGroupToolPolicy,
   setAccountEnabledInConfigSection,
-} from "openclaw/plugin-sdk";
+} from "openclaw/plugin-sdk/bluebubbles";
+import {
+  buildAccountScopedDmSecurityPolicy,
+  collectOpenGroupPolicyRestrictSendersWarnings,
+  formatNormalizedAllowFromEntries,
+  mapAllowFromEntries,
+} from "openclaw/plugin-sdk/compat";
 import {
   listBlueBubblesAccountIds,
   type ResolvedBlueBubblesAccount,
@@ -20,6 +31,7 @@ import {
   resolveDefaultBlueBubblesAccountId,
 } from "./accounts.js";
 import { bluebubblesMessageActions } from "./actions.js";
+import { applyBlueBubblesConnectionConfig } from "./config-apply.js";
 import { BlueBubblesConfigSchema } from "./config-schema.js";
 import { sendBlueBubblesMedia } from "./media-send.js";
 import { resolveBlueBubblesMessageId } from "./monitor.js";
@@ -104,41 +116,37 @@ export const bluebubblesPlugin: ChannelPlugin<ResolvedBlueBubblesAccount> = {
       baseUrl: account.baseUrl,
     }),
     resolveAllowFrom: ({ cfg, accountId }) =>
-      (resolveBlueBubblesAccount({ cfg: cfg, accountId }).config.allowFrom ?? []).map((entry) =>
-        String(entry),
-      ),
+      mapAllowFromEntries(resolveBlueBubblesAccount({ cfg: cfg, accountId }).config.allowFrom),
     formatAllowFrom: ({ allowFrom }) =>
-      allowFrom
-        .map((entry) => String(entry).trim())
-        .filter(Boolean)
-        .map((entry) => entry.replace(/^bluebubbles:/i, ""))
-        .map((entry) => normalizeBlueBubblesHandle(entry)),
+      formatNormalizedAllowFromEntries({
+        allowFrom,
+        normalizeEntry: (entry) => normalizeBlueBubblesHandle(entry.replace(/^bluebubbles:/i, "")),
+      }),
   },
   actions: bluebubblesMessageActions,
   security: {
     resolveDmPolicy: ({ cfg, accountId, account }) => {
-      const resolvedAccountId = accountId ?? account.accountId ?? DEFAULT_ACCOUNT_ID;
-      const useAccountPath = Boolean(cfg.channels?.bluebubbles?.accounts?.[resolvedAccountId]);
-      const basePath = useAccountPath
-        ? `channels.bluebubbles.accounts.${resolvedAccountId}.`
-        : "channels.bluebubbles.";
-      return {
-        policy: account.config.dmPolicy ?? "pairing",
+      return buildAccountScopedDmSecurityPolicy({
+        cfg,
+        channelKey: "bluebubbles",
+        accountId,
+        fallbackAccountId: account.accountId ?? DEFAULT_ACCOUNT_ID,
+        policy: account.config.dmPolicy,
         allowFrom: account.config.allowFrom ?? [],
-        policyPath: `${basePath}dmPolicy`,
-        allowFromPath: basePath,
-        approveHint: formatPairingApproveHint("bluebubbles"),
+        policyPathSuffix: "dmPolicy",
         normalizeEntry: (raw) => normalizeBlueBubblesHandle(raw.replace(/^bluebubbles:/i, "")),
-      };
+      });
     },
     collectWarnings: ({ account }) => {
       const groupPolicy = account.config.groupPolicy ?? "allowlist";
-      if (groupPolicy !== "open") {
-        return [];
-      }
-      return [
-        `- BlueBubbles groups: groupPolicy="open" allows any member to trigger the bot. Set channels.bluebubbles.groupPolicy="allowlist" + channels.bluebubbles.groupAllowFrom to restrict senders.`,
-      ];
+      return collectOpenGroupPolicyRestrictSendersWarnings({
+        groupPolicy,
+        surface: "BlueBubbles groups",
+        openScope: "any member",
+        groupPolicyPath: "channels.bluebubbles.groupPolicy",
+        groupAllowFromPath: "channels.bluebubbles.groupAllowFrom",
+        mentionGated: false,
+      });
     },
   },
   messaging: {
@@ -249,41 +257,16 @@ export const bluebubblesPlugin: ChannelPlugin<ResolvedBlueBubblesAccount> = {
               channelKey: "bluebubbles",
             })
           : namedConfig;
-      if (accountId === DEFAULT_ACCOUNT_ID) {
-        return {
-          ...next,
-          channels: {
-            ...next.channels,
-            bluebubbles: {
-              ...next.channels?.bluebubbles,
-              enabled: true,
-              ...(input.httpUrl ? { serverUrl: input.httpUrl } : {}),
-              ...(input.password ? { password: input.password } : {}),
-              ...(input.webhookPath ? { webhookPath: input.webhookPath } : {}),
-            },
-          },
-        } as OpenClawConfig;
-      }
-      return {
-        ...next,
-        channels: {
-          ...next.channels,
-          bluebubbles: {
-            ...next.channels?.bluebubbles,
-            enabled: true,
-            accounts: {
-              ...next.channels?.bluebubbles?.accounts,
-              [accountId]: {
-                ...next.channels?.bluebubbles?.accounts?.[accountId],
-                enabled: true,
-                ...(input.httpUrl ? { serverUrl: input.httpUrl } : {}),
-                ...(input.password ? { password: input.password } : {}),
-                ...(input.webhookPath ? { webhookPath: input.webhookPath } : {}),
-              },
-            },
-          },
+      return applyBlueBubblesConnectionConfig({
+        cfg: next,
+        accountId,
+        patch: {
+          serverUrl: input.httpUrl,
+          password: input.password,
+          webhookPath: input.webhookPath,
         },
-      } as OpenClawConfig;
+        onlyDefinedFields: true,
+      });
     },
   },
   pairing: {
@@ -356,16 +339,8 @@ export const bluebubblesPlugin: ChannelPlugin<ResolvedBlueBubblesAccount> = {
       lastError: null,
     },
     collectStatusIssues: collectBlueBubblesStatusIssues,
-    buildChannelSummary: ({ snapshot }) => ({
-      configured: snapshot.configured ?? false,
-      baseUrl: snapshot.baseUrl ?? null,
-      running: snapshot.running ?? false,
-      lastStartAt: snapshot.lastStartAt ?? null,
-      lastStopAt: snapshot.lastStopAt ?? null,
-      lastError: snapshot.lastError ?? null,
-      probe: snapshot.probe,
-      lastProbeAt: snapshot.lastProbeAt ?? null,
-    }),
+    buildChannelSummary: ({ snapshot }) =>
+      buildProbeChannelStatusSummary(snapshot, { baseUrl: snapshot.baseUrl ?? null }),
     probeAccount: async ({ account, timeoutMs }) =>
       probeBlueBubbles({
         baseUrl: account.baseUrl,
@@ -375,20 +350,18 @@ export const bluebubblesPlugin: ChannelPlugin<ResolvedBlueBubblesAccount> = {
     buildAccountSnapshot: ({ account, runtime, probe }) => {
       const running = runtime?.running ?? false;
       const probeOk = (probe as BlueBubblesProbe | undefined)?.ok;
-      return {
+      const base = buildComputedAccountStatusSnapshot({
         accountId: account.accountId,
         name: account.name,
         enabled: account.enabled,
         configured: account.configured,
+        runtime,
+        probe,
+      });
+      return {
+        ...base,
         baseUrl: account.baseUrl,
-        running,
         connected: probeOk ?? running,
-        lastStartAt: runtime?.lastStartAt ?? null,
-        lastStopAt: runtime?.lastStopAt ?? null,
-        lastError: runtime?.lastError ?? null,
-        probe,
-        lastInboundAt: runtime?.lastInboundAt ?? null,
-        lastOutboundAt: runtime?.lastOutboundAt ?? null,
       };
     },
   },

package/src/chat.ts

@@ -1,6 +1,6 @@
 import crypto from "node:crypto";
 import path from "node:path";
-import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/bluebubbles";
 import { resolveBlueBubblesServerAccount } from "./account-resolve.js";
 import { postMultipartFormData } from "./multipart.js";
 import { getCachedBlueBubblesPrivateApiStatus } from "./probe.js";
@@ -30,6 +30,39 @@ function resolvePartIndex(partIndex: number | undefined): number {
   return typeof partIndex === "number" ? partIndex : 0;
 }
 
+async function sendBlueBubblesChatEndpointRequest(params: {
+  chatGuid: string;
+  opts: BlueBubblesChatOpts;
+  endpoint: "read" | "typing";
+  method: "POST" | "DELETE";
+  action: "read" | "typing";
+}): Promise<void> {
+  const trimmed = params.chatGuid.trim();
+  if (!trimmed) {
+    return;
+  }
+  const { baseUrl, password, accountId } = resolveAccount(params.opts);
+  if (getCachedBlueBubblesPrivateApiStatus(accountId) === false) {
+    return;
+  }
+  const url = buildBlueBubblesApiUrl({
+    baseUrl,
+    path: `/api/v1/chat/${encodeURIComponent(trimmed)}/${params.endpoint}`,
+    password,
+  });
+  const res = await blueBubblesFetchWithTimeout(
+    url,
+    { 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"}`,
+    );
+  }
+}
+
 async function sendPrivateApiJsonRequest(params: {
   opts: BlueBubblesChatOpts;
   feature: string;
@@ -65,24 +98,13 @@ export async function markBlueBubblesChatRead(
   chatGuid: string,
   opts: BlueBubblesChatOpts = {},
 ): Promise<void> {
-  const trimmed = chatGuid.trim();
-  if (!trimmed) {
-    return;
-  }
-  const { baseUrl, password, accountId } = resolveAccount(opts);
-  if (getCachedBlueBubblesPrivateApiStatus(accountId) === false) {
-    return;
-  }
-  const url = buildBlueBubblesApiUrl({
-    baseUrl,
-    path: `/api/v1/chat/${encodeURIComponent(trimmed)}/read`,
-    password,
+  await sendBlueBubblesChatEndpointRequest({
+    chatGuid,
+    opts,
+    endpoint: "read",
+    method: "POST",
+    action: "read",
   });
-  const res = await blueBubblesFetchWithTimeout(url, { method: "POST" }, opts.timeoutMs);
-  if (!res.ok) {
-    const errorText = await res.text().catch(() => "");
-    throw new Error(`BlueBubbles read failed (${res.status}): ${errorText || "unknown"}`);
-  }
 }
 
 export async function sendBlueBubblesTyping(
@@ -90,28 +112,13 @@ export async function sendBlueBubblesTyping(
   typing: boolean,
   opts: BlueBubblesChatOpts = {},
 ): Promise<void> {
-  const trimmed = chatGuid.trim();
-  if (!trimmed) {
-    return;
-  }
-  const { baseUrl, password, accountId } = resolveAccount(opts);
-  if (getCachedBlueBubblesPrivateApiStatus(accountId) === false) {
-    return;
-  }
-  const url = buildBlueBubblesApiUrl({
-    baseUrl,
-    path: `/api/v1/chat/${encodeURIComponent(trimmed)}/typing`,
-    password,
+  await sendBlueBubblesChatEndpointRequest({
+    chatGuid,
+    opts,
+    endpoint: "typing",
+    method: typing ? "POST" : "DELETE",
+    action: "typing",
   });
-  const res = await blueBubblesFetchWithTimeout(
-    url,
-    { method: typing ? "POST" : "DELETE" },
-    opts.timeoutMs,
-  );
-  if (!res.ok) {
-    const errorText = await res.text().catch(() => "");
-    throw new Error(`BlueBubbles typing failed (${res.status}): ${errorText || "unknown"}`);
-  }
 }
 
 /**

package/src/config-apply.ts

@@ -0,0 +1,77 @@
+import { DEFAULT_ACCOUNT_ID, type OpenClawConfig } from "openclaw/plugin-sdk/bluebubbles";
+
+type BlueBubblesConfigPatch = {
+  serverUrl?: string;
+  password?: unknown;
+  webhookPath?: string;
+};
+
+type AccountEnabledMode = boolean | "preserve-or-true";
+
+function normalizePatch(
+  patch: BlueBubblesConfigPatch,
+  onlyDefinedFields: boolean,
+): BlueBubblesConfigPatch {
+  if (!onlyDefinedFields) {
+    return patch;
+  }
+  const next: BlueBubblesConfigPatch = {};
+  if (patch.serverUrl !== undefined) {
+    next.serverUrl = patch.serverUrl;
+  }
+  if (patch.password !== undefined) {
+    next.password = patch.password;
+  }
+  if (patch.webhookPath !== undefined) {
+    next.webhookPath = patch.webhookPath;
+  }
+  return next;
+}
+
+export function applyBlueBubblesConnectionConfig(params: {
+  cfg: OpenClawConfig;
+  accountId: string;
+  patch: BlueBubblesConfigPatch;
+  onlyDefinedFields?: boolean;
+  accountEnabled?: AccountEnabledMode;
+}): OpenClawConfig {
+  const patch = normalizePatch(params.patch, params.onlyDefinedFields === true);
+  if (params.accountId === DEFAULT_ACCOUNT_ID) {
+    return {
+      ...params.cfg,
+      channels: {
+        ...params.cfg.channels,
+        bluebubbles: {
+          ...params.cfg.channels?.bluebubbles,
+          enabled: true,
+          ...patch,
+        },
+      },
+    };
+  }
+
+  const currentAccount = params.cfg.channels?.bluebubbles?.accounts?.[params.accountId];
+  const enabled =
+    params.accountEnabled === "preserve-or-true"
+      ? (currentAccount?.enabled ?? true)
+      : (params.accountEnabled ?? true);
+
+  return {
+    ...params.cfg,
+    channels: {
+      ...params.cfg.channels,
+      bluebubbles: {
+        ...params.cfg.channels?.bluebubbles,
+        enabled: true,
+        accounts: {
+          ...params.cfg.channels?.bluebubbles?.accounts,
+          [params.accountId]: {
+            ...currentAccount,
+            enabled,
+            ...patch,
+          },
+        },
+      },
+    },
+  };
+}

package/src/config-schema.test.ts

@@ -5,7 +5,19 @@ describe("BlueBubblesConfigSchema", () => {
   it("accepts account config when serverUrl and password are both set", () => {
     const parsed = BlueBubblesConfigSchema.safeParse({
       serverUrl: "http://localhost:1234",
-      password: "secret",
+      password: "secret", // pragma: allowlist secret
+    });
+    expect(parsed.success).toBe(true);
+  });
+
+  it("accepts SecretRef password when serverUrl is set", () => {
+    const parsed = BlueBubblesConfigSchema.safeParse({
+      serverUrl: "http://localhost:1234",
+      password: {
+        source: "env",
+        provider: "default",
+        id: "BLUEBUBBLES_PASSWORD",
+      },
     });
     expect(parsed.success).toBe(true);
   });