@lingya-ai/agents-sdk 0.1.2

package/dist/esm/apis/WorkspaceApi.js

@@ -0,0 +1,190 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Lingya Agents OpenAPI
+ * Public, tenant-scoped Agent channel API authenticated with OPENAPI-HMAC-SHA256-V1. Studio administration endpoints are not part of this contract.
+ *
+ * The version of the OpenAPI document: 0.1.2
+ *
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import * as runtime from '../runtime';
+/**
+ *
+ */
+export class WorkspaceApi extends runtime.BaseAPI {
+    /**
+     * Creates request options for getWorkspaceFilePreview without sending the request
+     */
+    getWorkspaceFilePreviewRequestOpts(requestParameters) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (requestParameters['channelId'] == null) {
+                throw new runtime.RequiredError('channelId', 'Required parameter "channelId" was null or undefined when calling getWorkspaceFilePreview().');
+            }
+            if (requestParameters['conversationId'] == null) {
+                throw new runtime.RequiredError('conversationId', 'Required parameter "conversationId" was null or undefined when calling getWorkspaceFilePreview().');
+            }
+            if (requestParameters['path'] == null) {
+                throw new runtime.RequiredError('path', 'Required parameter "path" was null or undefined when calling getWorkspaceFilePreview().');
+            }
+            const queryParameters = {};
+            if (requestParameters['path'] != null) {
+                queryParameters['path'] = requestParameters['path'];
+            }
+            const headerParameters = {};
+            if (this.configuration && this.configuration.apiKey) {
+                headerParameters["X-OpenAPI-User"] = yield this.configuration.apiKey("X-OpenAPI-User"); // OpenApiUser authentication
+            }
+            if (this.configuration && this.configuration.apiKey) {
+                headerParameters["X-OpenAPI-AK"] = yield this.configuration.apiKey("X-OpenAPI-AK"); // OpenApiAccessKey authentication
+            }
+            if (this.configuration && this.configuration.apiKey) {
+                headerParameters["X-OpenAPI-Timestamp"] = yield this.configuration.apiKey("X-OpenAPI-Timestamp"); // OpenApiTimestamp authentication
+            }
+            if (this.configuration && this.configuration.apiKey) {
+                headerParameters["X-OpenAPI-Nonce"] = yield this.configuration.apiKey("X-OpenAPI-Nonce"); // OpenApiNonce authentication
+            }
+            if (this.configuration && this.configuration.apiKey) {
+                headerParameters["X-OpenAPI-Signature"] = yield this.configuration.apiKey("X-OpenAPI-Signature"); // OpenApiSignature authentication
+            }
+            let urlPath = `/api/agents/channel/openapi/v1/{channelId}/chat/conversations/{conversationId}/workspace/files/preview`;
+            urlPath = urlPath.replace('{channelId}', encodeURIComponent(String(requestParameters['channelId'])));
+            urlPath = urlPath.replace('{conversationId}', encodeURIComponent(String(requestParameters['conversationId'])));
+            return {
+                path: urlPath,
+                method: 'GET',
+                headers: headerParameters,
+                query: queryParameters,
+            };
+        });
+    }
+    /**
+     * 创建工作区文件预览地址 / Create a workspace file preview URL 请求会在身份验签和资源归属校验后执行；响应字段以本契约为准。 / The request runs after signature and resource-ownership validation; this contract defines the response fields.
+     * 创建工作区文件预览地址 / Create a workspace file preview URL
+     */
+    getWorkspaceFilePreviewRaw(requestParameters, initOverrides) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const requestOptions = yield this.getWorkspaceFilePreviewRequestOpts(requestParameters);
+            const response = yield this.request(requestOptions, initOverrides);
+            return new runtime.JSONApiResponse(response);
+        });
+    }
+    /**
+     * 创建工作区文件预览地址 / Create a workspace file preview URL 请求会在身份验签和资源归属校验后执行；响应字段以本契约为准。 / The request runs after signature and resource-ownership validation; this contract defines the response fields.
+     * 创建工作区文件预览地址 / Create a workspace file preview URL
+     */
+    getWorkspaceFilePreview(requestParameters, initOverrides) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const response = yield this.getWorkspaceFilePreviewRaw(requestParameters, initOverrides);
+            return yield response.value();
+        });
+    }
+    /**
+     * Creates request options for listWorkspaceArtifacts without sending the request
+     */
+    listWorkspaceArtifactsRequestOpts(requestParameters) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (requestParameters['channelId'] == null) {
+                throw new runtime.RequiredError('channelId', 'Required parameter "channelId" was null or undefined when calling listWorkspaceArtifacts().');
+            }
+            if (requestParameters['conversationId'] == null) {
+                throw new runtime.RequiredError('conversationId', 'Required parameter "conversationId" was null or undefined when calling listWorkspaceArtifacts().');
+            }
+            const queryParameters = {};
+            if (requestParameters['current'] != null) {
+                queryParameters['current'] = requestParameters['current'];
+            }
+            if (requestParameters['size'] != null) {
+                queryParameters['size'] = requestParameters['size'];
+            }
+            if (requestParameters['orderBy'] != null) {
+                queryParameters['orderBy'] = requestParameters['orderBy'];
+            }
+            if (requestParameters['orderDirection'] != null) {
+                queryParameters['orderDirection'] = requestParameters['orderDirection'];
+            }
+            if (requestParameters['orderNullHandling'] != null) {
+                queryParameters['orderNullHandling'] = requestParameters['orderNullHandling'];
+            }
+            if (requestParameters['keyword'] != null) {
+                queryParameters['keyword'] = requestParameters['keyword'];
+            }
+            if (requestParameters['prefix'] != null) {
+                queryParameters['prefix'] = requestParameters['prefix'];
+            }
+            const headerParameters = {};
+            if (this.configuration && this.configuration.apiKey) {
+                headerParameters["X-OpenAPI-User"] = yield this.configuration.apiKey("X-OpenAPI-User"); // OpenApiUser authentication
+            }
+            if (this.configuration && this.configuration.apiKey) {
+                headerParameters["X-OpenAPI-AK"] = yield this.configuration.apiKey("X-OpenAPI-AK"); // OpenApiAccessKey authentication
+            }
+            if (this.configuration && this.configuration.apiKey) {
+                headerParameters["X-OpenAPI-Timestamp"] = yield this.configuration.apiKey("X-OpenAPI-Timestamp"); // OpenApiTimestamp authentication
+            }
+            if (this.configuration && this.configuration.apiKey) {
+                headerParameters["X-OpenAPI-Nonce"] = yield this.configuration.apiKey("X-OpenAPI-Nonce"); // OpenApiNonce authentication
+            }
+            if (this.configuration && this.configuration.apiKey) {
+                headerParameters["X-OpenAPI-Signature"] = yield this.configuration.apiKey("X-OpenAPI-Signature"); // OpenApiSignature authentication
+            }
+            let urlPath = `/api/agents/channel/openapi/v1/{channelId}/chat/conversations/{conversationId}/workspace/files`;
+            urlPath = urlPath.replace('{channelId}', encodeURIComponent(String(requestParameters['channelId'])));
+            urlPath = urlPath.replace('{conversationId}', encodeURIComponent(String(requestParameters['conversationId'])));
+            return {
+                path: urlPath,
+                method: 'GET',
+                headers: headerParameters,
+                query: queryParameters,
+            };
+        });
+    }
+    /**
+     * 分页查询工作区制品 / List workspace artifacts 请求会在身份验签和资源归属校验后执行；响应字段以本契约为准。 / The request runs after signature and resource-ownership validation; this contract defines the response fields.
+     * 分页查询工作区制品 / List workspace artifacts
+     */
+    listWorkspaceArtifactsRaw(requestParameters, initOverrides) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const requestOptions = yield this.listWorkspaceArtifactsRequestOpts(requestParameters);
+            const response = yield this.request(requestOptions, initOverrides);
+            return new runtime.JSONApiResponse(response);
+        });
+    }
+    /**
+     * 分页查询工作区制品 / List workspace artifacts 请求会在身份验签和资源归属校验后执行；响应字段以本契约为准。 / The request runs after signature and resource-ownership validation; this contract defines the response fields.
+     * 分页查询工作区制品 / List workspace artifacts
+     */
+    listWorkspaceArtifacts(requestParameters, initOverrides) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const response = yield this.listWorkspaceArtifactsRaw(requestParameters, initOverrides);
+            return yield response.value();
+        });
+    }
+}
+/**
+ * @export
+ */
+export const ListWorkspaceArtifactsOrderDirectionEnum = {
+    Asc: 'ASC',
+    Desc: 'DESC',
+};
+/**
+ * @export
+ */
+export const ListWorkspaceArtifactsOrderNullHandlingEnum = {
+    Native: 'NATIVE',
+    NullsFirst: 'NULLS_FIRST',
+    NullsLast: 'NULLS_LAST',
+};

