@pmate/chat-sdk 0.12.0-next.0 → 0.12.0-next.2

package/lib/runtime/chatSession.d.ts

@@ -0,0 +1,59 @@
+import { type MessageReadersQuery } from "./messageReaders.js";
+import { type MessageClientOptions } from "./messageClient.js";
+import { DurableChatSender } from "./durableSender.js";
+import { type ReadingClientOptions } from "./readingClient.js";
+import { type ChatClientOptions } from "./chatClient.js";
+import { unreadInConversation } from "./readIndex.js";
+import type { StoredMessage } from "./messageStore.js";
+import type { ChatBody, ChatRuntimeMessage } from "./protocol.js";
+export type ChatSessionOptions<T extends StoredMessage> = {
+    messages: MessageClientOptions<T>;
+    connection: ChatClientOptions;
+    reading: ReadingClientOptions;
+    decode: (message: ChatRuntimeMessage) => T | undefined;
+    onError: (error: unknown) => void;
+};
+export type ChatThreadSnapshot<T> = {
+    messages: readonly T[];
+    outgoing: ReturnType<DurableChatSender["snapshot"]>;
+    hasEarlier: boolean;
+    unread: ReturnType<typeof unreadInConversation>;
+};
+/** Owns all browser message clients. Hosts subscribe to stable thread snapshots. */
+export declare class ChatSession<T extends StoredMessage> {
+    private options;
+    private messages;
+    private connection;
+    private reading;
+    private readers;
+    private sender;
+    private listeners;
+    private snapshots;
+    private off;
+    private closed;
+    private starting?;
+    private closing?;
+    constructor(options: ChatSessionOptions<T>);
+    start(): Promise<void>;
+    private assertOpen;
+    getMessages(threadId: string, options?: {
+        limit?: number;
+        before?: {
+            timestamp: number;
+            id: string;
+        };
+    }): Promise<import("./messageClient.js").MessageSnapshot<T>>;
+    sendMessage(threadId: string, input: {
+        to: string;
+        body: ChatBody;
+        recipients?: string[];
+    }): Promise<ChatRuntimeMessage>;
+    getReaders(threadId: string, messageId: string, page?: Omit<MessageReadersQuery, "threadId" | "messageId">, signal?: AbortSignal): Promise<import("./messageReaders.js").MessageReadersPage>;
+    retryMessage(messageId: string): Promise<ChatRuntimeMessage>;
+    observeMessages(threadId: string, ids: string[], event: "visible" | "played"): Promise<import("./readIndex.js").ReadIndexState>;
+    getSnapshot(threadId: string): ChatThreadSnapshot<T>;
+    subscribe(threadId: string, listener: () => void): () => void;
+    private publishAll;
+    private publish;
+    close(): Promise<void>;
+}

package/lib/runtime/chatSession.js

