SDK Integration

Summary

The AtlasBurn SDK patches globalThis.fetch at boot and captures usage from any call to a recognized AI provider host — OpenAI, Anthropic, Google Gemini, Google Vertex AI, Azure OpenAI, OpenRouter, Cohere, Mistral, Groq, Together AI, DeepSeek, xAI, and AWS Bedrock (best-effort). The only thing it can't auto-detect is a self-hosted model with no fixed public host (e.g. your own Llama endpoint) — capture that via the Cloudflare Edge Proxy or by posting events directly to /api/ingest.

Installation

npm install @atlasburn/sdk

Quick setup — the abn CLI

The SDK ships a zero-copy-paste CLI. From your project root:

npx abn init

abn init detects your framework and env file, auto-detects providers, asks for your ingest key (hidden input, sanitized + abn_-prefix validated), shows a diff of exactly what it will change and asks before writing, wires up initialization (instrumentation.ts for Next.js, an auto-injected import for Node), and runs a verification test. Use --dry-run to preview and --yes for CI.

On plain Node apps the added atlasburn.js reads ATLASBURN_KEY from .env when the environment doesn't already set it (so npm start works without dotenv; a key set by your hosting platform always wins). CommonJS projects get a require() version; the package loads under require() on Node 20.19+ / 22.12+. Re-running abn init upgrades an untouched file from an older CLI.

Non-interactive options:

• abn init --code abset_… --yes — redeem a one-time setup code (what Claude uses in the MCP integration flow); the key is created and written without ever being shown
• abn init --code abset_… --proxy --yes — Edge Proxy: write the key only and print each provider's proxy base URL (works for any language)
• ATLASBURN_KEY=abn_… npx abn init --yes — take an existing key from the environment instead of prompting

Other commands (run via npx abn <cmd>):

• abn test — verify your key + connectivity; sends one verification event
• abn status — current guardrail state (active / throttled / suspended)
• abn doctor — environment diagnostics + fixes

Auto-Detect Initialization

import { initAtlasBurnAuto } from "@atlasburn/sdk";

// The if-guard narrows ATLASBURN_KEY to string, so it type-checks under
// strict: true without a non-null ! assertion. No key -> AtlasBurn stays dormant.
if (process.env.ATLASBURN_KEY) {
  initAtlasBurnAuto({
    apiKey: process.env.ATLASBURN_KEY,
    // optional
    projectId: "your-project-id",
    metadata: { featureId: "chat-assistant" }, // default feature for untagged calls
  });
}

What the SDK auto-captures (recognized hosts, patched on globalThis.fetch):

• OpenAI — api.openai.com
• Anthropic — api.anthropic.com
• Google Gemini & Vertex AI — generativelanguage.googleapis.com, vertexai.googleapis.com
• Azure OpenAI — *.openai.azure.com (deployment-scoped host; SDK-only)
• OpenRouter — openrouter.ai
• Cohere — api.cohere.com / api.cohere.ai
• Mistral — api.mistral.ai
• Groq — api.groq.com
• Together AI — api.together.xyz / api.together.ai
• DeepSeek — api.deepseek.com
• xAI (Grok) — api.x.ai
• AWS Bedrock — bedrock-runtime (token counts from response headers; best-effort)

The only thing the SDK can't auto-detect is a self-hosted model with no fixed public host (e.g. your own Llama gateway). It's still priced by the registry — capture it through the proxy or by posting to /api/ingest.

Next.js (App Router)

Use the Next.js Instrumentation hook. Do not initialize inside layout.tsx — it is cached.

import { initAtlasBurnAuto } from "@atlasburn/sdk";

export function register() {
  // The if-guard narrows ATLASBURN_KEY from string | undefined to string, so this
  // type-checks under strict: true (no non-null ! needed). No key -> stays dormant.
  if (process.env.ATLASBURN_KEY) {
    initAtlasBurnAuto({ apiKey: process.env.ATLASBURN_KEY });
  } else {
    console.warn("[AtlasBurn] ATLASBURN_KEY not set - telemetry disabled.");
  }
}

Node.js / Express

import { initAtlasBurnAuto } from "@atlasburn/sdk";

// Initialize ONCE at the very top - BEFORE importing any AI client - so the fetch
// auto-patch is active before the first LLM call. The if-guard narrows
// ATLASBURN_KEY to string (type-safe under strict: true); no key -> stays dormant.
if (process.env.ATLASBURN_KEY) {
  initAtlasBurnAuto({ apiKey: process.env.ATLASBURN_KEY });
} else {
  console.warn("[AtlasBurn] ATLASBURN_KEY not set - telemetry disabled.");
}

