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

package/README.md

@@ -39,7 +39,7 @@ A dropped socket (including a network change or a suspended laptop) previously r
 
 `client.watchConnection(handler)` immediately reports the current state and returns an unsubscribe function. States are `connecting`, `reconnecting`, `authenticating`, `connected`, `authentication_required`, and `closed`. Only `connected` means the Hub acknowledged authentication. A rejected authentication stops retries; supply a fresh login session using a new client. `close()` cancels retries, heartbeat timers and browser wake listeners.
 
-Messages sent without an acknowledgement are rejected on disconnect and are **not replayed**: delivery is uncertain, so automatic retries could duplicate them. Callers should preserve drafts, display a reconnecting state, and refresh message history after recovery. No durable offline outbox is provided. An initial `connect()` wait times out after 30 seconds, but recovery continues until explicitly closed; retain the client and observe its connection state.
+The low-level `ChatClient.sendChat` rejects unacknowledged sends on disconnect and does not provide a durable outbox. Browser applications should use `createChat().sendMessage` below, which persists the exact wire in IndexedDB and owns delivery state and retries. An initial `connect()` wait times out after 30 seconds, but recovery continues until explicitly closed; retain the client and observe its connection state.
 
 ## Versioned Markdown and chart content
 
@@ -128,93 +128,182 @@ The handler leaves text-only pastes and events already handled by the host untou
 
 Only send on explicit submission: block send while `pending`, deliver each ready attachment's `url`, and remove it after delivery succeeds. Keep unsuccessful drafts to allow retry without reuploading. For `ChatInputDesktop`, use `hasPendingContent` and `sendDisabled` with host-owned drafts. Unmount or key the draft owner when switching accounts, Teams or conversations.
 
-## Browser message and reading data
+## Browser messages
 
 ### Background
 
