@lingya-ai/agents-sdk 0.1.2 → 0.4.0

package/dist/client.d.ts

@@ -1,13 +1,13 @@
 import { Configuration } from './runtime';
-import { ChatApi, ConfigurationApi, ConversationsApi, EventsApi, FilesApi, InteractionsApi, KnowledgeApi, MessagesApi, SQLApi, WorkspaceApi } from './apis';
 import { type OpenApiCredentials } from './hmac';
-import { type LingyaAiChatBriefEvent } from './events';
+import { type AiChatBriefEvent } from './events';
+import { AgentsLowLevelApis, ChatApi as BoundChatApi, ConfigurationApi as BoundConfigurationApi, ConversationsApi as BoundConversationsApi, EventsApi as BoundEventsApi, FilesApi as BoundFilesApi, InteractionsApi as BoundInteractionsApi, KnowledgeApi as BoundKnowledgeApi, MessagesApi as BoundMessagesApi, SqlApi, WorkspaceApi as BoundWorkspaceApi } from './bound';
 /**
  * Lingya Agents SDK 入口，仅适用于可信服务端。 / Server-side Lingya Agents SDK entry point.
  *
  * 客户端保存 channel 范围的凭证，但只有 [forUser] 创建的用户客户端可以发起请求。
  */
-export declare class LingyaAgentsClient {
+export declare class AgentsClient {
     private readonly baseUrl;
     readonly channelId: string;
     private readonly credentials;
@@ -25,33 +25,39 @@ export declare class LingyaAgentsClient {
      * @param externalUserId - 调用方系统的稳定用户 ID，UTF-8 编码后为 1..256 字节且不能含 NUL。
      * @returns 注入用户身份并可调用全部契约 API 的客户端。
      */
-    forUser(externalUserId: string): LingyaAgentsUserClient;
+    forUser(externalUserId: string): AgentsUserClient;
 }
 /** 已绑定外部用户的强类型 API 集合。 / Strongly typed API collection bound to one external user. */
-export declare class LingyaAgentsUserClient {
+export declare class AgentsUserClient {
     readonly channelId: string;
     private readonly signedFetch;
     private readonly baseUrl;
     /** 发起新聊天和流探针。 / Starts chats and stream probes. */
-    readonly chat: ChatApi;
+    readonly chat: BoundChatApi;
     /** 读取 Agent 与会话配置。 / Reads Agent and conversation configuration. */
-    readonly configuration: ConfigurationApi;
+    readonly configuration: BoundConfigurationApi;
     /** 管理会话、状态、分享和异步任务。 / Manages conversations, status, shares, and async tasks. */
-    readonly conversations: ConversationsApi;
+    readonly conversations: BoundConversationsApi;
     /** 查询已持久化事件。 / Reads persisted events. */
-    readonly events: EventsApi;
+    readonly events: BoundEventsApi;
     /** 管理附件与预签名 URL。 / Manages attachments and pre-signed URLs. */
-    readonly files: FilesApi;
+    readonly files: BoundFilesApi;
     /** 回答用户问题并处理计划审批。 / Handles user answers and plan approval. */
-    readonly interactions: InteractionsApi;
+    readonly interactions: BoundInteractionsApi;
     /** 查询引用元数据。 / Reads citation metadata. */
-    readonly knowledge: KnowledgeApi;
+    readonly knowledge: BoundKnowledgeApi;
     /** 查询消息并控制排队消息。 / Reads messages and controls queued messages. */
-    readonly messages: MessagesApi;
+    readonly messages: BoundMessagesApi;
     /** 查询、导出 SQL 结果与图表数据。 / Reads and exports SQL results and chart data. */
-    readonly sql: SQLApi;
+    readonly sql: SqlApi;
     /** 查询工作区文件及预览。 / Reads workspace files and previews. */
-    readonly workspace: WorkspaceApi;
+    readonly workspace: BoundWorkspaceApi;
+    /**
+     * 兼容旧版本的原始生成 API；正常业务调用应使用绑定门面。 / Raw generated APIs retained for migration only.
+     *
+     * @deprecated 将在 1.0 移除。 / Scheduled for removal in 1.0.
+     */
+    readonly lowLevel: AgentsLowLevelApis;
     constructor(channelId: string, configuration: Configuration, signedFetch: typeof fetch, baseUrl: string);
     /**
      * 调用契约端点并按指定类型返回 JSON；优先使用上方生成的强类型 API。 / Calls a contract endpoint and decodes typed JSON.
@@ -61,8 +67,9 @@ export declare class LingyaAgentsUserClient {
      * @param bodyJson - 最终发送并参与签名的 UTF-8 JSON 字符串；无请求体时省略。
      * @param query - 已按最终顺序组装的查询参数，允许重复键。
      * @returns 调用方指定的响应类型。
-     * @throws [LingyaApiError] 当服务端返回非 2xx 状态。
+     * @throws [ApiError] 当服务端返回非 2xx 状态。
      */
+    /** @deprecated 使用对应的业务分组方法。 / Use the matching grouped facade operation. */
     request<T>(method: string, suffix: string, bodyJson?: string, query?: URLSearchParams): Promise<T>;
     /**
      * 调用无响应正文的契约端点。 / Calls a contract endpoint that has no response body.
@@ -73,6 +80,7 @@ export declare class LingyaAgentsUserClient {
      * @param query - 保留顺序的查询参数。
      * @returns 2xx HTTP 状态码。
      */
+    /** @deprecated 使用对应的业务分组方法。 / Use the matching grouped facade operation. */
     requestStatus(method: string, suffix: string, bodyJson?: string, query?: URLSearchParams): Promise<number>;
     /**
      * 下载二进制响应，返回精确响应字节。 / Downloads an exact binary response.
@@ -82,6 +90,7 @@ export declare class LingyaAgentsUserClient {
      * @param query - 保留顺序的查询参数。
      * @returns 未经文本转换的响应字节。
      */
+    /** @deprecated 使用对应的业务分组方法。 / Use the matching grouped facade operation. */
     requestBinary(method: string, suffix: string, query?: URLSearchParams): Promise<Uint8Array>;
     /**
      * 订阅对话 SSE，事件按契约判别联合返回。 / Streams SSE as the contract discriminated union.
@@ -90,7 +99,8 @@ export declare class LingyaAgentsUserClient {
      * @param messageId - 触发本次生成的消息 ID。
      * @returns 支持取消的异步事件序列；未知 type 保留 `rawJson`。
      */
-    streamChatEvents(conversationId: string, messageId: string): AsyncGenerator<LingyaAiChatBriefEvent>;
+    /** @deprecated 使用 `chat.streamChatEvents(conversationId, { messageId })`。 / Use the channel-bound chat facade. */
+    streamChatEvents(conversationId: string, messageId: string): AsyncGenerator<AiChatBriefEvent>;
     /**
      * 发送底层受控请求；调用前固定最终 path、query、Content-Type 与 body 字节。 / Sends an exactly signed low-level request.
      *
@@ -102,15 +112,22 @@ export declare class LingyaAgentsUserClient {
      * @param query - 最终查询参数；顺序和重复键均参与签名。
      * @param accept - 精确的 Accept 值，例如 `application/json`、`text/event-stream` 或 `text/csv`。
      * @returns 成功的原始 Fetch Response。
-     * @throws [LingyaApiError] 当服务端返回非 2xx 状态。
+     * @throws [ApiError] 当服务端返回非 2xx 状态。
      */
-    rawRequest(method: string, suffix: string, bodyJson?: string, query?: URLSearchParams, accept?: string): Promise<Response>;
+    /** @deprecated 使用 `lowLevel`，或使用对应的业务分组方法。 / Use `lowLevel` or a grouped facade operation. */
+    rawRequest(method: string, suffix: string, bodyJson?: string, query?: URLSearchParams, accept?: string, requestId?: string): Promise<Response>;
 }
 /** 不含凭证的 HTTP 错误。 / HTTP failure that never includes credentials. */
-export declare class LingyaApiError extends Error {
+export declare class ApiError extends Error {
     readonly method: string;
     readonly path: string;
     readonly status: number;
     readonly responseBody: string;
     constructor(method: string, path: string, status: number, responseBody: string);
 }
+/** @deprecated Use [AgentsClient]. */
+export { AgentsClient as LingyaAgentsClient };
+/** @deprecated Use [AgentsUserClient]. */
+export { AgentsUserClient as LingyaAgentsUserClient };
+/** @deprecated Use [ApiError]. */
+export { ApiError as LingyaApiError };

package/dist/client.js

@@ -8,39 +8,18 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
-var __asyncValues = (this && this.__asyncValues) || function (o) {
-    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
-    var m = o[Symbol.asyncIterator], i;
-    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
-    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
-    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
-};
-var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
-    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
-    var g = generator.apply(thisArg, _arguments || []), i, q = [];
-    return i = Object.create((typeof AsyncIterator === "function" ? AsyncIterator : Object).prototype), verb("next"), verb("throw"), verb("return", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;
-    function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }
-    function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }
-    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
-    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
-    function fulfill(value) { resume("next", value); }
-    function reject(value) { resume("throw", value); }
-    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LingyaApiError = exports.LingyaAgentsUserClient = exports.LingyaAgentsClient = void 0;
+exports.LingyaApiError = exports.LingyaAgentsUserClient = exports.LingyaAgentsClient = exports.ApiError = exports.AgentsUserClient = exports.AgentsClient = void 0;
 const runtime_1 = require("./runtime");
 const apis_1 = require("./apis");
 const hmac_1 = require("./hmac");
-const sse_1 = require("./sse");
-const events_1 = require("./events");
+const bound_1 = require("./bound");
 /**
  * Lingya Agents SDK 入口，仅适用于可信服务端。 / Server-side Lingya Agents SDK entry point.
  *
  * 客户端保存 channel 范围的凭证，但只有 [forUser] 创建的用户客户端可以发起请求。
  */
-class LingyaAgentsClient {
+class AgentsClient {
     /**
      * 创建 channel 范围的客户端。 / Creates a channel-scoped client.
      *
@@ -64,26 +43,39 @@ class LingyaAgentsClient {
     forUser(externalUserId) {
         const signedFetch = (0, hmac_1.createSignedFetch)(this.credentials, externalUserId);
         const configuration = new runtime_1.Configuration({ basePath: this.baseUrl.replace(/\/+$/, ''), fetchApi: signedFetch });
-        return new LingyaAgentsUserClient(this.channelId, configuration, signedFetch, this.baseUrl);
+        return new AgentsUserClient(this.channelId, configuration, signedFetch, this.baseUrl);
     }
 }
-exports.LingyaAgentsClient = LingyaAgentsClient;
+exports.AgentsClient = AgentsClient;
+exports.LingyaAgentsClient = AgentsClient;
 /** 已绑定外部用户的强类型 API 集合。 / Strongly typed API collection bound to one external user. */
-class LingyaAgentsUserClient {
+class AgentsUserClient {
     constructor(channelId, configuration, signedFetch, baseUrl) {
         this.channelId = channelId;
         this.signedFetch = signedFetch;
         this.baseUrl = baseUrl;
-        this.chat = new apis_1.ChatApi(configuration);
-        this.configuration = new apis_1.ConfigurationApi(configuration);
-        this.conversations = new apis_1.ConversationsApi(configuration);
-        this.events = new apis_1.EventsApi(configuration);
-        this.files = new apis_1.FilesApi(configuration);
-        this.interactions = new apis_1.InteractionsApi(configuration);
-        this.knowledge = new apis_1.KnowledgeApi(configuration);
-        this.messages = new apis_1.MessagesApi(configuration);
-        this.sql = new apis_1.SQLApi(configuration);
-        this.workspace = new apis_1.WorkspaceApi(configuration);
+        const chat = new apis_1.ChatApi(configuration);
+        const configurationApi = new apis_1.ConfigurationApi(configuration);
+        const conversations = new apis_1.ConversationsApi(configuration);
+        const events = new apis_1.EventsApi(configuration);
+        const files = new apis_1.FilesApi(configuration);
+        const interactions = new apis_1.InteractionsApi(configuration);
+        const knowledge = new apis_1.KnowledgeApi(configuration);
+        const messages = new apis_1.MessagesApi(configuration);
+        const sql = new apis_1.SQLApi(configuration);
+        const workspace = new apis_1.WorkspaceApi(configuration);
+        this.lowLevel = new bound_1.AgentsLowLevelApis(configurationApi, chat, conversations, sql, messages, events, interactions, files, knowledge, workspace);
+        const rawRequest = this.rawRequest.bind(this);
+        this.chat = new bound_1.ChatApi(channelId, chat, rawRequest);
+        this.configuration = new bound_1.ConfigurationApi(channelId, configurationApi);
+        this.conversations = new bound_1.ConversationsApi(channelId, conversations);
+        this.events = new bound_1.EventsApi(channelId, events);
+        this.files = new bound_1.FilesApi(channelId, files);
+        this.interactions = new bound_1.InteractionsApi(channelId, interactions);
+        this.knowledge = new bound_1.KnowledgeApi(channelId, knowledge);
+        this.messages = new bound_1.MessagesApi(channelId, messages);
+        this.sql = new bound_1.SqlApi(channelId, sql);
+        this.workspace = new bound_1.WorkspaceApi(channelId, workspace);
     }
     /**
      * 调用契约端点并按指定类型返回 JSON；优先使用上方生成的强类型 API。 / Calls a contract endpoint and decodes typed JSON.
@@ -93,8 +85,9 @@ class LingyaAgentsUserClient {
      * @param bodyJson - 最终发送并参与签名的 UTF-8 JSON 字符串；无请求体时省略。
      * @param query - 已按最终顺序组装的查询参数，允许重复键。
      * @returns 调用方指定的响应类型。
-     * @throws [LingyaApiError] 当服务端返回非 2xx 状态。
+     * @throws [ApiError] 当服务端返回非 2xx 状态。
      */
+    /** @deprecated 使用对应的业务分组方法。 / Use the matching grouped facade operation. */
     request(method, suffix, bodyJson, query) {
         return __awaiter(this, void 0, void 0, function* () {
             const response = yield this.rawRequest(method, suffix, bodyJson, query, 'application/json');
@@ -110,6 +103,7 @@ class LingyaAgentsUserClient {
      * @param query - 保留顺序的查询参数。
      * @returns 2xx HTTP 状态码。
      */
+    /** @deprecated 使用对应的业务分组方法。 / Use the matching grouped facade operation. */
     requestStatus(method, suffix, bodyJson, query) {
         return __awaiter(this, void 0, void 0, function* () {
             return (yield this.rawRequest(method, suffix, bodyJson, query, 'application/json')).status;
@@ -123,6 +117,7 @@ class LingyaAgentsUserClient {
      * @param query - 保留顺序的查询参数。
      * @returns 未经文本转换的响应字节。
      */
+    /** @deprecated 使用对应的业务分组方法。 / Use the matching grouped facade operation. */
     requestBinary(method, suffix, query) {
         return __awaiter(this, void 0, void 0, function* () {
             const response = yield this.rawRequest(method, suffix, undefined, query, 'application/octet-stream');
@@ -136,27 +131,9 @@ class LingyaAgentsUserClient {
      * @param messageId - 触发本次生成的消息 ID。
      * @returns 支持取消的异步事件序列；未知 type 保留 `rawJson`。
      */
+    /** @deprecated 使用 `chat.streamChatEvents(conversationId, { messageId })`。 / Use the channel-bound chat facade. */
     streamChatEvents(conversationId, messageId) {
-        return __asyncGenerator(this, arguments, function* streamChatEvents_1() {
-            var _a, e_1, _b, _c;
-            const suffix = `/conversations/${encodeURIComponent(conversationId)}/stream`;
-            const response = yield __await(this.rawRequest('POST', suffix, JSON.stringify({ messageId }), undefined, 'text/event-stream'));
-            try {
-                for (var _d = true, _e = __asyncValues((0, sse_1.decodeSse)(response)), _f; _f = yield __await(_e.next()), _a = _f.done, !_a; _d = true) {
-                    _c = _f.value;
-                    _d = false;
-                    const data = _c;
-                    yield yield __await((0, events_1.decodeAiChatBriefEvent)(data));
-                }
-            }
-            catch (e_1_1) { e_1 = { error: e_1_1 }; }
-            finally {
-                try {
-                    if (!_d && !_a && (_b = _e.return)) yield __await(_b.call(_e));
-                }
-                finally { if (e_1) throw e_1.error; }
-            }
-        });
+        return this.chat.streamChatEvents(conversationId, { messageId });
     }
     /**
      * 发送底层受控请求；调用前固定最终 path、query、Content-Type 与 body 字节。 / Sends an exactly signed low-level request.
@@ -169,33 +146,36 @@ class LingyaAgentsUserClient {
      * @param query - 最终查询参数；顺序和重复键均参与签名。
      * @param accept - 精确的 Accept 值，例如 `application/json`、`text/event-stream` 或 `text/csv`。
      * @returns 成功的原始 Fetch Response。
-     * @throws [LingyaApiError] 当服务端返回非 2xx 状态。
+     * @throws [ApiError] 当服务端返回非 2xx 状态。
      */
+    /** @deprecated 使用 `lowLevel`，或使用对应的业务分组方法。 / Use `lowLevel` or a grouped facade operation. */
     rawRequest(method_1, suffix_1, bodyJson_1, query_1) {
-        return __awaiter(this, arguments, void 0, function* (method, suffix, bodyJson, query, accept = 'application/json') {
+        return __awaiter(this, arguments, void 0, function* (method, suffix, bodyJson, query, accept = 'application/json', requestId) {
             const root = `${this.baseUrl.replace(/\/+$/, '')}/api/agents/channel/openapi/v1/${encodeURIComponent(this.channelId)}/chat`;
             const url = `${root}${suffix}${query === undefined || query.size === 0 ? '' : `?${query.toString()}`}`;
             const response = yield this.signedFetch(url, {
                 method,
-                headers: Object.assign({ Accept: accept }, (bodyJson === undefined ? {} : { 'Content-Type': 'application/json' })),
+                headers: Object.assign(Object.assign({ Accept: accept }, (bodyJson === undefined ? {} : { 'Content-Type': 'application/json' })), (requestId === undefined ? {} : { 'X-Request-ID': requestId })),
                 body: bodyJson,
             });
             if (!response.ok)
-                throw new LingyaApiError(method, suffix, response.status, yield response.text());
+                throw new ApiError(method, suffix, response.status, yield response.text());
             return response;
         });
     }
 }
-exports.LingyaAgentsUserClient = LingyaAgentsUserClient;
+exports.AgentsUserClient = AgentsUserClient;
+exports.LingyaAgentsUserClient = AgentsUserClient;
 /** 不含凭证的 HTTP 错误。 / HTTP failure that never includes credentials. */
-class LingyaApiError extends Error {
+class ApiError extends Error {
     constructor(method, path, status, responseBody) {
         super(`${method} ${path} returned HTTP ${status}`);
         this.method = method;
         this.path = path;
         this.status = status;
         this.responseBody = responseBody;
-        this.name = 'LingyaApiError';
+        this.name = 'ApiError';
     }
 }
-exports.LingyaApiError = LingyaApiError;
+exports.ApiError = ApiError;
+exports.LingyaApiError = ApiError;