import OpenAI from "openai";

Verifying the install

import { verifyAtlasBurn } from "@atlasburn/sdk";

await verifyAtlasBurn({
  apiKey: process.env.ATLASBURN_KEY!,
  debug: true,
});

Overhead — honest numbers

Telemetry flush is fire-and-forget and adds no synchronous cost. The pre-call guardrail gate is different: the SDK reuses each feature's gate decision for 10 seconds and serves a slightly stale one (up to 60s) while refreshing in the background, so most AI calls never wait on it. When a call does have to wait, the check gives up after 2.5 seconds and lets the call through (fail open). Both are configurable via gateCacheMs and gateTimeoutMs.

Throttling (1.10+). When your guardrail tier throttles a feature, the SDK spaces that feature's calls 2 seconds apart (throttleSpacingMs). The calls still succeed; other features are not slowed. If so many calls queue up that one would wait more than 10 seconds (throttleMaxWaitMs), it gets a blocked 429 with x-atlasburn-reason: guardrail_throttled instead of stalling your app. Alert mode never slows a call. Telemetry batches flush approximately every 5 seconds; an event typically appears in the Forensic Ledger within ~5–10 seconds of the upstream response.

Feature attribution

Tag AI calls with the product feature they belong to. AtlasBurn then breaks spend down by feature, and if one feature loops, the guardrails pause only that feature while the rest of your app keeps running (see What gets blocked).

Per call: pass atlasburnFeature() as request headers. The SDK reads the tag and strips it before the request reaches the provider.

import { atlasburnFeature } from "@atlasburn/sdk";

await anthropic.messages.create(params, { headers: atlasburnFeature("support-chat") });
await openai.chat.completions.create(params, { headers: atlasburnFeature("search") });

One feature per process (a worker, a cron job): set a default at init with metadata: { featureId: "nightly-digest" }. A per-call tag always wins over the default. Calls with neither are grouped as untagged, so a loop in one of them pauses all untagged traffic. Tagging is what keeps a loop contained to one feature.

Feature names are trimmed to 100 characters; anything other than letters, digits, . _ : / - becomes a dash. There is no withAtlasBurn client wrapper; that API was removed before 1.0.

The 4 Laws of SDK Safety

1. Never block — telemetry is async, fire-and-forget
2. Never crash — all telemetry logic is wrapped in try/catch
3. Never leak — background queue is capped at 200 events
4. Never persist secrets — raw API keys are HMAC-SHA-256 hashed; never stored in plaintext

Retry and Queue Behavior

• Retries: 3 attempts with exponential backoff on ingest failure
• Queue limit: 200 events
• On failure: events drop silently after the retry budget is exhausted

Supported Runtimes

What won't be captured (and the fix)

The SDK captures a call only when it goes through the global fetch, to a recognized host, in the same process where init ran, and init ran first. Break any of those and it silently won't see the call:

• Non-fetch HTTP clients — axios (in Node it uses http/https, not fetch), got, superagent, raw http.request, and gRPC clients. This includes AWS Bedrock via @aws-sdk/client-bedrock-runtime and Vertex via gRPC, which don't use global fetch.
• A non-global fetch — a library importing node-fetch/undici as a local binding, or passing a custom fetch to a provider SDK (new OpenAI({ fetch })).
• Init timing / runtime split — a fetch reference captured before init; the AI call running in a different runtime (Edge vs Node), worker thread, or process where init didn't run; or Node < 18 (no global fetch).
• Unrecognized host — Ollama/localhost, self-hosted vLLM/LM Studio, Perplexity, Fireworks, Replicate, or a custom gateway whose hostname isn't in the allowlist.

The fix for anything the SDK can't patch: route the provider base URL through the Edge Proxy, which captures regardless of HTTP client — with one caveat: Azure OpenAI, Vertex, and Bedrock are host-bound / signed and can't be transparently proxied (SDK-only). A non-fetch client calling one of those three is the one genuine gap today.

Edge cases

• Do not await the SDK init call — it should be fire-and-forget.
• License: Apache-2.0. See License.

Next Steps

• Proxy Quickstart — language-agnostic capture
• Telemetry Architecture — pipeline deep dive
• Integrations — provider matrix