@pmate/chat-sdk 0.12.0-next.52 → 0.12.0-next.54

package/lib/runtime/chatSession.d.ts

@@ -17,6 +17,7 @@ export type ChatSessionOptions<T extends StoredMessage> = {
     sharedConnection?: ChatClient;
     activeThreadId?: string;
     uploadVoice?: DurableSenderOptions["uploadVoice"];
+    reconcileOutgoing?: DurableSenderOptions["reconcile"];
     reading: ReadingClientOptions;
     decode: (message: ChatRuntimeMessage) => T | undefined;
     readingCandidate?: (message: T) => ReadingCandidate | undefined;

package/lib/runtime/chatSession.js

@@ -69,7 +69,21 @@ export class ChatSession {
             } });
         this.reading = new ReadingClient({ ...options.reading, teamId: scope.teamId, storageScope: JSON.stringify([scope.accountId]), migrateLegacy: true, metadataOnly: true });
         this.readers = new MessageReadersClient({ appId: scope.appId, profileId: scope.profileId, token: options.reading.sessionToken, scope, access: () => this.messages.scopeAccess(), onError: options.onError, hubHttpUrl: options.reading.hubHttpUrl, fetch: options.reading.fetch });
-        this.sender = new DurableChatSender(this.connection, scope, options.onError, { access: () => this.messages.scopeAccess(), uploadVoice: options.uploadVoice });
+        this.sender = new DurableChatSender(this.connection, scope, options.onError, { access: () => this.messages.scopeAccess(), uploadVoice: options.uploadVoice, reconcile: async (record, signal) => {
+                const cached = await this.messages.cachedMessage(record.threadId, record.message.hash);
+                if (cached && cached.from === scope.profileId && cached.to === record.message.to)
+                    return true;
+                if (!options.reconcileOutgoing)
+                    throw new Error("OUTBOX_RECONCILIATION_UNAVAILABLE");
+                try {
+                    return await options.reconcileOutgoing(record, signal);
+                }
+                catch (error) {
+                    if ([401, 403].includes(error?.status ?? 0))
+                        await this.messages.revoke(record.threadId);
+                    throw error;
+                }
+            } });
         this.catchUp = new WindowedTasks(1000, error => { if (!this.closed)
             options.onError(error); });
         this.countTasks = new WindowedTasks(50, error => { if (!this.closed)

package/lib/runtime/createChat.js

@@ -1,4 +1,5 @@
 import { voiceUploader } from "./voiceUpload.js";
+import { isOffline } from "./connectivity.js";
 import { isReadingControl, messageRequiresPlayback, messageMentionsProfile } from "./readingContent.js";
 import { ChatSession } from "./chatSession.js";
 import { SocialReadClient } from "./socialReadClient.js";
@@ -19,6 +20,18 @@ export function createChat(options) {
     return new ChatSession({
         sharedConnection: options.connection,
         uploadVoice: voiceUploader(profileId, options.uploadEndpoint, options.fetch),
+        reconcileOutgoing: async (record, signal) => {
+            if (isOffline())
+                throw new Error("OUTBOX_RECONCILIATION_OFFLINE");
+            const result = await reader.messagePage({ threadId: record.threadId, teamId, messageId: record.message.hash }, signal);
+            const expected = record.message.body;
+            return result.messages.some(message => {
+                const body = message.body;
+                if (message.from !== profileId || message.to !== record.message.to || body?.kind !== expected.kind || body?.action !== expected.action)
+                    throw new Error("OUTBOX_RECONCILIATION_MISMATCH");
+                return true;
+            });
+        },
         activeThreadId: options.threadId,
         messages: { scope: { appId, accountId, profileId, teamId }, transport: { load: (thread, signal) => page(thread, signal), changes: (thread, after, signal) => page(thread, signal, { after }), older: (thread, before, signal) => page(thread, signal, { before }) }, onError },
         reading: { appId, profileId, sessionToken: token, hubHttpUrl: http, fetch: options.fetch, onError },

package/lib/runtime/durableSender.d.ts

@@ -31,6 +31,7 @@ export type DurableSenderOptions = {
     name?: string;
     access?: () => Promise<SenderScopeAccess>;
     uploadVoice?: (blob: Blob, signal: AbortSignal) => Promise<string>;
+    reconcile?: (record: Pick<OutgoingMessage, "threadId" | "message">, signal: AbortSignal) => Promise<boolean>;
 };
 /** Persists the exact wire message before sending; retries preserve its hash. */
 export declare class DurableChatSender {
@@ -43,6 +44,8 @@ export declare class DurableChatSender {
     private localUrls;
     private localViews;
     private uploads;
+    private reconciliations;
+    private firstDelivery;
     private uploadTail;
     private uploadWaiting;
     private confirmationQueue;
@@ -87,6 +90,7 @@ export declare class DurableChatSender {
     private persistOutgoing;
     retry(hash: string): Promise<ChatRuntimeMessage>;
     private transmit;
+    private reconcile;
     private releaseUrl;
     private releaseUrls;
     private localView;

package/lib/runtime/durableSender.js

@@ -1,4 +1,6 @@
 import { Dexie } from "dexie";
+import { blake3 } from "@noble/hashes/blake3.js";
+import { bytesToHex } from "@noble/hashes/utils.js";
 import { withChatTeam } from "./teamScope.js";
 import { messageScopeKey } from "./messageStore.js";
 /** Persists the exact wire message before sending; retries preserve its hash. */
@@ -12,6 +14,8 @@ export class DurableChatSender {
     localUrls = new Map();
     localViews = new WeakMap();
     uploads = new Set();
+    reconciliations = new Set();
+    firstDelivery = new Set();
     uploadTail = Promise.resolve();
     uploadWaiting = 0;
     confirmationQueue = [];
@@ -187,6 +191,8 @@ export class DurableChatSender {
         this.withdrawn = true;
         this.failConfirmations(new Error("OUTBOX_ACCESS_REVOKED"));
         this.uploads.forEach(controller => controller.abort());
+        this.reconciliations.forEach(controller => controller.abort());
+        this.firstDelivery.clear();
         this.releaseUrls();
         this.values.clear();
         this.emit();
@@ -249,17 +255,43 @@ export class DurableChatSender {
             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 command = statefulGroup(message);
+            if (command)
+                message.hash = commandId(this.scope, this.version, threadId, message);
             if (input.voiceBlob) {
                 const body = message.body;
                 if (!(input.voiceBlob instanceof Blob) || input.voiceBlob.size === 0 || input.voiceBlob.size > 16 * 1024 * 1024 || body.kind !== "message" || !validVoice(body.content.voice))
                     throw new Error("INVALID_VOICE_ATTACHMENT");
             }
             const record = { ...(input.voiceBlob ? { voiceData: { bytes: await input.voiceBlob.arrayBuffer(), type: input.voiceBlob.type } } : {}), scope: this.scope, threadId, hash: message.hash, message, status: "sending", accessVersion: this.version };
-            await this.withEpoch("rw", async () => { await this.outbox.put(record); });
+            const durable = await this.withEpoch("rw", async () => {
+                if (command) {
+                    const previous = await this.outbox.get([this.scope, message.hash]);
+                    if (previous && (previous.accessVersion ?? 0) === this.version) {
+                        if (previous.message.from !== this.identity.profileId || previous.message.hash !== message.hash || commandId(this.scope, this.version, threadId, previous.message) !== message.hash)
+                            throw new Error("OUTGOING_COMMAND_CONFLICT");
+                        return previous;
+                    }
+                }
+                await this.outbox.put(record);
+                return record;
+            });
             await this.checkAccess();
-            this.values.set(record.hash, record);
-            this.emit();
-            return message;
+            if (command && durable === record)
+                this.firstDelivery.add(record.hash);
+            if (durable.confirmed) {
+                this.firstDelivery.delete(durable.hash);
+                if (this.values.delete(durable.hash))
+                    this.emit();
+            }
+            else {
+                const current = this.values.get(durable.hash);
+                if (!current || current.status !== durable.status || current.accessVersion !== durable.accessVersion) {
+                    this.values.set(durable.hash, durable);
+                    this.emit();
+                }
+            }
+            return durable.message;
         })().finally(() => this.accepted.delete(pending));
         this.accepted.add(pending);
         return pending;
@@ -279,8 +311,10 @@ export class DurableChatSender {
         let record = await this.withEpoch("r", async () => this.outbox.get([this.scope, hash]));
         if (!record || this.closed || this.withdrawn)
             throw new Error("OUTGOING_MESSAGE_UNAVAILABLE");
-        if (record.status === "sent" || record.confirmed)
+        if (record.status === "sent" || record.confirmed) {
+            this.firstDelivery.delete(hash);
             return record.message;
+        }
         const sending = { ...record, status: "sending" };
         if (record.status !== "sending") {
             const latest = await this.save(sending);
@@ -292,7 +326,15 @@ export class DurableChatSender {
             this.values.set(hash, sending);
             this.emit();
         }
+        let transmitting = false;
         try {
+            if (statefulGroup(record.message) && !this.firstDelivery.delete(hash)) {
+                const confirmed = await this.reconcile(record);
+                if (confirmed) {
+                    await this.confirm([hash]);
+                    return record.message;
+                }
+            }
             if (hasVoice(record)) {
                 record = await this.prepareVoice(record);
                 if (record.confirmed || record.status === "sent")
@@ -301,6 +343,7 @@ export class DurableChatSender {
             await this.checkAccess();
             if (this.closing)
                 throw new Error("CHAT_SENDER_CLOSED");
+            transmitting = true;
             const message = await this.client.sendPrepared(record.message);
             const sent = { ...record, message, status: "sent" };
             const committed = await this.save(sent);
@@ -314,7 +357,20 @@ export class DurableChatSender {
             return message;
         }
         catch (error) {
-            if (!this.closed && !this.withdrawn) {
+            // A failed delivery can already be durable remotely, including the first
+            // lost ACK. Proof recovery never sends a second wire in this attempt.
+            if (statefulGroup(record.message) && this.options.reconcile && transmitting && !this.closed && !this.closing && !this.withdrawn) {
+                try {
+                    if (await this.reconcile(record)) {
+                        await this.confirm([hash]);
+                        return record.message;
+                    }
+                }
+                catch (verificationError) {
+                    error = new AggregateError([error, verificationError], "OUTBOX_RECONCILIATION_FAILED");
+                }
+            }
+            if (!this.closed && !this.withdrawn && !(this.closing && statefulGroup(record.message))) {
                 const failed = { ...record, status: "failed" };
                 const committed = await this.save(failed);
                 if (committed?.confirmed || committed?.status === "sent") {
@@ -331,6 +387,30 @@ export class DurableChatSender {
             throw error;
         }
     }
+    async reconcile(record) {
+        await this.checkAccess();
+        if (this.closing || this.closed || this.withdrawn)
+            throw new Error("OUTBOX_RECONCILIATION_ABORTED");
+        if (!this.options.reconcile)
+            throw new Error("OUTBOX_RECONCILIATION_UNAVAILABLE");
+        const controller = new AbortController();
+        this.reconciliations.add(controller);
+        let abort;
+        const stopped = new Promise((_, reject) => { abort = () => reject(new Error("OUTBOX_RECONCILIATION_ABORTED")); controller.signal.addEventListener("abort", abort, { once: true }); });
+        const timer = setTimeout(() => controller.abort(), 10_000);
+        try {
+            const confirmed = await Promise.race([this.options.reconcile({ threadId: record.threadId, message: record.message }, controller.signal), stopped]);
+            await this.checkAccess();
+            if (this.closing || controller.signal.aborted)
+                throw new Error("OUTBOX_RECONCILIATION_ABORTED");
+            return confirmed;
+        }
+        finally {
+            clearTimeout(timer);
+            controller.signal.removeEventListener("abort", abort);
+            this.reconciliations.delete(controller);
+        }
+    }
     releaseUrl(hash) { const value = this.localUrls.get(hash); if (value) {
         URL.revokeObjectURL(value.url);
         this.localUrls.delete(hash);
@@ -533,6 +613,7 @@ export class DurableChatSender {
     async close() {
         this.closing = true;
         this.uploads.forEach(controller => controller.abort());
+        this.reconciliations.forEach(controller => controller.abort());
         this.offConnection();
         this.listeners.clear();
         this.channel?.close();
@@ -545,6 +626,7 @@ export class DurableChatSender {
         finally {
             this.closed = true;
             this.failConfirmations(new Error("CHAT_SENDER_CLOSED"));
+            this.firstDelivery.clear();
             this.releaseUrls();
             this.values.clear();
             this.snapshots.clear();
@@ -552,6 +634,17 @@ export class DurableChatSender {
         }
     }
 }
+function statefulGroup(message) { const body = message.body; return body?.kind === "group" && (body.action === "groupCreate" || body.action === "groupUpdate"); }
+function commandId(scope, version, threadId, message) {
+    return bytesToHex(blake3(new TextEncoder().encode(JSON.stringify(["chat-command:v1", scope, version, threadId, message.to, ordered(message.body)]))));
+}
+function ordered(value) {
+    if (Array.isArray(value))
+        return value.map(ordered);
+    if (value && typeof value === "object")
+        return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, item]) => [key, ordered(item)]));
+    return value;
+}
 function validVoice(value) { const voice = value; return Boolean(voice && typeof voice.url === "string" && Number.isFinite(voice.durationMs) && voice.durationMs > 0); }
 function withVoiceUrl(message, url) {
     const body = message.body;

package/lib/runtime/messageClient.d.ts

@@ -41,6 +41,7 @@ export declare class MessageClient<T extends StoredMessage> {
     private allListeners;
     private reads;
     private syncing;
+    private completedSyncs;
     private paging;
     private writes;
     private activeWrites;
@@ -72,6 +73,8 @@ export declare class MessageClient<T extends StoredMessage> {
         allowed: boolean;
     }>;
     getSnapshot(thread: string): MessageSnapshot<T> | undefined;
+    /** Exact authoritative row only; migration-only rows never prove delivery. */
+    cachedMessage(thread: string, id: string): Promise<T>;
     subscribe(thread: string, listener: () => void): () => void;
     subscribeAll(listener: (threadId: string) => void): () => void;
     /** Close the connection gap for saved windows with four bounded background lanes. */

package/lib/runtime/messageClient.js

@@ -11,6 +11,7 @@ export class MessageClient {
     allListeners = new Set();
     reads = new Map();
     syncing = new Map();
+    completedSyncs = new Map();
     paging = new Map();
     writes = new Map();
     activeWrites = new Set();
@@ -100,6 +101,16 @@ export class MessageClient {
         return { version: current.version, allowed: !this.scopeDenied && !current.revoked && current.version === this.scopeVersion };
     }
     getSnapshot(thread) { return this.watches.get(thread)?.snapshot; }
+    /** Exact authoritative row only; migration-only rows never prove delivery. */
+    async cachedMessage(thread, id) {
+        await this.ensureScope();
+        if (this.closed || this.closing || this.scopeDenied || this.revoked.has(thread))
+            throw accessRevoked();
+        const page = await this.storage.readSelected(thread, [id]);
+        if (page.coverage?.revoked || (page.coverage?.scopeVersion ?? 0) !== this.scopeVersion)
+            throw accessRevoked();
+        return page.messages[0];
+    }
     subscribe(thread, listener) {
         let watch = this.watches.get(thread);
         if (!watch) {
@@ -137,6 +148,7 @@ export class MessageClient {
         if (running)
             return running;
         const task = (async () => {
+            const completedAtStart = this.completedSyncs.get(thread);
             await this.ensureScope();
             if (this.scopeDenied)
                 throw accessRevoked();
@@ -197,6 +209,7 @@ export class MessageClient {
             if (this.scopeDenied || this.revoked.has(thread))
                 throw accessRevoked();
             if (local.coverage?.complete && Date.now() - (local.coverage.syncedAt ?? 0) > (this.options.freshnessMs ?? 30_000)
+                && !this.syncing.has(thread) && this.completedSyncs.get(thread) === completedAtStart
                 && (typeof navigator === "undefined" || navigator.onLine !== false))
                 this.invalidate(thread);
             return limit === 100 ? snapshot : result;
@@ -483,6 +496,7 @@ export class MessageClient {
                 this.assertNetworkAvailable(thread);
                 page = await this.options.transport.changes(thread, after, this.abort.signal);
             }
+            this.completedSyncs.set(thread, (this.completedSyncs.get(thread) ?? 0) + 1);
         })().catch(async (error) => {
             if (String(error).includes("MESSAGE_SCOPE_CHANGED"))
                 this.denyScope();
@@ -676,6 +690,7 @@ export class MessageClient {
             this.channel?.close();
             this.watches.clear();
             this.windowEdges.clear();
+            this.completedSyncs.clear();
             this.allListeners.clear();
             this.accessListeners.clear();
             this.storage.close();

package/lib/runtime/readIndex.d.ts

@@ -127,6 +127,9 @@ export declare class IndexedDbReadIndex implements ReadIndexPersistence {
     constructor(factory?: IDBFactory, name?: string, storageScope?: string | undefined, migrateLegacy?: boolean, metadataOnly?: boolean);
     private transaction;
     private key;
+    /** Keyset pages avoid materializing a second, unbounded array of durable rows.
+     * Keep the caller's transaction so every page belongs to one consistent view. */
+    private readPages;
     private hydrate;
     private loadCurrent;
     private loadStored;

package/lib/runtime/readIndex.js

@@ -269,22 +269,33 @@ export class IndexedDbReadIndex {
         throw new Error("READ_STORAGE_UNAVAILABLE");
     }
     key(appId, profileId) { return this.storageScope === undefined ? [appId, profileId] : [appId, profileId, this.storageScope]; }
+    /** Keyset pages avoid materializing a second, unbounded array of durable rows.
+     * Keep the caller's transaction so every page belongs to one consistent view. */
+    async readPages(table, owner, key, visit) {
+        let after;
+        for (;;) {
+            const rows = await table.where(":id").between(after ?? [owner, Dexie.minKey], [owner, Dexie.maxKey], !after, true).limit(128).toArray();
+            for (const row of rows)
+                visit(row);
+            if (rows.length < 128)
+                return;
+            after = key(rows[rows.length - 1]);
+        }
+    }
     async hydrate(current, key) {
         if (current.normalized) {
             const owner = JSON.stringify(key);
-            const [threads, messages, positions] = await Promise.all([
-                this.threadRows.where("owner").equals(owner).toArray(),
-                this.messageRows.where("owner").equals(owner).toArray(),
-                this.positionRows.where("owner").equals(owner).toArray(),
-            ]);
             const byThread = new Map();
-            for (const row of messages) {
-                if (!byThread.has(row.thread))
-                    byThread.set(row.thread, new Map());
-                byThread.get(row.thread).set(row.id, row.value);
-            }
-            const byPosition = new Map(positions.map(row => [row.id, row]));
-            const byId = new Map(threads.map(row => [row.id, row]));
+            const byPosition = new Map(), byId = new Map();
+            await Promise.all([
+                this.readPages(this.threadRows, owner, row => [row.owner, row.id], row => byId.set(row.id, row)),
+                this.readPages(this.messageRows, owner, row => [row.owner, row.thread, row.id], row => {
+                    if (!byThread.has(row.thread))
+                        byThread.set(row.thread, new Map());
+                    byThread.get(row.thread).set(row.id, row.value);
+                }),
+                this.readPages(this.positionRows, owner, row => [row.owner, row.id], row => byPosition.set(row.id, row)),
+            ]);
             const { normalized: _normalized, threadOrder, ...state } = current;
             const result = { ...state, threads: (threadOrder ?? []).map(id => {
                     const row = byId.get(id);
@@ -494,8 +505,8 @@ export class IndexedDbReadIndex {
         // Cursors are the mutable cross-document view. Refresh their small rows,
         // while message metadata remains targeted; otherwise a later batch based
         // on an older snapshot could regress a different conversation's progress.
-        const allPositions = await this.positionRows.where("owner").equals(owner).toArray();
-        const positionById = new Map(allPositions.map(position => [position.id, position]));
+        const positionById = new Map();
+        await this.readPages(this.positionRows, owner, row => [row.owner, row.id], row => positionById.set(row.id, row));
         if (base.threads.some(thread => !positionById.has(thread.id)))
             return undefined;
         const positions = sourceIds.map(id => positionById.get(id));
@@ -538,7 +549,7 @@ export class IndexedDbReadIndex {
             await this.positionRows.bulkPut(writes);
         if (JSON.stringify(header.pending) !== JSON.stringify(result.pending) || JSON.stringify(header.observedReadIntents) !== JSON.stringify(result.observedReadIntents))
             await this.profiles.put({ ...header, pending: result.pending, observedReadIntents: result.observedReadIntents }, key);
-        const byId = new Map(allPositions.map(position => [position.id, position]));
+        const byId = new Map(positionById);
         result.threads.forEach(thread => byId.set(thread.id, thread));
         let changed = false;
         const threads = base.threads.map(thread => {

package/lib/runtime/socialReadClient.d.ts

@@ -57,6 +57,7 @@ export declare class SocialReadClient {
         limit?: number;
         before?: string;
         after?: string;
+        messageId?: string;
     }, signal?: AbortSignal): Promise<SocialMessagePage>;
     group(input: {
         groupId: string;

package/lib/runtime/socialReadClient.js

@@ -26,17 +26,21 @@ export class SocialReadClient {
     }
     async messagePage(input, signal) {
         this.requireTeam(input.teamId);
-        const limit = input.limit ?? 100;
+        const limit = input.limit ?? (input.messageId === undefined ? 100 : 1);
         if (!Number.isSafeInteger(limit) || limit < 1 || limit > 500 || (input.before !== undefined && input.after !== undefined))
             throw new SocialReadError(400, "INVALID_MESSAGE_PAGE");
+        if (input.messageId !== undefined && (!input.messageId || input.messageId.length > 256 || /[\u0000-\u001f\u007f]/.test(input.messageId) || limit !== 1 || input.before !== undefined || input.after !== undefined))
+            throw new SocialReadError(400, "INVALID_MESSAGE_LOOKUP");
         const value = await this.request("messages", { threadId: input.threadId, ...this.teamQuery(input.teamId), limit: String(limit),
-            ...(input.before === undefined ? {} : { before: input.before }), ...(input.after === undefined ? {} : { after: input.after }) }, signal);
+            ...(input.before === undefined ? {} : { before: input.before }), ...(input.after === undefined ? {} : { after: input.after }), ...(input.messageId === undefined ? {} : { messageId: input.messageId }) }, signal);
         const cursor = (token) => typeof token === "string" && /^mp1:\d+:[0-9a-f]{64}$/.test(token);
         if (!value || !Array.isArray(value.messages) || value.messages.length > limit || !cursor(value.checkpoint)
             || (value.nextBefore !== null && !cursor(value.nextBefore)) || typeof value.hasMoreChanges !== "boolean" || typeof value.resetRequired !== "boolean"
             || value.messages.some(row => row.appId !== this.options.appId || row.threadId !== input.threadId || row.teamId !== input.teamId || !row.messageId || !Number.isFinite(row.serverCreatedAt))
             || (value.resetRequired && (value.messages.length || value.hasMoreChanges || value.nextBefore !== null)))
             throw new SocialReadError(502, "INVALID_MESSAGE_PAGE_RESPONSE");
+        if (input.messageId !== undefined && (value.messages.some(row => row.messageId !== input.messageId) || value.nextBefore !== null || value.hasMoreChanges || value.resetRequired))
+            throw new SocialReadError(502, "INVALID_MESSAGE_LOOKUP_RESPONSE");
         return value;
     }
     group(input) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmate/chat-sdk",
-  "version": "0.12.0-next.52",
+  "version": "0.12.0-next.54",
   "description": "Cross-platform PMate chat input components, voice input primitives, and ASR helpers",
   "type": "module",
   "main": "./lib/index.js",