npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@nozle-js/node

v0.43.0

Published

Feature Event writes use the Go Engine at `https://api.nozle.app/engine/api/v1/events` (batch: `/events/batch`). Configure `baseUrl` for a custom ingestion endpoint. `eventsUrl` configures Core billing resources and subscription discovery.

Downloads

6,576

Readme

@nozle-js/node

Feature Event writes use the Go Engine at https://api.nozle.app/engine/api/v1/events (batch: /events/batch). Configure baseUrl for a custom ingestion endpoint. eventsUrl configures Core billing resources and subscription discovery.

Server-side Node.js SDK for usage tracking, entitlement checks, margin intelligence, LLM cost capture, and billing management.

Install

npm install @nozle-js/[email protected]

Works with both JavaScript and TypeScript. Requires Node.js 18+.

Version 0.13.0 adds captureFetch and recordUsage for usage from any LLM client, createBillingHandler to serve the React billing hooks, webhooks.verify and createWebhookHandler, invoices, usage and balance alerts, currentUsage and pastUsage, a host option and retries (maxRetries, default 2, safe calls only). apiKey is optional and falls back to NOZLE_SECRET_KEY, and every failed call throws NozleApiError. See the changelog and docs.nozle.dev.

Quick Start

import { Nozle } from "@nozle-js/node";

const nozle = new Nozle({ apiKey: "sk_live_..." });

// Track a Feature Event and keep its organization-wide identity.
const transactionId = await nozle.track(
  "cust_123",
  "copilot_action",
  { mode: "planning" },
);

// Add a detailed provider cost to that Feature Event without waiting for it.
await nozle.costEvents.track({
  parentTransactionId: transactionId,
  costMeterCode: "ai_tokens",
  properties: { model: "gpt-5", type: "input", tokens: 150 },
});

// Entitlement check
const { allowed, reason, used, limit } = await nozle.can("cust_123", "code_completion");

// A customer with several subscriptions: say which one (external ids). Without a selector the result is
// { allowed: false, reason: "subscription_required" }.
await nozle.can("cust_123", "seats", undefined, { subscriptionId: "sub_a" }); // or { entityId: "ent_1" }

Configuration

const nozle = new Nozle({
  apiKey: "sk_live_...",            // Required
  baseUrl: "https://api.nozle.app/engine",  // Default: https://api.nozle.app/engine
  eventsUrl: "https://api.nozle.app/core", // Default: https://api.nozle.app/core
  timeout: 15_000,                   // Default: 10000ms
});

LLM Auto-Capture

Automatically extract model name, token counts, and latency from LLM API responses. No manual tracking needed — the SDK intercepts completions and calls nozle.track() for you.

Cost calculation happens server-side via the Go engine's cost model system.

OpenAI

npm install openai  # peer dependency, >=4.0.0
import OpenAI from "openai";
import { Nozle, wrapOpenAI } from "@nozle-js/node";

const nozle = new Nozle({ apiKey: "sk_live_..." });
const openai = wrapOpenAI(new OpenAI(), nozle, {
  customerId: "cust_123",
  metricCode: "copilot_action", // customer-facing Feature Event code
  costMeterCode: "ai_tokens",  // optional detailed Cost Events
  feature: "code_completion",  // optional analytics property
});

// Use OpenAI normally — tracking happens automatically
const response = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello" }],
});

// Streaming works too
const stream = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello" }],
  stream: true,
});
for await (const chunk of stream) {
  // usage is captured from the final chunk
}

Anthropic

npm install @anthropic-ai/sdk  # peer dependency, >=0.30.0
import Anthropic from "@anthropic-ai/sdk";
import { Nozle, wrapAnthropic } from "@nozle-js/node";

const nozle = new Nozle({ apiKey: "sk_live_..." });
const anthropic = wrapAnthropic(new Anthropic(), nozle, {
  customerId: "cust_123",
  metricCode: "copilot_action",
  costMeterCode: "ai_tokens",
  feature: "code_completion",
});

// Use Anthropic normally
const message = await anthropic.messages.create({
  model: "claude-sonnet-4-20250514",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello" }],
});

wrapOpenAI and wrapAnthropic return a new client view and never change the client you pass in, so a server can keep one provider client and wrap it per request:

const openai = new OpenAI();
app.post("/chat", async (req) => {
  const client = wrapOpenAI(openai, nozle, { customerId: req.team.id });
  return client.chat.completions.create({ model: "gpt-4o", messages: req.body.messages });
});

Calls on the original client record nothing.

By default each call's usage is sent in the background as soon as the response is read. Pass an event buffer as buffer to queue it there instead, so it is batched and flush() or close() sends it, for example at the end of a serverless handler:

const buffer = nozle.createEventBuffer();
const client = wrapOpenAI(openai, nozle, { customerId: "cust_123", buffer });
await client.chat.completions.create({ model: "gpt-4o", messages: [{ role: "user", content: "Hello" }] });
await buffer.flush(); // sends the usage event

captureFetch(nozle, { customerId, buffer }) takes the same option. flush() and close() first wait for responses still being read and for their cost events, which are still sent directly. A buffered usage event's delivery failures go to the buffer's onError.

Each provider call creates one Feature Event. When costMeterCode is set, the wrapper generates the Feature Event transaction_id before sending and attaches separate detailed Cost Events for the input, cached_input, cache_write, cache_write_1h, output, reasoning, audio_input, audio_output, image_input and image_output token categories when present (batch_input and batch_output replace input and output for a batch-tier call). Each token is in exactly one category, the cost event ID is <transaction_id>:<type>, and the usage event also carries the breakdowns (cached_input_tokens, reasoning_tokens, ...). A stream that ends early is recorded with stream_aborted: true; tokens the provider did not report are estimated (usage_source: "estimated", bytes / 4). OpenAI and Anthropic field names are normalized into the same Cost Event properties: { tokens, provider, model, type }. Delivery can arrive out of order because the Cost Event processor resolves the shared transaction_id asynchronously.

