@spinabot/brigade 1.7.0 → 1.9.0

package/dist/agents/channels/bluebubbles/contact-names.js

@@ -0,0 +1,188 @@
+/**
+ * BlueBubbles contact-name resolution.
+ *
+ * An inbound BlueBubbles message carries the sender as a raw handle — a phone
+ * number (`+15551234567`) or an email. For the agent's context it reads far
+ * better as a human display name ("Alex Rivera"). The BlueBubbles server exposes
+ * the host Mac's Contacts via `GET /api/v1/contact`, so this module asks the
+ * server for the address book ONCE per account, indexes it by a normalised phone
+ * key + lowercased email, and resolves a sender address → display name from that
+ * cache.
+ *
+ * The directory is cached per account in a small LRU with a TTL (like Discord's
+ * directory cache): the first inbound for an account warms it, subsequent
+ * inbound hits the in-memory index. A NEGATIVE result (no match) is cached for a
+ * shorter TTL so an unknown number isn't re-queried on every message. `fetch` is
+ * INJECTABLE (the test seam) so the whole path runs with no live server.
+ */
+import { blueBubblesFetchWithTimeout, buildBlueBubblesApiUrl } from "./types.js";
+/** How long a fetched directory index stays warm before a re-fetch (1h). */
+const DIRECTORY_TTL_MS = 60 * 60 * 1000;
+/** How long a per-address negative (no-match) result is cached (5m). */
+const NEGATIVE_TTL_MS = 5 * 60 * 1000;
+/** Cap on the number of accounts whose directory we keep indexed at once. */
+const MAX_ACCOUNT_DIRECTORIES = 16;
+/** Module-level per-account directory cache (LRU by insertion order). */
+const directoryCache = new Map();
+/**
+ * Normalise a phone-ish string to a comparison key: digits only, dropping a
+ * leading US country code so `+1 (555) 123-4567` and `5551234567` collide.
+ * Returns null for a too-short / non-numeric value (e.g. an email).
+ */
+export function normalizePhoneKey(value) {
+    const digits = (value ?? "").replace(/\D/g, "");
+    if (!digits)
+        return null;
+    const trimmed = digits.length === 11 && digits.startsWith("1") ? digits.slice(1) : digits;
+    return trimmed.length >= 7 ? trimmed : null;
+}
+/** Build the lookup key for a sender address (email lowercased, phone digit-normalised). */
+export function contactLookupKey(address) {
+    const trimmed = (address ?? "").trim();
+    if (!trimmed)
+        return null;
+    if (trimmed.includes("@"))
+        return trimmed.toLowerCase();
+    return normalizePhoneKey(trimmed);
+}
+/** Pull a display name out of a contact record (display → first+last → nickname). */
+function contactDisplayName(c) {
+    const display = (c.displayName ?? "").trim();
+    if (display)
+        return display;
+    const first = (c.firstName ?? "").trim();
+    const last = (c.lastName ?? "").trim();
+    const full = `${first} ${last}`.trim();
+    if (full)
+        return full;
+    const nick = (c.nickname ?? "").trim();
+    return nick || undefined;
+}
+/** Read an address out of a `{ address }` object OR a bare string entry. */
+function readAddressEntry(entry) {
+    if (typeof entry === "string")
+        return entry.trim() || undefined;
+    const addr = (entry?.address ?? "").trim();
+    return addr || undefined;
+}
+/** Build the phone/email → name index from the raw contact list. */
+export function buildContactIndex(contacts) {
+    const byKey = new Map();
+    for (const c of contacts) {
+        if (!c || typeof c !== "object")
+            continue;
+        const name = contactDisplayName(c);
+        if (!name)
+            continue;
+        for (const phone of c.phoneNumbers ?? []) {
+            const addr = readAddressEntry(phone);
+            const key = addr ? normalizePhoneKey(addr) : null;
+            if (key && !byKey.has(key))
+                byKey.set(key, name);
+        }
+        for (const email of c.emails ?? []) {
+            const addr = readAddressEntry(email);
+            const key = addr ? addr.toLowerCase() : null;
+            if (key && !byKey.has(key))
+                byKey.set(key, name);
+        }
+    }
+    return byKey;
+}
+/** Touch an account directory to the MRU position (LRU bookkeeping). */
+function touch(accountId, dir) {
+    directoryCache.delete(accountId);
+    directoryCache.set(accountId, dir);
+    while (directoryCache.size > MAX_ACCOUNT_DIRECTORIES) {
+        const oldest = directoryCache.keys().next().value;
+        if (oldest === undefined)
+            break;
+        directoryCache.delete(oldest);
+    }
+}
+/** Fetch + index the account's contact directory from the server. Never throws. */
+async function fetchDirectory(args, now) {
+    let contacts = [];
+    try {
+        const url = buildBlueBubblesApiUrl({ serverUrl: args.serverUrl, path: "contact", password: args.password });
+        const res = await blueBubblesFetchWithTimeout(url, { method: "GET" }, { ...(args.timeoutMs !== undefined ? { timeoutMs: args.timeoutMs } : {}), ...(args.fetchImpl ? { fetchImpl: args.fetchImpl } : {}), ...(args.allowPrivateNetwork === false ? { allowPrivateNetwork: false } : {}) });
+        if (res.ok) {
+            const text = await res.text();
+            const body = text ? JSON.parse(text) : {};
+            const data = body.data;
+            if (Array.isArray(data))
+                contacts = data;
+        }
+    }
+    catch {
+        contacts = [];
+    }
+    const dir = {
+        byKey: buildContactIndex(contacts),
+        negative: new Map(),
+        expiresAt: now + DIRECTORY_TTL_MS,
+    };
+    return dir;
+}
+/**
+ * Resolve an inbound sender address → a human display name, or `undefined` when
+ * unknown. Warms (and caches) the account's contact directory on first use;
+ * subsequent calls hit the in-memory index. Negative results are cached briefly
+ * so an unknown number isn't re-queried every message. NEVER throws — a transport
+ * failure just yields `undefined` (the message still flows with the raw handle).
+ */
+export async function resolveBlueBubblesContactName(address, args, now = Date.now()) {
+    const key = contactLookupKey(address);
+    if (!key)
+        return undefined;
+    let dir = directoryCache.get(args.accountId);
+    if (!dir || dir.expiresAt <= now) {
+        dir = await fetchDirectory(args, now);
+        touch(args.accountId, dir);
+    }
+    else {
+        touch(args.accountId, dir);
+    }
+    const hit = dir.byKey.get(key);
+    if (hit)
+        return hit;
+    // Negative cache: don't re-query the directory mid-TTL for a known miss.
+    const negExpiry = dir.negative.get(key);
+    if (negExpiry && negExpiry > now)
+        return undefined;
+    dir.negative.set(key, now + NEGATIVE_TTL_MS);
+    return undefined;
+}
+/**
+ * SYNCHRONOUS cache-only peek: resolve an address from an ALREADY-WARM account
+ * directory, or `undefined` when the directory isn't cached yet / it's a miss.
+ * Never fetches — use this on the hot inbound path so dispatch stays synchronous;
+ * pair it with `warmBlueBubblesContactDirectory` to populate the cache in the
+ * background.
+ */
+export function peekBlueBubblesContactName(address, accountId, now = Date.now()) {
+    const key = contactLookupKey(address);
+    if (!key)
+        return undefined;
+    const dir = directoryCache.get(accountId);
+    if (!dir || dir.expiresAt <= now)
+        return undefined;
+    return dir.byKey.get(key);
+}
+/**
+ * Warm the account's contact directory cache in the background (best-effort).
+ * Fetches + indexes ONLY when the cache is cold/expired; a warm cache is a
+ * no-op. Never throws. Returns a promise the caller can ignore.
+ */
+export async function warmBlueBubblesContactDirectory(args, now = Date.now()) {
+    const existing = directoryCache.get(args.accountId);
+    if (existing && existing.expiresAt > now)
+        return;
+    const dir = await fetchDirectory(args, now);
+    touch(args.accountId, dir);
+}
+/** Drop every cached account directory (test isolation + reload teardown). */
+export function clearBlueBubblesContactCache() {
+    directoryCache.clear();
+}
+//# sourceMappingURL=contact-names.js.map

