@pmate/chat-sdk 0.12.0-next.7 → 0.12.0-next.70

package/lib/credentials.js

@@ -0,0 +1,110 @@
+import { ChatError } from "./chatError.js";
+/** Cancel the caller's wait, not the underlying shared operation. */
+export function waitForCaller(task, signal, onAbandonedValue) {
+    if (!signal)
+        return task;
+    if (signal.aborted) {
+        void task.then(value => onAbandonedValue?.(value), () => { });
+        return Promise.reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
+    }
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const abort = () => { if (settled)
+            return; settled = true; signal.removeEventListener("abort", abort); reject(signal.reason ?? new DOMException("Aborted", "AbortError")); };
+        signal.addEventListener("abort", abort, { once: true });
+        task.then(value => { signal.removeEventListener("abort", abort); if (settled) {
+            onAbandonedValue?.(value);
+            return;
+        } settled = true; resolve(value); }, error => { signal.removeEventListener("abort", abort); if (!settled) {
+            settled = true;
+            reject(error);
+        } });
+    });
+}
+/** One scoped credential owner; stale 401s share one refresh rather than cascading. */
+export class ChatCredentials {
+    provider;
+    origin;
+    transport;
+    lifetime = new AbortController();
+    flight;
+    refreshing;
+    latest;
+    recovery;
+    recoveredFrom = -1;
+    version = 0;
+    constructor(provider, origin, transport = fetch) {
+        this.provider = provider;
+        this.origin = origin;
+        this.transport = transport;
+    }
+    acquire(forceRefresh = false) {
+        if (this.lifetime.signal.aborted)
+            return Promise.reject(new ChatError("closed", "Chat credentials closed"));
+        if (this.refreshing)
+            return this.refreshing;
+        if (!forceRefresh && this.flight)
+            return this.flight;
+        const version = forceRefresh ? ++this.version : this.version;
+        const signal = AbortSignal.any([this.lifetime.signal, AbortSignal.timeout(15000)]);
+        const task = waitForCaller(Promise.resolve().then(() => this.provider({ forceRefresh, signal })), signal).then(token => {
+            if (this.lifetime.signal.aborted)
+                throw new ChatError("closed", "Chat credentials closed");
+            if (typeof token !== "string" || !token.trim())
+                throw new ChatError("authentication-required", "A valid access token is required");
+            if (version < this.version && this.latest)
+                return this.latest;
+            const value = { token, version };
+            this.latest = value;
+            return value;
+        }).catch(error => {
+            if (error?.status === 401)
+                throw new ChatError("authentication-required", "Credentials require a fresh login", { cause: error, status: 401 });
+            if (error?.status === 403)
+                throw new ChatError("access-denied", "Credential access denied", { cause: error, status: 403 });
+            throw error;
+        }).finally(() => { if (this.flight === task)
+            this.flight = undefined; if (this.refreshing === task)
+            this.refreshing = undefined; });
+        if (forceRefresh)
+            this.refreshing = task;
+        else
+            this.flight = task;
+        return task;
+    }
+    recover(used) {
+        if (this.latest && this.latest.version > used.version)
+            return Promise.resolve(this.latest);
+        if (this.recovery && used.version <= this.recoveredFrom)
+            return this.recovery;
+        this.recoveredFrom = used.version;
+        this.recovery = this.acquire(true);
+        return this.recovery;
+    }
+    getToken = async () => { return (await this.acquire()).token; };
+    fetch = async (input, init) => {
+        const transport = this.transport;
+        const url = new URL(input instanceof Request ? input.url : String(input)), headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
+        // Never attach an app credential to uploads, other origins or unauthenticated requests.
+        if (url.origin !== this.origin || !headers.has("authorization"))
+            return transport(input, init);
+        const callerSignal = init?.signal ?? (input instanceof Request ? input.signal : undefined);
+        const signal = AbortSignal.any([this.lifetime.signal, ...(callerSignal ? [callerSignal] : [])]);
+        signal?.throwIfAborted();
+        const original = input instanceof Request ? input.clone() : input;
+        const send = async (token) => {
+            signal?.throwIfAborted();
+            headers.set("authorization", `Bearer ${token}`);
+            return transport(original instanceof Request ? original.clone() : original, { ...init, headers, signal });
+        };
+        const used = await waitForCaller(this.acquire(), signal ?? undefined);
+        const response = await send(used.token);
+        if (response.status !== 401)
+            return response;
+        // Denial (403) is terminal. Only an unauthenticated response gets one replay.
+        void response.body?.cancel().catch(() => { });
+        const next = await waitForCaller(this.recover(used), signal);
+        return send(next.token);
+    };
+    close() { this.lifetime.abort(new ChatError("closed", "Chat credentials closed")); }
+}

