@pmate/chat-sdk 0.11.8 → 0.12.0-next.0

package/README.md

@@ -127,3 +127,45 @@ The handler leaves text-only pastes and events already handled by the host untou
 `useImageAttachments({ uploadImage, disabled })` provides `onPaste`, `addFiles`, `attachments`, `pending`, `remove` and `retry`. Render `ImageAttachmentTray` inside the composer's surface with these attachments and the input tokens. Local previews appear immediately; uploads happen in the background. Removal/unmount revokes local object URLs, and late upload results cannot reinsert removed drafts. Upload errors remain visible and retryable.
 
 Only send on explicit submission: block send while `pending`, deliver each ready attachment's `url`, and remove it after delivery succeeds. Keep unsuccessful drafts to allow retry without reuploading. For `ChatInputDesktop`, use `hasPendingContent` and `sendDisabled` with host-owned drafts. Unmount or key the draft owner when switching accounts, Teams or conversations.
+
+## Browser message and reading data
+
+### Background
+
+Message hosts previously coordinated remote history, offline snapshots, optimistic
+sends and reading synchronization independently. The runtime now provides local
+IndexedDB storage and fixed-window scheduling primitives so those operations can
+share bounded I/O, durable confirmation and scoped subscriptions.
+
+`MessageClient` reads a trusted recent window locally, coalesces concurrent misses,
+subscribes per conversation, and accepts incremental event batches. Its transport
+supplies authoritative `load`, `changes` and `older` pages. `nextBefore` tracks
+uncached older history independently of the latest synchronization checkpoint.
+A projection reset removes obsolete rows before installing a new window.
+`SocialReadClient.messagePage` implements the authenticated Hub page protocol;
+request cancellation is supported through its optional second signal argument.
+
+`ReadingClient` owns persisted visible/explicit read intents, windowed network
+synchronization and retry. A host reports actual visibility with `recordVisible`
+or explicit actions with `recordExplicit`; loading or subscribing never marks
+messages read. `getSnapshot` plus `subscribe` provide stable reading snapshots.
+`BatchedReadIndex` resolves queued writes only after their transaction commits.
+
+`IndexedDbRecordCache` is a version-aware control-event index. Call and await
+`open` before using it. An optional legacy reader runs during initialization only;
+legacy cleanup happens after durable migration. Normal reads use memory and writes
+are merged into bounded IndexedDB transactions. Cache errors must be surfaced by
+the host, and pending operations are not reported as saved before their promise
+resolves.
+
+`DurableChatSender` saves the exact message created by `ChatClient.prepareChat`
+before transmitting it. `retry(hash)` uses `sendPrepared` with the original hash
+and payload. Failed sends require an explicit retry; interrupted sends can resume
+when the connection returns. Call `confirm(hashes)` only after authoritative
+messages have been durably merged. Confirmation tombstones prevent another tab's
+late transport failure from recreating an outgoing message.
+
+These APIs are runtime primitives; applications must initialize them with the
+same authenticated scope, dispose them on identity changes, and wire their
+transport to an authorized server. The Merry migration and production validation
+are tracked in the unified message layer proposal.

package/lib/runtime/batchedReadIndex.d.ts

@@ -0,0 +1,23 @@
+import { type ReadIndexPersistence, type ReadIndexState } from "./readIndex.js";
+type Change = {
+    transform: (state: ReadIndexState) => ReadIndexState;
+    resolve: (state: ReadIndexState) => void;
+    reject: (error: unknown) => void;
+};
+/** Coalesces viewport observations into bounded, atomic read-index transactions.
+ * Each caller resolves only after its batch commits, never when merely queued. */
+export declare class BatchedReadIndex implements ReadIndexPersistence {
+    private storage;
+    private windowMs;
+    private batchSize;
+    private queueLimit;
+    private queues;
+    private closed;
+    constructor(storage: ReadIndexPersistence, windowMs?: number, batchSize?: number, queueLimit?: number);
+    load(appId: string, profileId: string): Promise<ReadIndexState | undefined>;
+    update(appId: string, profileId: string, transform: Change["transform"]): Promise<ReadIndexState>;
+    private drain;
+    flush(appId: string, profileId: string): Promise<void>;
+    close(): Promise<void>;
+}
+export {};

