@openclaw/bluebubbles 2026.2.21 → 2026.2.22

package/src/chat.ts

@@ -26,6 +26,41 @@ function assertPrivateApiEnabled(accountId: string, feature: string): void {
   }
 }
 
+function resolvePartIndex(partIndex: number | undefined): number {
+  return typeof partIndex === "number" ? partIndex : 0;
+}
+
+async function sendPrivateApiJsonRequest(params: {
+  opts: BlueBubblesChatOpts;
+  feature: string;
+  action: string;
+  path: string;
+  method: "POST" | "PUT" | "DELETE";
+  payload?: unknown;
+}): Promise<void> {
+  const { baseUrl, password, accountId } = resolveAccount(params.opts);
+  assertPrivateApiEnabled(accountId, params.feature);
+  const url = buildBlueBubblesApiUrl({
+    baseUrl,
+    path: params.path,
+    password,
+  });
+
+  const request: RequestInit = { method: params.method };
+  if (params.payload !== undefined) {
+    request.headers = { "Content-Type": "application/json" };
+    request.body = JSON.stringify(params.payload);
+  }
+
+  const res = await blueBubblesFetchWithTimeout(url, request, params.opts.timeoutMs);
+  if (!res.ok) {
+    const errorText = await res.text().catch(() => "");
+    throw new Error(
+      `BlueBubbles ${params.action} failed (${res.status}): ${errorText || "unknown"}`,
+    );
+  }
+}
+
 export async function markBlueBubblesChatRead(
   chatGuid: string,
   opts: BlueBubblesChatOpts = {},
@@ -97,34 +132,18 @@ export async function editBlueBubblesMessage(
     throw new Error("BlueBubbles edit requires newText");
   }
 
-  const { baseUrl, password, accountId } = resolveAccount(opts);
-  assertPrivateApiEnabled(accountId, "edit");
-  const url = buildBlueBubblesApiUrl({
-    baseUrl,
+  await sendPrivateApiJsonRequest({
+    opts,
+    feature: "edit",
+    action: "edit",
+    method: "POST",
     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),
+    payload: {
+      editedMessage: trimmedText,
+      backwardsCompatibilityMessage: opts.backwardsCompatMessage ?? `Edited to: ${trimmedText}`,
+      partIndex: resolvePartIndex(opts.partIndex),
     },
-    opts.timeoutMs,
-  );
-
-  if (!res.ok) {
-    const errorText = await res.text().catch(() => "");
-    throw new Error(`BlueBubbles edit failed (${res.status}): ${errorText || "unknown"}`);
-  }
+  });
 }
 
 /**
@@ -140,32 +159,14 @@ export async function unsendBlueBubblesMessage(
     throw new Error("BlueBubbles unsend requires messageGuid");
   }
 
-  const { baseUrl, password, accountId } = resolveAccount(opts);
-  assertPrivateApiEnabled(accountId, "unsend");
-  const url = buildBlueBubblesApiUrl({
-    baseUrl,
+  await sendPrivateApiJsonRequest({
+    opts,
+    feature: "unsend",
+    action: "unsend",
+    method: "POST",
     path: `/api/v1/message/${encodeURIComponent(trimmedGuid)}/unsend`,
-    password,
+    payload: { partIndex: resolvePartIndex(opts.partIndex) },
   });
-
-  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"}`);
-  }
 }
 
 /**
@@ -181,28 +182,14 @@ export async function renameBlueBubblesChat(
     throw new Error("BlueBubbles rename requires chatGuid");
   }
 
-  const { baseUrl, password, accountId } = resolveAccount(opts);
-  assertPrivateApiEnabled(accountId, "renameGroup");
-  const url = buildBlueBubblesApiUrl({
-    baseUrl,
+  await sendPrivateApiJsonRequest({
+    opts,
+    feature: "renameGroup",
+    action: "rename",
+    method: "PUT",
     path: `/api/v1/chat/${encodeURIComponent(trimmedGuid)}`,
-    password,
+    payload: { displayName },
   });
-
-  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"}`);
-  }
 }
 
 /**
@@ -222,28 +209,14 @@ export async function addBlueBubblesParticipant(
     throw new Error("BlueBubbles addParticipant requires address");
   }
 
-  const { baseUrl, password, accountId } = resolveAccount(opts);
-  assertPrivateApiEnabled(accountId, "addParticipant");
-  const url = buildBlueBubblesApiUrl({
-    baseUrl,
+  await sendPrivateApiJsonRequest({
+    opts,
+    feature: "addParticipant",
+    action: "addParticipant",
+    method: "POST",
     path: `/api/v1/chat/${encodeURIComponent(trimmedGuid)}/participant`,
-    password,
+    payload: { address: trimmedAddress },
   });
-
-  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"}`);
-  }
 }
 
 /**
@@ -263,30 +236,14 @@ export async function removeBlueBubblesParticipant(
     throw new Error("BlueBubbles removeParticipant requires address");
   }
 
-  const { baseUrl, password, accountId } = resolveAccount(opts);
-  assertPrivateApiEnabled(accountId, "removeParticipant");
-  const url = buildBlueBubblesApiUrl({
-    baseUrl,
+  await sendPrivateApiJsonRequest({
+    opts,
+    feature: "removeParticipant",
+    action: "removeParticipant",
+    method: "DELETE",
     path: `/api/v1/chat/${encodeURIComponent(trimmedGuid)}/participant`,
-    password,
+    payload: { address: trimmedAddress },
   });
-
-  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"}`,
-    );
-  }
 }
 
 /**
@@ -301,20 +258,13 @@ export async function leaveBlueBubblesChat(
     throw new Error("BlueBubbles leaveChat requires chatGuid");
   }
 
-  const { baseUrl, password, accountId } = resolveAccount(opts);
-  assertPrivateApiEnabled(accountId, "leaveGroup");
-  const url = buildBlueBubblesApiUrl({
-    baseUrl,
+  await sendPrivateApiJsonRequest({
+    opts,
+    feature: "leaveGroup",
+    action: "leaveChat",
+    method: "POST",
     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"}`);
-  }
 }
 
 /**

package/src/history.ts

@@ -0,0 +1,177 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import { resolveBlueBubblesServerAccount } from "./account-resolve.js";
+import { blueBubblesFetchWithTimeout, buildBlueBubblesApiUrl } from "./types.js";
+
+export type BlueBubblesHistoryEntry = {
+  sender: string;
+  body: string;
+  timestamp?: number;
+  messageId?: string;
+};
+
+export type BlueBubblesHistoryFetchResult = {
+  entries: BlueBubblesHistoryEntry[];
+  /**
+   * True when at least one API path returned a recognized response shape.
+   * False means all attempts failed or returned unusable data.
+   */
+  resolved: boolean;
+};
+
+export type BlueBubblesMessageData = {
+  guid?: string;
+  text?: string;
+  handle_id?: string;
+  is_from_me?: boolean;
+  date_created?: number;
+  date_delivered?: number;
+  associated_message_guid?: string;
+  sender?: {
+    address?: string;
+    display_name?: string;
+  };
+};
+
+export type BlueBubblesChatOpts = {
+  serverUrl?: string;
+  password?: string;
+  accountId?: string;
+  timeoutMs?: number;
+  cfg?: OpenClawConfig;
+};
+
+function resolveAccount(params: BlueBubblesChatOpts) {
+  return resolveBlueBubblesServerAccount(params);
+}
+
+const MAX_HISTORY_FETCH_LIMIT = 100;
+const HISTORY_SCAN_MULTIPLIER = 8;
+const MAX_HISTORY_SCAN_MESSAGES = 500;
+const MAX_HISTORY_BODY_CHARS = 2_000;
+
+function clampHistoryLimit(limit: number): number {
+  if (!Number.isFinite(limit)) {
+    return 0;
+  }
+  const normalized = Math.floor(limit);
+  if (normalized <= 0) {
+    return 0;
+  }
+  return Math.min(normalized, MAX_HISTORY_FETCH_LIMIT);
+}
+
+function truncateHistoryBody(text: string): string {
+  if (text.length <= MAX_HISTORY_BODY_CHARS) {
+    return text;
+  }
+  return `${text.slice(0, MAX_HISTORY_BODY_CHARS).trimEnd()}...`;
+}
+
+/**
+ * Fetch message history from BlueBubbles API for a specific chat.
+ * This provides the initial backfill for both group chats and DMs.
+ */
+export async function fetchBlueBubblesHistory(
+  chatIdentifier: string,
+  limit: number,
+  opts: BlueBubblesChatOpts = {},
+): Promise<BlueBubblesHistoryFetchResult> {
+  const effectiveLimit = clampHistoryLimit(limit);
+  if (!chatIdentifier.trim() || effectiveLimit <= 0) {
+    return { entries: [], resolved: true };
+  }
+
+  let baseUrl: string;
+  let password: string;
+  try {
+    ({ baseUrl, password } = resolveAccount(opts));
+  } catch {
+    return { entries: [], resolved: false };
+  }
+
+  // Try different common API patterns for fetching messages
+  const possiblePaths = [
+    `/api/v1/chat/${encodeURIComponent(chatIdentifier)}/messages?limit=${effectiveLimit}&sort=DESC`,
+    `/api/v1/messages?chatGuid=${encodeURIComponent(chatIdentifier)}&limit=${effectiveLimit}`,
+    `/api/v1/chat/${encodeURIComponent(chatIdentifier)}/message?limit=${effectiveLimit}`,
+  ];
+
+  for (const path of possiblePaths) {
+    try {
+      const url = buildBlueBubblesApiUrl({ baseUrl, path, password });
+      const res = await blueBubblesFetchWithTimeout(
+        url,
+        { method: "GET" },
+        opts.timeoutMs ?? 10000,
+      );
+
+      if (!res.ok) {
+        continue; // Try next path
+      }
+
+      const data = await res.json().catch(() => null);
+      if (!data) {
+        continue;
+      }
+
+      // Handle different response structures
+      let messages: unknown[] = [];
+      if (Array.isArray(data)) {
+        messages = data;
+      } else if (data.data && Array.isArray(data.data)) {
+        messages = data.data;
+      } else if (data.messages && Array.isArray(data.messages)) {
+        messages = data.messages;
+      } else {
+        continue;
+      }
+
+      const historyEntries: BlueBubblesHistoryEntry[] = [];
+
+      const maxScannedMessages = Math.min(
+        Math.max(effectiveLimit * HISTORY_SCAN_MULTIPLIER, effectiveLimit),
+        MAX_HISTORY_SCAN_MESSAGES,
+      );
+      for (let i = 0; i < messages.length && i < maxScannedMessages; i++) {
+        const item = messages[i];
+        const msg = item as BlueBubblesMessageData;
+
+        // Skip messages without text content
+        const text = msg.text?.trim();
+        if (!text) {
+          continue;
+        }
+
+        const sender = msg.is_from_me
+          ? "me"
+          : msg.sender?.display_name || msg.sender?.address || msg.handle_id || "Unknown";
+        const timestamp = msg.date_created || msg.date_delivered;
+
+        historyEntries.push({
+          sender,
+          body: truncateHistoryBody(text),
+          timestamp,
+          messageId: msg.guid,
+        });
+      }
+
+      // Sort by timestamp (oldest first for context)
+      historyEntries.sort((a, b) => {
+        const aTime = a.timestamp || 0;
+        const bTime = b.timestamp || 0;
+        return aTime - bTime;
+      });
+
+      return {
+        entries: historyEntries.slice(0, effectiveLimit), // Ensure we don't exceed the requested limit
+        resolved: true,
+      };
+    } catch (error) {
+      // Continue to next path
+      continue;
+    }
+  }
+
+  // If none of the API paths worked, return empty history
+  return { entries: [], resolved: false };
+}

