Usagey Node.js SDK

The official usagey package provides typed entitlement checks, idempotent usage metering, hosted checkout creation, and developer-event access.

Use it only in trusted server-side code. Usagey API keys must never be exposed in browser bundles or mobile applications.

Install the package

npm install @usagey/sdk

See Installation for npm, pnpm, Yarn, and Bun commands. Node.js 20.19.0 or newer is required.

Quick start

import { Usagey } from "@usagey/sdk";

const usagey = new Usagey(process.env.USAGEY_API_KEY!);

const access = await usagey.check({
  externalId: "customer-42",
  feature: "api_requests",
});

if (access.status === "access_granted") {
  // Run the billable operation before recording successful usage.
  await usagey.track(
    {
      externalId: "customer-42",
      feature: "api_requests",
      quantity: 1,
      metadata: { route: "/v1/embeddings" },
    },
    { idempotencyKey: "request_01JEXAMPLE" },
  );
}

The recommended lifecycle is:

1. Check the entitlement before expensive work runs.
2. Perform the operation only when access is granted.
3. Track usage only after the operation succeeds.
4. Reuse the same idempotency key when retrying that operation.

SDK resources

Resource	Purpose
usagey.check()	Check access without consuming usage.
usagey.track()	Record successful usage with idempotency protection.
usagey.meter()	Concise alias for track().
usagey.checkout.create()	Create a plan or credit-pack checkout.
usagey.events.list()	Read filtered, cursor-paginated developer events.

Next steps

• Configure environments and timeouts
• Check entitlements and meter usage
• Create hosted checkouts
• Read developer events
• Handle typed errors

If you used an earlier release, read Migrating from 0.1 before upgrading.