package/dist/esm/apis/index.d.ts

@@ -0,0 +1,10 @@
+export * from './ChatApi';
+export * from './ConfigurationApi';
+export * from './ConversationsApi';
+export * from './EventsApi';
+export * from './FilesApi';
+export * from './InteractionsApi';
+export * from './KnowledgeApi';
+export * from './MessagesApi';
+export * from './SQLApi';
+export * from './WorkspaceApi';

package/dist/esm/apis/index.js

@@ -0,0 +1,12 @@
+/* tslint:disable */
+/* eslint-disable */
+export * from './ChatApi';
+export * from './ConfigurationApi';
+export * from './ConversationsApi';
+export * from './EventsApi';
+export * from './FilesApi';
+export * from './InteractionsApi';
+export * from './KnowledgeApi';
+export * from './MessagesApi';
+export * from './SQLApi';
+export * from './WorkspaceApi';

package/dist/esm/client.d.ts

@@ -0,0 +1,116 @@
+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';
+/**
+ * Lingya Agents SDK 入口，仅适用于可信服务端。 / Server-side Lingya Agents SDK entry point.
+ *
+ * 客户端保存 channel 范围的凭证，但只有 [forUser] 创建的用户客户端可以发起请求。
+ */
+export declare class LingyaAgentsClient {
+    private readonly baseUrl;
+    readonly channelId: string;
+    private readonly credentials;
+    /**
+     * 创建 channel 范围的客户端。 / Creates a channel-scoped client.
+     *
+     * @param baseUrl - 服务根地址，不包含 `/api/.../chat`。 / Service root without the API path.
+     * @param channelId - OpenAPI channel ID，不得为空。 / Non-empty OpenAPI channel ID.
+     * @param credentials - 仅保存在当前服务端进程中的 HMAC 凭证。 / HMAC credentials kept in this server process.
+     */
+    constructor(baseUrl: string, channelId: string, credentials: OpenApiCredentials);
+    /**
+     * 绑定外部用户身份；后续所有请求都以该身份独立签名。 / Binds one external user to all subsequent signed calls.
+     *
+     * @param externalUserId - 调用方系统的稳定用户 ID，UTF-8 编码后为 1..256 字节且不能含 NUL。
+     * @returns 注入用户身份并可调用全部契约 API 的客户端。
+     */
+    forUser(externalUserId: string): LingyaAgentsUserClient;
+}
+/** 已绑定外部用户的强类型 API 集合。 / Strongly typed API collection bound to one external user. */
+export declare class LingyaAgentsUserClient {
+    readonly channelId: string;
+    private readonly signedFetch;
+    private readonly baseUrl;
+    /** 发起新聊天和流探针。 / Starts chats and stream probes. */
+    readonly chat: ChatApi;
+    /** 读取 Agent 与会话配置。 / Reads Agent and conversation configuration. */
+    readonly configuration: ConfigurationApi;
+    /** 管理会话、状态、分享和异步任务。 / Manages conversations, status, shares, and async tasks. */
+    readonly conversations: ConversationsApi;
+    /** 查询已持久化事件。 / Reads persisted events. */
+    readonly events: EventsApi;
+    /** 管理附件与预签名 URL。 / Manages attachments and pre-signed URLs. */
+    readonly files: FilesApi;
+    /** 回答用户问题并处理计划审批。 / Handles user answers and plan approval. */
+    readonly interactions: InteractionsApi;
+    /** 查询引用元数据。 / Reads citation metadata. */
+    readonly knowledge: KnowledgeApi;
+    /** 查询消息并控制排队消息。 / Reads messages and controls queued messages. */
+    readonly messages: MessagesApi;
+    /** 查询、导出 SQL 结果与图表数据。 / Reads and exports SQL results and chart data. */
+    readonly sql: SQLApi;
+    /** 查询工作区文件及预览。 / Reads workspace files and previews. */
+    readonly workspace: WorkspaceApi;
+    constructor(channelId: string, configuration: Configuration, signedFetch: typeof fetch, baseUrl: string);
+    /**
+     * 调用契约端点并按指定类型返回 JSON；优先使用上方生成的强类型 API。 / Calls a contract endpoint and decodes typed JSON.
+     *
+     * @param method - 大写 HTTP method。
+     * @param suffix - 相对于 channel chat 根路径的已编码路径。
+     * @param bodyJson - 最终发送并参与签名的 UTF-8 JSON 字符串；无请求体时省略。
+     * @param query - 已按最终顺序组装的查询参数，允许重复键。
+     * @returns 调用方指定的响应类型。
+     * @throws [LingyaApiError] 当服务端返回非 2xx 状态。
+     */
+    request<T>(method: string, suffix: string, bodyJson?: string, query?: URLSearchParams): Promise<T>;
+    /**
+     * 调用无响应正文的契约端点。 / Calls a contract endpoint that has no response body.
+     *
+     * @param method - 大写 HTTP method。
+     * @param suffix - 相对于 channel chat 根路径的已编码路径。
+     * @param bodyJson - 最终发送并参与签名的 UTF-8 JSON 字符串。
+     * @param query - 保留顺序的查询参数。
+     * @returns 2xx HTTP 状态码。
+     */
+    requestStatus(method: string, suffix: string, bodyJson?: string, query?: URLSearchParams): Promise<number>;
+    /**
+     * 下载二进制响应，返回精确响应字节。 / Downloads an exact binary response.
+     *
+     * @param method - HTTP method，通常为 `GET`。
+     * @param suffix - 已编码的相对路径。
+     * @param query - 保留顺序的查询参数。
+     * @returns 未经文本转换的响应字节。
+     */
+    requestBinary(method: string, suffix: string, query?: URLSearchParams): Promise<Uint8Array>;
+    /**
+     * 订阅对话 SSE，事件按契约判别联合返回。 / Streams SSE as the contract discriminated union.
+     *
+     * @param conversationId - 要订阅的会话 ID。
+     * @param messageId - 触发本次生成的消息 ID。
+     * @returns 支持取消的异步事件序列；未知 type 保留 `rawJson`。
+     */
+    streamChatEvents(conversationId: string, messageId: string): AsyncGenerator<LingyaAiChatBriefEvent>;
+    /**
+     * 发送底层受控请求；调用前固定最终 path、query、Content-Type 与 body 字节。 / Sends an exactly signed low-level request.
+     *
+     * 每次调用重新生成 timestamp 与 nonce，不对写请求自动重试。
+     *
+     * @param method - HTTP method。
+     * @param suffix - 已完成路径转义的相对路径；本方法不会二次编码。
+     * @param bodyJson - 最终 JSON 字符串，最大 2 MiB；省略时 Content-Type 为空。
+     * @param query - 最终查询参数；顺序和重复键均参与签名。
+     * @param accept - 精确的 Accept 值，例如 `application/json`、`text/event-stream` 或 `text/csv`。
+     * @returns 成功的原始 Fetch Response。
+     * @throws [LingyaApiError] 当服务端返回非 2xx 状态。
+     */
+    rawRequest(method: string, suffix: string, bodyJson?: string, query?: URLSearchParams, accept?: string): Promise<Response>;
+}
+/** 不含凭证的 HTTP 错误。 / HTTP failure that never includes credentials. */
+export declare class LingyaApiError extends Error {
+    readonly method: string;
+    readonly path: string;
+    readonly status: number;
+    readonly responseBody: string;
+    constructor(method: string, path: string, status: number, responseBody: string);
+}

