@acosmi/sdk-ts 1.4.1 → 1.5.0

package/examples/auth-oauth-flow.ts

@@ -0,0 +1,97 @@
+// examples/auth-oauth-flow.ts — 手动 OAuth 2.1 PKCE 流程示例（CLI / 自定义流程）。
+//
+// 演示：
+//   1. discover  — 拉取 OAuth Authorization Server 元数据 (RFC 8414)
+//   2. register  — RFC 7591 动态客户端注册
+//   3. authorize — 本地 loopback PKCE 授权 (Node only)，拿 authorization code
+//   4. exchangeCode — 用 code + code_verifier 换 token
+//   5. newTokenSet + TokenStore — 持久化 token，后续复用
+//   6. refreshToken — 用 refresh_token 续期
+//
+// 说明：
+//   - 大多数场景直接用 `client.login(appName, scopes)` 即可（内部封装了下面全部步骤）。
+//     本示例演示底层 helper，适用于需要自定义授权流程 / 自管 token 的 CLI。
+//   - authorize 仅在 Node 环境可用（需要本地 HTTP 回调 server）；浏览器侧应自行实现
+//     popup window + redirect handler。
+
+import {
+  discover,
+  register,
+  authorize,
+  exchangeCode,
+  refreshToken,
+  newTokenSet,
+  tokenSetIsExpired,
+  FileTokenStore,
+  allScopes,
+} from '@acosmi/sdk-ts';
+
+async function main() {
+  const serverURL = process.env.ACOSMI_SERVER_URL;
+  if (!serverURL) {
+    throw new Error('ACOSMI_SERVER_URL is required');
+  }
+  const scopes = allScopes();
+  const store = new FileTokenStore(process.env.ACOSMI_TOKEN_FILE ?? './auth-tokens.json');
+
+  // 0) 已有持久化 token 且未过期 → 直接复用，跳过整个授权流程。
+  const existing = await store.load();
+  if (existing && !tokenSetIsExpired(existing)) {
+    console.log('[token] reusing valid token from store, scope=', existing.scope);
+    return;
+  }
+
+  // 1) discover — OAuth Authorization Server 元数据
+  const meta = await discover(serverURL);
+  console.log('[discover] issuer=', meta.issuer);
+  console.log('[discover] token_endpoint=', meta.token_endpoint);
+
+  // 2) register — 动态注册一个 client，拿到 client_id
+  const reg = await register(meta, 'Auth Flow Example');
+  console.log('[register] client_id=', reg.client_id);
+
+  let tokenSet;
+
+  // 3) refresh-first：store 里有过期 token 但带 refresh_token → 先尝试静默刷新。
+  if (existing && existing.refresh_token) {
+    try {
+      const refreshed = await refreshToken(meta, existing.client_id, existing.refresh_token);
+      tokenSet = newTokenSet(refreshed, existing.client_id, serverURL);
+      console.log('[refresh] token refreshed without re-authorizing');
+    } catch (e) {
+      console.warn('[refresh] failed, falling back to full authorize:',
+        e instanceof Error ? e.message : e);
+    }
+  }
+
+  // 4) 没有可刷新的 token → 走完整 PKCE 授权。
+  if (!tokenSet) {
+    const { result, verifier } = await authorize(meta, reg.client_id, scopes, {
+      handler: (ev) => {
+        if (ev.type === 'auth_url') console.log('[authorize] open in browser:', ev.url);
+        if (ev.type === 'error') console.error('[authorize] error:', ev.err_code, ev.error);
+      },
+    });
+    console.log('[authorize] received authorization code');
+
+    // 5) exchangeCode — code + code_verifier 换 token
+    const tokenResp = await exchangeCode(
+      meta,
+      reg.client_id,
+      result.code,
+      result.redirectURI,
+      verifier,
+    );
+    tokenSet = newTokenSet(tokenResp, reg.client_id, serverURL);
+    console.log('[exchange] access token acquired, scope=', tokenSet.scope);
+  }
+
+  // 6) 持久化 token，供下次启动复用 / Client 直接读取。
+  await store.save(tokenSet);
+  console.log('[store] token persisted; expires_at=', tokenSet.expires_at);
+}
+
+main().catch((err) => {
+  console.error('auth oauth flow example failed:', err);
+  process.exit(1);
+});

package/examples/core-chat.ts