package/src/monitor-normalize.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it } from "vitest";
+import { normalizeWebhookMessage, normalizeWebhookReaction } from "./monitor-normalize.js";
+
+describe("normalizeWebhookMessage", () => {
+  it("falls back to DM chatGuid handle when sender handle is missing", () => {
+    const result = normalizeWebhookMessage({
+      type: "new-message",
+      data: {
+        guid: "msg-1",
+        text: "hello",
+        isGroup: false,
+        isFromMe: false,
+        handle: null,
+        chatGuid: "iMessage;-;+15551234567",
+      },
+    });
+
+    expect(result).not.toBeNull();
+    expect(result?.senderId).toBe("+15551234567");
+    expect(result?.chatGuid).toBe("iMessage;-;+15551234567");
+  });
+
+  it("does not infer sender from group chatGuid when sender handle is missing", () => {
+    const result = normalizeWebhookMessage({
+      type: "new-message",
+      data: {
+        guid: "msg-1",
+        text: "hello group",
+        isGroup: true,
+        isFromMe: false,
+        handle: null,
+        chatGuid: "iMessage;+;chat123456",
+      },
+    });
+
+    expect(result).toBeNull();
+  });
+
+  it("accepts array-wrapped payload data", () => {
+    const result = normalizeWebhookMessage({
+      type: "new-message",
+      data: [
+        {
+          guid: "msg-1",
+          text: "hello",
+          handle: { address: "+15551234567" },
+          isGroup: false,
+          isFromMe: false,
+        },
+      ],
+    });
+
+    expect(result).not.toBeNull();
+    expect(result?.senderId).toBe("+15551234567");
+  });
+});
+
+describe("normalizeWebhookReaction", () => {
+  it("falls back to DM chatGuid handle when reaction sender handle is missing", () => {
+    const result = normalizeWebhookReaction({
+      type: "updated-message",
+      data: {
+        guid: "msg-2",
+        associatedMessageGuid: "p:0/msg-1",
+        associatedMessageType: 2000,
+        isGroup: false,
+        isFromMe: false,
+        handle: null,
+        chatGuid: "iMessage;-;+15551234567",
+      },
+    });
+
+    expect(result).not.toBeNull();
+    expect(result?.senderId).toBe("+15551234567");
+    expect(result?.messageId).toBe("p:0/msg-1");
+    expect(result?.action).toBe("added");
+  });
+});

