chatablex-web-sdk 1.0.0

package/dist/index.d.ts

@@ -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 };

package/dist/index.js

@@ -0,0 +1,366 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Bridge: () => Bridge,
+  ChatableX: () => ChatableX,
+  SDK_VERSION: () => SDK_VERSION
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/bridge.ts
+var Bridge = class {
+  constructor(debug = false) {
+    this._msgId = 0;
+    this._pending = /* @__PURE__ */ new Map();
+    this._listeners = /* @__PURE__ */ new Map();
+    this._debug = debug;
+  }
+  // -------------------------------------------------------------------------
+  // Lifecycle
+  // -------------------------------------------------------------------------
+  /** Install the global ChatableXReceive handler so Flutter can push data in. */
+  install() {
+    window.ChatableXReceive = (jsonStr) => {
+      try {
+        const data = JSON.parse(jsonStr);
+        if (data.type === "response") {
+          this._handleResponse(data);
+        } else if (data.type === "event") {
+          this._handleEvent(data);
+        }
+      } catch (e) {
+        console.error("[ChatableX Bridge] receive parse error:", e);
+      }
+    };
+    this._log("ChatableXReceive installed");
+  }
+  /** Wait for ChatableXBridge (set by Flutter) to become available. */
+  waitForBridge(timeoutMs) {
+    return new Promise((resolve, reject) => {
+      if (window.ChatableXBridge) {
+        resolve();
+        return;
+      }
+      const start = Date.now();
+      const check = setInterval(() => {
+        if (window.ChatableXBridge) {
+          clearInterval(check);
+          resolve();
+        } else if (Date.now() - start > timeoutMs) {
+          clearInterval(check);
+          reject(new Error(`ChatableXBridge not available after ${timeoutMs}ms`));
+        }
+      }, 50);
+    });
+  }
+  // -------------------------------------------------------------------------
+  // Request / Response
+  // -------------------------------------------------------------------------
+  /** Send a request to Flutter and wait for a response. */
+  sendMessage(method, params = {}, requestTimeoutMs = 3e4) {
+    return new Promise((resolve, reject) => {
+      const id = this._nextId();
+      const message = { id, method, params, timestamp: Date.now() };
+      const timer = setTimeout(() => {
+        if (this._pending.has(id)) {
+          this._pending.delete(id);
+          reject(new Error(`Request timeout: ${method}`));
+        }
+      }, requestTimeoutMs);
+      this._pending.set(id, { resolve, reject, timer });
+      if (window.ChatableXBridge) {
+        window.ChatableXBridge.postMessage(JSON.stringify(message));
+      } else {
+        clearTimeout(timer);
+        this._pending.delete(id);
+        reject(new Error("ChatableXBridge not available"));
+      }
+    });
+  }
+  _handleResponse(data) {
+    const pending = this._pending.get(data.id);
+    if (!pending) return;
+    this._pending.delete(data.id);
+    clearTimeout(pending.timer);
+    if (data.success) {
+      pending.resolve(data.data);
+    } else {
+      pending.reject(new Error(data.error ?? "Unknown error"));
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Events
+  // -------------------------------------------------------------------------
+  _handleEvent(data) {
+    const handlers = this._listeners.get(data.eventType);
+    if (handlers) {
+      for (const fn of handlers) {
+        try {
+          fn(data.data);
+        } catch (e) {
+          console.error("[ChatableX] event handler error:", e);
+        }
+      }
+    }
+  }
+  addEventListener(eventType, handler) {
+    if (!this._listeners.has(eventType)) {
+      this._listeners.set(eventType, /* @__PURE__ */ new Set());
+    }
+    this._listeners.get(eventType).add(handler);
+    return () => {
+      const set = this._listeners.get(eventType);
+      if (set) {
+        set.delete(handler);
+        if (set.size === 0) this._listeners.delete(eventType);
+      }
+    };
+  }
+  /** Dispatch a synthetic event (used internally). */
+  dispatchEvent(eventType, data) {
+    this._handleEvent({ eventType, data });
+  }
+  // -------------------------------------------------------------------------
+  // Internals
+  // -------------------------------------------------------------------------
+  _nextId() {
+    return `ctx_${++this._msgId}_${Date.now()}`;
+  }
+  _log(...args) {
+    if (this._debug) console.log("[ChatableX Bridge]", ...args);
+  }
+  destroy() {
+    for (const [, p] of this._pending) {
+      clearTimeout(p.timer);
+      p.reject(new Error("Bridge destroyed"));
+    }
+    this._pending.clear();
+    this._listeners.clear();
+    window.ChatableXReceive = void 0;
+  }
+};
+
+// src/modules/tool.ts
+function createToolModule(bridge, appId) {
+  let _info = { id: appId, name: appId, version: "1.0.0", description: "" };
+  let _handler = null;
+  const dispatch = async (params) => {
+    if (!_handler) {
+      return { success: false, error: "No execute handler registered" };
+    }
+    try {
+      return await _handler(params);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      return { success: false, error: msg };
+    }
+  };
+  window.__CHATABLEX_DISPATCH__ = dispatch;
+  bridge.addEventListener("toolExecution", async (data) => {
+    const params = data;
+    const requestId = params._requestId;
+    const result = await dispatch(params);
+    if (requestId && window.ChatableXBridge) {
+      window.ChatableXBridge.postMessage(JSON.stringify({
+        method: "tool.executeResult",
+        params: { _requestId: requestId, ...result }
+      }));
+    }
+  });
+  return {
+    getInfo() {
+      return { ..._info };
+    },
+    onExecute(handler) {
+      _handler = handler;
+    },
+    /** @internal — called by SDK after handshake to fill in tool metadata */
+    _setInfo(info) {
+      _info = { ..._info, ...info };
+    }
+  };
+}
+
+// src/modules/events.ts
+function createEventsModule(bridge) {
+  return {
+    on(eventType, callback) {
+      bridge.sendMessage("events.subscribe", { eventType }).catch(() => {
+      });
+      return bridge.addEventListener(eventType, callback);
+    },
+    onAiResponse(callback) {
+      return this.on("aiResponse", callback);
+    },
+    onToolExecution(callback) {
+      return this.on("toolExecution", callback);
+    },
+    onUserMessage(callback) {
+      return this.on("userMessage", callback);
+    }
+  };
+}
+
+// src/modules/ai.ts
+function createAIModule(bridge) {
+  return {
+    chat(message, options) {
+      return bridge.sendMessage("ai.chat", { message, ...options });
+    },
+    chatStream(message, options) {
+      return bridge.sendMessage("ai.chatStream", { message, ...options });
+    },
+    getContext() {
+      return bridge.sendMessage("ai.getContext", {});
+    }
+  };
+}
+
+// src/modules/ui.ts
+function createUIModule(bridge) {
+  return {
+    showNotification(message, type = "info") {
+      return bridge.sendMessage("ui.showNotification", { message, type });
+    },
+    showConfirm(title, message) {
+      return bridge.sendMessage("ui.showConfirm", { title, message });
+    },
+    pickFile(options) {
+      return bridge.sendMessage("ui.pickFile", options ?? {});
+    },
+    openTab(config) {
+      return bridge.sendMessage("ui.openTab", config);
+    },
+    updateState(state) {
+      return bridge.sendMessage("ui.updateState", state);
+    }
+  };
+}
+
+// src/modules/storage.ts
+function createStorageModule(bridge) {
+  return {
+    get(key) {
+      return bridge.sendMessage("storage.get", { key });
+    },
+    set(key, value) {
+      return bridge.sendMessage("storage.set", { key, value });
+    },
+    delete(key) {
+      return bridge.sendMessage("storage.delete", { key });
+    }
+  };
+}
+
+// src/modules/tools.ts
+function createToolsModule(bridge) {
+  return {
+    list() {
+      return bridge.sendMessage("tools.list", {});
+    },
+    execute(toolId, params) {
+      return bridge.sendMessage("tools.execute", { toolId, params });
+    },
+    executeWithConfirm(toolId, params) {
+      return bridge.sendMessage("tools.executeWithConfirm", { toolId, params });
+    }
+  };
+}
+
+// src/modules/skills.ts
+function createSkillsModule(bridge) {
+  return {
+    list() {
+      return bridge.sendMessage("skills.list", {});
+    },
+    execute(skillId, variables) {
+      return bridge.sendMessage("skills.execute", { skillId, variables });
+    }
+  };
+}
+
+// src/index.ts
+var SDK_VERSION = "1.0.0";
+var _instance = null;
+var 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.
+   */
+  async init(config) {
+    if (_instance) return _instance;
+    const debug = config.debug ?? false;
+    const timeout = config.timeout ?? 1e4;
+    const bridge = new Bridge(debug);
+    bridge.install();
+    await bridge.waitForBridge(timeout);
+    if (debug) console.log("[ChatableX] Bridge connected, sending sdk_init");
+    let toolConfig = {};
+    try {
+      const resp = await bridge.sendMessage("sdk_init", {
+        appId: config.appId,
+        sdkVersion: SDK_VERSION
+      });
+      if (resp && typeof resp === "object") {
+        toolConfig = resp;
+      }
+    } catch {
+      if (debug) console.warn("[ChatableX] sdk_init handshake failed, continuing with defaults");
+    }
+    const toolModule = createToolModule(bridge, config.appId);
+    if (toolConfig) toolModule._setInfo(toolConfig);
+    const sdk = {
+      ai: createAIModule(bridge),
+      tools: createToolsModule(bridge),
+      skills: createSkillsModule(bridge),
+      ui: createUIModule(bridge),
+      events: createEventsModule(bridge),
+      storage: createStorageModule(bridge),
+      tool: toolModule
+    };
+    window.ChatableX = sdk;
+    _instance = sdk;
+    if (debug) console.log(`[ChatableX] SDK v${SDK_VERSION} ready for: ${config.appId}`);
+    return sdk;
+  },
+  /** Get the current SDK instance (throws if not initialised). */
+  getInstance() {
+    if (!_instance) throw new Error("ChatableX SDK not initialised. Call ChatableX.init() first.");
+    return _instance;
+  },
+  /** Check whether the SDK has been initialised. */
+  isReady() {
+    return _instance !== null;
+  },
+  /** SDK version */
+  version: SDK_VERSION
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Bridge,
+  ChatableX,
+  SDK_VERSION
+});