package/dist/agents/channels/bluebubbles/contact-names.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contact-names.js","sourceRoot":"","sources":["../../../../src/agents/channels/bluebubbles/contact-names.ts"],"names":[],"mappings":"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"}

package/dist/agents/channels/bluebubbles/debounce.d.ts

@@ -0,0 +1,78 @@
+/**
+ * BlueBubbles inbound debounce / balloon-coalescing.
+ *
+ * BlueBubbles fires SEPARATE `new-message` webhook events for things that are
+ * really ONE logical message:
+ *
+ *   - a URL text + its link-preview "balloon" (the balloon carries an
+ *     `associatedMessageGuid` pointing back at the text + a `balloonBundleId`);
+ *   - a text and its attachment that the server splits across two webhooks
+ *     (same `messageGuid`, one with text, one with the now-indexed media);
+ *   - rapid-fire bubbles a sender taps out back-to-back.
+ *
+ * Dispatching each as its own turn produces TWO agent replies for one user
+ * action. This module collects messages that share a coalescing key inside a
+ * short window (default 500 ms) and MERGES them into one (`combineDebounceEntries`):
+ * the texts join (de-duped), the attachments concatenate, the latest timestamp
+ * wins, and reply context is preserved. The merged message is then dispatched
+ * once.
+ *
+ * Self-contained + channel-local: it owns its own timer map (no central
+ * dependency). The connection wires it in ONLY when `inboundDebounceMs > 0`; the
+ * default (0) keeps the historical synchronous dispatch path so nothing changes
+ * for installs that don't opt in.
+ */
+import type { BlueBubblesInboundMessage } from "./connection.js";
+/** Default debounce window (ms) when coalescing is enabled but no value is given. */
+export declare const BLUEBUBBLES_DEFAULT_INBOUND_DEBOUNCE_MS = 500;
+/** Hard ceiling on the debounce window (defends against a misconfigured huge value). */
+export declare const BLUEBUBBLES_MAX_INBOUND_DEBOUNCE_MS = 10000;
+/** One buffered inbound awaiting a possible merge. */
+interface DebounceEntry {
+    message: BlueBubblesInboundMessage;
+}
+/**
+ * Merge multiple buffered inbound messages into ONE. The first entry is the
+ * base (typically the originating text); texts from the rest are appended unless
+ * a case-insensitive duplicate (a URL echoed in both the text and its balloon),
+ * attachments concatenate, the latest timestamp wins, and the first reply target
+ * is preserved. The deferred-media thunks are chained so the merged message
+ * resolves ALL of them.
+ */
+export declare function combineDebounceEntries(entries: DebounceEntry[]): BlueBubblesInboundMessage;
+/**
+ * The coalescing key for an inbound message. A balloon (URL preview / sticker)
+ * uses a different `messageGuid` than its parent text but carries the parent's
+ * `associatedMessageGuid` — key on THAT so text + balloon collapse. Otherwise key
+ * on the stable `messageGuid` (a text + its late-indexed attachment share it).
+ * Falls back to chat + sender so two bare bubbles in the same chat still merge.
+ */
+export declare function resolveDebounceKey(accountId: string, msg: BlueBubblesInboundMessage): string;
+/** A debouncer: enqueue an inbound + a way to tear all pending timers down. */
+export interface BlueBubblesInboundDebouncer {
+    /** Buffer an inbound; it (and any that share its key) flush after the window. */
+    enqueue(msg: BlueBubblesInboundMessage): void;
+    /** Flush everything immediately (e.g. on close). */
+    flushAll(): void;
+    /** Clear all pending timers without flushing (teardown). */
+    clear(): void;
+}
+export interface CreateInboundDebouncerArgs {
+    accountId: string;
+    /** Debounce window (ms). Clamped to `(0, MAX]`. */
+    debounceMs: number;
+    /** Called with the (possibly merged) message once a key's window elapses. */
+    dispatch: (msg: BlueBubblesInboundMessage) => void;
+    /** Optional verbose logger. */
+    log?: (msg: string) => void;
+}
+/** Clamp a requested debounce window into `[1, MAX]` ms. */
+export declare function clampInboundDebounceMs(raw: number | undefined): number;
+/**
+ * Build a per-conversation inbound debouncer. Each coalescing key gets its own
+ * buffer + timer; when the timer fires the buffered entries are merged (or passed
+ * through when there's only one) and handed to `dispatch`.
+ */
+export declare function createBlueBubblesInboundDebouncer(args: CreateInboundDebouncerArgs): BlueBubblesInboundDebouncer;
+export {};
+//# sourceMappingURL=debounce.d.ts.map