-Message hosts previously coordinated remote history, offline snapshots, optimistic
-sends and reading synchronization independently. The runtime now provides local
-IndexedDB storage and fixed-window scheduling primitives so those operations can
-share bounded I/O, durable confirmation and scoped subscriptions.
-
-The browser entry point is `createChat` from `@pmate/chat-sdk/runtime`:
+App code should render messages and report actual user actions. IndexedDB,
+trusted recent windows, synchronization, recipients, retries and read rules belong
+to the SDK. The default API presents one semantic message list, including delivery,
+recalls and reactions. It never presents a partial migration as a ready window.
 
 ```ts
-const chat = createChat({ appId, accountId, profileId, teamId, token, onError })
+import {createChat} from "@pmate/chat-sdk/chat"
+const chat = createChat({appId, accountId, profileId, teamId,
+  getToken: ({forceRefresh, signal}) => auth.getAccessToken({forceRefresh, signal}),
+})
 await chat.start()
-const page = await chat.getMessages(threadId, { limit: 50 })
-// 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()))
+const threadId = await chat.resolveThreadId({peerId}) // or {groupId}; no remote creation
+const off = chat.subscribeThread(threadId, state => {
+  if (state.status === "ready") render(state.messages)
+  else if (state.status === "error") showRetry(state.error)
+}) // listens first, opens local state, then owns background synchronization
+await chat.sendMessage(threadId, {text: "Hello"})
+await chat.loadEarlier(threadId)
+off()
+await chat.close()
+```
+
+`getThread(id)` is the one-shot equivalent; it returns the same stable snapshot
+as `subscribeThread`. Cache hits do not repeat history requests. `loadEarlier(id)`
+extends the SDK window without limits or cursors. `refreshThread(id)` explicitly
+reconciles authority; ordinary reconnect/wake synchronization is automatic.
+For a cold route, keep the usable list visible until `getThread` resolves, or
+until a subscription delivers `status: "ready"`; no intermediate message loader
+is necessary. Subscription initialization has four bounded concurrent lanes.
+Multiple consumers share work; disposing one does not stop another consumer.
+
+Thread state is `pending`, `ready`, or `error`. A failed initial read is `error`;
+a failed background refresh retains `ready` messages and includes `error`.
+`ready` is retained as a derived compatibility field; use `status` in new code.
+Connection state is independent. A snapshot also contains `hasEarlier`, `unread`,
+`group`, `readCounts` and scoped target identity. Unknown unread stays undefined.
+`subscribeChat` delivers known conversation summaries and aggregate reading state.
+Subscriptions emit their current snapshot first, then meaningful changes only;
+`fields` filters notifications. Callbacks cannot corrupt a shared cache read.
+Opening or subscribing does not mark messages read.
+
+Messages provide kind/text/image/voice/quote, reactions and reading/delivery state.
+No raw wire or control revision is needed. The public models do not derive their
+types from Session, storage or projection internals. Object references stay stable
+when content has not changed. React `useChatSnapshot(chat, threadId)` manages the
+external-store subscription; custom integrations use `getChatStore` from
+`@pmate/chat-sdk/framework`, where synchronous memory snapshots and change-only
+notifications are explicitly separated from ordinary asynchronous reads.
+
+`getThread`, `loadEarlier`, `refreshThread`, `getGroup`, `refreshGroup`,
+`resolveThreadId`, and `getVoiceAttachment` accept `{signal}`. Reader queries accept
+`{afterProfileId, revision, signal}`. Aborting rejects that consumer with the signal
+reason (normally AbortError); it does not abort shared work, publish a fake cache
+failure, or undo a durable send. A late abandoned voice lease is released.
+Complete-history search/export is an explicit, potentially large operation:
+`loadThreadHistory(chat, id, {signal})` from `@pmate/chat-sdk/history`. It traverses
+accessible history and rejects incomplete scans. It is not a flag on normal reads.
+
+The credential provider is invoked on connection/reconnection and authenticated
+HTTP reads; concurrent requests share acquisition. HTTP 401 gets one coalesced
+forced refresh and at most one replay. HTTP 403 is never retried automatically.
+Providers must preserve account/app/profile identity. A fixed `token` remains
+supported as an alternative; select one source. An ambiguous WebSocket AUTH_FAILED
+requires authentication rather than guessing that a permission failure expired.
+Closing fences late providers and prevents further authenticated network work.
+
+Sending accepts text/mentions/quotes, images, files, voice, recalls, reactions and
+invitations through the same typed content union. The SDK resolves the target
+and group roster, expands @all and assigns reaction revisions. The default
+Promise resolves after durable acceptance and returns `{id,timestamp}`; outgoing
+status is part of the same message list. `{waitFor:"delivered"}` waits for the
+server acknowledgement. `retryMessage(id)` retries a failed exact wire.
+
+```ts
+await chat.sendMessage(threadId, {file:{url,name,size,mimeType}}) // uploaded HTTPS metadata
+await chat.sendMessage(threadId, {voice:{blob,durationMs}})
+await chat.sendMessage(threadId, {reaction:{messageId,emojiId,active:true}})
+await chat.sendMessage(threadId, {recall:{messageId}}, {waitFor:"delivered"})
 await chat.observeMessages(threadId, visibleIds, "visible")
-// Report only the actual audio `playing` event.
-await chat.observeMessages(threadId, [voiceId], "played")
-await chat.sendMessage(threadId, { to, body, recipients })
+await chat.observeMessages(threadId, [voiceId], "played") // actual playing event
+await chat.markRead(threadId) // ordinary text only; unheard voice stays unread
 const readers = await chat.getReaders(threadId, messageId)
-off(); offSummary()
-await chat.close()
 ```
 