@@ -0,0 +1,130 @@
+import { MessageReadersClient } from "./messageReaders.js";
+import { MessageClient } from "./messageClient.js";
+import { DurableChatSender } from "./durableSender.js";
+import { ReadingClient } from "./readingClient.js";
+import { ChatClient } from "./chatClient.js";
+import { unreadInConversation } from "./readIndex.js";
+/** Owns all browser message clients. Hosts subscribe to stable thread snapshots. */
+export class ChatSession {
+    options;
+    messages;
+    connection;
+    reading;
+    readers;
+    sender;
+    listeners = new Map();
+    snapshots = new Map();
+    off = [];
+    closed = false;
+    starting;
+    closing;
+    constructor(options) {
+        this.options = options;
+        const scope = options.messages.scope;
+        if (options.connection.appId !== scope.appId || options.reading.appId !== scope.appId || options.reading.profileId !== scope.profileId || options.connection.profileId !== scope.profileId || options.connection.teamId !== scope.teamId)
+            throw new Error("CHAT_SESSION_SCOPE_MISMATCH");
+        this.messages = new MessageClient(options.messages);
+        this.connection = new ChatClient(options.connection);
+        this.reading = new ReadingClient(options.reading);
+        this.readers = new MessageReadersClient({ appId: scope.appId, profileId: scope.profileId, token: options.reading.sessionToken, hubHttpUrl: options.reading.hubHttpUrl, fetch: options.reading.fetch });
+        this.sender = new DurableChatSender(this.connection, scope, options.onError);
+        this.off.push(this.sender.subscribe(() => this.publishAll()), this.reading.subscribe(() => this.publishAll()));
+        this.off.push(this.connection.watchMessages(message => {
+            try {
+                const decoded = options.decode(message);
+                if (decoded)
+                    void this.messages.receive(decoded.threadId, [decoded]).then(() => { this.publish(decoded.threadId); return this.sender.confirm([message.hash]); }).catch(options.onError);
+            }
+            catch (error) {
+                options.onError(error);
+            }
+        }));
+        this.off.push(this.connection.watchConnection(state => {
+            if (state === "connected") {
+                for (const thread of this.listeners.keys())
+                    this.messages.invalidate(thread);
+                this.reading.refresh();
+            }
+        }));
+    }
+    start() {
+        this.assertOpen();
+        return this.starting ??= (async () => {
+            await this.sender.initialize();
+            await this.reading.start();
+            this.assertOpen();
+            await this.connection.connect();
+        })().catch(error => { this.starting = undefined; throw error; });
+    }
+    assertOpen() { if (this.closed)
+        throw new Error("CHAT_SESSION_CLOSED"); }
+    async getMessages(threadId, options = {}) {
+        this.assertOpen();
+        const page = await (options.before ? this.messages.earlier(threadId, options.before, options.limit) : this.messages.read(threadId, options.limit));
+        if (!options.before)
+            this.publish(threadId);
+        return page;
+    }
+    sendMessage(threadId, input) {
+        this.assertOpen();
+        return this.sender.enqueue(threadId, input);
+    }
+    getReaders(threadId, messageId, page = {}, signal) {
+        this.assertOpen();
+        return this.readers.getReaders({ ...page, threadId, messageId }, signal);
+    }
+    retryMessage(messageId) { this.assertOpen(); return this.sender.retry(messageId); }
+    observeMessages(threadId, ids, event) {
+        this.assertOpen();
+        return event === "played" ? this.reading.recordExplicit(threadId, ids) : this.reading.recordVisible(threadId, ids);
+    }
+    getSnapshot(threadId) {
+        let snapshot = this.snapshots.get(threadId);
+        if (!snapshot) {
+            const messages = this.messages.getSnapshot(threadId);
+            const state = this.reading.getSnapshot();
+            snapshot = { messages: messages?.messages ?? [], hasEarlier: messages?.hasEarlier ?? false, outgoing: this.sender.snapshot(threadId), unread: state?.threads.some(thread => (thread.conversationId ?? thread.id) === threadId) ? unreadInConversation(state, threadId) : { unreadMessageCount: 0, unreadMentionCount: 0, badgeCount: 0 } };
+            this.snapshots.set(threadId, snapshot);
+        }
+        return snapshot;
+    }
+    subscribe(threadId, listener) {
+        this.assertOpen();
+        let listeners = this.listeners.get(threadId);
+        if (!listeners) {
+            listeners = new Set();
+            this.listeners.set(threadId, listeners);
+        }
+        listeners.add(listener);
+        const off = this.messages.subscribe(threadId, () => this.publish(threadId));
+        return () => {
+            off();
+            listeners.delete(listener);
+            if (!listeners.size)
+                this.listeners.delete(threadId);
+        };
+    }
+    publishAll() { for (const threadId of [...this.snapshots.keys()])
+        this.publish(threadId); }
+    publish(threadId) {
+        const previous = this.snapshots.get(threadId);
+        this.snapshots.delete(threadId);
+        const next = this.getSnapshot(threadId);
+        if (previous && JSON.stringify(previous) === JSON.stringify(next)) {
+            this.snapshots.set(threadId, previous);
+            return;
+        }
+        this.listeners.get(threadId)?.forEach(listener => listener());
+    }
+    close() {
+        return this.closing ??= (async () => {
+            this.closed = true;
+            this.off.splice(0).forEach(off => off());
+            this.connection.close();
+            this.readers.close();
+            await Promise.all([this.sender.close(), this.reading.close(), this.messages.close()]);
+            this.listeners.clear();
+            this.snapshots.clear();
+        })();
+    }
+}

