@yushaw/sanqian-sdk 0.2.10 → 0.2.12

package/dist/index.browser.d.mts

@@ -0,0 +1,445 @@
+/**
+ * Sanqian SDK Type Definitions
+ */
+interface SDKConfig {
+    /** Unique app identifier (e.g., "sanqian-todolist") */
+    appName: string;
+    /** App version string */
+    appVersion: string;
+    /** Display name shown in Sanqian UI */
+    displayName?: string;
+    /** Command to launch this app (for auto-start) */
+    launchCommand?: string;
+    /** Tools provided by this app */
+    tools: ToolDefinition[];
+    /** Reconnect interval in ms (default: 5000) */
+    reconnectInterval?: number;
+    /** Heartbeat interval in ms (default: 30000) */
+    heartbeatInterval?: number;
+    /** Tool execution timeout in ms (default: 30000) */
+    toolExecutionTimeout?: number;
+    /**
+     * Auto-launch Sanqian if not running (default: false)
+     * When enabled, SDK will try to start Sanqian in hidden/tray mode
+     */
+    autoLaunchSanqian?: boolean;
+    /**
+     * Custom path to Sanqian executable (optional)
+     * If not provided, SDK will search in standard installation locations
+     */
+    sanqianPath?: string;
+    /**
+     * Enable debug logging (default: false)
+     * When enabled, SDK will output detailed logs to console
+     */
+    debug?: boolean;
+    /**
+     * Pre-configured connection info (for browser environments)
+     * When provided, SDK skips file-based discovery and connects directly.
+     * This is useful for browser extensions that discover Sanqian via other means
+     * (e.g., native messaging or HTTP API).
+     */
+    connectionInfo?: ConnectionInfo;
+}
+interface ToolDefinition {
+    /** Tool name (without app prefix) */
+    name: string;
+    /** Tool description for LLM */
+    description: string;
+    /** JSON Schema for parameters */
+    parameters: JSONSchema;
+    /** Handler function */
+    handler: (args: any) => Promise<any>;
+    /**
+     * Whether this tool can be discovered via search_capability (default: true)
+     * Set to false for internal tools that should be available but not searchable
+     */
+    searchable?: boolean;
+}
+interface JSONSchema {
+    type: "object" | "array" | "string" | "number" | "boolean";
+    properties?: Record<string, JSONSchemaProperty>;
+    required?: string[];
+    items?: JSONSchemaProperty;
+    description?: string;
+}
+interface JSONSchemaProperty {
+    type: "string" | "number" | "boolean" | "array" | "object";
+    description?: string;
+    enum?: (string | number)[];
+    default?: unknown;
+    items?: JSONSchemaProperty;
+    properties?: Record<string, JSONSchemaProperty>;
+    required?: string[];
+    format?: string;
+}
+interface ConnectionInfo {
+    version: number;
+    port: number;
+    ws_path: string;
+    token: string;
+    pid: number;
+    started_at: string;
+    /** Path to Sanqian executable (for SDK auto-launch) */
+    executable?: string;
+}
+interface ConnectionState {
+    connected: boolean;
+    registering: boolean;
+    registered: boolean;
+    lastError?: Error;
+    reconnectAttempts: number;
+}
+/** Remote tool definition for dynamic tool injection */
+interface RemoteToolDefinition {
+    /** Tool name */
+    name: string;
+    /** Tool description for LLM */
+    description: string;
+    /** JSON Schema for parameters */
+    parameters: JSONSchema;
+}
+interface ChatRequest {
+    /** Agent ID (can be short name, SDK auto-adds app prefix) */
+    agentId: string;
+    /** Messages to send */
+    messages: ChatMessage[];
+    /** Conversation ID for stateful mode (server stores messages) */
+    conversationId?: string;
+    /** Enable streaming (default: true) */
+    stream?: boolean;
+    /** Dynamic tools to inject at call time */
+    remoteTools?: RemoteToolDefinition[];
+}
+interface ChatMessage {
+    role: "user" | "assistant" | "system" | "tool";
+    content: string;
+    tool_calls?: ToolCall[];
+    tool_call_id?: string;
+}
+interface ToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+interface ChatResponse {
+    message: ChatMessage;
+    conversationId: string;
+    /** Conversation title (truncated from first user message, or LLM-generated after 3rd round) */
+    title?: string;
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+}
+interface ChatStreamEvent {
+    type: "text" | "thinking" | "tool_call" | "tool_result" | "done" | "error";
+    /** Text content (for "text" and "thinking" events) */
+    content?: string;
+    /** Tool call info (for "tool_call" event) */
+    tool_call?: ToolCall;
+    /** Tool call ID (for "tool_result" event) */
+    tool_call_id?: string;
+    /** Tool execution result (for "tool_result" event) */
+    result?: unknown;
+    /** Whether tool execution succeeded (for "tool_result" event) */
+    success?: boolean;
+    /** Conversation ID (for "done" event) */
+    conversationId?: string;
+    /** Conversation title (for "done" event) */
+    title?: string;
+    /** Error message (for "error" event or failed "tool_result") */
+    error?: string;
+}
+/** Agent configuration for create/update */
+interface AgentConfig {
+    /** Unique agent ID within this app (e.g., "assistant") */
+    agent_id: string;
+    /** Display name */
+    name: string;
+    /** Description */
+    description?: string;
+    /** System prompt */
+    system_prompt?: string;
+    /** Tool names from this app to enable (without prefix) */
+    tools?: string[];
+    /**
+     * Sub-agents this agent can call via task tool.
+     * - undefined/null: Cannot use task tool (default)
+     * - []: Cannot use task tool (explicit)
+     * - ["*"]: Can call all available agents
+     * - ["agent1", "agent2"]: Can only call specified agents
+     */
+    subagents?: string[];
+    /**
+     * Whether this agent can be discovered via search_capability (default: true)
+     * Set to false if you want the agent to be usable but not discoverable by other agents
+     */
+    searchable?: boolean;
+}
+/** Agent info returned from list */
+interface AgentInfo {
+    /** Full agent ID (app_name:agent_id) */
+    agent_id: string;
+    name: string;
+    description?: string;
+    /** Tool names with sdk_ prefix */
+    tools: string[];
+    /** Sub-agents this agent can call via task tool */
+    subagents?: string[] | null;
+    /** Whether this agent can be discovered via search_capability */
+    searchable?: boolean;
+    created_at?: string;
+}
+/** Conversation info */
+interface ConversationInfo {
+    conversation_id: string;
+    agent_id: string;
+    title?: string;
+    message_count: number;
+    created_at?: string;
+    updated_at?: string;
+}
+/** Message in a conversation */
+interface ConversationMessage {
+    id: string;
+    role: "user" | "assistant" | "system" | "tool";
+    content: string;
+    tool_calls?: ToolCall[] | null;
+    tool_call_id?: string | null;
+    created_at?: string;
+}
+/** Full conversation with messages */
+interface ConversationDetail extends ConversationInfo {
+    messages?: ConversationMessage[];
+}
+/** Agent update configuration (all fields optional except agent_id) */
+interface AgentUpdateConfig {
+    /** Agent ID to update */
+    agent_id: string;
+    /** New display name */
+    name?: string;
+    /** New description */
+    description?: string;
+    /** New system prompt */
+    system_prompt?: string;
+    /** New tool names from this app to enable (without prefix) */
+    tools?: string[];
+    /**
+     * Sub-agents this agent can call via task tool.
+     * - undefined: Keep existing value
+     * - null/[]: Cannot use task tool
+     * - ["*"]: Can call all available agents
+     * - ["agent1", "agent2"]: Can only call specified agents
+     */
+    subagents?: string[] | null;
+    /**
+     * Whether this agent can be discovered via search_capability
+     * - undefined: Keep existing value
+     * - true/false: Set explicitly
+     */
+    searchable?: boolean;
+}
+interface SDKEvents {
+    connected: () => void;
+    disconnected: (reason: string) => void;
+    registered: () => void;
+    error: (error: Error) => void;
+    tool_call: (call: {
+        name: string;
+        arguments: Record<string, unknown>;
+    }) => void;
+}
+type SDKEventName = keyof SDKEvents;
+
+/**
+ * Sanqian SDK Client - Browser Build
+ *
+ * This is a browser-optimized version of the SDK client that does NOT include
+ * DiscoveryManager or any Node.js APIs (fs, path, child_process, os).
+ *
+ * IMPORTANT: When using this build, you MUST provide connectionInfo in config.
+ * Auto-discovery and auto-launch features are not available in browser environments.
+ *
+ * TODO: Consider refactoring to share code with client.ts using composition or
+ * inheritance pattern to reduce duplication (~900 lines shared). Currently kept
+ * separate for simplicity and to avoid complex build configurations.
+ * See: https://github.com/anthropics/claude-code/issues/xxx (if tracked)
+ */
+
+declare class SanqianSDK {
+    private config;
+    private ws;
+    private connectionInfo;
+    private state;
+    private toolHandlers;
+    private pendingRequests;
+    private heartbeatTimer;
+    private reconnectTimer;
+    private heartbeatAckPending;
+    private missedHeartbeats;
+    private static readonly MAX_MISSED_HEARTBEATS;
+    private connectingPromise;
+    private reconnectRefCount;
+    private eventListeners;
+    private log;
+    private warn;
+    constructor(config: SDKConfig);
+    /**
+     * Build WebSocket URL from connection info
+     */
+    private buildWebSocketUrl;
+    connect(): Promise<void>;
+    private connectWithInfo;
+    disconnect(): Promise<void>;
+    private register;
+    private handleMessage;
+    private handleChatStream;
+    private handleToolCall;
+    private sendToolResult;
+    private handleDisconnect;
+    private shouldAutoReconnect;
+    acquireReconnect(): void;
+    releaseReconnect(): void;
+    private scheduleReconnect;
+    private stopReconnect;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private send;
+    private sendAndWait;
+    getState(): ConnectionState;
+    isConnected(): boolean;
+    ensureReady(): Promise<void>;
+    private doFullConnect;
+    updateTools(tools: ToolDefinition[]): Promise<void>;
+    createAgent(config: AgentConfig): Promise<AgentInfo>;
+    listAgents(): Promise<AgentInfo[]>;
+    deleteAgent(agentId: string): Promise<void>;
+    updateAgent(agentId: string, updates: Omit<AgentUpdateConfig, "agent_id">): Promise<AgentInfo>;
+    listConversations(options?: {
+        agentId?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        conversations: ConversationInfo[];
+        total: number;
+    }>;
+    getConversation(conversationId: string, options?: {
+        includeMessages?: boolean;
+        messageLimit?: number;
+        messageOffset?: number;
+    }): Promise<ConversationDetail>;
+    deleteConversation(conversationId: string): Promise<void>;
+    private streamHandlers;
+    chat(agentId: string, messages: ChatMessage[], options?: {
+        conversationId?: string;
+        remoteTools?: RemoteToolDefinition[];
+    }): Promise<ChatResponse>;
+    chatStream(agentId: string, messages: ChatMessage[], options?: {
+        conversationId?: string;
+        remoteTools?: RemoteToolDefinition[];
+    }): AsyncGenerator<ChatStreamEvent>;
+    startConversation(agentId: string): Conversation;
+    on<T extends SDKEventName>(event: T, listener: SDKEvents[T]): this;
+    off<T extends SDKEventName>(event: T, listener: SDKEvents[T]): this;
+    once<T extends SDKEventName>(event: T, listener: SDKEvents[T]): this;
+    /**
+     * Remove all event listeners
+     *
+     * Call this to prevent memory leaks when disposing the SDK instance.
+     * If event is specified, only removes listeners for that event.
+     */
+    removeAllListeners(event?: SDKEventName): this;
+    private emit;
+    private generateId;
+    private createTimeout;
+}
+/**
+ * Conversation helper for multi-turn chat
+ */
+declare class Conversation {
+    private sdk;
+    private agentId;
+    private _conversationId;
+    constructor(sdk: SanqianSDK, agentId: string, conversationId?: string);
+    get id(): string | null;
+    send(content: string, options?: {
+        remoteTools?: RemoteToolDefinition[];
+    }): Promise<ChatResponse>;
+    sendStream(content: string, options?: {
+        remoteTools?: RemoteToolDefinition[];
+    }): AsyncGenerator<ChatStreamEvent>;
+    delete(): Promise<void>;
+    getDetails(options?: {
+        messageLimit?: number;
+    }): Promise<ConversationDetail>;
+}
+
+/**
+ * SDK Error Messages
+ *
+ * User-friendly error messages in English and Chinese.
+ * All errors guide users to sanqian.io for installation.
+ */
+declare const SANQIAN_WEBSITE = "https://sanqian.io";
+/**
+ * Error codes for SDK errors
+ */
+declare enum SDKErrorCode {
+    NOT_INSTALLED = "NOT_INSTALLED",
+    NOT_RUNNING = "NOT_RUNNING",
+    CONNECTION_TIMEOUT = "CONNECTION_TIMEOUT",
+    STARTUP_TIMEOUT = "STARTUP_TIMEOUT",
+    REGISTRATION_FAILED = "REGISTRATION_FAILED",
+    REQUEST_TIMEOUT = "REQUEST_TIMEOUT",
+    REQUEST_FAILED = "REQUEST_FAILED",
+    DISCONNECTED = "DISCONNECTED",
+    WEBSOCKET_ERROR = "WEBSOCKET_ERROR",
+    AGENT_NOT_FOUND = "AGENT_NOT_FOUND",
+    CONVERSATION_NOT_FOUND = "CONVERSATION_NOT_FOUND",
+    TOOL_NOT_FOUND = "TOOL_NOT_FOUND",
+    TOOL_EXECUTION_TIMEOUT = "TOOL_EXECUTION_TIMEOUT"
+}
+/**
+ * Bilingual error messages
+ */
+declare const ErrorMessages: Record<SDKErrorCode, {
+    en: string;
+    zh: string;
+    hint?: {
+        en: string;
+        zh: string;
+    };
+}>;
+/**
+ * Custom SDK Error with code and bilingual message
+ */
+declare class SanqianSDKError extends Error {
+    code: SDKErrorCode;
+    messageZh: string;
+    hint?: string;
+    hintZh?: string;
+    constructor(code: SDKErrorCode, details?: string);
+    /**
+     * Get full error message with hint (English)
+     */
+    getFullMessage(): string;
+    /**
+     * Get full error message with hint (Chinese)
+     */
+    getFullMessageZh(): string;
+    /**
+     * Get bilingual error message
+     */
+    getBilingualMessage(): string;
+}
+/**
+ * Create a user-friendly SDK error
+ */
+declare function createSDKError(code: SDKErrorCode, details?: string): SanqianSDKError;
+
+export { type AgentConfig, type AgentInfo, type AgentUpdateConfig, type ChatMessage, type ChatRequest, type ChatResponse, type ChatStreamEvent, type ConnectionInfo, type ConnectionState, Conversation, type ConversationDetail, type ConversationInfo, type ConversationMessage, ErrorMessages, type JSONSchema, type JSONSchemaProperty, type RemoteToolDefinition, SANQIAN_WEBSITE, type SDKConfig, SDKErrorCode, type SDKEventName, type SDKEvents, SanqianSDK, SanqianSDKError, type ToolCall, type ToolDefinition, createSDKError };