@pmate/chat-sdk 0.12.0-next.4 → 0.12.0-next.41

package/README.md

@@ -142,7 +142,14 @@ The browser entry point is `createChat` from `@pmate/chat-sdk/runtime`:
 ```ts
 const chat = createChat({ appId, accountId, profileId, teamId, token, onError })
 await chat.start()
-const page = await chat.getMessages(threadId, { limit: 50 })
+const page = await chat.getMessages(threadId)
+// SDK owns the page size and history boundary; hosts need not construct a cursor.
+const earlier = await chat.getMessages(threadId, { earlier: true })
+// After an authoritative mutation (e.g. history assignment), await reconciliation.
+// Concurrent refreshes share transport; errors do not masquerade as fresh cache.
+const reconciled = await chat.getMessages(threadId, { refresh: true })
+// Explicit full-history queries reuse cached pages and internally rebase expired cursors.
+const history = await chat.getMessages(threadId, { all: true })
 const off = chat.subscribe(threadId, () => render(chat.getSnapshot(threadId)))
 const offSummary = chat.subscribe(() => renderSummary(chat.getSnapshot()))
 await chat.observeMessages(threadId, visibleIds, "visible")
@@ -151,9 +158,17 @@ await chat.observeMessages(threadId, [voiceId], "played")
 await chat.sendMessage(threadId, { to, body, recipients })
 const readers = await chat.getReaders(threadId, messageId)
 off(); offSummary()
+// Ordinary navigation/shutdown preserves offline data.
 await chat.close()
 ```
 
+```ts
+// When team access is withdrawn, use this instead of ordinary close(). It hides
+// snapshots immediately, retires durable caches/outbox and closes this session.
+// Other teams' reading operations remain intact. Create a new session to recover.
+await chat.revokeAccess()
+```
+
 The facade owns all clients below. Message reads transparently restore IndexedDB
 windows and fetch missing ranges through the authenticated Hub. Its normalized
 messages retain the protocol body; product rendering remains with the host.
@@ -162,6 +177,11 @@ snapshot reports transport progress and failure. Retry uses the original message
 hash. The subscribed recent window remains 100 records regardless of individual
 query limits; history requests return their own pages and do not replace it.
 Global snapshots contain thread summaries and totals, not complete message arrays.
+Message pages report `complete`; unavailable older pages return cached records with
+`complete: false`. Authorization failures throw and never fall back to denied
+records. Thread snapshots expose `resetVersion`; hosts discard retained rows when
+it changes. Reset epochs are durable, so late cross-tab writes cannot restore a
+pre-reset payload.
 Voice visibility never acknowledges playback, including observations that arrive
 before metadata. Create a new instance and close the previous owner when the
 account or active Team changes.
@@ -191,6 +211,11 @@ legacy cleanup happens after durable migration. Normal reads use memory and writ
 are merged into bounded IndexedDB transactions. Cache errors must be surfaced by
 the host, and pending operations are not reported as saved before their promise
 resolves.
+Control-event batches are bounded by both 128 records and 1 MiB per transaction;
+the queue includes in-flight writes and is limited to 4096 records / 8 MiB.
+`transactionBytes` and `queueBytes` can lower these limits. Oversized operations
+fail before changing the memory snapshot. Repeating an in-flight write waits for
+that physical write, including its failure, rather than acknowledging it early.
 
 `DurableChatSender` saves the exact message created by `ChatClient.prepareChat`
 before transmitting it. `retry(hash)` uses `sendPrepared` with the original hash
@@ -203,3 +228,18 @@ Custom primitive integrations must initialize them with the same authenticated
 scope, dispose them on identity changes, and wire their transport to an authorized
 server. Standard browser integrations should use the facade instead. The Merry migration and production validation
 are tracked in the unified message layer proposal.
+
+When the browser reports offline, scheduled message restoration and reading
+refreshes wait for the normal reconnect/wake path. Cached reads remain available;
+unknown receipt counts stay unknown and an uncached reader detail page rejects
+without attempting transport. A network failure arriving after the browser went
+offline does not turn background synchronization into an operation error.
+Authorization failures still revoke the corresponding cached data.
+
+Reading entry points check the message scope even before `initialize()` finishes.
+Concurrent observations share the permission lookup and batch their local writes.
+Visibility/playback operations reject another known team's conversation; a
+permission change in another team does not discard this team's observations.
+Ordinary shutdown waits for accepted local reading writes, while access withdrawal
+rejects late results. Retired asynchronous reading entries reject through promises;
+refresh/subscription teardown remains safe.

