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才会执行一个模拟请求。示例固定编号用于这一个任务;新任务先换编号,原任务重放保持不变。
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,不能当作执行失败或自动换编号重发。
按响应状态决定下一步
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的整数。
类型检查不能代替服务端鉴权或预算校验。执行时会重新验证,成功报价不是预留保证。
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和支付保持关闭。固定样本和模拟供应商结果不能作为实时市场事实。