package/lib/fileMetadata.d.ts

@@ -0,0 +1,9 @@
+/** Durable file reference. Upload limits and download policy belong to the host. */
+export type ChatFile = Readonly<{
+    url: string;
+    name: string;
+    size: number;
+    mimeType?: string;
+    expiresAt?: number;
+}>;
+export declare function parseChatFile(value: unknown): ChatFile | undefined;

package/lib/fileMetadata.js

@@ -0,0 +1,18 @@
+export function parseChatFile(value) {
+    if (!value || typeof value !== "object")
+        return;
+    const file = value;
+    if (typeof file.name !== "string" || !file.name.trim() || file.name.length > 255 || /[\u0000-\u001f\\/]/u.test(file.name) || typeof file.url !== "string" || file.url.length > 8192 || !Number.isSafeInteger(file.size) || Number(file.size) < 0)
+        return;
+    try {
+        const url = new URL(file.url);
+        if (url.protocol !== "https:" || url.username || url.password)
+            return;
+    }
+    catch {
+        return;
+    }
+    return { url: file.url, name: file.name, size: file.size,
+        ...(typeof file.mimeType === "string" && file.mimeType.length <= 255 && !/[\r\n]/.test(file.mimeType) ? { mimeType: file.mimeType } : {}),
+        ...(typeof file.expiresAt === "number" && Number.isSafeInteger(file.expiresAt) && file.expiresAt > 0 ? { expiresAt: file.expiresAt } : {}), };
+}

package/lib/framework.d.ts

@@ -0,0 +1,11 @@
+import type { Chat } from "./chatContract.js";
+import type { ChatSnapshot, ChatThreadSnapshot } from "./chatTypes.js";
+export interface ChatStore {
+    subscribeThread(threadId: string, listener: () => void, fields?: readonly (keyof ChatThreadSnapshot)[]): () => void;
+    getSnapshot(): ChatSnapshot;
+    getSnapshot(threadId: string): ChatThreadSnapshot;
+    subscribeChanges(listener: () => void): () => void;
+    subscribeChanges(threadId: string, listener: () => void, fields?: readonly (keyof ChatThreadSnapshot)[]): () => void;
+}
+/** Synchronous memory reads are for external-store integrations, not cache selection. */
+export declare function getChatStore(chat: Chat): ChatStore;

package/lib/framework.js

@@ -0,0 +1,12 @@
+import { chatEngine } from "./internal/chatRegistry.js";
+const stores = new WeakMap();
+/** Synchronous memory reads are for external-store integrations, not cache selection. */
+export function getChatStore(chat) {
+    let store = stores.get(chat);
+    if (!store) {
+        const engine = chatEngine(chat);
+        store = { subscribeThread: (id, listener, fields) => engine.subscribeThread(id, listener, { fields, emitCurrent: false }), getSnapshot: ((id) => id === undefined ? engine.getSnapshot() : engine.getSnapshot(id)), subscribeChanges: ((target, callback, fields) => typeof target === "function" ? engine.subscribe(target, { emitCurrent: false }) : engine.subscribe(target, callback, { fields, emitCurrent: false })) };
+        stores.set(chat, store);
+    }
+    return store;
+}

package/lib/history.d.ts

@@ -0,0 +1,4 @@
+import type { Chat } from "./chatContract.js";
+import type { ChatThreadSnapshot, ReadOptions } from "./chatTypes.js";
+/** Explicit complete-history operation for search/export; may scan many pages. */
+export declare function loadThreadHistory(chat: Chat, threadId: string, { signal }?: ReadOptions): Promise<ChatThreadSnapshot>;

