@pmate/chat-sdk 0.12.0-next.6 → 0.12.0-next.60

package/lib/runtime/responseCache.js

@@ -0,0 +1,230 @@
+import { Dexie } from "dexie";
+import { WindowedTasks } from "./coalescer.js";
+export function isResponseCacheAuthorityError(error) {
+    return /RESPONSE_CACHE_(ACCESS_REVOKED|SCOPE_CHANGED|INVALIDATED)/.test(String(error));
+}
+export async function assertResponseCacheAccess(access, expectedVersion) {
+    if (!access)
+        return undefined;
+    const current = await access();
+    if (!current.allowed)
+        throw new Error("RESPONSE_CACHE_ACCESS_REVOKED");
+    if (expectedVersion !== undefined && current.version !== expectedVersion)
+        throw new Error("RESPONSE_CACHE_SCOPE_CHANGED");
+    return current.version;
+}
+/** 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;
+    options;
+    db;
+    rows;
+    epochs;
+    pending = [];
+    tasks = new WindowedTasks(16, () => { });
+    running;
+    invalidations = new Set();
+    closed = false;
+    closing;
+    constructor(scope, options = {}) {
+        this.scope = scope;
+        this.options = options;
+        for (const [value, max] of [[options.recordBytes ?? 65536, 1048576], [options.entries ?? 256, 256], [options.batchRecords ?? 128, 128]])
+            if (!Number.isSafeInteger(value) || value < 1 || value > max)
+                throw new Error("INVALID_RESPONSE_CACHE_LIMIT");
+        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");
+    }
+    /** Resolve shared message-scope authority before opening our transaction.
+     * A newer authority version retires response windows exactly once; delayed
+     * callers can never roll the authority backwards or delete recovered data. */
+    async synchronizeAccess() {
+        if (!this.options.access)
+            return;
+        const access = await this.options.access();
+        const stored = await this.epochs.get(this.scope);
+        const storedVersion = stored?.accessVersion ?? 0;
+        if (access.version < storedVersion)
+            throw new Error("RESPONSE_CACHE_SCOPE_CHANGED");
+        // Ordinary cache reads must not take an IndexedDB write lock. Only an
+        // authority transition needs the atomic epoch bump and range deletion.
+        if (access.version > storedVersion)
+            await this.db.transaction("rw", this.rows, this.epochs, async () => {
+                const current = await this.epochs.get(this.scope);
+                const version = current?.accessVersion ?? 0;
+                if (access.version < version)
+                    throw new Error("RESPONSE_CACHE_SCOPE_CHANGED");
+                if (access.version > version) {
+                    await this.epochs.put({ scope: this.scope, epoch: (current?.epoch ?? 0) + 1, accessVersion: access.version });
+                    await this.rows.where("scope").equals(this.scope).delete();
+                }
+            });
+        if (!access.allowed)
+            throw new Error("RESPONSE_CACHE_ACCESS_REVOKED");
+    }
+    async read(key) {
+        if (this.closed)
+            throw new Error("RESPONSE_CACHE_CLOSED");
+        await this.synchronizeAccess();
+        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 };
+        });
+    }
+    /** Key-only callers can share one bounded metadata read transaction. */
+    async readMany(keys) {
+        if (this.closed)
+            throw new Error("RESPONSE_CACHE_CLOSED");
+        if (keys.length > 128)
+            throw new Error("RESPONSE_CACHE_SELECTION_TOO_LARGE");
+        await this.synchronizeAccess();
+        return this.db.transaction("r", this.rows, this.epochs, async () => {
+            const epoch = (await this.epochs.get(this.scope))?.epoch ?? 0, unique = [...new Set(keys)];
+            const rows = await this.rows.bulkGet(unique.map(key => [this.scope, key]));
+            return new Map(unique.map((key, index) => { const row = rows[index]; return [key, { epoch, cached: row?.epoch === epoch ? { value: row.value, time: row.time } : undefined }]; }));
+        });
+    }
+    write(key, value, epoch, expectedRevision) {
+        if (this.closed)
+            return Promise.reject(new Error("RESPONSE_CACHE_CLOSED"));
+        if (expectedRevision !== undefined && !this.options.revision)
+            return Promise.reject(new Error("RESPONSE_CACHE_REVISION_UNAVAILABLE"));
+        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 > (this.options.recordBytes ?? 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 }, expectedRevision, resolve, reject }));
+        this.tasks.schedule("write", () => this.flush());
+        return promise;
+    }
+    /** Idempotent shared-scope retirement: an old cleanup cannot erase windows
+     * created after the same authority version was already recovered. */
+    retire(version) {
+        if (this.closed)
+            return Promise.reject(new Error("RESPONSE_CACHE_CLOSED"));
+        if (!Number.isSafeInteger(version) || version < 1)
+            return Promise.reject(new Error("INVALID_RESPONSE_SCOPE_VERSION"));
+        const task = this.db.transaction("rw", this.rows, this.epochs, async () => {
+            const current = await this.epochs.get(this.scope);
+            if ((current?.accessVersion ?? 0) >= version)
+                return;
+            await this.epochs.put({ scope: this.scope, epoch: (current?.epoch ?? 0) + 1, accessVersion: version });
+            await this.rows.where("scope").equals(this.scope).delete();
+        });
+        this.invalidations.add(task);
+        return task.finally(() => this.invalidations.delete(task));
+    }
+    invalidate() {
+        if (this.closed)
+            return Promise.reject(new Error("RESPONSE_CACHE_CLOSED"));
+        const task = (async () => {
+            await this.db.transaction("rw", this.rows, this.epochs, async () => {
+                const current = await this.epochs.get(this.scope);
+                const epoch = (current?.epoch ?? 0) + 1;
+                await this.epochs.put({ scope: this.scope, epoch, accessVersion: current?.accessVersion });
+                await this.rows.where("scope").equals(this.scope).delete();
+            });
+        })();
+        this.invalidations.add(task);
+        return task.finally(() => this.invalidations.delete(task));
+    }
+    async flush() {
+        if (this.running) {
+            await this.running;
+            if (this.pending.length)
+                return this.flush();
+            return;
+        }
+        if (!this.pending.length)
+            return;
+        const task = (async () => {
+            let failed = false, failure;
+            // Each batch commits and resolves independently. A configured smaller
+            // batch still drains all accepted requests, including during close.
+            while (this.pending.length) {
+                const batch = this.pending.slice(0, this.options.batchRecords ?? 128);
+                try {
+                    await this.synchronizeAccess();
+                    const outcome = 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 conditional = valid.filter(write => write.expectedRevision !== undefined);
+                        const keys = [...new Set(conditional.map(write => write.row.key))];
+                        const current = conditional.length ? await this.rows.bulkGet(keys.map(key => [this.scope, key])) : [];
+                        const projected = new Map(keys.map((key, index) => [key, current[index]?.epoch === epoch ? current[index] : undefined]));
+                        const accepted = new Set(), changed = new Set(), unique = new Map();
+                        for (const write of valid) {
+                            if (write.expectedRevision !== undefined) {
+                                const previous = projected.get(write.row.key);
+                                const revision = previous ? this.options.revision(previous.value) : null;
+                                if (revision !== write.expectedRevision) {
+                                    // Another document may have already committed this exact
+                                    // revision; it is an idempotent success, never an overwrite.
+                                    if (revision === this.options.revision(write.row.value) && JSON.stringify(previous.value) === JSON.stringify(write.row.value))
+                                        accepted.add(write);
+                                    else
+                                        changed.add(write);
+                                    continue;
+                                }
+                            }
+                            unique.set(write.row.key, write.row);
+                            projected.set(write.row.key, write.row);
+                            accepted.add(write);
+                        }
+                        if (unique.size) {
+                            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 >= (this.options.entries ?? 256) || bytes > 1048576)
+                                evicted.push([this.scope, row.key]); });
+                            if (evicted.length)
+                                await this.rows.bulkDelete(evicted);
+                        }
+                        return { accepted, changed };
+                    });
+                    for (const write of batch) {
+                        if (outcome.accepted.has(write))
+                            write.resolve();
+                        else
+                            write.reject(new Error(outcome.changed.has(write) ? "RESPONSE_CACHE_CHANGED" : "RESPONSE_CACHE_INVALIDATED"));
+                    }
+                }
+                catch (error) {
+                    batch.forEach(write => write.reject(error));
+                    if (!failed)
+                        failure = error;
+                    failed = true;
+                }
+                finally {
+                    this.pending.splice(0, batch.length);
+                }
+            }
+            if (failed)
+                throw failure;
+        })().finally(() => { if (this.running === task)
+            this.running = undefined; });
+        this.running = task;
+        return task;
+    }
+    close() {
+        if (this.closing)
+            return this.closing;
+        this.closed = true;
+        this.tasks.close();
+        return this.closing = (async () => {
+            try {
+                await Promise.all([this.flush(), ...this.invalidations]);
+            }
+            finally {
+                this.db.close();
+            }
+        })();
+    }
+}

