# JavaScript / TypeScript SDK 接入

用本地ES module连接客户模拟网关：下载SDK、账户与用量查询、只读报价、显式执行、TEST上限与分页回执。

用少量代码把目录、报价和一次执行接进你的 Node 工作流。SDK没有外部依赖，也不会替你重试或翻页。

运行范围：ES MODULE · LOCAL ONLY

## 对应能力

- [获取 X 账号资料](https://datanavoapi.com/apis/x/users/get/)：x.users.get，返回 data.item，不支持分页，客户成功请求1 TEST。

## 准备本机服务与客户 Key

先在完整DataNavoAPI项目中运行 npm run local，确认网站地址为 http://127.0.0.1:4321。SDK固定连接本机，始终使用 simulated 模式。

注册本地账户，创建允许 x.users.get 的客户 Key，并通过模拟收银台取得 TEST 点数。可以同时设置日/月/总消费预算，轮换Key也不会清零。

[创建客户 Key](https://datanavoapi.com/account/keys/)

[本地模拟收银台入口](https://datanavoapi.com/account/billing/)

## 把SDK和类型声明放在一起

下载guanliu.mjs，与自己的connect.mjs放在同一个目录。TypeScript项目同时保留同名的guanliu.d.mts，NodeNext解析会自动关联声明。

SDK使用Node自带fetch；完整DataNavoAPI项目的运行要求是Node22.23.4或更高。这里下载的是本地源码文件，尚未发布npm包。

[下载 guanliu.mjs](https://datanavoapi.com/sdk/guanliu.mjs)

[下载 guanliu.d.mts](https://datanavoapi.com/sdk/guanliu.d.mts)

## 默认只报价，显式参数才执行

把下面保存为connect.mjs。由你在本机进程环境中设置GUANLIU_CUSTOMER_API_KEY；SDK自身不读取.env。不要把Key写入公开代码或浏览器URL。

运行node connect.mjs只报价。核对结果后，手动运行node connect.mjs --execute才会执行一个模拟请求。示例固定编号用于这一个任务；新任务先换编号，原任务重放保持不变。

```
import {GuanliuClient, GuanliuError} from './guanliu.mjs';

const client = new GuanliuClient({
  apiKey: process.env.GUANLIU_CUSTOMER_API_KEY,
  port: 4321,
});
const capability = 'x.users.get';
const params = {username: 'guanliu_demo'};
const idempotencyKey = 'js-account-sample-001';

try {
  const quote = await client.quote(capability, params, {maxCredits: 1});
  console.log('quote', quote.status, quote.body);
  if (process.argv.includes('--execute') &&
      quote.status === 200 && quote.body.data.eligible) {
    const result = await client.call(capability, params, {
      idempotencyKey, scenario: 'success', maxCredits: 1,
    });
    console.log('call', result.status, result.body);
    // 202仍在处理；不要自动换编号或循环重试。
  }
} catch (error) {
  if (!(error instanceof GuanliuError)) throw error;
  console.log(error.code, error.outcomeUnknown);
  // true表示执行结果未知。保留原编号、参数和场景。
}
```

## 只读查询余额、预算与当前Key用量

将下方保存为account.mjs，运行node account.mjs。它是独立只读示例；客户Key仍从本机进程环境读取。

account()直接读取余额、当前Key概要、预算与当日请求额度；usage(filters)读取当前Bearer Key的用量。两者不先拉目录、不执行、不预留或扣点，不需要幂等编号。

钱包属于账户，所有Key共享；预算随轮换组继承；用量只属于当前Key，新Key不继承旧Key的用量列表。用量是已保存计费流水，不是每次重试次数或所有未完成请求。

usage可筛选status（all/success/failure）、capability和UTC日期from/to。page为1–1,000,000整数，pageSize为20/50/100；Python使用相同字典字段名。默认第1页、20条，不自动翻页，不接受keyId/userId等身份覆盖。

预算按执行准入时间、用量按记录时间计算，跨日完成时可能不一致。返回金额为TEST_CREDIT，非真实供应商数据；只读失败的outcomeUnknown/outcome_unknown始终为false。

```
import {GuanliuClient, GuanliuError} from './guanliu.mjs';

const client = new GuanliuClient({
  apiKey: process.env.GUANLIU_CUSTOMER_API_KEY,
  port: 4321,
});
try {
  const account = await client.account();
  const usage = await client.usage({status: 'all', page: 1, pageSize: 20});
  console.log('account', account.status, account.body);
  console.log('usage', usage.status, usage.body);
} catch (error) {
  if (!(error instanceof GuanliuError)) throw error;
  console.log(error.code, error.outcomeUnknown);
  // 只读失败始终为false，不会触发执行或自动重试。
}
```

## 只读查询执行状态与已保存结果

calls(filters)列出当前Key的模拟执行；receipt(requestId)读取单次状态；result(requestId)读取已保存结果。它们直接GET /v1/calls及详情路径，不恢复超时记录、不续租、不重发，也不再扣TEST。

calls使用state筛选all/pending/succeeded/failed/timed_out/interrupted，以及capability、UTC日期from/to、page和pageSize。调用按准入时间筛选；usage按用量记录时间筛选。

result外层HTTP200表示读取成功；data.response.status保留原执行状态，可能是502或504。pending尚无保存结果时返回409 call_result_pending，不能当作执行失败或自动换编号重发。

[网页只读回执检查](https://datanavoapi.com/tools/request-inspector/)

[CLI 查询同一回执](https://datanavoapi.com/integrations/cli/#receipts)

## 按响应状态决定下一步

200是模拟成功；202是处理中，不自动轮询。401/403检查Key和scope；402查看最高单价、余额与预算；409表示编号已经用于不同的参数或场景。

502/504是已返回的模拟失败或超时，回执记录释放情况。运输异常的 outcomeUnknown / outcome_unknown=true 表示结果未确认，不能据此声称没有执行或扣点。

SDK不自动重试或翻页。报价失败属于未执行，错误的未知结果标志为false；quote本身不会消费点数。

[查看执行与结算](https://datanavoapi.com/account/executions/)

[预算合同说明](https://datanavoapi.com/docs/#budgets)

## 手动分页，逐页保留请求编号

搜索或评论的成功响应可含 body.page.next_cursor。需要下一页时，复制原params并加入cursor，使用新的幂等编号再call；同一页重放继续用该页编号。

SDK没有全局最高价格设置。每次手动call下一页都显式传maxCredits或max_credits。新页独立扣TEST；已完成回执重放不新增扣点。

本页x.users.get示例没有分页。请先从对应能力文档确认paginated，再把相应参数应用到分页调用。

[能力目录](https://datanavoapi.com/apis/)

[统一对象字段](https://datanavoapi.com/docs/objects/)

## TypeScript使用同一个实现

导入./guanliu.mjs后，类型声明提供GuanliuParams、GuanliuResponse与GuanliuError。params只接受合同字段对应的字符串或数字，最高单次点数须为1–1,000,000的整数。

类型检查不能代替服务端鉴权或预算校验。执行时会重新验证，成功报价不是预留保证。

```
import {GuanliuClient, type GuanliuParams} from './guanliu.mjs';
const params: GuanliuParams = {username: 'guanliu_demo'};
// 复用上方 client.quote / client.call；不另安装一个客户端。
```

## 核对已经保存的真实请求

v0.28 增加明确的 live 只读入口。JavaScript / Python 使用 GuanliuLiveReadClient；CLI 使用 --mode live；stdio MCP 使用 GUANLIU_MCP_MODE=live。默认模拟模式保持原行为。

只读取当前 gl_live_ Key 的账户免费授权、用量、回执与保存结果。MCP 仅提供 find、describe、account，account 的 what=balance/usage/calls/standing/receipt/result；不执行新的请求，也不充值或支付。

pending 与 unknown 不自动重试。免费预留按供应商和单位分开，实际供应商成本未知；同账户其他 Key 占用幂等编号时不泄露其回执。

[live 只读接入说明](https://datanavoapi.com/mcp/#live-read)

[账户真实调用记录](https://datanavoapi.com/account/live-usage/)

## 下一步

[改用Python](https://datanavoapi.com/integrations/python/)

[接入MCP客户端](https://datanavoapi.com/integrations/mcp-stdio/)

[网页查看报价](https://datanavoapi.com/account/keys/#sandbox-request)

真实API和支付保持关闭。固定样本和模拟供应商结果不能作为实时市场事实。

## 机器接入与数据说明

演示固定返回虚构样本，请检查 meta.mode，不得作为实时市场事实。MCP 默认 demo，可显式配置客户 Key 使用 simulated；SDK 固定模拟模式。模拟调用只消耗 TEST_CREDIT，真实供应商和支付保持关闭。

[能力合同](https://datanavoapi.com/catalog.json)

[OpenAPI](https://datanavoapi.com/openapi.json)

[Agent 指引](https://datanavoapi.com/agents.md)
