@composy/chat-core 0.0.1 → 0.0.2

package/lib/core/message-schema.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-schema.cjs","names":["clone"],"sources":["../../src/core/message-schema.ts"],"sourcesContent":["import type {\n  ChatContentBlock,\n  ChatMessage,\n  ChatUser,\n  FileAttachment,\n  ImageAttachment,\n  MentionItem,\n} from '../types'\nimport { CHAT_MESSAGE_SCHEMA_VERSION } from '../types'\n\n/**\n * 归一化消息并复制所有可变字段。\n *\n * 该函数是 transport、outbox、ChatManager 共享的边界：外部数据先经过\n * schema/version 校验，再进入内存状态，避免调用方继续修改内部消息。\n */\nexport function normalizeChatMessage(message: ChatMessage): ChatMessage {\n  if (!message || typeof message !== 'object') {\n    throw new TypeError('Chat message must be an object.')\n  }\n  if (typeof message.id !== 'string' || !message.id.trim()) {\n    throw new TypeError('Chat message ID must be a non-empty string.')\n  }\n  if (!Number.isFinite(message.timestamp)) {\n    throw new TypeError('Chat message timestamp must be finite.')\n  }\n  const schemaVersion = message.schemaVersion ?? CHAT_MESSAGE_SCHEMA_VERSION\n  if (schemaVersion > CHAT_MESSAGE_SCHEMA_VERSION) {\n    throw new Error(\n      `Unsupported chat message schema version: ${schemaVersion}.`\n    )\n  }\n\n  return cloneChatMessage({\n    ...message,\n    schemaVersion: CHAT_MESSAGE_SCHEMA_VERSION,\n    ...(message.contentBlocks && {\n      contentBlocks: normalizeChatContentBlocks(message.contentBlocks),\n    }),\n  })\n}\n\n/**\n * 对来自网络/持久化的 content block 做运行时白名单归一化。\n * 不认识的块优先使用 fallback 文本，否则丢弃，避免将任意对象带入渲染器。\n */\nexport function normalizeChatContentBlocks(\n  blocks: unknown[]\n): ChatContentBlock[] {\n  const normalized: ChatContentBlock[] = []\n  for (const value of blocks) {\n    const block = normalizeContentBlock(value)\n    if (block) normalized.push(block)\n  }\n  return normalized\n}\n\n/** 归一化消息集合，并在进入状态层前拒绝重复的消息 ID/client ID。 */\nexport function normalizeChatMessages(messages: ChatMessage[]): ChatMessage[] {\n  const result: ChatMessage[] = []\n  const ids = new Set<string>()\n  const clientIds = new Set<string>()\n  for (const message of messages) {\n    const normalized = normalizeChatMessage(message)\n    if (ids.has(normalized.id)) {\n      throw new Error(`Duplicate chat message ID: ${normalized.id}`)\n    }\n    if (\n      normalized.clientMessageId &&\n      clientIds.has(normalized.clientMessageId)\n    ) {\n      throw new Error(\n        `Duplicate chat client message ID: ${normalized.clientMessageId}`\n      )\n    }\n    ids.add(normalized.id)\n    if (normalized.clientMessageId) clientIds.add(normalized.clientMessageId)\n    result.push(normalized)\n  }\n  return result\n}\n\n/** 复制消息，用于事件 payload、outbox 与公开读取，避免可变引用泄漏。 */\nexport function cloneChatMessage(message: ChatMessage): ChatMessage {\n  return {\n    ...message,\n    sender: cloneUser(message.sender),\n    ...(message.image && { image: cloneImage(message.image) }),\n    ...(message.file && { file: cloneFile(message.file) }),\n    ...(message.mentions && {\n      mentions: message.mentions.map(cloneMention),\n    }),\n    ...(message.contentBlocks && {\n      contentBlocks: message.contentBlocks.map(cloneContentBlock),\n    }),\n    ...(message.customData && {\n      customData: cloneRecord(message.customData),\n    }),\n  }\n}\n\n/** 根据服务端 sequence/timestamp 给出稳定排序值。 */\nexport function compareChatMessages(left: ChatMessage, right: ChatMessage) {\n  if (\n    Number.isFinite(left.sequence) &&\n    Number.isFinite(right.sequence) &&\n    left.sequence !== right.sequence\n  ) {\n    return (left.sequence as number) - (right.sequence as number)\n  }\n  if (left.timestamp !== right.timestamp)\n    return left.timestamp - right.timestamp\n  return left.id.localeCompare(right.id)\n}\n\nfunction cloneContentBlock(block: ChatContentBlock): ChatContentBlock {\n  switch (block.type) {\n    case 'text':\n      return { type: 'text', text: block.text }\n    case 'mention':\n      return { type: 'mention', id: block.id, label: block.label }\n    case 'link':\n      return {\n        type: 'link',\n        url: block.url,\n        ...(block.label && { label: block.label }),\n      }\n    case 'code':\n      return {\n        type: 'code',\n        code: block.code,\n        ...(block.language && { language: block.language }),\n      }\n    case 'image':\n      return {\n        type: 'image',\n        src: block.src,\n        ...(block.alt && { alt: block.alt }),\n        ...(block.width !== undefined && { width: block.width }),\n        ...(block.height !== undefined && { height: block.height }),\n      }\n    case 'file':\n      return {\n        type: 'file',\n        url: block.url,\n        name: block.name,\n        ...(block.size !== undefined && { size: block.size }),\n        ...(block.mimeType && { mimeType: block.mimeType }),\n      }\n    case 'break':\n      return { type: 'break' }\n    case 'custom':\n      return {\n        type: 'custom',\n        kind: block.kind,\n        data: cloneRecord(block.data),\n        ...(block.fallback && { fallback: block.fallback }),\n      }\n  }\n}\n\nfunction normalizeContentBlock(value: unknown): ChatContentBlock | null {\n  if (!isRecord(value) || typeof value.type !== 'string') return null\n  switch (value.type) {\n    case 'text':\n      return typeof value.text === 'string'\n        ? { type: 'text', text: value.text }\n        : null\n    case 'mention':\n      return typeof value.id === 'string' && typeof value.label === 'string'\n        ? { type: 'mention', id: value.id, label: value.label }\n        : null\n    case 'link':\n      return typeof value.url === 'string'\n        ? {\n            type: 'link',\n            url: value.url,\n            ...(typeof value.label === 'string' && { label: value.label }),\n          }\n        : null\n    case 'code':\n      return typeof value.code === 'string'\n        ? {\n            type: 'code',\n            code: value.code,\n            ...(typeof value.language === 'string' && {\n              language: value.language,\n            }),\n          }\n        : null\n    case 'image':\n      return typeof value.src === 'string'\n        ? {\n            type: 'image',\n            src: value.src,\n            ...(typeof value.alt === 'string' && { alt: value.alt }),\n            ...(isPositiveNumber(value.width) && { width: value.width }),\n            ...(isPositiveNumber(value.height) && { height: value.height }),\n          }\n        : null\n    case 'file':\n      return typeof value.url === 'string' && typeof value.name === 'string'\n        ? {\n            type: 'file',\n            url: value.url,\n            name: value.name,\n            ...(isPositiveNumber(value.size) && { size: value.size }),\n            ...(typeof value.mimeType === 'string' && {\n              mimeType: value.mimeType,\n            }),\n          }\n        : null\n    case 'break':\n      return { type: 'break' }\n    case 'custom':\n      return typeof value.kind === 'string' && isRecord(value.data)\n        ? {\n            type: 'custom',\n            kind: value.kind,\n            data: cloneRecord(value.data),\n            ...(typeof value.fallback === 'string' && {\n              fallback: value.fallback,\n            }),\n          }\n        : fallbackBlock(value)\n    default:\n      return fallbackBlock(value)\n  }\n}\n\nfunction fallbackBlock(\n  value: Record<string, unknown>\n): ChatContentBlock | null {\n  return typeof value.fallback === 'string'\n    ? { type: 'text', text: value.fallback }\n    : null\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)\n}\n\nfunction isPositiveNumber(value: unknown): value is number {\n  return typeof value === 'number' && Number.isFinite(value) && value > 0\n}\n\nfunction cloneUser(user: ChatUser): ChatUser {\n  return { ...user }\n}\n\nfunction cloneMention(mention: MentionItem): MentionItem {\n  return { ...mention }\n}\n\nfunction cloneImage(image: ImageAttachment): ImageAttachment {\n  return { ...image }\n}\n\nfunction cloneFile(file: FileAttachment): FileAttachment {\n  return { ...file }\n}\n\nfunction cloneRecord<T>(value: T, seen = new WeakMap<object, unknown>()): T {\n  if (!value || typeof value !== 'object') return value\n  if (seen.has(value)) return seen.get(value) as T\n  if (Array.isArray(value)) {\n    const clone: unknown[] = []\n    seen.set(value, clone)\n    value.forEach(item => clone.push(cloneRecord(item, seen)))\n    return clone as T\n  }\n\n  const prototype = Object.getPrototypeOf(value)\n  if (prototype !== Object.prototype && prototype !== null) return value\n  const clone: Record<string, unknown> = {}\n  seen.set(value, clone)\n  Object.entries(value).forEach(([key, item]) => {\n    clone[key] = cloneRecord(item, seen)\n  })\n  return clone as T\n}\n"],"mappings":"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"}

