@yushaw/sanqian-sdk 0.3.21 → 0.3.24

package/README.md

@@ -640,6 +640,31 @@ if (rerank.available) {
 
 ---
 
+## Messaging Channels API
+
+Channels methods in the SDK use Sanqian HTTP endpoints with `X-App-Token` auth. They only require runtime connection info and do not require WebSocket registration to be completed first.
+
+```typescript
+// Useful when building URLs for local HTTP integrations
+const baseUrl = sdk.getBaseUrl() // e.g. http://127.0.0.1:8765
+
+// Fetch config schema for setup forms
+const schema = await sdk.getChannelConfigSchema('telegram')
+
+// Validate/probe config before creating an account
+const probe = await sdk.probeChannelConfig({
+  channel_type: 'telegram',
+  config: { bot_token: process.env.TELEGRAM_BOT_TOKEN }
+})
+if (!probe.ok) {
+  console.error(probe.error)
+}
+```
+
+This section only shows the newly added methods. Full account/binding/message operations are available via `listChannelAccounts`, `createChannelAccount`, `listChannelBindings`, `sendChannelMessage`, and related methods.
+
+---
+
 ## Connection
 
 ### Connection Lifecycle
@@ -742,6 +767,8 @@ const sdk = new SanqianSDK({
   reconnectInterval: 5000,         // Reconnect interval (ms, default: 5000)
   heartbeatInterval: 30000,        // Heartbeat interval (ms, default: 30000)
   toolExecutionTimeout: 30000,     // Tool timeout (ms, default: 30000)
+  connectionFileReconnectMaxDurationMs: 300000, // File-watch reconnect max duration (ms, default: 5min)
+  connectionFileReconnectJitterMs: 300,         // Extra random delay per retry (ms, default: 300)
 
   // Auto-launch
   autoLaunchSanqian: true,         // Launch Sanqian if not running (default: true)
@@ -1521,6 +1548,31 @@ if (rerank.available) {
 
 ---
 
+## 消息渠道 API
+
+SDK 的 channels 方法通过 Sanqian HTTP 接口调用，并自动附带 `X-App-Token` 鉴权。它们只依赖运行时连接信息，不要求先完成 WebSocket 注册。
+
+```typescript
+// 构建本地 HTTP 集成时可直接复用
+const baseUrl = sdk.getBaseUrl() // 例如 http://127.0.0.1:8765
+
+// 获取某个渠道的配置 schema（用于设置表单）
+const schema = await sdk.getChannelConfigSchema('telegram')
+
+// 创建账号前先探测配置是否可用
+const probe = await sdk.probeChannelConfig({
+  channel_type: 'telegram',
+  config: { bot_token: process.env.TELEGRAM_BOT_TOKEN }
+})
+if (!probe.ok) {
+  console.error(probe.error)
+}
+```
+
+这里仅展示新增方法。完整渠道能力可通过 `listChannelAccounts`、`createChannelAccount`、`listChannelBindings`、`sendChannelMessage` 等方法使用。
+
+---
+
 ## 连接
 
 ### 连接生命周期
@@ -1778,4 +1830,4 @@ HTTP API 适合任意语言的简单对话。SDK 适合需要工具、Agent、
 | `400` | 请求参数无效 |
 | `404` | Agent 或会话未找到 |
 | `429` | 频率限制 |
-| `500` | 内部服务器错误 |
+| `500` | 内部服务器错误 |

package/dist/index.browser.d.mts

@@ -33,6 +33,16 @@ interface SDKConfig {
     heartbeatInterval?: number;
     /** Tool execution timeout in ms (default: 30000) */
     toolExecutionTimeout?: number;
+    /**
+     * Max duration for connection.json-triggered reconnect loop in ms (default: 300000 / 5min).
+     * After timeout, SDK stops retrying until next connection.json change event.
+     */
+    connectionFileReconnectMaxDurationMs?: number;
+    /**
+     * Random jitter upper bound for each connection.json reconnect delay in ms (default: 300).
+     * Helps avoid synchronized reconnect spikes when many apps reconnect together.
+     */
+    connectionFileReconnectJitterMs?: number;
     /**
      * Auto-launch Sanqian if not running (default: false)
      * When enabled, SDK will try to start Sanqian in hidden/tray mode
@@ -836,6 +846,11 @@ interface ChannelProbeResult {
     bot_username: string | null;
     error: string | null;
 }
+interface ProbeChannelConfigRequest {
+    channel_type: string;
+    config: Record<string, unknown>;
+}
+type ChannelConfigSchema = Record<string, unknown>;
 interface CreateChannelAccountRequest {
     channel_type: string;
     name: string;
@@ -967,11 +982,18 @@ declare class SanqianSDK {
     }>;
     private getHttpBaseUrl;
     private getHttpAuthHeaders;
+    private ensureHttpReady;
     /**
      * Get the port number for the Sanqian backend
      * @throws Error if not connected
      */
     getPort(): number;
+    /**
+     * Get the HTTP base URL for Sanqian backend.
+     *
+     * @throws Error if connection info is not available
+     */
+    getBaseUrl(): string;
     /**
      * Get conversation messages via history API (aligned with main app history)
      */
@@ -1114,6 +1136,8 @@ declare class SanqianSDK {
     }>;
     getChannelStatus(id: string): Promise<ChannelStatus>;
     probeChannelAccount(id: string): Promise<ChannelProbeResult>;
+    probeChannelConfig(req: ProbeChannelConfigRequest): Promise<ChannelProbeResult>;
+    getChannelConfigSchema(channelType: string): Promise<ChannelConfigSchema>;
     listChannelBindings(accountId?: string): Promise<ChannelBinding[]>;
     createChannelBinding(req: CreateChannelBindingRequest): Promise<ChannelBinding>;
     updateChannelBinding(id: string, req: UpdateChannelBindingRequest): Promise<ChannelBinding>;
@@ -1207,4 +1231,4 @@ declare class SanqianSDKError extends Error {
  */
 declare function createSDKError(code: SDKErrorCode, details?: string): SanqianSDKError;
 
-export { type AgentCapability, type AgentConfig, type AgentInfo, type AgentUpdateConfig, type Capability, type CapabilitySearchResult, type CapabilityType, type ChannelAccount, type ChannelAccountStatus, type ChannelBinding, type ChannelBindingMatchType, type ChannelChatType, type ChannelDmPolicy, type ChannelDmScope, type ChannelGroupPolicy, type ChannelPluginInfo, type ChannelProbeResult, type ChannelRuntimeStatus, type ChannelStatus, type ChatMessage, type ChatRequest, type ChatResponse, type ChatStreamEvent, type ConnectionInfo, type ConnectionState, type ContextData, type ContextListItem, type ContextProvider, Conversation, type ConversationDetail, type ConversationInfo, type ConversationMessage, type CreateChannelAccountRequest, type CreateChannelBindingRequest, type EmbeddingConfigResult, ErrorMessages, type HitlInterruptPayload, type HitlInterruptType, type HitlResponse, type HitlRiskLevel, type JSONSchema, type JSONSchemaProperty, type ListCapabilitiesOptions, type LoadItem, type LoadItemAction, type LoadItemType, type RemoteToolDefinition, type RerankConfigResult, SANQIAN_WEBSITE, type SDKConfig, SDKErrorCode, type SDKEventName, type SDKEvents, SanqianSDK, SanqianSDKError, type SearchCapabilitiesOptions, type SendChannelMessageRequest, type SendChannelMessageResponse, type SessionResource, type SkillCapability, type StoredSessionResource, type ToolCall, type ToolCapability, type ToolDefinition, type UpdateChannelAccountRequest, type UpdateChannelBindingRequest, createSDKError };
+export { type AgentCapability, type AgentConfig, type AgentInfo, type AgentUpdateConfig, type Capability, type CapabilitySearchResult, type CapabilityType, type ChannelAccount, type ChannelAccountStatus, type ChannelBinding, type ChannelBindingMatchType, type ChannelChatType, type ChannelConfigSchema, type ChannelDmPolicy, type ChannelDmScope, type ChannelGroupPolicy, type ChannelPluginInfo, type ChannelProbeResult, type ChannelRuntimeStatus, type ChannelStatus, type ChatMessage, type ChatRequest, type ChatResponse, type ChatStreamEvent, type ConnectionInfo, type ConnectionState, type ContextData, type ContextListItem, type ContextProvider, Conversation, type ConversationDetail, type ConversationInfo, type ConversationMessage, type CreateChannelAccountRequest, type CreateChannelBindingRequest, type EmbeddingConfigResult, ErrorMessages, type HitlInterruptPayload, type HitlInterruptType, type HitlResponse, type HitlRiskLevel, type JSONSchema, type JSONSchemaProperty, type ListCapabilitiesOptions, type LoadItem, type LoadItemAction, type LoadItemType, type ProbeChannelConfigRequest, type RemoteToolDefinition, type RerankConfigResult, SANQIAN_WEBSITE, type SDKConfig, SDKErrorCode, type SDKEventName, type SDKEvents, SanqianSDK, SanqianSDKError, type SearchCapabilitiesOptions, type SendChannelMessageRequest, type SendChannelMessageResponse, type SessionResource, type SkillCapability, type StoredSessionResource, type ToolCall, type ToolCapability, type ToolDefinition, type UpdateChannelAccountRequest, type UpdateChannelBindingRequest, createSDKError };

package/dist/index.browser.d.ts

@@ -33,6 +33,16 @@ interface SDKConfig {
     heartbeatInterval?: number;
     /** Tool execution timeout in ms (default: 30000) */
     toolExecutionTimeout?: number;
+    /**
+     * Max duration for connection.json-triggered reconnect loop in ms (default: 300000 / 5min).
+     * After timeout, SDK stops retrying until next connection.json change event.
+     */
+    connectionFileReconnectMaxDurationMs?: number;
+    /**
+     * Random jitter upper bound for each connection.json reconnect delay in ms (default: 300).
+     * Helps avoid synchronized reconnect spikes when many apps reconnect together.
+     */
+    connectionFileReconnectJitterMs?: number;
     /**
      * Auto-launch Sanqian if not running (default: false)
      * When enabled, SDK will try to start Sanqian in hidden/tray mode
@@ -836,6 +846,11 @@ interface ChannelProbeResult {
     bot_username: string | null;
     error: string | null;
 }
+interface ProbeChannelConfigRequest {
+    channel_type: string;
+    config: Record<string, unknown>;
+}
+type ChannelConfigSchema = Record<string, unknown>;
 interface CreateChannelAccountRequest {
     channel_type: string;
     name: string;
@@ -967,11 +982,18 @@ declare class SanqianSDK {
     }>;
     private getHttpBaseUrl;
     private getHttpAuthHeaders;
+    private ensureHttpReady;
     /**
      * Get the port number for the Sanqian backend
      * @throws Error if not connected
      */
     getPort(): number;
+    /**
+     * Get the HTTP base URL for Sanqian backend.
+     *
+     * @throws Error if connection info is not available
+     */
+    getBaseUrl(): string;
     /**
      * Get conversation messages via history API (aligned with main app history)
      */
@@ -1114,6 +1136,8 @@ declare class SanqianSDK {
     }>;
     getChannelStatus(id: string): Promise<ChannelStatus>;
     probeChannelAccount(id: string): Promise<ChannelProbeResult>;
+    probeChannelConfig(req: ProbeChannelConfigRequest): Promise<ChannelProbeResult>;
+    getChannelConfigSchema(channelType: string): Promise<ChannelConfigSchema>;
     listChannelBindings(accountId?: string): Promise<ChannelBinding[]>;
     createChannelBinding(req: CreateChannelBindingRequest): Promise<ChannelBinding>;
     updateChannelBinding(id: string, req: UpdateChannelBindingRequest): Promise<ChannelBinding>;
@@ -1207,4 +1231,4 @@ declare class SanqianSDKError extends Error {
  */
 declare function createSDKError(code: SDKErrorCode, details?: string): SanqianSDKError;
 
-export { type AgentCapability, type AgentConfig, type AgentInfo, type AgentUpdateConfig, type Capability, type CapabilitySearchResult, type CapabilityType, type ChannelAccount, type ChannelAccountStatus, type ChannelBinding, type ChannelBindingMatchType, type ChannelChatType, type ChannelDmPolicy, type ChannelDmScope, type ChannelGroupPolicy, type ChannelPluginInfo, type ChannelProbeResult, type ChannelRuntimeStatus, type ChannelStatus, type ChatMessage, type ChatRequest, type ChatResponse, type ChatStreamEvent, type ConnectionInfo, type ConnectionState, type ContextData, type ContextListItem, type ContextProvider, Conversation, type ConversationDetail, type ConversationInfo, type ConversationMessage, type CreateChannelAccountRequest, type CreateChannelBindingRequest, type EmbeddingConfigResult, ErrorMessages, type HitlInterruptPayload, type HitlInterruptType, type HitlResponse, type HitlRiskLevel, type JSONSchema, type JSONSchemaProperty, type ListCapabilitiesOptions, type LoadItem, type LoadItemAction, type LoadItemType, type RemoteToolDefinition, type RerankConfigResult, SANQIAN_WEBSITE, type SDKConfig, SDKErrorCode, type SDKEventName, type SDKEvents, SanqianSDK, SanqianSDKError, type SearchCapabilitiesOptions, type SendChannelMessageRequest, type SendChannelMessageResponse, type SessionResource, type SkillCapability, type StoredSessionResource, type ToolCall, type ToolCapability, type ToolDefinition, type UpdateChannelAccountRequest, type UpdateChannelBindingRequest, createSDKError };
+export { type AgentCapability, type AgentConfig, type AgentInfo, type AgentUpdateConfig, type Capability, type CapabilitySearchResult, type CapabilityType, type ChannelAccount, type ChannelAccountStatus, type ChannelBinding, type ChannelBindingMatchType, type ChannelChatType, type ChannelConfigSchema, type ChannelDmPolicy, type ChannelDmScope, type ChannelGroupPolicy, type ChannelPluginInfo, type ChannelProbeResult, type ChannelRuntimeStatus, type ChannelStatus, type ChatMessage, type ChatRequest, type ChatResponse, type ChatStreamEvent, type ConnectionInfo, type ConnectionState, type ContextData, type ContextListItem, type ContextProvider, Conversation, type ConversationDetail, type ConversationInfo, type ConversationMessage, type CreateChannelAccountRequest, type CreateChannelBindingRequest, type EmbeddingConfigResult, ErrorMessages, type HitlInterruptPayload, type HitlInterruptType, type HitlResponse, type HitlRiskLevel, type JSONSchema, type JSONSchemaProperty, type ListCapabilitiesOptions, type LoadItem, type LoadItemAction, type LoadItemType, type ProbeChannelConfigRequest, type RemoteToolDefinition, type RerankConfigResult, SANQIAN_WEBSITE, type SDKConfig, SDKErrorCode, type SDKEventName, type SDKEvents, SanqianSDK, SanqianSDKError, type SearchCapabilitiesOptions, type SendChannelMessageRequest, type SendChannelMessageResponse, type SessionResource, type SkillCapability, type StoredSessionResource, type ToolCall, type ToolCapability, type ToolDefinition, type UpdateChannelAccountRequest, type UpdateChannelBindingRequest, createSDKError };

package/dist/index.browser.js

@@ -999,7 +999,14 @@ var SanqianSDK = class _SanqianSDK {
   }
   async doFullConnect() {
     this.log("Starting connection (browser mode)...");
-    const info = this.config.connectionInfo;
+    await this.ensureHttpReady();
+    const info = this.connectionInfo || this.config.connectionInfo;
+    if (!info) {
+      throw createSDKError(
+        "NOT_RUNNING" /* NOT_RUNNING */,
+        "Connection info not available in browser mode"
+      );
+    }
     await this.connectWithInfo(info);
   }
   async updateTools(tools) {
@@ -1145,6 +1152,16 @@ var SanqianSDK = class _SanqianSDK {
     const token = info?.token;
     return token ? { "X-App-Token": token } : {};
   }
+  async ensureHttpReady() {
+    const info = this.connectionInfo || this.config.connectionInfo;
+    if (!info) {
+      throw createSDKError(
+        "NOT_RUNNING" /* NOT_RUNNING */,
+        "Connection info not available for HTTP API in browser build"
+      );
+    }
+    this.connectionInfo = info;
+  }
   /**
    * Get the port number for the Sanqian backend
    * @throws Error if not connected
@@ -1156,6 +1173,14 @@ var SanqianSDK = class _SanqianSDK {
     }
     return info.port;
   }
+  /**
+   * Get the HTTP base URL for Sanqian backend.
+   *
+   * @throws Error if connection info is not available
+   */
+  getBaseUrl() {
+    return this.getHttpBaseUrl();
+  }
   /**
    * Get conversation messages via history API (aligned with main app history)
    */
@@ -1707,7 +1732,7 @@ var SanqianSDK = class _SanqianSDK {
   // Channels
   // ============================================
   async listChannelPlugins() {
-    await this.ensureReady();
+    await this.ensureHttpReady();
     const url = `${this.getHttpBaseUrl()}/api/channels/plugins`;
     const response = await fetch(url, { headers: this.getHttpAuthHeaders() });
     if (!response.ok) {
@@ -1716,7 +1741,7 @@ var SanqianSDK = class _SanqianSDK {
     return response.json();
   }
   async listChannelAccounts() {
-    await this.ensureReady();
+    await this.ensureHttpReady();
     const url = `${this.getHttpBaseUrl()}/api/channels/accounts`;
     const response = await fetch(url, { headers: this.getHttpAuthHeaders() });
     if (!response.ok) {
@@ -1725,7 +1750,7 @@ var SanqianSDK = class _SanqianSDK {
     return response.json();
   }
   async createChannelAccount(req) {
-    await this.ensureReady();
+    await this.ensureHttpReady();
     const url = `${this.getHttpBaseUrl()}/api/channels/accounts`;
     const response = await fetch(url, {
       method: "POST",
@@ -1739,7 +1764,7 @@ var SanqianSDK = class _SanqianSDK {
     return response.json();
   }
   async getChannelAccount(id) {
-    await this.ensureReady();
+    await this.ensureHttpReady();
     const url = `${this.getHttpBaseUrl()}/api/channels/accounts/${encodeURIComponent(id)}`;
     const response = await fetch(url, { headers: this.getHttpAuthHeaders() });
     if (!response.ok) {
@@ -1748,7 +1773,7 @@ var SanqianSDK = class _SanqianSDK {
     return response.json();
   }
   async updateChannelAccount(id, req) {
-    await this.ensureReady();
+    await this.ensureHttpReady();
     const url = `${this.getHttpBaseUrl()}/api/channels/accounts/${encodeURIComponent(id)}`;
     const response = await fetch(url, {
       method: "PUT",
@@ -1762,7 +1787,7 @@ var SanqianSDK = class _SanqianSDK {
     return response.json();
   }
   async deleteChannelAccount(id) {
-    await this.ensureReady();
+    await this.ensureHttpReady();
     const url = `${this.getHttpBaseUrl()}/api/channels/accounts/${encodeURIComponent(id)}`;
     const response = await fetch(url, { method: "DELETE", headers: this.getHttpAuthHeaders() });
     if (!response.ok) {
@@ -1770,7 +1795,7 @@ var SanqianSDK = class _SanqianSDK {
     }
   }
   async startChannelAccount(id) {
-    await this.ensureReady();
+    await this.ensureHttpReady();
     const url = `${this.getHttpBaseUrl()}/api/channels/accounts/${encodeURIComponent(id)}/start`;
     const response = await fetch(url, { method: "POST", headers: this.getHttpAuthHeaders() });
     if (!response.ok) {
@@ -1780,7 +1805,7 @@ var SanqianSDK = class _SanqianSDK {
     return response.json();
   }
   async stopChannelAccount(id) {
-    await this.ensureReady();
+    await this.ensureHttpReady();
     const url = `${this.getHttpBaseUrl()}/api/channels/accounts/${encodeURIComponent(id)}/stop`;
     const response = await fetch(url, { method: "POST", headers: this.getHttpAuthHeaders() });
     if (!response.ok) {
@@ -1789,7 +1814,7 @@ var SanqianSDK = class _SanqianSDK {
     return response.json();
   }
   async getChannelStatus(id) {
-    await this.ensureReady();
+    await this.ensureHttpReady();
     const url = `${this.getHttpBaseUrl()}/api/channels/accounts/${encodeURIComponent(id)}/status`;
     const response = await fetch(url, { headers: this.getHttpAuthHeaders() });
     if (!response.ok) {
@@ -1798,7 +1823,7 @@ var SanqianSDK = class _SanqianSDK {
     return response.json();
   }
   async probeChannelAccount(id) {
-    await this.ensureReady();
+    await this.ensureHttpReady();
     const url = `${this.getHttpBaseUrl()}/api/channels/accounts/${encodeURIComponent(id)}/probe`;
     const response = await fetch(url, { method: "POST", headers: this.getHttpAuthHeaders() });
     if (!response.ok) {
@@ -1807,8 +1832,32 @@ var SanqianSDK = class _SanqianSDK {
     }
     return response.json();
   }
+  async probeChannelConfig(req) {
+    await this.ensureHttpReady();
+    const url = `${this.getHttpBaseUrl()}/api/channels/probe-config`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { ...this.getHttpAuthHeaders(), "Content-Type": "application/json" },
+      body: JSON.stringify(req)
+    });
+    if (!response.ok) {
+      const detail = await response.text();
+      throw createSDKError("REQUEST_FAILED" /* REQUEST_FAILED */, `Failed to probe channel config: ${detail}`);
+    }
+    return response.json();
+  }
+  async getChannelConfigSchema(channelType) {
+    await this.ensureHttpReady();
+    const url = `${this.getHttpBaseUrl()}/api/channels/plugins/${encodeURIComponent(channelType)}/config-schema`;
+    const response = await fetch(url, { headers: this.getHttpAuthHeaders() });
+    if (!response.ok) {
+      const detail = await response.text();
+      throw createSDKError("REQUEST_FAILED" /* REQUEST_FAILED */, `Failed to get channel config schema: ${detail}`);
+    }
+    return response.json();
+  }
   async listChannelBindings(accountId) {
-    await this.ensureReady();
+    await this.ensureHttpReady();
     const params = accountId ? `?account_id=${encodeURIComponent(accountId)}` : "";
     const url = `${this.getHttpBaseUrl()}/api/channels/bindings${params}`;
     const response = await fetch(url, { headers: this.getHttpAuthHeaders() });
@@ -1818,7 +1867,7 @@ var SanqianSDK = class _SanqianSDK {
     return response.json();
   }
   async createChannelBinding(req) {
-    await this.ensureReady();
+    await this.ensureHttpReady();
     const url = `${this.getHttpBaseUrl()}/api/channels/bindings`;
     const response = await fetch(url, {
       method: "POST",
@@ -1832,7 +1881,7 @@ var SanqianSDK = class _SanqianSDK {
     return response.json();
   }
   async updateChannelBinding(id, req) {
-    await this.ensureReady();
+    await this.ensureHttpReady();
     const url = `${this.getHttpBaseUrl()}/api/channels/bindings/${encodeURIComponent(id)}`;
     const response = await fetch(url, {
       method: "PUT",
@@ -1846,7 +1895,7 @@ var SanqianSDK = class _SanqianSDK {
     return response.json();
   }
   async deleteChannelBinding(id) {
-    await this.ensureReady();
+    await this.ensureHttpReady();
     const url = `${this.getHttpBaseUrl()}/api/channels/bindings/${encodeURIComponent(id)}`;
     const response = await fetch(url, { method: "DELETE", headers: this.getHttpAuthHeaders() });
     if (!response.ok) {
@@ -1854,7 +1903,7 @@ var SanqianSDK = class _SanqianSDK {
     }
   }
   async sendChannelMessage(req) {
-    await this.ensureReady();
+    await this.ensureHttpReady();
     const url = `${this.getHttpBaseUrl()}/api/channels/send`;
     const response = await fetch(url, {
       method: "POST",