@@ -0,0 +1,85 @@
+// examples/core-chat.ts — Client 基础用法示例（构造 / 配置 / 模型列举 / chat / 流式）。
+//
+// 演示：
+//   1. 构造 Client (serverURL + 可选 FileTokenStore)
+//   2. OAuth 登录 (按业务最小集合申请 scope)
+//   3. 列举托管模型 + 查看配额摘要
+//   4. 同步 chat 调用
+//   5. 流式 chatStreamWithUsage 并聚合 usage / 结算事件
+//
+// 说明：
+//   - SDK 自动按 ManagedModel 的 preferredFormat / supportedFormats 选 Anthropic
+//     或 OpenAI adapter，调用方无需关心。
+//   - 金额 / 余额字段是 string（避免 JS number 精度损失），不要做浮点运算。
+
+import { Client, allScopes, FileTokenStore } from '@acosmi/sdk-ts';
+
+async function main() {
+  const serverURL = process.env.ACOSMI_SERVER_URL;
+  if (!serverURL) {
+    throw new Error('ACOSMI_SERVER_URL is required');
+  }
+
+  // 1) 构造 Client。Client.create 会从 store 异步加载已持久化的 token。
+  //    Node 上不传 store 时默认 ~/.acosmi/tokens.json；这里显式指定一个路径。
+  const client = await Client.create({
+    serverURL,
+    store: new FileTokenStore(process.env.ACOSMI_TOKEN_FILE ?? './core-tokens.json'),
+  });
+
+  // 2) OAuth 登录 — 已有有效 token 时 login 会直接复用，不重复弹浏览器。
+  await client.login('Core Chat Example', allScopes());
+
+  // 3) 列举托管模型 + 配额摘要
+  const models = await client.listModels();
+  console.log('[models]', models.length, 'available');
+  for (const m of models.slice(0, 5)) {
+    console.log('  -', m.modelId, `(provider=${m.provider}, enabled=${m.isEnabled})`);
+  }
+
+  const quota = await client.getQuotaSummary();
+  console.log('[quota] freeTotalEtu=', quota.freeTotalEtu,
+    'paidTotalEtu=', quota.paidTotalEtu);
+
+  // 选一个模型：优先 isDefault，否则取第一个启用的。
+  const model =
+    models.find((m) => m.isDefault && m.isEnabled) ??
+    models.find((m) => m.isEnabled);
+  if (!model) {
+    throw new Error('no enabled model available — 让管理员在网关启用一个模型');
+  }
+  console.log('[selected model]', model.modelId);
+
+  // 4) 同步 chat 调用
+  const resp = await client.chat(model.modelId, {
+    messages: [{ role: 'user', content: '用一句话介绍 TypeScript。' }],
+    max_tokens: 256,
+  });
+  for (const block of resp.content) {
+    if (block.type === 'text' && block.text) {
+      console.log('[chat text]', block.text);
+    }
+  }
+  console.log('[chat usage] input=', resp.usage.input_tokens,
+    'output=', resp.usage.output_tokens);
+
+  // 5) 流式调用 — chatStreamWithUsage 把内容 / sources / 结算事件分流为带标签的迭代项。
+  const stream = client.chatStreamWithUsage(model.modelId, {
+    messages: [{ role: 'user', content: '写一首关于海的两行短诗。' }],
+    max_tokens: 512,
+  });
+  for await (const item of stream) {
+    if (item.kind === 'content' && item.event.event === 'content_block_delta') {
+      process.stdout.write('.'); // 实际项目里在此解析 delta 输出 token
+    } else if (item.kind === 'settle') {
+      console.log('\n[settle] totalTokens=', item.event.totalTokens,
+        'tokenRemaining=', item.event.tokenRemaining);
+    }
+  }
+  console.log('\n[stream] done');
+}
+
+main().catch((err) => {
+  console.error('core chat example failed:', err);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acosmi/sdk-ts",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "Acosmi TypeScript SDK：模型网关、Agent Run Gateway 与 Compliance（电子证据、时间章、报告、签署 envelope）统一客户端，支持浏览器 / Node ≥18 / Deno / Bun。",
   "type": "module",
   "main": "./dist/node/index.cjs",
@@ -51,7 +51,8 @@
     "format": "prettier --write \"src/**/*.{ts,json}\"",
     "typecheck": "tsc --noEmit",
     "test:pack": "node scripts/smoke-pack.mjs",
-    "prepublishOnly": "npm run typecheck && npm run lint && npm test && npm run build && npm run test:pack"
+    "docs": "typedoc",
+    "prepublishOnly": "npm run typecheck && npm run lint && npm test && npm run build && npm run test:pack && npm run docs"
   },
   "engines": {
     "node": ">=18"
@@ -90,6 +91,8 @@
     "eslint": "^8.57.0",
     "prettier": "^3.0.0",
     "tsup": "^8.0.0",
+    "typedoc": "^0.28.19",
+    "typedoc-plugin-markdown": "^4.11.0",
     "typescript": "^5.4.0",
     "vitest": "^1.0.0"
   }