package/lib/core/message-schema.d.cts

@@ -0,0 +1,19 @@
+import type { ChatContentBlock, ChatMessage } from '../types';
+/**
+ * 归一化消息并复制所有可变字段。
+ *
+ * 该函数是 transport、outbox、ChatManager 共享的边界：外部数据先经过
+ * schema/version 校验，再进入内存状态，避免调用方继续修改内部消息。
+ */
+export declare function normalizeChatMessage(message: ChatMessage): ChatMessage;
+/**
+ * 对来自网络/持久化的 content block 做运行时白名单归一化。
+ * 不认识的块优先使用 fallback 文本，否则丢弃，避免将任意对象带入渲染器。
+ */
+export declare function normalizeChatContentBlocks(blocks: unknown[]): ChatContentBlock[];
+/** 归一化消息集合，并在进入状态层前拒绝重复的消息 ID/client ID。 */
+export declare function normalizeChatMessages(messages: ChatMessage[]): ChatMessage[];
+/** 复制消息，用于事件 payload、outbox 与公开读取，避免可变引用泄漏。 */
+export declare function cloneChatMessage(message: ChatMessage): ChatMessage;
+/** 根据服务端 sequence/timestamp 给出稳定排序值。 */
+export declare function compareChatMessages(left: ChatMessage, right: ChatMessage): number;