package/dist/agents/channels/bluebubbles/debounce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debounce.d.ts","sourceRoot":"","sources":["../../../../src/agents/channels/bluebubbles/debounce.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAEjE,qFAAqF;AACrF,eAAO,MAAM,uCAAuC,MAAM,CAAC;AAC3D,wFAAwF;AACxF,eAAO,MAAM,mCAAmC,QAAS,CAAC;AAE1D,sDAAsD;AACtD,UAAU,aAAa;IACtB,OAAO,EAAE,yBAAyB,CAAC;CACnC;AAQD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,yBAAyB,CAmD1F;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,yBAAyB,GAAG,MAAM,CAS5F;AAED,+EAA+E;AAC/E,MAAM,WAAW,2BAA2B;IAC3C,iFAAiF;IACjF,OAAO,CAAC,GAAG,EAAE,yBAAyB,GAAG,IAAI,CAAC;IAC9C,oDAAoD;IACpD,QAAQ,IAAI,IAAI,CAAC;IACjB,4DAA4D;IAC5D,KAAK,IAAI,IAAI,CAAC;CACd;AAED,MAAM,WAAW,0BAA0B;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,QAAQ,EAAE,CAAC,GAAG,EAAE,yBAAyB,KAAK,IAAI,CAAC;IACnD,+BAA+B;IAC/B,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5B;AAED,4DAA4D;AAC5D,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAItE;AAED;;;;GAIG;AACH,wBAAgB,iCAAiC,CAAC,IAAI,EAAE,0BAA0B,GAAG,2BAA2B,CAoD/G"}