-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.
-`sendMessage` resolves after local persistence, while `outgoing` in the thread
-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.
-
-This facade is still under integration. Reader details currently require network
-access, global summaries do not yet replace the host's contact/thread metadata,
-and Merry's message-list/send migration and production validation are unfinished.
-The lower-level primitives remain available for custom transports:
-
-`MessageClient` reads a trusted recent window locally, coalesces concurrent misses,
-subscribes per conversation, and accepts incremental event batches. Its transport
-supplies authoritative `load`, `changes` and `older` pages. `nextBefore` tracks
-uncached older history independently of the latest synchronization checkpoint.
-A projection reset removes obsolete rows before installing a new window.
-`SocialReadClient.messagePage` implements the authenticated Hub page protocol;
-request cancellation is supported through its optional second signal argument.
-
-`ReadingClient` owns persisted visible/explicit read intents, windowed network
-synchronization and retry. A host reports actual visibility with `recordVisible`
-or explicit actions with `recordExplicit`; loading or subscribing never marks
-messages read. `getSnapshot` plus `subscribe` provide stable reading snapshots.
-`BatchedReadIndex` resolves queued writes only after their transaction commits.
-
-`IndexedDbRecordCache` is a version-aware control-event index. Call and await
-`open` before using it. An optional legacy reader runs during initialization only;
-legacy cleanup happens after durable migration. Normal reads use memory and writes
-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
-and payload. Failed sends require an explicit retry; interrupted sends can resume
-when the connection returns. Call `confirm(hashes)` only after authoritative
-messages have been durably merged. Confirmation tombstones prevent another tab's
-late transport failure from recreating an outgoing message.
-
-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.
+Voice media is acquired on demand through `getVoiceAttachment(threadId,messageId)`.
+Use its `url` and call `release()` when playback/transcription stops. Acquisition,
+clicking play, a fulfilled play Promise and transcription do not count as playing.
+The SDK persists observations locally, batches writes and synchronization, and
+preserves offline intents. It does not promise all media binaries are offline.
+
+```ts
+const group = await chat.getGroup(threadId)
+const created = await chat.createGroup({title, members}) // optional groupId
+await chat.updateGroup(created.threadId, {title: "New title"})
+```
+
+Group reads restore IndexedDB metadata before background reconciliation. Mutations
+wait for confirmed delivery and a causal server version. SDK-owned requests share
+bounded queues and time windows; Apps do not poll. `watchReaders(threadId,ids,receiver)`
+selects receipt counts for the current viewport; clear with `watchReaders(undefined,[])`.
+
+`ChatError` exposes code, retryable, optional HTTP status and cause. Categories are
+unavailable, authentication-required, access-denied, storage-unavailable,
+invalid-input, conflict, closed and busy. Token expiry requires authentication;
+a 403 withdraws the scoped session and its caches. Account/profile/team changes
+require a new SDK instance. Token renewal alone uses the provider.
+
+### Advanced integration and migration
+
+The default client has no `advanced`, `getSnapshot`, `getMessages`, `getConversation`
+or generic `subscribe`. Use resolveThreadId, getThread, subscribeThread,
+loadEarlier and refreshThread. Public readers no longer accept a separate fourth
+signal argument. Use `{signal}` together with the query instead.
+
+Host-owned calls/presence transports use `createChatWithTransport` from
+`@pmate/chat-sdk/advanced`; it returns the same public client. `getChatRuntime(chat)`
+provides explicit one-time migration/diagnostic access. `handleChatReach` and
+`revokeChatAccess` are advanced integration helpers. A deprecated
+`getLegacyChat(chat)` adapter is available only from this entry during migration.
+The raw factory is named `createChatSession` in `/runtime`; its old `createChat`
+name is deprecated. Raw storage/transport clients remain advanced capabilities.
+They must share identity and respect scope authority. Apps do not maintain a second
+message cache, outbox, recipient roster or control revision generator.
+
+### Reading storage recovery
+
+Large reading snapshots use a persisted journal. The full plan becomes durable
+before canonical rows change; bounded transactions apply it, and the sync cursor
+commits last. A reader recovers an active plan before returning a snapshot. Failed
+staging leaves the previous snapshot authoritative; failure after activation keeps
+the old cursor until recovery completes. Pending reads retain their operation IDs.
+
+Writes use at most 128 records per transaction, including journal/lease records,
+and conservatively budget one MiB per batch. Message order is stored per row so a
+source no longer needs a growing array of every message ID. Ordinary observations
+continue to update only positions and pending operations. Locks serialize each
+owner across documents; a fenced IndexedDB lease supports contexts without Web Locks.
+
+The private reading database format is now 60. Existing stores are renamed by
+IndexedDB metadata operations, preserving keys and records. Older SDKs cannot
+write through the former namespace and need a page reload to use the new format.
+The message-body cache is separate and unchanged. The public reading state remains
+schema version 1; applications do not select storage formats or recovery steps.
+
+
+Pending voice snapshots contain `voiceAttachment` metadata, without loading audio bytes or creating Blob URLs at startup. For playback or transcription, acquire media through `await chat.getVoiceAttachment(threadId, messageId)`, use the returned `url`, and call `release()` when the consumer stops. The same method returns a remote voice reference for delivered messages. Attachment reads are charged before allocation, and close/revocation releases local URLs. A pending voice remains unread until the player actually starts; acquiring media does not mark it read.
+
+The outbox format upgrade renames the old canonical store without copying binary data in the schema transaction, then atomically separates inline payloads in bounded, resumable transactions. An already-open older application must reload; unsupported senders reject the new format. Original wire/hash, failed status and retry semantics are retained.
+
+
+SDK group metadata uses a 200ms merge window, four concurrent requests, a bounded
+128-request queue, five-second timeout and at most five read-after-write attempts.
+The persistent group cache is capped at 64 groups / 1MiB, with 128KiB records,
+32-record write batches, conditional writes and bounded pruning. Conversation
+identities are stored separately without rosters; repeated registrations share
+one write, concurrent lookups use bulk reads, and a concurrent memory-hit burst
+shares one fresh authority read without retaining authorization across bursts. Scope withdrawal retires both.
+
+
+## Slash command suggestions
+
+### Background
+
+Host applications know which commands are available in a conversation. The shared desktop/mobile inputs now display that catalog while typing a leading `/`, without coupling the SDK to a particular bot or executing commands from the picker.
+
+```tsx
+<ChatInputDesktop commands={{ commands: [
+  { name: "review", description: "Review code", usage: "PR URL or branch" },
+  { name: "qa", description: "Run independent tests", usage: "PR URL" },
+] }} mentions={groupMembers} onSend={sendMessage} />
+```
+
+The same prop is supported by `ChatInputMobile`. Names omit the leading slash. Arrow keys navigate, Enter/Tab inserts a command and a space, Escape closes; touch selection edits the draft only. Command arguments and existing member mentions are preserved. IME composition, URLs and slashes in ordinary body text do not trigger command execution. Omit `commands` for unsupported conversations.
+
+Host-owned textareas can use `useComposerSuggestions({ value, onChange, mentions, commands, disabled })`, spread `inputProps`, render `MentionMenu` with `menuProps` and `CommandMenu` with `commandMenuProps`, and send `getMentions()` with the untrimmed value.

