TypeScript SDK

The official @revkeen/sdk package provides typed API resources for server-side JavaScript and TypeScript. This guide targets 1.20260822.1541, the npm release verified on 5 September 2026.

Install

npm install @revkeen/sdk@1.20260822.1541

npm package · Source and releases. Use a maintained Node.js release. Package-manager tabs describe installation, not a guarantee that every runtime supports every helper.

Quick start

Create a staging merchant secret key in the dashboard and store it in REVKEEN_API_KEY on your server. Save this example as example.mjs, then run node example.mjs with the environment variable supplied by your secret store.

import { RevKeenClient } from "@revkeen/sdk";

const apiKey = process.env.REVKEEN_API_KEY;
if (!apiKey) throw new Error("Set REVKEEN_API_KEY to your staging merchant key");

const client = new RevKeenClient({
  apiKey,
  baseUrl: "https://staging-api.revkeen.com/v2",
  timeout: 10000,
});

const response = await client.customers.list({ limit: 10 });
console.log(response.data);

This sends GET /v2/customers?limit=10. Expect an array of customer records; [] is valid for a merchant with no customers. The request does not create data.

Environments and credentials

This published release requires /v2 in a custom base URL. Production is the default when baseUrl is omitted. A key works only where it was issued. Never expose secret keys to the browser. Demo requests belong in the key-free playground.

Errors and timeouts

import { RevKeenAPIError, RevKeenTimeoutError } from "@revkeen/sdk";

try {
  const response = await client.customers.list({ limit: 10 });
  console.log(response.data);
} catch (error) {
  if (error instanceof RevKeenAPIError) {
    console.error("RevKeen request failed", { status: error.status });
  } else if (error instanceof RevKeenTimeoutError) {
    console.error("RevKeen request timed out");
  } else {
    throw error;
  }
}

This fragment uses client from the quickstart. Do not log keys or whole response bodies containing customer data. Treat 401 as an authentication problem and 403 as an access problem. Handle 429 with bounded backoff. A timed-out mutation may have succeeded: reconcile its state before retrying.

Pagination

List methods accept the pagination parameters defined by their operation. For customer lists, request a bounded page with limit and advance offset explicitly:

const page = await client.customers.list({ limit: 25, offset: 0 });
console.log(page.data);

See pagination for response metadata. Do not assume all resources use the same pagination shape or that the client fetches later pages automatically.

Idempotent mutations

Choose an idempotency key for one logical operation. Reuse it for a retry of that same payload; use a new key for a new operation. The published wrapper has constructor-level headers, not a documented per-call options argument on every resource method. For a dedicated one-operation client, supply headers: { "Idempotency-Key": operationKey }. Do not reuse that client across unrelated mutations. For fine-grained request control, use the operation's HTTP example and idempotency guide.

OAuth client credentials

For an authorised server-to-server OAuth integration, configure oauth instead of apiKey. Keep the client secret server-side. This is not an interactive merchant login.

const client = new RevKeenClient({
  oauth: {
    clientId: process.env.REVKEEN_CLIENT_ID,
    clientSecret: process.env.REVKEEN_CLIENT_SECRET,
    tokenEndpoint: "https://api.revkeen.com/api/auth/oauth2/token",
    scopes: ["customers:read"],
  },
  baseUrl: "https://api.revkeen.com/v2",
});

Validate both environment variables before constructing the client. Configure the matching staging token endpoint when targeting staging. See OAuth for supported grants and authorisation requirements.

Verify webhooks

Use constructEvent from @revkeen/sdk/webhooks with the raw body, signature header, and endpoint signing secret. The signing secret is separate from your merchant API key.

Follow the complete receiver example and signature contract. Verification errors are WebhookSignatureVerificationError; this published class does not expose a code field.

Runtime compatibility

Prefer a Node.js server runtime for the webhook receiver. There is no blanket compatibility guarantee for runtimes that only implement fetch.

Upgrading

Review release notes, update your lockfile intentionally, and rerun your integration tests. Development-source examples may use a newer client shape than the published npm package.

See release availability and migration for the current package boundary and newer client capabilities.

Owner: david · Reviewed 5 Sep 2026