@pmate/chat-sdk 0.12.0-next.56 → 0.12.0-next.57

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
 
@@ -155,7 +155,10 @@ const offSummary = chat.subscribe(() => renderSummary(chat.getSnapshot()))
 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 })
+const conversation = { id: threadId, kind: "dm" as const, targetId: peerId, teamId }
+await chat.sendMessage(conversation, { text: "Hello" })
+await chat.sendMessage(conversation, { image: { url: uploadedUrl, name: "photo.png" } })
+await chat.sendMessage(conversation, { voice: { blob: recording, durationMs: 1200 } })
 const readers = await chat.getReaders(threadId, messageId)
 off(); offSummary()
 // Ordinary navigation/shutdown preserves offline data.
@@ -169,6 +172,14 @@ await chat.close()
 await chat.revokeAccess()
 ```
 
+Conversation descriptors identify the target and optional group `memberIds`; the SDK
+checks the descriptor against its identity and team before acceptance. It builds
+text, image, quote and voice envelopes and expands group `@all`/`@所有人` to concrete
+members. Content callers do not provide `appId`, protocol `body` or `recipients`.
+The existing `sendMessage(threadId, { to, body, recipients })` form remains available
+for protocol integrations. Blob voice uploads stay in the durable sender; offline
+uploads wait for retry instead of starting HTTP.
+
 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.

package/lib/runtime/chatSession.d.ts

@@ -1,3 +1,4 @@
+import { type ChatConversation, type OutgoingContent } from "./outgoingContent.js";
 import { type TimelineItem } from "./messageTimeline.js";
 import { type ReadingCandidate, type MessageReadingState } from "./conversationReading.js";
 import type { ConversationReadMessage } from "./conversationRead.js";
@@ -120,6 +121,7 @@ export declare class ChatSession<T extends StoredMessage> {
     private rememberHistoryEdge;
     private readEarlier;
     private readAll;
+    sendMessage(thread: ChatConversation, input: OutgoingContent): Promise<ChatRuntimeMessage>;
     sendMessage(threadId: string, input: SendMessageInput): Promise<ChatRuntimeMessage>;
     getReaders(threadId: string, messageId: string, page?: Omit<MessageReadersQuery, "threadId" | "messageId">, signal?: AbortSignal): Promise<import("./messageReaders.js").MessageReadersPage>;
     retryMessage(messageId: string): Promise<ChatRuntimeMessage>;

package/lib/runtime/chatSession.js

@@ -1,3 +1,4 @@
+import { outgoingContent } from "./outgoingContent.js";
 import { projectMessageTimeline } from "./messageTimeline.js";
 import { projectConversationReading } from "./conversationReading.js";
 import { ReadCountsClient } from "./readCounts.js";
@@ -359,9 +360,11 @@ export class ChatSession {
         }
         throw new Error("MESSAGE_SYNC_RESET_REQUIRED");
     }
-    sendMessage(threadId, input) {
+    sendMessage(thread, input) {
         this.assertOpen();
-        return this.sender.enqueue(threadId, input).then(next => { if (this.withdrawn)
+        const threadId = typeof thread === "string" ? thread : thread.id;
+        const wire = typeof thread === "string" ? input : outgoingContent(this.options.messages.scope, thread, input);
+        return this.sender.enqueue(threadId, wire).then(next => { if (this.withdrawn)
             throw new Error("CHAT_ACCESS_REVOKED"); return next; });
     }
     async getReaders(threadId, messageId, page = {}, signal) {

package/lib/runtime/index.d.ts

@@ -33,3 +33,4 @@ export * from "./conversationRead.js";
 export { projectConversationReading, type ReadingCandidate, type MessageReadingState, type ConversationReadingView } from "./conversationReading.js";
 export { projectMessageTimeline, type TimelineItem, type TimelineReaction, type TimelineReactionEvent } from "./messageTimeline.js";
 export * from "./messageLaunch.js";
+export * from "./outgoingContent.js";

package/lib/runtime/index.js

@@ -33,3 +33,4 @@ export * from "./conversationRead.js";
 export { projectConversationReading } from "./conversationReading.js";
 export { projectMessageTimeline } from "./messageTimeline.js";
 export * from "./messageLaunch.js";
+export * from "./outgoingContent.js";

package/lib/runtime/outgoingContent.d.ts

@@ -0,0 +1,47 @@
+import type { ChatMention } from "../mentions/model.js";
+import type { MessageScope } from "./messageStore.js";
+import type { SendMessageInput } from "./durableSender.js";
+export type ChatConversation = {
+    id: string;
+    kind: "dm" | "group";
+    targetId: string;
+    teamId?: string;
+    memberIds?: readonly string[];
+};
+export type MessageQuote = {
+    messageId?: string;
+    senderName: string;
+    content: string;
+};
+export type OutgoingContent = {
+    text: string;
+    mentions?: ChatMention[];
+    quote?: MessageQuote;
+    image?: never;
+    voice?: never;
+} | {
+    image: {
+        url: string;
+        name?: string;
+    };
+    text?: never;
+    voice?: never;
+} | {
+    voice: ({
+        blob: Blob;
+        url?: never;
+    } | {
+        url: string;
+        blob?: never;
+    }) & {
+        durationMs: number;
+        transcript?: string;
+    };
+    text?: never;
+    image?: never;
+};
+export declare const ALL_MENTION_ID = "__pmate_mention_all__";
+/** Expand group mentions into concrete members understood by all protocol readers. */
+export declare function expandGroupMentions(text: string, mentions: ChatMention[] | undefined, memberIds: readonly string[], senderId: string): ChatMention[];
+/** Build the existing wire protocol inside the owner, before durable acceptance. */
+export declare function outgoingContent(scope: MessageScope, thread: ChatConversation, input: OutgoingContent): SendMessageInput;

package/lib/runtime/outgoingContent.js

@@ -0,0 +1,58 @@
+import { dmThreadId, groupThreadId } from "./thread.js";
+export const ALL_MENTION_ID = "__pmate_mention_all__";
+/** Expand group mentions into concrete members understood by all protocol readers. */
+export function expandGroupMentions(text, mentions, memberIds, senderId) {
+    const validMembers = [...new Set(memberIds)], members = validMembers.filter(id => id !== senderId), entries = [...(mentions ?? [])];
+    const pattern = /(?:^|[\s([{，。！？、：；])(@(?:all|所有人))(?=$|[\s,.;:!?，。！？、：；)\]}])/gu;
+    for (const match of text.matchAll(pattern)) {
+        const start = match.index + match[0].length - match[1].length;
+        if (!entries.some(entry => entry.start === start && entry.end === start + match[1].length))
+            entries.push({ id: ALL_MENTION_ID, name: match[1].slice(1), start, end: start + match[1].length });
+    }
+    const seen = new Set();
+    return entries.flatMap(entry => {
+        if (text.slice(entry.start, entry.end) !== `@${entry.name}`)
+            return [];
+        if (entry.id === ALL_MENTION_ID)
+            return ["all", "所有人"].includes(entry.name) ? members.map(id => ({ ...entry, id })) : [];
+        return validMembers.includes(entry.id) ? [entry] : [];
+    }).filter(entry => { const key = `${entry.id}:${entry.start}:${entry.end}`; if (seen.has(key))
+        return false; seen.add(key); return true; });
+}
+/** Build the existing wire protocol inside the owner, before durable acceptance. */
+export function outgoingContent(scope, thread, input) {
+    if (!thread || !["dm", "group"].includes(thread.kind) || typeof thread.targetId !== "string" || !thread.targetId || thread.teamId !== undefined && thread.teamId !== scope.teamId)
+        throw new Error("INVALID_MESSAGE_CONVERSATION");
+    const expected = thread.kind === "group" ? groupThreadId(scope.appId, thread.targetId, scope.teamId) : dmThreadId(scope.appId, scope.profileId, thread.targetId, scope.teamId);
+    if (thread.id !== expected)
+        throw new Error("MESSAGE_CONVERSATION_MISMATCH");
+    const recipients = thread.kind === "group" ? [...new Set(thread.memberIds)] : undefined;
+    if (recipients && (!recipients.length || recipients.some(id => typeof id !== "string" || !id)))
+        throw new Error("MESSAGE_GROUP_MEMBERS_UNAVAILABLE");
+    const base = { appId: scope.appId, ...(scope.teamId === undefined ? {} : { teamId: scope.teamId }), ...(thread.kind === "group" ? { groupId: thread.targetId } : {}) };
+    if (!input || typeof input !== "object" || ["text", "image", "voice"].filter(key => Object.hasOwn(input, key)).length !== 1)
+        throw new Error("INVALID_MESSAGE_CONTENT");
+    let content, contentKind = "text", voiceBlob;
+    if ("text" in input) {
+        if (typeof input.text !== "string")
+            throw new Error("INVALID_MESSAGE_TEXT");
+        const mentions = thread.kind === "group" ? expandGroupMentions(input.text, input.mentions, recipients, scope.profileId) : input.mentions;
+        content = { ...base, text: input.text, ...(input.quote ? { quote: input.quote } : {}), ...(mentions?.length ? { mentions } : {}) };
+    }
+    else if ("image" in input && input.image) {
+        if (typeof input.image.url !== "string" || !input.image.url)
+            throw new Error("INVALID_MESSAGE_IMAGE");
+        contentKind = "image";
+        content = { ...base, url: input.image.url, ...(input.image.name === undefined ? {} : { name: input.image.name }) };
+    }
+    else if ("voice" in input && input.voice) {
+        const voice = input.voice;
+        if (!Number.isFinite(voice.durationMs) || voice.durationMs <= 0 || !("blob" in voice ? voice.blob instanceof Blob : typeof voice.url === "string" && voice.url.length > 0))
+            throw new Error("INVALID_MESSAGE_VOICE");
+        voiceBlob = voice.blob;
+        content = { ...base, text: "[语音]", voice: { url: voiceBlob ? "" : voice.url, durationMs: voice.durationMs, ...(voice.transcript ? { transcript: voice.transcript } : {}) } };
+    }
+    else
+        throw new Error("INVALID_MESSAGE_CONTENT");
+    return { to: thread.targetId, body: { kind: "message", threadKind: thread.kind, contentKind, content }, ...(recipients ? { recipients } : {}), ...(voiceBlob ? { voiceBlob } : {}) };
+}

package/lib/runtime/voiceUpload.js

@@ -1,6 +1,11 @@
+import { isOffline } from "./connectivity.js";
 /** The SDK owns upload I/O; hosts configure only their service endpoint. */
 export function voiceUploader(profileId, endpoint = "https://upload-fc.pmate.chat", fetcher = globalThis.fetch) {
     return async (blob, signal) => {
+        if (signal.aborted)
+            throw new DOMException("Upload aborted", "AbortError");
+        if (isOffline())
+            throw new Error("VOICE_UPLOAD_OFFLINE");
         const bytes = new Uint8Array(await blob.arrayBuffer());
         if (signal.aborted)
             throw new DOMException("Upload aborted", "AbortError");
@@ -9,6 +14,8 @@ export function voiceUploader(profileId, endpoint = "https://upload-fc.pmate.cha
             binary += String.fromCharCode(...bytes.subarray(offset, offset + 32768));
         const extension = blob.type.includes("mp4") ? "m4a" : blob.type.includes("mpeg") ? "mp3" : "webm";
         const type = extension === "m4a" ? "audio/mp4" : extension === "mp3" ? "audio/mpeg" : "audio/webm";
+        if (isOffline())
+            throw new Error("VOICE_UPLOAD_OFFLINE");
         const response = await fetcher(`${endpoint.replace(/\/+$/, "")}/file`, { method: "POST", signal, headers: { "Content-Type": "application/json", "x-file-content-type": type }, body: JSON.stringify({ user: profileId, base64: btoa(binary), filename: `voice-${Date.now()}.${extension}` }) });
         if (!response.ok)
             throw new Error("VOICE_UPLOAD_FAILED");

package/package.json

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