package/lib/runtime/batchedReadIndex.js

@@ -0,0 +1,81 @@
+import {} from "./readIndex.js";
+/** Coalesces viewport observations into bounded, atomic read-index transactions.
+ * Each caller resolves only after its batch commits, never when merely queued. */
+export class BatchedReadIndex {
+    storage;
+    windowMs;
+    batchSize;
+    queueLimit;
+    queues = new Map();
+    closed = false;
+    constructor(storage, windowMs = 16, batchSize = 128, queueLimit = 4096) {
+        this.storage = storage;
+        this.windowMs = windowMs;
+        this.batchSize = batchSize;
+        this.queueLimit = queueLimit;
+        if (windowMs < 0 || !Number.isSafeInteger(batchSize) || batchSize < 1 || !Number.isSafeInteger(queueLimit) || queueLimit < batchSize)
+            throw new Error("INVALID_READ_BATCH_OPTIONS");
+    }
+    async load(appId, profileId) {
+        await this.flush(appId, profileId);
+        if (this.closed)
+            throw new Error("READ_STORAGE_CLOSED");
+        return this.storage.load(appId, profileId);
+    }
+    update(appId, profileId, transform) {
+        if (this.closed)
+            return Promise.reject(new Error("READ_STORAGE_CLOSED"));
+        const key = JSON.stringify([appId, profileId]);
+        let queue = this.queues.get(key);
+        if (!queue) {
+            queue = { appId, profileId, pending: [] };
+            this.queues.set(key, queue);
+        }
+        if (queue.pending.length >= this.queueLimit)
+            return Promise.reject(new Error("READ_STORAGE_BACKPRESSURE"));
+        const promise = new Promise((resolve, reject) => queue.pending.push({ transform, resolve, reject }));
+        if (!queue.running && queue.timer === undefined)
+            queue.timer = setTimeout(() => { queue.timer = undefined; void this.drain(key, queue); }, this.windowMs);
+        return promise;
+    }
+    async drain(key, queue) {
+        if (queue.running)
+            return queue.running;
+        clearTimeout(queue.timer);
+        queue.timer = undefined;
+        const batch = queue.pending.splice(0, this.batchSize);
+        if (!batch.length)
+            return;
+        const run = (async () => {
+            try {
+                const next = await this.storage.update(queue.appId, queue.profileId, state => batch.reduce((current, change) => change.transform(current), state));
+                batch.forEach(change => change.resolve(next));
+            }
+            catch (error) {
+                batch.forEach(change => change.reject(error));
+            }
+        })();
+        queue.running = run;
+        await run;
+        queue.running = undefined;
+        if (queue.pending.length)
+            queue.timer = setTimeout(() => { queue.timer = undefined; void this.drain(key, queue); }, 0);
+        else
+            this.queues.delete(key);
+    }
+    async flush(appId, profileId) {
+        const key = JSON.stringify([appId, profileId]);
+        let queue = this.queues.get(key);
+        while (queue) {
+            if (queue.running)
+                await queue.running;
+            else
+                await this.drain(key, queue);
+            queue = this.queues.get(key);
+        }
+    }
+    async close() {
+        this.closed = true;
+        await Promise.all([...this.queues.values()].map(queue => this.flush(queue.appId, queue.profileId)));
+    }
+}

package/lib/runtime/chatClient.d.ts

@@ -46,6 +46,7 @@ export declare class ChatClient {
     private botKey;
     private readonly activities;
     private readonly publishers;
+    private readonly preparedSends;
     private readonly pendingAcks;
     private readonly messageHandlers;
     private readonly updateHandlers;
@@ -120,6 +121,9 @@ export declare class ChatClient {
         recipients?: string[];
         mentions?: ChatMention[];
     }): Promise<ChatRuntimeMessage>;
