@composy/chat-core 0.0.1 → 0.0.2

package/esm/core/outbox.js

@@ -0,0 +1,160 @@
+/*!
+* ***********************************
+* @composy/chat-core v0.0.2       *
+* Built with rollup               *
+* Build time: 2024-10-12 21:52:18 *
+* Build mode: production          *
+* Minified: No                    *
+* ***********************************
+*/
+import { cloneChatMessage, normalizeChatMessage } from "./message-schema.js";
+//#region src/core/outbox.ts
+var MemoryChatOutboxStorage = class {
+	constructor() {
+		this.entries = [];
+	}
+	load() {
+		return cloneEntries(this.entries);
+	}
+	save(entries) {
+		this.entries = cloneEntries(entries);
+	}
+};
+var ChatOutbox = class {
+	constructor(options = {}) {
+		this.entries = [];
+		this.hydrated = false;
+		this.writePromise = Promise.resolve();
+		this.storage = options.storage ?? new MemoryChatOutboxStorage();
+		this.now = options.now ?? Date.now;
+	}
+	async hydrate() {
+		if (!this.hydrated) {
+			this.entries = (await this.storage.load()).map(normalizeEntry);
+			this.hydrated = true;
+		}
+		return this.list();
+	}
+	list() {
+		return cloneEntries(this.entries);
+	}
+	async enqueue(message) {
+		await this.hydrate();
+		const normalized = normalizeChatMessage({
+			...message,
+			clientMessageId: message.clientMessageId ?? message.id
+		});
+		const key = getOutboxKey(normalized);
+		const existing = this.entries.find((entry2) => entry2.id === key);
+		if (existing) return cloneEntry(existing);
+		const entry = {
+			id: key,
+			message: normalized,
+			enqueuedAt: this.now(),
+			attempts: 0,
+			state: "pending"
+		};
+		this.entries.push(entry);
+		await this.persist();
+		return cloneEntry(entry);
+	}
+	async remove(id) {
+		await this.hydrate();
+		const index = this.entries.findIndex((entry) => entry.id === id);
+		if (index < 0) return false;
+		this.entries.splice(index, 1);
+		await this.persist();
+		return true;
+	}
+	async retry(id) {
+		await this.hydrate();
+		for (const entry of this.entries) if (!id || entry.id === id) {
+			entry.state = "pending";
+			entry.lastError = void 0;
+		}
+		await this.persist();
+	}
+	async clear() {
+		await this.hydrate();
+		this.entries = [];
+		await this.persist();
+	}
+	async flush(send, options = {}) {
+		await this.hydrate();
+		const maxAttempts = Math.max(1, Math.floor(options.maxAttempts ?? 3));
+		const concurrency = Math.min(8, Math.max(1, Math.floor(options.concurrency ?? 1)));
+		const candidates = this.entries.filter((entry) => entry.state === "pending");
+		const sent = [];
+		const failed = [];
+		let cursor = 0;
+		const worker = async () => {
+			while (cursor < candidates.length) {
+				if (options.signal?.aborted) throw createAbortError();
+				const entry = candidates[cursor++];
+				entry.attempts += 1;
+				try {
+					await send(entry.message, {
+						signal: options.signal,
+						clientMessageId: entry.message.clientMessageId ?? entry.id
+					});
+					const index = this.entries.findIndex((item) => item.id === entry.id);
+					if (index >= 0) this.entries.splice(index, 1);
+					sent.push(entry.id);
+				} catch (error) {
+					entry.lastError = toErrorMessage(error);
+					if (entry.attempts >= maxAttempts) entry.state = "failed";
+					failed.push({
+						id: entry.id,
+						error
+					});
+				}
+				await this.persist();
+			}
+		};
+		await Promise.all(Array.from({ length: concurrency }, () => worker()));
+		return {
+			sent,
+			failed,
+			remaining: this.list()
+		};
+	}
+	async persist() {
+		const snapshot = cloneEntries(this.entries);
+		const previous = this.writePromise;
+		this.writePromise = previous.then(() => this.storage.save(snapshot));
+		await this.writePromise;
+	}
+};
+function getOutboxKey(message) {
+	return message.clientMessageId ?? message.id;
+}
+function cloneEntry(entry) {
+	return {
+		...entry,
+		message: cloneChatMessage(entry.message)
+	};
+}
+function cloneEntries(entries) {
+	return entries.map(cloneEntry);
+}
+function normalizeEntry(entry) {
+	const message = normalizeChatMessage(entry.message);
+	return {
+		id: typeof entry.id === "string" && entry.id ? entry.id : getOutboxKey(message),
+		message,
+		enqueuedAt: Number.isFinite(entry.enqueuedAt) ? entry.enqueuedAt : Date.now(),
+		attempts: Number.isFinite(entry.attempts) ? Math.max(0, Math.floor(entry.attempts)) : 0,
+		state: entry.state === "failed" ? "failed" : "pending",
+		...typeof entry.lastError === "string" && { lastError: entry.lastError }
+	};
+}
+function toErrorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function createAbortError() {
+	return new DOMException("The operation was aborted.", "AbortError");
+}
+//#endregion
+export { ChatOutbox, MemoryChatOutboxStorage };
+/*! End of @composy/chat-core | Powered by @composy/builder */
+//# sourceMappingURL=outbox.js.map