package/lib/history.js

@@ -0,0 +1,8 @@
+import { chatEngine } from "./internal/chatRegistry.js";
+import { waitForCaller } from "./credentials.js";
+/** Explicit complete-history operation for search/export; may scan many pages. */
+export function loadThreadHistory(chat, threadId, { signal } = {}) {
+    if (signal?.aborted)
+        return Promise.reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
+    return waitForCaller(chatEngine(chat).getMessages(threadId, { all: true }), signal);
+}

package/lib/hooks/useChatSnapshot.d.ts

@@ -0,0 +1,4 @@
+import type { Chat, ChatSnapshot, ChatThreadSnapshot } from "../chat.js";
+/** React consumes the same stable view as callback subscribers. No App-side cache. */
+export declare function useChatSnapshot(chat: Chat | undefined): ChatSnapshot;
+export declare function useChatSnapshot(chat: Chat | undefined, threadId: string): ChatThreadSnapshot;

package/lib/hooks/useChatSnapshot.js

@@ -0,0 +1,9 @@
+import { useCallback, useSyncExternalStore } from "react";
+import { getChatStore } from "../framework.js";
+const emptySummary = Object.freeze({ threads: [], unreadMessageCount: undefined, badgeCount: undefined, connection: "closed" });
+const emptyThread = Object.freeze({ threadId: "", messages: [], status: "pending", ready: false, hasEarlier: false, unread: undefined, group: undefined, readCounts: undefined });
+export function useChatSnapshot(chat, threadId) {
+    const subscribe = useCallback((notify) => !chat ? () => { } : threadId === undefined ? getChatStore(chat).subscribeChanges(notify) : getChatStore(chat).subscribeThread(threadId, notify), [chat, threadId]);
+    const snapshot = useCallback(() => threadId === undefined ? (chat ? getChatStore(chat).getSnapshot() : undefined) ?? emptySummary : (chat ? getChatStore(chat).getSnapshot(threadId) : undefined) ?? emptyThread, [chat, threadId]);
+    return useSyncExternalStore(subscribe, snapshot, () => threadId === undefined ? emptySummary : emptyThread);
+}

package/lib/index.d.ts

@@ -41,3 +41,5 @@ export * from "./runtime/socialReadClient";
 export * from "./ux/imagePaste";
 export * from "./hooks/useImageAttachments";
 export * from "./components/ImageAttachmentTray";
+export { createChat, type Chat, ChatError, type ChatThreadSnapshot, type ChatMessage as MessageView, type ChatErrorCode, type ConversationTarget, type OutgoingContent, type CreateChatOptions, type ChatSnapshot, type SentMessage, type ReadOptions, type ReadersQuery, type GroupChanges } from "./chat.js";
+export { useChatSnapshot } from "./hooks/useChatSnapshot.js";

package/lib/index.js

@@ -41,3 +41,5 @@ export * from "./runtime/socialReadClient";
 export * from "./ux/imagePaste";
 export * from "./hooks/useImageAttachments";
 export * from "./components/ImageAttachmentTray";
+export { createChat, ChatError } from "./chat.js";
+export { useChatSnapshot } from "./hooks/useChatSnapshot.js";

package/lib/internal/chatEngine.d.ts