package/lib/runtime/socialReadClient.d.ts

@@ -22,6 +22,7 @@ export type SocialGroup = {
     title: string;
     avatar?: string | null;
     revision: string;
+    versionNumber?: number;
 };
 export type SocialRelationship = {
     appId: string;
@@ -57,11 +58,12 @@ export declare class SocialReadClient {
         limit?: number;
         before?: string;
         after?: string;
+        messageId?: string;
     }, signal?: AbortSignal): Promise<SocialMessagePage>;
     group(input: {
         groupId: string;
         teamId?: string;
-    }): Promise<SocialGroup>;
+    }, signal?: AbortSignal): Promise<SocialGroup>;
     relationship(input: {
         peerId: string;
         teamId?: string;

package/lib/runtime/socialReadClient.js

@@ -26,22 +26,26 @@ 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) {
+    group(input, signal) {
         this.requireTeam(input.teamId);
-        return this.request("group", { groupId: input.groupId, ...this.teamQuery(input.teamId) });
+        return this.request("group", { groupId: input.groupId, ...this.teamQuery(input.teamId) }, signal);
     }
     relationship(input) {
         this.requireTeam(input.teamId);

package/lib/runtime/voiceUpload.d.ts

@@ -0,0 +1,2 @@
+/** The SDK owns upload I/O; hosts configure only their service endpoint. */
+export declare function voiceUploader(profileId: string, endpoint?: string, fetcher?: typeof fetch): (blob: Blob, signal: AbortSignal) => Promise<string>;

package/lib/runtime/voiceUpload.js

@@ -0,0 +1,27 @@
+import { isOffline } from "./connectivity.js";
+/** The SDK owns upload I/O; hosts configure only their service endpoint. */
+export function voiceUploader(profileId, endpoint = "https://upload-fc.pmate.chat", fetcher = globalThis.fetch) {
+    return async (blob, signal) => {
+        if (signal.aborted)
+            throw new DOMException("Upload aborted", "AbortError");
+        if (isOffline())
+            throw new Error("VOICE_UPLOAD_OFFLINE");
+        const bytes = new Uint8Array(await blob.arrayBuffer());
+        if (signal.aborted)
+            throw new DOMException("Upload aborted", "AbortError");
+        let binary = "";
+        for (let offset = 0; offset < bytes.length; offset += 32768)
+            binary += String.fromCharCode(...bytes.subarray(offset, offset + 32768));
+        const extension = blob.type.includes("mp4") ? "m4a" : blob.type.includes("mpeg") ? "mp3" : "webm";
+        const type = extension === "m4a" ? "audio/mp4" : extension === "mp3" ? "audio/mpeg" : "audio/webm";
+        if (isOffline())
+            throw new Error("VOICE_UPLOAD_OFFLINE");
+        const response = await fetcher(`${endpoint.replace(/\/+$/, "")}/file`, { method: "POST", signal, headers: { "Content-Type": "application/json", "x-file-content-type": type }, body: JSON.stringify({ user: profileId, base64: btoa(binary), filename: `voice-${Date.now()}.${extension}` }) });
+        if (!response.ok)
+            throw new Error("VOICE_UPLOAD_FAILED");
+        const result = await response.json();
+        if (typeof result.data !== "string" || !result.data)
+            throw new Error("VOICE_UPLOAD_FAILED");
+        return result.data;
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmate/chat-sdk",
-  "version": "0.12.0-next.6",
+  "version": "0.12.0-next.60",
   "description": "Cross-platform PMate chat input components, voice input primitives, and ASR helpers",
   "type": "module",
   "main": "./lib/index.js",
@@ -19,6 +19,11 @@
       "import": "./lib/index.js",
       "default": "./lib/index.js"
     },
+    "./bootstrap": {
+      "types": "./lib/runtime/messageLaunch.d.ts",
+      "import": "./lib/runtime/messageLaunch.js",
+      "default": "./lib/runtime/messageLaunch.js"
+    },
     "./runtime": {
       "types": "./lib/runtime/index.d.ts",
       "import": "./lib/runtime/index.js",