@pmate/chat-sdk 0.12.0-next.7 → 0.12.0-next.9

package/README.md

@@ -142,7 +142,9 @@ The browser entry point is `createChat` from `@pmate/chat-sdk/runtime`:
 ```ts
 const chat = createChat({ appId, accountId, profileId, teamId, token, onError })
 await chat.start()
-const page = await chat.getMessages(threadId, { limit: 50 })
+const page = await chat.getMessages(threadId)
+// SDK owns the page size and history boundary; hosts need not construct a cursor.
+const earlier = await chat.getMessages(threadId, { earlier: true })
 // After an authoritative mutation (e.g. history assignment), await reconciliation.
 // Concurrent refreshes share transport; errors do not masquerade as fresh cache.
 const reconciled = await chat.getMessages(threadId, { refresh: true })

package/lib/runtime/chatSession.d.ts

@@ -43,6 +43,8 @@ export declare class ChatSession<T extends StoredMessage> {
     private sender;
     private listeners;
     private snapshots;
+    private historyEdges;
+    private earlierReads;
     private off;
     private globalListeners;
     private globalSnapshot?;
@@ -61,9 +63,12 @@ export declare class ChatSession<T extends StoredMessage> {
             timestamp: number;
             id: string;
         };
+        earlier?: boolean;
         all?: boolean;
         refresh?: boolean;
     }): Promise<MessageSnapshot<T>>;
+    private rememberHistoryEdge;
+    private readEarlier;
     private readAll;
     sendMessage(threadId: string, input: {
         to: string;

package/lib/runtime/chatSession.js

@@ -15,6 +15,8 @@ export class ChatSession {
     sender;
     listeners = new Map();
     snapshots = new Map();
+    historyEdges = new Map();
+    earlierReads = new Map();
     off = [];
     globalListeners = new Set();
     globalSnapshot;
@@ -37,7 +39,7 @@ export class ChatSession {
         this.messages = new MessageClient(options.messages);
         this.connection = options.sharedConnection ?? new ChatClient(options.connection);
         this.reading = new ReadingClient({ ...options.reading, storageScope: JSON.stringify([scope.accountId, scope.teamId]) });
-        this.readers = new MessageReadersClient({ appId: scope.appId, profileId: scope.profileId, token: options.reading.sessionToken, hubHttpUrl: options.reading.hubHttpUrl, fetch: options.reading.fetch });
+        this.readers = new MessageReadersClient({ appId: scope.appId, profileId: scope.profileId, token: options.reading.sessionToken, scope, onError: options.onError, hubHttpUrl: options.reading.hubHttpUrl, fetch: options.reading.fetch });
         this.sender = new DurableChatSender(this.connection, scope, options.onError);
         this.catchUp = new WindowedTasks(1000, error => { if (!this.closed)
             options.onError(error); });
@@ -81,6 +83,11 @@ export class ChatSession {
         throw new Error("CHAT_SESSION_CLOSED"); }
     async getMessages(threadId, options = {}) {
         this.assertOpen();
+        if (options.earlier) {
+            if (options.before || options.all || options.limit !== undefined || options.refresh)
+                throw new Error("INVALID_MESSAGE_QUERY");
+            return this.readEarlier(threadId);
+        }
         if (options.all && (options.before || options.limit !== undefined))
             throw new Error("INVALID_MESSAGE_QUERY");
         // Explicit authoritative changes (for example history assignment) can invalidate
@@ -92,8 +99,37 @@ export class ChatSession {
         }
         const page = await (options.before ? this.messages.earlier(threadId, options.before, options.limit) : this.messages.read(threadId, options.limit));
         await this.sender.confirm(page.messages.map(message => message.id));
+        const edge = this.historyEdges.get(threadId);
+        if (!options.before && page.complete && (!edge || edge.version !== page.resetVersion))
+            this.rememberHistoryEdge(threadId, page);
         return page;
     }
+    rememberHistoryEdge(threadId, page) {
+        const first = page.messages[0];
+        this.historyEdges.set(threadId, { before: first ? { timestamp: first.timestamp, id: first.id } : undefined, version: page.resetVersion, hasEarlier: page.hasEarlier });
+    }
+    readEarlier(threadId) {
+        const running = this.earlierReads.get(threadId);
+        if (running)
+            return running;
+        const task = (async () => {
+            const recent = await this.getMessages(threadId);
+            if (!recent.complete)
+                throw new Error("MESSAGE_WINDOW_INCOMPLETE");
+            const edge = this.historyEdges.get(threadId);
+            if (!edge.hasEarlier)
+                return { ...recent, messages: [], hasEarlier: false };
+            if (!edge.before)
+                throw new Error("MESSAGE_SYNC_NO_PROGRESS");
+            const page = await this.getMessages(threadId, { before: edge.before });
+            this.assertOpen();
+            this.rememberHistoryEdge(threadId, page);
+            return page;
+        })().finally(() => { if (this.earlierReads.get(threadId) === task)
+            this.earlierReads.delete(threadId); });
+        this.earlierReads.set(threadId, task);
+        return task;
+    }
     async readAll(threadId) {
         for (let attempt = 0; attempt < 3; attempt++) {
             const pages = [];
@@ -231,6 +267,8 @@ export class ChatSession {
             this.listeners.clear();
             this.globalListeners.clear();
             this.snapshots.clear();
+            this.historyEdges.clear();
+            this.earlierReads.clear();
             this.globalSnapshot = undefined;
         })();
     }

package/lib/runtime/messageReaders.d.ts

@@ -1,3 +1,4 @@
+import { type MessageScope } from "./messageStore.js";
 export type MessageReadersPage = {
     appId: string;
     threadId: string;
@@ -21,6 +22,8 @@ export type MessageReadersOptions = {
     token: string;
     hubHttpUrl: string;
     fetch?: typeof fetch;
+    scope?: MessageScope;
+    onError?: (error: unknown) => void;
 };
 export declare class MessageReadersError extends Error {
     readonly status: number;
@@ -32,8 +35,12 @@ export declare class MessageReadersClient {
     private options;
     private pending;
     private lifetime;
+    private cache?;
+    private revoked;
+    private generation;
     constructor(options: MessageReadersOptions);
     getReaders(query: MessageReadersQuery, signal?: AbortSignal): Promise<MessageReadersPage>;
+    private cachedRequest;
     private request;
     close(): void;
 }

package/lib/runtime/messageReaders.js

@@ -1,3 +1,5 @@
+import { IndexedDbResponseCache } from "./responseCache.js";
+import { messageScopeKey } from "./messageStore.js";
 export class MessageReadersError extends Error {
     status;
     forbidden;
@@ -12,7 +14,17 @@ export class MessageReadersClient {
     options;
     pending = new Map();
     lifetime = new AbortController();
-    constructor(options) { this.options = { ...options }; }
+    cache;
+    revoked = false;
+    generation = 0;
+    constructor(options) {
+        this.options = { ...options };
+        if (options.scope) {
+            if (options.scope.appId !== options.appId || options.scope.profileId !== options.profileId)
+                throw new Error("MESSAGE_READERS_SCOPE_MISMATCH");
+            this.cache = new IndexedDbResponseCache(messageScopeKey(options.scope));
+        }
+    }
     getReaders(query, signal) {
         if (this.lifetime.signal.aborted)
             return Promise.reject(new Error("MESSAGE_READERS_CLOSED"));
@@ -24,7 +36,7 @@ export class MessageReadersClient {
         const key = JSON.stringify([input.threadId, input.messageId, input.afterProfileId, input.revision, input.limit]);
         let task = this.pending.get(key);
         if (!task) {
-            task = this.request(input).finally(() => { if (this.pending.get(key) === task)
+            task = this.cachedRequest(input, key).finally(() => { if (this.pending.get(key) === task)
                 this.pending.delete(key); });
             this.pending.set(key, task);
         }
@@ -37,6 +49,47 @@ export class MessageReadersClient {
             task.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
         });
     }
+    async cachedRequest(input, key) {
+        // Keep only the standard SDK window. Arbitrary page sizes must not multiply
+        // durable cache entries. Revision is part of the key, so changed counts do
+        // not reuse a page from a previous membership/read projection.
+        const cache = input.limit === 50 ? this.cache : undefined;
+        if (!cache)
+            return this.request(input);
+        const stored = await cache.read(key).catch(error => { this.options.onError?.(error); return undefined; });
+        if (this.lifetime.signal.aborted)
+            throw new Error("MESSAGE_READERS_CLOSED");
+        const generation = this.generation;
+        const cached = this.revoked ? undefined : stored?.cached;
+        if (cached && (Date.now() - cached.time < 5000 || (typeof navigator !== "undefined" && navigator.onLine === false)))
+            return structuredClone(cached.value);
+        let value;
+        try {
+            value = await this.request(input);
+        }
+        catch (error) {
+            if (error instanceof MessageReadersError && error.forbidden) {
+                this.revoked = true;
+                this.generation++;
+                await this.cache?.invalidate().catch(failure => this.options.onError?.(failure));
+                throw error;
+            }
+            if (cached && !this.revoked && generation === this.generation && !this.lifetime.signal.aborted && (error instanceof TypeError || (error instanceof MessageReadersError && error.status >= 500)))
+                return structuredClone(cached.value);
+            throw error;
+        }
+        if (generation !== this.generation)
+            throw new Error("MESSAGE_READERS_INVALIDATED");
+        this.revoked = false;
+        if (value.resetRequired)
+            await cache?.invalidate().catch(error => this.options.onError?.(error));
+        else if (stored)
+            await cache?.write(key, value, stored.epoch).catch(error => { if (String(error).includes("RESPONSE_CACHE_INVALIDATED"))
+                throw error; this.options.onError?.(error); });
+        if (this.lifetime.signal.aborted)
+            throw new Error("MESSAGE_READERS_CLOSED");
+        return value;
+    }
     async request(input) {
         const { token, fetch: fetcher, hubHttpUrl, appId, profileId } = this.options;
         const controller = new AbortController();
@@ -67,5 +120,5 @@ export class MessageReadersClient {
             this.lifetime.signal.removeEventListener("abort", cancel);
         }
     }
-    close() { this.lifetime.abort(); this.pending.clear(); }
+    close() { this.lifetime.abort(); this.pending.clear(); void this.cache?.close().catch(error => this.options.onError?.(error)); }
 }

package/lib/runtime/readCounts.d.ts

@@ -1,3 +1,4 @@
+import { type MessageScope } from "./messageStore.js";
 export type ReadCountsResult = {
     appId: string;
     threadId: string;
@@ -11,6 +12,7 @@ export type ReadCountsOptions = {
     clientInstanceId: string;
     hubHttpUrl: string;
     fetch?: typeof fetch;
+    scope?: MessageScope;
     onChange: (value: ReadCountsResult) => void;
     onError?: (error: unknown) => void;
 };
@@ -31,7 +33,15 @@ export declare class ReadCountsClient {
     private subscribed;
     private subscriptionDenied;
     private subscriptionPending?;
+    private cache?;
+    private lastResult?;
+    private publish;
+    private revoked;
+    private accessVersion;
+    private requestedRevision;
+    private force;
     constructor(options: ReadCountsOptions);
+    private denyCache;
     private post;
     private subscription;
     private renew;

package/lib/runtime/readCounts.js

@@ -1,3 +1,5 @@
+import { IndexedDbResponseCache } from "./responseCache.js";
+import { messageScopeKey } from "./messageStore.js";
 let subscriptionSequence = 0;
 function nextSubscriptionSequence() { subscriptionSequence = Math.max(Date.now() * 1000, subscriptionSequence + 1); return subscriptionSequence; }
 /** One active conversation; fixed event window, bounded batches, no count polling. */
@@ -17,8 +19,31 @@ export class ReadCountsClient {
     subscribed = false;
     subscriptionDenied = false;
     subscriptionPending;
+    cache;
+    lastResult;
+    publish(value) {
+        if (JSON.stringify(value) === JSON.stringify(this.lastResult))
+            return;
+        this.lastResult = value;
+        this.options.onChange(value);
+    }
+    revoked = false;
+    accessVersion = 0;
+    requestedRevision = -1;
+    force = false;
     constructor(options) {
         this.options = options;
+        if (options.scope) {
+            if (options.scope.appId !== options.appId || options.scope.profileId !== options.profileId)
+                throw new Error("READ_COUNTS_SCOPE_MISMATCH");
+            this.cache = new IndexedDbResponseCache(messageScopeKey(options.scope));
+        }
+    }
+    denyCache() {
+        this.revoked = true;
+        this.accessVersion++;
+        this.lastResult = undefined;
+        void this.cache?.invalidate().catch(error => this.options.onError?.(error));
     }
     async post(path, body, signal) {
         const response = await (this.options.fetch ?? fetch)(`${this.options.hubHttpUrl.replace(/\/$/, "")}${path}`, { method: "POST", headers: { authorization: `Bearer ${this.options.token}`, "content-type": "application/json" }, body: JSON.stringify(body), signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(8000)]) : AbortSignal.timeout(8000), redirect: "error" });
@@ -33,7 +58,7 @@ export class ReadCountsClient {
         return this.post("/api/social/reading/subscription", { appId: this.options.appId, profileId: this.options.profileId, threadId, clientInstanceId: this.options.clientInstanceId, sequence: nextSubscriptionSequence(), release });
     }
     renew() {
-        if (!this.thread || this.closed || this.subscriptionDenied)
+        if (!this.thread || this.closed || this.subscriptionDenied || (typeof navigator !== "undefined" && navigator.onLine === false))
             return;
         const threadId = this.thread, generation = this.generation;
         if (this.subscriptionPending?.generation === generation)
@@ -56,6 +81,7 @@ export class ReadCountsClient {
             this.subscribed = false;
             if (/READ_COUNTS_HTTP_(401|403)/.test(String(error))) {
                 this.subscriptionDenied = true;
+                this.denyCache();
                 clearInterval(this.heartbeat);
                 this.heartbeat = undefined;
             }
@@ -83,9 +109,12 @@ export class ReadCountsClient {
         clearTimeout(this.timer);
         clearInterval(this.heartbeat);
         this.timer = undefined;
+        this.lastResult = undefined;
         this.thread = threadId;
         this.ids = ids;
         this.revision = -1;
+        this.requestedRevision = -1;
+        this.force = false;
         this.dirty = false;
         this.retries = 0;
         this.subscribed = false;
@@ -104,11 +133,13 @@ export class ReadCountsClient {
             throw new Error("INVALID_READ_COUNTS_EVENT");
         if (threadId !== this.thread || revision <= this.revision || this.closed)
             return;
+        this.requestedRevision = Math.max(this.requestedRevision, revision);
         this.schedule(3000);
     }
     reconnect() {
         if (!this.thread || this.closed)
             return;
+        this.force = true;
         this.subscribed = false;
         this.subscriptionDenied = false;
         this.renew();
@@ -137,20 +168,44 @@ export class ReadCountsClient {
         let retryDelay;
         const controller = new AbortController();
         this.controller = controller;
+        const accessVersion = this.accessVersion, force = this.force;
+        this.force = false;
+        const key = JSON.stringify(["counts", threadId, [...ids].sort()]);
         try {
+            const stored = this.cache ? await this.cache.read(key).catch(error => { this.options.onError?.(error); return undefined; }) : undefined;
+            if (generation !== this.generation || this.closed || accessVersion !== this.accessVersion)
+                return;
+            const cached = this.revoked || (stored?.cached && stored.cached.value.revision < this.revision) ? undefined : stored?.cached;
+            if (cached) {
+                this.revision = cached.value.revision;
+                this.publish(cached.value);
+                const offline = typeof navigator !== "undefined" && navigator.onLine === false;
+                if (offline || (!force && this.requestedRevision <= this.revision && Date.now() - cached.time < 5000))
+                    return;
+            }
             const value = await this.post("/api/social/reading/counts", { appId: this.options.appId, profileId: this.options.profileId, threadId, messageIds: ids }, controller.signal);
-            if (generation !== this.generation || this.closed)
+            if (generation !== this.generation || this.closed || accessVersion !== this.accessVersion)
                 return;
             if (value?.appId !== this.options.appId || value.threadId !== threadId || !Number.isSafeInteger(value.revision) || value.revision < 0 || !value.counts || typeof value.counts !== "object" || ids.some(id => !Number.isSafeInteger(value.counts[id]) || value.counts[id] < 0) || Object.keys(value.counts).some(id => !ids.includes(id)))
                 throw new Error("INVALID_READ_COUNTS_RESULT");
+            if (value.revision < this.revision)
+                return;
             this.retries = 0;
+            this.revoked = false;
+            if (stored)
+                await this.cache?.write(key, value, stored.epoch).catch(error => { if (String(error).includes("RESPONSE_CACHE_INVALIDATED"))
+                    throw error; this.options.onError?.(error); });
+            if (generation !== this.generation || this.closed || accessVersion !== this.accessVersion)
+                return;
             this.revision = value.revision;
-            this.options.onChange(value);
+            this.publish(value);
             if (!this.subscribed)
                 this.renew();
         }
         catch (error) {
             if (!controller.signal.aborted && generation === this.generation && !this.closed) {
+                if (/READ_COUNTS_HTTP_(401|403)/.test(String(error)))
+                    this.denyCache();
                 this.options.onError?.(error);
                 if (!/READ_COUNTS_HTTP_4\d\d|INVALID_READ_COUNTS/.test(String(error)) && this.retries < 3) {
                     retryDelay = 1000 * 2 ** this.retries++;
@@ -178,5 +233,6 @@ export class ReadCountsClient {
         if (old)
             void this.subscription(old, true).catch(() => { });
         this.thread = undefined;
+        void this.cache?.close().catch(error => this.options.onError?.(error));
     }
 }

package/lib/runtime/responseCache.d.ts

@@ -0,0 +1,27 @@
+/** Small response windows, isolated by identity. Epochs fence late writes after
+ * access withdrawal. No localStorage or synchronous writes on the read path. */
+export declare class IndexedDbResponseCache<T> {
+    private scope;
+    private db;
+    private rows;
+    private epochs;
+    private pending;
+    private tasks;
+    private running?;
+    private closed;
+    constructor(scope: string, options?: {
+        indexedDB?: IDBFactory;
+        name?: string;
+    });
+    read(key: string): Promise<{
+        epoch: number;
+        cached: {
+            value: T;
+            time: number;
+        } | undefined;
+    }>;
+    write(key: string, value: T, epoch: number): Promise<void>;
+    invalidate(): Promise<void>;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}

package/lib/runtime/responseCache.js

@@ -0,0 +1,103 @@
+import { Dexie } from "dexie";
+import { WindowedTasks } from "./coalescer.js";
+/** Small response windows, isolated by identity. Epochs fence late writes after
+ * access withdrawal. No localStorage or synchronous writes on the read path. */
+export class IndexedDbResponseCache {
+    scope;
+    db;
+    rows;
+    epochs;
+    pending = [];
+    tasks = new WindowedTasks(16, () => { });
+    running;
+    closed = false;
+    constructor(scope, options = {}) {
+        this.scope = scope;
+        this.db = new Dexie(options.name ?? "pmate-chat-response-windows", { indexedDB: options.indexedDB ?? globalThis.indexedDB, IDBKeyRange: globalThis.IDBKeyRange });
+        this.db.version(1).stores({ windows: "[scope+key],scope", epochs: "scope" });
+        this.rows = this.db.table("windows");
+        this.epochs = this.db.table("epochs");
+    }
+    async read(key) {
+        if (this.closed)
+            throw new Error("RESPONSE_CACHE_CLOSED");
+        return this.db.transaction("r", this.rows, this.epochs, async () => {
+            const epoch = (await this.epochs.get(this.scope))?.epoch ?? 0;
+            const row = await this.rows.get([this.scope, key]);
+            return { epoch, cached: row?.epoch === epoch ? { value: row.value, time: row.time } : undefined };
+        });
+    }
+    write(key, value, epoch) {
+        if (this.closed)
+            return Promise.reject(new Error("RESPONSE_CACHE_CLOSED"));
+        const copy = structuredClone(value), bytes = new TextEncoder().encode(JSON.stringify(copy)).byteLength;
+        // Count in-flight data as well as queued data; requests cannot create an
+        // unbounded backlog while IndexedDB is blocked by another tab.
+        if (bytes > 65536 || this.pending.length >= 128 || this.pending.reduce((n, w) => n + w.row.bytes, 0) + bytes > 1048576)
+            return Promise.reject(new Error("RESPONSE_CACHE_BACKPRESSURE"));
+        const promise = new Promise((resolve, reject) => this.pending.push({ row: { scope: this.scope, key, epoch, time: Date.now(), bytes, value: copy }, resolve, reject }));
+        this.tasks.schedule("write", () => this.flush());
+        return promise;
+    }
+    async invalidate() {
+        if (this.closed)
+            throw new Error("RESPONSE_CACHE_CLOSED");
+        await this.db.transaction("rw", this.rows, this.epochs, async () => {
+            const epoch = ((await this.epochs.get(this.scope))?.epoch ?? 0) + 1;
+            await this.epochs.put({ scope: this.scope, epoch });
+            await this.rows.where("scope").equals(this.scope).delete();
+        });
+    }
+    async flush() {
+        if (this.running) {
+            await this.running;
+            if (this.pending.length)
+                return this.flush();
+            return;
+        }
+        const batch = [...this.pending];
+        if (!batch.length)
+            return;
+        const task = (async () => {
+            try {
+                const accepted = await this.db.transaction("rw", this.rows, this.epochs, async () => {
+                    const epoch = (await this.epochs.get(this.scope))?.epoch ?? 0;
+                    const valid = batch.filter(write => write.row.epoch === epoch);
+                    const unique = new Map(valid.map(write => [write.row.key, write.row]));
+                    await this.rows.bulkPut([...unique.values()]);
+                    const stored = await this.rows.where("scope").equals(this.scope).toArray();
+                    stored.sort((a, b) => b.time - a.time || a.key.localeCompare(b.key));
+                    let bytes = 0;
+                    const evicted = [];
+                    stored.forEach((row, index) => { bytes += row.bytes; if (index >= 256 || bytes > 1048576)
+                        evicted.push([this.scope, row.key]); });
+                    await this.rows.bulkDelete(evicted);
+                    return new Set(valid);
+                });
+                batch.forEach(write => accepted.has(write) ? write.resolve() : write.reject(new Error("RESPONSE_CACHE_INVALIDATED")));
+            }
+            catch (error) {
+                batch.forEach(write => write.reject(error));
+                throw error;
+            }
+            finally {
+                this.pending.splice(0, batch.length);
+            }
+        })().finally(() => { if (this.running === task)
+            this.running = undefined; });
+        this.running = task;
+        return task;
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.tasks.close();
+        try {
+            await this.flush();
+        }
+        finally {
+            this.db.close();
+        }
+    }
+}

package/package.json

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