@@ -0,0 +1,131 @@
+export type { ChatMessage } from "../chatTypes.js";
+import { type CreateChatOptions } from "../runtime/createChat.js";
+import type { ChatSession } from "../runtime/chatSession.js";
+import type { CachedChatMessage } from "../runtime/cachedMessage.js";
+import type { ConversationTarget } from "../runtime/conversationDirectory.js";
+import type { OutgoingContent as RuntimeContent } from "../runtime/outgoingContent.js";
+export { ChatError } from "../chatError.js";
+export type { ChatErrorCode } from "../chatError.js";
+export type { CreateChatOptions, ConversationTarget };
+export type OutgoingContent = Exclude<RuntimeContent, {
+    groupCreate: unknown;
+} | {
+    groupUpdate: unknown;
+}>;
+import type { ChatThreadSnapshot, ChatSnapshot, ReadOptions } from "../chatTypes.js";
+export type { ChatGroup, ConversationInfo, ChatThreadSnapshot, ChatSnapshot, ReadOptions } from "../chatTypes.js";
+export type MessageQuery = {
+    earlier?: boolean;
+    all?: boolean;
+    refresh?: boolean;
+};
+export type ReadersQuery = {
+    afterProfileId?: string;
+    revision?: number;
+};
+export type GroupChanges = {
+    expectedRevision?: string;
+    addMembers?: readonly string[];
+    removeMembers?: readonly string[];
+    title?: string;
+    avatar?: string;
+};
+export type SendOptions = {
+    waitFor?: "accepted" | "delivered";
+};
+export type SentMessage = Readonly<{
+    id: string;
+    timestamp: number;
+}>;
+type SubscribeOptions<T> = {
+    fields?: readonly (keyof T)[];
+    emitCurrent?: boolean;
+};
+/** App-facing API. Cache coverage, raw protocol and synchronization stay in advanced. */
+export declare class ChatEngine {
+    readonly advanced: ChatSession<CachedChatMessage>;
+    private options;
+    private groups;
+    private group;
+    private present;
+    private redactedQuotes;
+    private messageLists;
+    private messages;
+    private views;
+    private summary?;
+    private targets;
+    private errors;
+    private listeners;
+    private closed;
+    constructor(advanced: ChatSession<CachedChatMessage>, options: CreateChatOptions);
+    private operation;
+    private deny;
+    private threadOperation;
+    start(): Promise<void>;
+    /** Resolve a scoped ID locally, registering its target when needed. No remote group is created. */
+    resolveThreadId(target: ConversationTarget): Promise<string>;
+    /** A trusted recent window. Source selection and synchronization belong to the SDK. */
+    getThread(threadId: string, options?: ReadOptions): Promise<ChatThreadSnapshot>;
+    loadEarlier(threadId: string, options?: ReadOptions): Promise<ChatThreadSnapshot>;
+    refreshThread(threadId: string, options?: ReadOptions): Promise<ChatThreadSnapshot>;
+    private readForCaller;
+    private threadSubscribers;
+    private openQueue;
+    private opening;
+    private drainOpens;
+    /** Listen first, then open the local window; concurrent consumers share the initial read. */
+    subscribeThread(threadId: string, listener: (snapshot: ChatThreadSnapshot) => void, options?: SubscribeOptions<ChatThreadSnapshot>): () => void;
+    /** @deprecated Use resolveThreadId. Retained only for the migration window. */
+    getConversation(target: ConversationTarget): Promise<string>;
+    getSnapshot(): ChatSnapshot;
+    getSnapshot(threadId: string): ChatThreadSnapshot;
+    getMessages(threadId: string, query?: MessageQuery): Promise<ChatThreadSnapshot>;
+    sendMessage(threadId: string, content: OutgoingContent, options?: SendOptions): Promise<SentMessage>;
+    retryMessage(messageId: string): Promise<SentMessage>;
+    subscribe(listener: (snapshot: ChatSnapshot) => void, options?: SubscribeOptions<ChatSnapshot>): () => void;
+    subscribe(threadId: string, listener: (snapshot: ChatThreadSnapshot) => void, options?: SubscribeOptions<ChatThreadSnapshot>): () => void;
+    private sessionFields;
+    private notify;
+    observeMessages(threadId: string, ids: string[], event: "visible" | "played"): Promise<void>;
+    markRead(threadId: string): Promise<void>;
+    getReaders(threadId: string, messageId: string, page?: ReadersQuery, signal?: AbortSignal): Promise<import("../runtime/messageReaders.js").MessageReadersPage>;
+    watchReaders(threadId: string | undefined, ids: string[], receiver?: string): Promise<void>;
+    handleReach(event: Parameters<ChatSession<CachedChatMessage>["handleReach"]>[0]): Promise<"handled" | undefined>;
+    getVoiceAttachment(threadId: string, messageId: string): Promise<import("../runtime/durableSender.js").VoiceAttachmentLease>;
+    getGroup(threadId: string, options?: {
+        refresh?: boolean;
+    }): Promise<Readonly<{
+        groupId: string;
+        teamId: string;
+        ownerId: string;
+        title: string;
+        avatar?: string;
+        memberIds: readonly string[];
+        revision: string;
+    }>>;
+    createGroup(input: {
+        groupId?: string;
+        title: string;
+        members: readonly string[];
+    }): Promise<{
+        threadId: string;
+        groupId: string;
+        teamId: string;
+        ownerId: string;
+        title: string;
+        avatar?: string;
+        memberIds: readonly string[];
+        revision: string;
+    }>;
+    updateGroup(threadId: string, changes: GroupChanges): Promise<Readonly<{
+        groupId: string;
+        teamId: string;
+        ownerId: string;
+        title: string;
+        avatar?: string;
+        memberIds: readonly string[];
+        revision: string;
+    }>>;
+    revokeAccess(): Promise<void>;
+    close(): Promise<void>;
+}

