# @bachs/sdk 中文文档

规范地址：https://npmcn.com/package/%40bachs/sdk/

版本：2\.0\.0
npm 元数据更新时间：2026-10-23T12:16:36.965Z
中文译文更新时间：2026-11-07T19:06:01.884Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bachs/sdk
原文对照：https://npmcn.com/package/%40bachs/sdk/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：230 kB，131 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：0 个
- 首次发布：2026-07-14T22:00:14.312Z
- 最新版本发布：2026-10-23T12:16:36.721Z
- 近 30 天下载量：3084（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

Bachs 官方服务器侧 TypeScript SDK

## 安装

```sh
npm install @bachs/sdk
```

也可以使用：`pnpm add @bachs/sdk`、`yarn add @bachs/sdk`、`bun add @bachs/sdk`

## README

# 巴赫斯类型SDK

官方服务器侧 TypeScript SDK for Bachs. SDK 版本 `1.0.0` 和后端 API `/v1` 是单独的版本系统。 麻省理工学院颁发的许可证;见LICENSE.

服务器侧节点.js 22或更新. 本地获取和加密, 没有运行时的依赖性 。 ES-模块导入和CommonJS要求共享相同的运行时类和出错.

```sh
npm install @bachs/sdk@1.0.0
```

```ts
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: 'synthetic@example.com', 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` 是一个针对每个项目的同步浏览器,仅在到达时获取每个页面,并跟踪光标或相抵显示每个资源需求:

````ts
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验收运行进行验证;不将初始付款或样本/重播事件视为更新证据.

## 付款

```ts
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`而不是银行名.

## 网络呼号

```ts
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) 未建立正账名解析和生产目的地审查。 如上文所述,真正的更新仍未核实。 这些是有界限的沙盒观测,而不是生产结算的保证,公共的网路快递重试或应用程序的分解. 仍然需要最后的释放审查;单是绿色测试计数不能稳定释放接受.

两个开发日志都是当地的工作记录. 永远不要舞台、承诺、推动或把它们包括在包裹中.

## 常见问题

### @bachs/sdk 是什么？

Bachs 官方服务器侧 TypeScript SDK

### 如何安装 @bachs/sdk？

在项目目录运行 npm install @bachs/sdk，或使用 pnpm add / yarn add / bun add。

### @bachs/sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @bachs/sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @bachs/sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @bachs/sdk 可以商用吗？

@bachs/sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bachs/sdk 的下载量有多少？

根据 npm 官方下载统计，@bachs/sdk 在 2026/10/08 – 2026/11/06 这 30 天内被下载 3,084 次，日均约 103 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bachs/sdk 还在维护吗？

最新版本 2\.0\.0 发布于 2026/10/23（15 天前）；至今共发布 3 个版本，其中过去 12 个月发布了 3 个；首次发布于 2026/07/15。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。