@yushaw/sanqian-sdk 0.2.0 → 0.2.2

package/dist/index.d.mts

@@ -63,6 +63,8 @@ interface ConnectionInfo {
     token: string;
     pid: number;
     started_at: string;
+    /** Path to Sanqian executable (for SDK auto-launch) */
+    executable?: string;
 }
 interface ConnectionState {
     connected: boolean;
@@ -215,6 +217,7 @@ declare class SanqianSDK {
     private heartbeatAckPending;
     private missedHeartbeats;
     private static readonly MAX_MISSED_HEARTBEATS;
+    private connectingPromise;
     private eventListeners;
     constructor(config: SDKConfig);
     /**
@@ -225,6 +228,9 @@ declare class SanqianSDK {
      *
      * If autoLaunchSanqian is enabled and Sanqian is not running,
      * SDK will attempt to start it in hidden/tray mode.
+     *
+     * @throws Error if Sanqian executable cannot be found (when autoLaunchSanqian is enabled)
+     * @throws Error if connection times out after 2 minutes
      */
     connect(): Promise<void>;
     /**
@@ -256,11 +262,31 @@ declare class SanqianSDK {
      */
     isConnected(): boolean;
     /**
-     * Wait for connection to be established.
-     * Used internally by chat() and chatStream() for auto-reconnect.
-     * Relies on background scheduleReconnect() to do the actual reconnection.
+     * Ensure SDK is ready for API calls.
+     *
+     * This is the unified entry point for all API methods that require a connection.
+     * It handles:
+     * - Already connected: returns immediately
+     * - Connection in progress: waits for existing attempt (deduplication)
+     * - Not connected: initiates connection (with optional auto-launch)
+     *
+     * Design pattern: gRPC wait-for-ready + ClientFactory promise deduplication
+     *
+     * @throws Error if connection fails or times out
+     */
+    ensureReady(): Promise<void>;
+    /**
+     * Internal: Perform full connection flow
+     * Handles launching Sanqian if needed, then connecting and registering.
+     *
+     * Note: This method is protected by connectingPromise deduplication in ensureReady(),
+     * so there's no need for additional launch-in-progress tracking within a single instance.
+     */
+    private doFullConnect;
+    /**
+     * Wait for Sanqian to start and connection.json to become available
      */
-    private waitForConnection;
+    private waitForSanqianStartup;
     /**
      * Update tool list dynamically
      */
@@ -431,6 +457,11 @@ declare class DiscoveryManager {
     private watcher;
     private onChange;
     private pollInterval;
+    /**
+     * Cached executable path from last successful connection.json read.
+     * Persists even when Sanqian is not running, for use in auto-launch.
+     */
+    private cachedExecutable;
     /**
      * Get the path to connection.json
      */
@@ -482,6 +513,11 @@ declare class DiscoveryManager {
     /**
      * Launch Sanqian in hidden/tray mode
      * Returns true if launch was initiated successfully
+     *
+     * Priority for finding Sanqian executable:
+     * 1. customPath parameter (if provided)
+     * 2. Cached executable from connection.json (most reliable)
+     * 3. Search in standard installation locations (fallback)
      */
     launchSanqian(customPath?: string): boolean;
     /**
@@ -490,4 +526,67 @@ declare class DiscoveryManager {
     isSanqianRunning(): boolean;
 }
 
-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, DiscoveryManager, type JSONSchema, type JSONSchemaProperty, type RemoteToolDefinition, type SDKConfig, type SDKEventName, type SDKEvents, SanqianSDK, type ToolCall, type ToolDefinition };
+/**
+ * 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, DiscoveryManager, ErrorMessages, type JSONSchema, type JSONSchemaProperty, type RemoteToolDefinition, SANQIAN_WEBSITE, type SDKConfig, SDKErrorCode, type SDKEventName, type SDKEvents, SanqianSDK, SanqianSDKError, type ToolCall, type ToolDefinition, createSDKError };

package/dist/index.d.ts

@@ -63,6 +63,8 @@ interface ConnectionInfo {
     token: string;
     pid: number;
     started_at: string;
+    /** Path to Sanqian executable (for SDK auto-launch) */
+    executable?: string;
 }
 interface ConnectionState {
     connected: boolean;
@@ -215,6 +217,7 @@ declare class SanqianSDK {
     private heartbeatAckPending;
     private missedHeartbeats;
     private static readonly MAX_MISSED_HEARTBEATS;
+    private connectingPromise;
     private eventListeners;
     constructor(config: SDKConfig);
     /**
@@ -225,6 +228,9 @@ declare class SanqianSDK {
      *
      * If autoLaunchSanqian is enabled and Sanqian is not running,
      * SDK will attempt to start it in hidden/tray mode.
+     *
+     * @throws Error if Sanqian executable cannot be found (when autoLaunchSanqian is enabled)
+     * @throws Error if connection times out after 2 minutes
      */
     connect(): Promise<void>;
     /**
@@ -256,11 +262,31 @@ declare class SanqianSDK {
      */
     isConnected(): boolean;
     /**
-     * Wait for connection to be established.
-     * Used internally by chat() and chatStream() for auto-reconnect.
-     * Relies on background scheduleReconnect() to do the actual reconnection.
+     * Ensure SDK is ready for API calls.
+     *
+     * This is the unified entry point for all API methods that require a connection.
+     * It handles:
+     * - Already connected: returns immediately
+     * - Connection in progress: waits for existing attempt (deduplication)
+     * - Not connected: initiates connection (with optional auto-launch)
+     *
+     * Design pattern: gRPC wait-for-ready + ClientFactory promise deduplication
+     *
+     * @throws Error if connection fails or times out
+     */
+    ensureReady(): Promise<void>;
+    /**
+     * Internal: Perform full connection flow
+     * Handles launching Sanqian if needed, then connecting and registering.
+     *
+     * Note: This method is protected by connectingPromise deduplication in ensureReady(),
+     * so there's no need for additional launch-in-progress tracking within a single instance.
+     */
+    private doFullConnect;
+    /**
+     * Wait for Sanqian to start and connection.json to become available
      */
-    private waitForConnection;
+    private waitForSanqianStartup;
     /**
      * Update tool list dynamically
      */
@@ -431,6 +457,11 @@ declare class DiscoveryManager {
     private watcher;
     private onChange;
     private pollInterval;
+    /**
+     * Cached executable path from last successful connection.json read.
+     * Persists even when Sanqian is not running, for use in auto-launch.
+     */
+    private cachedExecutable;
     /**
      * Get the path to connection.json
      */
@@ -482,6 +513,11 @@ declare class DiscoveryManager {
     /**
      * Launch Sanqian in hidden/tray mode
      * Returns true if launch was initiated successfully
+     *
+     * Priority for finding Sanqian executable:
+     * 1. customPath parameter (if provided)
+     * 2. Cached executable from connection.json (most reliable)
+     * 3. Search in standard installation locations (fallback)
      */
     launchSanqian(customPath?: string): boolean;
     /**
@@ -490,4 +526,67 @@ declare class DiscoveryManager {
     isSanqianRunning(): boolean;
 }
 
-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, DiscoveryManager, type JSONSchema, type JSONSchemaProperty, type RemoteToolDefinition, type SDKConfig, type SDKEventName, type SDKEvents, SanqianSDK, type ToolCall, type ToolDefinition };
+/**
+ * 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, DiscoveryManager, ErrorMessages, type JSONSchema, type JSONSchemaProperty, type RemoteToolDefinition, SANQIAN_WEBSITE, type SDKConfig, SDKErrorCode, type SDKEventName, type SDKEvents, SanqianSDK, SanqianSDKError, type ToolCall, type ToolDefinition, createSDKError };