@open-pay/sdk

billing-saas Gateway 模式 (a2a-only) 接入加速器。提供 @multi-agent/a2a 的 ClientPlugin / ServerPlugin + dashboard REST 查询 typed client。

历史: 0.7.0 起重写为 a2a plugin 集合。0.6.0 及之前的 createAgentMeter / createBillingClient (老 events 上报模型) 已废弃, 请直接迁到下面 3 个新 API。

三个 API

| API | 给谁用 | 是 a2a plugin 吗 | |---|---|---| | createBillingClientPlugin | caller (a2a 调用方) | ✓ ClientPlugin | | createBillingServerPlugin | agent 开发者 | ✓ ServerPlugin | | createBillingApiClient | 业务后端 (查 transactions / balance) | ✗ 普通 REST client |

安装

bun add @open-pay/sdk @multi-agent/a2a
# 或: npm i @open-pay/sdk @multi-agent/a2a

@multi-agent/a2a >= 0.3.10 是 peer dep —— 用 client/server plugin 时必装; 只用 createBillingApiClient 时可不装。

Caller 侧 —— 一行接入

每个 agent 在 dashboard 注册后获得一个独立的 Marketplace URL (a2a://gateway.openbilling.dev/agents/<slug>), caller 复制粘贴到 .env 即可调用:

import { createAgentClient } from '@multi-agent/a2a'
import { createBillingClientPlugin } from '@open-pay/sdk'

// 从 dashboard → My Agents → 复制 marketplace URL
const client = createAgentClient({
  agentId: 'image-agent',  // 仅用于 ctx / log, 路由不靠它
  address: 'a2a://gateway.openbilling.dev/agents/haiveo-image-agent',
}).use(createBillingClientPlugin({
  apiKey: process.env.OB_API_KEY!,   // ob_live_xxx, 在 billing-saas dashboard 创建
}))

const stream = await client.call('generate', { prompt: 'a corgi' })
for await (const msg of stream) {
  if (msg.type === 'done') console.log(msg.data)
}

plugin 做的事 (15 行 beforeCall hook):

• 注入 Authorization: Bearer ob_live_xxx (caller 鉴权)
• 注入 x-target-agent: <agentId> (老 header 路由 fallback)

Gateway 路由机制 (Marketplace URL 优先):

• caller address 中的 /agents/<slug> 被 a2a 协议层自动转成 x-agent-namespace metadata
• Gateway 优先用 namespace 查 marketplace slug 路由到 agent 真实地址
• agent 真实物理地址对 caller 完全透明 (类似 OpenRouter)

详细使用见 docs/marketplace-url-quickstart.md。

Agent 侧 —— 一行 token-gate

import { createAgentServer, createAgentConfig } from '@multi-agent/a2a'
import { createBillingServerPlugin } from '@open-pay/sdk'

const server = createAgentServer(createAgentConfig({
  agentId: 'image-agent',
  name: 'Image Agent',
  version: '1.0.0',
  description: '...',
  address: 'a2a://0.0.0.0:50118',
  skills: [/* ... */],
  defaultSkill: 'generate',
})).use(createBillingServerPlugin({
  accessToken: process.env.IMAGE_AGENT_ACCESS_TOKEN,
}))

await server.start()

plugin 做的事 (beforeMessage hook):

• 拦 call 消息, 验 Authorization: Bearer <accessToken>
• 不匹配 → stream.send(error) + return 'exit' 短路
• accessToken 留空 → 跳过验证 (本地开发方便, 生产必填)

错误码 (0.7.1+):

• MISSING_AGENT_ACCESS_TOKEN: 请求没带 Authorization header (Gateway 配置问题)
• AGENT_ACCESS_TOKEN_MISMATCH: 请求带了 Bearer, 但跟本机不一致 (两端 token 没对齐, 最常见)

access token 来源: 在 billing-saas dashboard /agents 注册 agent 时平台自动生成 + 一次性显示明文; 复制到本机 .env 的 IMAGE_AGENT_ACCESS_TOKEN。后续可在 dashboard Eye reveal 或 Rotate 换新。

业务后端侧 —— 查 transactions / balance

import { createBillingApiClient } from '@open-pay/sdk'

const api = createBillingApiClient({
  baseUrl: 'https://billingapi.haivex.ai',
  apiKey: process.env.OB_API_KEY!,
})

// 本月聚合 (caller 视角 + agent 视角)
const summary = await api.transactions.summary()

// 流水分页
const txs = await api.transactions.list({ view: 'caller', limit: 50 })

// 余额
const balance = await api.balance.get()

对应 billing-saas dashboard REST endpoint:

• /tenants/me/transactions / /transactions/summary
• /tenants/me/balance
• /tenants/me/agents (CRUD)

非 a2a plugin, 是普通 fetch wrapper。

设计原则

• a2a-only: caller → agent 调用必须经 @multi-agent/a2a, 没有 REST gateway 入口
• plugin 风格 > wrapper 风格: 不抢 a2a API, 用 .use(plugin) 增强
• 零额外协议: 老 events POST / /usage / /accounts 协议已下线
• 可组合: 跟其他 a2a plugin (tracing / call-recorder) 链式 .use() 共存

类型导出

import type {
  // 三个 API 的 Options
  BillingClientPluginOptions,
  BillingServerPluginOptions,
  BillingApiClientOptions,
  BillingApiClient,

  // REST 数据结构
  BillingAgent,
  BillingAgentCreate,
  BillingTransaction,
  BalanceInfo,
  TopupResponse,
  TransactionListFilter,
  TransactionListPage,
  TransactionSummary,

  // 共享
  AuthConfig,
  TransportConfig,
  BillingError,
} from '@open-pay/sdk'

版本

• 0.7.1: 细化 BillingServerPlugin 错误码 (MISSING_AGENT_ACCESS_TOKEN / AGENT_ACCESS_TOKEN_MISMATCH), error text 改成直白告知"两端 token 没对齐"
• 0.7.0: 重写为 a2a plugin 集合
• 0.6.0 及之前: 老 events 上报模型 (createAgentMeter / createBillingClient), 已废弃

License: MIT