package/lib/runtime/batchedReadIndex.d.ts

@@ -1,6 +1,6 @@
-import { type ReadIndexPersistence, type ReadIndexState } from "./readIndex.js";
+import { type ReadIndexPersistence, type ReadIndexState, type ReadIndexTransform } from "./readIndex.js";
 type Change = {
-    transform: (state: ReadIndexState) => ReadIndexState;
+    transform: ReadIndexTransform;
     resolve: (state: ReadIndexState) => void;
     reject: (error: unknown) => void;
 };
@@ -15,6 +15,15 @@ export declare class BatchedReadIndex implements ReadIndexPersistence {
     private closed;
     constructor(storage: ReadIndexPersistence, windowMs?: number, batchSize?: number, queueLimit?: number);
     load(appId: string, profileId: string): Promise<ReadIndexState | undefined>;
+    loadVersioned(appId: string, profileId: string): Promise<{
+        state: ReadIndexState | undefined;
+        versions: import("./readIndex.js").ReadIndexVersions;
+    } | {
+        state: ReadIndexState | undefined;
+        versions: {};
+    }>;
+    loadVersions(appId: string, profileId: string): Promise<{}>;
+    invalidateTeam(appId: string, profileId: string, teamId: string, version: number, knownThreadIds?: readonly string[]): Promise<ReadIndexState>;
     update(appId: string, profileId: string, transform: Change["transform"]): Promise<ReadIndexState>;
     private drain;
     flush(appId: string, profileId: string): Promise<void>;

package/lib/runtime/batchedReadIndex.js

@@ -22,6 +22,26 @@ export class BatchedReadIndex {
             throw new Error("READ_STORAGE_CLOSED");
         return this.storage.load(appId, profileId);
     }
+    async loadVersioned(appId, profileId) {
+        await this.flush(appId, profileId);
+        if (this.closed)
+            throw new Error("READ_STORAGE_CLOSED");
+        return this.storage.loadVersioned ? this.storage.loadVersioned(appId, profileId) : { state: await this.storage.load(appId, profileId), versions: {} };
+    }
+    async loadVersions(appId, profileId) {
+        if (this.closed)
+            throw new Error("READ_STORAGE_CLOSED");
+        return this.storage.loadVersions ? this.storage.loadVersions(appId, profileId) : {};
+    }
+    async invalidateTeam(appId, profileId, teamId, version, knownThreadIds) {
+        if (this.closed)
+            throw new Error("READ_STORAGE_CLOSED");
+        if (!this.storage.invalidateTeam)
+            throw new Error("READ_SCOPE_INVALIDATION_UNAVAILABLE");
+        // Do not flush a blocked old HTTP transform first. The durable epoch is the
+        // barrier; any queued transform sees it inside its eventual transaction.
+        return this.storage.invalidateTeam(appId, profileId, teamId, version, knownThreadIds);
+    }
     update(appId, profileId, transform) {
         if (this.closed)
             return Promise.reject(new Error("READ_STORAGE_CLOSED"));
@@ -48,7 +68,7 @@ export class BatchedReadIndex {
             return;
         const run = (async () => {
             try {
-                const next = await this.storage.update(queue.appId, queue.profileId, state => batch.reduce((current, change) => change.transform(current), state));
+                const next = await this.storage.update(queue.appId, queue.profileId, (state, versions) => batch.reduce((current, change) => change.transform(current, versions), state));
                 batch.forEach(change => change.resolve(next));
             }
             catch (error) {

package/lib/runtime/cachedMessage.d.ts

@@ -0,0 +1,12 @@
+import type { ChatReaderSocialMessage } from "./readerClient.js";
+import type { ChatRuntimeMessage } from "./protocol.js";
+export type CachedChatMessage = ChatReaderSocialMessage & {
+    id: string;
+    timestamp: number;
+    readPolicy?: "visible" | "explicit";
+};
+export declare function decodeCachedChatMessage(message: ChatRuntimeMessage, scope: {
+    appId: string;
+    profileId: string;
+    teamId: string;
+}): CachedChatMessage | undefined;

package/lib/runtime/cachedMessage.js

@@ -0,0 +1,18 @@
+import { chatTeamId } from "./teamScope.js";
+import { dmThreadId, groupThreadId } from "./thread.js";
+export function decodeCachedChatMessage(message, scope) {
+    if (message.opcode !== 1 || !message.body || typeof message.body !== "object")
+        return;
+    const body = message.body;
+    const invitation = body.kind === "contact" && ["friendRequest", "requestFriend"].includes(String(body.action));
+    if ((!invitation && body.kind !== "message") || (invitation ? body.payload?.appId : body.content?.appId) !== scope.appId || chatTeamId(body) !== scope.teamId)
+        return;
+    const threadKind = invitation ? "dm" : body.threadKind;
+    if (threadKind !== "dm" && threadKind !== "group")
+        return;
+    if (threadKind === "dm" && message.from !== scope.profileId && message.to !== scope.profileId)
+        return;
+    const threadId = threadKind === "dm" ? dmThreadId(scope.appId, message.from, message.to, scope.teamId) : groupThreadId(scope.appId, message.to, scope.teamId);
+    return { appId: scope.appId, teamId: scope.teamId, threadId, threadKind, messageId: message.hash, id: message.hash,
+        timestamp: message.t, serverCreatedAt: message.t, clientCreatedAt: message.t, from: message.from, to: message.to, body: message.body, recipients: message.recipients };
+}

package/lib/runtime/chatClient.d.ts

@@ -62,6 +62,7 @@ export declare class ChatClient {
         profileId: string | undefined;
         accountId: string | undefined;
         teamId: string | undefined;
+        clientInstanceId: string;
     };
     watchConnection(handler: (state: ChatConnectionState) => void): () => void;
     private setConnection;

package/lib/runtime/chatClient.js

@@ -123,7 +123,7 @@ export class ChatClient {
     /** Non-secret identity used to validate a shared browser transport. */
     identityScope() {
         const identity = this.session?.identity ?? this.session?.session?.identity;
-        return { appId: this.options.appId, profileId: this.profileIdValue ?? this.options.profileId, accountId: identity?.accountId, teamId: this.options.teamId };
+        return { appId: this.options.appId, profileId: this.profileIdValue ?? this.options.profileId, accountId: identity?.accountId, teamId: this.options.teamId, clientInstanceId: this.instanceId };
     }
     watchConnection(handler) {
         this.connectionHandlers.add(handler);

package/lib/runtime/chatSession.d.ts

@@ -1,7 +1,12 @@
+import { type TimelineItem } from "./messageTimeline.js";
+import { type ReadingCandidate, type MessageReadingState } from "./conversationReading.js";
+import type { ConversationReadMessage } from "./conversationRead.js";
+import { type ReadCountsResult } from "./readCounts.js";
+import type { OnlineReachEvent } from "./reach.js";
 import { type MessageReadersQuery } from "./messageReaders.js";
-import { type MessageClientOptions } from "./messageClient.js";
+import { type MessageClientOptions, type MessageSnapshot } from "./messageClient.js";
 import { DurableChatSender } from "./durableSender.js";
-import { type ReadingClientOptions } from "./readingClient.js";
+import { ReadingClient, type ReadingClientOptions } from "./readingClient.js";
 import { ChatClient, type ChatClientOptions, type ChatConnectionState } from "./chatClient.js";
 import { unreadInConversation } from "./readIndex.js";
 import type { StoredMessage } from "./messageStore.js";
@@ -10,25 +15,33 @@ export type ChatSessionOptions<T extends StoredMessage> = {
     messages: MessageClientOptions<T>;
     connection: ChatClientOptions;
     sharedConnection?: ChatClient;
+    activeThreadId?: string;
     reading: ReadingClientOptions;
     decode: (message: ChatRuntimeMessage) => T | undefined;
+    readingCandidate?: (message: T) => ReadingCandidate | undefined;
     onError: (error: unknown) => void;
 };
 export type ChatThreadSnapshot<T> = {
     messages: readonly T[];
+    timeline: readonly TimelineItem<T>[];
     outgoing: ReturnType<DurableChatSender["snapshot"]>;
     hasEarlier: boolean;
-    unread: ReturnType<typeof unreadInConversation>;
+    resetVersion: number;
+    complete: boolean;
+    readCounts?: ReadCountsResult;
+    unread: ReturnType<typeof unreadInConversation> | undefined;
+    messageReading: Readonly<Record<string, MessageReadingState>>;
 };
 export type ChatSummarySnapshot<T> = {
     threads: readonly {
         threadId: string;
         lastMessage?: T;
+        lastItem?: TimelineItem<T>;
         unread: ChatThreadSnapshot<T>["unread"];
         outgoingCount: number;
     }[];
-    unreadMessageCount: number;
-    badgeCount: number;
+    unreadMessageCount: number | undefined;
+    badgeCount: number | undefined;
     connection: ChatConnectionState;
 };
 /** Owns all browser message clients. Hosts subscribe to stable thread snapshots. */
@@ -38,18 +51,57 @@ export declare class ChatSession<T extends StoredMessage> {
     private connection;
     private reading;
     private readers;
+    private counts?;
+    private countsReceiver?;
+    private countsThread?;
+    private countSnapshots;
+    private countClosings;
+    private countTasks;
     private sender;
     private listeners;
     private snapshots;
+    private timelineDecoded;
+    private decodeTimeline;
+    private historyEdges;
+    private earlierReads;
     private off;
     private globalListeners;
     private globalSnapshot?;
+    private closedThread;
+    private closedSummary;
     private connectionState;
+    private catchUp;
+    private readingAllowed;
+    private readingListeners;
+    private acceptedReading;
+    private readingAccess?;
+    private readingStarted;
+    private readingStarting?;
+    private withdrawn;
+    private revoking?;
     private closed;
     private starting?;
+    private initializing?;
     private closing?;
     constructor(options: ChatSessionOptions<T>);
     start(): Promise<void>;
+    /** Initializes local state and background reading sync without opening a
+     * second transport when the host already owns calls/presence. */
+    initialize(): Promise<void>;
+    private startReading;
+    /** One-time migration only: never establishes trusted history coverage. */
+    importLegacyMessages(threadId: string, messages: T[]): Promise<void>;
+    getReadingSnapshot(): import("./readIndex.js").ReadIndexState | undefined;
+    subscribeReading(listener: () => void): () => void;
+    private setReadingAllowed;
+    private readingAuthority;
+    private authorizeReading;
+    private readingOperation;
+    refreshReading(): void;
+    synchronizeReading(cursor?: string, profileId?: string): Promise<import("./readIndex.js").ReadIndexState>;
+    /** Explicit text-history acknowledgement; unheard audio stays unread. */
+    markRead(threadId: string, messages?: readonly ConversationReadMessage[]): Promise<import("./readIndex.js").ReadIndexState>;
+    updateReading(transform: Parameters<ReadingClient["update"]>[0]): Promise<import("./readIndex.js").ReadIndexState>;
     private assertOpen;
     getMessages(threadId: string, options?: {
         limit?: number;
@@ -57,7 +109,13 @@ export declare class ChatSession<T extends StoredMessage> {
             timestamp: number;
             id: string;
         };
-    }): Promise<import("./messageClient.js").MessageSnapshot<T>>;
+        earlier?: boolean;
+        all?: boolean;
+        refresh?: boolean;
+    }): Promise<MessageSnapshot<T>>;
+    private rememberHistoryEdge;
+    private readEarlier;
+    private readAll;
     sendMessage(threadId: string, input: {
         to: string;
         body: ChatBody;
@@ -65,14 +123,26 @@ export declare class ChatSession<T extends StoredMessage> {
     }): 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>;
+    observeMessages(threadId: string, ids: string[], event: "visible" | "played"): ReturnType<ReadingClient["recordVisible"]>;
+    observeMessages(threadId: string | undefined, ids: string[], event: "receipts", clientInstanceId?: string): Promise<void>;
+    /** Bridge transports can delegate social events without maintaining clients. */
+    handleReach(event: OnlineReachEvent): Promise<"handled" | undefined>;
+    private wakeCounts;
+    private publishCountSnapshot;
+    private publishCounts;
+    private watchCounts;
     getSnapshot(): ChatSummarySnapshot<T>;
     getSnapshot(threadId: string): ChatThreadSnapshot<T>;
+    private buildThreadSnapshot;
     subscribe(listener: () => void): () => void;
-    subscribe(threadId: string, listener: () => void): () => void;
+    subscribe(threadId: string, listener: () => void, fields?: readonly (keyof ChatThreadSnapshot<T>)[]): () => void;
     private publishAll;
     private buildGlobal;
     private publishGlobal;
     private publish;
+    /** Permanently retire this identity/team session. UI withdrawal is immediate;
+     * completion means all durable stores have crossed the same authority epoch. */
+    revokeAccess(): Promise<void>;
     close(): Promise<void>;
+    private dispose;
 }