@pmate/chat-sdk 0.12.0-next.63 → 0.12.0-next.65

package/README.md

@@ -173,7 +173,12 @@ route entry and startup before the first read; it is not a cache-source indicato
 `getSnapshot()` and `subscribe(listener)` provide conversation summaries, aggregate
 unread counts and connection state. Unknown unread counts remain `undefined`.
 Subscription always emits the current snapshot first, including with
-`{fields:["messages","unread"]}`, then meaningful changes only. Object references
+`{fields:["messages","unread"]}`, then meaningful changes only. Messages expose `kind`, `text`, optional `image`,
+`voice`, `quote`, explicit `richContent`, semantic `reactions` and reading/delivery
+state. Apps do not inspect transport bodies or control-event revisions. Group
+causal version numbers and raw message records remain under `advanced`.
+`observeMessages` and `markRead` resolve with `void` after durable submission.
+Object references
 remain stable for unchanged results. Framework adapters can use
 `{emitCurrent:false}`; React can import `useChatSnapshot(chat, threadId)` from
 `@pmate/chat-sdk`. Establishing a subscription never starts a read or marks it read.
@@ -215,7 +220,9 @@ selects receipt counts for the current viewport; clear with `watchReaders(undefi
 `ChatError` exposes `code`, `retryable`, optional HTTP `status`, and the original
 `cause`. Recovery categories are `unavailable`, `access-denied`,
 `storage-unavailable`, `invalid-input`, `conflict`, `closed`, and `busy`.
-Permission failures never turn into trusted offline data. Dispose and recreate
+Permission failures withdraw the current scoped session and retire its caches;
+failed cleanup remains in the error cause. They never turn into trusted offline
+data. Dispose and recreate
 the SDK when account, profile, team or token changes.
 
 ### Advanced integration and migration
@@ -228,7 +235,8 @@ contract for compatibility. New Apps should import from `@pmate/chat-sdk/chat`
 or the package root. Do not mix the two snapshot contracts.
 
 For migration, replace `subscribe(id, () => render(getSnapshot(id).timeline))`
-with `subscribe(id, state => render(state.messages))`; replace conversation
+with `subscribe(id, state => render(state.messages))`; replace
+`item.message.body` parsing with `item.kind/text/image/voice/quote`; replace conversation
 objects and App-supplied recipients with `threadId`; await `getMessages` before
 opening a cold thread instead of checking `page.complete`. Replace `initialize()`
 with `start()`; a shared connection is initialized without another connect call.

package/lib/chat.d.ts

@@ -1,7 +1,9 @@
+import type { ChatGroup as RuntimeGroup } from "./runtime/groupClient.js";
+import { type ChatMessage } from "./messageView.js";
+export type { ChatMessage } from "./messageView.js";
 import { type CreateChatOptions } from "./runtime/createChat.js";
 import type { ChatSession, ChatSummarySnapshot as SessionSummary, ChatThreadSnapshot as SessionThread } from "./runtime/chatSession.js";
 import type { CachedChatMessage } from "./runtime/cachedMessage.js";
-import type { TimelineItem } from "./runtime/messageTimeline.js";
 import type { ConversationTarget } from "./runtime/conversationDirectory.js";
 import type { OutgoingContent as RuntimeContent } from "./runtime/outgoingContent.js";
 import { ChatError } from "./runtime/chatError.js";
@@ -13,8 +15,7 @@ export type OutgoingContent = Exclude<RuntimeContent, {
 } | {
     groupUpdate: unknown;
 }>;
-export type { ChatGroup } from "./runtime/groupClient.js";
-export type ChatMessage = Readonly<TimelineItem<CachedChatMessage>>;
+export type ChatGroup = Readonly<Omit<RuntimeGroup, "versionNumber">>;
 export type ConversationInfo = Readonly<{
     kind: "dm" | "group";
     targetId: string;
@@ -26,7 +27,7 @@ export type ChatThreadSnapshot = Readonly<{
     hasEarlier: boolean;
     conversation?: ConversationInfo;
     unread: SessionThread<CachedChatMessage>["unread"];
-    group: SessionThread<CachedChatMessage>["group"];
+    group: ChatGroup | undefined;
     readCounts: SessionThread<CachedChatMessage>["readCounts"];
     error?: ChatError;
 }>;
@@ -34,7 +35,7 @@ export type ChatSnapshot = Readonly<{
     threads: readonly {
         threadId: string;
         lastMessage?: ChatMessage;
-        group: SessionThread<CachedChatMessage>["group"];
+        group: ChatGroup | undefined;
         unread: ChatThreadSnapshot["unread"];
         outgoingCount: number;
     }[];
@@ -62,6 +63,12 @@ type SubscribeOptions<T> = {
 export declare class Chat {
     readonly advanced: ChatSession<CachedChatMessage>;
     private options;
+    private groups;
+    private group;
+    private present;
+    private redactedQuotes;
+    private messageLists;
+    private messages;
     private views;
     private summary?;
     private targets;
@@ -70,6 +77,7 @@ export declare class Chat {
     private closed;
     constructor(advanced: ChatSession<CachedChatMessage>, options: CreateChatOptions);
     private operation;
+    private deny;
     private threadOperation;
     start(): Promise<void>;
     getConversation(target: ConversationTarget): Promise<string>;
@@ -82,31 +90,30 @@ export declare class Chat {
     subscribe(threadId: string, listener: (snapshot: ChatThreadSnapshot) => void, options?: SubscribeOptions<ChatThreadSnapshot>): () => void;
     private sessionFields;
     private notify;
-    observeMessages(threadId: string, ids: string[], event: "visible" | "played"): Promise<import("./runtime/readIndex.js").ReadIndexState>;
-    markRead(threadId: string): Promise<import("./runtime/readIndex.js").ReadIndexState>;
+    observeMessages(threadId: string, ids: string[], event: "visible" | "played"): Promise<void>;
+    markRead(threadId: string): Promise<void>;
     getReaders(threadId: string, messageId: string, page?: Parameters<ChatSession<CachedChatMessage>["getReaders"]>[2], 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<import("./chat.js").ChatGroup>;
+    }): Promise<Readonly<Omit<RuntimeGroup, "versionNumber">>>;
     createGroup(input: {
         groupId?: string;
         title: string;
         members: readonly string[];
     }): Promise<{
         threadId: string;
-        groupId: string;
+        revision: string;
         teamId: string;
-        ownerId: string;
         title: string;
+        groupId: string;
         avatar?: string;
+        ownerId: string;
         memberIds: readonly string[];
-        revision: string;
-        versionNumber: number;
     }>;
-    updateGroup(threadId: string, changes: Parameters<ChatSession<CachedChatMessage>["updateGroup"]>[1]): Promise<import("./chat.js").ChatGroup>;
+    updateGroup(threadId: string, changes: Parameters<ChatSession<CachedChatMessage>["updateGroup"]>[1]): Promise<Readonly<Omit<RuntimeGroup, "versionNumber">>>;
     revokeAccess(): Promise<void>;
     close(): Promise<void>;
 }

package/lib/chat.js

@@ -1,3 +1,4 @@
+import { createMessagePresenter } from "./messageView.js";
 import { createChat as createSession } from "./runtime/createChat.js";
 import { asChatError, ChatError } from "./runtime/chatError.js";
 export { ChatError } from "./runtime/chatError.js";
@@ -6,6 +7,40 @@ const emptyMessages = Object.freeze([]);
 export class Chat {
     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();
@@ -22,6 +57,18 @@ export class Chat {
     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;
@@ -32,11 +79,8 @@ export class Chat {
             }
             catch (error) {
                 const failure = asChatError(error);
-                if (threadId && failure.code === "access-denied") {
-                    this.errors.set(threadId, failure);
-                    this.targets.delete(threadId);
-                    this.notify(threadId);
-                }
+                if (threadId && failure.code === "access-denied")
+                    await this.deny(threadId, failure);
                 throw failure;
             }
         });
@@ -57,17 +101,19 @@ export class Chat {
     getSnapshot(threadId) {
         if (threadId === undefined) {
             const source = this.advanced.getSnapshot(), previous = this.summary;
-            const threads = source.threads.map(thread => ({ threadId: thread.threadId, lastMessage: thread.lastItem, group: thread.group, unread: thread.unread, outgoingCount: thread.outgoingCount }));
-            if (previous && previous.connection === source.connection && previous.badgeCount === source.badgeCount && previous.unreadMessageCount === source.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; }))
+            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: source.badgeCount, unreadMessageCount: source.unreadMessageCount };
+            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 ? source.timeline : emptyMessages, ready: !denied && source.complete, hasEarlier: !denied && source.hasEarlier, unread: denied ? undefined : source.unread, group: denied ? undefined : source.group, readCounts: denied ? undefined : source.readCounts, error };
+        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 };
         if (previous && Object.keys(next).every(key => next[key] === previous[key]))
             return previous;
         this.views.set(threadId, next);
@@ -87,8 +133,12 @@ export class Chat {
         catch (error) {
             const failure = asChatError(error);
             if (!this.closed) {
-                this.errors.set(threadId, failure);
-                this.notify(threadId);
+                if (failure.code === "access-denied")
+                    await this.deny(threadId, failure);
+                else {
+                    this.errors.set(threadId, failure);
+                    this.notify(threadId);
+                }
             }
             throw failure;
         }
@@ -138,24 +188,24 @@ export class Chat {
     sessionFields(fields) {
         return fields ? [...new Set(fields.flatMap(field => field === "messages" ? ["timeline", "complete"] : field === "ready" ? ["complete"] : field === "conversation" ? ["messages", "group"] : field === "error" || field === "threadId" ? [] : [field]))] : undefined;
     }
-    notify(threadId) { this.listeners.get(threadId)?.forEach(listener => listener()); }
-    observeMessages(threadId, ids, event) { return this.threadOperation(threadId, () => this.advanced.observeMessages(threadId, ids, event)); }
-    markRead(threadId) { return this.threadOperation(threadId, () => this.advanced.markRead(threadId)); }
+    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, () => 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, () => this.advanced.getGroup(threadId, options)); }
+    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 { ...group, threadId };
+            return { ...this.group(group), threadId };
         });
     }
-    updateGroup(threadId, changes) { return this.threadOperation(threadId, () => this.advanced.updateGroup(threadId, changes)); }
+    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.views.clear(); this.summary = undefined; }); }
+    close() { this.closed = true; return this.operation(() => this.advanced.close()).finally(() => { this.errors.clear(); this.targets.clear(); this.listeners.clear(); this.views.clear(); this.summary = undefined; this.present = createMessagePresenter(); this.messageLists = new WeakMap(); this.groups = new WeakMap(); this.redactedQuotes = new WeakMap(); }); }
 }
 export function createChat(options) {
     const configured = { ...options, onError: (error) => options.onError(asChatError(error)) };

package/lib/messageView.d.ts

@@ -0,0 +1,36 @@
+import type { TimelineItem } from "./runtime/messageTimeline.js";
+import type { CachedChatMessage } from "./runtime/cachedMessage.js";
+import type { MessageQuote } from "./runtime/outgoingContent.js";
+import type { ChatMention } from "./mentions/model.js";
+export type ChatMessage = Readonly<Omit<TimelineItem<CachedChatMessage>, "message" | "reactionEvents"> & {
+    kind: "text" | "image" | "voice" | "emoji" | "quote" | "invitation" | "system" | "attachment";
+    text: string;
+    senderName?: string;
+    senderAvatar?: string;
+    image?: Readonly<{
+        url: string;
+        name?: string;
+    }>;
+    voice?: Readonly<{
+        url: string;
+        durationMs: number;
+        transcript?: string;
+    }>;
+    quote?: Readonly<MessageQuote & {
+        recalled?: boolean;
+    }>;
+    attachment?: Readonly<{
+        name?: string;
+        size?: string;
+    }>;
+    /** Explicit versioned content, interpreted with SDK readMessageContent. */
+    richContent?: unknown;
+    mentions?: readonly ChatMention[];
+    recipientCount?: number;
+    system?: Readonly<{
+        type: "group-created" | "group-updated" | "contact-updated";
+        title?: string;
+    }>;
+}>;
+/** Decode a body once; reading and delivery projections reuse its normalized content. */
+export declare function createMessagePresenter(): (item: TimelineItem<CachedChatMessage>) => ChatMessage;

package/lib/messageView.js

@@ -0,0 +1,97 @@
+const object = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
+const text = (value) => typeof value === "string" ? value : "";
+function media(value) {
+    if (typeof value !== "string" || !value)
+        return undefined;
+    try {
+        const url = new URL(value);
+        return ["https:", "http:"].includes(url.protocol) && !url.username && !url.password ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function quote(value) {
+    const record = object(value);
+    if (typeof record.senderName !== "string" || typeof record.content !== "string" || record.content.length > 6000)
+        return;
+    return { senderName: record.senderName.slice(0, 100), content: record.content, ...(typeof record.messageId === "string" ? { messageId: record.messageId } : {}) };
+}
+function legacyDuration(value) {
+    if (typeof value !== "string" || !/^\d+:\d{2}$/.test(value))
+        return 0;
+    const [minutes, seconds] = value.split(":").map(Number);
+    return (minutes * 60 + seconds) * 1000;
+}
+function content(message) {
+    const body = object(message.body), outer = object(body.content);
+    const envelope = body.kind === "quote" && outer.content !== undefined ? outer : body;
+    const payload = object(envelope.content);
+    const legacy = object(message.legacyDisplay);
+    const validLegacy = legacy.id === message.id && legacy.threadId === message.threadId && legacy.orgId === message.teamId && legacy.from === message.from && typeof legacy.content === "string";
+    const hint = validLegacy ? legacy : {};
+    const contentKind = envelope.contentKind, voice = object(payload.voice);
+    const voiceHint = hint.kind === "voice";
+    const voiceUrl = media(voice.url) ?? (voiceHint ? media(hint.audioUrl) : undefined) ?? "";
+    const durationMs = typeof voice.durationMs === "number" && Number.isFinite(voice.durationMs) ? voice.durationMs : voiceHint ? legacyDuration(hint.duration) : 0;
+    const hasVoice = voiceHint || Object.keys(voice).length > 0 && (voiceUrl.length > 0 || durationMs > 0) || contentKind === "voice";
+    const imageUrl = media(payload.url) ?? (hint.kind === "image" ? media(hint.imageUrl) : undefined);
+    const messageQuote = quote(payload.quote) ?? quote(hint.quote);
+    const rawText = text(payload.text) || text(object(body.payload).message);
+    const result = { kind: "text", text: validLegacy ? text(hint.content) : rawText, senderName: text(hint.senderName) || undefined, senderAvatar: media(hint.senderAvatar),
+        recipientCount: message.threadKind === "dm" ? 1 : validLegacy ? typeof hint.recipientCount === "number" ? hint.recipientCount : undefined : Array.isArray(message.recipients) ? new Set(message.recipients.filter(id => id !== message.from)).size : undefined };
+    if (validLegacy && ["emoji", "system", "attachment", "quote"].includes(String(hint.kind)))
+        result.kind = hint.kind;
+    if (body.kind === "contact") {
+        result.kind = ["friendRequest", "requestFriend"].includes(String(body.action)) ? "invitation" : "system";
+        if (result.kind === "system")
+            result.system = { type: "contact-updated" };
+    }
+    else if (body.kind === "group") {
+        result.kind = "system";
+        result.system = { type: body.action === "groupCreate" ? "group-created" : "group-updated", title: text(object(body.payload).title) || undefined };
+    }
+    else if (hasVoice) {
+        result.kind = "voice";
+        result.voice = { url: voiceUrl, durationMs, ...(text(voice.transcript) || text(hint.transcript) ? { transcript: text(voice.transcript) || text(hint.transcript) } : {}) };
+    }
+    else if ((contentKind === "image" || hint.kind === "image") && imageUrl) {
+        result.kind = "image";
+        result.image = { url: imageUrl, name: text(payload.name) || text(hint.imageAlt) || undefined };
+    }
+    else if (contentKind === "emoji") {
+        result.kind = "emoji";
+        result.text = text(payload.code) || result.text;
+    }
+    if (messageQuote) {
+        result.quote = messageQuote;
+        if (result.kind === "text")
+            result.kind = "quote";
+    }
+    if (result.kind === "attachment")
+        result.attachment = { name: text(hint.attachmentName) || undefined, size: text(hint.attachmentSize) || undefined };
+    if (payload.format !== undefined)
+        result.richContent = payload;
+    else if (hint.richContent !== undefined)
+        result.richContent = hint.richContent;
+    if (Array.isArray(payload.mentions))
+        result.mentions = payload.mentions;
+    return result;
+}
+/** Decode a body once; reading and delivery projections reuse its normalized content. */
+export function createMessagePresenter() {
+    const bodies = new WeakMap(), items = new WeakMap();
+    return (item) => {
+        const previous = items.get(item);
+        if (previous)
+            return previous;
+        let value = { kind: "system", text: "" };
+        if (!item.recalled && item.message) {
+            value = bodies.get(item.message) ?? content(item.message);
+            bodies.set(item.message, value);
+        }
+        const result = { id: item.id, threadId: item.threadId, timestamp: item.timestamp, from: item.from, mine: item.mine, status: item.status, recalled: item.recalled, unread: item.unread, attentionEligible: item.attentionEligible, reading: item.reading, reactions: item.reactions, ...value };
+        items.set(item, result);
+        return result;
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmate/chat-sdk",
-  "version": "0.12.0-next.63",
+  "version": "0.12.0-next.65",
   "description": "Local-first chat SDK, message subscriptions, reading state, and shared chat UI primitives",
   "type": "module",
   "main": "./lib/index.js",