Usage Tracking

// Basic tracking (Engine picks the customer's one active subscription)
await nozle.track("cust_123", "api_call", { tokens: 100 });

// With explicit subscription
await nozle.track("cust_123", "api_call", { tokens: 100 }, {
  subscriptionId: "sub_abc",
});

// With custom transaction ID and timestamp
await nozle.track("cust_123", "api_call", { tokens: 100 }, {
  transactionId: "tx_custom_123",
  timestamp: "2025-01-15T10:30:00Z",
});

Subscription resolution: track() sends external_customer_id and your subscriptionId if given; the SDK does no lookup. Without one, Engine uses the customer's one active subscription. If there are several or none, it answers 422 active_subscription_ambiguous or active_subscription_not_found, thrown as a NozleApiError with that code: pass subscriptionId. currentUsage() and pastUsage() still look the subscription up (cached for 60 seconds).

track() returns the transactionId. The SDK generates a UUID version 7 identifier before sending the request when one is not supplied. The identifier is unique across the Nozle organization and can immediately be reused as a Cost Event parent, including when the two requests arrive out of order.

When track() throws (an error response, a network error or a timeout), the event may still have been recorded. The error carries the transaction ID as error.transactionId, also when the SDK generated it. Retry with that ID and the same event: Engine records an event once per transaction ID, so the retry does not bill it twice. Also pass a timestamp and reuse it on the retry: without one, each attempt is stamped with its own arrival time, and Nozle may count two attempts with different timestamps separately.

const timestamp = new Date().toISOString();
try {
  await nozle.track("cust_123", "api_call", { tokens: 100 }, { timestamp });
} catch (error) {
  const transactionId = (error as { transactionId?: string }).transactionId;
  await nozle.track("cust_123", "api_call", { tokens: 100 }, { transactionId, timestamp });
}
const transactionId = nozle.events.createTransactionId();

await nozle.track("cust_123", "copilot_action", {}, { transactionId });

await nozle.costEvents.track({
  costEventId: nozle.costEvents.createCostEventId(),
  costMeterCode: "ai_tokens",
  parentTransactionId: transactionId,
  requestId: "provider_request_123",
  operationKey: "planning",
  properties: { model: "gpt-5", type: "output", tokens: 900 },
});

A Cost Event may instead use externalCustomerId without a parent when the cost belongs to a customer but not to one Feature Event. Cost Event methods require a secret key.

Voiding an event

events.void() (secret key) cancels a recorded event by its transaction ID and reverses its usage, credits, cost and margin. It works only while no finalized, open or pending invoice covers the event's time; otherwise it throws NozleApiError period_invoiced and changes nothing. It is idempotent: a replay returns status: "already_voided".

const { void: v } = await nozle.events.void("tx_123", { reason: "wrong quantity" }); // reason: 1 to 500 characters
// v.status "voided" | "already_voided"; v.effects.credits "refunded" | "not_applicable" | "pending"

Refusals: event_not_found (404), period_invoiced (409), reason_required (422); test with error.hasCode(EventVoidErrorCode.PeriodInvoiced). A voided ID cannot be tracked again (transaction_voided, 409): send the corrected event with a new transactionId. An effect is pending while its background step runs; replay the call to read the current state.

Batching events

trackBatch() sends many events through Engine's /events/batch in one call. It takes the arguments of track() as objects, splits them into requests, sends them in parallel and returns one result per event.

const result = await nozle.trackBatch([
  { customerId: "cust_123", event: "api_call", metadata: { tokens: 100 } },
  { customerId: "cust_456", event: "api_call", metadata: { tokens: 40 }, timestamp: "2026-10-29T09:30:00Z" },
]);

console.log(result.accepted, result.rejected, result.failed);
for (const r of result.results) {
  if (r.status === "rejected") console.warn(r.index, r.errors); // { code: ["value_is_mandatory"] }
  if (r.status === "failed") console.error(r.index, r.transactionId, r.error); // resend with this transactionId
}