package/lib/advanced.d.ts

@@ -0,0 +1,10 @@
+import type { Chat } from "./chatContract.js";
+import type { CreateChatOptions } from "./runtime/createChat.js";
+/** Host-owned transport integration. The default factory never accepts raw transports. */
+export declare function createChatWithTransport(options: CreateChatOptions): Chat;
+/** Explicit migration/diagnostic access, outside the ordinary client. */
+export declare function getChatRuntime(chat: Chat): import("./runtime/chatSession.js").ChatSession<import("./runtime/cachedMessage.js").CachedChatMessage>;
+export declare function handleChatReach(chat: Chat, event: Parameters<ReturnType<typeof getChatRuntime>["handleReach"]>[0]): Promise<"handled" | undefined>;
+export declare function revokeChatAccess(chat: Chat): Promise<void>;
+/** @deprecated Transitional next.68 adapter. New App code must use the public client. */
+export declare function getLegacyChat(chat: Chat): import("./internal/chatEngine.js").ChatEngine;

package/lib/advanced.js

@@ -0,0 +1,10 @@
+import { createPublicChat } from "./internal/createPublicChat.js";
+import { chatEngine } from "./internal/chatRegistry.js";
+/** Host-owned transport integration. The default factory never accepts raw transports. */
+export function createChatWithTransport(options) { return createPublicChat(options); }
+/** Explicit migration/diagnostic access, outside the ordinary client. */
+export function getChatRuntime(chat) { return chatEngine(chat).advanced; }
+export function handleChatReach(chat, event) { return chatEngine(chat).handleReach(event); }
+export function revokeChatAccess(chat) { return chatEngine(chat).revokeAccess(); }
+/** @deprecated Transitional next.68 adapter. New App code must use the public client. */
+export function getLegacyChat(chat) { return chatEngine(chat); }

