chatablex-web-sdk 1.0.0

package/src/modules/skills.ts

@@ -0,0 +1,14 @@
+import type { Bridge } from '../bridge';
+import type { Skill, SkillResult, ChatableXSkills } from '../types';
+
+export function createSkillsModule(bridge: Bridge): ChatableXSkills {
+  return {
+    list(): Promise<Skill[]> {
+      return bridge.sendMessage('skills.list', {}) as Promise<Skill[]>;
+    },
+
+    execute(skillId: string, variables: Record<string, unknown>): Promise<SkillResult> {
+      return bridge.sendMessage('skills.execute', { skillId, variables }) as Promise<SkillResult>;
+    },
+  };
+}

package/src/modules/storage.ts

@@ -0,0 +1,18 @@
+import type { Bridge } from '../bridge';
+import type { ChatableXStorage } from '../types';
+
+export function createStorageModule(bridge: Bridge): ChatableXStorage {
+  return {
+    get<T = unknown>(key: string): Promise<T | null> {
+      return bridge.sendMessage('storage.get', { key }) as Promise<T | null>;
+    },
+
+    set<T = unknown>(key: string, value: T): Promise<void> {
+      return bridge.sendMessage('storage.set', { key, value: value as unknown }) as Promise<void>;
+    },
+
+    delete(key: string): Promise<void> {
+      return bridge.sendMessage('storage.delete', { key }) as Promise<void>;
+    },
+  };
+}

package/src/modules/tool.ts

@@ -0,0 +1,54 @@
+import type { Bridge } from '../bridge';
+import type { ToolInfo, ToolExecuteHandler, ChatableXToolModule } from '../types';
+
+/**
+ * Creates the `sdk.tool` module — the primary interface for LLM-driven
+ * tool execution in a ChatableX WebUI app.
+ */
+export function createToolModule(bridge: Bridge, appId: string): ChatableXToolModule & { _setInfo(info: Partial<ToolInfo>): void } {
+  let _info: ToolInfo = { id: appId, name: appId, version: '1.0.0', description: '' };
+  let _handler: ToolExecuteHandler | null = null;
+
+  const dispatch = async (params: Record<string, unknown>): Promise<Record<string, unknown>> => {
+    if (!_handler) {
+      return { success: false, error: 'No execute handler registered' };
+    }
+    try {
+      return await _handler(params);
+    } catch (e: unknown) {
+      const msg = e instanceof Error ? e.message : String(e);
+      return { success: false, error: msg };
+    }
+  };
+
+  // Expose globally so Flutter can call it via runJavaScriptReturningResult
+  window.__CHATABLEX_DISPATCH__ = dispatch;
+
+  // Listen for toolExecution events pushed from Flutter.
+  // If the event carries a _requestId, send the result back via the bridge
+  // so Flutter can resolve its pending Completer.
+  bridge.addEventListener('toolExecution', async (data) => {
+    const params = data as Record<string, unknown>;
+    const requestId = params._requestId as string | undefined;
+    const result = await dispatch(params);
+    if (requestId && window.ChatableXBridge) {
+      window.ChatableXBridge.postMessage(JSON.stringify({
+        method: 'tool.executeResult',
+        params: { _requestId: requestId, ...result },
+      }));
+    }
+  });
+
+  return {
+    getInfo(): ToolInfo {
+      return { ..._info };
+    },
+    onExecute(handler: ToolExecuteHandler): void {
+      _handler = handler;
+    },
+    /** @internal — called by SDK after handshake to fill in tool metadata */
+    _setInfo(info: Partial<ToolInfo>): void {
+      _info = { ..._info, ...info };
+    },
+  };
+}

package/src/modules/tools.ts