The contract:

  • Size. At most 5000 events per request: the Engine 2.28.0+ default (LAGO_EVENTS_BATCH_MAX_LENGTH). chunkSize (1 to 5000, default 5000) sets the size of each request, and a longer list is split. concurrency (1 to 64, default 4) is how many requests are in flight at once. Each request body is gzipped (Content-Encoding: gzip, Engine 2.28.0+); the decoded body limit is 16 MiB. An Engine with a lower cap (before 2.28.0 the default was 100) answers 422 too_many_events and stores nothing; the SDK then sends that request in halves until each fits.
  • Result. results[i] belongs to events[i] and has a status: accepted (stored), rejected (Engine refused this event; errors maps a field to codes, and resending it unchanged fails again) or failed (its request failed: error is a NozleApiError, a network error or a timeout, and the event may or may not be stored). accepted, rejected, failed and total count them. trackBatch() throws only for invalid arguments; a failed request never hides the results of the others.
  • Partial acceptance. Engine 2.28.0+ stores the valid events of a request and answers 200 with error_details naming each refused event by position: an invalid event, a transactionId already stored with other values, or an event of a customer whose payment is overdue (customer_payment_overdue). The SDK marks those rejected and the others accepted. A request that stores nothing (every event refused, or an Engine before 2.28.0, which refuses a whole request for one bad event) answers 422 or 402 naming the bad events; the SDK marks those rejected and resends the valid rest (at most 3 requests for one chunk), so one bad event costs its own result only. A 5xx or network error still fails the whole request; it is retried as below.
  • Idempotency. Every event has a transactionId: yours, or a generated UUID version 7 that is also returned in results[i].transactionId. Engine records an event once per transaction ID, so the SDK retries a request after a network error, timeout, 429 or 5xx (maxRetries, default 2) without storing an event twice. IDs must be unique in one call (NozleValidationError otherwise). To retry failed events yourself, pass the same transactionId and the same timestamp.
  • Timestamps. Each event keeps its own timestamp (RFC 3339 or Unix seconds); without one Engine stamps it on arrival. There is no backfill flag: /events/batch accepts old and future timestamps as sent. It does not apply the 24 hours ahead and 366 days back window that usage.track() and cost events enforce.
  • Subscription. As for track(), pass subscriptionId or let Engine resolve the customer's one active subscription. A customer with several or none is a 422 for that event, so it comes back rejected.
  • Invalid arguments (NozleValidationError with the event's index, before any request): a missing customerId or event, a bad timestamp, a repeated transactionId, or an out-of-range chunkSize or concurrency.

trackBatch() is not usage.track(): it records events like track() does and does not deduct credits, apply a money-billed feature's checks or return a balance. A list of 0 events sends nothing. To batch events as they happen, use an event buffer.

Event buffer

createEventBuffer() queues events in memory and sends them through trackBatch() in the background, so recording an event never waits for the network.

const buffer = nozle.createEventBuffer({
  onError: (error, events) => console.error(error.code, error.message, events.map((e) => e.transactionId)),
});

const transactionId = buffer.track({ customerId: "cust_123", event: "api_call", metadata: { tokens: 100 } });

// At shutdown, or at the end of a serverless handler:
await buffer.close();
  • track(event) takes a trackBatch() event and returns its transaction ID at once, without a request: yours, or a generated UUID version 7. Every resend of the event carries that ID, so Engine records it once. It throws NozleValidationError only for an invalid event (missing customerId or event, bad timestamp).

  • When it sends. A flush starts as soon as maxBatchSize events are waiting (default 500, 1 to 5000; also the size of each request), every flushIntervalMs (default 5000; 0 disables the timer) and on the process's beforeExit. The timer never keeps the process alive. Only one flush runs at a time; a trigger during a flush waits for it.

  • Backoff. After a flush in which any event failed, the size, timer and beforeExit flushes pause for 1 s, doubling after each consecutive flush with failures up to 60 s; a flush without failures ends the pause. Events keep queueing meanwhile (up to maxQueueSize), so a short outage costs no events. An explicit flush() or close() does not wait.

  • await flush() sends every event waiting now and resolves when done; it never rejects. await close() stops the timer, removes the beforeExit hook, sends everything (retrying failures as below) and refuses later events. size is the number of events waiting.

  • Bounded memory. The buffer holds at most maxQueueSize events (default 10 000), including those in a request. When it is full, track() drops the new event and reports it as buffer_full; it does not throw.

  • Never silent. onError(error, events) receives an EventBufferError for every event that leaves the buffer unsent, with error.code:

    • buffer_full: the queue was full and the new event was dropped.
    • rejected: Engine refused the event; error.errors maps a field to codes. It is not retried.
    • failed: its requests failed (after the maxRetries of each request) in maxAttempts flushes (default 3), spaced by the backoff above. Until then a failed event goes back to the front of the queue for the next flush; error.cause is the last error.
    • closed: track() was called after close().

    Without onError, each is emitted as a NozleTrackingWarning process warning. onError must not throw.

Serverless (AWS Lambda, Vercel and Cloudflare functions, and similar): the platform may freeze or end the process as soon as the handler returns, so neither the timer nor beforeExit runs. Always await buffer.flush() (buffer kept between invocations) or await buffer.close() (buffer per invocation) before returning, or the waiting events are lost. flush() keeps a failed event queued for a later flush; only close() retries it to maxAttempts and reports it, so short-lived processes and scripts should end with await buffer.close().

The queue lives in memory only: events still waiting when the process is killed (for example SIGKILL, or process.exit(), which skips beforeExit) are lost. During a backoff, beforeExit only sets a timer that does not keep the process alive, so a process whose server stays unreachable still exits and its waiting events are lost without a report unless it called close(). wrapOpenAI, wrapAnthropic and captureFetch queue their usage events in a buffer passed as their buffer option.

Entitlement Checks

const result = await nozle.can("cust_123", "code_completion");

if (result.allowed) {
  console.log(`${result.remaining} uses remaining`);
} else {
  console.log(`Blocked: ${result.reason}`);
}

Response includes cost intelligence:

result.economics?.estimated_incremental_cost    // Exact decimal string, for example "0.05"
result.economics?.estimated_incremental_revenue // Exact decimal string, for example "0.10"
result.economics?.estimated_incremental_margin  // Exact decimal string, for example "0.05"
result.economics?.estimated_margin_percent      // Percentage string when revenue is above zero
result.policy?.decision                         // "allow", "warn", or "deny"
result.policy?.scope                            // "customer", "plan", "feature" or "organization" (Engine 2.40.0)
result.policy?.on_not_configured                // "allow", "warn" or "deny" for a feature with no Cost Rule (Engine 2.39.0)

Credit Check & Deduct

checkAndDeduct is a legacy wallet adapter. New product-credit integrations should use nozle.usage.check() and nozle.usage.track() so metric conversion, source ordering, idempotency, and the immutable ledger remain authoritative.

Advisory checks return exact-decimal projected_remaining and ordered projected_deductions. These fields show the source plan without changing a balance and are suitable for shadow comparisons before a metric canary.

const result = await nozle.checkAndDeduct({
  customerId: "cust_123",
  credits: 5,
});

// `feature` is deprecated: it is accepted for old callers but never sent.
if (result.allowed) {
  console.log(`Deducted. Remaining: ${result.remaining}`);
} else {
  console.log(`Insufficient credits. Balance: ${result.remaining}`);
}

Customer Management

Customer writes go directly to Nozle Core using the merchant's secret key, so Core derives the owning organization from that key.

// Create or update a customer
const customer = await nozle.customers.upsert({
  externalId: "cust_123",
  name: "Acme Corp",
  email: "[email protected]",
});

// Link a customer that already exists in Stripe, without creating a new one
await nozle.customers.upsert({
  externalId: "cust_123",
  billingConfiguration: {
    paymentProvider: "stripe",
    paymentProviderCode: "stripe_main",
    providerCustomerId: "cus_ABC123",
  },
});

Tax data: pass customerType, legalName, address, shippingAddress and taxId. Core validates the format (value_is_invalid, value_is_mandatory, invalid_format in errorDetails; test with error.hasCode(CustomerTaxErrorCode.InvalidFormat)). A VIES check can leave tax_identification_status at pending, so wait before checkout:

await nozle.customers.upsert({
  externalId: "cust_123",
  customerType: "company",
  address: { line1: "Main St 1", city: "Berlin", postalCode: "10115", country: "DE" },
  taxId: { type: "eu_vat", value: "DE811128135" }, // null clears it
});
const customer = await nozle.customers.waitForTaxCheck("cust_123"); // { timeoutMs } defaults to 10000
customer.tax_treatment; // "reverse_charge" | "standard" | ...

Pass taxExempt: true to exempt a customer from tax. An invoice with tax_status: "failed" carries one of CustomerTaxErrorCode.TaxLocationInvalid, TaxIdInvalid, StripeTaxNotAuthorized, StripeAccountRequired or TaxProviderUnavailable.

A checkout call refuses with customer_tax_location_required (422) when the billing entity needs a country or address, and customer_tax_check_pending (409, error.retryAfterSeconds) while a check runs.

A payment provider assignment needs providerCustomerId or syncWithProvider: true; otherwise Core drops it. The same applies to provider_customer_id and sync_with_provider when you call the REST API directly.

Deleting and erasing a customer

customers.delete(externalId) deletes the customer and ends its subscriptions. It is not an erasure: the customer's personal data stays. customers.erase(externalId) erases that personal data (GDPR), irreversibly, and returns the customer with erased_at set; Core finishes in the background and sends a customer.erased webhook. Erase refuses with 422 while the customer has active subscriptions or draft or unpaid invoices. Erasing an erased customer changes nothing. Neither call is retried automatically.

try {
  const customer = await nozle.customers.erase("cust_123");
  customer.erased_at; // "2026-11-18T10:00:00Z"
} catch (error) {
  if (error instanceof NozleApiError && error.hasCode(CustomerEraseErrorCode.HasUnpaidInvoices)) {
    // collect or void the open invoices first
  }
}

Importing billing state and opening credit balances

When you move customers from another billing system, import each subscription that system still bills, then its current credit balance. Both calls need a secret key and an idempotencyKey (at most 255 bytes): retry an uncertain call with the same key and the same body. dryRun: true validates without writing.

const imported = await nozle.customers.importBillingState(
  "workspace_123",
  {
    subscription: {
      planCode: "pro_monthly",
      status: "active",
      billingAuthority: "external",
      externalReference: "merchant_subscription_123",
      currentPeriodStart: "2026-10-15T00:00:00Z",
      currentPeriodEnd: "2026-11-15T00:00:00Z",
    },
  },
  { idempotencyKey: "import-workspace_123-state" },
);

await nozle.customers.importCreditBalance(
  "workspace_123",
  {
    externalSubscriptionId: imported.subscription.external_subscription_id!,
    creditSystemCode: "ai_credits",
    grantedAmount: "500",
    remainingAmount: "320",
  },
  { idempotencyKey: "import-workspace_123-credits" },
);

Failures throw NozleApiError; for example error.code === "idempotency_key_reused" when a key is reused with a different body.

Product credits

Read exact-decimal balances and immutable operation history from the Phase 1 credit engine:

const balance = await nozle.credits.getBalance("cust_123", "ai_credits");
const page = await nozle.credits.listOperations("cust_123", {
  creditSystemCode: "ai_credits",
  limit: 25,
});

Keep these reads on the merchant backend. Return only the fields your authenticated browser route needs, and derive the customer from the logged-in user or team instead of trusting a browser customer ID.

Credit holds

When a call's final amount is known only afterwards (an LLM response, a long job), reserve credits first and settle afterwards. Needs Engine 2.34.0+ and a secret key.

const hold = await nozle.usage.holds.create(
  { customerId: "cust_123", featureCode: "agent_execution", properties: { tokens: 4000 }, ttlSeconds: 600 },
  { idempotencyKey: `hold-${runId}` },
);
if (!hold.allowed) throw new Error(hold.reason); // "insufficient_credits": nothing was reserved

try {
  const answer = await runAgent();
  await nozle.usage.holds.finalize(hold.hold_id, { properties: { tokens: answer.tokens } });
} catch (error) {
  await nozle.usage.holds.release(hold.hold_id);
  throw error;
}
  • create(params, { idempotencyKey }) takes the usage.track() params plus ttlSeconds (1 to 86400, default 900). A short balance answers allowed: false, not an error; a retry with the same key gets the same answer.
  • finalize(holdId, { properties, timestamp }) spends the actual usage at the rate pinned by the hold and releases the rest (credits_released). More than was held passes when the hold plus free credit covers it; otherwise allowed: false and the hold stays open. After expiry it runs as a plain track (hold_expired: true). A repeat with the same usage replays the answer, so it is retried like usage.track().
  • release(holdId) is idempotent; a finalized hold throws NozleApiError with code hold_already_resolved (409).
  • get(holdId) and list(customerId, { status }) (held, denied, finalized, released, expired; newest 100) read holds; another status throws before any request. A missing hold throws hold_not_found (404).
  • Balances gain held (and each source held; entity balances entity_held, shared_held); available already excludes open holds.
  • As with usage.track(), a timestamp the SDK fills in is kept per idempotency key (and per hold for finalize) in this client's memory. Pass timestamp when a retry may come from another process.

Money budgets

Spend limits (Core) cap what a customer's metered usage may cost per period. Needs Engine 2.34.0+.

import { RefusalReason } from "@nozle-js/node";

const decision = await nozle.can("cust_123", "agent_execution");
if (!decision.allowed && decision.reason === RefusalReason.BudgetExceeded) {
  // decision.budget: { limit, spent, held, remaining, currency, period_end, status, ... }
}

const { budgets } = await nozle.budgets.list("cust_123", { subscriptionId: "sub_123" });
  • can(), usage.check() and usage.track() answer allowed: false, reason: "budget_exceeded" with budget when a hard limit covering the Feature is used up; a soft limit never refuses. Compare reason with RefusalReason values; unknown reasons arrive as their string.
  • A plain can() is check-then-call, so calls in flight can overrun a cap. For an exact cap, take a hold: on a Feature billed in money usage.holds.create() returns a budget hold (kind: "budget", amount_held, currency) and refuses with budget_exceeded when the estimated spend does not fit.
  • Where a failed response throws, a 402 budget_exceeded is a BudgetExceededError (with budget when sent) and a 429 usage_limit_exceeded a UsageLimitExceededError; both extend NozleApiError. Through the LLM proxy the provider SDK's own error carries the same code.

Entities and per-user credits

Use Entities for stable customer-owned subjects such as workspace users. Entity mutations require a server-side secret key and a caller-supplied idempotency key.

await nozle.entities.upsert(
  "workspace_123",
  "user_42",
  { name: "Asha", status: "active", metadata: { role: "agent" } },
  { idempotencyKey: "entity-user-42-v1" },
);

const entities = await nozle.entities.list("workspace_123", {
  status: "active",
  limit: 50,
});

const balance = await nozle.credits.getEntityBalance(
  "workspace_123",
  "user_42",
  "ai_credits",
);

console.log(balance.entity_available);
console.log(balance.shared_available);
console.log(balance.effective_available);

Entity subscription checkout

Create one payment for a mixed basket of Entity plans from your trusted backend:

const checkout = await nozle.entitySubscriptions.checkoutMany("workspace_123", {
  billingTime: "anniversary",
  returnUrl: "https://app.example.com/settings/billing",
  idempotencyKey: "workspace-123-seat-purchase-v1",
  items: [
    { externalEntityId: "seat_pro_001", planCode: "pro_monthly" },
    { externalEntityId: "seat_max_001", planCode: "max_monthly" },
  ],
});

For Stripe the result is type: "hosted": redirect the customer to checkout.url. After they return, confirm the outcome as described under "Payment providers" below (a Stripe checkout_id is not a status id). Never expose the secret Nozle key to the browser.

Allocation and deallocation preserve exact decimal strings, source provenance, and expiry. They are backend-only operations and may also be disabled by the Engine's exact organization/Credit System rollout gate.

await nozle.credits.allocate(
  "workspace_123",
  "user_42",
  { creditSystemCode: "ai_credits", amount: "100.000000000001" },
  { idempotencyKey: "allocate-user-42-100" },
);

await nozle.usage.track(
  {
    customerId: "workspace_123",
    entityId: "user_42",
    featureCode: "agent_execution",
    creditSystemCode: "ai_credits",
  },
  { idempotencyKey: "execution-0183f" },
);

Keep the same idempotency key when retrying an uncertain mutation result. Never convert credit amounts to JavaScript numbers.

Workspace suspended or card required (402)

When your Nozle workspace is suspended because its Nozle invoices are unpaid, every API call answers HTTP 402 with code workspace_suspended. A workspace without a verified card answers 402 with code card_required the same way. NozleApiError has status 402 and code workspace_suspended, from can(), track(), usage.check() and every other call; can() throws it instead of returning allowed: false. createBillingHandler passes the code to the browser.

try {
  await nozle.can("cust_123", "code_completion");
} catch (error) {
  if (error instanceof NozleApiError && error.code === "workspace_suspended") {
    // Tell your team to pay the Nozle invoices; do not treat this as allowed or denied.
  }
}

Never retry blindly: the SDK does not retry a 402. Add a card in the Nozle dashboard (card_required) or pay the Nozle invoices (workspace_suspended) and calls work again at once. Events sent during the suspension are refused, not queued.

Customer payment overdue (402)

When one of your customers leaves invoices unpaid past the plan's grace (your dunning settings), Nozle refuses that customer's usage with HTTP 402 and code customer_payment_overdue until the invoices are paid. Other customers are not affected.

  • can() returns { allowed: false, reason: "customer_payment_overdue", used: 0, limit: null, remaining: null } instead of throwing. Show the customer that a payment is overdue and link to your billing page.
  • track(), usage.check() and usage.track() throw NozleApiError with status 402; error.hasCode(CUSTOMER_PAYMENT_OVERDUE) is true. Nothing is recorded.
  • /events/batch stores the other customers' events and answers 200 with error_details keyed by the index of each refused event (EventBatchResponse); refusedEventIndexes(body.error_details, CUSTOMER_PAYMENT_OVERDUE) lists them. When every event is refused it answers 402 and stores nothing; error.refusedEventIndexes(CUSTOMER_PAYMENT_OVERDUE) lists them on the NozleApiError.
  • The LLM proxy answers 402 with code customer_payment_overdue for the X-Nozle-Customer-Id customer before the provider is called. isCustomerPaymentOverdue(error) is true for that error from the Anthropic SDK (it keeps the body in error) and for a NozleApiError. The OpenAI SDK drops a top-level code; with it, call can() before the request to read the reason.
import { CUSTOMER_PAYMENT_OVERDUE, refusedEventIndexes, type EventBatchResponse } from "@nozle-js/node";

const { allowed, reason } = await nozle.can("cust_123", "code_completion");
if (reason === CUSTOMER_PAYMENT_OVERDUE) {
  // Ask the customer to pay the open invoice.
}

const res = await fetch(`${nozleUrl}/api/v1/events/batch`, { method: "POST", headers, body: JSON.stringify({ events }) });
const body = (await res.json()) as EventBatchResponse;
const refused = refusedEventIndexes(body.error_details, CUSTOMER_PAYMENT_OVERDUE); // stored: every other event

Webhooks

nozle.webhooks.verify({ body, headers, secret }) checks a delivery against the raw body and returns the parsed event, or throws WebhookVerificationError. Pass the endpoint's whsec_ secret; during a rotation pass both secrets as an array. The check uses webhook-id, webhook-timestamp and webhook-signature, rejects timestamps more than 300 seconds off (toleranceSeconds changes this) and makes no network call.

import { createWebhookHandler } from "@nozle-js/node";

export const POST = createWebhookHandler(nozle, {
  secret: process.env.NOZLE_WEBHOOK_SECRET,
  onEvent: async (event) => { /* event.id is the same on every retry: skip duplicates */ },
});

Credit notes and refunds

Needs a secret key and a workspace with credit notes enabled (otherwise NozleApiError 403 feature_unavailable). A credit note lowers a finalized invoice; its total is settled by crediting the customer's balance, refunding the original payment method (Stripe or Razorpay, started by Nozle), offsetting what the customer still owes, or a mix.

const items = [{ feeId: "fee_123", amountCents: 500 }]; // feeId: `fees[].nozle_id` in the invoice from GET /invoices/{id}

// 1. Preview: nothing is created. Taxes and coupons are applied.
const preview = await nozle.creditNotes.preview({ invoiceId: "inv_123", items });
preview.max_creditable_amount_cents; // the credit note's total
preview.max_refundable_amount_cents; // what was paid and not refunded yet

// 2a. Refund the items to the original payment method (partial refunds: use fewer or smaller items).
const note = await nozle.creditNotes.refund({ invoiceId: "inv_123", items, reason: "duplicated_charge", metadata: { ticket: "T-42" } });
note.refund_status; // "pending", then "succeeded" or "failed" (webhook credit_note.refund_failure)

// 2b. Or choose the split yourself: the three amounts add up to max_creditable_amount_cents.
await nozle.creditNotes.create({ invoiceId: "inv_123", items, refundAmountCents: 300, creditAmountCents: 200, reason: "order_change" });

// 2c. Money you already paid back yourself (bank transfer, cash): the out-of-band part of the refund is recorded, never sent to a provider.
await nozle.creditNotes.create({ invoiceId: "inv_123", items, refundAmountCents: 500, outOfBandRefundAmountCents: 500, outOfBandRefundReference: "TRX-42" });

await nozle.creditNotes.list({ customerId: "cus_1", refundStatus: "failed" });
await nozle.creditNotes.get(note.nozle_id);
await nozle.creditNotes.void(note.nozle_id); // voids the unused credit; never undoes a paid refund or an offset

reason is one of duplicated_charge, product_unsatisfactory, order_change, order_cancellation, fraudulent_charge, other (default). refund() throws refund_exceeds_paid_amount and creates nothing when less was paid than the items are worth; pass creditRemainder: true to refund what was paid and credit the rest.

The SDK sends no Idempotency-Key with credit note requests yet (Core 11.22.0 accepts one on create), so create(), refund() and void() are never retried, whatever maxRetries says; preview(), get() and list() are. After a network error or a 5xx on create(), call list({ customerId, invoiceNumber }) before trying again. Errors are NozleApiError; test them with error.hasCode(CREDIT_NOTE_ERROR_CODES.cannotRefundUnpaidInvoice) (also higherThanRemainingInvoiceAmount, higherThanRemainingFeeAmount, doesNotMatchItemAmounts, invalidTypeOrStatus, noVoidableAmount). From Core 11.46.0 an online refund the invoice's provider payments cannot take is refused with manualRefundRequired (manual payment, or only marked paid), providerRefundUnsupported (a provider Nozle cannot refund through) or insufficientRefundableAmount; record it with outOfBandRefundAmountCents instead (higherThanRefundAmount when that is above refundAmountCents). Nozle stores only the provider's refund id and status, never card or bank details.

Health Check

const status = await nozle.ping();
// { ok: true, engine: "ok" }

Margin Intelligence

Requires a secret key (sk_ prefix).

const summary = await nozle.margin.summary();
const byCustomer = await nozle.margin.byCustomer();
const byMetric = await nozle.margin.byMetric();
const byPlan = await nozle.margin.byPlan();
const byModel = await nozle.margin.byModel();
const trend = await nozle.margin.trend({ granularity: "day" });
const simulation = await nozle.margin.simulate({ metricCode: "agent_execution", newPriceDollars: 1 });

// With time range
const q1 = await nozle.margin.summary({
  from: "2025-01-01T00:00:00Z",
  to: "2025-03-31T23:59:59Z",
});

Cost Intelligence

const report = await nozle.costIntelligence.report({ from: "2026-10-01T00:00:00Z", limit: 50 });
const preview = await nozle.costIntelligence.previewSharedCostAllocation(poolId, {
  allocationPeriodStart: "2026-10-01T00:00:00Z",
});
// Books a closed period now; Nozle also books it within about 15 minutes of the close.
const run = await nozle.costIntelligence.allocateSharedCost(poolId, { allocationPeriodStart: "2026-10-01T00:00:00Z" });

Plans & Checkout

// List available plans
const plans = await nozle.plans();
// The pricing table view: without plan families and features hidden from it
const visible = await nozle.plans({ includeHidden: false });
// Archived plans (secret key): they take no new subscriptions, existing ones keep billing
const archived = await nozle.plans({ status: "archived" });

// Create checkout from an authenticated merchant route.
const checkout = await nozle.checkout(
  "cust_123",
  "pro",
  "https://merchant.example/billing/complete",
);

// Create subscription after payment
const { subscription_id, status } = await nozle.subscribe("cust_123", "pro");

Currencies

A plan family can be sold in several currencies, one plan per interval and currency. With a secret key, plans() lists every plan in every currency; plans({ currency }) lists only that currency, and plans({ externalCustomerId }) only the customer's locked currency (ignored when your organization allows several currencies per customer). A publishable key without currency gets each family's default-currency plans, as the React pricing table shows them. A family plan carries family (code, currencies, default_currency) and prices (every variant: currency, interval, plan_code, amount_cents). An unknown currency is a 422.

checkout() and subscribe() take { planFamilyCode, interval, currency } instead of a plan code; Core picks the variant. Without currency it uses the customer's locked currency, else the family's default. Needs Core 11.10.0.

const eurPlans = await nozle.plans({ currency: "EUR" });
await nozle.checkout("cust_123", { planFamilyCode: "pro", interval: "yearly", currency: "EUR" }, returnUrl);

Plan versions

Changing the price of a plan that customers pay for saves it as the plan's next version: new customers get the new version, and existing subscribers keep the price they bought until you move them. plans() returns current versions only; each plan has version and is_current.

// Keep selling the older price to one customer.
await nozle.subscribe("cust_123", "pro", { planVersion: 1 });

const versions = await nozle.planVersions.list("pro"); // every version, its price and active subscriptions
const older = await nozle.planVersions.get("pro", 1);

// Move version 1's subscribers to the current version, each at the end of its billing period.
const preview = await nozle.planVersions.previewMigration("pro", { fromVersion: 1 });
const migration = await nozle.planVersions.createMigration("pro", { fromVersion: 1 });
const detail = await nozle.planVersions.getMigration("pro", migration.nozle_id); // per-subscription items
await nozle.planVersions.cancelMigration("pro", migration.nozle_id); // unschedules moves not started

A migration invoices, credits and refunds nothing when it runs: each subscription is billed the new version from its next period. Subscriptions it cannot move (custom pricing, a trial the new version would change, a pending plan change, an open checkout, and so on) are skipped with a skip_reason. Sending the same plan code again for an existing subscription keeps its version; another planVersion for it is refused. planVersions needs a secret key. See Plan versioning.

Payment providers: Stripe and Razorpay

Nozle collects through the payment provider connected to your organization and assigned to the customer. checkout() and checkoutInvoice() return a result whose type tells you what to do next. Branch on type; a browser callback alone never proves payment.

| type | Provider | Next step | | --- | --- | --- | | hosted | Stripe, Razorpay link | Redirect the customer to url (the Stripe Checkout page; payment_url is the same address), then confirm as described below (Stripe: checkout_id is the Stripe session id, not a status id) | | razorpay | Razorpay | Open the Razorpay modal with key_id, order_id, amount_cents and currency, then verify | | processing | Razorpay or Stripe | Recover with checkoutStatus(checkout_id) instead of starting another checkout. Razorpay returns it while the order is not ready; Stripe returns it when a quoted upgrade is replayed while its webhook is still pending | | completed, scheduled | Either | No payment is due now. Credits covered it, or the change takes effect later |

Stripe. Every Stripe checkout is the Stripe-hosted Checkout page; there is no embedded form. checkout_id of a Stripe result is the Stripe session id (cs_...); checkoutStatus does not accept it. An upgrade session lasts 35 minutes, an Entity batch 23 hours. Redirect the customer to url. Pass cancelUrl in the options to choose where Stripe sends a customer who leaves the page (validated like returnUrl, defaults to it). A return URL may contain the literal {CHECKOUT_SESSION_ID}, which Stripe replaces with the Checkout Session id. Credit top-up purchases also return a Stripe-hosted payment_url (valid for 24 hours).

import { Nozle } from "@nozle-js/node";

const nozle = new Nozle({ apiKey: process.env.NOZLE_SECRET_KEY! });
const returnUrl = "https://app.example.com/settings/billing";

const result = await nozle.checkout("cust_123", "pro_monthly", returnUrl, {
  cancelUrl: "https://app.example.com/pricing",
});
if (result.type === "hosted") {
  // Redirect the customer to result.url.
  // Paid upgrade (result.plan_upgrade_intent_id): after they return, poll
  //   nozle.checkoutStatus(result.plan_upgrade_intent_id, { customerId, subscriptionId });
  //   status is awaiting_payment (hosted nested), processing, succeeded or expired.
  // New subscription or invoice (result.invoice_id): there is no status call. The customer
  //   returns to your return URL; confirm with the invoice.payment_succeeded or subscription
  //   webhook, or by reloading billing state (can() or the subscription read).
}

A new-subscription checkout retried while the first attempt is unpaid reopens payment for the same invoice when the plan is the same (or returns completed if it was paid meanwhile). For another plan, the unpaid attempt is expired and replaced, or the request gets HTTP 409 subscription_checkout_in_progress (entity_subscription_checkout_in_progress for an Entity checkout) when it cannot be expired yet. Keep the body identical for one idempotency key: a different request with the same key gets HTTP 409 idempotency_key_reused, including an invoice checkout. Checkout error bodies carry status, error and code.

Razorpay. Razorpay supports only INR. Return the razorpay result to the browser, open the modal there, and post the handler's three fields back to your backend. verifyCheckout() sends them to Nozle, which checks the signature and fetches the payment from Razorpay; the SDK does not check the signature locally. Verify and status need an sk_ key.

// Backend: create. `checkout` is { type: "razorpay", checkout_id, key_id, order_id,
// amount_cents (paise), currency: "INR", expires_at, invoice_id | plan_upgrade_intent_id }.
const checkout = await nozle.checkout("cust_123", "pro_monthly", returnUrl, {
  idempotencyKey: "checkout-cust_123-pro_monthly-v1",
  // registerMandate: true, // UPI AutoPay; the result then also has customer_id,
  //                       // recurring and mandate_max_amount_cents
});
if (checkout.type !== "razorpay") throw new Error("not a Razorpay checkout");

// Browser (after loading https://checkout.razorpay.com/v1/checkout.js):
//   new window.Razorpay({ key: checkout.key_id, order_id: checkout.order_id,
//     amount: checkout.amount_cents, currency: checkout.currency, handler }).open()
// For a mandate also pass customer_id: checkout.customer_id and recurring: "1".

// Backend: verify what the handler returned (`body` is the JSON your browser posted),
// then poll until both statuses succeed.
const scope = { customerId: "cust_123", subscriptionId: "sub_123" };
await nozle.verifyCheckout(checkout.checkout_id, {
  razorpay_order_id: body.razorpay_order_id,
  razorpay_payment_id: body.razorpay_payment_id,
  razorpay_signature: body.razorpay_signature,
}, scope);
const status = await nozle.checkoutStatus(checkout.checkout_id, scope);
// status.status: awaiting_payment | processing | succeeded | failed | expired | needs_review
// Show success only when status.status and status.fulfillment_status are both "succeeded".

Bind each checkout_id to the buyer who started it before you call verify or status. Pass both scope fields to tie a call to one customer and subscription.

Provider errors are NozleApiError instances with status, code and errorDetails. hasCode() matches the top-level code and the codes listed in error_details, for example razorpay_requires_inr, payment_provider_required or invalid_checkout_signature.

import { NozleApiError } from "@nozle-js/node";

try {
  await nozle.checkout("cust_123", "pro_monthly", returnUrl);
} catch (error) {
  if (error instanceof NozleApiError && error.hasCode("razorpay_requires_inr"))
    // Price the plan in INR for customers who pay through Razorpay.
    return;
  throw error;
}

See the Stripe and Razorpay integration guides for connection setup, webhooks, and limits.

Cancel a subscription

Cancellation is server-only and requires an sk_ key. Without a timing, the organization's cancellation timing applies (set in the dashboard; new organizations default to end_of_period; existing organizations keep their setting). Pass the timing to choose it per call:

const result = await nozle.cancelSubscription("cust_123", "sub_123", "end_of_period");
// result.subscription.status === "active"
// result.subscription.ending_at === "2026-08-15T00:00:00Z"

Pass an options object to also choose how the cancellation is settled. Each option left out follows the subscription, then the organization's cancellation settings:

await nozle.cancelSubscription("cust_123", "sub_123", {
  policy: "immediate",
  creditAction: "refund", // credit, refund, offset or none
  refundMode: "prorated", // prorated or full
  finalInvoiceAction: "generate", // generate or skip
});

Extend or end a trial

Server-only (sk_ key). trial takes exactly one of extend_days, ends_at or convert, plus an optional reason (up to 500 characters); giving none or several throws NozleValidationError before any request. A trial can be extended by at most 90 days at a time and can last at most 365 days in total (the server enforces both).

await nozle.extendTrial("sub_123", { days: 14, reason: "sales call" });
await nozle.extendTrial("sub_123", { endsAt: "2026-12-01T00:00:00Z" }); // at least 30 minutes ahead
const { subscription } = await nozle.convertTrial("sub_123"); // ends the trial now, starts paid billing
// subscription.in_trial === false, subscription.trial_ends_at, subscription.trial_ended_at

await nozle.updateSubscription("sub_123", { trial: { extend_days: 7 } }); // the general call

Convert bills at period end on a pay-in-arrears plan and invoices at once on pay-in-advance; payment follows the normal collection flow and a failed payment does not undo the conversion. Refusals are NozleApiError; test with error.hasCode(TrialErrorCode.NotActive) (trial_invalid_params, trial_not_active, trial_extension_too_long, trial_end_in_past, payment_method_required, and plan_change_pending as a 409). These calls are not retried.

TypeScript

All methods and responses are fully typed. Exported types:

import type {
  NozleConfig,
  TrackOptions,
  CanResult,
  Plan,
  CheckoutResult,
  CheckoutStatus,
  RazorpayCheckoutResult,
  SubscribeResult,
  MarginQueryParams,
  TrendParams,
  PingResult,
  CustomerUpsertParams,
  CustomerUpsertResult,
  CheckAndDeductParams,
  CheckAndDeductResult,
  WrapOptions,
} from "@nozle-js/node";

React billing portal subscription management

See the runnable authenticated merchant integration for Cancel, Keep, payment-backed upgrades, scheduled downgrades, and exact pending-change withdrawal through the React billing portal. It reuses the existing transition methods and derives customer identity from the merchant session. For end-of-period cancellation, optional expectedEffectiveAt preserves the exact preview timestamp and rejects a changed date atomically on compatible Engine/Core deployments. Existing calls without this option remain compatible.

Version 0.9.0 adds subscriptionOptions(customerId, subscriptionId), previewSubscriptionChange(customerId, subscriptionId, planCode), and withdrawPendingSubscriptionChange(customerId, subscriptionId, pendingSubscriptionId, idempotencyKey). Use the existing checkout/transition methods with the selected subscription, signed quote, and a stable action key. Scope checkoutStatus and verifyCheckout with both customer and subscription identifiers. See the method examples.

License

MIT. See LICENSE.