@pmate/chat-sdk 0.9.4 → 0.9.6

package/lib/runtime/index.d.ts

@@ -13,3 +13,4 @@ export * from "./call.js";
 export * from "./presence.js";
 export * from "./meeting.js";
 export * from "./notification.js";
+export * from "./readSync.js";

package/lib/runtime/index.js

@@ -13,3 +13,4 @@ export * from "./call.js";
 export * from "./presence.js";
 export * from "./meeting.js";
 export * from "./notification.js";
+export * from "./readSync.js";

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.d.ts

@@ -0,0 +1,23 @@
+import { type ReadIndexPersistence, type ReadIndexState } from "./readIndex.js";
+export type ReadSyncOptions = {
+    appId: string;
+    profileId: string;
+    sessionToken: string;
+    hubHttpUrl: string;
+    persistence: ReadIndexPersistence;
+    fetch?: typeof globalThis.fetch;
+    onChange?: (state: ReadIndexState) => void;
+};
+/** Keeps local operations until an authoritative projection covers them. */
+export declare class ReadSyncClient {
+    private readonly options;
+    private readonly controller;
+    private inFlight?;
+    private readAfter;
+    constructor(options: ReadSyncOptions);
+    loadLocal(): Promise<ReadIndexState>;
+    stop(): void;
+    synchronize(): Promise<ReadIndexState>;
+    private request;
+    private run;
+}

package/lib/runtime/readSync.js

@@ -0,0 +1,71 @@
+import { createReadIndex, installReadSnapshot } from "./readIndex.js";
+/** Keeps local operations until an authoritative projection covers them. */
+export class ReadSyncClient {
+    options;
+    controller = new AbortController();
+    inFlight;
+    readAfter = 0;
+    constructor(options) {
+        this.options = options;
+    }
+    async loadLocal() {
+        return await this.options.persistence.load(this.options.appId, this.options.profileId)
+            ?? createReadIndex(this.options.appId, this.options.profileId);
+    }
+    stop() { this.controller.abort(); }
+    synchronize() {
+        if (this.inFlight)
+            return this.inFlight;
+        const task = this.run().finally(() => { if (this.inFlight === task)
+            this.inFlight = undefined; });
+        this.inFlight = task;
+        return task;
+    }
+    async request(path, init = {}) {
+        if (this.controller.signal.aborted)
+            throw new Error("READ_SYNC_STOPPED");
+        const timeout = new AbortController();
+        const abort = () => timeout.abort();
+        this.controller.signal.addEventListener("abort", abort, { once: true });
+        const timer = setTimeout(abort, 10_000);
+        try {
+            const response = await (this.options.fetch ?? globalThis.fetch)(`${this.options.hubHttpUrl.replace(/\/$/, "")}${path}`, {
+                ...init, signal: timeout.signal, headers: { ...init.headers, authorization: `Bearer ${this.options.sessionToken}` },
+            });
+            if (!response.ok)
+                throw new Error(`READ_SYNC_HTTP_${response.status}`);
+            const envelope = await response.json();
+            if (envelope.success !== true || envelope.data === undefined)
+                throw new Error("INVALID_READ_SYNC_RESPONSE");
+            return envelope.data;
+        }
+        finally {
+            clearTimeout(timer);
+            this.controller.signal.removeEventListener("abort", abort);
+        }
+    }
+    async run() {
+        const { appId, profileId, persistence } = this.options;
+        const current = await this.loadLocal();
+        for (const operation of current.pending) {
+            const receipt = await this.request("/api/social/reading", {
+                method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ ...operation, appId, profileId }),
+            });
+            if (receipt.operationId !== operation.operationId || receipt.accepted !== true
+                || !Number.isSafeInteger(receipt.acceptedAt) || receipt.acceptedAt <= 0)
+                throw new Error("INVALID_READING_RECEIPT");
+            this.readAfter = Math.max(this.readAfter, receipt.acceptedAt);
+        }
+        const query = new URLSearchParams({ appId, profileId });
+        const snapshot = await this.request(`/api/social/reading/snapshot?${query}`, {
+            headers: this.readAfter ? { "x-pmate-read-after-time": String(this.readAfter) } : {},
+        });
+        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));
+        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.4",
+  "version": "0.9.6",
   "description": "Cross-platform PMate chat input components, voice input primitives, and ASR helpers",
   "type": "module",
   "main": "./lib/index.js",