package/esm/core/outbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox.js","names":["entry"],"sources":["../../src/core/outbox.ts"],"sourcesContent":["import type { ChatMessage } from '../types'\nimport { cloneChatMessage, normalizeChatMessage } from './message-schema'\n\n/** 离线 outbox 中的一条待发送消息。 */\nexport interface ChatOutboxEntry {\n  id: string\n  message: ChatMessage\n  enqueuedAt: number\n  attempts: number\n  state: 'pending' | 'failed'\n  lastError?: string\n}\n\n/** outbox 持久化适配器；可接 IndexedDB、SQLite bridge 或业务缓存。 */\nexport interface ChatOutboxStorage {\n  load: () => ChatOutboxEntry[] | Promise<ChatOutboxEntry[]>\n  save: (entries: ChatOutboxEntry[]) => void | Promise<void>\n}\n\n/** 内存适配器，适合默认运行和单元测试。 */\nexport class MemoryChatOutboxStorage implements ChatOutboxStorage {\n  private entries: ChatOutboxEntry[] = []\n\n  load(): ChatOutboxEntry[] {\n    return cloneEntries(this.entries)\n  }\n\n  save(entries: ChatOutboxEntry[]): void {\n    this.entries = cloneEntries(entries)\n  }\n}\n\nexport interface ChatOutboxOptions {\n  storage?: ChatOutboxStorage\n  now?: () => number\n}\n\nexport interface ChatOutboxFlushOptions {\n  signal?: AbortSignal\n  maxAttempts?: number\n  concurrency?: number\n}\n\nexport interface ChatOutboxFlushResult {\n  sent: string[]\n  failed: Array<{ id: string; error: unknown }>\n  remaining: ChatOutboxEntry[]\n}\n\n/**\n * 幂等离线队列。\n *\n * 队列只负责保存和重试，不假设网络协议；发送函数由 ChatTransportController\n * 或业务层注入。每条消息以 clientMessageId 优先作为幂等键，重复 enqueue 不会产生重复项。\n */\nexport class ChatOutbox {\n  private readonly storage: ChatOutboxStorage\n  private readonly now: () => number\n  private entries: ChatOutboxEntry[] = []\n  private hydrated = false\n  private writePromise: Promise<void> = Promise.resolve()\n\n  constructor(options: ChatOutboxOptions = {}) {\n    this.storage = options.storage ?? new MemoryChatOutboxStorage()\n    this.now = options.now ?? Date.now\n  }\n\n  async hydrate(): Promise<ChatOutboxEntry[]> {\n    if (!this.hydrated) {\n      this.entries = (await this.storage.load()).map(normalizeEntry)\n      this.hydrated = true\n    }\n    return this.list()\n  }\n\n  list(): ChatOutboxEntry[] {\n    return cloneEntries(this.entries)\n  }\n\n  async enqueue(message: ChatMessage): Promise<ChatOutboxEntry> {\n    await this.hydrate()\n    const normalized = normalizeChatMessage({\n      ...message,\n      clientMessageId: message.clientMessageId ?? message.id,\n    })\n    const key = getOutboxKey(normalized)\n    const existing = this.entries.find(entry => entry.id === key)\n    if (existing) return cloneEntry(existing)\n\n    const entry: ChatOutboxEntry = {\n      id: key,\n      message: normalized,\n      enqueuedAt: this.now(),\n      attempts: 0,\n      state: 'pending',\n    }\n    this.entries.push(entry)\n    await this.persist()\n    return cloneEntry(entry)\n  }\n\n  async remove(id: string): Promise<boolean> {\n    await this.hydrate()\n    const index = this.entries.findIndex(entry => entry.id === id)\n    if (index < 0) return false\n    this.entries.splice(index, 1)\n    await this.persist()\n    return true\n  }\n\n  async retry(id?: string): Promise<void> {\n    await this.hydrate()\n    for (const entry of this.entries) {\n      if (!id || entry.id === id) {\n        entry.state = 'pending'\n        entry.lastError = undefined\n      }\n    }\n    await this.persist()\n  }\n\n  async clear(): Promise<void> {\n    await this.hydrate()\n    this.entries = []\n    await this.persist()\n  }\n\n  async flush(\n    send: (\n      message: ChatMessage,\n      options: { signal?: AbortSignal; clientMessageId: string }\n    ) => Promise<unknown>,\n    options: ChatOutboxFlushOptions = {}\n  ): Promise<ChatOutboxFlushResult> {\n    await this.hydrate()\n    const maxAttempts = Math.max(1, Math.floor(options.maxAttempts ?? 3))\n    const concurrency = Math.min(\n      8,\n      Math.max(1, Math.floor(options.concurrency ?? 1))\n    )\n    const candidates = this.entries.filter(entry => entry.state === 'pending')\n    const sent: string[] = []\n    const failed: Array<{ id: string; error: unknown }> = []\n    let cursor = 0\n\n    const worker = async () => {\n      while (cursor < candidates.length) {\n        if (options.signal?.aborted) throw createAbortError()\n        const entry = candidates[cursor++]\n        entry.attempts += 1\n        try {\n          await send(entry.message, {\n            signal: options.signal,\n            clientMessageId: entry.message.clientMessageId ?? entry.id,\n          })\n          const index = this.entries.findIndex(item => item.id === entry.id)\n          if (index >= 0) this.entries.splice(index, 1)\n          sent.push(entry.id)\n        } catch (error) {\n          entry.lastError = toErrorMessage(error)\n          if (entry.attempts >= maxAttempts) entry.state = 'failed'\n          failed.push({ id: entry.id, error })\n        }\n        await this.persist()\n      }\n    }\n\n    await Promise.all(Array.from({ length: concurrency }, () => worker()))\n    return { sent, failed, remaining: this.list() }\n  }\n\n  private async persist(): Promise<void> {\n    const snapshot = cloneEntries(this.entries)\n    const previous = this.writePromise\n    this.writePromise = previous.then(() => this.storage.save(snapshot))\n    await this.writePromise\n  }\n}\n\nfunction getOutboxKey(message: ChatMessage): string {\n  return message.clientMessageId ?? message.id\n}\n\nfunction cloneEntry(entry: ChatOutboxEntry): ChatOutboxEntry {\n  return {\n    ...entry,\n    message: cloneChatMessage(entry.message),\n  }\n}\n\nfunction cloneEntries(entries: ChatOutboxEntry[]): ChatOutboxEntry[] {\n  return entries.map(cloneEntry)\n}\n\nfunction normalizeEntry(entry: ChatOutboxEntry): ChatOutboxEntry {\n  const message = normalizeChatMessage(entry.message)\n  const id =\n    typeof entry.id === 'string' && entry.id ? entry.id : getOutboxKey(message)\n  const enqueuedAt = Number.isFinite(entry.enqueuedAt)\n    ? entry.enqueuedAt\n    : Date.now()\n  const attempts = Number.isFinite(entry.attempts)\n    ? Math.max(0, Math.floor(entry.attempts))\n    : 0\n  const state = entry.state === 'failed' ? 'failed' : 'pending'\n  return {\n    id,\n    message,\n    enqueuedAt,\n    attempts,\n    state,\n    ...(typeof entry.lastError === 'string' && {\n      lastError: entry.lastError,\n    }),\n  }\n}\n\nfunction toErrorMessage(error: unknown): string {\n  return error instanceof Error ? error.message : String(error)\n}\n\nfunction createAbortError(): DOMException {\n  return new DOMException('The operation was aborted.', 'AbortError')\n}\n"],"mappings":"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"}

