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.

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",
    featureId: "chat-assistant",
  });
}

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: when an enforcement check is required, the SDK awaits up to ~800ms for a KV flag lookup and may rewrite the request body. In normal traffic the gate short-circuits in single-digit milliseconds. 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

Set featureId at init time, or pass it per-request via the AtlasBurn context helper. 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