bazhuayu-client-js — DataHub 官方 JavaScript SDK

八爪鱼 DataHub 的官方 JavaScript 客户端（npm 包 bazhuayu-client）：发现、调用、 消费 Data App。TypeScript 编写、编译发行 JS + 类型声明，纯 JS 项目可直接使用。 自包含小项目，运行时零依赖（仅 Node 内置 fetch），只讲平台公开的 /v1 REST API。 与 Python SDK（bazhuayu-client pip 包）逐方法对齐。

要求 Node >= 20.17（ESM 发行，此版本起 CJS 也可直接 require）。

安装

npm install bazhuayu-client

用法

import { Client } from "bazhuayu-client";

// baseUrl 缺省即生产端点 https://api-datahub.bazhuayu.com,本地/预发环境按需传入
const client = new Client({ apiKey: "demo-key" });

// 发现
const result = await client.search("评论", { limit: 10 });
const detail = await client.getApp("demo/reviews-store-query");   // 或卡片里的 app_id

// 调用（等到终态）并消费。时间参数一律毫秒（timeout / pollInterval；
// Python SDK 为秒），timeout 超时抛 TimeoutError 但不取消服务端运行
const run = await client.call("demo/partner-reviews-api", { product: "p-9001" }, {
  timeout: 120_000, raiseOnFailure: true,
});
for await (const record of client.iterateRecords(run.run_id)) {
  console.log(record.content, record.rating);
}

// 盘点与对账
for await (const r of client.iterateRuns({
  runKind: "production", createdFrom: "2026-08-01T00:00:00Z",
})) {
  console.log(r.run_id, r.state, r.billing);
}
console.log(await client.billing({ groupBy: "data_app", tzOffset: 480 }));

// 结果数据默认保留 90 天，要长期留存打保留标记
await client.setDatasetRetention(run.dataset_id, true);

call() 发起运行并轮询到终态；需要非阻塞语义时用 run() 拿 run_id 后自行 getRun() / cancel()。被点对点授权给自己的 App 不在市场结果里，用 search("", { sharedWith: "me" }) 查。全部方法与错误映射见 src/client.ts。

App 引用有两种形态，getApp() / run() / call() 及运行列表的 dataApp 过滤处等价可用：<用户名>/<应用名> 两段式引用（取自卡片的 namespace 与 app_name，适合人读，发布者改名后旧引用失效）；不变标识 app_id （app_<hex>，取自卡片/详情的 app_id 字段，改名免疫）。写进配置、定时任务 等长期集成建议钉 app_id。

配置

new Client() 的 baseUrl / apiKey 缺省时回退环境变量 BAZHUAYU_BASE_URL / BAZHUAYU_API_KEY（模板见 .env.example；SDK 不自动加载 .env，由调用方 自行加载），再回退生产端点 https://api-datahub.bazhuayu.com / 匿名。

OAuth 登录（账号密码，替代 apiKey）

除 apiKey 外，也可用八爪鱼账号密码经 openapi /token 端点换取 identity JWT 调用平台（两通道互斥，归属与计费同一账户）：

import { Client, PasswordTokenProvider } from "bazhuayu-client";

const provider = new PasswordTokenProvider("[email protected]", "password");
const client = new Client({
  baseUrl: "https://datahub.example.com", tokenProvider: provider,
});
await client.call("demo/partner-reviews-api", { product: "p-9001" });

token 的缓存、快过期自动续期、refresh_token 一次性轮换与失效后密码重登都收在 provider 内（并发取值共享同一在途刷新）；提交 run 前默认要求 token 剩余有效期 ≥ 12h（不足则先强制刷新，可用 runTokenMinTtl 毫秒值调整）——平台入队时快照 凭证、终态重放扣费，提交时 token 越新鲜，长运行结束时扣费凭证过期的敞口越小。 注意 refresh_token 一次性使用：多进程不要共享同一账号的凭据序列，每个 进程各建 provider（各自密码登录）即可。tokenUrl 缺省生产端点，可用参数或 环境变量 BAZHUAYU_TOKEN_URL 覆盖。tokenProvider 也接受任意返回当前有效 token 的无参函数（自管续期时用）。

测试

npm test             # 离线单元测试（注入 fetch mock，不依赖服务端）
npm run typecheck    # 严格类型检查（含测试）