客户端接入 / JavaScript / TypeScript SDK 接入
JAVASCRIPT / TYPESCRIPT

JavaScript / TypeScript SDK 接入

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

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

对应能力

准备本机服务与客户 Key

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

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

把SDK和类型声明放在一起

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

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

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

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

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

JAVASCRIPT / connect.mjs
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。

JAVASCRIPT / account.mjs
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,不能当作执行失败或自动换编号重发。

按响应状态决定下一步

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

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

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

手动分页,逐页保留请求编号

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

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

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

TypeScript使用同一个实现

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

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

TYPESCRIPT
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 占用幂等编号时不泄露其回执。

下一步

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