package/dist/esm/client.js

@@ -0,0 +1,195 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        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]); }
+};
+import { Configuration } from './runtime';
+import { ChatApi, ConfigurationApi, ConversationsApi, EventsApi, FilesApi, InteractionsApi, KnowledgeApi, MessagesApi, SQLApi, WorkspaceApi } from './apis';
+import { createSignedFetch } from './hmac';
+import { decodeSse } from './sse';
+import { decodeAiChatBriefEvent } from './events';
+/**
+ * Lingya Agents SDK 入口，仅适用于可信服务端。 / Server-side Lingya Agents SDK entry point.
+ *
+ * 客户端保存 channel 范围的凭证，但只有 [forUser] 创建的用户客户端可以发起请求。
+ */
+export class LingyaAgentsClient {
+    /**
+     * 创建 channel 范围的客户端。 / Creates a channel-scoped client.
+     *
+     * @param baseUrl - 服务根地址，不包含 `/api/.../chat`。 / Service root without the API path.
+     * @param channelId - OpenAPI channel ID，不得为空。 / Non-empty OpenAPI channel ID.
+     * @param credentials - 仅保存在当前服务端进程中的 HMAC 凭证。 / HMAC credentials kept in this server process.
+     */
+    constructor(baseUrl, channelId, credentials) {
+        this.baseUrl = baseUrl;
+        this.channelId = channelId;
+        this.credentials = credentials;
+        if (channelId.length === 0)
+            throw new Error('channelId must not be empty');
+    }
+    /**
+     * 绑定外部用户身份；后续所有请求都以该身份独立签名。 / Binds one external user to all subsequent signed calls.
+     *
+     * @param externalUserId - 调用方系统的稳定用户 ID，UTF-8 编码后为 1..256 字节且不能含 NUL。
+     * @returns 注入用户身份并可调用全部契约 API 的客户端。
+     */
+    forUser(externalUserId) {
+        const signedFetch = createSignedFetch(this.credentials, externalUserId);
+        const configuration = new Configuration({ basePath: this.baseUrl.replace(/\/+$/, ''), fetchApi: signedFetch });
+        return new LingyaAgentsUserClient(this.channelId, configuration, signedFetch, this.baseUrl);
+    }
+}
+/** 已绑定外部用户的强类型 API 集合。 / Strongly typed API collection bound to one external user. */
+export class LingyaAgentsUserClient {
+    constructor(channelId, configuration, signedFetch, baseUrl) {
+        this.channelId = channelId;
+        this.signedFetch = signedFetch;
+        this.baseUrl = baseUrl;
+        this.chat = new ChatApi(configuration);
+        this.configuration = new ConfigurationApi(configuration);
+        this.conversations = new ConversationsApi(configuration);
+        this.events = new EventsApi(configuration);
+        this.files = new FilesApi(configuration);
+        this.interactions = new InteractionsApi(configuration);
+        this.knowledge = new KnowledgeApi(configuration);
+        this.messages = new MessagesApi(configuration);
+        this.sql = new SQLApi(configuration);
+        this.workspace = new WorkspaceApi(configuration);
+    }
+    /**
+     * 调用契约端点并按指定类型返回 JSON；优先使用上方生成的强类型 API。 / Calls a contract endpoint and decodes typed JSON.
+     *
+     * @param method - 大写 HTTP method。
+     * @param suffix - 相对于 channel chat 根路径的已编码路径。
+     * @param bodyJson - 最终发送并参与签名的 UTF-8 JSON 字符串；无请求体时省略。
+     * @param query - 已按最终顺序组装的查询参数，允许重复键。
+     * @returns 调用方指定的响应类型。
+     * @throws [LingyaApiError] 当服务端返回非 2xx 状态。
+     */
+    request(method, suffix, bodyJson, query) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const response = yield this.rawRequest(method, suffix, bodyJson, query, 'application/json');
+            return yield response.json();
+        });
+    }
+    /**
+     * 调用无响应正文的契约端点。 / Calls a contract endpoint that has no response body.
+     *
+     * @param method - 大写 HTTP method。
+     * @param suffix - 相对于 channel chat 根路径的已编码路径。
+     * @param bodyJson - 最终发送并参与签名的 UTF-8 JSON 字符串。
+     * @param query - 保留顺序的查询参数。
+     * @returns 2xx HTTP 状态码。
+     */
+    requestStatus(method, suffix, bodyJson, query) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return (yield this.rawRequest(method, suffix, bodyJson, query, 'application/json')).status;
+        });
+    }
+    /**
+     * 下载二进制响应，返回精确响应字节。 / Downloads an exact binary response.
+     *
+     * @param method - HTTP method，通常为 `GET`。
+     * @param suffix - 已编码的相对路径。
+     * @param query - 保留顺序的查询参数。
+     * @returns 未经文本转换的响应字节。
+     */
+    requestBinary(method, suffix, query) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const response = yield this.rawRequest(method, suffix, undefined, query, 'application/octet-stream');
+            return new Uint8Array(yield response.arrayBuffer());
+        });
+    }
+    /**
+     * 订阅对话 SSE，事件按契约判别联合返回。 / Streams SSE as the contract discriminated union.
+     *
+     * @param conversationId - 要订阅的会话 ID。
+     * @param messageId - 触发本次生成的消息 ID。
+     * @returns 支持取消的异步事件序列；未知 type 保留 `rawJson`。
+     */
+    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(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(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; }
+            }
+        });
+    }
+    /**
+     * 发送底层受控请求；调用前固定最终 path、query、Content-Type 与 body 字节。 / Sends an exactly signed low-level request.
+     *
+     * 每次调用重新生成 timestamp 与 nonce，不对写请求自动重试。
+     *
+     * @param method - HTTP method。
+     * @param suffix - 已完成路径转义的相对路径；本方法不会二次编码。
+     * @param bodyJson - 最终 JSON 字符串，最大 2 MiB；省略时 Content-Type 为空。
+     * @param query - 最终查询参数；顺序和重复键均参与签名。
+     * @param accept - 精确的 Accept 值，例如 `application/json`、`text/event-stream` 或 `text/csv`。
+     * @returns 成功的原始 Fetch Response。
+     * @throws [LingyaApiError] 当服务端返回非 2xx 状态。
+     */
+    rawRequest(method_1, suffix_1, bodyJson_1, query_1) {
+        return __awaiter(this, arguments, void 0, function* (method, suffix, bodyJson, query, accept = 'application/json') {
+            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' })),
+                body: bodyJson,
+            });
+            if (!response.ok)
+                throw new LingyaApiError(method, suffix, response.status, yield response.text());
+            return response;
+        });
+    }
+}
+/** 不含凭证的 HTTP 错误。 / HTTP failure that never includes credentials. */
+export class LingyaApiError 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';
+    }
+}

