@tbox-dev-js/sdk 0.1.4 → 0.1.6

package/dist/index.cjs

@@ -1180,6 +1180,10 @@ let KnowledgeClient$1 = class KnowledgeClient {
 
 /**
  * 百宝箱插件服务 SDK - 底层 HTTP 请求封装
+ *
+ * 支持两种鉴权模式：
+ * - B端：Authorization header（API Key）
+ * - C端：TBOXSESSIONID + X-Tbox-Channel + X-Tbox-AppId headers
  */
 /** 默认调用域名 */
 const DEFAULT_BASE_URL = 'https://o.tbox.cn';
@@ -1199,25 +1203,53 @@ function normalizeResponse(raw) {
 }
 /**
  * 底层 HTTP 客户端
+ *
+ * 支持两种构造方式：
+ * - 新版：传入 HttpClientConfig（含 AuthMode）
+ * - 旧版：传入 LegacyHttpClientConfig（含 apiKey，向后兼容）
  */
 class HttpClient {
     constructor(config) {
-        this.baseUrl = config.baseUrl.replace(/\/$/, '');
-        this.apiKey = config.apiKey;
+        this._baseUrl = config.baseUrl.replace(/\/$/, '');
         this.timeout = config.timeout;
+        if ('auth' in config) {
+            this.auth = config.auth;
+        }
+        else {
+            this.auth = { type: 'apiKey', apiKey: config.apiKey };
+        }
+    }
+    /** 获取 base URL */
+    get baseUrl() {
+        return this._baseUrl;
+    }
+    /** 获取鉴权请求头（供外部流式请求等场景使用） */
+    getAuthHeaders() {
+        return this.buildAuthHeaders();
+    }
+    /** 构建鉴权相关的请求头 */
+    buildAuthHeaders() {
+        if (this.auth.type === 'session') {
+            return {
+                TBOXSESSIONID: this.auth.session.sessionId,
+                'X-Tbox-Channel': this.auth.session.channel,
+                'X-Tbox-AppId': this.auth.session.appId,
+            };
+        }
+        return { Authorization: this.auth.apiKey };
     }
     /** 构建通用请求头 */
     buildHeaders(extra) {
         return {
             'Content-Type': 'application/json;charset=UTF-8',
-            Authorization: this.apiKey,
+            ...this.buildAuthHeaders(),
             ...extra,
         };
     }
     /** 构建 FormData 请求头（不设置 Content-Type，让浏览器自动处理 boundary） */
     buildHeadersForFormData(extra) {
         return {
-            Authorization: this.apiKey,
+            ...this.buildAuthHeaders(),
             ...extra,
         };
     }
@@ -1309,7 +1341,7 @@ class HttpClient {
             base = path;
         }
         else {
-            base = `${this.baseUrl}${path}`;
+            base = `${this._baseUrl}${path}`;
         }
         if (!queryParams || Object.keys(queryParams).length === 0) {
             return base;
@@ -1319,18 +1351,36 @@ class HttpClient {
     }
     /** 解析响应体 */
     async parseResponse(response) {
-        if (!response.ok) {
+        let text;
+        try {
+            const buffer = await response.arrayBuffer();
+            text = new TextDecoder('utf-8').decode(buffer);
+        }
+        catch {
             return {
                 success: false,
                 errorCode: `HTTP_${response.status}`,
                 errorMsg: `HTTP error: ${response.status} ${response.statusText}`,
             };
         }
+        // 非 200 时也尝试解析响应体，提取服务端返回的真实错误信息
+        if (!response.ok) {
+            try {
+                const errorJson = JSON.parse(text);
+                const errorCode = errorJson.errorCode ?? errorJson.code ?? errorJson.resultCode ?? `HTTP_${response.status}`;
+                const errorMsg = errorJson.errorMsg ?? errorJson.msg ?? errorJson.resultDesc ?? `HTTP error: ${response.status} ${response.statusText}`;
+                return { success: false, errorCode, errorMsg };
+            }
+            catch {
+                return {
+                    success: false,
+                    errorCode: `HTTP_${response.status}`,
+                    errorMsg: `HTTP error: ${response.status} ${response.statusText}`,
+                };
+            }
+        }
         let json;
         try {
-            // 使用 arrayBuffer + TextDecoder 确保多字节 UTF-8 字符（如中文）正确解码
-            const buffer = await response.arrayBuffer();
-            const text = new TextDecoder('utf-8').decode(buffer);
             json = JSON.parse(text);
         }
         catch {
@@ -1350,7 +1400,7 @@ class HttpClient {
  * 封装 /openapi/v1/plugin 下的全部接口
  */
 /** API 路径前缀 */
-const API_PREFIX$4 = '/openapi/v1/plugin';
+const API_PREFIX$5 = '/openapi/v1/plugin';
 /**
  * 百宝箱插件服务客户端
  *
@@ -1392,7 +1442,7 @@ class TboxPluginClient {
      * ```
      */
     async doTts(request) {
-        return this.http.post(`${API_PREFIX$4}/doTts`, request);
+        return this.http.post(`${API_PREFIX$5}/doTts`, request);
     }
     // ============================================================
     // ASR - 语音转文字
@@ -1414,7 +1464,7 @@ class TboxPluginClient {
      * ```
      */
     async asrBase64(request) {
-        return this.http.post(`${API_PREFIX$4}/asrBase64V2`, request);
+        return this.http.post(`${API_PREFIX$5}/asrBase64V2`, request);
     }
     // ============================================================
     // 插件工具执行
@@ -1441,7 +1491,7 @@ class TboxPluginClient {
      * ```
      */
     async run(pluginToolId, request) {
-        return this.http.post(`${API_PREFIX$4}/run/${encodeURIComponent(pluginToolId)}`, request);
+        return this.http.post(`${API_PREFIX$5}/run/${encodeURIComponent(pluginToolId)}`, request);
     }
     // ============================================================
     // 插件信息查询
@@ -1463,7 +1513,7 @@ class TboxPluginClient {
      * ```
      */
     async getPluginInfo(pluginId) {
-        return this.http.get(`${API_PREFIX$4}/info/${encodeURIComponent(pluginId)}`);
+        return this.http.get(`${API_PREFIX$5}/info/${encodeURIComponent(pluginId)}`);
     }
     /**
      * 网络搜索
@@ -1522,7 +1572,7 @@ TboxPluginClient.WEB_SEARCH_TOOL_ID = '20240611204600000001';
  * 封装 /openapi/v1/conversation 下的全部接口
  */
 /** API 路径前缀 */
-const API_PREFIX$3 = '/openapi/v1/conversation';
+const API_PREFIX$4 = '/openapi/v1/conversation';
 /**
  * 百宝箱会话管理客户端
  *
@@ -1570,7 +1620,7 @@ class TboxConversationClient {
      * ```
      */
     async createConversation(request) {
-        return this.http.post(`${API_PREFIX$3}/create`, request);
+        return this.http.post(`${API_PREFIX$4}/create`, request);
     }
     /**
      * 查询会话列表（分页）
@@ -1594,7 +1644,7 @@ class TboxConversationClient {
      * ```
      */
     async listConversations(request) {
-        return this.http.post(`${API_PREFIX$3}/list`, request);
+        return this.http.post(`${API_PREFIX$4}/list`, request);
     }
     // ============================================================
     // 消息管理
@@ -1620,7 +1670,7 @@ class TboxConversationClient {
      * ```
      */
     async listMessages(request) {
-        return this.http.post(`${API_PREFIX$3}/message/list`, request);
+        return this.http.post(`${API_PREFIX$4}/message/list`, request);
     }
     /**
      * 新增会话消息
@@ -1645,7 +1695,7 @@ class TboxConversationClient {
      * ```
      */
     async saveMessage(request) {
-        return this.http.post(`${API_PREFIX$3}/message/save`, request);
+        return this.http.post(`${API_PREFIX$4}/message/save`, request);
     }
 }
 
@@ -1703,6 +1753,116 @@ class TboxAppClient {
     }
 }
 
+/**
+ * 百宝箱首页开场白 SDK - HomepageClient 核心类
+ *
+ * 封装 /agent/v1/homepage 下的接口。
+ * 该接口走 C端鉴权（TBOXSESSIONID + X-Tbox-Channel + X-Tbox-AppId）。
+ */
+/** API 路径前缀 */
+const API_PREFIX$3 = '/agent/v1/homepage';
+/**
+ * 百宝箱首页开场白客户端（C端鉴权）
+ *
+ * @example
+ * ```ts
+ * import { TboxHomepageClient } from '@tbox-dev-js/sdk';
+ *
+ * // 方式一：自动获取 session（推荐）
+ * const client = await TboxHomepageClient.create({
+ *   apiKey: 'your-api-key',
+ *   appId: '202508APhciU03604644',
+ *   userId: 'user-123',
+ * });
+ *
+ * // 方式二：手动传入 session
+ * const client = new TboxHomepageClient({
+ *   session: { sessionId: 'xxx', channel: 'alipay_mini_app', appId: '202508APhciU03604644' },
+ * });
+ *
+ * const result = await client.get({ agentId: '202508APhciU03604644' });
+ * if (result.success) {
+ *   console.log('开场白:', result.data?.prologue);
+ * }
+ * ```
+ */
+class TboxHomepageClient {
+    /**
+     * 使用 C端 Session 鉴权构造
+     */
+    constructor(config) {
+        this.http = new HttpClient({
+            baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,
+            auth: { type: 'session', session: config.session },
+            timeout: config.timeout,
+        });
+    }
+    /**
+     * 便捷工厂方法：通过 B端 apiKey 自动获取 session 并创建 C端客户端
+     *
+     * 内部流程：
+     * 1. 使用 apiKey 调用 TboxAppClient.generateSession() 获取 sessionId + channel
+     * 2. 用获取到的 session 信息创建 C端鉴权的 HomepageClient
+     *
+     * @param options - 创建参数（apiKey、appId、userId）
+     * @returns 已鉴权的 TboxHomepageClient 实例
+     *
+     * @example
+     * ```ts
+     * const client = await TboxHomepageClient.create({
+     *   apiKey: 'your-api-key',
+     *   appId: '202508APhciU03604644',
+     *   userId: 'user-123',
+     * });
+     * ```
+     */
+    static async create(options) {
+        const appClient = new TboxAppClient({
+            apiKey: options.apiKey,
+            baseUrl: options.baseUrl,
+            timeout: options.timeout,
+        });
+        const sessionResult = await appClient.generateSession({
+            appId: options.appId,
+            userId: options.userId,
+        });
+        if (!sessionResult.success || !sessionResult.data?.sessionId || !sessionResult.data?.channel) {
+            throw new Error(`Failed to generate session: ${sessionResult.errorCode ?? 'UNKNOWN'} - ${sessionResult.errorMsg ?? 'No session data returned'}`);
+        }
+        return new TboxHomepageClient({
+            session: {
+                sessionId: sessionResult.data.sessionId,
+                channel: sessionResult.data.channel,
+                appId: options.appId,
+            },
+            baseUrl: options.baseUrl,
+            timeout: options.timeout,
+        });
+    }
+    /**
+     * 获取首页开场白
+     *
+     * POST /agent/v1/homepage/get
+     *
+     * @param request - 请求参数，agentId 为必填
+     * @returns 开场白信息，包含开场白文本、推荐问题等
+     *
+     * @example
+     * ```ts
+     * const res = await client.get({
+     *   agentId: '202508APhciU03604644',
+     *   extInfo: '{}',
+     * });
+     * if (res.success) {
+     *   console.log(res.data?.prologue);
+     * }
+     * ```
+     */
+    async get(request) {
+        return this.http.post(`${API_PREFIX$3}/get`, request);
+    }
+}
+
 /**
  * 高德地图 SDK - AmapClient 核心类
  *
@@ -2834,12 +2994,12 @@ class LlmClient {
      * 流式调用 Chat Completions
      */
     async *streamChatCompletions(request) {
-        const url = `${this.http['baseUrl']}${API_PREFIX}/chat/completions`;
+        const url = `${this.http.baseUrl}${API_PREFIX}/chat/completions`;
         const response = await fetch(url, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json;charset=UTF-8',
-                Authorization: this.http['apiKey'],
+                ...this.http.getAuthHeaders(),
             },
             body: JSON.stringify(request),
         });
@@ -2975,6 +3135,7 @@ exports.TboxAPI = TboxAPI;
 exports.TboxAppClient = TboxAppClient;
 exports.TboxConversationClient = TboxConversationClient;
 exports.TboxError = TboxError;
+exports.TboxHomepageClient = TboxHomepageClient;
 exports.TboxPluginClient = TboxPluginClient;
 exports.TimeoutError = TimeoutError;
 exports.knowledgeSchema = knowledgeSchema;