package/lib/runtime/durableSender.d.ts

@@ -32,11 +32,19 @@ export declare class DurableChatSender {
     subscribe(listener: () => void): () => void;
     snapshot(threadId?: string): readonly OutgoingMessage[];
     private emit;
+    /** Resolves after the exact wire message is durable, independently of network delivery. */
+    enqueue(threadId: string, input: {
+        to: string;
+        body: ChatBody;
+        recipients?: string[];
+    }): Promise<ChatRuntimeMessage>;
+    /** Compatibility API: resolves only after transport delivery. */
     send(threadId: string, input: {
         to: string;
         body: ChatBody;
         recipients?: string[];
     }): Promise<ChatRuntimeMessage>;
+    private persistOutgoing;
     retry(hash: string): Promise<ChatRuntimeMessage>;
     private transmit;
     private save;

package/lib/runtime/durableSender.js

@@ -47,7 +47,18 @@ export class DurableChatSender {
     }
     emit() { this.snapshots.clear(); if (!this.closed)
         this.listeners.forEach(listener => listener()); }
+    /** Resolves after the exact wire message is durable, independently of network delivery. */
+    async enqueue(threadId, input) {
+        const message = await this.persistOutgoing(threadId, input);
+        void this.retry(message.hash).catch(error => this.onError(error));
+        return message;
+    }
+    /** Compatibility API: resolves only after transport delivery. */
     async send(threadId, input) {
+        const message = await this.persistOutgoing(threadId, input);
+        return this.retry(message.hash);
+    }
+    async persistOutgoing(threadId, input) {
         await this.ready;
         if (this.closed)
             throw new Error("CHAT_SENDER_CLOSED");
@@ -60,7 +71,7 @@ export class DurableChatSender {
             throw new Error("CHAT_SENDER_CLOSED");
         this.values.set(record.hash, record);
         this.emit();
-        return this.retry(record.hash);
+        return message;
     }
     retry(hash) {
         if (this.closed)

package/lib/runtime/index.d.ts

@@ -26,3 +26,5 @@ export * from "./messageStore.js";
 export * from "./messageClient.js";
 export * from "./recordCache.js";
 export * from "./durableSender.js";
+export * from "./chatSession.js";
+export * from "./messageReaders.js";

package/lib/runtime/index.js

@@ -26,3 +26,5 @@ export * from "./messageStore.js";
 export * from "./messageClient.js";
 export * from "./recordCache.js";
 export * from "./durableSender.js";
+export * from "./chatSession.js";
+export * from "./messageReaders.js";

package/lib/runtime/messageClient.d.ts

@@ -33,6 +33,7 @@ export declare class MessageClient<T extends StoredMessage> {
     private watches;
     private reads;
     private syncing;
+    private paging;
     private writes;
     private activeWrites;
     private writeTasks;
@@ -63,6 +64,7 @@ export declare class MessageClient<T extends StoredMessage> {
         messages: T[];
         hasEarlier: boolean;
     }>;
+    private fillWindow;
     revoke(thread: string): Promise<void>;
     close(): Promise<void>;
 }

package/lib/runtime/messageClient.js

@@ -7,6 +7,7 @@ export class MessageClient {
     watches = new Map();
     reads = new Map();
     syncing = new Map();
+    paging = new Map();
     writes = new Map();
     activeWrites = new Set();
     writeTasks;
@@ -55,6 +56,7 @@ export class MessageClient {
                 await this.synchronize(thread);
             if (this.closed)
                 throw new Error("MESSAGE_CLIENT_CLOSED");
+            await this.fillWindow(thread, limit);
             return this.reload(thread, limit);
         })().finally(() => { if (this.reads.get(key) === task)
             this.reads.delete(key); });
@@ -183,19 +185,33 @@ export class MessageClient {
             throw new Error("MESSAGE_ACCESS_REVOKED");
         if (!(await this.storage.read(thread, 1)).coverage?.complete)
             await this.synchronize(thread);
+        return this.fillWindow(thread, limit, before);
+    }
+    async fillWindow(thread, limit, before) {
         let page = await this.storage.read(thread, limit, before);
         while (page.messages.length < limit && page.coverage?.nextBefore && this.options.transport.older) {
-            const token = page.coverage.nextBefore;
-            const remote = await this.options.transport.older(thread, token, this.abort.signal);
-            if (this.closed || this.revoked.has(thread))
-                throw new Error("MESSAGE_CLIENT_UNAVAILABLE");
-            if (remote.resetRequired) {
-                await this.storage.removeThread(thread);
-                throw new Error("MESSAGE_SYNC_RESET_REQUIRED");
+            const pending = this.paging.get(thread);
+            if (pending) {
+                await pending;
+                page = await this.storage.read(thread, limit, before);
+                continue;
             }
-            if (remote.nextBefore === token)
-                throw new Error("MESSAGE_SYNC_NO_PROGRESS");
-            await this.persist(thread, remote.messages, undefined, true, remote.nextBefore ?? null);
+            const token = page.coverage.nextBefore;
+            const task = (async () => {
+                const remote = await this.options.transport.older(thread, token, this.abort.signal);
+                if (this.closed || this.revoked.has(thread))
+                    throw new Error("MESSAGE_CLIENT_UNAVAILABLE");
+                if (remote.resetRequired) {
+                    await this.storage.removeThread(thread);
+                    throw new Error("MESSAGE_SYNC_RESET_REQUIRED");
+                }
+                if (remote.nextBefore === token)
+                    throw new Error("MESSAGE_SYNC_NO_PROGRESS");
+                await this.persist(thread, remote.messages, undefined, true, remote.nextBefore ?? null);
+            })().finally(() => { if (this.paging.get(thread) === task)
+                this.paging.delete(thread); });
+            this.paging.set(thread, task);
+            await task;
             page = await this.storage.read(thread, limit, before);
         }
         return { messages: page.messages, hasEarlier: page.hasEarlier || Boolean(page.coverage?.nextBefore) };

package/lib/runtime/messageReaders.d.ts

@@ -0,0 +1,39 @@
+export type MessageReadersPage = {
+    appId: string;
+    threadId: string;
+    messageId: string;
+    revision: number;
+    total: number;
+    profileIds: string[];
+    nextAfter: string | null;
+    resetRequired: boolean;
+};
+export type MessageReadersQuery = {
+    threadId: string;
+    messageId: string;
+    afterProfileId?: string;
+    revision?: number;
+    limit?: number;
+};
+export type MessageReadersOptions = {
+    appId: string;
+    profileId: string;
+    token: string;
+    hubHttpUrl: string;
+    fetch?: typeof fetch;
+};
+export declare class MessageReadersError extends Error {
+    readonly status: number;
+    readonly forbidden: boolean;
+    constructor(status: number, message: string);
+}
+/** Authenticated detail reads; concurrent identical requests share one transport call. */
+export declare class MessageReadersClient {
+    private options;
+    private pending;
+    private lifetime;
+    constructor(options: MessageReadersOptions);
+    getReaders(query: MessageReadersQuery, signal?: AbortSignal): Promise<MessageReadersPage>;
+    private request;
+    close(): void;
+}

package/lib/runtime/messageReaders.js

@@ -0,0 +1,71 @@
+export class MessageReadersError extends Error {
+    status;
+    forbidden;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.forbidden = status === 401 || status === 403;
+    }
+}
+/** Authenticated detail reads; concurrent identical requests share one transport call. */
+export class MessageReadersClient {
+    options;
+    pending = new Map();
+    lifetime = new AbortController();
+    constructor(options) { this.options = { ...options }; }
+    getReaders(query, signal) {
+        if (this.lifetime.signal.aborted)
+            return Promise.reject(new Error("MESSAGE_READERS_CLOSED"));
+        if (signal?.aborted)
+            return Promise.reject(signal.reason);
+        const input = { ...query, limit: query.limit ?? 50 };
+        if (!Number.isSafeInteger(input.limit) || input.limit < 1 || input.limit > 100 || (input.revision !== undefined && (!Number.isSafeInteger(input.revision) || input.revision < 0)))
+            return Promise.reject(new Error("INVALID_MESSAGE_READERS_QUERY"));
+        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)
+                this.pending.delete(key); });
+            this.pending.set(key, task);
+        }
+        if (!signal)
+            return task;
+        // Cancelling one view must not cancel another view's shared request.
+        return new Promise((resolve, reject) => {
+            const abort = () => { signal.removeEventListener("abort", abort); reject(signal.reason); };
+            signal.addEventListener("abort", abort, { once: true });
+            task.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+        });
+    }
+    async request(input) {
+        const { token, fetch: fetcher, hubHttpUrl, appId, profileId } = this.options;
+        const controller = new AbortController();
+        const cancel = () => controller.abort(this.lifetime.signal.reason);
+        this.lifetime.signal.addEventListener("abort", cancel, { once: true });
+        const timeout = setTimeout(() => controller.abort(), 8000);
+        try {
+            const response = await (fetcher ?? fetch)(`${hubHttpUrl.replace(/^ws/, "http").replace(/\/+$/, "")}/api/social/reading/readers`, {
+                method: "POST", headers: { authorization: `Bearer ${token}`, "content-type": "application/json" }, body: JSON.stringify({ ...input, appId, profileId }),
+                signal: controller.signal, redirect: "error", cache: "no-store",
+            });
+            if (!response.ok)
+                throw new MessageReadersError(response.status, `MESSAGE_READERS_HTTP_${response.status}`);
+            const envelope = await response.json(), data = envelope.data;
+            if (envelope.success !== true || data?.appId !== appId || data.threadId !== input.threadId || data.messageId !== input.messageId
+                || !Number.isSafeInteger(data.revision) || data.revision < 0 || !Number.isSafeInteger(data.total) || data.total < 0
+                || !Array.isArray(data.profileIds) || data.profileIds.length > input.limit || data.profileIds.length > data.total
+                || data.profileIds.some((id, i, ids) => typeof id !== "string" || !id || id.length > 512 || id === profileId || (i > 0 && id <= ids[i - 1]) || (input.afterProfileId && !data.resetRequired && id <= input.afterProfileId))
+                || typeof data.resetRequired !== "boolean" || (data.nextAfter !== null && (typeof data.nextAfter !== "string" || data.nextAfter !== data.profileIds.at(-1)))
+                || (!data.resetRequired && input.revision !== undefined && data.revision !== input.revision))
+                throw new Error("INVALID_MESSAGE_READERS_RESPONSE");
+            if (this.lifetime.signal.aborted)
+                throw new Error("MESSAGE_READERS_CLOSED");
+            return data;
+        }
+        finally {
+            clearTimeout(timeout);
+            this.lifetime.signal.removeEventListener("abort", cancel);
+        }
+    }
+    close() { this.lifetime.abort(); this.pending.clear(); }
+}