package/lib/core/message-schema.d.ts

@@ -0,0 +1,19 @@
+import type { ChatContentBlock, ChatMessage } from '../types';
+/**
+ * 归一化消息并复制所有可变字段。
+ *
+ * 该函数是 transport、outbox、ChatManager 共享的边界：外部数据先经过
+ * schema/version 校验，再进入内存状态，避免调用方继续修改内部消息。
+ */
+export declare function normalizeChatMessage(message: ChatMessage): ChatMessage;
+/**
+ * 对来自网络/持久化的 content block 做运行时白名单归一化。
+ * 不认识的块优先使用 fallback 文本，否则丢弃，避免将任意对象带入渲染器。
+ */
+export declare function normalizeChatContentBlocks(blocks: unknown[]): ChatContentBlock[];
+/** 归一化消息集合，并在进入状态层前拒绝重复的消息 ID/client ID。 */
+export declare function normalizeChatMessages(messages: ChatMessage[]): ChatMessage[];
+/** 复制消息，用于事件 payload、outbox 与公开读取，避免可变引用泄漏。 */
+export declare function cloneChatMessage(message: ChatMessage): ChatMessage;
+/** 根据服务端 sequence/timestamp 给出稳定排序值。 */
+export declare function compareChatMessages(left: ChatMessage, right: ChatMessage): number;

package/lib/core/outbox.cjs

