@pmate/chat-sdk 0.11.9 → 0.12.0-next.1

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/chatSession.d.ts

@@ -0,0 +1,59 @@
+import { type MessageReadersQuery } from "./messageReaders.js";
+import { type MessageClientOptions } from "./messageClient.js";
+import { DurableChatSender } from "./durableSender.js";
+import { type ReadingClientOptions } from "./readingClient.js";
+import { type ChatClientOptions } from "./chatClient.js";
+import { unreadInConversation } from "./readIndex.js";
+import type { StoredMessage } from "./messageStore.js";
+import type { ChatBody, ChatRuntimeMessage } from "./protocol.js";
+export type ChatSessionOptions<T extends StoredMessage> = {
+    messages: MessageClientOptions<T>;
+    connection: ChatClientOptions;
+    reading: ReadingClientOptions;
+    decode: (message: ChatRuntimeMessage) => T | undefined;
+    onError: (error: unknown) => void;
+};
+export type ChatThreadSnapshot<T> = {
+    messages: readonly T[];
+    outgoing: ReturnType<DurableChatSender["snapshot"]>;
+    hasEarlier: boolean;
+    unread: ReturnType<typeof unreadInConversation>;
+};
+/** Owns all browser message clients. Hosts subscribe to stable thread snapshots. */
+export declare class ChatSession<T extends StoredMessage> {
+    private options;
+    private messages;
+    private connection;
+    private reading;
+    private readers;
+    private sender;
+    private listeners;
+    private snapshots;
+    private off;
+    private closed;
+    private starting?;
+    private closing?;
+    constructor(options: ChatSessionOptions<T>);
+    start(): Promise<void>;
+    private assertOpen;
+    getMessages(threadId: string, options?: {
+        limit?: number;
+        before?: {
+            timestamp: number;
+            id: string;
+        };
+    }): Promise<import("./messageClient.js").MessageSnapshot<T>>;
+    sendMessage(threadId: string, input: {
+        to: string;
+        body: ChatBody;
+        recipients?: string[];
+    }): Promise<ChatRuntimeMessage>;
+    getReaders(threadId: string, messageId: string, page?: Omit<MessageReadersQuery, "threadId" | "messageId">, signal?: AbortSignal): Promise<import("./messageReaders.js").MessageReadersPage>;
+    retryMessage(messageId: string): Promise<ChatRuntimeMessage>;
+    observeMessages(threadId: string, ids: string[], event: "visible" | "played"): Promise<import("./readIndex.js").ReadIndexState>;
+    getSnapshot(threadId: string): ChatThreadSnapshot<T>;
+    subscribe(threadId: string, listener: () => void): () => void;
+    private publishAll;
+    private publish;
+    close(): Promise<void>;
+}

package/lib/runtime/chatSession.js