@@ -0,0 +1,18 @@
+import type { Bridge } from '../bridge';
+import type { ToolInfo, ToolResult, ChatableXTools } from '../types';
+
+export function createToolsModule(bridge: Bridge): ChatableXTools {
+  return {
+    list(): Promise<ToolInfo[]> {
+      return bridge.sendMessage('tools.list', {}) as Promise<ToolInfo[]>;
+    },
+
+    execute(toolId: string, params: Record<string, unknown>): Promise<ToolResult> {
+      return bridge.sendMessage('tools.execute', { toolId, params }) as Promise<ToolResult>;
+    },
+
+    executeWithConfirm(toolId: string, params: Record<string, unknown>): Promise<ToolResult> {
+      return bridge.sendMessage('tools.executeWithConfirm', { toolId, params }) as Promise<ToolResult>;
+    },
+  };
+}

package/src/modules/ui.ts

@@ -0,0 +1,26 @@
+import type { Bridge } from '../bridge';
+import type { NotificationType, FilePickerOptions, TabConfig, StateUpdate, ChatableXUI } from '../types';
+
+export function createUIModule(bridge: Bridge): ChatableXUI {
+  return {
+    showNotification(message: string, type: NotificationType = 'info'): Promise<void> {
+      return bridge.sendMessage('ui.showNotification', { message, type }) as Promise<void>;
+    },
+
+    showConfirm(title: string, message: string): Promise<boolean> {
+      return bridge.sendMessage('ui.showConfirm', { title, message }) as Promise<boolean>;
+    },
+
+    pickFile(options?: FilePickerOptions): Promise<string | null> {
+      return bridge.sendMessage('ui.pickFile', options ?? {}) as Promise<string | null>;
+    },
+
+    openTab(config: TabConfig): Promise<void> {
+      return bridge.sendMessage('ui.openTab', config as unknown as Record<string, unknown>) as Promise<void>;
+    },
+
+    updateState(state: StateUpdate): Promise<void> {
+      return bridge.sendMessage('ui.updateState', state as Record<string, unknown>) as Promise<void>;
+    },
+  };
+}

package/src/types.ts

