# @borga/node 中文文档

规范地址：https://npmcn.com/package/%40borga/node/

版本：0\.10\.1
npm 元数据更新时间：2026-11-06T09:34:57.558Z
中文译文更新时间：2026-11-08T11:44:07.280Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40borga/node
原文对照：https://npmcn.com/package/%40borga/node/?lang=original
项目主页：https://docs.borga.is/
源码仓库：https://github.com/aranja/borga

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

- 包体积（解压后）：671 kB，8 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：0 个
- 首次发布：2026-09-07T16:28:42.652Z
- 最新版本发布：2026-11-06T09:34:57.330Z
- 近 30 天下载量：1900（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 15 个）

## 中文简介

Borga Node.js客户端库——打入了Borga API.

## 安装

```sh
npm install @borga/node
```

也可以使用：`pnpm add @borga/node`、`yarn add @borga/node`、`bun add @borga/node`

## README

# @borga/节点

官方节点客户端 [博尔加](https://docs.borga.is/) API:为冰岛市场支付卡片、银行发票(krafa)、订阅和计费.

## 安装

```sh
npm install @borga/node
```

要求节点.js 18或更新.

## 使用量

以密钥 API 认证( E)`sk_test_…` 或者说 `sk_live_…`从Borga仪表板下 **开发者**。密钥可以识别您的商家,所以不需要其他标题.

```ts
import { Borga } from "@borga/node";

const borga = new Borga({ apiKey: process.env.BORGA_SECRET_KEY! });

// Create a hosted checkout session and redirect the payer to session.url
const session = await borga.paymentSessions.create({
  amount: 24180, // whole krónur: 24.180 kr.
  currency: "ISK",
  return_url: "https://example.is/order/complete",
  cancel_url: "https://example.is/cart",
  external_reference: "order_1042",
});
```

通过Borga OAuth 的赠款为商人代理的应用程序 `new Borga({ accessToken })`通过一份证书,而不是两份证书; `defaultHeaders` 在每个请求中添加信头但无法设置 `Authorization`. 赠款的范围决定哪些要求成功.

### 嵌入式检出

```ts
const session = await borga.paymentSessions.create({
  amount: 24180,
  currency: "ISK",
  mode: "embedded",
  origin: "https://example.is",
});

// Hand session.id and session.client_secret to the browser and open the
// modal with borga.js:  new Borga(pk).checkout.open({ sessionId, clientSecret })
```

### 用法事件(计费)

```ts
await borga.usageEvents.create({
  event_name: "api_call",
  customer: "cus_…",
  idempotency_key: "req_…",
  metadata: { units: 1 },
});
```

### 网络呼号

```ts
import { verifyWebhookSignature } from "@borga/node";

const event = verifyWebhookSignature({
  body: rawRequestBody, // the raw string or Buffer, not the parsed JSON
  signature: req.headers["borga-signature"],
  secret: process.env.BORGA_WEBHOOK_SECRET!,
});

switch (event.type) {
  case "payment.succeeded":
    // event.data is narrowed to the Payment object
    break;
  case "invoice.payment_failed":
    // event.data.attempt, event.data.reason
    break;
}
```

## 行为

-   POST 请求获得自动生成 `Idempotency-Key`所以复试是安全的。 自己通过 `{ idempotencyKey }` 使各种过程的重复也变得安全.
-   5xx,429和网络出错被以指数回放(默认为3回放)来重试.
-   API 出错 `BorgaError` 与 `type`, (中文(简体) ), `code`, (中文(简体) ), `status`, (中文(简体) ), `param`, (中文(简体) ), `requestId` 和被剖开的身体.

## 文档

指南和 API 的完整参考文件在 [维基文库中相关的原始文献: 维基语录链接:名人名言 - 分类](https://docs.borga.is/)。所有代码样本都会对照此软件包进行打字检查.

## 常见问题

### @borga/node 是什么？

Borga Node\.js客户端库——打入了Borga API\.

### 如何安装 @borga/node？

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

### @borga/node 支持 TypeScript 吗？

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

### @borga/node 支持 ESM 还是 CommonJS？

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

### @borga/node 需要什么版本的 Node\.js？

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

### @borga/node 可以商用吗？

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

### @borga/node 的下载量有多少？

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

### @borga/node 还在维护吗？

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