@open-billing/sdk

agent-billing 协议的中立 SDK。一包两味,按你的角色选:

createAgentMeter —— AI Agent 作者用。返回一个 IOMetricsProvider, 挂到 @multi-agent/a2a Agent Server 即可,每次 IO 自动带 HMAC 签名上报。
createBillingClient —— 业务方后端用。查事件、用量、余额、流水、价格。

本包从不发明价格、也不假设租户模型 —— 它严格说 docs/spec.md 定义的那个协议。换言之你完全可以自己写一个 SDK 替代它,协议本身才是契约。

安装

bun add @open-billing/sdk
# 或: npm i @open-billing/sdk

@multi-agent/a2a >= 0.3.10 是 peer dep —— 只在用 createAgentMeter 时才需要, 纯业务端 client 不需要。

Agent 侧 —— 一行接入计量

import { createAgentServer, defineSkill } from '@multi-agent/a2a'
import { createAgentMeter } from '@open-billing/sdk'

createAgentServer({
  agentId: 'image-agent',
  address: 'a2a://0.0.0.0:9090',

  // a2a 协议层接管 HMAC / token 计数 / 流拦截;SDK 只做 4 个 HTTP 调用。
  metricsProvider: createAgentMeter({
    baseUrl: process.env.BILLING_URL!,
    auth: { type: 'bearer', token: process.env.BILLING_AGENT_TOKEN! },
  }),

  skills: [
    defineSkill('generate', async (params, ctx) => {
      // 业务代码不写一行计费逻辑
      return { url: `https://example.com/${Date.now()}.png` }
    }),
  ],
})

每次 skill 调用幕后发生:

a2a 启动时调 verifyIntegrity → 后端返 signingKey
每次调用前 preCallCheck → 后端按余额 / 规则决定 allow
handler 跑 → 输入 / 输出 token 由 a2a 统计 + 算 contentHash + HMAC 签名
reportMetrics POST /events 落库

verifyIntegrity / preCallCheck 错误走严格模式(不能预检的事不应该扣费)。 reportMetrics 错误会抛出 —— a2a 内置 plugin 会 log。

"skill 失败也扣费"注意事项: a2a 的 afterHandler 不区分业务成功 / 失败, 只要 stream 有过输出就上报 IO 事件。如果 skill 报错并往 stream 写了 error 消息, 这些字节会算作 output token 扣费。三种补法见 docs/design-rationale.md §7。

业务侧 —— 五指 client

import { createBillingClient } from '@open-billing/sdk'

const billing = createBillingClient({
  baseUrl: process.env.BILLING_URL!,
  auth: { type: 'bearer', token: process.env.BUSINESS_TOKEN! },
})

// 1. 用户总消费
const usage = await billing.usage.byUser('user_42')
// → { totalCalls, totalInputTokens, totalOutputTokens, totalCost? }

// 2. 按 trace 拿事件(call graph)
const events = await billing.events.byTrace(traceId)

// 3. 时间范围 + Agent 过滤
const page = await billing.events.list({
  agentId: 'image-agent',
  from: new Date(Date.now() - 24 * 3600_000),
  limit: 50,
})

// 4. 余额(Billing Module 启用时)
const balance = await billing.accounts.balance('user_42')

// 5. 流水
const ledger = await billing.accounts.ledger('user_42', { op: 'charge' })

Admin 专用操作

需要 admin token(独立的角色,见 spec §3):

await billing.accounts.topup('user_42', 10_000, 'monthly grant')
await billing.accounts.adjust('user_42', -50, 'manual refund')
await billing.pricing.create({
  skill: 'generate',
  inputTokenPrice: 1,
  outputTokenPrice: 3,
})
await billing.pricing.expire(42)

鉴权 —— 三种姿势

// 1. Bearer(默认推荐)
auth: { type: 'bearer', token: 'xxx' }

// 2. 任意 header(对接非标准后端)
auth: { type: 'header', name: 'X-Service-Token', value: 'xxx' }

// 3. 完全自定义(签 JWT / mTLS 加证书 / 注入 trace header)
auth: { type: 'fn', apply: async (init) => {
  init.headers = { ...init.headers, Authorization: await signJWT() }
  return init
}}

Transport 调优

createBillingClient({
  baseUrl: '...',
  auth: { ... },
  timeout: 5_000,                          // 默认 10000ms
  retry: { attempts: 3, backoff: 'expo' }, // 默认 1(不重试);'expo' 或 'linear'
  fetcher: customFetch,                    // 完全替换 fetch(测试 / IPC / mock)
})

重试只针对 429 + 5xx —— 4xx 错误立刻抛。

错误处理

所有 HTTP 失败都抛 BillingError:

import type { BillingError } from '@open-billing/sdk'

try {
  await billing.accounts.balance('user_42')
} catch (e) {
  const err = e as BillingError
  err.status   // HTTP 状态码,如 404
  err.code     // 服务端给的错误码,如 'account_not_found'
  err.message  // 人类可读说明
  err.details  // 可选的结构化详情
}

API 一览

导出	角色	返回
`createAgentMeter`	Agent	`IOMetricsProvider`(a2a)
`createBillingClient`	业务方	`{ usage, events, accounts, pricing }`

分组	方法	spec	所需 token
usage	`byUser(userId, query?)`	§6.6	business
usage	`byAgent(agentId, query?)`	§6.7	business
events	`list(filter?)`	§6.5	business
events	`byTrace(traceId)`	§6.4	business
accounts	`list(filter?)`	§6.7.5	business
accounts	`balance(userId)`	§6.8	business
accounts	`ledger(userId, filter?)`	§6.9	business
accounts	`topup(userId, amount, note?)`	§6.10	admin
accounts	`adjust(userId, amount, note?)`	§6.11	admin
pricing	`list(filter?)`	§6.12	business
pricing	`create(entry)`	§6.13	admin
pricing	`expire(id)`	§6.14	admin

完整类型定义看 src/types.ts,完整 wire format 看 docs/openapi.yaml。

验证你的后端是否符合本协议

不管你 fork 参考服务端还是自己撸,跑 @open-billing/testkit 一次 —— 17 个 case 覆盖鉴权 / HMAC / 幂等 / Billing Module 合规性。

License

MIT