package/esm/core/transport.d.ts

@@ -0,0 +1,79 @@
+import type { ChatMessage } from '../types';
+/** transport 连接状态。 */
+export type ChatTransportStatus = 'idle' | 'connecting' | 'connected' | 'disconnected' | 'error';
+/** 建立 transport 时传入的同步上下文。 */
+export interface ChatTransportContext {
+    conversationId?: string;
+    cursor?: string;
+    signal?: AbortSignal;
+}
+/** transport ack，可携带服务端补全后的消息和同步序号。 */
+export interface ChatTransportAck {
+    clientMessageId: string;
+    message?: Partial<ChatMessage>;
+    sequence?: number;
+    cursor?: string;
+}
+/** transport 推送的统一事件协议。 */
+export type ChatTransportEvent = {
+    type: 'message';
+    message: ChatMessage;
+    sequence?: number;
+    cursor?: string;
+} | {
+    type: 'ack';
+    ack: ChatTransportAck;
+} | {
+    type: 'cursor';
+    cursor: string;
+} | {
+    type: 'error';
+    error: unknown;
+    recoverable?: boolean;
+};
+/** 可由 HTTP/SSE/WebSocket/原生 App bridge 实现的最小 transport 协议。 */
+export interface ChatTransport {
+    connect: (context?: ChatTransportContext) => void | Promise<void>;
+    disconnect: () => void | Promise<void>;
+    send: (message: ChatMessage, options?: {
+        signal?: AbortSignal;
+        clientMessageId?: string;
+    }) => Promise<ChatTransportAck | void>;
+    subscribe: (listener: (event: ChatTransportEvent) => void) => () => void;
+    onStatusChange?: (listener: (status: ChatTransportStatus) => void) => () => void;
+}
+export interface ChatTransportControllerOptions {
+    conversationId?: string;
+    cursor?: string;
+    onEvent?: (event: ChatTransportEvent) => void;
+    onStatusChange?: (status: ChatTransportStatus) => void;
+}
+/**
+ * 连接生命周期、游标和外部 transport 事件的统一控制器。
+ *
+ * Controller 不假设网络实现，负责避免重复 connect、转发状态、保存 cursor，
+ * 并在 dispose 后拒绝迟到的异步结果。
+ */
+export declare class ChatTransportController {
+    private readonly transport;
+    private readonly options;
+    private status;
+    private cursor?;
+    private unsubscribeEvents;
+    private unsubscribeStatus;
+    private destroyed;
+    private connectPromise;
+    private lifecycle;
+    constructor(transport: ChatTransport, options?: ChatTransportControllerOptions);
+    getStatus(): ChatTransportStatus;
+    getCursor(): string | undefined;
+    connect(signal?: AbortSignal): Promise<void>;
+    disconnect(): Promise<void>;
+    send(message: ChatMessage, options?: {
+        signal?: AbortSignal;
+        clientMessageId?: string;
+    }): Promise<ChatTransportAck | void>;
+    dispose(): void;
+    private handleEvent;
+    private setStatus;
+}

