@noburn/sdk

Hard LLM spend enforcement for Node.js — pre-call budget checks and per-user metering.

Check a planned LLM call against project-, per-user-, and per-run budget caps before you make it, then record what it actually cost.

Install

npm install @noburn/sdk

Requires Node.js ≥ 18 (uses the global fetch).

Quick start

import { NoburnGuard } from '@noburn/sdk';

const guard = new NoburnGuard({
  apiKey: process.env.NOBURN_API_KEY!,
  projectId: process.env.NOBURN_PROJECT_ID!,
  budgetCapUsd: 10,          // optional local fallback cap
  onError: 'allow',          // 'allow' (default, fail-open) | 'block' (fail-closed)
});

const decision = await guard.check({
  model: 'gpt-4o',
  estimatedTokensIn: 1000,
  estimatedTokensOut: 300,
  endUserId: 'user_123',     // optional — enforces that user's cap
});

if (decision.blocked) {
  throw new Error(`Blocked by noburn: ${decision.blockReason}`);
}

// ... make your LLM call ...

await guard.record({
  model: 'gpt-4o',
  tokensIn: 980,
  tokensOut: 290,
  costUsd: 0.005,
  wasBlocked: false,
  endUserId: 'user_123',
});

record() is fire-and-forget — it returns immediately and never throws, so it adds no latency to your call path.

Agent runs

Bound a single agent invocation with its own cap:

const run = await guard.startRun({ budgetCapUsd: 0.5 });

const decision = await guard.check({
  model: 'gpt-4o',
  estimatedTokensIn: 1000,
  estimatedTokensOut: 300,
  runId: run.runId,
});

await guard.record({ /* ... */, runId: run.runId });

const summary = await guard.endRun(run.runId); // { status, spendUsd, ... }

Behavior

• check() never throws except NoburnAuthError (bad key). Every call asks the server for an authoritative decision; if the server is unreachable it falls back to a local in-memory check.
• onError controls that fallback when nothing local blocks the call: 'allow' (default) fails open so a noburn outage never breaks your app; 'block' fails closed (blockReason: 'noburn_unreachable').
• startRun() throws on network/auth error (NoburnTimeoutError on timeout) — a run must be registered before you proceed.

License

MIT