package/dist/agents/channels/bluebubbles/debounce.js

@@ -0,0 +1,173 @@
+/**
+ * BlueBubbles inbound debounce / balloon-coalescing.
+ *
+ * BlueBubbles fires SEPARATE `new-message` webhook events for things that are
+ * really ONE logical message:
+ *
+ *   - a URL text + its link-preview "balloon" (the balloon carries an
+ *     `associatedMessageGuid` pointing back at the text + a `balloonBundleId`);
+ *   - a text and its attachment that the server splits across two webhooks
+ *     (same `messageGuid`, one with text, one with the now-indexed media);
+ *   - rapid-fire bubbles a sender taps out back-to-back.
+ *
+ * Dispatching each as its own turn produces TWO agent replies for one user
+ * action. This module collects messages that share a coalescing key inside a
+ * short window (default 500 ms) and MERGES them into one (`combineDebounceEntries`):
+ * the texts join (de-duped), the attachments concatenate, the latest timestamp
+ * wins, and reply context is preserved. The merged message is then dispatched
+ * once.
+ *
+ * Self-contained + channel-local: it owns its own timer map (no central
+ * dependency). The connection wires it in ONLY when `inboundDebounceMs > 0`; the
+ * default (0) keeps the historical synchronous dispatch path so nothing changes
+ * for installs that don't opt in.
+ */
+/** Default debounce window (ms) when coalescing is enabled but no value is given. */
+export const BLUEBUBBLES_DEFAULT_INBOUND_DEBOUNCE_MS = 500;
+/** Hard ceiling on the debounce window (defends against a misconfigured huge value). */
+export const BLUEBUBBLES_MAX_INBOUND_DEBOUNCE_MS = 10_000;
+/**
+ * Merge multiple buffered inbound messages into ONE. The first entry is the
+ * base (typically the originating text); texts from the rest are appended unless
+ * a case-insensitive duplicate (a URL echoed in both the text and its balloon),
+ * attachments concatenate, the latest timestamp wins, and the first reply target
+ * is preserved. The deferred-media thunks are chained so the merged message
+ * resolves ALL of them.
+ */
+export function combineDebounceEntries(entries) {
+    if (entries.length === 0)
+        throw new Error("cannot combine zero debounce entries");
+    const first = entries[0].message;
+    if (entries.length === 1)
+        return first;
+    // Join texts, skipping empties + case-insensitive duplicates.
+    const seen = new Set();
+    const parts = [];
+    for (const { message } of entries) {
+        const text = (typeof message.text === "string" ? message.text : "").trim();
+        if (!text)
+            continue;
+        const norm = text.toLowerCase();
+        if (seen.has(norm))
+            continue;
+        seen.add(norm);
+        parts.push(text);
+    }
+    // Concatenate raw attachment descriptors across all entries.
+    const attachments = entries.flatMap((e) => e.message.attachments ?? []);
+    // Latest timestamp wins.
+    const stamps = entries
+        .map((e) => e.message.timestampMs)
+        .filter((t) => typeof t === "number");
+    const latest = stamps.length > 0 ? Math.max(...stamps) : first.timestampMs;
+    // Chain every deferred-media thunk so the merged message resolves them all.
+    const thunks = entries.map((e) => e.message.resolveMedia).filter((r) => !!r);
+    const resolveMedia = thunks.length > 0
+        ? async () => {
+            const all = await Promise.all(thunks.map((t) => t().catch(() => [])));
+            return all.flat();
+        }
+        : first.resolveMedia;
+    // Prefer a reply target from any entry that carries one.
+    const withReply = entries.find((e) => e.message.replyToGuid)?.message;
+    const merged = {
+        ...first,
+        text: parts.join(" "),
+        attachments,
+        ...(latest !== undefined ? { timestampMs: latest } : {}),
+        ...(withReply?.replyToGuid ? { replyToGuid: withReply.replyToGuid } : {}),
+        // The merged message is no longer "just a balloon".
+        ...(resolveMedia ? { resolveMedia } : {}),
+    };
+    // Drop the balloon-only markers now that we've coalesced.
+    delete merged.balloonBundleId;
+    return merged;
+}
+/**
+ * The coalescing key for an inbound message. A balloon (URL preview / sticker)
+ * uses a different `messageGuid` than its parent text but carries the parent's
+ * `associatedMessageGuid` — key on THAT so text + balloon collapse. Otherwise key
+ * on the stable `messageGuid` (a text + its late-indexed attachment share it).
+ * Falls back to chat + sender so two bare bubbles in the same chat still merge.
+ */
+export function resolveDebounceKey(accountId, msg) {
+    // A balloon keys on its PARENT's guid so it collides with the parent text
+    // (which keys on its OWN messageGuid) — same `msg:` namespace either way.
+    const assoc = msg.associatedMessageGuid?.trim();
+    if (msg.balloonBundleId?.trim() && assoc)
+        return `${accountId}:msg:${assoc}`;
+    const guid = msg.messageGuid?.trim();
+    if (guid)
+        return `${accountId}:msg:${guid}`;
+    const chat = msg.chatGuid?.trim() || "chat";
+    return `${accountId}:${chat}:${msg.from}`;
+}
+/** Clamp a requested debounce window into `[1, MAX]` ms. */
+export function clampInboundDebounceMs(raw) {
+    const n = typeof raw === "number" && Number.isFinite(raw) ? Math.floor(raw) : 0;
+    if (n <= 0)
+        return 0;
+    return Math.min(n, BLUEBUBBLES_MAX_INBOUND_DEBOUNCE_MS);
+}
+/**
+ * Build a per-conversation inbound debouncer. Each coalescing key gets its own
+ * buffer + timer; when the timer fires the buffered entries are merged (or passed
+ * through when there's only one) and handed to `dispatch`.
+ */
+export function createBlueBubblesInboundDebouncer(args) {
+    const windowMs = clampInboundDebounceMs(args.debounceMs);
+    const slots = new Map();
+    const flush = (key) => {
+        const slot = slots.get(key);
+        if (!slot)
+            return;
+        slots.delete(key);
+        clearTimeout(slot.timer);
+        if (slot.entries.length === 0)
+            return;
+        try {
+            const out = slot.entries.length === 1 ? slot.entries[0].message : combineDebounceEntries(slot.entries);
+            if (slot.entries.length > 1) {
+                args.log?.(`coalesced ${slot.entries.length} messages into one turn`);
+            }
+            args.dispatch(out);
+        }
+        catch (err) {
+            args.log?.(`debounce flush failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    return {
+        enqueue(msg) {
+            // Window disabled → straight through (defensive; callers gate on > 0).
+            if (windowMs <= 0) {
+                args.dispatch(msg);
+                return;
+            }
+            const key = resolveDebounceKey(args.accountId, msg);
+            const existing = slots.get(key);
+            if (existing) {
+                existing.entries.push({ message: msg });
+                clearTimeout(existing.timer);
+                existing.timer = arm(key);
+                return;
+            }
+            slots.set(key, { entries: [{ message: msg }], timer: arm(key) });
+        },
+        flushAll() {
+            for (const key of [...slots.keys()])
+                flush(key);
+        },
+        clear() {
+            for (const slot of slots.values())
+                clearTimeout(slot.timer);
+            slots.clear();
+        },
+    };
+    function arm(key) {
+        const t = setTimeout(() => flush(key), windowMs);
+        if (typeof t.unref === "function")
+            t.unref();
+        return t;
+    }
+}
+//# sourceMappingURL=debounce.js.map

package/dist/agents/channels/bluebubbles/debounce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debounce.js","sourceRoot":"","sources":["../../../../src/agents/channels/bluebubbles/debounce.ts"],"names":[],"mappings":"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"}

package/dist/agents/channels/bluebubbles/dedupe.d.ts

@@ -0,0 +1,25 @@
+/**
+ * BlueBubbles inbound dedupe key.
+ *
+ * BlueBubbles has no inbound ack/sequence and its message poller can REPLAY a
+ * lookback window of `new-message` events after a server restart, so the same
+ * message GUID can arrive twice. The connection layer claims each inbound through
+ * the shared `createDedupeCache` (claim-once, LRU + TTL); this module just
+ * computes the dedupe KEY.
+ *
+ * The key is the message GUID, namespaced per account. An `updated-message`
+ * (attachment-indexing follow-up) gets a distinct `:updated` suffix so the text
+ * pass and the attachment follow-up aren't collapsed into one (the follow-up
+ * must be allowed through to attach the now-indexed media).
+ */
+/** The default dedupe cache TTL — generous (BlueBubbles replays up to ~1 week). */
+export declare const BLUEBUBBLES_DEDUPE_TTL_MS: number;
+/** The default dedupe cache size cap. */
+export declare const BLUEBUBBLES_DEDUPE_MAX_ENTRIES = 5000;
+/**
+ * Resolve the dedupe key for a webhook payload (or undefined when the payload has
+ * no usable message GUID — those are handled by the normalize skip path anyway).
+ * `accountId` namespaces the key so two accounts never collide.
+ */
+export declare function resolveBlueBubblesDedupeKey(accountId: string, payload: unknown, eventType?: string): string | undefined;
+//# sourceMappingURL=dedupe.d.ts.map

package/dist/agents/channels/bluebubbles/dedupe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedupe.d.ts","sourceRoot":"","sources":["../../../../src/agents/channels/bluebubbles/dedupe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,mFAAmF;AACnF,eAAO,MAAM,yBAAyB,QAA0B,CAAC;AACjE,yCAAyC;AACzC,eAAO,MAAM,8BAA8B,OAAO,CAAC;AAEnD;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAOvH"}

package/dist/agents/channels/bluebubbles/dedupe.js

@@ -0,0 +1,35 @@
+/**
+ * BlueBubbles inbound dedupe key.
+ *
+ * BlueBubbles has no inbound ack/sequence and its message poller can REPLAY a
+ * lookback window of `new-message` events after a server restart, so the same
+ * message GUID can arrive twice. The connection layer claims each inbound through
+ * the shared `createDedupeCache` (claim-once, LRU + TTL); this module just
+ * computes the dedupe KEY.
+ *
+ * The key is the message GUID, namespaced per account. An `updated-message`
+ * (attachment-indexing follow-up) gets a distinct `:updated` suffix so the text
+ * pass and the attachment follow-up aren't collapsed into one (the follow-up
+ * must be allowed through to attach the now-indexed media).
+ */
+import { normalizeBlueBubblesWebhook } from "./normalize.js";
+/** The default dedupe cache TTL — generous (BlueBubbles replays up to ~1 week). */
+export const BLUEBUBBLES_DEDUPE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+/** The default dedupe cache size cap. */
+export const BLUEBUBBLES_DEDUPE_MAX_ENTRIES = 5000;
+/**
+ * Resolve the dedupe key for a webhook payload (or undefined when the payload has
+ * no usable message GUID — those are handled by the normalize skip path anyway).
+ * `accountId` namespaces the key so two accounts never collide.
+ */
+export function resolveBlueBubblesDedupeKey(accountId, payload, eventType) {
+    const result = normalizeBlueBubblesWebhook(payload, eventType);
+    if (result.kind !== "message")
+        return undefined;
+    const guid = result.message.messageGuid.trim();
+    if (!guid)
+        return undefined;
+    const base = `${accountId}:${guid}`;
+    return eventType === "updated-message" ? `${base}:updated` : base;
+}
+//# sourceMappingURL=dedupe.js.map

package/dist/agents/channels/bluebubbles/dedupe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedupe.js","sourceRoot":"","sources":["../../../../src/agents/channels/bluebubbles/dedupe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,2BAA2B,EAAE,MAAM,gBAAgB,CAAC;AAE7D,mFAAmF;AACnF,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AACjE,yCAAyC;AACzC,MAAM,CAAC,MAAM,8BAA8B,GAAG,IAAI,CAAC;AAEnD;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CAAC,SAAiB,EAAE,OAAgB,EAAE,SAAkB;IAClG,MAAM,MAAM,GAAG,2BAA2B,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAC/D,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAChD,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC;IAC/C,IAAI,CAAC,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5B,MAAM,IAAI,GAAG,GAAG,SAAS,IAAI,IAAI,EAAE,CAAC;IACpC,OAAO,SAAS,KAAK,iBAAiB,CAAC,CAAC,CAAC,GAAG,IAAI,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC;AACnE,CAAC"}

package/dist/agents/channels/bluebubbles/effects.d.ts

@@ -0,0 +1,17 @@
+/**
+ * iMessage send-effect (balloon / screen) id resolution.
+ *
+ * The Private-API `message/text` endpoint accepts an `effectId` — Apple's bundle
+ * identifier for a bubble or screen effect (`com.apple.MobileSMS.expressivesend.*`
+ * / `com.apple.messages.effect.*`). `resolveEffectId` maps a friendly short name
+ * (`"confetti"`, `"slam"`, `"invisible ink"`) onto that id; an already-qualified
+ * Apple id passes through.
+ */
+/**
+ * Resolve an effect name to an Apple effect id. Tries the literal name, then a
+ * `[\s_]`→`-` variant, then a separator-stripped compact form; an already-fully-
+ * qualified `com.apple.*` id passes through. Returns undefined for an unknown
+ * name (the caller then sends with no effect).
+ */
+export declare function resolveEffectId(raw: string): string | undefined;
+//# sourceMappingURL=effects.d.ts.map

package/dist/agents/channels/bluebubbles/effects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effects.d.ts","sourceRoot":"","sources":["../../../../src/agents/channels/bluebubbles/effects.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA2BH;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAW/D"}

package/dist/agents/channels/bluebubbles/effects.js

@@ -0,0 +1,57 @@
+/**
+ * iMessage send-effect (balloon / screen) id resolution.
+ *
+ * The Private-API `message/text` endpoint accepts an `effectId` — Apple's bundle
+ * identifier for a bubble or screen effect (`com.apple.MobileSMS.expressivesend.*`
+ * / `com.apple.messages.effect.*`). `resolveEffectId` maps a friendly short name
+ * (`"confetti"`, `"slam"`, `"invisible ink"`) onto that id; an already-qualified
+ * Apple id passes through.
+ */
+/** Friendly name → Apple effect bundle id. */
+const EFFECT_MAP = {
+    // Bubble effects
+    slam: "com.apple.MobileSMS.expressivesend.impact",
+    impact: "com.apple.MobileSMS.expressivesend.impact",
+    loud: "com.apple.MobileSMS.expressivesend.loud",
+    gentle: "com.apple.MobileSMS.expressivesend.gentle",
+    invisible: "com.apple.MobileSMS.expressivesend.invisibleink",
+    "invisible-ink": "com.apple.MobileSMS.expressivesend.invisibleink",
+    "invisible ink": "com.apple.MobileSMS.expressivesend.invisibleink",
+    invisibleink: "com.apple.MobileSMS.expressivesend.invisibleink",
+    // Screen effects
+    echo: "com.apple.messages.effect.CKEchoEffect",
+    spotlight: "com.apple.messages.effect.CKSpotlightEffect",
+    balloons: "com.apple.messages.effect.CKHappyBirthdayEffect",
+    confetti: "com.apple.messages.effect.CKConfettiEffect",
+    love: "com.apple.messages.effect.CKHeartEffect",
+    heart: "com.apple.messages.effect.CKHeartEffect",
+    hearts: "com.apple.messages.effect.CKHeartEffect",
+    lasers: "com.apple.messages.effect.CKLasersEffect",
+    fireworks: "com.apple.messages.effect.CKFireworksEffect",
+    celebration: "com.apple.messages.effect.CKSparklesEffect",
+    sparkles: "com.apple.messages.effect.CKSparklesEffect",
+};
+/**
+ * Resolve an effect name to an Apple effect id. Tries the literal name, then a
+ * `[\s_]`→`-` variant, then a separator-stripped compact form; an already-fully-
+ * qualified `com.apple.*` id passes through. Returns undefined for an unknown
+ * name (the caller then sends with no effect).
+ */
+export function resolveEffectId(raw) {
+    const trimmed = (raw ?? "").trim();
+    if (!trimmed)
+        return undefined;
+    if (/^com\.apple\./i.test(trimmed))
+        return trimmed;
+    const lower = trimmed.toLowerCase();
+    if (EFFECT_MAP[lower])
+        return EFFECT_MAP[lower];
+    const dashed = lower.replace(/[\s_]+/g, "-");
+    if (EFFECT_MAP[dashed])
+        return EFFECT_MAP[dashed];
+    const compact = lower.replace(/[\s_-]+/g, "");
+    if (EFFECT_MAP[compact])
+        return EFFECT_MAP[compact];
+    return undefined;
+}
+//# sourceMappingURL=effects.js.map

package/dist/agents/channels/bluebubbles/effects.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"effects.js","sourceRoot":"","sources":["../../../../src/agents/channels/bluebubbles/effects.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,8CAA8C;AAC9C,MAAM,UAAU,GAA2B;IAC1C,iBAAiB;IACjB,IAAI,EAAE,2CAA2C;IACjD,MAAM,EAAE,2CAA2C;IACnD,IAAI,EAAE,yCAAyC;IAC/C,MAAM,EAAE,2CAA2C;IACnD,SAAS,EAAE,iDAAiD;IAC5D,eAAe,EAAE,iDAAiD;IAClE,eAAe,EAAE,iDAAiD;IAClE,YAAY,EAAE,iDAAiD;IAC/D,iBAAiB;IACjB,IAAI,EAAE,wCAAwC;IAC9C,SAAS,EAAE,6CAA6C;IACxD,QAAQ,EAAE,iDAAiD;IAC3D,QAAQ,EAAE,4CAA4C;IACtD,IAAI,EAAE,yCAAyC;IAC/C,KAAK,EAAE,yCAAyC;IAChD,MAAM,EAAE,yCAAyC;IACjD,MAAM,EAAE,0CAA0C;IAClD,SAAS,EAAE,6CAA6C;IACxD,WAAW,EAAE,4CAA4C;IACzD,QAAQ,EAAE,4CAA4C;CACtD,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW;IAC1C,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACnC,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAC/B,IAAI,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC;IACnD,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IACpC,IAAI,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC;IAChD,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IAC7C,IAAI,UAAU,CAAC,MAAM,CAAC;QAAE,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC;IAClD,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAC9C,IAAI,UAAU,CAAC,OAAO,CAAC;QAAE,OAAO,UAAU,CAAC,OAAO,CAAC,CAAC;IACpD,OAAO,SAAS,CAAC;AAClB,CAAC"}