package/src/monitor-normalize.ts

@@ -1,4 +1,4 @@
-import { normalizeBlueBubblesHandle } from "./targets.js";
+import { extractHandleFromChatGuid, normalizeBlueBubblesHandle } from "./targets.js";
 import type { BlueBubblesAttachment } from "./types.js";
 
 function asRecord(value: unknown): Record<string, unknown> | null {
@@ -629,18 +629,42 @@ export function parseTapbackText(params: {
 }
 
 function extractMessagePayload(payload: Record<string, unknown>): Record<string, unknown> | null {
+  const parseRecord = (value: unknown): Record<string, unknown> | null => {
+    const record = asRecord(value);
+    if (record) {
+      return record;
+    }
+    if (Array.isArray(value)) {
+      for (const entry of value) {
+        const parsedEntry = parseRecord(entry);
+        if (parsedEntry) {
+          return parsedEntry;
+        }
+      }
+      return null;
+    }
+    if (typeof value !== "string") {
+      return null;
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+      return null;
+    }
+    try {
+      return parseRecord(JSON.parse(trimmed));
+    } catch {
+      return null;
+    }
+  };
+
   const dataRaw = payload.data ?? payload.payload ?? payload.event;
-  const data =
-    asRecord(dataRaw) ??
-    (typeof dataRaw === "string" ? (asRecord(JSON.parse(dataRaw)) ?? null) : null);
+  const data = parseRecord(dataRaw);
   const messageRaw = payload.message ?? data?.message ?? data;
-  const message =
-    asRecord(messageRaw) ??
-    (typeof messageRaw === "string" ? (asRecord(JSON.parse(messageRaw)) ?? null) : null);
-  if (!message) {
-    return null;
+  const message = parseRecord(messageRaw);
+  if (message) {
+    return message;
   }
-  return message;
+  return null;
 }
 
 export function normalizeWebhookMessage(
@@ -700,7 +724,10 @@ export function normalizeWebhookMessage(
         : timestampRaw * 1000
       : undefined;
 
-  const normalizedSender = normalizeBlueBubblesHandle(senderId);
+  // BlueBubbles may omit `handle` in webhook payloads; for DM chat GUIDs we can still infer sender.
+  const senderFallbackFromChatGuid =
+    !senderId && !isGroup && chatGuid ? extractHandleFromChatGuid(chatGuid) : null;
+  const normalizedSender = normalizeBlueBubblesHandle(senderId || senderFallbackFromChatGuid || "");
   if (!normalizedSender) {
     return null;
   }
@@ -774,7 +801,9 @@ export function normalizeWebhookReaction(
         : timestampRaw * 1000
       : undefined;
 
-  const normalizedSender = normalizeBlueBubblesHandle(senderId);
+  const senderFallbackFromChatGuid =
+    !senderId && !isGroup && chatGuid ? extractHandleFromChatGuid(chatGuid) : null;
+  const normalizedSender = normalizeBlueBubblesHandle(senderId || senderFallbackFromChatGuid || "");
   if (!normalizedSender) {
     return null;
   }