+    prepareChat(to: string, body: ChatBody, recipients?: string[]): ChatRuntimeMessage;
+    /** Reuses a durably saved hash and payload when retrying an uncertain send. */
+    sendPrepared(msg: ChatRuntimeMessage): Promise<ChatRuntimeMessage>;
     sendChat(to: string, body: ChatBody, recipients?: string[]): Promise<ChatRuntimeMessage>;
     private sendContactAction;
     private sendAuth;

package/lib/runtime/chatClient.js

@@ -29,6 +29,7 @@ export class ChatClient {
     botKey = null;
     activities = new ChatActivityStore();
     publishers = new Set();
+    preparedSends = new Map();
     pendingAcks = new Map();
     messageHandlers = new Set();
     updateHandlers = new Set();
@@ -254,11 +255,29 @@ export class ChatClient {
             content: { appId: this.options.appId, groupId: input.groupId, ...(input.teamId !== undefined ? { teamId: input.teamId } : {}), text: input.text, ...(input.mentions?.length ? { mentions: input.mentions } : {}) },
         }, input.recipients);
     }
-    async sendChat(to, body, recipients) {
+    prepareChat(to, body, recipients) {
         const msg = createRuntimeMsg(this.profileId(), to, ChatMsgOp.CHAT, withChatTeam(body, this.options.teamId), ChatMsgKind.DM);
-        if (recipients) {
-            msg.recipients = recipients;
+        if (recipients)
+            msg.recipients = [...recipients];
+        return msg;
+    }
+    /** Reuses a durably saved hash and payload when retrying an uncertain send. */
+    sendPrepared(msg) {
+        const body = msg.body;
+        if (msg.opcode !== ChatMsgOp.CHAT || msg.from !== this.profileId() || !msg.hash || (body?.content?.appId ?? body?.payload?.appId) !== this.options.appId) {
+            return Promise.reject(new Error("PREPARED_MESSAGE_IDENTITY_MISMATCH"));
         }
+        const existing = this.preparedSends.get(msg.hash);
+        if (existing)
+            return existing;
+        const saved = structuredClone(msg);
+        const task = this.sendAndWaitForAck(saved).then(() => saved).finally(() => this.preparedSends.delete(saved.hash));
+        this.preparedSends.set(saved.hash, task);
+        return task;
+    }
+    async sendChat(to, body, recipients) {
+        const msg = this.prepareChat(to, body, recipients);
+        // Existing control/activity envelopes retain their transport behavior.
         await this.sendAndWaitForAck(msg);
         return msg;
     }

package/lib/runtime/coalescer.d.ts

@@ -0,0 +1,12 @@
+/** Fixed windows, one in-flight task per key, and one trailing run for new work.
+ * Unlike trailing debounce, continuous events cannot postpone work indefinitely. */
+export declare class WindowedTasks {
+    private windowMs;
+    private onError;
+    private tasks;
+    private closed;
+    constructor(windowMs?: number, onError?: (error: unknown, key: string) => void);
+    schedule(key: string, work: () => Promise<void>, delay?: number): void;
+    private run;
+    close(): void;
+}

package/lib/runtime/coalescer.js

@@ -0,0 +1,56 @@
+/** Fixed windows, one in-flight task per key, and one trailing run for new work.
+ * Unlike trailing debounce, continuous events cannot postpone work indefinitely. */
+export class WindowedTasks {
+    windowMs;
+    onError;
+    tasks = new Map();
+    closed = false;
+    constructor(windowMs = 250, onError = () => { }) {
+        this.windowMs = windowMs;
+        this.onError = onError;
+    }
+    schedule(key, work, delay = this.windowMs) {
+        if (this.closed)
+            return;
+        let task = this.tasks.get(key);
+        if (!task) {
+            task = { dirty: false, work, failures: 0 };
+            this.tasks.set(key, task);
+        }
+        task.work = work;
+        task.dirty = true;
+        if (task.timer !== undefined || task.running)
+            return;
+        task.timer = setTimeout(() => { task.timer = undefined; void this.run(key, task); }, delay);
+    }
+    async run(key, task) {
+        if (this.closed || !task.dirty || task.running)
+            return;
+        task.dirty = false;
+        const pending = Promise.resolve().then(task.work);
+        task.running = pending;
+        try {
+            await pending;
+            task.failures = 0;
+        }
+        catch (error) {
+            task.failures++;
+            this.onError(error, key);
+        }
+        finally {
+            task.running = undefined;
+            if (!this.closed && task.dirty) {
+                const delay = task.failures ? Math.min(30_000, 1000 * 2 ** Math.min(task.failures - 1, 5)) : this.windowMs;
+                this.schedule(key, task.work, delay);
+            }
+            else
+                this.tasks.delete(key);
+        }
+    }
+    close() {
+        this.closed = true;
+        for (const task of this.tasks.values())
+            clearTimeout(task.timer);
+        this.tasks.clear();
+    }
+}

package/lib/runtime/durableSender.d.ts

@@ -0,0 +1,48 @@
+import type { ChatClient } from "./chatClient.js";
+import { type MessageScope } from "./messageStore.js";
+import type { ChatBody, ChatRuntimeMessage } from "./protocol.js";
+export type OutgoingMessage = {
+    scope: string;
+    threadId: string;
+    hash: string;
+    message: ChatRuntimeMessage;
+    status: "sending" | "failed" | "sent";
+    confirmed?: boolean;
+};
+/** Persists the exact wire message before sending; retries preserve its hash. */
+export declare class DurableChatSender {
+    private client;
+    private onError;
+    private db;
+    private outbox;
+    private scope;
+    private identity;
+    private values;
+    private snapshots;
+    private listeners;
+    private running;
+    private closed;
+    private offConnection;
+    private ready;
+    constructor(client: ChatClient, scope: MessageScope, onError: (error: unknown) => void, options?: {
+        indexedDB?: IDBFactory;
+        name?: string;
+    });
+    initialize(): Promise<void>;
+    subscribe(listener: () => void): () => void;
+    snapshot(threadId?: string): readonly OutgoingMessage[];
+    private emit;
+    send(threadId: string, input: {
+        to: string;
+        body: ChatBody;
+        recipients?: string[];
+    }): Promise<ChatRuntimeMessage>;
+    retry(hash: string): Promise<ChatRuntimeMessage>;
+    private transmit;
+    private save;
+    /** Confirm only after the authoritative message has been durably merged.
+     * A tombstone prevents another tab's late failure from recreating the outbox. */
+    confirm(hashes: string[]): Promise<void>;
+    private resume;
+    close(): Promise<void>;
+}

package/lib/runtime/durableSender.js

@@ -0,0 +1,173 @@
+import { Dexie } from "dexie";
+import { withChatTeam } from "./teamScope.js";
+import { messageScopeKey } from "./messageStore.js";
+/** Persists the exact wire message before sending; retries preserve its hash. */
+export class DurableChatSender {
+    client;
+    onError;
+    db;
+    outbox;
+    scope;
+    identity;
+    values = new Map();
+    snapshots = new Map();
+    listeners = new Set();
+    running = new Map();
+    closed = false;
+    offConnection;
+    ready;
+    constructor(client, scope, onError, options = {}) {
+        this.client = client;
+        this.onError = onError;
+        this.scope = messageScopeKey(scope);
+        this.identity = { ...scope };
+        this.db = new Dexie(options.name ?? "pmate-chat-outbox", { indexedDB: options.indexedDB ?? globalThis.indexedDB, IDBKeyRange: globalThis.IDBKeyRange });
+        this.db.version(1).stores({ outbox: "[scope+hash],scope,[scope+threadId]" });
+        this.outbox = this.db.table("outbox");
+        this.ready = this.outbox.where("scope").equals(this.scope).toArray().then(records => {
+            if (this.closed)
+                return;
+            records.filter(record => !record.confirmed).forEach(record => this.values.set(record.hash, record));
+            this.emit();
+        });
+        this.offConnection = client.watchConnection(state => {
+            if (state === "connected")
+                void this.resume().catch(onError);
+        });
+    }
+    initialize() { return this.ready; }
+    subscribe(listener) { this.listeners.add(listener); return () => { this.listeners.delete(listener); }; }
+    snapshot(threadId) {
+        let snapshot = this.snapshots.get(threadId);
+        if (!snapshot) {
+            snapshot = [...this.values.values()].filter(record => threadId === undefined || record.threadId === threadId);
+            this.snapshots.set(threadId, snapshot);
+        }
+        return snapshot;
+    }
+    emit() { this.snapshots.clear(); if (!this.closed)
+        this.listeners.forEach(listener => listener()); }
+    async send(threadId, input) {
+        await this.ready;
+        if (this.closed)
+            throw new Error("CHAT_SENDER_CLOSED");
+        const message = this.client.prepareChat(input.to, withChatTeam(input.body, this.identity.teamId), input.recipients);
+        if (message.from !== this.identity.profileId)
+            throw new Error("OUTGOING_MESSAGE_IDENTITY_MISMATCH");
+        const record = { scope: this.scope, threadId, hash: message.hash, message, status: "sending" };
+        await this.outbox.put(record);
+        if (this.closed)
+            throw new Error("CHAT_SENDER_CLOSED");
+        this.values.set(record.hash, record);
+        this.emit();
+        return this.retry(record.hash);
+    }
+    retry(hash) {
+        if (this.closed)
+            return Promise.reject(new Error("CHAT_SENDER_CLOSED"));
+        const running = this.running.get(hash);
+        if (running)
+            return running;
+        const task = this.transmit(hash).finally(() => this.running.delete(hash));
+        this.running.set(hash, task);
+        return task;
+    }
+    async transmit(hash) {
+        await this.ready;
+        const record = await this.outbox.get([this.scope, hash]);
+        if (!record || this.closed)
+            throw new Error("OUTGOING_MESSAGE_UNAVAILABLE");
+        if (record.status === "sent" || record.confirmed)
+            return record.message;
+        const sending = { ...record, status: "sending" };
+        if (record.status !== "sending") {
+            const latest = await this.save(sending);
+            if (!latest || latest.confirmed || latest.status === "sent")
+                return latest?.message ?? record.message;
+        }
+        if (this.values.get(hash)?.status !== "sending") {
+            this.values.set(hash, sending);
+            this.emit();
+        }
+        try {
+            const message = await this.client.sendPrepared(record.message);
+            const sent = { ...record, message, status: "sent" };
+            const committed = await this.save(sent);
+            if (!this.closed) {
+                if (committed?.confirmed || !committed)
+                    this.values.delete(hash);
+                else
+                    this.values.set(hash, committed);
+                this.emit();
+            }
+            return message;
+        }
+        catch (error) {
+            if (!this.closed) {
+                const failed = { ...record, status: "failed" };
+                const committed = await this.save(failed);
+                if (committed?.confirmed || committed?.status === "sent") {
+                    this.values.delete(hash);
+                    this.emit();
+                    return committed.message;
+                }
+                if (committed)
+                    this.values.set(hash, committed);
+                else
+                    this.values.delete(hash);
+                this.emit();
+            }
+            throw error;
+        }
+    }
+    async save(record) {
+        return this.db.transaction("rw", this.outbox, async () => {
+            const previous = await this.outbox.get([this.scope, record.hash]);
+            if (!previous || previous.confirmed || previous.status === "sent")
+                return previous;
+            await this.outbox.put(record);
+            return record;
+        });
+    }
+    /** Confirm only after the authoritative message has been durably merged.
+     * A tombstone prevents another tab's late failure from recreating the outbox. */
+    async confirm(hashes) {
+        await this.ready;
+        await this.db.transaction("rw", this.outbox, async () => {
+            const previous = await this.outbox.bulkGet(hashes.map(hash => [this.scope, hash]));
+            const confirmed = previous.filter((record) => Boolean(record)).map(record => ({ ...record, status: "sent", confirmed: true }));
+            if (confirmed.length)
+                await this.outbox.bulkPut(confirmed);
+        });
+        let changed = false;
+        for (const hash of hashes)
+            changed = this.values.delete(hash) || changed;
+        if (changed)
+            this.emit();
+    }
+    async resume() {
+        await this.ready;
+        if (this.closed)
+            return;
+        // Only interrupted, unconfirmed sends resume automatically; failed sends require retry.
+        for (const record of this.values.values())
+            if (record.status === "sending") {
+                if (this.closed)
+                    return;
+                try {
+                    await this.retry(record.hash);
+                }
+                catch (error) {
+                    this.onError(error);
+                }
+            }
+    }
+    async close() {
+        this.closed = true;
+        this.offConnection();
+        this.listeners.clear();
+        await this.ready;
+        await Promise.allSettled([...this.running.values()]);
+        this.db.close();
+    }
+}

package/lib/runtime/index.d.ts

@@ -19,3 +19,10 @@ export * from "./teamScope.js";
 export * from "./teamMigrations.js";
 export * from "./socialReadClient.js";
 export * from "./readCounts.js";
+export * from "./coalescer.js";
+export * from "./batchedReadIndex.js";
+export * from "./readingClient.js";
+export * from "./messageStore.js";
+export * from "./messageClient.js";
+export * from "./recordCache.js";
+export * from "./durableSender.js";

package/lib/runtime/index.js

@@ -19,3 +19,10 @@ export * from "./teamScope.js";
 export * from "./teamMigrations.js";
 export * from "./socialReadClient.js";
 export * from "./readCounts.js";
+export * from "./coalescer.js";
+export * from "./batchedReadIndex.js";
+export * from "./readingClient.js";
+export * from "./messageStore.js";
+export * from "./messageClient.js";
+export * from "./recordCache.js";
+export * from "./durableSender.js";

package/lib/runtime/messageClient.d.ts

@@ -0,0 +1,68 @@
+import { IndexedDbMessageStore, type MessageScope, type StoredMessage } from "./messageStore.js";
+export type MessagePage<T> = {
+    messages: T[];
+    checkpoint?: string;
+    nextBefore?: string | null;
+    hasMoreChanges?: boolean;
+    resetRequired?: boolean;
+};
+export type MessageTransport<T> = {
+    /** Authoritative history. Must include control state needed to merge old rows. */
+    load: (threadId: string, signal: AbortSignal) => Promise<MessagePage<T>>;
+    changes?: (threadId: string, after: string, signal: AbortSignal) => Promise<MessagePage<T>>;
+    older?: (threadId: string, before: string, signal: AbortSignal) => Promise<MessagePage<T>>;
+};
+export type MessageSnapshot<T> = {
+    messages: readonly T[];
+    hasEarlier: boolean;
+};
+export type MessageClientOptions<T extends StoredMessage> = {
+    scope: MessageScope;
+    transport: MessageTransport<T>;
+    storage?: IndexedDbMessageStore<T>;
+    merge?: (previous: T | undefined, incoming: T) => T;
+    onError?: (error: unknown, threadId: string) => void;
+    batchSize?: number;
+    writeWindowMs?: number;
+    syncWindowMs?: number;
+};
+/** Local-first message facade; hosts never select a cache or network source. */
+export declare class MessageClient<T extends StoredMessage> {
+    private options;
+    private storage;
+    private watches;
+    private reads;
+    private syncing;
+    private writes;
+    private activeWrites;
+    private writeTasks;
+    private syncTasks;
+    private abort;
+    private channel?;
+    private closed;
+    private closing;
+    private revoked;
+    private batchSize;
+    constructor(options: MessageClientOptions<T>);
+    getSnapshot(thread: string): MessageSnapshot<T> | undefined;
+    subscribe(thread: string, listener: () => void): () => void;
+    read(thread: string, limit?: number): Promise<MessageSnapshot<T>>;
+    /** Application connection/wake events invalidate, rather than fetching directly. */
+    invalidate(thread: string): void;
+    private reload;
+    /** Events are visible only after their atomic batch commits. */
+    receive(thread: string, messages: T[]): Promise<void>;
+    private persist;
+    private flushWrites;
+    private runWrites;
+    synchronize(thread: string): Promise<void>;
+    earlier(thread: string, before: {
+        timestamp: number;
+        id: string;
+    }, limit?: number): Promise<{
+        messages: T[];
+        hasEarlier: boolean;
+    }>;
+    revoke(thread: string): Promise<void>;
+    close(): Promise<void>;
+}