opentoken-sdk — Node.js SDK for Open Token

Non-blocking usage reporting for LLM calls. Ships events off the caller's hot path via a background timer; batches, retries, and drops gracefully when the network flakes.

Requires Node.js 18+. Uses the built-in fetch and AsyncLocalStorage.

Install

npm install opentoken-sdk

Using UsageReporter directly

import { UsageReporter } from "opentoken-sdk";

const reporter = new UsageReporter({
  openTokenApiKey: process.env.OPENTOKEN_API_KEY,
  tags: { service: "checkout-api", env: "prod" },
  batch: true, // default; set false to POST one event at a time
});

const response = await providerClient.chat.completions.create({ /* ... */ });

reporter.reportUsage({
  response,
  latencyMs: 1234,
  tags: { workflow_id: "abc" },
});

reportUsage(...) pushes the event onto an in-memory queue and returns synchronously (~microseconds on the caller's thread). A background timer flushes the queue to /v1/usage:batch. You don't manage the timer — it starts lazily on your first call and is unref'd so it never holds the event loop open.

OpenAI Agents SDK integration

If you're using the OpenAI Agents SDK for JavaScript, register the tracing bridge once at startup and every run(...) will forward its LLM spans to Open Token. You never call reportUsage yourself.

npm install @openai/agents

import { UsageReporter, withTags } from "opentoken-sdk";
import { registerTrace } from "opentoken-sdk/integrations/agents";
import { Agent, run } from "@openai/agents";

const reporter = new UsageReporter({
  openTokenApiKey: process.env.OPENTOKEN_API_KEY,
  tags: { env: "prod" },
});
await registerTrace(reporter);

const salesAgent = new Agent({
  name: "sales_agent",
  model: "gpt-5.5",
  instructions: "...",
});

async function handle(customerId: string, question: string) {
  return withTags({ customer_id: customerId, agent_name: "sales" }, () =>
    run(salesAgent, question),
  );
}

Every event that flows out of that run(...) lands with the merged tag set — reporter defaults + whatever's active in the surrounding withTags block.

The integration only reports on generation and response spans (the ones that carry model + usage). Agent/handoff/function/guardrail/ mcp_tools spans are ignored — they don't consume tokens.

withTags(tags, fn) — dynamic per-request tags

withTags is the customer-facing knob for tags that vary per request: customer_id, session_id, workflow, whatever. It uses AsyncLocalStorage so:

• Async-safe. Concurrent tasks each maintain their own tag scope.
• Nested. Inner blocks inherit outer tags and override on collisions.
• Works with both flows. Whether the event is emitted by a future framework integration or by a manual reporter.reportUsage(...) call, the same ambient stack is read.

import { UsageReporter, withTags } from "opentoken-sdk";

const reporter = new UsageReporter({
  openTokenApiKey: process.env.OPENTOKEN_API_KEY,
  tags: { env: "prod" },
});

async function handle(customerId: string, question: string) {
  return withTags(
    { customer_id: customerId, agent_name: "sales" },
    async () => {
      const response = await openai.chat.completions.create({ /* ... */ });
      reporter.reportUsage({ response });
      return response;
    },
  );
}

Tag precedence (highest wins)

For any event, tags merge in this order:

1. new UsageReporter({ tags: ... }) — reporter defaults, static, process-wide
2. withTags({ ... }, fn) — ambient, request-scoped
3. reportUsage({ tags: ... }) — per-call, most specific

Later layers override earlier ones on key collisions.

Failure modes

• HTTP failure (5xx, timeout, network blip). The batch is retried up to 3 times with exponential backoff + jitter, then dropped and counted in stats().dropped. The reporter keeps running.
• 429 rate limit. Honors Retry-After if the server sends it, otherwise backs off. Counts toward the retry budget.
• 4xx (non-429). Retrying won't help — dropped immediately.
• Queue full. reportUsage returns false and bumps dropped. The caller never blocks.
• Process exit. process.on("beforeExit") triggers a bounded flush. beforeExit does NOT fire on SIGINT, SIGTERM, or process.exit() — for short-lived scripts, call await reporter.flush() before exit to guarantee delivery.

Inspect reporter.stats() any time — sent, dropped, retried, batchesFlushed, queueDepth.

Response shape

Both /v1/usage and /v1/usage:batch return the same positional bool array — one element per input event:

{ "results": [true, false, true] }

Each true means the event was accepted; each false means it failed (unknown model, missing usage block, etc.). The SDK counts true events toward sent and retries false events up to maxRetries times.

HTTP status is 200 for any well-formed request — individual event failures are surfaced inside results, not at the HTTP layer. Endpoints return 4xx only for whole-request problems (auth, malformed JSON, oversized batch).

Development

npm install
npm run test        # vitest
npm run typecheck   # tsc --noEmit
npm run build       # tsup → dist/