巴赫斯类型SDK
官方服务器侧 TypeScript SDK for Bachs. SDK 版本 1.0.0 和后端 API /v1 是单独的版本系统。 麻省理工学院颁发的许可证;见LICENSE.
服务器侧节点.js 22或更新. 本地获取和加密, 没有运行时的依赖性 。 ES-模块导入和CommonJS要求共享相同的运行时类和出错.
npm install @bachs/[email protected]
import { Bachs } from '@bachs/sdk';
const bachs = new Bachs({ apiKey: process.env.BACHS_API_KEY });
const product = await bachs.products.create({
name: 'Pro Plan',
price: { currency: 'USD', amount: '12.00' },
billing_cycle: { interval: 'month', frequency: 1 }
}, { idempotencyKey: 'unique-operation-key-retained-by-your-app' });
const checkout = await bachs.checkoutSessions.create({
product_cart: [{ product_id: product.id }],
customer: { email: '[email protected]', name: 'Synthetic Customer' },
success_url: 'https://your-public-app.example/success'
}, { idempotencyKey: 'another-unique-operation-key' });
// Redirect the customer to checkout.checkout_url in your application.
// A redirect alone does not prove payment or establish access rights.
const session = await bachs.checkoutSessions.get(checkout.checkout_id);
配置后端的 SDK; 保留前端代码中的密钥 。 构建客户端不发送请求 。 环境来自关键前缀: sk_sandbox_ 键使用沙盒和 sk_live_ 键使用生产,以及 bachs.environment 说哪一个。 通过 environment 是可选的;如果与密钥相矛盾,客户端拒绝以 BachsConfigError 而不是发送一个沙盒键 生产或反之。 未识别前缀需要的密钥 environment 明确设定. baseURL 可以覆盖代理/本地测试服务器的端点。 SDK不提供交叉账户连接头或浏览器证书管理.
已执行资源
| 资源 | 方法 | 责任 |
|---|---|---|
products | create, (中文(简体) ), get, (中文(简体) ), list | 可重复使用的目录报价,包括经常性定价 |
checkoutSessions | create, (中文(简体) ), get | 主办产品推车或原始定价的离职 |
payments | get, (中文(简体) ), list | 付款状况和历史;无β直接收费 |
subscriptions | get, (中文(简体) ), list, (中文(简体) ), cancel | 客户订阅查询和即期/期末注销 |
customerPortal | createSession(customerId) | 为获得授权的客户提供短期托管的账单 URL |
balances | get | 以本国货币计算的余额桶 |
banks | list, (中文(简体) ), resolveAccount | 银行代码和账户名查询 |
payoutDestinations | create, (中文(简体) ), get, (中文(简体) ), list | 目标记录和提供者审查/使用状态 |
payoutQuotes | create | 跨货币来源/接受方数额和引文过期 |
payouts | create, (中文(简体) ), get, (中文(简体) ), list | 自主平衡支付请求、现状和历史 |
webhooks | constructEvent | 验证原始签名字节并返回事件信封 |
创建用途 (input, options?),检索用途 (id, options?)和列表用途 (filters?, options?)。 。 。 . subscriptions.cancel 用途 (id, input?, options?)· ; customerPortal.createSession 用途 (customerId, options?)。 。 。 . balances.get 只有一个选项.
list 返回一页. listAll(filters?, options?) 打开 products, (中文(简体) ), payments, (中文(简体) ), subscriptions, (中文(简体) ), payoutDestinations 财务报告和审定财务报表 payouts 是一个针对每个项目的同步浏览器,仅在到达时获取每个页面,并跟踪光标或相抵显示每个资源需求:
for await (const payout of bachs.payouts.listAll({ status_filter: 'completed' })) {
console.log(payout.id, payout.amount);
}
``` Payment list items retain `id`; a retrieved payment retains `payment_id`. Payout and destination lists retain their own distinct envelopes.
Money remains decimal strings and fields remain in Bachs snake_case. Fixed product `price_type` can be omitted; fixed `amount` is required. Free/custom inputs support their verified omitted/null money fields. Checkout requires a cart or raw pricing, not both. Deprecated `return_url`, Connect split/account fields and beta payment-method saving are not exposed in the checkout input type.
## Subscription management
```ts
const page = await bachs.subscriptions.list({ customer_id: 'cust_synthetic' });
const scheduled = await bachs.subscriptions.cancel('sub_synthetic', {
cancel_at_period_end: true
});
// For immediate cancellation, use cancel_at_period_end: false.
const portal = await bachs.customerPortal.createSession('cust_synthetic');
Bachs在离职后管理经常性的账单. 商家在查询,取消或门户网站创建前,必须授权请求客户. 门户网站 URL 携带证书:将客户重定向到它,不登录/共享. SDK不提供客户门户UI,应享权利规则或续约管弦乐.
更新核查限制 : 巴赫拥有自动反复开账单. 该版已核实了沙盒中的第一个订阅付款和即期/期终注销答复,但没有观察到第二个计费周期付款或其续订的网页hook. 在检查过的API和CLI中没有发现支持公共沙盒循环/测试小时操作. 更新行为仍未通过SDK验收运行进行验证;不将初始付款或样本/重播事件视为更新证据.
付款
const quote = await bachs.payoutQuotes.create({
from_currency: 'USD', to_currency: 'NGN', amount: '120.00'
});
const payout = await bachs.payouts.create({
destination: 'pd_synthetic', quote_id: quote.quote_id,
reference: 'unique-payout-reference-retained-by-your-app'
}, { idempotencyKey: 'durable-operation-key-from-your-app' });
这是说明性的,而不是要求提供资金。 跨货币支付使用 quote_id; 同货币支付使用 amount 在目的地货币。 供应正好一个. amount编号 :currency 描述接收方; fee编号 :total_debited 使用情况 source_currency引文不是付款,接受/待付不是最后交付。 利用检索/历史和经核实的付款结果活动跟踪进展情况.
提供独特的报酬 reference 并保留它用于这一行动,与它的同能钥匙分开。 虽然API标记 reference 选项,测试过的沙盒拒绝了“这个组织已经存在参考”的省略引用。 SDK 保存 API 可选性; 此工作变通不会改变其请求类型 .
使用提供者的 is_usable 标记用于准备目的地。 SDK 付款创建不会秘密解决/ 创建目的地, 获取余额或强制实施猜测的管理员政策 . banks.resolveAccount 能够返回 resolved: false 带有没有 HTTP 错误的信件。 从 banks.list而不是银行名.
网络呼号
import { webhooks } from '@bachs/sdk';
const event = webhooks.constructEvent(
rawRequestBody,
requestHeaders,
webhookSigningSecret
);
// Persist/check event.id atomically in your application before applying effects.
rawRequestBody 是 JSON 解析前的字符串或 Uint8Array 。 信头可以是标准信头对象,也可以是节点式信头记录. 签名密钥与API密钥分离. 独立的助手不需要 API 客户端 ; bachs.webhooks 揭发同名帮手.
偏爱 X-Bachs-Signature-V2; 校验接受任何匹配 v1 旋转时消化. 遗产 X-Bachs-Timestamp编号 :X-Bachs-Signature 也得到支持。 畸形V2不会回落到遗产. HMAC-SHA256标出准确的时间戳加生字节;比较使用常时密码. 默认时间戳的可容忍度是300秒左右,可以通过 { toleranceSeconds }。未知的事件类型和额外字段得到保存。 只有经核实有效的JSON/事件信封被还原.
帮助者不存储已处理过的ID,保证准确的即时效果或运行业务处理器. 商家拥有可持久的分解,HTTP确认,客户授权和访问更改等功能. 在签名验证前不要将 JSON 序列化 .
请求行为和错误
timeoutMs: 整个操作默认为30000,包括尝试,延迟和回复读取. 支持每个请求覆盖; 范围为 1–2147483647毫秒, 以避免节点计时器溢出 .maxRetries: 默认另外两次 GET 尝试; 客户端/ 阅读覆盖支持 。 网络/机体-传输失败和HTTP 429/500/502/503/504可以重试. 其他 HTTP 拒绝和无效的成功响应机构不重试 .- 等待开始于500/1000毫秒左右,随机分布很小. 有效
Retry-After提示是荣耀的。 在所需等待时间不能在所剩期限内时不再作进一步尝试. - 信件发送一次,包括用
idempotencyKey。没有生成的密钥或持久的 SDK 密钥存储。 事后故意重复必须保留密钥并请求;后端保留不能由SDK保证. signal支持取消。 发送后停止本地工作不能取消提供者处理 .
日志
SDK日志通过 logger 选项(带有 debug, (中文(简体) ), info, (中文(简体) ), warn 财务报告和审定财务报表 error 方法,例如: console 或皮诺伐木机。 没有了,警告就到 console.warn 并且没有其他东西是印刷的. logLevel 或 BACHS_LOG 环境变量( e)debug, (中文(简体) ), info, (中文(简体) ), warn, (中文(简体) ), off)设置最低水平;默认为 warn。警告包括一个未识别的密钥前缀和用过的重试预算;信息记录每个客户端的环境一次;调试日志每个请求的方法、路径、状态代码、持续时间、尝试编号和请求ID。 API密钥,请求和响应机构,门户网站URL和webhook秘密从未在任何级别被登录.
BachsApiError 携带 statusCode (HTTP状态代码), errorCode (Bachs错误代码从身体),原始 body选择 fieldErrors, (中文(简体) ), requestId 财务报告和审定财务报表 retryAfter。 。 。 . BachsNetworkError 保留其事业,并 responseStatusCode,任何已观察到的状态代码;超时和调用取消都有不同的子类. BachsResponseError 意味着成功 statusCode 带有无法使用的 JSON/形状. BachsConfigError 拒绝本地配置/请求滥用. BachsWebhookError 拒绝无效的 webhook 认证/ enveropes .
写出 5xx , 后端网络/ 取消/ 超时失败和无法使用的成功写入回复曝光 outcomeUnknown: true。不将错误解释为不存在操作的证据;在创建新的操作密钥之前调节。 提供机构和门户URL可能包含敏感数据;SDK从不登录.
响应卫士验证支持类型承诺的字段,返回实际对象并保留额外的字段为未知. 因果关系和普遍反应的完整性仍然是合同问题。 未完全输入的网状提供者字段仍然未知,而不是收到不加控制的断言.
核查
运行 npm install,则 npm run check: 严格的正/负型固定装置,既包括构建,也包括覆盖客户端,资源和网络hook/可靠性行为的30个局部情景. 本地测试无法建立真正的供应商处理或网络快递.
GitHub 动作运行相同 npm run check 命令在安装锁定的依赖关系后在节点22和24上 npm ci。它运行在推取和拉取请求上,可以从动作分页手动启动。 这些检查使用本地固定装置,不需要 Bachs API 密钥,也不发布包.
node examples/sandbox-check.mjs --key-file <local-file> 使用真沙盒进行只读 SDK 检查并保存已消毒的局部结果. 只有在批准之后, --create-approved-records 此外,还创造了1个月产12美元、1个未付离职单和1个1美元对NGN报价。 它从不支付结账,发送付款,取消订阅,创建门户会话或创建目的地. 新书写使用已记录的独有操作密钥并保存不确定的结果. 不要盲目重运行写入模式:每个新运行描述新的操作.
Sandbox验收核实了最初的1美元12的订阅购买,匹配了报出/付款/订阅记录,托管的门户访问,既包括SDK注销模式,Sandbox目的地创建/get/list,又包括已完成的10至NGN付款,收费为1美元。 官方Bachs CLI发送了一份真正的签名付款网页,与该付款有关,并在字节被篡改后被拒绝。 有记录的沙盒银行固定器还原了 resolved: false (b) 未建立正账名解析和生产目的地审查。 如上文所述,真正的更新仍未核实。 这些是有界限的沙盒观测,而不是生产结算的保证,公共的网路快递重试或应用程序的分解. 仍然需要最后的释放审查;单是绿色测试计数不能稳定释放接受.
两个开发日志都是当地的工作记录. 永远不要舞台、承诺、推动或把它们包括在包裹中.