@pmate/chat-sdk 0.9.5 → 0.9.7

package/lib/runtime/readIndex.d.ts

@@ -24,6 +24,12 @@ export type IndexedReadThread = {
     readThroughSeq: number;
     explicitReadMessageIds: string[];
 };
+export type ObservedReadIntent = {
+    operationId: string;
+    threadId: string;
+    messageId: string;
+    readPolicy: "visible" | "explicit";
+};
 export type ReadIndexState = {
     schemaVersion: 1;
     appId: string;
@@ -31,8 +37,10 @@ export type ReadIndexState = {
     syncCursor: string;
     threads: IndexedReadThread[];
     pending: ReadingOperation[];
+    /** Actual viewport/playback observation awaiting authoritative message metadata. */
+    observedReadIntents?: ObservedReadIntent[];
 };
-export type ReadSnapshot = Omit<ReadIndexState, "pending">;
+export type ReadSnapshot = Omit<ReadIndexState, "pending" | "observedReadIntents">;
 export type ReadChange = {
     eventId: string;
     appId: string;
@@ -50,6 +58,8 @@ export declare function createReadIndex(appId: string, profileId: string): ReadI
 export declare function installReadSnapshot(current: ReadIndexState, snapshot: ReadSnapshot): ReadIndexState;
 /** Cursor positions are opaque; only exact predecessor matching proves continuity. */
 export declare function applyReadChange(current: ReadIndexState, change: ReadChange): ReadIndexState;
+/** Persist observations even if the message arrived before its Sequence metadata. */
+export declare function recordReadIntent(current: ReadIndexState, intent: ObservedReadIntent): ReadIndexState;
 /** Called only for a message the visible viewport actually reached. */
 export declare function recordVisibleRead(current: ReadIndexState, threadId: string, messageId: string, operationId: string): ReadIndexState;
 export declare function recordExplicitRead(current: ReadIndexState, threadId: string, messageId: string, operationId: string): ReadIndexState;

package/lib/runtime/readIndex.js

@@ -56,7 +56,7 @@ export function installReadSnapshot(current, snapshot) {
             byId.set(thread.id, { ...thread, readThroughSeq: Math.max(thread.readThroughSeq, previous.readThroughSeq),
                 explicitReadMessageIds: [...new Set([...thread.explicitReadMessageIds, ...previous.explicitReadMessageIds])] });
     }
-    return { ...snapshot, threads: [...byId.values()], pending };
+    return resolveObservedReads({ ...snapshot, threads: [...byId.values()], pending, observedReadIntents: current.observedReadIntents ?? [] });
 }
 /** Cursor positions are opaque; only exact predecessor matching proves continuity. */
 export function applyReadChange(current, change) {
@@ -72,7 +72,36 @@ export function applyReadChange(current, change) {
     const merged = previous ? { ...incoming, readThroughSeq: Math.max(incoming.readThroughSeq, previous.readThroughSeq),
         explicitReadMessageIds: [...new Set([...incoming.explicitReadMessageIds, ...previous.explicitReadMessageIds])] } : incoming;
     const projected = pending.filter(operation => operation.threadId === incoming.id).reduce(applyOperation, merged);
-    return { ...current, syncCursor: change.syncCursor, pending, threads: [...current.threads.filter(t => t.id !== incoming.id), projected] };
+    return resolveObservedReads({ ...current, syncCursor: change.syncCursor, pending, threads: [...current.threads.filter(t => t.id !== incoming.id), projected] });
+}
+/** Persist observations even if the message arrived before its Sequence metadata. */
+export function recordReadIntent(current, intent) {
+    if (!intent.operationId || !intent.threadId || !intent.messageId || !["visible", "explicit"].includes(intent.readPolicy))
+        throw new Error("INVALID_READ_INTENT");
+    const observed = current.observedReadIntents ?? [];
+    if (observed.some(item => item.threadId === intent.threadId && item.messageId === intent.messageId && item.readPolicy === intent.readPolicy))
+        return current;
+    if (observed.some(item => item.operationId === intent.operationId) || current.pending.some(item => item.operationId === intent.operationId))
+        throw new Error("INVALID_READ_OPERATION_ID");
+    return resolveObservedReads({ ...current, observedReadIntents: [...observed, structuredClone(intent)] });
+}
+function resolveObservedReads(current) {
+    let next = current;
+    const remaining = [];
+    for (const intent of current.observedReadIntents ?? []) {
+        const message = next.threads.find(thread => thread.id === intent.threadId)?.messages.find(message => message.id === intent.messageId);
+        if (!message) {
+            remaining.push(intent);
+            continue;
+        }
+        if (message.recalled || message.from === next.profileId || !message.recipients.includes(next.profileId))
+            continue;
+        if (message.readPolicy !== intent.readPolicy)
+            throw new Error("READ_POLICY_MISMATCH");
+        next = intent.readPolicy === "explicit" ? recordExplicitRead(next, intent.threadId, intent.messageId, intent.operationId)
+            : recordVisibleRead(next, intent.threadId, intent.messageId, intent.operationId);
+    }
+    return { ...next, observedReadIntents: remaining };
 }
 /** Called only for a message the visible viewport actually reached. */
 export function recordVisibleRead(current, threadId, messageId, operationId) {

package/lib/runtime/readSync.js

@@ -1,4 +1,4 @@
-import { createReadIndex, installReadSnapshot } from "./readIndex.js";
+import { applyReadChange, ReadSyncGap, createReadIndex, installReadSnapshot } from "./readIndex.js";
 /** Keeps local operations until an authoritative projection covers them. */
 export class ReadSyncClient {
     options;
@@ -57,6 +57,31 @@ export class ReadSyncClient {
             this.readAfter = Math.max(this.readAfter, receipt.acceptedAt);
         }
         const query = new URLSearchParams({ appId, profileId });
+        if (!this.readAfter && current.syncCursor !== "0") {
+            const delta = await this.request(`/api/social/reading/changes?${new URLSearchParams({ appId, profileId, after: current.syncCursor })}`);
+            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");
+            if (!delta.snapshotRequired) {
+                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);
+                        if (applied.syncCursor !== delta.syncCursor)
+                            throw new ReadSyncGap(applied.syncCursor);
+                        return applied;
+                    });
+                    if (!this.controller.signal.aborted)
+                        this.options.onChange?.(next);
+                    return next;
+                }
+                catch (error) {
+                    if (!(error instanceof ReadSyncGap))
+                        throw error;
+                }
+            }
+        }
         const snapshot = await this.request(`/api/social/reading/snapshot?${query}`, {
             headers: this.readAfter ? { "x-pmate-read-after-time": String(this.readAfter) } : {},
         });
@@ -64,6 +89,8 @@ export class ReadSyncClient {
             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));
+        if (!next.pending.length)
+            this.readAfter = 0;
         if (!this.controller.signal.aborted)
             this.options.onChange?.(next);
         return next;

package/package.json

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