@gr4vy/node

中文文档
1.4.0发布于 2025/07/22MITTypeScriptESM + CJS近 30 天下载 7785

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

此软件包已被标记为弃用

Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

中文使用文档
文档目录20 节
  1. 安装
  2. 开始
  3. 环境
  4. Gr4vy 嵌入器
  5. 刷新一个符号
  6. 其他数据
  7. 初始化
  8. 给API打电话
  9. 生成 API 无记名符号
  10. 回应和承诺( O)
  11. 正在校验 Webhooks
  12. 使用量
  13. 参数
  14. 错误
  15. 日志调试( D)
  16. 发展
  17. 添加新的 API
  18. 出版
  19. 许可证
  20. 发布注释

节点的 Gr4vy SDK



[大 这个SDK现在已经贬值了. 请参见我们的新 贝塔打字机 SDK 这个SDK的新方向.

Module Version

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

安装

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

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

开始

要打第一个API电话,你需要 请求 a 将设立Gr4vy实例。 请联系我们的销售团队 进行演示.

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

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数字 :

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的金额、货币和可选购买信息.

// 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 重新使用原始符号和新数据。 您的退出会 自动添加到同一种符号.

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

其他数据

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

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和私人钥匙.

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

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

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

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

给API打电话

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

client.listBuyers(null, 100)

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

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

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

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

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

生成 API 无记名符号

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

import { JWTScope } from '@gr4vy/node'

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

第一个参数是Gr4vy API的公认范围列表. 第二个 参数是该符号定义的过期时间 vercel/ms 图书馆.

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

Authorization: Bearer <bearerToken>

回应和承诺( O)

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

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

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

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请求的方法。 这确保了网钩有效载荷是真实的,没有被篡改.

使用量

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使得对控制台的要求和回应变得容易.

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

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

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 时间更长.

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

出版

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

许可证

此库在 MIT 许可证。 。 。 .

发布注释

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

版本与发布记录

@gr4vy/node 共发布 68 个版本,首次发布于 2021/02/24;过去 12 个月发布了 0 个版本。

版本发布日期距今
1.4.0latest2025/07/221.3 年前
1.3.12025/07/051.4 年前
1.3.02025/07/051.4 年前
1.2.02025/04/181.6 年前
1.1.12025/04/141.6 年前
1.1.02024/09/112 年前

关于 @gr4vy/node 的常见问题

@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。作者已将其标记为弃用,新项目建议寻找替代方案。