@openclaw/bluebubbles 2026.1.29

package/src/chat.ts

@@ -0,0 +1,354 @@
+import crypto from "node:crypto";
+import { resolveBlueBubblesAccount } from "./accounts.js";
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import { blueBubblesFetchWithTimeout, buildBlueBubblesApiUrl } from "./types.js";
+
+export type BlueBubblesChatOpts = {
+  serverUrl?: string;
+  password?: string;
+  accountId?: string;
+  timeoutMs?: number;
+  cfg?: OpenClawConfig;
+};
+
+function resolveAccount(params: BlueBubblesChatOpts) {
+  const account = resolveBlueBubblesAccount({
+    cfg: params.cfg ?? {},
+    accountId: params.accountId,
+  });
+  const baseUrl = params.serverUrl?.trim() || account.config.serverUrl?.trim();
+  const password = params.password?.trim() || account.config.password?.trim();
+  if (!baseUrl) throw new Error("BlueBubbles serverUrl is required");
+  if (!password) throw new Error("BlueBubbles password is required");
+  return { baseUrl, password };
+}
+
+export async function markBlueBubblesChatRead(
+  chatGuid: string,
+  opts: BlueBubblesChatOpts = {},
+): Promise<void> {
+  const trimmed = chatGuid.trim();
+  if (!trimmed) return;
+  const { baseUrl, password } = resolveAccount(opts);
+  const url = buildBlueBubblesApiUrl({
+    baseUrl,
+    path: `/api/v1/chat/${encodeURIComponent(trimmed)}/read`,
+    password,
+  });
+  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(
+  chatGuid: string,
+  typing: boolean,
+  opts: BlueBubblesChatOpts = {},
+): Promise<void> {
+  const trimmed = chatGuid.trim();
+  if (!trimmed) return;
+  const { baseUrl, password } = resolveAccount(opts);
+  const url = buildBlueBubblesApiUrl({
+    baseUrl,
+    path: `/api/v1/chat/${encodeURIComponent(trimmed)}/typing`,
+    password,
+  });
+  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"}`);
+  }
+}
+
+/**
+ * Edit a message via BlueBubbles API.
+ * Requires macOS 13 (Ventura) or higher with Private API enabled.
+ */
+export async function editBlueBubblesMessage(
+  messageGuid: string,
+  newText: string,
+  opts: BlueBubblesChatOpts & { partIndex?: number; backwardsCompatMessage?: string } = {},
+): Promise<void> {
+  const trimmedGuid = messageGuid.trim();
+  if (!trimmedGuid) throw new Error("BlueBubbles edit requires messageGuid");
+  const trimmedText = newText.trim();
+  if (!trimmedText) throw new Error("BlueBubbles edit requires newText");
+
+  const { baseUrl, password } = resolveAccount(opts);
+  const url = buildBlueBubblesApiUrl({
+    baseUrl,
+    path: `/api/v1/message/${encodeURIComponent(trimmedGuid)}/edit`,
+    password,
+  });
+
+  const payload = {
+    editedMessage: trimmedText,
+    backwardsCompatibilityMessage: opts.backwardsCompatMessage ?? `Edited to: ${trimmedText}`,
+    partIndex: typeof opts.partIndex === "number" ? opts.partIndex : 0,
+  };
+
+  const res = await blueBubblesFetchWithTimeout(
+    url,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    },
+    opts.timeoutMs,
+  );
+
+  if (!res.ok) {
+    const errorText = await res.text().catch(() => "");
+    throw new Error(`BlueBubbles edit failed (${res.status}): ${errorText || "unknown"}`);
+  }
+}
+
+/**
+ * Unsend (retract) a message via BlueBubbles API.
+ * Requires macOS 13 (Ventura) or higher with Private API enabled.
+ */
+export async function unsendBlueBubblesMessage(
+  messageGuid: string,
+  opts: BlueBubblesChatOpts & { partIndex?: number } = {},
+): Promise<void> {
+  const trimmedGuid = messageGuid.trim();
+  if (!trimmedGuid) throw new Error("BlueBubbles unsend requires messageGuid");
+
+  const { baseUrl, password } = resolveAccount(opts);
+  const url = buildBlueBubblesApiUrl({
+    baseUrl,
+    path: `/api/v1/message/${encodeURIComponent(trimmedGuid)}/unsend`,
+    password,
+  });
+
+  const payload = {
+    partIndex: typeof opts.partIndex === "number" ? opts.partIndex : 0,
+  };
+
+  const res = await blueBubblesFetchWithTimeout(
+    url,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    },
+    opts.timeoutMs,
+  );
+
+  if (!res.ok) {
+    const errorText = await res.text().catch(() => "");
+    throw new Error(`BlueBubbles unsend failed (${res.status}): ${errorText || "unknown"}`);
+  }
+}
+
+/**
+ * Rename a group chat via BlueBubbles API.
+ */
+export async function renameBlueBubblesChat(
+  chatGuid: string,
+  displayName: string,
+  opts: BlueBubblesChatOpts = {},
+): Promise<void> {
+  const trimmedGuid = chatGuid.trim();
+  if (!trimmedGuid) throw new Error("BlueBubbles rename requires chatGuid");
+
+  const { baseUrl, password } = resolveAccount(opts);
+  const url = buildBlueBubblesApiUrl({
+    baseUrl,
+    path: `/api/v1/chat/${encodeURIComponent(trimmedGuid)}`,
+    password,
+  });
+
+  const res = await blueBubblesFetchWithTimeout(
+    url,
+    {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ displayName }),
+    },
+    opts.timeoutMs,
+  );
+
+  if (!res.ok) {
+    const errorText = await res.text().catch(() => "");
+    throw new Error(`BlueBubbles rename failed (${res.status}): ${errorText || "unknown"}`);
+  }
+}
+
+/**
+ * Add a participant to a group chat via BlueBubbles API.
+ */
+export async function addBlueBubblesParticipant(
+  chatGuid: string,
+  address: string,
+  opts: BlueBubblesChatOpts = {},
+): Promise<void> {
+  const trimmedGuid = chatGuid.trim();
+  if (!trimmedGuid) throw new Error("BlueBubbles addParticipant requires chatGuid");
+  const trimmedAddress = address.trim();
+  if (!trimmedAddress) throw new Error("BlueBubbles addParticipant requires address");
+
+  const { baseUrl, password } = resolveAccount(opts);
+  const url = buildBlueBubblesApiUrl({
+    baseUrl,
+    path: `/api/v1/chat/${encodeURIComponent(trimmedGuid)}/participant`,
+    password,
+  });
+
+  const res = await blueBubblesFetchWithTimeout(
+    url,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ address: trimmedAddress }),
+    },
+    opts.timeoutMs,
+  );
+
+  if (!res.ok) {
+    const errorText = await res.text().catch(() => "");
+    throw new Error(`BlueBubbles addParticipant failed (${res.status}): ${errorText || "unknown"}`);
+  }
+}
+
+/**
+ * Remove a participant from a group chat via BlueBubbles API.
+ */
+export async function removeBlueBubblesParticipant(
+  chatGuid: string,
+  address: string,
+  opts: BlueBubblesChatOpts = {},
+): Promise<void> {
+  const trimmedGuid = chatGuid.trim();
+  if (!trimmedGuid) throw new Error("BlueBubbles removeParticipant requires chatGuid");
+  const trimmedAddress = address.trim();
+  if (!trimmedAddress) throw new Error("BlueBubbles removeParticipant requires address");
+
+  const { baseUrl, password } = resolveAccount(opts);
+  const url = buildBlueBubblesApiUrl({
+    baseUrl,
+    path: `/api/v1/chat/${encodeURIComponent(trimmedGuid)}/participant`,
+    password,
+  });
+
+  const res = await blueBubblesFetchWithTimeout(
+    url,
+    {
+      method: "DELETE",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ address: trimmedAddress }),
+    },
+    opts.timeoutMs,
+  );
+
+  if (!res.ok) {
+    const errorText = await res.text().catch(() => "");
+    throw new Error(`BlueBubbles removeParticipant failed (${res.status}): ${errorText || "unknown"}`);
+  }
+}
+
+/**
+ * Leave a group chat via BlueBubbles API.
+ */
+export async function leaveBlueBubblesChat(
+  chatGuid: string,
+  opts: BlueBubblesChatOpts = {},
+): Promise<void> {
+  const trimmedGuid = chatGuid.trim();
+  if (!trimmedGuid) throw new Error("BlueBubbles leaveChat requires chatGuid");
+
+  const { baseUrl, password } = resolveAccount(opts);
+  const url = buildBlueBubblesApiUrl({
+    baseUrl,
+    path: `/api/v1/chat/${encodeURIComponent(trimmedGuid)}/leave`,
+    password,
+  });
+
+  const res = await blueBubblesFetchWithTimeout(
+    url,
+    { method: "POST" },
+    opts.timeoutMs,
+  );
+
+  if (!res.ok) {
+    const errorText = await res.text().catch(() => "");
+    throw new Error(`BlueBubbles leaveChat failed (${res.status}): ${errorText || "unknown"}`);
+  }
+}
+
+/**
+ * Set a group chat's icon/photo via BlueBubbles API.
+ * Requires Private API to be enabled.
+ */
+export async function setGroupIconBlueBubbles(
+  chatGuid: string,
+  buffer: Uint8Array,
+  filename: string,
+  opts: BlueBubblesChatOpts & { contentType?: string } = {},
+): Promise<void> {
+  const trimmedGuid = chatGuid.trim();
+  if (!trimmedGuid) throw new Error("BlueBubbles setGroupIcon requires chatGuid");
+  if (!buffer || buffer.length === 0) {
+    throw new Error("BlueBubbles setGroupIcon requires image buffer");
+  }
+
+  const { baseUrl, password } = resolveAccount(opts);
+  const url = buildBlueBubblesApiUrl({
+    baseUrl,
+    path: `/api/v1/chat/${encodeURIComponent(trimmedGuid)}/icon`,
+    password,
+  });
+
+  // Build multipart form-data
+  const boundary = `----BlueBubblesFormBoundary${crypto.randomUUID().replace(/-/g, "")}`;
+  const parts: Uint8Array[] = [];
+  const encoder = new TextEncoder();
+
+  // Add file field named "icon" as per API spec
+  parts.push(encoder.encode(`--${boundary}\r\n`));
+  parts.push(
+    encoder.encode(
+      `Content-Disposition: form-data; name="icon"; filename="${filename}"\r\n`,
+    ),
+  );
+  parts.push(
+    encoder.encode(`Content-Type: ${opts.contentType ?? "application/octet-stream"}\r\n\r\n`),
+  );
+  parts.push(buffer);
+  parts.push(encoder.encode("\r\n"));
+
+  // Close multipart body
+  parts.push(encoder.encode(`--${boundary}--\r\n`));
+
+  // Combine into single buffer
+  const totalLength = parts.reduce((acc, part) => acc + part.length, 0);
+  const body = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const part of parts) {
+    body.set(part, offset);
+    offset += part.length;
+  }
+
+  const res = await blueBubblesFetchWithTimeout(
+    url,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": `multipart/form-data; boundary=${boundary}`,
+      },
+      body,
+    },
+    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"}`);
+  }
+}

