# @gr4vy/node 中文文档

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

版本：1\.4\.0
npm 元数据更新时间：2025-12-15T19:20:25.491Z
中文译文更新时间：2026-11-17T03:25:37.093Z
软件包许可：MIT

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

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

弃用说明：Package no longer supported\. Contact Support at https://www\.npmjs\.com/support for more info\.

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

- 包体积（解压后）：2.6 MB，1259 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：8 个
- 首次发布：2021-02-23T17:14:32.602Z
- 最新版本发布：2025-07-22T09:12:13.559Z
- 近 30 天下载量：7785（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：68（近 12 个月 0 个）

## 中文简介

@ gr4vy/ 节点的节点JS 客户端

## 安装

```sh
npm install @gr4vy/node
```

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

## README

# 节点的 Gr4vy SDK

  
  

> \[大 这个SDK现在已经贬值了. 请参见我们的新 [贝塔打字机 SDK](https://github.com/gr4vy/gr4vy-typescript) 这个SDK的新方向.

[![Module Version](https://badge.fury.io/js/%40gr4vy%2Fnode.svg)](https://www.npmjs.com/package/@gr4vy/node)

Gr4vy通过一个统一的API提供任何您的支付整合. 详情请访问 [gr4vy.com (英语)](https://gr4vy.com/)。 。 。 .

## 安装

要将 Gr4vy 添加到您的工程中, 请安装 `@gr4vy/node` 软件包如下.

```sh
npm install @gr4vy/node --save
# yarn add @gr4vy/node
```

## 开始

要打第一个API电话,你需要 [请求](https://gr4vy.com/) a 将设立Gr4vy实例。 请联系我们的销售团队 进行演示.

一旦你建立了Gr4vy账户,你需要去 **一体化** 面板并生成一个私钥。 我们建议把这个密钥存储在一个安全的地方 但是在这个代码样本中 我们只是从磁盘上读取文件.

```js
const fs = require('fs')
const { Client, BuyerRequest } = require('@gr4vy/node')
// or: import { Client, BuyerRequest } from "@gr4vy/node";

const key = String(fs.readFileSync('./private.key'))

const client = new Client({
  gr4vyId: 'YOUR_GR4VY_ID',
  privateKey: key,
  environment: 'production',
})

const buyerRequest = new BuyerRequest()
buyerRequest.displayName = 'John L.'
const buyer = await client.newBuyer(buyerRequest)
console.log(buyer)
// {
//   response: {...} the HTTP response object
//   body {...} the parsed JSON
// }
```

## 环境

SDK 默认环境为 “ sandbox ” , 将交易发送到生产中, 设置环境 `Client`数字 :

```js
const client = new Client({
  gr4vyId: 'YOUR_GR4VY_ID',
  privateKey: key,
  environment: 'sandbox',
})

const client = new Client({
  gr4vyId: 'YOUR_GR4VY_ID',
  privateKey: key,
  environment: 'production',
})
```

## Gr4vy 嵌入器

要为 Gr4vy Embed 创建一个符号,请拨打 `client.getEmbedToken()` 函数 gr4vy Embed的金额、货币和可选购买信息.

```js
// generate a session to tie any transactions to
const response = await this.newCheckoutSession()
// generate the token
const token = await client.getEmbedToken({
  amount: 1299,
  currency: 'USD',
  buyerExternalIdentifier: 'user-1234',
  checkoutSessionId: response.body.id,
  // or: buyerId: ...
})

// or to combine both calls in one
const { token, checkoutSession } =
  await client.getEmbedTokenWithCheckoutSession(embedParams)
```

你现在可以把这个标志 传递到你的前端 它可以用来 认证Gr4vy Embed.

### 刷新一个符号

获得带有新到期日的新令牌,或者在令牌上添加新数据,同时不丢失取出会话ID, 你可以打电话 `updateEmbedToken` 重新使用原始符号和新数据。 您的退出会 自动添加到同一种符号.

```js
const token = await client.updateEmbedToken(oldToken, {
  amount: 1299,
  currency: 'USD',
  buyerExternalIdentifier: 'user-1234',
})
```

### 其他数据

附加数据可以添加到一个符号上. 这个 `buyerId` 财务报告和审定财务报表 `buyerExternalIdentifier` 字段可以用于让符号为用户拉入先前存储的支付方法. 购买者需要先被创造,然后才能被这样使用.

```js
const buyerRequest = new BuyerRequest()
buyerRequest.displayName = 'John L.'
buyerRequest.externalIdentifier = 'user-1234'
const buyer = await client.newBuyer(buyerRequest)

const token = await client.getEmbedToken({
  amount: 1299,
  currency: 'USD',
  buyerId: buyer.body.id,
})
```

## 初始化

客户端可以用 Gr4vy ID 初始化(`gr4vyId`和私人钥匙.

```js
const client = new Client({
  gr4vyId: 'acme',
  privateKey: key,
})
```

或者,不要 `gr4vyId` 它可以初始化 与 `baseUrl` 用于直接使用的服务器.

```js
const client = new Client({
  baseUrl: 'https://api.acme.gr4vy.app',
  privateKey: key,
})
```

您的 API 密钥可以在您的管理面板中创建 **一体化** 选项卡.

## 给API打电话

这个库方便地将每个API路径映射到一个分隔函数. 譬如说, `GET /buyers?limit=100` 将:

```js
client.listBuyers(null, 100)
```

要创建或更新资源, API 需要为此请求对象 以修道院命名的资源 `<Resource>Request` 或者说 `<Resource>UpdateRequest`。 。 。 .

例如,要创建买方,您需要通过 `BuyerRequest` 对象 页:1 `addBuyer` 方法.

```js
const buyerRequest = new BuyerRequest()
buyerRequest.displayName = 'John L.'
const buyer = await client.newBuyer(buyerRequest)
```

同样,为了更新购买者,您需要通过 `BuyerUpdateRequest`。 。 。 .

```js
const buyerUpdateRequest = new BuyerUpdateRequest()
buyerUpdateRequest.displayName = 'John D.'
const buyer = await client.updateBuyer(buyer.id, buyerUpdateRequest)
```

## 生成 API 无记名符号

SDK 可用于创建 API 访问令牌, 以便与其他请求一起使用 图书馆.

```js
import { JWTScope } from '@gr4vy/node'

const bearerToken = client.getBearerToken(
  [JWTScope.BuyersRead, JWTScope.BuyersWrite],
  '1h'
)
```

第一个参数是Gr4vy API的公认范围列表. 第二个 参数是该符号定义的过期时间 [`vercel/ms`](https://github.com/vercel/ms) 图书馆.

在 HTTP 的页眉中, 生成的符可以用作无记名符号 请求API.

```ini
Authorization: Bearer <bearerToken>
```

## 回应和承诺( O)

API 调用返回 a `Promise` 要么决定,要么拒绝.

每个解析的 API 调用返回包含 `body` 属性与已解析的 JSON 天体和 a `response` 表示对象 HTTP 响应对象,包括原始头和状态代码.

对于一个失败的 API 调用, 它返回一个与 API 一起返回的类似对象 `body` 错误.

```js
client
  .getBuyer(buyer.id)
  .then((result) => {
    console.dir(result.body) // the parsed JSON
    console.dir(result.response.statusCode) // the status code of the response
  })
  .catch((error) => {
    console.dir(error.response.body) // the parsed JSON of the error
    console.dir(error.response.statusCode) // the status code of the error
  })
```

## 正在校验 Webhooks

SDK提供了一个 `verifyWebhook` 用于验证Gr4vy收到的webhook请求的方法。 这确保了网钩有效载荷是真实的,没有被篡改.

### 使用量

```js
const { Client } = require('@gr4vy/node')
// or: import { Client } from '@gr4vy/node';

const payload = 'your-webhook-payload'
const secret = 'your-webhook-secret'
const signatureHeader = 'signatures-from-header'
const timestampHeader = 'timestamp-from-header'
const timestampTolerance = 300 // optional, in seconds (default: 0)

try {
  Client.verifyWebhook(
    payload,
    secret,
    signatureHeader,
    timestampHeader,
    timestampTolerance
  )
  console.log('Webhook verified successfully!')
} catch (error) {
  console.error('Webhook verification failed:', error.message)
}
```

### 参数

-   **`payload`**:在webhook请求中收到的原始有效载荷字符串.
-   **`secret`**:用来签下"网钩"的秘密. 这在你的Gr4vy仪表板上提供.
-   **`signatureHeader`**编号: `X-Gr4vy-Signature` 由 webhook 请求发出的头条 .
-   **`timestampHeader`**编号: `X-Gr4vy-Timestamp` 由 webhook 请求发出的头条 .
-   **`timestampTolerance`**数字 : _(备选)_ 允许的最大值( 以秒计) 在webhook中当前时间和时间戳之间的相差 。 默认为 `0` (没有宽容).

### 错误

这个 `verifyWebhook` 方法在以下情况下丢出错误:

-   **缺少信头值**: 如果其中之一 `signatureHeader` 或者说 `timestampHeader` 缺少.
-   **无效的页眉时间戳**: 如果 `timestampHeader` 不是一个有效的号码.
-   **未找到匹配的签名**:如果签名与预期值不符.
-   **时间戳太老了**: 如果时间戳在允许的容忍度之外.

## 日志调试( D)

SDK使得对控制台的要求和回应变得容易.

```js
const client = new Client({
  gr4vyId: 'demo',
  privateKey: key,
  debug: true,
  // merchantAccountId: 'my-merchant-id' # optional for multi merchant instances
})
```

这将输出请求参数和对控制台的响应如下.

```sh
Gr4vy - Request - .getBuyer: 41291df0-4a5d-42d9-a977-dbc8ef6463c4
Gr4vy - Response - .getBuyer - 200): Buyer {
  type: 'buyer',
  id: '41291df0-4a5d-42d9-a977-dbc8ef6463c4',
  external_identifier: null,
  display_name: 'Test',
  created_at: 2021-02-23T16:23:22.794Z,
  updated_at: 2021-02-23T16:23:22.794Z
}
```

## 发展

### 添加新的 API

要添加新的 API, 请运行以下命令以更新模型和基于 API 的 API 的 API 规格.

```
./openapi-generator-generate.sh
```

下一个, 更新 `sdk/client.ts` 绑定任何新的 API 或删除任何没有的 API 时间更长.

```js
const poa = new PaymentOptionsApi(this.baseUrl)
this.listPaymentOptions = this.wrap(poa.listPaymentOptions.bind(poa))
this.apis.push(poa)
```

### 出版

此工程的出版将自动使用 `yarn release` 命令创建新版本,将其发布到标签上,然后触发一个 GitHub行动组织向国家预防机制发布新的一揽子计划.

## 许可证

此库在 [MIT 许可证](https://npmcn.com/package/%40gr4vy/node/LICENSE)。 。 。 .

## 发布注释

-   1.0.0 - 更新到 OpenAPI SDK 生成器 v7. 6.0
-   0.65.0 - 更新依赖性

## 常见问题

### @gr4vy/node 是什么？

@ gr4vy/ 节点的节点JS 客户端注意：该包已被作者标记为弃用——Package no longer supported\. Contact Support at https://www\.npmjs\.com/support for more info\.

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

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

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

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

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

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

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

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

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

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

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

最新版本 1\.4\.0 发布于 2025/07/22（1\.3 年前）；至今共发布 68 个版本，其中过去 12 个月发布了 0 个；首次发布于 2021/02/24。作者已将其标记为弃用，新项目建议寻找替代方案。