package/dist/esm/events.d.ts

@@ -0,0 +1,21 @@
+import type { AiChatBriefEvent, ToolExtension, UnknownAiChatBriefEvent, UnknownToolExtension } from './models';
+/** 包含全部已知事件以及携带原始 JSON 的未知事件。 / All known events plus a raw-JSON fallback for future event types. */
+export type LingyaAiChatBriefEvent = AiChatBriefEvent | UnknownAiChatBriefEvent;
+/** 包含全部已知工具扩展以及携带原始 JSON 的未知扩展。 / All known tool extensions plus a raw-JSON fallback. */
+export type LingyaToolExtension = ToolExtension | UnknownToolExtension;
+/**
+ * 按 type 判别事件；未知值只暴露 type 与 rawJson。 / Decodes by type with an exact JSON fallback.
+ *
+ * @param rawJson - 一个完整 SSE data 对象的原始 JSON。
+ * @returns 已知事件联合，或保存输入原文的未知事件。
+ * @throws SyntaxError 当输入不是有效 JSON。
+ */
+export declare function decodeAiChatBriefEvent(rawJson: string): LingyaAiChatBriefEvent;
+/**
+ * 按 category 判别工具扩展。 / Decodes a tool extension by category.
+ *
+ * @param rawJson - 一个完整工具扩展对象的原始 JSON。
+ * @returns 12 种已知扩展之一，或保存输入原文的未知扩展。
+ * @throws SyntaxError 当输入不是有效 JSON。
+ */
+export declare function decodeToolExtension(rawJson: string): LingyaToolExtension;

