AiTokenTracker TypeScript SDK

@ai-token-tracker/sdk captures LLM request/response envelopes and sends them to your ingest API.

This v1 package mirrors the .NET SDK wrapper and explicit ingest behavior:

1. AiTokenTrackerIngestionClient for direct envelope ingest.
2. AiTokenTrackerSdkClient + call scope for provider SDK wrappers.

Installation

npm install @ai-token-tracker/sdk

Requirements

• Node.js 18+

Configuration

import { AiTokenTrackerIngestionClient } from "@ai-token-tracker/sdk";

const ingestionClient = new AiTokenTrackerIngestionClient({
  authToken: "your-subscription-or-api-key",
  enableAutoInterception: true, // optional
});

enableAutoInterception defaults to true.

Wrapper Integration (beginLlmCall)

import {
  AiTokenTrackerIngestionClient,
  AiTokenTrackerSdkClient,
} from "@ai-token-tracker/sdk";

const ingestionClient = new AiTokenTrackerIngestionClient({
  authToken: process.env.AI_TOKEN_TRACKER_API_KEY ?? "",
});

const tracker = new AiTokenTrackerSdkClient(ingestionClient);

const scope = tracker.beginLlmCall(
  {
    model: "gpt-4.1-mini",
    input: "hello",
  },
  {
    additionalCustomFilters: {
      Workflow: "Example",
    },
  },
  "openai",
);

try {
  const providerResponse = {
    id: "resp_123",
    usage: {
      input_tokens: 42,
      output_tokens: 11,
    },
  };

  void scope.complete(providerResponse, { statusCode: 200 });
} catch (error) {
  void scope.fail(error, { statusCode: 500 });
  throw error;
}

Explicit Ingest (track)

import { AiTokenTrackerIngestionClient } from "@ai-token-tracker/sdk";

const ingestionClient = new AiTokenTrackerIngestionClient({
  authToken: "your-subscription-or-api-key",
});

await ingestionClient.track({
  providerHint: "anthropic",
  method: "POST",
  requestBody: JSON.stringify({ model: "claude-sonnet-4-6" }),
  responseBody: JSON.stringify({ id: "msg_123" }),
  statusCode: 200,
  requestHeaders: {
    "content-type": ["application/json"],
  },
  responseHeaders: {
    "x-request-id": ["request_123"],
  },
  additionalCustomFilters: {
    Workflow: "ManualIngest",
  },
});

Automatic HTTP Interception

Use SDK-managed interception for outbound LLM calls made through global fetch:

import { AiTokenTrackerIngestionClient } from "@ai-token-tracker/sdk";

const ingestionClient = new AiTokenTrackerIngestionClient({
  authToken: process.env.AI_TOKEN_TRACKER_API_KEY ?? "",
  enableAutoInterception: true,
});

// Any classified LLM fetch call is automatically ingested.
await fetch("https://api.openai.com/v1/responses", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.OPENAI_API_KEY}` },
  body: JSON.stringify({ model: "gpt-4.1-mini", input: "hello" }),
});

// Optional: call when shutting down app processes that no longer need interception.
ingestionClient.dispose();

Scoped Custom Filters For Automatic Interception

You can register interception once, then apply custom filters anywhere through async scope context:

import {
  AiTokenTrackerIngestionClient,
  createAiTokenTrackerInterceptionScope,
  withAiTokenTrackerInterceptionScope,
} from "@ai-token-tracker/sdk";

const _ = new AiTokenTrackerIngestionClient({
  authToken: process.env.AI_TOKEN_TRACKER_API_KEY ?? "",
  enableAutoInterception: true,
});

const scope = createAiTokenTrackerInterceptionScope({
  Workflow: "CheckoutFlow",
});

scope.addCustomFilters({ Tenant: "acme" });

await withAiTokenTrackerInterceptionScope(scope, async () => {
  await fetch("https://api.openai.com/v1/responses", {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.OPENAI_API_KEY}` },
    body: JSON.stringify({ model: "gpt-4.1-mini", input: "hello" }),
  });
});

Manual lifecycle option:

const scope = createAiTokenTrackerInterceptionScope({
  Workflow: "CheckoutFlow",
});

scope.addCustomFilters({ Tenant: "acme" });

try {
  await fetch("https://api.openai.com/v1/responses", {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.OPENAI_API_KEY}` },
    body: JSON.stringify({ model: "gpt-4.1-mini", input: "hello" }),
  });
} finally {
  scope.close();
}

Error Handling Behavior

Like the .NET SDK, ingest attempts are non-throwing by default:

• transport failures return success: false
• non-2xx responses return success: false with statusCode
• optional logger.warn(...) hooks can capture warning/error context