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, and Google Vertex AI. Everything else (Mistral, DeepSeek, xAI, Cohere, Meta/Llama, OpenRouter) is supported via the Cloudflare Edge Proxy or by posting events directly to /api/ingest.

Installation

npm install @atlasburn/sdk

Auto-Detect Initialization

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

initAtlasBurnAuto({
  apiKey: process.env.ATLASBURN_KEY!,
  // optional
  projectId: "your-project-id",
  featureId: "chat-assistant",
});

What the SDK auto-captures:

• OpenAI — api.openai.com
• Anthropic — api.anthropic.com
• Google Gemini & Vertex AI — generativelanguage.googleapis.com, Vertex endpoints

Anything else needs the proxy. The pricing registry knows Meta/Llama, Mistral, DeepSeek, xAI, and Cohere — they are priced but not yet auto-captured.

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() {
  if (process.env.ATLASBURN_KEY) {
    initAtlasBurnAuto({ apiKey: process.env.ATLASBURN_KEY });
  }
}

Node.js / Express

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

// Initialize BEFORE importing any AI client.
initAtlasBurnAuto({ apiKey: process.env.ATLASBURN_KEY! });

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

Edge cases

• Do not await the SDK init call — it should be fire-and-forget.
• Custom HTTP clients that bypass globalThis.fetch won't be intercepted. Route them through the proxy.
• License: Apache-2.0. See License.

Next Steps

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