package/dist/esm/events.js

@@ -0,0 +1,33 @@
+const knownEventTypes = new Set([
+    'user-query', 'compressor-context-start', 'compressor-context-end', 'compactor-warning', 'manual-interrupt',
+    'error', 'start', 'think', 'chat-client-request', 'chat-client-response', 'message', 'tool-execution',
+    'tool-execution-sub-agent-call', 'tool-execution-awaiting-user-input', 'end',
+]);
+const knownToolCategories = new Set([
+    'planApproval', 'askUserQuestion', 'imageGeneration', 'sqlQuery', 'sqlQueryResult', 'sqlChartResult',
+    'mathFormula', 'mathResult', 'jsRunScript', 'jsRunScriptResult', 'skillResource', 'taskProgress',
+]);
+/**
+ * 按 type 判别事件；未知值只暴露 type 与 rawJson。 / Decodes by type with an exact JSON fallback.
+ *
+ * @param rawJson - 一个完整 SSE data 对象的原始 JSON。
+ * @returns 已知事件联合，或保存输入原文的未知事件。
+ * @throws SyntaxError 当输入不是有效 JSON。
+ */
+export function decodeAiChatBriefEvent(rawJson) {
+    const parsed = JSON.parse(rawJson);
+    const type = typeof parsed.type === 'string' ? parsed.type : 'unknown';
+    return knownEventTypes.has(type) ? parsed : { type, rawJson };
+}
+/**
+ * 按 category 判别工具扩展。 / Decodes a tool extension by category.
+ *
+ * @param rawJson - 一个完整工具扩展对象的原始 JSON。
+ * @returns 12 种已知扩展之一，或保存输入原文的未知扩展。
+ * @throws SyntaxError 当输入不是有效 JSON。
+ */
+export function decodeToolExtension(rawJson) {
+    const parsed = JSON.parse(rawJson);
+    const category = typeof parsed.category === 'string' ? parsed.category : 'unknown';
+    return knownToolCategories.has(category) ? parsed : { category, rawJson };
+}

