chatablex-web-sdk 1.0.0

package/README.md

@@ -0,0 +1,199 @@
+# chatablex-web-sdk
+
+English | [**简体中文**](README.zh-CN.md)
+
+Runtime SDK for building **ChatableX AI App** WebUI applications.
+
+Unlike a type-only package, this SDK contains the actual bridge runtime that connects your web app to the ChatableX Flutter host. You must install it as a dependency — the platform does **not** inject it for you.
+
+## Install
+
+```bash
+npm install chatablex-web-sdk
+# or link locally during development:
+npm install ../chatablex-web-sdk
+```
+
+## Quick Start
+
+```tsx
+import { ChatableX } from 'chatablex-web-sdk';
+
+// Initialize — connects to the Flutter WebView host
+const sdk = await ChatableX.init({ appId: 'my-app', debug: true });
+
+// Register a tool handler (called when the LLM invokes your tool)
+sdk.tool.onExecute(async (params) => {
+  const { action, value } = params;
+  // ... perform action, update UI ...
+  return { success: true, result: 42 };
+});
+```
+
+## What are the SDK namespaces for?
+
+The object returned by `ChatableX.init()` is a **set of APIs grouped by responsibility**. Your WebUI runs inside a WebView; many capabilities (native dialogs, file picking, storage aligned with the main chat, AI calls through the host’s stack) are awkward or inconsistent if you only use browser APIs. These modules call into the **Flutter host via the JS bridge**.
+
+**You do not need every module** for every app — the smallest integration is usually `sdk.tool` (handle LLM invocations). Add others when you need them.
+
+
+| Namespace | Role (why it exists) |
+|-----------|----------------------|
+| **`sdk.tool`** | Register tool execution: when the LLM invokes your tool, the host forwards params into your WebUI and you return a result. This is the **core** hook for an AI App. |
+| **`sdk.events`** | Subscribe to host-side events (e.g. user messages, streaming) so the WebUI stays in sync with the session. |
+| **`sdk.ai`** | Send messages or read session context through the **same host AI pipeline** (`chat`, `getContext`, etc.) instead of wiring your own model only inside the page. |
+| **`sdk.ui`** | Drive **native host UI**: toasts, confirms, file picker, refresh main chrome — same UX and permissions as the desktop client. |
+| **`sdk.storage`** | Key–value storage on the **host** for persistence and sharing with the rest of the app, not only `localStorage` in the WebView. |
+| **`sdk.tools` / `sdk.skills`** | List or invoke other tools and skills on the platform for orchestration. |
+
+The **API** sections below each include: a **typical scenario** (when to use it) + **example code** (how to wire it up).
+
+## API
+
+### `ChatableX.init(config)`
+
+| Option    | Type    | Default | Description |
+|-----------|---------|---------|-------------|
+| `appId`   | string  | —       | **Required.** Must match your `manifest.json` `id`. |
+| `debug`   | boolean | false   | Print debug logs to console. |
+| `timeout` | number  | 10000   | Handshake timeout in ms. |
+
+Returns `Promise<ChatableXSDK>`.
+
+### `sdk.tool`
+
+**When to use**: The user opens your AI App from chat, or the model invokes your tool; the host forwards JSON params into the WebView and you return a result back into the session.
+
+```ts
+sdk.tool.onExecute(async (params) => {
+  const { action, rowId } = params as { action?: string; rowId?: string };
+  if (action === 'delete') {
+    await deleteRow(rowId);
+    return { success: true, message: 'Deleted' };
+  }
+  return { success: false, error: 'unknown action' };
+});
+
+// Metadata from manifest (filled in by the host after handshake)
+const info = sdk.tool.getInfo();
+```
+
+### `sdk.events`
+
+**When to use**: Your side panel should stay in sync with the main window—new user messages, streaming assistant output, or other tool executions should update your UI.
+
+```ts
+const unsubUser = sdk.events.onUserMessage(({ message }) => {
+  appendActivityFeed(`User: ${message}`);
+});
+
+const unsubStream = sdk.events.on('streamingContent', ({ content, finished }) => {
+  setPartialReply(content);
+  if (finished) setLoading(false);
+});
+
+const unsubAi = sdk.events.onAiResponse((data) => {
+  setLastReply(data.content);
+});
+
+// Unsubscribe on unmount to avoid leaks
+// unsubUser(); unsubStream(); unsubAi();
+```
+
+You can also subscribe to `toolExecution`, `close`, etc. (depends on host support).
+
+### `sdk.ai`
+
+**When to use**: A button in your panel like “ask about this session again” should use the **host’s** model and context, not a separate API key inside the page; or you need session metadata for a summary view.
+
+```ts
+const reply = await sdk.ai.chat('Summarize the last user message in three bullets', {
+  stream: false,
+});
+
+const ctx = await sdk.ai.getContext();
+if (ctx.name) setSessionTitle(ctx.name); // some fields depend on host implementation
+
+// Streaming may be pushed by the host; call chatStream when supported
+await sdk.ai.chatStream('Write a short reply', { stream: true });
+```
+
+### `sdk.ui`
+
+**When to use**: Destructive actions need a **native confirm**; long jobs end with a **host toast**; picking files should use the **host file picker**; after work you may **refresh the main transcript** or close the WebUI.
+
+```ts
+await sdk.ui.showNotification('Export finished', 'success');
+
+const ok = await sdk.ui.showConfirm('Delete record', 'This cannot be undone. Continue?');
+if (!ok) return;
+
+const path = await sdk.ui.pickFile({ type: 'image' });
+if (path) await uploadPreview(path);
+
+await sdk.ui.updateState({ refreshMessages: true });
+// await sdk.ui.openTab({ title: 'Details', type: 'custom', data: { id: 'x' } });
+```
+
+### `sdk.storage`
+
+**When to use**: Persist filters, layout, or drafts for your panel on the **host** so it behaves like the rest of the desktop app—not only `localStorage` inside the WebView.
+
+```ts
+const KEY = 'my-app:filters';
+
+await sdk.storage.set(KEY, { projectId: 'p1', sort: 'date' });
+const filters = await sdk.storage.get<{ projectId: string; sort: string }>(KEY);
+await sdk.storage.delete(KEY);
+```
+
+### `sdk.tools` / `sdk.skills`
+
+**When to use**: A one-click flow in your panel chains **other installed tools** in order; or you show a form so the user fills variables and runs a **skill** (a skill may orchestrate several tools). Use `executeWithConfirm` for risky steps so the host shows a confirm dialog first.
+
+```ts
+const tools = await sdk.tools.list();
+setToolPicker(tools.filter((t) => t.id !== sdk.tool.getInfo().id));
+
+const step1 = await sdk.tools.execute('fetch-doc', { url });
+if (!step1.success) throw new Error(step1.error);
+const step2 = await sdk.tools.execute('summarize', { text: step1.data });
+
+// High-risk actions: confirm in the host first
+await sdk.tools.executeWithConfirm('delete-backup', { id: backupId });
+
+const skills = await sdk.skills.list();
+const skillResult = await sdk.skills.execute('weekly-report-skill', {
+  week: '2026-W13',
+  department: 'sales',
+});
+```
+
+## Architecture
+
+```
+Your App (React/Vue/Vanilla)
+    │  import { ChatableX } from 'chatablex-web-sdk'
+    │
+    ▼
+┌─────────────────────────────────────┐
+│  chatablex-web-sdk (this package)   │
+│                                     │
+│  Bridge layer:                      │
+│    JS → Flutter: ChatableXBridge    │
+│    Flutter → JS: ChatableXReceive   │
+│                                     │
+│  Modules: tool, events, ai, ui,    │
+│           storage, tools, skills    │
+└──────────────┬──────────────────────┘
+               │  WebView Bridge
+               ▼
+┌─────────────────────────────────────┐
+│  ChatableX Flutter Client           │
+│  (owns chat UI, SSE stream, agent)  │
+└─────────────────────────────────────┘
+```
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,199 @@
+# chatablex-web-sdk
+
+**[English](README.md)** | 简体中文
+
+用于构建 **ChatableX AI App** WebUI 应用的运行时 SDK。
+
+与仅提供类型的包不同，本 SDK 包含将 Web 应用连接到 ChatableX Flutter 宿主的真实桥接运行时。你必须将其作为依赖安装.
+
+## 安装
+
+```bash
+npm install chatablex-web-sdk
+```
+
+## 快速开始
+
+```tsx
+import { ChatableX } from 'chatablex-web-sdk';
+
+// 初始化 —— 连接 Flutter WebView 宿主
+const sdk = await ChatableX.init({ appId: 'my-app', debug: true });
+
+// 注册工具处理器（当 LLM 调用你的工具时触发）
+sdk.tool.onExecute(async (params) => {
+  const { action, value } = params;
+  // ... 执行操作、更新 UI ...
+  return { success: true, result: 42 };
+});
+```
+
+## SDK 模块是做什么的？
+
+`ChatableX.init()` 返回的 `sdk` 是一个**按职责划分的 API 集合**。WebUI 跑在 WebView 里，很多能力（系统对话框、文件选择、与主聊天同步的存储、走宿主模型的对话等）在浏览器里要么不好做、要么和 Flutter 主应用割裂。这些模块都通过 **JS ↔ Flutter 桥** 调用宿主已实现的能力。
+
+**你不一定要用到每一个模块**：最小集成往往只需要 `sdk.tool`（响应 LLM 调用）；其余按需选用。
+
+
+| 命名空间 | 用途（为什么要单独拆出来） |
+|----------|---------------------------|
+| **`sdk.tool`** | 注册工具执行逻辑：LLM 调用你的工具时由宿主把参数传进来，你在 WebUI 里算完再返回结果。这是 AI App 的**核心**入口。 |
+| **`sdk.events`** | 订阅宿主侧事件（如用户消息、流式内容），让 WebUI 与当前会话状态对齐。 |
+| **`sdk.ai`** | 在 WebUI 内向**宿主同一条 AI 管线**发消息或拉取会话上下文（`chat` / `getContext` 等），避免你在页面里自己再接一套模型。 |
+| **`sdk.ui`** | 用**宿主原生 UI** 做提示、确认框、选文件、通知主界面刷新等，体验和权限与桌面客户端一致。 |
+| **`sdk.storage`** | 键值存储走**宿主侧**，便于与 App 其它部分共享状态、持久化，而不只存在页面的 `localStorage` 里。 |
+| **`sdk.tools` / `sdk.skills`** | 列举或调用平台上其它工具、技能，做编排或联动。 |
+
+下面「API」各节包含：**典型场景**（什么时候用）+ **示例代码**（怎么接）。
+
+## API
+
+### `ChatableX.init(config)`
+
+
+| 选项        | 类型      | 默认值   | 说明                                    |
+| --------- | ------- | ----- | ------------------------------------- |
+| `appId`   | string  | —     | **必填。**须与 `manifest.json` 中的 `id` 一致。 |
+| `debug`   | boolean | false | 是否在控制台打印调试日志。                         |
+| `timeout` | number  | 10000 | 握手超时时间（毫秒）。                           |
+
+
+返回 `Promise<ChatableXSDK>`。
+
+### `sdk.tool`
+
+**典型场景**：用户在聊天里触发你的 AI App，或模型根据上下文调用你的工具；宿主把 JSON 参数推进 WebView，你要执行逻辑并把结果返回给会话。
+
+```ts
+sdk.tool.onExecute(async (params) => {
+  const { action, rowId } = params as { action?: string; rowId?: string };
+  if (action === 'delete') {
+    await deleteRow(rowId);
+    return { success: true, message: '已删除' };
+  }
+  return { success: false, error: 'unknown action' };
+});
+
+// 展示 manifest 里的名称、版本等（握手后由宿主填充）
+const info = sdk.tool.getInfo();
+```
+
+### `sdk.events`
+
+**典型场景**：侧边 WebUI 要做「实时仪表盘」——主窗口里用户发了新消息、AI 流式输出、或其它工具执行完成时，你的面板要同步高亮或刷新。
+
+```ts
+const unsubUser = sdk.events.onUserMessage(({ message }) => {
+  appendActivityFeed(`用户：${message}`);
+});
+
+const unsubStream = sdk.events.on('streamingContent', ({ content, finished }) => {
+  setPartialReply(content);
+  if (finished) setLoading(false);
+});
+
+const unsubAi = sdk.events.onAiResponse((data) => {
+  setLastReply(data.content);
+});
+
+// 组件卸载时取消订阅，避免泄漏
+// unsubUser(); unsubStream(); unsubAi();
+```
+
+事件名还可选：`toolExecution`、`close` 等（与宿主实现一致）。
+
+### `sdk.ai`
+
+**典型场景**：在工具面板里提供「针对当前会话再问一句」按钮——走宿主已配置的模型与上下文，而不是在页面里单独接第三方 API；或拉取会话上下文做摘要展示。
+
+```ts
+const reply = await sdk.ai.chat('把上一条用户消息总结成三点', {
+  stream: false,
+});
+
+const ctx = await sdk.ai.getContext();
+if (ctx.name) setSessionTitle(ctx.name); // 部分字段视宿主实现而定
+
+// 流式由宿主推送；也可按需调用 chatStream（视宿主支持而定）
+await sdk.ai.chatStream('写一段简短回复', { stream: true });
+```
+
+### `sdk.ui`
+
+**典型场景**：危险操作要用**系统级确认框**；完成长任务后用**原生通知**；需要访问用户文件时用**宿主文件选择器**；操作结束后让主窗口**刷新消息列表或关闭 WebUI**。
+
+```ts
+await sdk.ui.showNotification('导出完成', 'success');
+
+const ok = await sdk.ui.showConfirm('删除记录', '此操作不可撤销，是否继续？');
+if (!ok) return;
+
+const path = await sdk.ui.pickFile({ type: 'image' });
+if (path) await uploadPreview(path);
+
+await sdk.ui.updateState({ refreshMessages: true });
+// await sdk.ui.openTab({ title: '详情', type: 'custom', data: { id: 'x' } });
+```
+
+### `sdk.storage`
+
+**典型场景**：记住用户在面板里的筛选条件、布局或草稿；数据存在**宿主侧**，可和 App 其它部分一致、也比仅 `localStorage` 更符合桌面端预期。
+
+```ts
+const KEY = 'my-app:filters';
+
+await sdk.storage.set(KEY, { projectId: 'p1', sort: 'date' });
+const filters = await sdk.storage.get<{ projectId: string; sort: string }>(KEY);
+await sdk.storage.delete(KEY);
+```
+
+### `sdk.tools` / `sdk.skills`
+
+**典型场景**：面板上的「一键流程」——按固定顺序调用**其它已安装工具**；或展示表单让用户填变量后执行**技能**（技能内部可编排多个工具）。敏感步骤可用 `executeWithConfirm` 让宿主先弹确认。
+
+```ts
+const tools = await sdk.tools.list();
+setToolPicker(tools.filter((t) => t.id !== sdk.tool.getInfo().id));
+
+const step1 = await sdk.tools.execute('fetch-doc', { url });
+if (!step1.success) throw new Error(step1.error);
+const step2 = await sdk.tools.execute('summarize', { text: step1.data });
+
+// 删除类等高风险：走宿主确认
+await sdk.tools.executeWithConfirm('delete-backup', { id: backupId });
+
+const skills = await sdk.skills.list();
+const skillResult = await sdk.skills.execute('weekly-report-skill', {
+  week: '2026-W13',
+  department: 'sales',
+});
+```
+
+## 架构
+
+```
+Your App (React/Vue/Vanilla)
+    │  import { ChatableX } from 'chatablex-web-sdk'
+    │
+    ▼
+┌─────────────────────────────────────┐
+│  chatablex-web-sdk（本包）            │
+│                                     │
+│  桥接层：                            │
+│    JS → Flutter: ChatableXBridge    │
+│    Flutter → JS: ChatableXReceive   │
+│                                     │
+│  模块：tool, events, ai, ui,        │
+│        storage, tools, skills       │
+└──────────────┬──────────────────────┘
+               │  WebView Bridge
+               ▼
+┌─────────────────────────────────────┐
+│  ChatableX Flutter 客户端            │
+│  （承载聊天 UI、SSE 流、Agent）       │
+└─────────────────────────────────────┘
+```
+
+## 许可证
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,280 @@
+/**
+ * ChatableX Web SDK — Type Definitions
+ */
+interface ChatOptions {
+    sessionId?: string;
+    context?: Record<string, unknown>;
+    tools?: string[];
+    skills?: string[];
+    stream?: boolean;
+}
+interface ChatResponse {
+    content: string;
+    sessionId: string;
+    messageId: string;
+    toolResults?: ToolResult[];
+    finished: boolean;
+    model?: string;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+interface SessionContext {
+    sessionId: string;
+    name: string;
+    messages: Message[];
+    activeTools: string[];
+    activeSkills: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+interface Message {
+    id: string;
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    content: string;
+    timestamp: string;
+    toolCalls?: ToolCall[];
+}
+interface ToolInfo {
+    id: string;
+    name: string;
+    version: string;
+    description: string;
+}
+interface ToolParameter {
+    name: string;
+    type: string;
+    description: string;
+    required: boolean;
+    default?: unknown;
+    enum?: string[];
+}
+interface ToolCall {
+    id: string;
+    toolId: string;
+    name: string;
+    params: Record<string, unknown>;
+    status: 'pending' | 'running' | 'success' | 'error' | 'cancelled';
+}
+interface ToolResult {
+    success: boolean;
+    data?: unknown;
+    error?: string;
+    toolId: string;
+    duration?: number;
+}
+type ToolExecuteHandler = (params: Record<string, unknown>) => Promise<Record<string, unknown>>;
+interface Skill {
+    id: string;
+    name: string;
+    description: string;
+    version: string;
+    author?: string;
+    category?: string;
+    toolIds: string[];
+    variables: SkillVariable[];
+    installed: boolean;
+}
+interface SkillVariable {
+    name: string;
+    type: string;
+    description: string;
+    required: boolean;
+    default?: unknown;
+}
+interface SkillResult {
+    success: boolean;
+    data?: unknown;
+    error?: string;
+    skillId: string;
+    toolResults?: ToolResult[];
+}
+type NotificationType = 'info' | 'success' | 'warning' | 'error';
+interface FilePickerOptions {
+    type?: 'any' | 'image' | 'video' | 'audio' | 'custom';
+    multiple?: boolean;
+    allowedExtensions?: string[];
+}
+interface TabConfig {
+    id: string;
+    title: string;
+    icon?: string;
+    type: 'chat' | 'tool' | 'skill' | 'custom';
+    data?: Record<string, unknown>;
+}
+interface StateUpdate {
+    refreshMessages?: boolean;
+    closeWebUI?: boolean;
+    [key: string]: unknown;
+}
+type EventType = 'aiResponse' | 'toolExecution' | 'userMessage' | 'streamingContent' | 'close';
+interface AiResponseEventData extends ChatResponse {
+}
+interface ToolExecutionEventData {
+    toolCall: ToolCall;
+    result?: ToolResult;
+}
+interface UserMessageEventData {
+    message: string;
+    timestamp: string;
+}
+interface StreamingContentEventData {
+    content: string;
+    finished?: boolean;
+}
+interface CloseEventData {
+    toolId: string;
+}
+interface EventCallbackMap {
+    aiResponse: (data: AiResponseEventData) => void;
+    toolExecution: (data: ToolExecutionEventData) => void;
+    userMessage: (data: UserMessageEventData) => void;
+    streamingContent: (data: StreamingContentEventData) => void;
+    close: (data: CloseEventData) => void;
+}
+type Unsubscribe = () => void;
+interface ChatableXInitConfig {
+    /** Your app / tool id (must match manifest.json id) */
+    appId: string;
+    /** SDK version override (default: SDK built-in version) */
+    version?: string;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+    /** Timeout in ms for the handshake with Flutter (default: 10000) */
+    timeout?: number;
+}
+interface ChatableXAI {
+    chat(message: string, options?: ChatOptions): Promise<ChatResponse>;
+    chatStream(message: string, options?: ChatOptions): Promise<unknown>;
+    getContext(): Promise<SessionContext>;
+}
+interface ChatableXTools {
+    list(): Promise<ToolInfo[]>;
+    execute(toolId: string, params: Record<string, unknown>): Promise<ToolResult>;
+    executeWithConfirm(toolId: string, params: Record<string, unknown>): Promise<ToolResult>;
+}
+interface ChatableXSkills {
+    list(): Promise<Skill[]>;
+    execute(skillId: string, variables: Record<string, unknown>): Promise<SkillResult>;
+}
+interface ChatableXUI {
+    showNotification(message: string, type?: NotificationType): Promise<void>;
+    showConfirm(title: string, message: string): Promise<boolean>;
+    pickFile(options?: FilePickerOptions): Promise<string | null>;
+    openTab(config: TabConfig): Promise<void>;
+    updateState(state: StateUpdate): Promise<void>;
+}
+interface ChatableXEvents {
+    on<T extends EventType>(eventType: T, callback: EventCallbackMap[T]): Unsubscribe;
+    onAiResponse(callback: EventCallbackMap['aiResponse']): Unsubscribe;
+    onToolExecution(callback: EventCallbackMap['toolExecution']): Unsubscribe;
+    onUserMessage(callback: EventCallbackMap['userMessage']): Unsubscribe;
+}
+interface ChatableXStorage {
+    get<T = unknown>(key: string): Promise<T | null>;
+    set<T = unknown>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+interface ChatableXToolModule {
+    getInfo(): ToolInfo;
+    onExecute(handler: ToolExecuteHandler): void;
+}
+interface ChatableXSDK {
+    ai: ChatableXAI;
+    tools: ChatableXTools;
+    skills: ChatableXSkills;
+    ui: ChatableXUI;
+    events: ChatableXEvents;
+    storage: ChatableXStorage;
+    tool: ChatableXToolModule;
+}
+declare global {
+    interface Window {
+        /** SDK instance — set after ChatableX.init() */
+        ChatableX?: ChatableXSDK;
+        /** Flutter → JS message receiver — set by SDK */
+        ChatableXReceive?: (jsonStr: string) => void;
+        /** Flutter's JavaScriptChannel (set by Flutter WebView) */
+        ChatableXBridge?: {
+            postMessage: (msg: string) => void;
+        };
+        /** Direct dispatch function for Flutter's executeInWebUI */
+        __CHATABLEX_DISPATCH__?: (params: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    }
+}
+
+/**
+ * Low-level WebView bridge between the Web SDK and the Flutter host.
+ *
+ * Communication:
+ *   JS → Flutter : window.ChatableXBridge.postMessage(JSON.stringify(msg))
+ *   Flutter → JS : controller.runJavaScript("window.ChatableXReceive('...')")
+ */
+type EventHandler = (data: unknown) => void;
+declare class Bridge {
+    private _msgId;
+    private _pending;
+    private _listeners;
+    private _debug;
+    constructor(debug?: boolean);
+    /** Install the global ChatableXReceive handler so Flutter can push data in. */
+    install(): void;
+    /** Wait for ChatableXBridge (set by Flutter) to become available. */
+    waitForBridge(timeoutMs: number): Promise<void>;
+    /** Send a request to Flutter and wait for a response. */
+    sendMessage(method: string, params?: Record<string, unknown>, requestTimeoutMs?: number): Promise<unknown>;
+    private _handleResponse;
+    private _handleEvent;
+    addEventListener(eventType: string, handler: EventHandler): () => void;
+    /** Dispatch a synthetic event (used internally). */
+    dispatchEvent(eventType: string, data: unknown): void;
+    private _nextId;
+    private _log;
+    destroy(): void;
+}
+
+/**
+ * chatablex-web-sdk
+ *
+ * Runtime SDK for ChatableX AI App (WebUI) development.
+ * Developers install this package and call `ChatableX.init()` to connect
+ * their web app to the ChatableX Flutter host.
+ *
+ * @example
+ * ```ts
+ * import { ChatableX } from 'chatablex-web-sdk';
+ *
+ * const sdk = await ChatableX.init({ appId: 'counter-app' });
+ *
+ * sdk.tool.onExecute(async (params) => {
+ *   // handle LLM-driven tool calls
+ *   return { success: true, data: 'done' };
+ * });
+ * ```
+ */
+
+declare const SDK_VERSION = "1.0.0";
+/**
+ * Main entry point. Provides `ChatableX.init()` to bootstrap the SDK.
+ */
+declare const ChatableX: {
+    /**
+     * Initialize the SDK and establish the bridge with the Flutter host.
+     *
+     * 1. Sets up `window.ChatableXReceive` (Flutter → JS message handler).
+     * 2. Waits for `window.ChatableXBridge` (Flutter's JavaScriptChannel).
+     * 3. Sends `sdk_init` handshake and receives tool config from Flutter.
+     * 4. Returns the fully-initialised SDK instance.
+     */
+    init(config: ChatableXInitConfig): Promise<ChatableXSDK>;
+    /** Get the current SDK instance (throws if not initialised). */
+    getInstance(): ChatableXSDK;
+    /** Check whether the SDK has been initialised. */
+    isReady(): boolean;
+    /** SDK version */
+    version: string;
+};
+
+export { type AiResponseEventData, Bridge, type ChatOptions, type ChatResponse, ChatableX, type ChatableXAI, type ChatableXEvents, type ChatableXInitConfig, type ChatableXSDK, type ChatableXSkills, type ChatableXStorage, type ChatableXToolModule, type ChatableXTools, type ChatableXUI, type CloseEventData, type EventCallbackMap, type EventType, type FilePickerOptions, type Message, type NotificationType, SDK_VERSION, type SessionContext, type Skill, type SkillResult, type SkillVariable, type StateUpdate, type StreamingContentEventData, type TabConfig, type ToolCall, type ToolExecuteHandler, type ToolExecutionEventData, type ToolInfo, type ToolParameter, type ToolResult, type Unsubscribe, type UserMessageEventData };