package/lib/runtime/readIndex.js

@@ -102,8 +102,9 @@ function resolveObservedReads(current) {
         }
         if (message.recalled || message.from === next.profileId || !message.recipients.includes(next.profileId))
             continue;
+        // Visibility may include voice rows; incompatible observations never acknowledge them.
         if (message.readPolicy !== intent.readPolicy)
-            throw new Error("READ_POLICY_MISMATCH");
+            continue;
         next = intent.readPolicy === "explicit" ? recordExplicitRead(next, intent.threadId, intent.messageId, intent.operationId)
             : recordVisibleRead(next, intent.threadId, intent.messageId, intent.operationId);
     }

package/lib/runtime/recordCache.js

@@ -47,6 +47,7 @@ export class IndexedDbRecordCache {
             }
             await this.reload();
             this.initialized = true;
+            this.listeners.forEach(listener => listener());
         })().catch(error => { this.ready = undefined; throw error; });
         return this.ready;
     }
@@ -70,7 +71,8 @@ export class IndexedDbRecordCache {
         }
         if (changed) {
             this.snapshotValue = [...this.values.values()];
-            this.listeners.forEach(listener => listener());
+            if (this.initialized)
+                this.listeners.forEach(listener => listener());
         }
     }
     async upsert(incoming) {

package/package.json

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