package/esm/core/transport.js

@@ -0,0 +1,102 @@
+/*!
+* ***********************************
+* @composy/chat-core v0.0.2       *
+* Built with rollup               *
+* Build time: 2024-10-12 21:52:18 *
+* Build mode: production          *
+* Minified: No                    *
+* ***********************************
+*/
+//#region src/core/transport.ts
+var ChatTransportController = class {
+	constructor(transport, options = {}) {
+		this.status = "idle";
+		this.unsubscribeEvents = null;
+		this.unsubscribeStatus = null;
+		this.destroyed = false;
+		this.connectPromise = null;
+		this.lifecycle = 0;
+		this.transport = transport;
+		this.options = options;
+		this.cursor = options.cursor;
+	}
+	getStatus() {
+		return this.status;
+	}
+	getCursor() {
+		return this.cursor;
+	}
+	async connect(signal) {
+		if (this.destroyed) throw new Error("Chat transport controller is disposed.");
+		if (this.status === "connected") return;
+		if (this.connectPromise) return this.connectPromise;
+		const lifecycle = ++this.lifecycle;
+		this.setStatus("connecting");
+		this.connectPromise = (async () => {
+			this.unsubscribeEvents?.();
+			this.unsubscribeStatus?.();
+			this.unsubscribeEvents = this.transport.subscribe((event) => this.handleEvent(event));
+			this.unsubscribeStatus = this.transport.onStatusChange?.((status) => this.setStatus(status)) ?? null;
+			try {
+				await this.transport.connect({
+					conversationId: this.options.conversationId,
+					cursor: this.cursor,
+					signal
+				});
+				if (this.destroyed || lifecycle !== this.lifecycle) return;
+				this.setStatus("connected");
+			} catch (error) {
+				if (!this.destroyed && lifecycle === this.lifecycle) this.setStatus("error");
+				throw error;
+			} finally {
+				this.connectPromise = null;
+			}
+		})();
+		return this.connectPromise;
+	}
+	async disconnect() {
+		if (this.destroyed) return;
+		this.lifecycle += 1;
+		this.connectPromise = null;
+		try {
+			await this.transport.disconnect();
+		} finally {
+			this.setStatus("disconnected");
+		}
+	}
+	async send(message, options = {}) {
+		if (this.destroyed) throw new Error("Chat transport controller is disposed.");
+		if (this.status !== "connected") throw new Error(`Chat transport is not connected: ${this.status}`);
+		const result = await this.transport.send(message, options);
+		if (result && result.cursor) this.cursor = result.cursor;
+		return result;
+	}
+	dispose() {
+		if (this.destroyed) return;
+		this.destroyed = true;
+		this.lifecycle += 1;
+		this.unsubscribeEvents?.();
+		this.unsubscribeStatus?.();
+		this.unsubscribeEvents = null;
+		this.unsubscribeStatus = null;
+		this.connectPromise = null;
+		Promise.resolve(this.transport.disconnect()).catch(() => void 0);
+		this.setStatus("disconnected");
+	}
+	handleEvent(event) {
+		if (this.destroyed) return;
+		if ("cursor" in event && event.cursor) this.cursor = event.cursor;
+		if (event.type === "ack" && event.ack.cursor) this.cursor = event.ack.cursor;
+		if (event.type === "error" && !event.recoverable) this.setStatus("error");
+		this.options.onEvent?.(event);
+	}
+	setStatus(status) {
+		if (this.status === status) return;
+		this.status = status;
+		this.options.onStatusChange?.(status);
+	}
+};
+//#endregion
+export { ChatTransportController };
+/*! End of @composy/chat-core | Powered by @composy/builder */
+//# sourceMappingURL=transport.js.map