package/dist/esm/hmac.d.ts

@@ -0,0 +1,25 @@
+/** 服务端 OpenAPI 凭证。Secret 不会被发送或写入异常。 / Trusted-server credentials; the secret is never transmitted. */
+export interface OpenApiCredentials {
+    /** 访问密钥标识。 / Access-key identifier. */
+    accessKey: string;
+    /** HMAC 密钥。 / HMAC secret. */
+    secretKey: string;
+}
+/**
+ * 构造已签名 fetch；每次调用都会重新生成 timestamp、nonce 和签名。 / Creates a fetch that signs every attempt independently.
+ *
+ * 签名在 Fetch Request 完全确定后计算，避免 URL 或 body 在签名后再次编码。
+ *
+ * @param credentials - channel 的访问密钥与 HMAC secret。
+ * @param externalUserId - UTF-8 编码后为 1..256 字节且不含 NUL 的外部用户 ID。
+ * @returns 与原生 fetch 兼容的签名 transport。
+ */
+export declare function createSignedFetch(credentials: OpenApiCredentials, externalUserId: string): typeof fetch;
+/**
+ * 对固定 canonical string 计算 HMAC。 / Computes HMAC for a fixed canonical string.
+ *
+ * @param secretKey - HMAC-SHA256 secret。
+ * @param canonical - 已按协议顺序拼接的规范字符串。
+ * @returns 小写十六进制签名。
+ */
+export declare function signCanonical(secretKey: string, canonical: string): string;