package/lib/chat.d.ts

@@ -0,0 +1,5 @@
+import type { Chat, CreateChatOptions } from "./chatContract.js";
+export type * from "./chatContract.js";
+export type * from "./chatTypes.js";
+export { ChatError, type ChatErrorCode } from "./chatError.js";
+export declare function createChat(options: CreateChatOptions): Chat;

package/lib/chat.js

@@ -0,0 +1,11 @@
+import { createPublicChat } from "./internal/createPublicChat.js";
+import { ChatError } from "./chatError.js";
+export { ChatError } from "./chatError.js";
+export function createChat(options) {
+    const allowed = ["appId", "accountId", "profileId", "teamId", "threadId", "endpoint", "uploadEndpoint", "clientInstanceId", "fetch", "onError", "token", "getToken"];
+    if (Object.keys(options).some(key => !allowed.includes(key)))
+        throw new ChatError("invalid-input", "Unsupported chat option; transport integration belongs to /advanced");
+    if (options.token !== undefined && options.getToken !== undefined)
+        throw new ChatError("invalid-input", "Select one credential source");
+    return createPublicChat({ ...options, onError: error => options.onError?.(error) });
+}

package/lib/chatContract.d.ts

@@ -0,0 +1,148 @@
+import type { ChatFile } from "./fileMetadata.js";
+import type { ChatError } from "./chatError.js";
+import type { ChatMention } from "./mentions/model.js";
+import type { TokenProvider } from "./credentials.js";
+import type { ChatGroup, ChatSnapshot, ChatThreadSnapshot, ReadOptions } from "./chatTypes.js";
+export type { TokenProvider, TokenRequest } from "./credentials.js";
+export type ConversationTarget = {
+    peerId: string;
+    groupId?: never;
+} | {
+    groupId: string;
+    peerId?: never;
+};
+export type CreateChatOptions = {
+    appId: string;
+    accountId: string;
+    profileId: string;
+    teamId: string;
+    threadId?: string;
+    endpoint?: string;
+    uploadEndpoint?: string;
+    clientInstanceId?: string;
+    fetch?: typeof fetch;
+    onError?: (error: ChatError) => void;
+} & ({
+    token: string;
+    getToken?: never;
+} | {
+    getToken: TokenProvider;
+    token?: never;
+});
+export type SendOptions = {
+    waitFor?: "accepted" | "delivered";
+};
+export type SentMessage = Readonly<{
+    id: string;
+    timestamp: number;
+}>;
+export type ReadersQuery = {
+    afterProfileId?: string;
+    revision?: number;
+};
+export type ReadersPage = Readonly<{
+    appId: string;
+    threadId: string;
+    messageId: string;
+    revision: number;
+    total: number;
+    profileIds: string[];
+    nextAfter: string | null;
+    resetRequired: boolean;
+}>;
+export type GroupChanges = {
+    expectedRevision?: string;
+    addMembers?: readonly string[];
+    removeMembers?: readonly string[];
+    title?: string;
+    avatar?: string;
+};
+export type VoiceAttachment = Readonly<{
+    url: string;
+    release: () => void;
+}>;
+export type SubscribeOptions<T> = {
+    fields?: readonly (keyof T)[];
+};
+type ContentChoices = {
+    text: {
+        text: string;
+        mentions?: ChatMention[];
+        quote?: {
+            messageId?: string;
+            senderName: string;
+            content: string;
+        };
+    };
+    file: {
+        file: ChatFile;
+    };
+    image: {
+        image: {
+            url: string;
+            name?: string;
+        };
+    };
+    voice: {
+        voice: ({
+            blob: Blob;
+            url?: never;
+        } | {
+            url: string;
+            blob?: never;
+        }) & {
+            durationMs: number;
+            transcript?: string;
+        };
+    };
+    recall: {
+        recall: {
+            messageId: string;
+        };
+    };
+    reaction: {
+        reaction: {
+            messageId: string;
+            emojiId: string;
+            active: boolean;
+        };
+    };
+    invitation: {
+        invitation: {
+            message?: string;
+        };
+    };
+};
+export type OutgoingContent = {
+    [K in keyof ContentChoices]: ContentChoices[K] & {
+        [P in Exclude<keyof ContentChoices, K>]?: never;
+    };
+}[keyof ContentChoices];
+/** Default public client. Protocol and synchronous store internals are separate entry points. */
+export interface Chat {
+    start(): Promise<void>;
+    close(): Promise<void>;
+    resolveThreadId(target: ConversationTarget, options?: ReadOptions): Promise<string>;
+    getThread(threadId: string, options?: ReadOptions): Promise<ChatThreadSnapshot>;
+    loadEarlier(threadId: string, options?: ReadOptions): Promise<ChatThreadSnapshot>;
+    refreshThread(threadId: string, options?: ReadOptions): Promise<ChatThreadSnapshot>;
+    subscribeThread(threadId: string, listener: (snapshot: ChatThreadSnapshot) => void, options?: SubscribeOptions<ChatThreadSnapshot>): () => void;
+    subscribeChat(listener: (snapshot: ChatSnapshot) => void, options?: SubscribeOptions<ChatSnapshot>): () => void;
+    sendMessage(threadId: string, content: OutgoingContent, options?: SendOptions): Promise<SentMessage>;
+    retryMessage(messageId: string): Promise<SentMessage>;
+    observeMessages(threadId: string, ids: string[], event: "visible" | "played"): Promise<void>;
+    markRead(threadId: string): Promise<void>;
+    getReaders(threadId: string, messageId: string, options?: ReadersQuery & ReadOptions): Promise<ReadersPage>;
+    watchReaders(threadId: string | undefined, ids: string[], receiver?: string): Promise<void>;
+    getVoiceAttachment(threadId: string, messageId: string, options?: ReadOptions): Promise<VoiceAttachment>;
+    getGroup(threadId: string, options?: ReadOptions): Promise<ChatGroup>;
+    refreshGroup(threadId: string, options?: ReadOptions): Promise<ChatGroup>;
+    createGroup(input: {
+        groupId?: string;
+        title: string;
+        members: readonly string[];
+    }): Promise<ChatGroup & {
+        threadId: string;
+    }>;
+    updateGroup(threadId: string, changes: GroupChanges): Promise<ChatGroup>;
+}