@@ -0,0 +1,162 @@
+/*!
+* ***********************************
+* @composy/chat-core v0.0.2       *
+* Built with rollup               *
+* Build time: 2024-10-12 21:52:18 *
+* Build mode: production          *
+* Minified: No                    *
+* ***********************************
+*/
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_message_schema = require("./message-schema.cjs");
+//#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 = require_message_schema.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: require_message_schema.cloneChatMessage(entry.message)
+	};
+}
+function cloneEntries(entries) {
+	return entries.map(cloneEntry);
+}
+function normalizeEntry(entry) {
+	const message = require_message_schema.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
+exports.ChatOutbox = ChatOutbox;
+exports.MemoryChatOutboxStorage = MemoryChatOutboxStorage;
+/*! End of @composy/chat-core | Powered by @composy/builder */
+//# sourceMappingURL=outbox.cjs.map

package/lib/core/outbox.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox.cjs","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/lib/core/outbox.d.cts

@@ -0,0 +1,63 @@
+import type { ChatMessage } from '../types';
+/** 离线 outbox 中的一条待发送消息。 */
+export interface ChatOutboxEntry {
+    id: string;
+    message: ChatMessage;
+    enqueuedAt: number;
+    attempts: number;
+    state: 'pending' | 'failed';
+    lastError?: string;
+}
+/** outbox 持久化适配器；可接 IndexedDB、SQLite bridge 或业务缓存。 */
+export interface ChatOutboxStorage {
+    load: () => ChatOutboxEntry[] | Promise<ChatOutboxEntry[]>;
+    save: (entries: ChatOutboxEntry[]) => void | Promise<void>;
+}
+/** 内存适配器，适合默认运行和单元测试。 */
+export declare class MemoryChatOutboxStorage implements ChatOutboxStorage {
+    private entries;
+    load(): ChatOutboxEntry[];
+    save(entries: ChatOutboxEntry[]): void;
+}
+export interface ChatOutboxOptions {
+    storage?: ChatOutboxStorage;
+    now?: () => number;
+}
+export interface ChatOutboxFlushOptions {
+    signal?: AbortSignal;
+    maxAttempts?: number;
+    concurrency?: number;
+}
+export interface ChatOutboxFlushResult {
+    sent: string[];
+    failed: Array<{
+        id: string;
+        error: unknown;
+    }>;
+    remaining: ChatOutboxEntry[];
+}
+/**
+ * 幂等离线队列。
+ *
+ * 队列只负责保存和重试，不假设网络协议；发送函数由 ChatTransportController
+ * 或业务层注入。每条消息以 clientMessageId 优先作为幂等键，重复 enqueue 不会产生重复项。
+ */
+export declare class ChatOutbox {
+    private readonly storage;
+    private readonly now;
+    private entries;
+    private hydrated;
+    private writePromise;
+    constructor(options?: ChatOutboxOptions);
+    hydrate(): Promise<ChatOutboxEntry[]>;
+    list(): ChatOutboxEntry[];
+    enqueue(message: ChatMessage): Promise<ChatOutboxEntry>;
+    remove(id: string): Promise<boolean>;
+    retry(id?: string): Promise<void>;
+    clear(): Promise<void>;
+    flush(send: (message: ChatMessage, options: {
+        signal?: AbortSignal;
+        clientMessageId: string;
+    }) => Promise<unknown>, options?: ChatOutboxFlushOptions): Promise<ChatOutboxFlushResult>;
+    private persist;
+}

package/lib/core/outbox.d.ts

@@ -0,0 +1,63 @@
+import type { ChatMessage } from '../types';
+/** 离线 outbox 中的一条待发送消息。 */
+export interface ChatOutboxEntry {
+    id: string;
+    message: ChatMessage;
+    enqueuedAt: number;
+    attempts: number;
+    state: 'pending' | 'failed';
+    lastError?: string;
+}
+/** outbox 持久化适配器；可接 IndexedDB、SQLite bridge 或业务缓存。 */
+export interface ChatOutboxStorage {
+    load: () => ChatOutboxEntry[] | Promise<ChatOutboxEntry[]>;
+    save: (entries: ChatOutboxEntry[]) => void | Promise<void>;
+}
+/** 内存适配器，适合默认运行和单元测试。 */
+export declare class MemoryChatOutboxStorage implements ChatOutboxStorage {
+    private entries;
+    load(): ChatOutboxEntry[];
+    save(entries: ChatOutboxEntry[]): void;
+}
+export interface ChatOutboxOptions {
+    storage?: ChatOutboxStorage;
+    now?: () => number;
+}
+export interface ChatOutboxFlushOptions {
+    signal?: AbortSignal;
+    maxAttempts?: number;
+    concurrency?: number;
+}
+export interface ChatOutboxFlushResult {
+    sent: string[];
+    failed: Array<{
+        id: string;
+        error: unknown;
+    }>;
+    remaining: ChatOutboxEntry[];
+}
+/**
+ * 幂等离线队列。
+ *
+ * 队列只负责保存和重试，不假设网络协议；发送函数由 ChatTransportController
+ * 或业务层注入。每条消息以 clientMessageId 优先作为幂等键，重复 enqueue 不会产生重复项。
+ */
+export declare class ChatOutbox {
+    private readonly storage;
+    private readonly now;
+    private entries;
+    private hydrated;
+    private writePromise;
+    constructor(options?: ChatOutboxOptions);
+    hydrate(): Promise<ChatOutboxEntry[]>;
+    list(): ChatOutboxEntry[];
+    enqueue(message: ChatMessage): Promise<ChatOutboxEntry>;
+    remove(id: string): Promise<boolean>;
+    retry(id?: string): Promise<void>;
+    clear(): Promise<void>;
+    flush(send: (message: ChatMessage, options: {
+        signal?: AbortSignal;
+        clientMessageId: string;
+    }) => Promise<unknown>, options?: ChatOutboxFlushOptions): Promise<ChatOutboxFlushResult>;
+    private persist;
+}

package/lib/core/transport.cjs

@@ -0,0 +1,103 @@
+/*!
+* ***********************************
+* @composy/chat-core v0.0.2       *
+* Built with rollup               *
+* Build time: 2024-10-12 21:52:18 *
+* Build mode: production          *
+* Minified: No                    *
+* ***********************************
+*/
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#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
+exports.ChatTransportController = ChatTransportController;
+/*! End of @composy/chat-core | Powered by @composy/builder */
+//# sourceMappingURL=transport.cjs.map

package/lib/core/transport.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.cjs","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/lib/core/transport.d.cts

@@ -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/lib/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;
+}