@@ -0,0 +1,130 @@
+import { MessageReadersClient } from "./messageReaders.js";
+import { MessageClient } from "./messageClient.js";
+import { DurableChatSender } from "./durableSender.js";
+import { ReadingClient } from "./readingClient.js";
+import { ChatClient } from "./chatClient.js";
+import { unreadInConversation } from "./readIndex.js";
+/** Owns all browser message clients. Hosts subscribe to stable thread snapshots. */
+export class ChatSession {
+    options;
+    messages;
+    connection;
+    reading;
+    readers;
+    sender;
+    listeners = new Map();
+    snapshots = new Map();
+    off = [];
+    closed = false;
+    starting;
+    closing;
+    constructor(options) {
+        this.options = options;
+        const scope = options.messages.scope;
+        if (options.connection.appId !== scope.appId || options.reading.appId !== scope.appId || options.reading.profileId !== scope.profileId || options.connection.profileId !== scope.profileId || options.connection.teamId !== scope.teamId)
+            throw new Error("CHAT_SESSION_SCOPE_MISMATCH");
+        this.messages = new MessageClient(options.messages);
+        this.connection = new ChatClient(options.connection);
+        this.reading = new ReadingClient(options.reading);
+        this.readers = new MessageReadersClient({ appId: scope.appId, profileId: scope.profileId, token: options.reading.sessionToken, hubHttpUrl: options.reading.hubHttpUrl, fetch: options.reading.fetch });
+        this.sender = new DurableChatSender(this.connection, scope, options.onError);
+        this.off.push(this.sender.subscribe(() => this.publishAll()), this.reading.subscribe(() => this.publishAll()));
+        this.off.push(this.connection.watchMessages(message => {
+            try {
+                const decoded = options.decode(message);
+                if (decoded)
+                    void this.messages.receive(decoded.threadId, [decoded]).then(() => { this.publish(decoded.threadId); return this.sender.confirm([message.hash]); }).catch(options.onError);
+            }
+            catch (error) {
+                options.onError(error);
+            }
+        }));
+        this.off.push(this.connection.watchConnection(state => {
+            if (state === "connected") {
+                for (const thread of this.listeners.keys())
+                    this.messages.invalidate(thread);
+                this.reading.refresh();
+            }
+        }));
+    }
+    start() {
+        this.assertOpen();
+        return this.starting ??= (async () => {
+            await this.sender.initialize();
+            await this.reading.start();
+            this.assertOpen();
+            await this.connection.connect();
+        })().catch(error => { this.starting = undefined; throw error; });
+    }
+    assertOpen() { if (this.closed)
+        throw new Error("CHAT_SESSION_CLOSED"); }
+    async getMessages(threadId, options = {}) {
+        this.assertOpen();
+        const page = await (options.before ? this.messages.earlier(threadId, options.before, options.limit) : this.messages.read(threadId, options.limit));
+        if (!options.before)
+            this.publish(threadId);
+        return page;
+    }
+    sendMessage(threadId, input) {
+        this.assertOpen();
+        return this.sender.enqueue(threadId, input);
+    }
+    getReaders(threadId, messageId, page = {}, signal) {
+        this.assertOpen();
+        return this.readers.getReaders({ ...page, threadId, messageId }, signal);
+    }
+    retryMessage(messageId) { this.assertOpen(); return this.sender.retry(messageId); }
+    observeMessages(threadId, ids, event) {
+        this.assertOpen();
+        return event === "played" ? this.reading.recordExplicit(threadId, ids) : this.reading.recordVisible(threadId, ids);
+    }
+    getSnapshot(threadId) {
+        let snapshot = this.snapshots.get(threadId);
+        if (!snapshot) {
+            const messages = this.messages.getSnapshot(threadId);
+            const state = this.reading.getSnapshot();
+            snapshot = { messages: messages?.messages ?? [], hasEarlier: messages?.hasEarlier ?? false, outgoing: this.sender.snapshot(threadId), unread: state?.threads.some(thread => (thread.conversationId ?? thread.id) === threadId) ? unreadInConversation(state, threadId) : { unreadMessageCount: 0, unreadMentionCount: 0, badgeCount: 0 } };
+            this.snapshots.set(threadId, snapshot);
+        }
+        return snapshot;
+    }
+    subscribe(threadId, listener) {
+        this.assertOpen();
+        let listeners = this.listeners.get(threadId);
+        if (!listeners) {
+            listeners = new Set();
+            this.listeners.set(threadId, listeners);
+        }
+        listeners.add(listener);
+        const off = this.messages.subscribe(threadId, () => this.publish(threadId));
+        return () => {
+            off();
+            listeners.delete(listener);
+            if (!listeners.size)
+                this.listeners.delete(threadId);
+        };
+    }
+    publishAll() { for (const threadId of [...this.snapshots.keys()])
+        this.publish(threadId); }
+    publish(threadId) {
+        const previous = this.snapshots.get(threadId);
+        this.snapshots.delete(threadId);
+        const next = this.getSnapshot(threadId);
+        if (previous && JSON.stringify(previous) === JSON.stringify(next)) {
+            this.snapshots.set(threadId, previous);
+            return;
+        }
+        this.listeners.get(threadId)?.forEach(listener => listener());
+    }
+    close() {
+        return this.closing ??= (async () => {
+            this.closed = true;
+            this.off.splice(0).forEach(off => off());
+            this.connection.close();
+            this.readers.close();
+            await Promise.all([this.sender.close(), this.reading.close(), this.messages.close()]);
+            this.listeners.clear();
+            this.snapshots.clear();
+        })();
+    }
+}

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,56 @@
+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;
+    /** Resolves after the exact wire message is durable, independently of network delivery. */
+    enqueue(threadId: string, input: {
+        to: string;
+        body: ChatBody;
+        recipients?: string[];
+    }): Promise<ChatRuntimeMessage>;
+    /** Compatibility API: resolves only after transport delivery. */
+    send(threadId: string, input: {
+        to: string;
+        body: ChatBody;
+        recipients?: string[];
+    }): Promise<ChatRuntimeMessage>;
+    private persistOutgoing;
+    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>;
+}