package/lib/chatContract.js

@@ -0,0 +1 @@
+export {};

package/lib/chatError.d.ts

@@ -0,0 +1,11 @@
+export type ChatErrorCode = "unavailable" | "access-denied" | "authentication-required" | "storage-unavailable" | "invalid-input" | "conflict" | "closed" | "busy";
+/** Stable recovery categories. The original failure remains available as cause. */
+export declare class ChatError extends Error {
+    readonly code: ChatErrorCode;
+    readonly retryable: boolean;
+    readonly status?: number;
+    constructor(code: ChatErrorCode, message: string, options?: {
+        cause?: unknown;
+        status?: number;
+    });
+}

package/lib/chatError.js

@@ -0,0 +1,13 @@
+/** Stable recovery categories. The original failure remains available as cause. */
+export class ChatError extends Error {
+    code;
+    retryable;
+    status;
+    constructor(code, message, options = {}) {
+        super(message, { cause: options.cause });
+        this.code = code;
+        this.name = "ChatError";
+        this.status = options.status;
+        this.retryable = ["unavailable", "storage-unavailable", "busy"].includes(code);
+    }
+}

package/lib/chatTypes.d.ts

@@ -0,0 +1,121 @@
+import type { ChatFile } from "./fileMetadata.js";
+export type { ChatFile } from "./fileMetadata.js";
+import type { ChatError } from "./chatError.js";
+import type { ChatMention } from "./mentions/model.js";
+/** Stable product model. No storage, transport, Session or projection types. */
+export type ChatMessage = Readonly<{
+    id: string;
+    threadId: string;
+    timestamp: number;
+    from?: string;
+    mine: boolean;
+    status: "sending" | "sent" | "failed" | "read";
+    recalled: boolean;
+    unread?: boolean;
+    attentionEligible?: boolean;
+    reading?: Readonly<{
+        seq?: number;
+        read: boolean;
+        readPolicy: "visible" | "explicit";
+    }>;
+    reactions: readonly Readonly<{
+        emojiId: string;
+        userIds: string[];
+        mine: boolean;
+    }>[];
+    kind: "text" | "image" | "voice" | "emoji" | "quote" | "invitation" | "system" | "attachment";
+    text: string;
+    senderName?: string;
+    senderAvatar?: string;
+    timeLabel?: string;
+    file?: ChatFile;
+    image?: Readonly<{
+        url: string;
+        name?: string;
+    }>;
+    voice?: Readonly<{
+        url: string;
+        durationMs: number;
+        transcript?: string;
+    }>;
+    quote?: Readonly<{
+        messageId?: string;
+        senderName: string;
+        content: string;
+        recalled?: boolean;
+    }>;
+    attachment?: Readonly<{
+        name?: string;
+        size?: string;
+    }>;
+    richContent?: unknown;
+    mentions?: readonly ChatMention[];
+    recipientCount?: number;
+    system?: Readonly<{
+        type: "group-created" | "group-updated" | "contact-updated";
+        title?: string;
+    }>;
+}>;
+export type ChatGroup = Readonly<{
+    groupId: string;
+    teamId: string;
+    ownerId: string;
+    title: string;
+    avatar?: string;
+    memberIds: readonly string[];
+    revision: string;
+}>;
+export type ConversationInfo = Readonly<{
+    kind: "dm" | "group";
+    targetId: string;
+}>;
+export type UnreadState = Readonly<{
+    unreadMessageCount: number;
+    unreadMentionCount: number;
+    badgeCount: number;
+}>;
+export type ReadCounts = Readonly<{
+    appId: string;
+    threadId: string;
+    revision: number;
+    counts: Record<string, number>;
+}>;
+type ThreadFields = Readonly<{
+    threadId: string;
+    messages: readonly ChatMessage[];
+    hasEarlier: boolean;
+    conversation?: ConversationInfo;
+    unread: UnreadState | undefined;
+    group: ChatGroup | undefined;
+    readCounts: ReadCounts | undefined;
+}>;
+/** A refresh failure retains ready data; only an initial failure has status error. */
+export type ChatThreadSnapshot = ThreadFields & (Readonly<{
+    status: "pending";
+    ready: false;
+    error?: undefined;
+}> | Readonly<{
+    status: "ready";
+    ready: true;
+    error?: ChatError;
+}> | Readonly<{
+    status: "error";
+    ready: false;
+    error: ChatError;
+}>);
+export type ChatConnectionState = "connecting" | "reconnecting" | "authenticating" | "connected" | "authentication_required" | "closed";
+export type ChatSnapshot = Readonly<{
+    threads: readonly {
+        threadId: string;
+        lastMessage?: ChatMessage;
+        group: ChatGroup | undefined;
+        unread: UnreadState | undefined;
+        outgoingCount: number;
+    }[];
+    unreadMessageCount: number | undefined;
+    badgeCount: number | undefined;
+    connection: ChatConnectionState;
+}>;
+export type ReadOptions = {
+    signal?: AbortSignal;
+};

package/lib/chatTypes.js

@@ -0,0 +1 @@
+export {};