@huace-aigc/aigc-maas-client 0.1.0 → 0.1.1

package/README.md

@@ -1,10 +1,7 @@
 # Huace AIGC MaaS Node.js SDK
 
-Node.js 客户端用于接入 new-api MaaS 托管 Key 能力，支持申请或复用托管 Key、查询 Key
-元信息和查询用量。
-
-调用方或 Agent 请先阅读 [`SKILL.md`](SKILL.md)；公共 HTTP 契约见
-[`../openapi/maas.yaml`](../openapi/maas.yaml)。
+Node.js 客户端用于接入 Huace AIGC MaaS 托管 Key 能力，支持申请或复用托管 Key、查询
+Key 元信息和查询用量。本文档随 npm 包一起发布，可直接作为接入指南。
 
 ## 安装
 
@@ -12,27 +9,89 @@ Node.js 客户端用于接入 new-api MaaS 托管 Key 能力，支持申请或
 npm install @huace-aigc/aigc-maas-client
 ```
 
-## 使用
+## 前置条件
+
+- Node.js 18 或更高版本。
+- `baseUrl` 是 MaaS 服务地址，必须包含协议和主机名。
+- `appId` 是已在 AIGC Auth 注册的正整数应用 ID，使用字符串传入。
+- 服务端应用已启用，并且该应用恰好只有一个启用的 MaaS 路由。
+- 用户的服务端人员映射已确认，否则会返回 `MAPPING_REVIEW_PENDING`。
+
+## 快速开始
 
 ```js
-import { MaaSClient } from "@huace-aigc/aigc-maas-client";
+import { APIError, MaaSClient } from "@huace-aigc/aigc-maas-client";
+
+const userToken = process.env.AIGC_AUTH_USER_TOKEN;
+if (!userToken) {
+  throw new Error("AIGC_AUTH_USER_TOKEN is required");
+}
 
 const client = new MaaSClient({
   baseUrl: "https://maas.example.com",
-  appId: "12", // Numeric AIGC Auth application ID.
+  appId: "12",
 });
-const ensured = await client.ensureKey({ userToken: "auth-user-token" });
-const key = ensured.credential.apiKey;
-const info = await client.getKeyInfo(key);
-const usage = await client.getUsage(key);
+
+try {
+  const ensured = await client.ensureKey({
+    userToken,
+    idempotencyKey: "user-42-provision-v1",
+  });
+  const apiKey = ensured.credential.apiKey;
+
+  const info = await client.getKeyInfo(apiKey);
+  const usage = await client.getUsage(apiKey);
+  console.log({ keyId: info.id, requestCount: usage.summary.count });
+
+  // 模型请求使用 ensured.credential.baseUrl + "/v1/chat/completions"，
+  // 并设置 Authorization: Bearer <apiKey>。SDK 不代替模型协议客户端。
+} catch (error) {
+  if (error instanceof APIError) {
+    console.error({ status: error.statusCode, code: error.code, message: error.message });
+  }
+  throw error;
+}
 ```
 
-`userToken` 只在申请时传入，Client 不保存用户 Token。未提供幂等键时，SDK 会自动
-生成 UUID，并在内部重试中复用。API Key 是敏感凭证，请通过 HTTPS 传输并避免写入
-日志。Key 信息查询接口不会返回明文 Key。
+`ensureKey` 返回 `state`、用户和应用信息，以及 `credential.apiKey`、
+`credential.baseUrl`、`credential.models`。同一应用和用户会复用同一个托管 Key；未提供
+`idempotencyKey` 时，SDK 自动生成 UUID，并在重试中复用。
+
+## 接口
+
+SDK 对应以下 MaaS HTTP 接口：
+
+- `POST /api/integrations/v1/keys/ensure`：使用 AIGC Auth 用户 Token 申请或复用托管 Key。
+- `GET /api/integrations/v1/self/key`：使用托管 API Key 查询 Key 状态、模型、额度和归属。
+- `GET /api/integrations/v1/self/usage`：使用托管 API Key 查询汇总及按模型用量。
 
-## 配置
+申请请求会发送 `Authorization: Bearer <userToken>`、`X-AIGC-Auth-App-Id: <appId>` 和
+`Idempotency-Key`。查询请求只发送 `Authorization: Bearer <apiKey>`。
+
+## 查询用量
+
+可以通过时间戳限制查询范围；不传字段时不会发送对应查询参数。返回值会规范化为
+camelCase：
+
+```js
+const usage = await client.getUsage(apiKey, {
+  startTimestamp: 1720000000,
+  endTimestamp: 1720086400,
+});
+
+console.log(usage.period.startTimestamp, usage.models);
+```
+
+## 配置和重试
 
 - `baseUrl` 和 `appId` 必填。
-- 默认请求超时为 10 秒，默认最多重试 2 次。
+- 默认请求超时为 10 秒，可通过 `timeout` 配置。
+- 默认最多重试 2 次，可通过 `maxRetries` 配置。
 - 仅网络错误、429 和 5xx 会自动重试，4xx 错误直接抛出 `APIError`。
+- 可通过 `retryBaseDelay` 配置重试基础延迟，单位为毫秒。
+
+## 安全边界
+
+- `userToken` 只传给 `ensureKey`，Client 不保存用户 Token。
+- API Key 是敏感凭证，必须通过 HTTPS 传输并安全存储，禁止写入日志、URL、指标或错误上报。
+- 不要向请求传递来源应用 Secret，也不要让浏览器直接持有托管 API Key。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huace-aigc/aigc-maas-client",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Node.js client for the new-api MaaS managed-key API",
   "type": "module",
   "main": "src/index.js",
@@ -17,6 +17,6 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node --test test/client.test.js"
+    "test": "node --test test/*.test.js"
   }
 }