package/src/config-schema.ts

@@ -0,0 +1,51 @@
+import { MarkdownConfigSchema, ToolPolicySchema } from "openclaw/plugin-sdk";
+import { z } from "zod";
+
+const allowFromEntry = z.union([z.string(), z.number()]);
+
+const bluebubblesActionSchema = z
+  .object({
+    reactions: z.boolean().default(true),
+    edit: z.boolean().default(true),
+    unsend: z.boolean().default(true),
+    reply: z.boolean().default(true),
+    sendWithEffect: z.boolean().default(true),
+    renameGroup: z.boolean().default(true),
+    setGroupIcon: z.boolean().default(true),
+    addParticipant: z.boolean().default(true),
+    removeParticipant: z.boolean().default(true),
+    leaveGroup: z.boolean().default(true),
+    sendAttachment: z.boolean().default(true),
+  })
+  .optional();
+
+const bluebubblesGroupConfigSchema = z.object({
+  requireMention: z.boolean().optional(),
+  tools: ToolPolicySchema,
+});
+
+const bluebubblesAccountSchema = z.object({
+  name: z.string().optional(),
+  enabled: z.boolean().optional(),
+  markdown: MarkdownConfigSchema,
+  serverUrl: z.string().optional(),
+  password: z.string().optional(),
+  webhookPath: z.string().optional(),
+  dmPolicy: z.enum(["pairing", "allowlist", "open", "disabled"]).optional(),
+  allowFrom: z.array(allowFromEntry).optional(),
+  groupAllowFrom: z.array(allowFromEntry).optional(),
+  groupPolicy: z.enum(["open", "disabled", "allowlist"]).optional(),
+  historyLimit: z.number().int().min(0).optional(),
+  dmHistoryLimit: z.number().int().min(0).optional(),
+  textChunkLimit: z.number().int().positive().optional(),
+  chunkMode: z.enum(["length", "newline"]).optional(),
+  mediaMaxMb: z.number().int().positive().optional(),
+  sendReadReceipts: z.boolean().optional(),
+  blockStreaming: z.boolean().optional(),
+  groups: z.object({}).catchall(bluebubblesGroupConfigSchema).optional(),
+});
+
+export const BlueBubblesConfigSchema = bluebubblesAccountSchema.extend({
+  accounts: z.object({}).catchall(bluebubblesAccountSchema).optional(),
+  actions: bluebubblesActionSchema,
+});

