@huace-aigc/aigc-maas-client 0.1.0

package/README.md

@@ -0,0 +1,38 @@
+# 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)。
+
+## 安装
+
+```bash
+npm install @huace-aigc/aigc-maas-client
+```
+
+## 使用
+
+```js
+import { MaaSClient } from "@huace-aigc/aigc-maas-client";
+
+const client = new MaaSClient({
+  baseUrl: "https://maas.example.com",
+  appId: "12", // Numeric AIGC Auth application ID.
+});
+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);
+```
+
+`userToken` 只在申请时传入，Client 不保存用户 Token。未提供幂等键时，SDK 会自动
+生成 UUID，并在内部重试中复用。API Key 是敏感凭证，请通过 HTTPS 传输并避免写入
+日志。Key 信息查询接口不会返回明文 Key。
+
+## 配置
+
+- `baseUrl` 和 `appId` 必填。
+- 默认请求超时为 10 秒，默认最多重试 2 次。
+- 仅网络错误、429 和 5xx 会自动重试，4xx 错误直接抛出 `APIError`。

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@huace-aigc/aigc-maas-client",
+  "version": "0.1.0",
+  "description": "Node.js client for the new-api MaaS managed-key API",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": ".",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/client.test.js"
+  }
+}

package/src/index.js

@@ -0,0 +1,182 @@
+import { randomUUID } from "node:crypto";
+
+class ResponseDecodeError extends Error {}
+
+export class APIError extends Error {
+  constructor(statusCode, code, message) {
+    super(`maas: request failed with status ${statusCode} (${code}): ${message}`);
+    this.name = "APIError";
+    this.statusCode = statusCode;
+    this.code = code;
+    this.message = message;
+  }
+}
+
+export class MaaSClient {
+  constructor({ baseUrl, appId, timeout = 10000, maxRetries = 2, retryBaseDelay = 100, fetchImpl = globalThis.fetch } = {}) {
+    if (typeof baseUrl !== "string" || !baseUrl.trim()) {
+      throw new TypeError("baseUrl is required");
+    }
+    const parsed = new URL(baseUrl.trim());
+    if (!parsed.protocol || !parsed.host) {
+      throw new TypeError("baseUrl must include scheme and host");
+    }
+    if (typeof appId !== "string" || !/^\d+$/.test(appId.trim())) {
+      throw new TypeError("appId must be a positive integer");
+    }
+    const normalizedAppId = BigInt(appId.trim());
+    if (normalizedAppId <= 0n || normalizedAppId > 9223372036854775807n) {
+      throw new TypeError("appId must be a positive integer");
+    }
+    if (timeout < 0 || maxRetries < 0 || retryBaseDelay < 0) {
+      throw new TypeError("timeout, retries and retry delay cannot be negative");
+    }
+    if (typeof fetchImpl !== "function") {
+      throw new TypeError("fetch is unavailable");
+    }
+    this.baseUrl = baseUrl.trim().replace(/\/+$/, "");
+    this.appId = normalizedAppId.toString();
+    this.timeout = timeout;
+    this.maxRetries = maxRetries;
+    this.retryBaseDelay = retryBaseDelay;
+    this.fetchImpl = fetchImpl;
+  }
+
+  async ensureKey({ userToken, idempotencyKey } = {}) {
+    if (typeof userToken !== "string" || !userToken.trim()) {
+      throw new TypeError("userToken is required");
+    }
+    const key = typeof idempotencyKey === "string" && idempotencyKey.trim() ? idempotencyKey.trim() : randomUUID();
+    const body = await this.#request("POST", "/api/integrations/v1/keys/ensure", userToken, {
+      "X-AIGC-Auth-App-Id": this.appId,
+      "Idempotency-Key": key,
+      "Content-Type": "application/json",
+    }, "{}");
+    return body.data;
+  }
+
+  async getKeyInfo(apiKey) {
+    const body = await this.#request("GET", "/api/integrations/v1/self/key", apiKey);
+    return body.data;
+  }
+
+  async getUsage(apiKey, { startTimestamp, endTimestamp } = {}) {
+    const params = new URLSearchParams();
+    if (startTimestamp !== undefined && startTimestamp !== null) {
+      params.set("start_timestamp", String(startTimestamp));
+    }
+    if (endTimestamp !== undefined && endTimestamp !== null) {
+      params.set("end_timestamp", String(endTimestamp));
+    }
+    const query = params.toString();
+    const path = `/api/integrations/v1/self/usage${query ? `?${query}` : ""}`;
+    const body = await this.#request("GET", path, apiKey);
+    return normalizeUsage(body.data);
+  }
+
+  async #request(method, path, credential, extraHeaders = {}, body) {
+    if (typeof credential !== "string" || !credential.trim()) {
+      throw new TypeError("credential is required");
+    }
+    for (let attempt = 0; attempt <= this.maxRetries; attempt += 1) {
+      const controller = new AbortController();
+      const timer = this.timeout > 0 ? setTimeout(() => controller.abort(), this.timeout) : null;
+      try {
+        const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+          method,
+          headers: { Authorization: bearerHeader(credential), ...extraHeaders },
+          body,
+          signal: controller.signal,
+        });
+        const text = await response.text();
+        if (response.ok) {
+          try {
+            return JSON.parse(text);
+          } catch (error) {
+            throw new ResponseDecodeError(`decode MaaS response: ${error.message}`);
+          }
+        }
+        const apiError = decodeAPIError(response.status, text);
+        if (attempt < this.maxRetries && retryableStatus(response.status)) {
+          await this.#wait(attempt);
+          continue;
+        }
+        throw apiError;
+      } catch (error) {
+        if (error instanceof APIError || error instanceof ResponseDecodeError) {
+          throw error;
+        }
+        if (attempt < this.maxRetries) {
+          await this.#wait(attempt);
+          continue;
+        }
+        throw error;
+      } finally {
+        if (timer) {
+          clearTimeout(timer);
+        }
+      }
+    }
+    throw new Error("maas: retry loop exhausted");
+  }
+
+  async #wait(attempt) {
+    const delay = this.retryBaseDelay * (2 ** attempt);
+    if (delay > 0) {
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+}
+
+function bearerHeader(value) {
+  const trimmed = value.trim();
+  if (trimmed.toLowerCase().startsWith("bearer ")) {
+    return `Bearer ${trimmed.slice(7).trim()}`;
+  }
+  return `Bearer ${trimmed}`;
+}
+
+function retryableStatus(status) {
+  return status === 429 || status >= 500;
+}
+
+function decodeAPIError(status, text) {
+  let code = `HTTP_${status}`;
+  let message = `HTTP status ${status}`;
+  try {
+    const error = JSON.parse(text).error || {};
+    code = error.code || code;
+    message = error.message || message;
+  } catch {
+    // Keep the HTTP fallback when the server did not return JSON.
+  }
+  return new APIError(status, code, message);
+}
+
+function normalizeUsage(data = {}) {
+  return {
+    ...data,
+    period: {
+      startTimestamp: data.period?.start_timestamp ?? 0,
+      endTimestamp: data.period?.end_timestamp ?? 0,
+    },
+    remainQuota: data.remain_quota ?? 0,
+    summary: normalizeMetrics(data.summary),
+    models: (data.models ?? []).map((model) => ({
+      ...model,
+      modelName: model.model_name ?? "",
+      ...normalizeMetrics(model),
+    })),
+  };
+}
+
+function normalizeMetrics(metrics = {}) {
+  return {
+    quota: metrics.quota ?? 0,
+    count: metrics.count ?? 0,
+    tokenUsed: metrics.token_used ?? 0,
+    promptTokens: metrics.prompt_tokens ?? 0,
+    completionTokens: metrics.completion_tokens ?? 0,
+    cacheTokens: metrics.cache_tokens ?? 0,
+  };
+}