package/lib/internal/chatEngine.js

@@ -0,0 +1,280 @@
+import { createMessagePresenter } from "../messageView.js";
+import { createChat as createSession } from "../runtime/createChat.js";
+import { asChatError } from "../runtime/chatError.js";
+import { ChatError } from "../chatError.js";
+export { ChatError } from "../chatError.js";
+const emptyMessages = Object.freeze([]);
+/** App-facing API. Cache coverage, raw protocol and synchronization stay in advanced. */
+export class ChatEngine {
+    advanced;
+    options;
+    groups = new WeakMap();
+    group(value) {
+        if (!value)
+            return undefined;
+        let projected = this.groups.get(value);
+        if (!projected) {
+            const { versionNumber: _, ...visible } = value;
+            projected = visible;
+            this.groups.set(value, projected);
+        }
+        return projected;
+    }
+    present = createMessagePresenter();
+    redactedQuotes = new WeakMap();
+    messageLists = new WeakMap();
+    messages(items) {
+        let values = this.messageLists.get(items);
+        if (!values) {
+            const recalled = new Set(items.filter(item => item.recalled).map(item => item.id));
+            values = items.map(item => {
+                const value = this.present(item);
+                if (!value.quote?.messageId || !recalled.has(value.quote.messageId))
+                    return value;
+                let hidden = this.redactedQuotes.get(value);
+                if (!hidden) {
+                    hidden = { ...value, quote: { ...value.quote, content: "", recalled: true } };
+                    this.redactedQuotes.set(value, hidden);
+                }
+                return hidden;
+            });
+            this.messageLists.set(items, values);
+        }
+        return values;
+    }
+    views = new Map();
+    summary;
+    targets = new Map();
+    errors = new Map();
+    listeners = new Map();
+    closed = false;
+    constructor(advanced, options) {
+        this.advanced = advanced;
+        this.options = options;
+    }
+    async operation(run) { try {
+        return await run();
+    }
+    catch (error) {
+        throw asChatError(error);
+    } }
+    async deny(threadId, failure) {
+        this.errors.set(threadId, failure);
+        this.targets.delete(threadId);
+        const retiring = this.advanced.revokeAccess();
+        this.notify(threadId);
+        try {
+            await retiring;
+        }
+        catch (error) {
+            failure.cause = new AggregateError([failure.cause, error], "Access withdrawn; cache cleanup incomplete");
+        }
+    }
+    threadOperation(threadId, run) {
+        return this.operation(async () => {
+            const denied = threadId ? this.errors.get(threadId) : undefined;
+            if (denied?.code === "access-denied")
+                throw denied;
+            try {
+                return await run();
+            }
+            catch (error) {
+                const failure = asChatError(error);
+                if (threadId && failure.code === "access-denied")
+                    await this.deny(threadId, failure);
+                throw failure;
+            }
+        });
+    }
+    start() { return this.operation(() => this.options.connection ? this.advanced.initialize() : this.advanced.start()); }
+    /** Resolve a scoped ID locally, registering its target when needed. No remote group is created. */
+    resolveThreadId(target) { return this.getConversation(target); }
+    /** A trusted recent window. Source selection and synchronization belong to the SDK. */
+    getThread(threadId, options = {}) { return this.readForCaller(() => this.getMessages(threadId), options); }
+    loadEarlier(threadId, options = {}) { return this.readForCaller(() => this.getMessages(threadId, { earlier: true }), options); }
+    refreshThread(threadId, options = {}) { return this.readForCaller(() => this.getMessages(threadId, { refresh: true }), options); }
+    readForCaller(run, { signal }) {
+        if (signal?.aborted)
+            return Promise.reject(signal.reason ?? new DOMException("The operation was aborted", "AbortError"));
+        if (!signal)
+            return run();
+        // A caller's cancellation never aborts another subscriber's shared read.
+        return new Promise((resolve, reject) => {
+            const abort = () => { signal.removeEventListener("abort", abort); reject(signal.reason ?? new DOMException("The operation was aborted", "AbortError")); };
+            signal.addEventListener("abort", abort, { once: true });
+            run().then(value => { signal.removeEventListener("abort", abort); resolve(value); }, error => { signal.removeEventListener("abort", abort); reject(error); });
+        });
+    }
+    threadSubscribers = new Map();
+    openQueue = new Set();
+    opening = 0;
+    drainOpens() {
+        while (!this.closed && this.opening < 4 && this.openQueue.size) {
+            const id = this.openQueue.values().next().value;
+            this.openQueue.delete(id);
+            if (!this.threadSubscribers.has(id))
+                continue;
+            this.opening++;
+            void this.getThread(id).catch(() => { }).finally(() => { this.opening--; this.drainOpens(); });
+        }
+    }
+    /** Listen first, then open the local window; concurrent consumers share the initial read. */
+    subscribeThread(threadId, listener, options = {}) {
+        const off = this.subscribe(threadId, listener, options), count = this.threadSubscribers.get(threadId) ?? 0;
+        this.threadSubscribers.set(threadId, count + 1);
+        if (!count) {
+            this.openQueue.add(threadId);
+            this.drainOpens();
+        }
+        let disposed = false;
+        return () => {
+            if (disposed)
+                return;
+            disposed = true;
+            off();
+            const remaining = (this.threadSubscribers.get(threadId) ?? 1) - 1;
+            if (remaining)
+                this.threadSubscribers.set(threadId, remaining);
+            else {
+                this.threadSubscribers.delete(threadId);
+                this.openQueue.delete(threadId);
+            }
+        };
+    }
+    /** @deprecated Use resolveThreadId. Retained only for the migration window. */
+    getConversation(target) {
+        return this.operation(async () => {
+            const id = await this.advanced.getConversation(target);
+            const value = target.groupId !== undefined ? { kind: "group", targetId: target.groupId } : { kind: "dm", targetId: target.peerId };
+            this.targets.delete(id);
+            this.targets.set(id, value);
+            if (this.targets.size > 256)
+                this.targets.delete(this.targets.keys().next().value);
+            this.notify(id);
+            return id;
+        });
+    }
+    getSnapshot(threadId) {
+        if (threadId === undefined) {
+            const source = this.advanced.getSnapshot(), previous = this.summary;
+            const threads = source.threads.filter(thread => this.errors.get(thread.threadId)?.code !== "access-denied").map(thread => ({ threadId: thread.threadId, lastMessage: this.messages(this.advanced.getSnapshot(thread.threadId).timeline).at(-1), group: this.group(thread.group), unread: thread.unread, outgoingCount: thread.outgoingCount }));
+            const unreadMessageCount = source.unreadMessageCount === undefined ? undefined : threads.reduce((sum, thread) => sum + (thread.unread?.unreadMessageCount ?? 0), 0);
+            const badgeCount = source.badgeCount === undefined ? undefined : threads.reduce((sum, thread) => sum + (thread.unread?.badgeCount ?? 0), 0);
+            if (previous && previous.connection === source.connection && previous.badgeCount === badgeCount && previous.unreadMessageCount === unreadMessageCount && previous.threads.length === threads.length && threads.every((thread, i) => { const old = previous.threads[i]; return thread.threadId === old.threadId && thread.lastMessage === old.lastMessage && thread.group === old.group && thread.unread === old.unread && thread.outgoingCount === old.outgoingCount; }))
+                return previous;
+            return this.summary = { threads, connection: source.connection, badgeCount, unreadMessageCount };
+        }
+        const source = this.advanced.getSnapshot(threadId), previous = this.views.get(threadId);
+        const error = this.closed ? undefined : this.errors.get(threadId), denied = error?.code === "access-denied";
+        const target = this.closed || !this.advanced.active || denied ? undefined : this.advanced.getConversationTarget(threadId) ?? this.targets.get(threadId);
+        const conversation = previous?.conversation?.kind === target?.kind && previous?.conversation?.targetId === target?.targetId ? previous?.conversation : target ? { kind: target.kind, targetId: target.targetId } : undefined;
+        // Partial migrated rows never masquerade as a trusted recent window.
+        const next = { threadId, conversation, messages: !denied && source.complete ? this.messages(source.timeline) : emptyMessages, ready: !denied && source.complete, hasEarlier: !denied && source.hasEarlier, unread: denied ? undefined : source.unread, group: denied ? undefined : this.group(source.group), readCounts: denied ? undefined : source.readCounts, error, status: !denied && source.complete ? "ready" : error ? "error" : "pending" };
+        if (previous && Object.keys(next).every(key => next[key] === previous[key]))
+            return previous;
+        this.views.set(threadId, next);
+        return next;
+    }
+    async getMessages(threadId, query = {}) {
+        try {
+            if (Object.keys(query).some(key => !["earlier", "all", "refresh"].includes(key)))
+                throw new ChatError("invalid-input", "Unsupported message query");
+            const page = await this.advanced.getMessages(threadId, query);
+            if (!page.complete)
+                throw new ChatError("unavailable", "Messages are not ready; retry when connected");
+            this.errors.delete(threadId);
+            this.notify(threadId);
+            return this.getSnapshot(threadId);
+        }
+        catch (error) {
+            const failure = asChatError(error);
+            if (!this.closed) {
+                if (failure.code === "access-denied")
+                    await this.deny(threadId, failure);
+                else {
+                    this.errors.set(threadId, failure);
+                    this.notify(threadId);
+                }
+            }
+            throw failure;
+        }
+    }
+    sendMessage(threadId, content, options = {}) {
+        return this.threadOperation(threadId, async () => {
+            if (content && ("groupCreate" in content || "groupUpdate" in content))
+                throw new ChatError("invalid-input", "Use createGroup or updateGroup for group changes");
+            const result = await this.advanced.sendMessage(threadId, content, options);
+            return { id: result.hash, timestamp: result.t };
+        });
+    }
+    retryMessage(messageId) { return this.operation(async () => { const result = await this.advanced.retryMessage(messageId); return { id: result.hash, timestamp: result.t }; }); }
+    subscribe(target, callback, options = {}) {
+        const global = typeof target === "function", key = global ? "" : target;
+        const config = global ? callback : options;
+        const read = () => global ? this.getSnapshot() : this.getSnapshot(key);
+        let previous = read();
+        const emit = () => {
+            const value = read();
+            const fields = config?.fields;
+            const changed = fields ? fields.some(field => previous[field] !== value[field]) : value !== previous;
+            previous = value;
+            if (changed) {
+                try {
+                    (global ? target : callback)(value);
+                }
+                catch (error) {
+                    try {
+                        this.options.onError(error);
+                    }
+                    catch { /* A consumer cannot break other consumers or cache publication. */ }
+                }
+            }
+        };
+        let listeners = this.listeners.get(key);
+        if (!listeners) {
+            listeners = new Set();
+            this.listeners.set(key, listeners);
+        }
+        listeners.add(emit);
+        const off = global ? this.advanced.subscribeChanges(emit) : this.advanced.subscribeChanges(key, emit, this.sessionFields(options.fields));
+        const dispose = () => { off(); listeners.delete(emit); if (!listeners.size)
+            this.listeners.delete(key); };
+        if (config?.emitCurrent !== false) {
+            try {
+                (global ? target : callback)(previous);
+            }
+            catch (error) {
+                dispose();
+                throw error;
+            }
+        }
+        return dispose;
+    }
+    sessionFields(fields) {
+        return fields ? [...new Set(fields.flatMap(field => field === "messages" ? ["timeline", "complete"] : field === "ready" || field === "status" ? ["complete"] : field === "conversation" ? ["messages", "group"] : field === "error" || field === "threadId" ? [] : [field]))] : undefined;
+    }
+    notify(threadId) { this.listeners.get(threadId)?.forEach(listener => listener()); this.listeners.get("")?.forEach(listener => listener()); }
+    observeMessages(threadId, ids, event) { return this.threadOperation(threadId, async () => { await this.advanced.observeMessages(threadId, ids, event); }); }
+    markRead(threadId) { return this.threadOperation(threadId, async () => { await this.advanced.markRead(threadId); }); }
+    getReaders(threadId, messageId, page = {}, signal) {
+        return this.threadOperation(threadId, async () => {
+            if (Object.keys(page).some(key => !["afterProfileId", "revision"].includes(key)))
+                throw new ChatError("invalid-input", "Unsupported reader query");
+            return this.advanced.getReaders(threadId, messageId, page, signal);
+        });
+    }
+    watchReaders(threadId, ids, receiver) { return this.threadOperation(threadId, () => this.advanced.observeMessages(threadId, ids, "receipts", receiver)); }
+    handleReach(event) { return this.operation(() => this.advanced.handleReach(event)); }
+    getVoiceAttachment(threadId, messageId) { return this.threadOperation(threadId, () => this.advanced.getVoiceAttachment(threadId, messageId)); }
+    getGroup(threadId, options = {}) { return this.threadOperation(threadId, async () => this.group(await this.advanced.getGroup(threadId, options))); }
+    createGroup(input) {
+        return this.operation(async () => {
+            const groupId = input.groupId ?? crypto.randomUUID(), threadId = await this.getConversation({ groupId });
+            const group = await this.advanced.createGroup({ id: threadId, kind: "group", targetId: groupId, teamId: this.options.teamId }, { title: input.title, members: input.members });
+            return { ...this.group(group), threadId };
+        });
+    }
+    updateGroup(threadId, changes) { return this.threadOperation(threadId, async () => this.group(await this.advanced.updateGroup(threadId, changes))); }
+    revokeAccess() { return this.operation(() => this.advanced.revokeAccess()); }
+    close() { this.closed = true; return this.operation(() => this.advanced.close()).finally(() => { this.errors.clear(); this.targets.clear(); this.listeners.clear(); this.threadSubscribers.clear(); this.openQueue.clear(); this.views.clear(); this.summary = undefined; this.present = createMessagePresenter(); this.messageLists = new WeakMap(); this.groups = new WeakMap(); this.redactedQuotes = new WeakMap(); }); }
+}

package/lib/internal/chatRegistry.d.ts

@@ -0,0 +1,4 @@
+import type { Chat } from "../chatContract.js";
+import type { ChatEngine } from "./chatEngine.js";
+export declare function registerChat(chat: Chat, engine: ChatEngine): void;
+export declare function chatEngine(chat: Chat): ChatEngine;

package/lib/internal/chatRegistry.js

@@ -0,0 +1,4 @@
+const engines = new WeakMap();
+export function registerChat(chat, engine) { engines.set(chat, engine); }
+export function chatEngine(chat) { const engine = engines.get(chat); if (!engine)
+    throw new TypeError("Unknown Chat client"); return engine; }

package/lib/internal/createPublicChat.d.ts

@@ -0,0 +1,4 @@
+import type { Chat } from "../chatContract.js";
+import { type CreateChatOptions } from "../runtime/createChat.js";
+/** Build only the public capabilities; no aliases or engine fields on the returned object. */
+export declare function createPublicChat(options: CreateChatOptions): Chat;