package/src/media-send.ts

@@ -0,0 +1,168 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { resolveChannelMediaMaxBytes, type OpenClawConfig } from "openclaw/plugin-sdk";
+
+import { sendBlueBubblesAttachment } from "./attachments.js";
+import { resolveBlueBubblesMessageId } from "./monitor.js";
+import { getBlueBubblesRuntime } from "./runtime.js";
+import { sendMessageBlueBubbles } from "./send.js";
+
+const HTTP_URL_RE = /^https?:\/\//i;
+const MB = 1024 * 1024;
+
+function assertMediaWithinLimit(sizeBytes: number, maxBytes?: number): void {
+  if (typeof maxBytes !== "number" || maxBytes <= 0) return;
+  if (sizeBytes <= maxBytes) return;
+  const maxLabel = (maxBytes / MB).toFixed(0);
+  const sizeLabel = (sizeBytes / MB).toFixed(2);
+  throw new Error(`Media exceeds ${maxLabel}MB limit (got ${sizeLabel}MB)`);
+}
+
+function resolveLocalMediaPath(source: string): string {
+  if (!source.startsWith("file://")) return source;
+  try {
+    return fileURLToPath(source);
+  } catch {
+    throw new Error(`Invalid file:// URL: ${source}`);
+  }
+}
+
+function resolveFilenameFromSource(source?: string): string | undefined {
+  if (!source) return undefined;
+  if (source.startsWith("file://")) {
+    try {
+      return path.basename(fileURLToPath(source)) || undefined;
+    } catch {
+      return undefined;
+    }
+  }
+  if (HTTP_URL_RE.test(source)) {
+    try {
+      return path.basename(new URL(source).pathname) || undefined;
+    } catch {
+      return undefined;
+    }
+  }
+  const base = path.basename(source);
+  return base || undefined;
+}
+
+export async function sendBlueBubblesMedia(params: {
+  cfg: OpenClawConfig;
+  to: string;
+  mediaUrl?: string;
+  mediaPath?: string;
+  mediaBuffer?: Uint8Array;
+  contentType?: string;
+  filename?: string;
+  caption?: string;
+  replyToId?: string | null;
+  accountId?: string;
+  asVoice?: boolean;
+}) {
+  const {
+    cfg,
+    to,
+    mediaUrl,
+    mediaPath,
+    mediaBuffer,
+    contentType,
+    filename,
+    caption,
+    replyToId,
+    accountId,
+    asVoice,
+  } = params;
+  const core = getBlueBubblesRuntime();
+  const maxBytes = resolveChannelMediaMaxBytes({
+    cfg,
+    resolveChannelLimitMb: ({ cfg, accountId }) =>
+      cfg.channels?.bluebubbles?.accounts?.[accountId]?.mediaMaxMb ??
+      cfg.channels?.bluebubbles?.mediaMaxMb,
+    accountId,
+  });
+
+  let buffer: Uint8Array;
+  let resolvedContentType = contentType ?? undefined;
+  let resolvedFilename = filename ?? undefined;
+
+  if (mediaBuffer) {
+    assertMediaWithinLimit(mediaBuffer.byteLength, maxBytes);
+    buffer = mediaBuffer;
+    if (!resolvedContentType) {
+      const hint = mediaPath ?? mediaUrl;
+      const detected = await core.media.detectMime({
+        buffer: Buffer.isBuffer(mediaBuffer) ? mediaBuffer : Buffer.from(mediaBuffer),
+        filePath: hint,
+      });
+      resolvedContentType = detected ?? undefined;
+    }
+    if (!resolvedFilename) {
+      resolvedFilename = resolveFilenameFromSource(mediaPath ?? mediaUrl);
+    }
+  } else {
+    const source = mediaPath ?? mediaUrl;
+    if (!source) {
+      throw new Error("BlueBubbles media delivery requires mediaUrl, mediaPath, or mediaBuffer.");
+    }
+    if (HTTP_URL_RE.test(source)) {
+      const fetched = await core.channel.media.fetchRemoteMedia({
+        url: source,
+        maxBytes: typeof maxBytes === "number" && maxBytes > 0 ? maxBytes : undefined,
+      });
+      buffer = fetched.buffer;
+      resolvedContentType = resolvedContentType ?? fetched.contentType ?? undefined;
+      resolvedFilename = resolvedFilename ?? fetched.fileName;
+    } else {
+      const localPath = resolveLocalMediaPath(source);
+      const fs = await import("node:fs/promises");
+      if (typeof maxBytes === "number" && maxBytes > 0) {
+        const stats = await fs.stat(localPath);
+        assertMediaWithinLimit(stats.size, maxBytes);
+      }
+      const data = await fs.readFile(localPath);
+      assertMediaWithinLimit(data.byteLength, maxBytes);
+      buffer = new Uint8Array(data);
+      if (!resolvedContentType) {
+        const detected = await core.media.detectMime({
+          buffer: data,
+          filePath: localPath,
+        });
+        resolvedContentType = detected ?? undefined;
+      }
+      if (!resolvedFilename) {
+        resolvedFilename = resolveFilenameFromSource(localPath);
+      }
+    }
+  }
+
+  // Resolve short ID (e.g., "5") to full UUID
+  const replyToMessageGuid = replyToId?.trim()
+    ? resolveBlueBubblesMessageId(replyToId.trim(), { requireKnownShortId: true })
+    : undefined;
+
+  const attachmentResult = await sendBlueBubblesAttachment({
+    to,
+    buffer,
+    filename: resolvedFilename ?? "attachment",
+    contentType: resolvedContentType ?? undefined,
+    replyToMessageGuid,
+    asVoice,
+    opts: {
+      cfg,
+      accountId,
+    },
+  });
+
+  const trimmedCaption = caption?.trim();
+  if (trimmedCaption) {
+    await sendMessageBlueBubbles(to, trimmedCaption, {
+      cfg,
+      accountId,
+      replyToMessageGuid,
+    });
+  }
+
+  return attachmentResult;
+}