@pmate/chat-sdk 0.12.0-next.8 → 0.12.0-next.81

package/lib/runtime/readSync.js

@@ -1,4 +1,4 @@
-import { applyReadChange, ReadSyncGap, createReadIndex, installReadSnapshot } from "./readIndex.js";
+import { readingMetadata, resolveObservedReads, assertReadIndexVersions, applyReadChange, ReadSyncGap, createReadIndex, installReadSnapshot } from "./readIndex.js";
 /** Keeps local operations until an authoritative projection covers them. */
 export class ReadSyncClient {
     options;
@@ -9,8 +9,15 @@ export class ReadSyncClient {
         this.options = options;
     }
     async loadLocal() {
-        return await this.options.persistence.load(this.options.appId, this.options.profileId)
-            ?? createReadIndex(this.options.appId, this.options.profileId);
+        const { appId, profileId, persistence, metadataOnly } = this.options;
+        const state = await persistence.load(appId, profileId) ?? createReadIndex(appId, profileId);
+        const normalize = (current) => {
+            const next = metadataOnly ? readingMetadata(current) : current;
+            return next.observedReadIntents?.length ? resolveObservedReads(next) : next;
+        };
+        if (normalize(state) === state)
+            return state;
+        return persistence.update(appId, profileId, normalize);
     }
     stop() { this.controller.abort(); }
     synchronize() {
@@ -33,7 +40,7 @@ export class ReadSyncClient {
                 ...init, signal: timeout.signal, headers: { ...init.headers, authorization: `Bearer ${this.options.sessionToken}` },
             });
             if (!response.ok)
-                throw new Error(`READ_SYNC_HTTP_${response.status}`);
+                throw Object.assign(new Error(`READ_SYNC_HTTP_${response.status}`), { status: response.status });
             const envelope = await response.json();
             if (envelope.success !== true || envelope.data === undefined)
                 throw new Error("INVALID_READ_SYNC_RESPONSE");
@@ -46,7 +53,9 @@ export class ReadSyncClient {
     }
     async run() {
         const { appId, profileId, persistence } = this.options;
-        const current = await this.loadLocal();
+        const loaded = persistence.loadVersioned ? await persistence.loadVersioned(appId, profileId) : { state: await persistence.load(appId, profileId), versions: {} };
+        const current = loaded.state ?? createReadIndex(appId, profileId);
+        const versions = loaded.versions;
         // Ordinary reads are monotonic: only the furthest position per thread needs
         // sending. Keep every original operation in storage until the projection
         // confirms it, and never rewrite an operation ID's payload during retries.
@@ -60,6 +69,8 @@ export class ReadSyncClient {
         }
         const outgoing = current.pending.filter(operation => operation.explicitReadMessageIds.length || operation.readThroughSeq <= 0 || latest.get(operation.threadId) === operation);
         for (const operation of outgoing) {
+            if (persistence.loadVersions)
+                assertReadIndexVersions(versions, await persistence.loadVersions(appId, profileId));
             const receipt = await this.request("/api/social/reading", {
                 method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ ...operation, appId, profileId }),
             });
@@ -69,8 +80,10 @@ export class ReadSyncClient {
             this.readAfter = Math.max(this.readAfter, receipt.acceptedAt);
         }
         const query = new URLSearchParams({ appId, profileId });
+        if (this.options.metadataOnly)
+            query.set("metadataOnly", "true");
         if (!this.readAfter && current.syncCursor !== "0") {
-            const delta = await this.request(`/api/social/reading/changes?${new URLSearchParams({ appId, profileId, after: current.syncCursor })}`);
+            const delta = await this.request(`/api/social/reading/changes?${new URLSearchParams({ appId, profileId, after: current.syncCursor, ...(this.options.metadataOnly ? { metadataOnly: "true" } : {}) })}`);
             if (delta.appId !== appId || delta.profileId !== profileId || typeof delta.syncCursor !== "string"
                 || typeof delta.snapshotRequired !== "boolean" || !Array.isArray(delta.changes))
                 throw new Error("INVALID_READ_DELTA");
@@ -78,8 +91,9 @@ export class ReadSyncClient {
                 try {
                     if (this.controller.signal.aborted)
                         throw new Error("READ_SYNC_STOPPED");
-                    const next = await persistence.update(appId, profileId, state => {
-                        const applied = delta.changes.reduce(applyReadChange, state);
+                    const next = await persistence.update(appId, profileId, (state, currentVersions) => {
+                        assertReadIndexVersions(versions, currentVersions);
+                        const applied = delta.changes.reduce((current, change) => applyReadChange(current, this.options.metadataOnly ? { ...change, thread: readingMetadata({ appId, threads: [change.thread] }).threads[0] } : change), this.options.metadataOnly ? readingMetadata(state) : state);
                         if (applied.syncCursor !== delta.syncCursor)
                             throw new ReadSyncGap(applied.syncCursor);
                         return applied;
@@ -100,7 +114,10 @@ export class ReadSyncClient {
         if (this.controller.signal.aborted)
             throw new Error("READ_SYNC_STOPPED");
         // Merge into the latest transaction, including reads made while HTTP was pending.
-        const next = await persistence.update(appId, profileId, state => installReadSnapshot(state, snapshot));
+        const next = await persistence.update(appId, profileId, (state, currentVersions) => {
+            assertReadIndexVersions(versions, currentVersions);
+            return installReadSnapshot(state, this.options.metadataOnly ? readingMetadata(snapshot) : snapshot);
+        });
         if (!next.pending.length)
             this.readAfter = 0;
         if (!this.controller.signal.aborted)

package/lib/runtime/readingClient.d.ts

@@ -1,11 +1,15 @@
+import { type ConversationReadMessage } from "./conversationRead.js";
 import { type ReadIndexPersistence, type ReadIndexState } from "./readIndex.js";
 export type ReadingClientOptions = {
     appId: string;
     profileId: string;
     sessionToken: string;
     hubHttpUrl: string;
+    teamId?: string;
+    metadataOnly?: boolean;
     persistence?: ReadIndexPersistence;
     storageScope?: string;
+    migrateLegacy?: boolean;
     fetch?: typeof fetch;
     onError?: (error: unknown) => void;
     onRecovered?: () => void;
@@ -15,6 +19,12 @@ export type ReadingClientOptions = {
 export declare class ReadingClient {
     private options;
     private storage;
+    private backing;
+    private closing?;
+    private revoking?;
+    private versions?;
+    private prepared;
+    private accepted;
     private persistence;
     private sync;
     private tasks;
@@ -34,8 +44,17 @@ export declare class ReadingClient {
     refresh: () => void;
     synchronize(targetCursor?: string, profileId?: string): Promise<ReadIndexState>;
     update(transform: (state: ReadIndexState) => ReadIndexState): Promise<ReadIndexState>;
+    private updateScoped;
+    prepareTeam(teamId: string, version: number): Promise<void>;
+    private assertThreadTeam;
+    markRead(threadId: string, messages?: readonly ConversationReadMessage[]): Promise<ReadIndexState>;
     recordVisible(threadId: string, messageIds: string[]): Promise<ReadIndexState>;
     recordExplicit(threadId: string, messageIds: string[]): Promise<ReadIndexState>;
     private record;
+    withdraw(): void;
+    private stop;
+    /** This client is retired permanently. Drain accepted local observations
+     * before deleting one team's profile-wide projection; sibling teams survive. */
+    revokeTeam(teamId: string, version: number, knownThreadIds?: readonly string[]): Promise<void>;
     close(): Promise<void>;
 }

package/lib/runtime/readingClient.js

@@ -1,12 +1,21 @@
+import { isValidChatTeamId } from "./thread.js";
+import { isOffline, isOfflineNetworkFailure } from "./connectivity.js";
+import { recordConversationRead } from "./conversationRead.js";
 import { BatchedReadIndex } from "./batchedReadIndex.js";
 import { WindowedTasks } from "./coalescer.js";
-import { IndexedDbReadIndex, recordReadIntent } from "./readIndex.js";
+import { IndexedDbReadIndex, readingMetadata, recordReadIntent, assertReadIndexVersions } from "./readIndex.js";
 import { ReadSyncClient } from "./readSync.js";
 /** Owns durable local reads, network coalescing, retries and state notifications.
  * Hosts report actual visibility; loading or subscribing never marks messages read. */
 export class ReadingClient {
     options;
     storage;
+    backing;
+    closing;
+    revoking;
+    versions;
+    prepared = new Map();
+    accepted = new Set();
     persistence;
     sync;
     tasks;
@@ -19,7 +28,10 @@ export class ReadingClient {
     generation = 0;
     constructor(options) {
         this.options = options;
-        const storage = options.persistence ?? (this.storage = new IndexedDbReadIndex(globalThis.indexedDB, "pmate-social-read-index", options.storageScope));
+        if (options.teamId !== undefined && !isValidChatTeamId(options.teamId))
+            throw new Error("INVALID_READ_TEAM");
+        const storage = options.persistence ?? (this.storage = new IndexedDbReadIndex(globalThis.indexedDB, "pmate-social-read-index", options.storageScope, options.migrateLegacy, options.metadataOnly));
+        this.backing = storage;
         this.persistence = new BatchedReadIndex(storage);
         this.tasks = new WindowedTasks(1000, error => this.failed(error));
         this.sync = new ReadSyncClient({ ...options, persistence: this.persistence, onChange: state => this.publish(state) });
@@ -27,13 +39,13 @@ export class ReadingClient {
     getSnapshot = () => this.state;
     subscribe = (listener) => { this.listeners.add(listener); return () => { this.listeners.delete(listener); }; };
     publish(state) {
-        if (this.closed || JSON.stringify(state) === JSON.stringify(this.state))
+        if (this.closed || state === this.state || JSON.stringify(state) === JSON.stringify(this.state))
             return;
         this.state = state;
         this.listeners.forEach(listener => listener());
     }
     failed(error) {
-        if (this.closed)
+        if (this.closed || isOfflineNetworkFailure(error))
             return;
         this.options.onError?.(error);
         if (/HTTP_(400|401|403)/.test(String(error)) || (typeof navigator !== "undefined" && !navigator.onLine) || this.retry)
@@ -56,8 +68,9 @@ export class ReadingClient {
         this.refresh();
     }
     refresh = () => {
-        if (!this.closed)
-            this.tasks.schedule("reading", async () => { await this.synchronize(); });
+        if (!this.closed && !isOffline())
+            this.tasks.schedule("reading", async () => { if (!isOffline())
+                await this.synchronize(); });
     };
     async synchronize(targetCursor, profileId) {
         if (this.closed)
@@ -84,32 +97,131 @@ export class ReadingClient {
         }
         throw new Error("Reading projection has not reached the announced version");
     }
-    async update(transform) {
+    update(transform) {
+        // Advanced transforms may replace profile-wide state. Typed observation
+        // methods below only derive changes for their configured team.
+        return this.updateScoped(transform);
+    }
+    updateScoped(transform, teamId, observation) {
         if (this.closed)
-            throw new Error("READING_CLIENT_CLOSED");
-        const next = await this.persistence.update(this.options.appId, this.options.profileId, transform);
-        if (!this.closed) {
-            this.publish(next);
-            if (next.pending.length || next.observedReadIntents?.length)
-                this.refresh();
-        }
-        return next;
+            return Promise.reject(new Error("READING_CLIENT_CLOSED"));
+        // One shared metadata read per local authority generation, rather than one
+        // IndexedDB lookup for every viewport observation.
+        const versions = this.versions ??= this.persistence.loadVersions(this.options.appId, this.options.profileId);
+        const task = (async () => {
+            const expected = await versions;
+            const next = await this.persistence.update(this.options.appId, this.options.profileId, (state, currentVersions) => {
+                assertReadIndexVersions(expected, currentVersions, teamId);
+                const next = transform(state);
+                return this.options.metadataOnly ? readingMetadata(next) : next;
+            }, observation);
+            if (!this.closed) {
+                this.publish(next);
+                if (next.pending.length || next.observedReadIntents?.length)
+                    this.refresh();
+            }
+            return next;
+        })().catch(error => {
+            if (String(error).includes("READ_SCOPE_CHANGED")) {
+                if (teamId !== undefined)
+                    this.withdraw();
+                else
+                    this.versions = undefined;
+            }
+            throw error;
+        });
+        this.accepted.add(task);
+        void task.finally(() => this.accepted.delete(task)).catch(() => { });
+        return task;
+    }
+    prepareTeam(teamId, version) {
+        if (this.closed)
+            return Promise.reject(new Error("READING_CLIENT_CLOSED"));
+        if (!isValidChatTeamId(teamId) || !Number.isSafeInteger(version) || version < 0)
+            return Promise.reject(new Error("INVALID_READ_SCOPE_VERSION"));
+        const previous = this.prepared.get(teamId);
+        if (previous && previous.version >= version)
+            return previous.task;
+        const task = (async () => {
+            if (version > 0)
+                await this.persistence.invalidateTeam(this.options.appId, this.options.profileId, teamId, version);
+            this.versions = undefined;
+        })().catch(error => { if (this.prepared.get(teamId)?.task === task)
+            this.prepared.delete(teamId); throw error; });
+        this.prepared.set(teamId, { version, task });
+        return task;
+    }
+    assertThreadTeam(state, threadId) {
+        if (this.options.teamId !== undefined && state.threads.some(thread => (thread.id === threadId || thread.conversationId === threadId) && thread.teamId !== undefined && thread.teamId !== this.options.teamId))
+            throw new Error("READ_CONVERSATION_TEAM_MISMATCH");
+    }
+    markRead(threadId, messages = []) {
+        return this.updateScoped(state => { this.assertThreadTeam(state, threadId); return recordConversationRead(state, threadId, messages); }, this.options.teamId);
     }
     recordVisible(threadId, messageIds) { return this.record(threadId, messageIds, "visible"); }
     recordExplicit(threadId, messageIds) { return this.record(threadId, messageIds, "explicit"); }
     record(threadId, ids, readPolicy) {
         const messageIds = [...new Set(ids)];
-        return this.update(state => messageIds.reduce((next, messageId) => recordReadIntent(next, { threadId, messageId, readPolicy, operationId: crypto.randomUUID() }), state));
+        if (!messageIds.length && this.state) {
+            try {
+                this.assertThreadTeam(this.state, threadId);
+                return Promise.resolve(this.state);
+            }
+            catch (error) {
+                return Promise.reject(error);
+            }
+        }
+        return this.updateScoped(state => { this.assertThreadTeam(state, threadId); return messageIds.reduce((next, messageId) => recordReadIntent(next, { threadId, messageId, readPolicy, operationId: crypto.randomUUID() }), state); }, this.options.teamId, this.state && messageIds.length ? { base: this.state, targets: messageIds.map(messageId => ({ threadId, messageId })) } : undefined);
     }
-    async close() {
+    withdraw() { this.stop(); }
+    stop() {
+        if (this.closed)
+            return;
         this.closed = true;
         this.generation++;
         this.offWake?.();
         this.tasks.close();
         clearTimeout(this.retry);
         this.sync.stop();
+        this.state = undefined;
+        this.listeners.forEach(listener => listener());
         this.listeners.clear();
-        await this.persistence.close();
-        await this.storage?.close();
+    }
+    /** This client is retired permanently. Drain accepted local observations
+     * before deleting one team's profile-wide projection; sibling teams survive. */
+    revokeTeam(teamId, version, knownThreadIds = []) {
+        if (this.revoking)
+            return this.revoking;
+        if (this.closing)
+            return Promise.reject(new Error("READING_CLIENT_CLOSED"));
+        this.stop();
+        return this.revoking = (async () => {
+            try {
+                await Promise.allSettled([...this.accepted]);
+                await this.persistence.close();
+                if (!this.backing.invalidateTeam)
+                    throw new Error("READ_SCOPE_INVALIDATION_UNAVAILABLE");
+                await this.backing.invalidateTeam(this.options.appId, this.options.profileId, teamId, version, knownThreadIds);
+            }
+            finally {
+                await this.storage?.close();
+            }
+        })();
+    }
+    close() {
+        if (this.revoking)
+            return this.revoking;
+        if (this.closing)
+            return this.closing;
+        this.stop();
+        return this.closing = (async () => {
+            try {
+                await Promise.allSettled([...this.accepted]);
+                await this.persistence.close();
+            }
+            finally {
+                await this.storage?.close();
+            }
+        })();
     }
 }

package/lib/runtime/readingContent.d.ts

@@ -0,0 +1,5 @@
+/** Social control envelopes do not contribute to message unread counts. */
+export declare function isReadingControl(payload: unknown, appId: string): boolean;
+/** Mirrors the server's voice policy for ordinary and quoted wire envelopes. */
+export declare function messageRequiresPlayback(body: unknown): boolean;
+export declare function messageMentionsProfile(body: unknown, profileId: string): boolean;

package/lib/runtime/readingContent.js

@@ -0,0 +1,23 @@
+/** Social control envelopes do not contribute to message unread counts. */
+export function isReadingControl(payload, appId) {
+    if (!payload || typeof payload !== "object")
+        return false;
+    const value = payload;
+    if (value.body !== undefined)
+        return isReadingControl(value.body, appId);
+    return value.kind === "message" && value.content?.appId === appId && (value.content.reaction !== undefined || value.content.recall !== undefined);
+}
+/** Mirrors the server's voice policy for ordinary and quoted wire envelopes. */
+export function messageRequiresPlayback(body) {
+    if (!body || typeof body !== "object")
+        return false;
+    const value = body;
+    return value.contentKind === "voice" || value.content?.contentKind === "voice" || [value.content?.voice?.url, value.content?.content?.voice?.url].some(url => typeof url === "string" && url.length > 0);
+}
+export function messageMentionsProfile(body, profileId) {
+    if (!body || typeof body !== "object")
+        return false;
+    const content = body.content;
+    const mentions = content?.mentions !== undefined ? content.mentions : content?.content?.mentions;
+    return Array.isArray(mentions) && mentions.some(mention => mention?.id === profileId);
+}

package/lib/runtime/responseCache.d.ts

@@ -1,18 +1,40 @@
+export type ResponseCacheAccess = () => Promise<{
+    version: number;
+    allowed: boolean;
+}>;
+export declare function isResponseCacheAuthorityError(error: unknown): boolean;
+export declare function assertResponseCacheAccess(access?: ResponseCacheAccess, expectedVersion?: number): Promise<number | undefined>;
+export type ResponseCacheOptions<T> = {
+    indexedDB?: IDBFactory;
+    name?: string;
+    access?: ResponseCacheAccess;
+    /** Immutable identity metadata must survive ordinary response-window eviction. */
+    retainAll?: boolean;
+    recordBytes?: number;
+    entries?: number;
+    batchRecords?: number;
+    revision?: (value: T) => string;
+};
 /** 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 options;
+    private transact;
     private db;
     private rows;
     private epochs;
     private pending;
     private tasks;
     private running?;
+    private invalidations;
     private closed;
-    constructor(scope: string, options?: {
-        indexedDB?: IDBFactory;
-        name?: string;
-    });
+    private closing?;
+    constructor(scope: string, options?: ResponseCacheOptions<T>);
+    /** 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. */
+    private synchronizeAccess;
     read(key: string): Promise<{
         epoch: number;
         cached: {
@@ -20,7 +42,20 @@ export declare class IndexedDbResponseCache<T> {
             time: number;
         } | undefined;
     }>;
-    write(key: string, value: T, epoch: number): Promise<void>;
+    /** Key-only callers can share one bounded metadata read transaction. */
+    readMany(keys: readonly string[]): Promise<Map<string, {
+        epoch: number;
+        cached: {
+            value: T;
+            time: number;
+        } | undefined;
+    }>>;
+    write(key: string, value: T, epoch: number, expectedRevision?: string | null): Promise<void>;
+    /** Forget one response without invalidating unrelated cached conversations. */
+    remove(key: string): Promise<void>;
+    /** Idempotent shared-scope retirement: an old cleanup cannot erase windows
+     * created after the same authority version was already recovered. */
+    retire(version: number): Promise<void>;
     invalidate(): Promise<void>;
     flush(): Promise<void>;
     close(): Promise<void>;