@@ -0,0 +1,270 @@
+/**
+ * ChatableX Web SDK — Type Definitions
+ */
+
+// ---------------------------------------------------------------------------
+// Chat / AI
+// ---------------------------------------------------------------------------
+
+export interface ChatOptions {
+  sessionId?: string;
+  context?: Record<string, unknown>;
+  tools?: string[];
+  skills?: string[];
+  stream?: boolean;
+}
+
+export interface ChatResponse {
+  content: string;
+  sessionId: string;
+  messageId: string;
+  toolResults?: ToolResult[];
+  finished: boolean;
+  model?: string;
+  usage?: { promptTokens: number; completionTokens: number; totalTokens: number };
+}
+
+export interface SessionContext {
+  sessionId: string;
+  name: string;
+  messages: Message[];
+  activeTools: string[];
+  activeSkills: string[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface Message {
+  id: string;
+  role: 'user' | 'assistant' | 'system' | 'tool';
+  content: string;
+  timestamp: string;
+  toolCalls?: ToolCall[];
+}
+
+// ---------------------------------------------------------------------------
+// Tool
+// ---------------------------------------------------------------------------
+
+export interface ToolInfo {
+  id: string;
+  name: string;
+  version: string;
+  description: string;
+}
+
+export interface ToolParameter {
+  name: string;
+  type: string;
+  description: string;
+  required: boolean;
+  default?: unknown;
+  enum?: string[];
+}
+
+export interface ToolCall {
+  id: string;
+  toolId: string;
+  name: string;
+  params: Record<string, unknown>;
+  status: 'pending' | 'running' | 'success' | 'error' | 'cancelled';
+}
+
+export interface ToolResult {
+  success: boolean;
+  data?: unknown;
+  error?: string;
+  toolId: string;
+  duration?: number;
+}
+
+export type ToolExecuteHandler = (params: Record<string, unknown>) => Promise<Record<string, unknown>>;
+
+// ---------------------------------------------------------------------------
+// Skill
+// ---------------------------------------------------------------------------
+
+export interface Skill {
+  id: string;
+  name: string;
+  description: string;
+  version: string;
+  author?: string;
+  category?: string;
+  toolIds: string[];
+  variables: SkillVariable[];
+  installed: boolean;
+}
+
+export interface SkillVariable {
+  name: string;
+  type: string;
+  description: string;
+  required: boolean;
+  default?: unknown;
+}
+
+export interface SkillResult {
+  success: boolean;
+  data?: unknown;
+  error?: string;
+  skillId: string;
+  toolResults?: ToolResult[];
+}
+
+// ---------------------------------------------------------------------------
+// UI
+// ---------------------------------------------------------------------------
+
+export type NotificationType = 'info' | 'success' | 'warning' | 'error';
+
+export interface FilePickerOptions {
+  type?: 'any' | 'image' | 'video' | 'audio' | 'custom';
+  multiple?: boolean;
+  allowedExtensions?: string[];
+}
+
+export interface TabConfig {
+  id: string;
+  title: string;
+  icon?: string;
+  type: 'chat' | 'tool' | 'skill' | 'custom';
+  data?: Record<string, unknown>;
+}
+
+export interface StateUpdate {
+  refreshMessages?: boolean;
+  closeWebUI?: boolean;
+  [key: string]: unknown;
+}
+
+// ---------------------------------------------------------------------------
+// Events
+// ---------------------------------------------------------------------------
+
+export type EventType =
+  | 'aiResponse'
+  | 'toolExecution'
+  | 'userMessage'
+  | 'streamingContent'
+  | 'close';
+
+export interface AiResponseEventData extends ChatResponse {}
+
+export interface ToolExecutionEventData {
+  toolCall: ToolCall;
+  result?: ToolResult;
+}
+
+export interface UserMessageEventData {
+  message: string;
+  timestamp: string;
+}
+
+export interface StreamingContentEventData {
+  content: string;
+  finished?: boolean;
+}
+
+export interface CloseEventData {
+  toolId: string;
+}
+
+export interface EventCallbackMap {
+  aiResponse: (data: AiResponseEventData) => void;
+  toolExecution: (data: ToolExecutionEventData) => void;
+  userMessage: (data: UserMessageEventData) => void;
+  streamingContent: (data: StreamingContentEventData) => void;
+  close: (data: CloseEventData) => void;
+}
+
+export type Unsubscribe = () => void;
+
+// ---------------------------------------------------------------------------
+// Init Config
+// ---------------------------------------------------------------------------
+
+export 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;
+}
+
+// ---------------------------------------------------------------------------
+// SDK Module Interfaces
+// ---------------------------------------------------------------------------
+
+export interface ChatableXAI {
+  chat(message: string, options?: ChatOptions): Promise<ChatResponse>;
+  chatStream(message: string, options?: ChatOptions): Promise<unknown>;
+  getContext(): Promise<SessionContext>;
+}
+
+export interface ChatableXTools {
+  list(): Promise<ToolInfo[]>;
+  execute(toolId: string, params: Record<string, unknown>): Promise<ToolResult>;
+  executeWithConfirm(toolId: string, params: Record<string, unknown>): Promise<ToolResult>;
+}
+
+export interface ChatableXSkills {
+  list(): Promise<Skill[]>;
+  execute(skillId: string, variables: Record<string, unknown>): Promise<SkillResult>;
+}
+
+export 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>;
+}
+
+export 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;
+}
+
+export interface ChatableXStorage {
+  get<T = unknown>(key: string): Promise<T | null>;
+  set<T = unknown>(key: string, value: T): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+
+export interface ChatableXToolModule {
+  getInfo(): ToolInfo;
+  onExecute(handler: ToolExecuteHandler): void;
+}
+
+export interface ChatableXSDK {
+  ai: ChatableXAI;
+  tools: ChatableXTools;
+  skills: ChatableXSkills;
+  ui: ChatableXUI;
+  events: ChatableXEvents;
+  storage: ChatableXStorage;
+  tool: ChatableXToolModule;
+}
+
+// ---------------------------------------------------------------------------
+// Global Window Augmentation
+// ---------------------------------------------------------------------------
+
+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>>;
+  }
+}