package/esm/core/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","names":[],"sources":["../../src/core/transport.ts"],"sourcesContent":["import type { ChatMessage } from '../types'\n\n/** transport 连接状态。 */\nexport type ChatTransportStatus =\n  'idle' | 'connecting' | 'connected' | 'disconnected' | 'error'\n\n/** 建立 transport 时传入的同步上下文。 */\nexport interface ChatTransportContext {\n  conversationId?: string\n  cursor?: string\n  signal?: AbortSignal\n}\n\n/** transport ack，可携带服务端补全后的消息和同步序号。 */\nexport interface ChatTransportAck {\n  clientMessageId: string\n  message?: Partial<ChatMessage>\n  sequence?: number\n  cursor?: string\n}\n\n/** transport 推送的统一事件协议。 */\nexport type ChatTransportEvent =\n  | {\n      type: 'message'\n      message: ChatMessage\n      sequence?: number\n      cursor?: string\n    }\n  | { type: 'ack'; ack: ChatTransportAck }\n  | { type: 'cursor'; cursor: string }\n  | { type: 'error'; error: unknown; recoverable?: boolean }\n\n/** 可由 HTTP/SSE/WebSocket/原生 App bridge 实现的最小 transport 协议。 */\nexport interface ChatTransport {\n  connect: (context?: ChatTransportContext) => void | Promise<void>\n  disconnect: () => void | Promise<void>\n  send: (\n    message: ChatMessage,\n    options?: { signal?: AbortSignal; clientMessageId?: string }\n  ) => Promise<ChatTransportAck | void>\n  subscribe: (listener: (event: ChatTransportEvent) => void) => () => void\n  onStatusChange?: (\n    listener: (status: ChatTransportStatus) => void\n  ) => () => void\n}\n\nexport interface ChatTransportControllerOptions {\n  conversationId?: string\n  cursor?: string\n  onEvent?: (event: ChatTransportEvent) => void\n  onStatusChange?: (status: ChatTransportStatus) => void\n}\n\n/**\n * 连接生命周期、游标和外部 transport 事件的统一控制器。\n *\n * Controller 不假设网络实现，负责避免重复 connect、转发状态、保存 cursor，\n * 并在 dispose 后拒绝迟到的异步结果。\n */\nexport class ChatTransportController {\n  private readonly transport: ChatTransport\n  private readonly options: ChatTransportControllerOptions\n  private status: ChatTransportStatus = 'idle'\n  private cursor?: string\n  private unsubscribeEvents: (() => void) | null = null\n  private unsubscribeStatus: (() => void) | null = null\n  private destroyed = false\n  private connectPromise: Promise<void> | null = null\n  private lifecycle = 0\n\n  constructor(\n    transport: ChatTransport,\n    options: ChatTransportControllerOptions = {}\n  ) {\n    this.transport = transport\n    this.options = options\n    this.cursor = options.cursor\n  }\n\n  getStatus(): ChatTransportStatus {\n    return this.status\n  }\n\n  getCursor(): string | undefined {\n    return this.cursor\n  }\n\n  async connect(signal?: AbortSignal): Promise<void> {\n    if (this.destroyed)\n      throw new Error('Chat transport controller is disposed.')\n    if (this.status === 'connected') return\n    if (this.connectPromise) return this.connectPromise\n\n    const lifecycle = ++this.lifecycle\n    this.setStatus('connecting')\n    this.connectPromise = (async () => {\n      this.unsubscribeEvents?.()\n      this.unsubscribeStatus?.()\n      this.unsubscribeEvents = this.transport.subscribe(event =>\n        this.handleEvent(event)\n      )\n      this.unsubscribeStatus =\n        this.transport.onStatusChange?.(status => this.setStatus(status)) ??\n        null\n      try {\n        await this.transport.connect({\n          conversationId: this.options.conversationId,\n          cursor: this.cursor,\n          signal,\n        })\n        if (this.destroyed || lifecycle !== this.lifecycle) return\n        this.setStatus('connected')\n      } catch (error) {\n        if (!this.destroyed && lifecycle === this.lifecycle) {\n          this.setStatus('error')\n        }\n        throw error\n      } finally {\n        this.connectPromise = null\n      }\n    })()\n\n    return this.connectPromise\n  }\n\n  async disconnect(): Promise<void> {\n    if (this.destroyed) return\n    this.lifecycle += 1\n    this.connectPromise = null\n    try {\n      await this.transport.disconnect()\n    } finally {\n      this.setStatus('disconnected')\n    }\n  }\n\n  async send(\n    message: ChatMessage,\n    options: { signal?: AbortSignal; clientMessageId?: string } = {}\n  ): Promise<ChatTransportAck | void> {\n    if (this.destroyed)\n      throw new Error('Chat transport controller is disposed.')\n    if (this.status !== 'connected') {\n      throw new Error(`Chat transport is not connected: ${this.status}`)\n    }\n    const result = await this.transport.send(message, options)\n    if (result && result.cursor) this.cursor = result.cursor\n    return result\n  }\n\n  dispose(): void {\n    if (this.destroyed) return\n    this.destroyed = true\n    this.lifecycle += 1\n    this.unsubscribeEvents?.()\n    this.unsubscribeStatus?.()\n    this.unsubscribeEvents = null\n    this.unsubscribeStatus = null\n    this.connectPromise = null\n    void Promise.resolve(this.transport.disconnect()).catch(() => undefined)\n    this.setStatus('disconnected')\n  }\n\n  private handleEvent(event: ChatTransportEvent): void {\n    if (this.destroyed) return\n    if ('cursor' in event && event.cursor) this.cursor = event.cursor\n    if (event.type === 'ack' && event.ack.cursor) {\n      this.cursor = event.ack.cursor\n    }\n    if (event.type === 'error' && !event.recoverable) this.setStatus('error')\n    this.options.onEvent?.(event)\n  }\n\n  private setStatus(status: ChatTransportStatus): void {\n    if (this.status === status) return\n    this.status = status\n    this.options.onStatusChange?.(status)\n  }\n}\n"],"mappings":";;;;;;;;;;AA4DO,IAAM,0BAAN,MAA8B;CAWnC,YACE,WACA,UAA0C,CAAC,GAC3C;EAXF,KAAQ,SAA8B;EAEtC,KAAQ,oBAAyC;EACjD,KAAQ,oBAAyC;EACjD,KAAQ,YAAY;EACpB,KAAQ,iBAAuC;EAC/C,KAAQ,YAAY;EAMlB,KAAK,YAAY;EACjB,KAAK,UAAU;EACf,KAAK,SAAS,QAAQ;CACxB;CAEA,YAAiC;EAC/B,OAAO,KAAK;CACd;CAEA,YAAgC;EAC9B,OAAO,KAAK;CACd;CAEA,MAAM,QAAQ,QAAqC;EACjD,IAAI,KAAK,WACP,MAAM,IAAI,MAAM,wCAAwC;EAC1D,IAAI,KAAK,WAAW,aAAa;EACjC,IAAI,KAAK,gBAAgB,OAAO,KAAK;EAErC,MAAM,YAAY,EAAE,KAAK;EACzB,KAAK,UAAU,YAAY;EAC3B,KAAK,kBAAkB,YAAY;GACjC,KAAK,oBAAoB;GACzB,KAAK,oBAAoB;GACzB,KAAK,oBAAoB,KAAK,UAAU,WAAU,UAChD,KAAK,YAAY,KAAK,CACxB;GACA,KAAK,oBACH,KAAK,UAAU,kBAAiB,WAAU,KAAK,UAAU,MAAM,CAAC,KAChE;GACF,IAAI;IACF,MAAM,KAAK,UAAU,QAAQ;KAC3B,gBAAgB,KAAK,QAAQ;KAC7B,QAAQ,KAAK;KACb;IACF,CAAC;IACD,IAAI,KAAK,aAAa,cAAc,KAAK,WAAW;IACpD,KAAK,UAAU,WAAW;GAC5B,SAAS,OAAO;IACd,IAAI,CAAC,KAAK,aAAa,cAAc,KAAK,WACxC,KAAK,UAAU,OAAO;IAExB,MAAM;GACR,UAAE;IACA,KAAK,iBAAiB;GACxB;EACF,EAAA,CAAG;EAEH,OAAO,KAAK;CACd;CAEA,MAAM,aAA4B;EAChC,IAAI,KAAK,WAAW;EACpB,KAAK,aAAa;EAClB,KAAK,iBAAiB;EACtB,IAAI;GACF,MAAM,KAAK,UAAU,WAAW;EAClC,UAAE;GACA,KAAK,UAAU,cAAc;EAC/B;CACF;CAEA,MAAM,KACJ,SACA,UAA8D,CAAC,GAC7B;EAClC,IAAI,KAAK,WACP,MAAM,IAAI,MAAM,wCAAwC;EAC1D,IAAI,KAAK,WAAW,aAClB,MAAM,IAAI,MAAM,oCAAoC,KAAK,QAAQ;EAEnE,MAAM,SAAS,MAAM,KAAK,UAAU,KAAK,SAAS,OAAO;EACzD,IAAI,UAAU,OAAO,QAAQ,KAAK,SAAS,OAAO;EAClD,OAAO;CACT;CAEA,UAAgB;EACd,IAAI,KAAK,WAAW;EACpB,KAAK,YAAY;EACjB,KAAK,aAAa;EAClB,KAAK,oBAAoB;EACzB,KAAK,oBAAoB;EACzB,KAAK,oBAAoB;EACzB,KAAK,oBAAoB;EACzB,KAAK,iBAAiB;EACtB,QAAa,QAAQ,KAAK,UAAU,WAAW,CAAC,CAAA,CAAE,YAAY,KAAA,CAAS;EACvE,KAAK,UAAU,cAAc;CAC/B;CAEQ,YAAY,OAAiC;EACnD,IAAI,KAAK,WAAW;EACpB,IAAI,YAAY,SAAS,MAAM,QAAQ,KAAK,SAAS,MAAM;EAC3D,IAAI,MAAM,SAAS,SAAS,MAAM,IAAI,QACpC,KAAK,SAAS,MAAM,IAAI;EAE1B,IAAI,MAAM,SAAS,WAAW,CAAC,MAAM,aAAa,KAAK,UAAU,OAAO;EACxE,KAAK,QAAQ,UAAU,KAAK;CAC9B;CAEQ,UAAU,QAAmC;EACnD,IAAI,KAAK,WAAW,QAAQ;EAC5B,KAAK,SAAS;EACd,KAAK,QAAQ,iBAAiB,MAAM;CACtC;AACF"}

