@gr4vy/node

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

NodeJS client for @gr4vy/node

此软件包已被标记为弃用

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

原始使用文档
文档目录20 节
  1. Installation
  2. Getting Started
  3. Environment
  4. Gr4vy Embed
  5. Refreshing a token
  6. Additional data
  7. Initialization
  8. Making API calls
  9. Generate API bearer token
  10. Response & Promises
  11. Verifying Webhooks
  12. Usage
  13. Parameters
  14. Errors
  15. Logging & Debugging
  16. Development
  17. Adding new APIs
  18. Publishing
  19. License
  20. Release notes

Gr4vy SDK for Node



[!IMPORTANT] This SDK is now deprecated. Please refer to our new Beta Typescript SDK for the new direction for this SDK.

Module Version

Gr4vy provides any of your payment integrations through one unified API. For more details, visit gr4vy.com.

Installation

To add Gr4vy to your project, install the @gr4vy/node package as follows.

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

Getting Started

To make your first API call, you will need to request a Gr4vy instance to be set up. Please contact our sales team for a demo.

Once you have been set up with a Gr4vy account you will need to head over to the Integrations panel and generate a private key. We recommend storing this key in a secure location but in this code sample we simply read the file from disk.

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
// }

Environment

The SDK defaults the environment to "sandbox", to send transactions to production, set the environment in 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 Embed

To create a token for Gr4vy Embed, call the client.getEmbedToken() function with the amount, currency, and optional buyer information for 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)

You can now pass this token to your front end where it can be used to authenticate Gr4vy Embed.

Refreshing a token

To get a new token with a new expiration date, or to add new data to a token, without losing the checkout session ID, you can call the updateEmbedToken method again with the original token and the new data. Your checkout session will automatically be added to the same token.

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

Additional data

Additional data can be added to a token. The buyerId and buyerExternalIdentifier fields can be used to allow the token to pull in previously stored payment methods for a user. A buyer needs to be created before it can be used in this way.

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,
})

Initialization

The client can be initialized with the Gr4vy ID (gr4vyId) and the private key.

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

Alternatively, instead of the gr4vyId it can be initialized with the baseUrl of the server to use directly.

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

Your API key can be created in your admin panel on the Integrations tab.

Making API calls

This library conveniently maps every API path to a seperate function. For example, GET /buyers?limit=100 would be:

client.listBuyers(null, 100)

To create or update a resource, the API requires a request object for that resource that is conventiently named <Resource>Request or <Resource>UpdateRequest.

For example, to create a buyer you will need to pass a BuyerRequest object to the addBuyer method.

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

Similarly, to update a buyer you will need to pass in the BuyerUpdateRequest.

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

Generate API bearer token

The SDK can be used to create API access tokens for use with other request libraries.

import { JWTScope } from '@gr4vy/node'

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

The first parameter is a list of recognised scopes for the Gr4vy API. The second parameter is the expiration time for the token as defined by the vercel/ms library.

The resulting token can be used as a bearer token in the header of the HTTP request made to the API.

Authorization: Bearer <bearerToken>

Response & Promises

Every API call returns a Promise that either resolves or rejects.

Every resolved API call returns an object containing a body attribute with the parsed JSON body and a response object representing the HTTP response object which includes the raw headers and status code.

For a failed API call, it returns a similar object is returned with the body of the error.

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
  })

Verifying Webhooks

The SDK provides a verifyWebhook method to validate incoming webhook requests from Gr4vy. This ensures that the webhook payload is authentic and has not been tampered with.

Usage

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)
}

Parameters

  • payload: The raw payload string received in the webhook request.
  • secret: The secret used to sign the webhook. This is provided in your Gr4vy dashboard.
  • signatureHeader: The X-Gr4vy-Signature header from the webhook request.
  • timestampHeader: The X-Gr4vy-Timestamp header from the webhook request.
  • timestampTolerance: (Optional) The maximum allowed difference (in seconds) between the current time and the timestamp in the webhook. Defaults to 0 (no tolerance).

Errors

The verifyWebhook method throws an error in the following cases:

  • Missing header values: If either the signatureHeader or timestampHeader is missing.
  • Invalid header timestamp: If the timestampHeader is not a valid number.
  • No matching signature found: If the signature does not match the expected value.
  • Timestamp too old: If the timestamp is outside the allowed tolerance.

Logging & Debugging

The SDK makes it easy possible to the requests and responses to the console.

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

This will output the request parameters and response to the console as follows.

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
}

Development

Adding new APIs

To add new APIs, run the following command to update the models and APIs based on the API spec.

./openapi-generator-generate.sh

Next, update sdk/client.ts to bind any new APIs or remove any APIs that are no longer available.

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

Publishing

Publishing of this project is done automatically using the yarn release command which creates a new version, publishes it to a tag, and then triggers a GitHub Action to release the new package to NPM.

License

This library is released under the MIT License.

Release notes

  • 1.0.0 - Update to OpenAPI SDK generator v7.6.0
  • 0.65.0 - Update dependencies

版本与发布记录

@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 是什么?

NodeJS client for @gr4vy/node注意:该包已被作者标记为弃用——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。作者已将其标记为弃用,新项目建议寻找替代方案。