docs(js-sdk): add SDK doc pages + type-drift guard (#106 follow-ups) (#127)

* docs(js-sdk): add SDK doc pages + type-drift guard (#106 follow-ups)

Closes two of the #106 follow-ups:

- Type-drift guard: a vitest test asserts packages/js-sdk/src/types.ts
  stays byte-identical to packages/mcp/src/types.ts (the JS SDK types
  are a maintained copy of the MCP types, which track the OpenAPI
  contract). It fails if the two ever drift, prompting a re-copy. Gated
  by the existing js-sdk-tests CI job.
- Docs: js-sdk.md in all three doc variants (en-US, zh-CN, cn/zh-CN,
  the last with qveris.cn region adaptations), mirroring python-sdk.md;
  a TypeScript SDK section added to getting-started in each variant; the
  new paths registered in the docs-to-website sync workflow.

The third follow-up (Vercel AI SDK adapter) belongs to the framework
adapters issue (#109), not #106.

* docs: fix js-sdk link depth in cn/zh-CN and restore en-US line endings

Review fixes for #127:
- docs/cn/zh-CN/getting-started.md sits one level deeper, so the
  packages/js-sdk link needs ../../../ (matching the sibling python-sdk
  link), not ../../ which resolved to a nonexistent docs/packages/js-sdk.
- Re-applied the en-US TypeScript SDK section preserving the file's
  original line endings, dropping the spurious CRLF churn.

* test(js-sdk): normalize line endings in the types-drift guard

Addresses a review note: comparing the two types.ts files byte-for-byte
could spuriously fail on a Windows checkout where core.autocrlf converts
one file to CRLF. Normalize CRLF->LF before comparing so the guard
tracks type content, not the checkout's line-ending style.

Author: linfangw

.github/workflows/sync-docs-to-website.yml

@@ -36,6 +36,9 @@ on:
       - "docs/en-US/python-sdk.md"
       - "docs/zh-CN/python-sdk.md"
       - "docs/cn/zh-CN/python-sdk.md"
+      - "docs/en-US/js-sdk.md"
+      - "docs/zh-CN/js-sdk.md"
+      - "docs/cn/zh-CN/js-sdk.md"
       - ".github/workflows/sync-docs-to-website.yml"
   workflow_dispatch:
 

docs/cn/zh-CN/getting-started.md

@@ -141,6 +141,32 @@ if __name__ == "__main__":
 
 ---
 
+### 使用 QVeris TypeScript SDK
+
+TypeScript/JavaScript SDK 位于本单体仓库的 [`packages/js-sdk`](../../../packages/js-sdk)。安装已发布的包：
+
+```bash
+npm install @qverisai/sdk
+```
+
+这是一个零依赖的类型化客户端（原生 `fetch`，Node.js 18+）。完整指南（配置、API 参考、类型化响应、错误处理）见 [TypeScript SDK](js-sdk.md)。
+
+```typescript
+import { Qveris } from '@qverisai/sdk';
+
+const qveris = Qveris.fromEnv(); // 读取 QVERIS_API_KEY、QVERIS_BASE_URL
+
+const discovered = await qveris.discover('weather forecast API', { limit: 5 });
+const tool = discovered.results[0];
+const result = await qveris.call(tool.tool_id, {
+  parameters: { city: 'London' },
+  searchId: discovered.search_id,
+});
+console.log(result.execution_id, result.success, result.billing);
+```
+
+---
+
 ### 直接调用 QVeris REST API
 
 **Base URL**

docs/cn/zh-CN/js-sdk.md

@@ -0,0 +1,168 @@
+# QVeris TypeScript SDK
+
+类型化的 TypeScript/JavaScript SDK，让你在自己的 Agent 和应用中发现、检查、调用并审计 10,000+ 真实已验证的 API 能力。
+
+`@qverisai/sdk` 是对 QVeris REST API（`discover`、`inspect`、`call`、`credits`、`usage`、`ledger`）的轻量类型化封装。它**零运行时依赖**——使用平台原生 `fetch`（Node.js 18+）——并与 [Python SDK](python-sdk.md) 和 [MCP 服务器](mcp-server.md) 保持一致的通信语义。
+
+## 安装
+
+```bash
+npm install @qverisai/sdk
+```
+
+需要 Node.js 18+（原生 `fetch`）。该包仅支持 ESM。
+
+## 认证
+
+SDK 从环境变量 `QVERIS_API_KEY` 读取 API 密钥，并通过 `QVERIS_BASE_URL` 指向 API 地址。请设置：
+
+```bash
+export QVERIS_API_KEY="your-api-key"
+export QVERIS_BASE_URL="https://qveris.cn/api/v1"
+```
+
+在 [qveris.cn](https://qveris.cn) 获取密钥。可从环境变量创建客户端，也可以显式传入配置：
+
+```typescript
+import { Qveris } from '@qverisai/sdk';
+
+const qveris = Qveris.fromEnv();
+// 或
+const explicit = new Qveris({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://qveris.cn/api/v1',
+});
+```
+
+区域解析优先级为：显式 `baseUrl` > `QVERIS_BASE_URL` > `QVERIS_REGION`（`global` | `cn`）> 密钥前缀自动识别（`sk-cn-…` → 中国）。
+
+## 快速开始
+
+核心工作流是 **discover → inspect → call**，然后可选地**审计**发生了什么。所有方法都返回 Promise。
+
+```typescript
+import { Qveris } from '@qverisai/sdk';
+
+const qveris = Qveris.fromEnv();
+
+// 1. 用自然语言发现能力（免费）
+const discovered = await qveris.discover('weather forecast API', { limit: 5 });
+const tool = discovered.results[0];
+
+// 2. 检查所选能力的完整参数
+const inspected = await qveris.inspect(tool.tool_id, { searchId: discovered.search_id });
+const selected = inspected.results[0];
+
+// 3. 调用（可能消耗积分）
+const params = selected.examples?.sample_parameters ?? { city: 'London' };
+const result = await qveris.call(selected.tool_id, {
+  parameters: params,
+  searchId: discovered.search_id,
+  maxResponseSize: 20480,
+});
+console.log(result.success, result.result);
+
+// 4. 审计最终扣费结果
+const usage = await qveris.usage({ execution_id: result.execution_id, summary: true });
+const ledger = await qveris.ledger({ summary: true, limit: 5 });
+console.log(usage.total, ledger.total);
+```
+
+客户端基于 `fetch`、无状态，无需手动关闭连接。
+
+## 配置参考
+
+`new Qveris(config)` 接受：
+
+| 字段 | 环境变量 | 默认值 | 说明 |
+|------|---------|--------|------|
+| `apiKey` | `QVERIS_API_KEY` | —（必填） | API 密钥，以 `Authorization: Bearer ...` 发送 |
+| `baseUrl` | `QVERIS_BASE_URL` | 按区域解析 | API 基础地址（优先级最高） |
+| `timeoutMs` | — | `30000` | 默认请求超时（`call` 默认 `120000`） |
+
+未显式给出 `baseUrl` 时，`QVERIS_REGION`（`global` | `cn`）强制指定区域。`Qveris.fromEnv(overrides?)` 从 `QVERIS_API_KEY` 构建客户端，并接受相同的非密钥选项。
+
+## API 参考
+
+### `Qveris`
+
+| 方法 | REST 端点 | 用途 |
+|------|-----------|------|
+| `discover(query, options?)` | `POST /search` | 用自然语言发现能力（免费） |
+| `inspect(toolIds, options?)` | `POST /tools/by-ids` | 获取能力完整元数据（免费） |
+| `call(toolId, options)` | `POST /tools/execute` | 执行能力（可能消耗积分） |
+| `credits()` | `GET /auth/credits` | 当前积分余额与分桶 |
+| `usage(filters?)` | `GET /auth/usage/history/v2` | 审计请求状态与扣费结果 |
+| `ledger(filters?)` | `GET /auth/credits/ledger` | 查看最终积分余额变动 |
+
+选项结构：
+
+- `discover(query, { limit?, sessionId?, timeoutMs? })`
+- `inspect(toolIds, { searchId?, sessionId?, timeoutMs? })` —— `toolIds` 接受单个字符串或数组；**空数组会短路**，直接返回空响应而不发起网络请求。
+- `call(toolId, { parameters, searchId?, sessionId?, maxResponseSize?, timeoutMs? })`
+
+`usage(...)` 和 `ledger(...)` 接受过滤对象，如 `start_date`、`end_date`、`summary`、`bucket`、`charge_outcome`、`execution_id`、`search_id`、`direction`、`entry_type`、`min_credits`、`max_credits`、`limit`、`page`、`page_size`。
+
+## 类型化响应
+
+所有方法返回与公开 OpenAPI 合同对齐的类型化结果。未知的后端字段会透传，因此新增的 API 元数据不会破坏旧版 SDK 客户端。
+
+- 发现 / 检查：`SearchResponse` → `results: ToolInfo[]`；`ToolInfo` 含 `tool_id`、`name`、`description`、`categories`（对象或字符串）、`capabilities`、`params`、`examples`、`stats`、`billing_rule`、`expected_cost`，以及（仅 discover）`why_recommended`。
+- 调用：`ExecuteResponse`，含 `execution_id`、`success`、`result`、`error_message`、`billing`（`CompactBillingStatement`）、`cost`、`remaining_credits`。
+- 用量审计：`UsageEventsResponse` → `items: UsageEventItem[]`、`total`、`summary`。
+- 积分账本：`CreditsLedgerResponse` → `items: CreditsLedgerItem[]`、`total`、`summary`。
+
+```typescript
+import type { ExecuteResponse } from '@qverisai/sdk';
+
+function explain(result: ExecuteResponse): string {
+  if (!result.success) return `failed: ${result.error_message}`;
+  const charged = result.billing?.summary ?? 'no billing info';
+  return `ok (${charged}); remaining=${result.remaining_credits}`;
+}
+```
+
+## 接入你自己的 Agent 循环
+
+类型化客户端天然可作为任何 LLM Agent 框架的工具后端：把 `discover` / `inspect` / `call` 作为工具暴露给模型，再把工具调用路由回客户端。由于 `discover` 返回 `why_recommended` 和 `expected_cost`，你的 Agent 可以在调用前对能力进行排序和预算控制。
+
+## 错误处理
+
+每个失败请求都会抛出 `QverisApiError`——一个 `Error` 子类，携带：
+
+| 属性 | 说明 |
+|------|------|
+| `status` | HTTP 状态码（`0` 网络错误，`408` 超时，`402` 积分不足，……） |
+| `details` | 服务端返回的错误体（如有） |
+| `observability` | 请求上下文（operation、endpoint、request id），用于诊断 |
+| `cause` | 更底层的传输/运行时原因（如有） |
+
+```typescript
+import { Qveris, QverisApiError } from '@qverisai/sdk';
+
+const qveris = Qveris.fromEnv();
+try {
+  await qveris.call('some.tool.v1', { parameters: {} });
+} catch (err) {
+  if (err instanceof QverisApiError && err.status === 402) {
+    // 积分不足 —— err.message 含购买链接
+  }
+}
+```
+
+`result.success` 只反映能力调用本身。**不要**把它当作最终扣费结果——请用 `usage(...)` / `ledger(...)` 确认扣费。
+
+## 兼容性
+
+- Node.js `>=18`（原生 `fetch`）。仅 ESM。
+- 响应类型与公开方法尽量遵循增量兼容。
+- 破坏性变更需要主版本号提升并附迁移说明。
+
+> `@qverisai/sdk` 的 `0.1.x` 版本是早期以 MCP 为中心的 SDK，现已被 [`@qverisai/mcp`](mcp-server.md) 取代。本文档所述的类型化 REST 客户端从 **`0.2.0`** 起。
+
+## 链接
+
+- 包：[npm 上的 `@qverisai/sdk`](https://www.npmjs.com/package/@qverisai/sdk)
+- 源码：[`packages/js-sdk`](https://github.com/QVerisAI/qveris-agent-toolkit/tree/main/packages/js-sdk)
+- REST API：[rest-api.md](rest-api.md)
+- 获取 API 密钥：[qveris.cn](https://qveris.cn)

docs/en-US/getting-started.md

@@ -141,6 +141,30 @@ if __name__ == "__main__":
 
 ---
 
+### Use the QVeris TypeScript SDK
+
+The TypeScript/JavaScript SDK lives in this monorepo at [`packages/js-sdk`](../../packages/js-sdk). Install the published package with:
+
+```bash
+npm install @qverisai/sdk
+```
+
+It is a zero-dependency typed client (native `fetch`, Node.js 18+). For the full guide (config, API reference, typed responses, error handling), see [TypeScript SDK](js-sdk.md).
+
+```typescript
+import { Qveris } from '@qverisai/sdk';
+
+const qveris = Qveris.fromEnv(); // reads QVERIS_API_KEY
+
+const discovered = await qveris.discover('weather forecast API', { limit: 5 });
+const tool = discovered.results[0];
+const result = await qveris.call(tool.tool_id, {
+  parameters: { city: 'London' },
+  searchId: discovered.search_id,
+});
+console.log(result.execution_id, result.success, result.billing);
+```
+
 ### Directly call the QVeris REST API
 
 **Base URL**