feat: update BlueBubbles documentation and code to clarify group icon handling and normalize chat identifiers

extensions/bluebubbles/src/probe.ts

@@ -6,6 +6,68 @@ export type BlueBubblesProbe = {
   error?: string | null;
 };
 
+export type BlueBubblesServerInfo = {
+  os_version?: string;
+  server_version?: string;
+  private_api?: boolean;
+  helper_connected?: boolean;
+  proxy_service?: string;
+  detected_icloud?: string;
+  computer_id?: string;
+};
+
+/** Cache server info to avoid repeated API calls */
+const serverInfoCache = new Map<string, { info: BlueBubblesServerInfo; expires: number }>();
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+/**
+ * Fetch server info from BlueBubbles API.
+ * Returns cached result if available and not expired.
+ */
+export async function fetchBlueBubblesServerInfo(params: {
+  baseUrl?: string | null;
+  password?: string | null;
+  timeoutMs?: number;
+}): Promise<BlueBubblesServerInfo | null> {
+  const baseUrl = params.baseUrl?.trim();
+  const password = params.password?.trim();
+  if (!baseUrl || !password) return null;
+
+  const cacheKey = `${baseUrl}:${password}`;
+  const cached = serverInfoCache.get(cacheKey);
+  if (cached && cached.expires > Date.now()) {
+    return cached.info;
+  }
+
+  const url = buildBlueBubblesApiUrl({ baseUrl, path: "/api/v1/server/info", password });
+  try {
+    const res = await blueBubblesFetchWithTimeout(url, { method: "GET" }, params.timeoutMs ?? 5000);
+    if (!res.ok) return null;
+    const payload = (await res.json().catch(() => null)) as Record<string, unknown> | null;
+    const data = payload?.data as BlueBubblesServerInfo | undefined;
+    if (data) {
+      serverInfoCache.set(cacheKey, { info: data, expires: Date.now() + CACHE_TTL_MS });
+    }
+    return data ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Parse macOS version string (e.g., "15.0.1" or "26.0") into major version number.
+ */
+export function parseMacOSMajorVersion(version?: string | null): number | null {
+  if (!version) return null;
+  const match = /^(\d+)/.exec(version.trim());
+  return match ? Number.parseInt(match[1], 10) : null;
+}
+
+/** Clear the server info cache (for testing) */
+export function clearServerInfoCache(): void {
+  serverInfoCache.clear();
+}
+
 export async function probeBlueBubbles(params: {
   baseUrl?: string | null;
   password?: string | null;

extensions/bluebubbles/src/targets.test.ts

@@ -50,12 +50,12 @@ describe("normalizeBlueBubblesMessagingTarget", () => {
     expect(normalizeBlueBubblesMessagingTarget("iMessage;-;+19257864429")).toBe("+19257864429");
   });
 
-  it("normalizes chat<digits> pattern to chat_id format", () => {
+  it("normalizes chat<digits> pattern to chat_identifier format", () => {
     expect(normalizeBlueBubblesMessagingTarget("chat660250192681427962")).toBe(
-      "chat_id:660250192681427962",
+      "chat_identifier:chat660250192681427962",
     );
-    expect(normalizeBlueBubblesMessagingTarget("chat123")).toBe("chat_id:123");
-    expect(normalizeBlueBubblesMessagingTarget("Chat456789")).toBe("chat_id:456789");
+    expect(normalizeBlueBubblesMessagingTarget("chat123")).toBe("chat_identifier:chat123");
+    expect(normalizeBlueBubblesMessagingTarget("Chat456789")).toBe("chat_identifier:Chat456789");
   });
 });
 
@@ -88,13 +88,19 @@ describe("looksLikeBlueBubblesTargetId", () => {
 });
 
 describe("parseBlueBubblesTarget", () => {
-  it("parses chat<digits> pattern as chat_id", () => {
+  it("parses chat<digits> pattern as chat_identifier", () => {
     expect(parseBlueBubblesTarget("chat660250192681427962")).toEqual({
-      kind: "chat_id",
-      chatId: 660250192681427962,
+      kind: "chat_identifier",
+      chatIdentifier: "chat660250192681427962",
+    });
+    expect(parseBlueBubblesTarget("chat123")).toEqual({
+      kind: "chat_identifier",
+      chatIdentifier: "chat123",
+    });
+    expect(parseBlueBubblesTarget("Chat456789")).toEqual({
+      kind: "chat_identifier",
+      chatIdentifier: "Chat456789",
     });
-    expect(parseBlueBubblesTarget("chat123")).toEqual({ kind: "chat_id", chatId: 123 });
-    expect(parseBlueBubblesTarget("Chat456789")).toEqual({ kind: "chat_id", chatId: 456789 });
   });
 
   it("parses explicit chat_id: prefix", () => {
@@ -118,12 +124,15 @@ describe("parseBlueBubblesTarget", () => {
 });
 
 describe("parseBlueBubblesAllowTarget", () => {
-  it("parses chat<digits> pattern as chat_id", () => {
+  it("parses chat<digits> pattern as chat_identifier", () => {
     expect(parseBlueBubblesAllowTarget("chat660250192681427962")).toEqual({
-      kind: "chat_id",
-      chatId: 660250192681427962,
+      kind: "chat_identifier",
+      chatIdentifier: "chat660250192681427962",
+    });
+    expect(parseBlueBubblesAllowTarget("chat123")).toEqual({
+      kind: "chat_identifier",
+      chatIdentifier: "chat123",
     });
-    expect(parseBlueBubblesAllowTarget("chat123")).toEqual({ kind: "chat_id", chatId: 123 });
   });
 
   it("parses explicit chat_id: prefix", () => {

extensions/bluebubbles/src/targets.ts

@@ -245,11 +245,10 @@ export function parseBlueBubblesAllowTarget(raw: string): BlueBubblesAllowTarget
     if (value) return { kind: "chat_guid", chatGuid: value };
   }
 
-  // Handle chat<digits> pattern (e.g., "chat660250192681427962") as chat_id
-  const chatDigitsMatch = /^chat(\d+)$/i.exec(trimmed);
-  if (chatDigitsMatch) {
-    const chatId = Number.parseInt(chatDigitsMatch[1], 10);
-    if (Number.isFinite(chatId)) return { kind: "chat_id", chatId };
+  // Handle chat<digits> pattern (e.g., "chat660250192681427962") as chat_identifier
+  // These are BlueBubbles chat identifiers (the third part of a chat GUID), not numeric IDs
+  if (/^chat\d+$/i.test(trimmed)) {
+    return { kind: "chat_identifier", chatIdentifier: trimmed };
   }
 
   return { kind: "handle", handle: normalizeBlueBubblesHandle(trimmed) };