package/esm/index.d.ts

@@ -10,19 +10,24 @@
  */
 import type { ChatConfig, ChatInstance } from './types';
 export declare const version = "0.1.0";
-export * from './types';
-export { EventEmitter } from './core/event-emitter';
+export { COMPONENT_CSS_VAR_PREFIX, cx, DEFAULT_CLASS_PREFIX, getStyleElementId, normalizeClassPrefix, STYLE_ELEMENT_ID, } from './constants/dom';
 export { ChatManager } from './core/chat-manager';
+export type { MessageMergeOptions, MessageMergeResult, StreamAppendOptions, } from './core/chat-manager';
+export { EventEmitter } from './core/event-emitter';
 export { MentionEngine } from './core/mention-engine';
 export type { MentionState } from './core/mention-engine';
+export { cloneChatMessage, compareChatMessages, normalizeChatContentBlocks, normalizeChatMessage, normalizeChatMessages, } from './core/message-schema';
+export { ChatOutbox, MemoryChatOutboxStorage } from './core/outbox';
+export type { ChatOutboxEntry, ChatOutboxFlushOptions, ChatOutboxFlushResult, ChatOutboxOptions, ChatOutboxStorage, } from './core/outbox';
+export { ChatTransportController } from './core/transport';
+export type { ChatTransport, ChatTransportAck, ChatTransportContext, ChatTransportControllerOptions, ChatTransportEvent, ChatTransportStatus, } from './core/transport';
+export { DOMRenderer } from './renderer/dom-renderer';
+export { cls, clsx, injectStyles, removeStyles, updateStyles, } from './renderer/style-manager';
 export { ThemeManager } from './theme/theme-manager';
 export type { ThemeTokens } from './theme/tokens';
-export { lightTokens, darkTokens } from './theme/tokens';
-export { DOMRenderer } from './renderer/dom-renderer';
-export { injectStyles, updateStyles, removeStyles, cls, clsx } from './renderer/style-manager';
-export { DEFAULT_CLASS_PREFIX, COMPONENT_CSS_VAR_PREFIX, STYLE_ELEMENT_ID, getStyleElementId, normalizeClassPrefix, cx, } from './constants/dom';
+export { darkTokens, lightTokens } from './theme/tokens';
+export * from './types';
 /**
  * 创建聊天实例
  */
 export declare function createChat(config: ChatConfig): ChatInstance;
-//# sourceMappingURL=index.d.ts.map