token-warden 1.0.0

package/README.md

@@ -0,0 +1,133 @@
+# Token Warden
+
+Track LLM costs per feature, team, and user — with budget alerts and anomaly detection.
+
+[![npm version](https://img.shields.io/npm/v/token-warden)](https://www.npmjs.com/package/token-warden)
+[![CI](https://github.com/Flagship-Software/token-warden/actions/workflows/ci.yml/badge.svg)](https://github.com/Flagship-Software/token-warden/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Why
+
+LLM API costs are opaque and hard to attribute. When multiple features share the same API keys, you can't tell which feature is responsible for cost spikes. Token Warden wraps your LLM clients to automatically capture token usage and attribute costs per feature.
+
+## Quick Start
+
+```bash
+npm install token-warden
+```
+
+```typescript
+import { warden } from "token-warden";
+import OpenAI from "openai";
+
+// Initialize Token Warden
+warden.init({
+  apiKey: "tw_your_api_key",
+  endpoint: "https://your-token-warden-endpoint.com/v1/events",
+});
+
+// Wrap your OpenAI client — tracking happens automatically
+const openai = warden.wrap(new OpenAI(), {
+  feature: "chat-support",
+  team: "cx-team",
+});
+
+// Use the client as usual
+const response = await openai.chat.completions.create({
+  model: "gpt-4o",
+  messages: [{ role: "user", content: "Hello!" }],
+});
+
+// In serverless environments, flush before the function exits
+await warden.flush();
+```
+
+## Manual Tracking
+
+For custom providers or direct HTTP calls that bypass SDK clients, use `warden.track()` to record usage manually.
+
+```typescript
+warden.track({
+  provider: "together",
+  model: "llama-3.1-70b",
+  feature: "document-summary",
+  inputTokens: 1200,
+  outputTokens: 350,
+  durationMs: 820,
+});
+```
+
+## Supported Providers
+
+| Provider             | SDK Pattern             | Auto-detected |
+| -------------------- | ----------------------- | ------------- |
+| OpenAI               | `new OpenAI()`          | ✓             |
+| Anthropic            | `new Anthropic()`       | ✓             |
+| Google Generative AI | `new GoogleGenerativeAI()` | ✓          |
+| Amazon Bedrock       | `new BedrockRuntimeClient()` | ✓       |
+| DeepSeek             | `new OpenAI()` (compatible) | ✓        |
+| Mistral              | `new Mistral()`         | ✓             |
+| xAI                  | `new OpenAI()` (compatible) | ✓        |
+| Cohere               | `new CohereClient()`    | ✓             |
+
+## API Reference
+
+### `warden.init(config)`
+
+Initialize Token Warden. Call once at application startup.
+
+| Parameter   | Type     | Required | Description                                      |
+| ----------- | -------- | -------- | ------------------------------------------------ |
+| `apiKey`    | `string` | Yes      | Your Token Warden API key                        |
+| `endpoint`  | `string` | Yes      | URL of the Token Warden ingestion endpoint       |
+| `flushIntervalMs` | `number` | No | How often to flush events (default: `5000`)  |
+| `maxBatchSize` | `number` | No    | Max events per batch (default: `100`)            |
+| `debug`     | `boolean` | No     | Enable debug logging (default: `false`)          |
+
+### `warden.wrap(client, opts)`
+
+Wrap an LLM SDK client to automatically capture usage.
+
+| Parameter   | Type     | Required | Description                                      |
+| ----------- | -------- | -------- | ------------------------------------------------ |
+| `client`    | `object` | Yes      | An LLM SDK client instance                      |
+| `opts.feature` | `string` | No   | Feature name for cost attribution                |
+| `opts.team` | `string` | No      | Team name for cost attribution                   |
+| `opts.user` | `string` | No      | User identifier for cost attribution             |
+| `opts.metadata` | `Record<string, string>` | No | Additional key-value metadata       |
+
+### `warden.track(event)`
+
+Manually record a usage event.
+
+| Parameter       | Type     | Required | Description                                  |
+| --------------- | -------- | -------- | -------------------------------------------- |
+| `provider`      | `string` | Yes      | LLM provider name                           |
+| `model`         | `string` | Yes      | Model identifier                             |
+| `feature`       | `string` | No       | Feature name for cost attribution            |
+| `team`          | `string` | No       | Team name for cost attribution               |
+| `user`          | `string` | No       | User identifier for cost attribution         |
+| `inputTokens`   | `number` | Yes      | Number of input tokens consumed             |
+| `outputTokens`  | `number` | Yes      | Number of output tokens generated           |
+| `durationMs`    | `number` | No       | Request duration in milliseconds             |
+| `metadata`      | `Record<string, string>` | No | Additional key-value metadata     |
+
+### `warden.flush()`
+
+Flush all pending events to the ingestion endpoint. Returns a promise that resolves when all events have been sent. Call this before process exit in serverless environments.
+
+### `warden.shutdown()`
+
+Flush pending events and stop the background flush interval. Call this during graceful application shutdown.
+
+## Dashboard (Coming Soon)
+
+A full-featured dashboard with budget alerts, anomaly detection, and per-feature cost drill-down is in development. Star this repo to get notified when it launches.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

package/dist/index.cjs

@@ -0,0 +1,331 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  warden: () => warden
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/providers.ts
+function detectProvider(client) {
+  const proto = Object.getPrototypeOf(client);
+  const name = proto?.constructor?.name?.toLowerCase() ?? "";
+  if (name.includes("openai")) return "openai";
+  if (name.includes("anthropic")) return "anthropic";
+  if (name.includes("google") || name.includes("generativeai")) return "google";
+  if (name.includes("deepseek")) return "deepseek";
+  if (name.includes("mistral")) return "mistral";
+  if (name.includes("xai")) return "xai";
+  if (name.includes("cohere")) return "cohere";
+  if (name.includes("bedrock")) return "amazon";
+  return "unknown";
+}
+
+// src/proxy.ts
+function extractCompletionTokens(result) {
+  const usage = result.usage;
+  const inputTokens = usage?.prompt_tokens ?? usage?.input_tokens ?? 0;
+  const outputTokens = usage?.completion_tokens ?? usage?.output_tokens ?? 0;
+  return { inputTokens, outputTokens, totalTokens: inputTokens + outputTokens };
+}
+function extractGoogleTokens(result) {
+  const usageMetadata = result.response?.usageMetadata;
+  const inputTokens = usageMetadata?.promptTokenCount ?? 0;
+  const outputTokens = usageMetadata?.candidatesTokenCount ?? 0;
+  const totalTokens = usageMetadata?.totalTokenCount ?? inputTokens + outputTokens;
+  return { inputTokens, outputTokens, totalTokens };
+}
+function modelFromArgs(args) {
+  return args[0]?.model ?? "unknown";
+}
+function createMethodProxy(original, cfg) {
+  return new Proxy(original, {
+    get(target, prop) {
+      if (prop === cfg.methodName) {
+        return async (...args) => {
+          const start = Date.now();
+          const model = cfg.modelExtractor(args);
+          try {
+            const fn = target[cfg.methodName];
+            const result = await fn.apply(target, args);
+            const usage = cfg.tokenExtractor(result);
+            cfg.pushEvent({
+              feature: cfg.opts.feature,
+              team: cfg.opts.team,
+              userId: cfg.opts.userId,
+              provider: cfg.provider,
+              model,
+              ...usage,
+              latencyMs: Date.now() - start,
+              status: "success",
+              timestamp: Date.now()
+            });
+            if (cfg.shouldFlush()) cfg.triggerFlush();
+            return result;
+          } catch (err) {
+            cfg.pushEvent({
+              feature: cfg.opts.feature,
+              team: cfg.opts.team,
+              userId: cfg.opts.userId,
+              provider: cfg.provider,
+              model,
+              inputTokens: 0,
+              outputTokens: 0,
+              totalTokens: 0,
+              latencyMs: Date.now() - start,
+              status: "error",
+              timestamp: Date.now()
+            });
+            throw err;
+          }
+        };
+      }
+      return target[prop];
+    }
+  });
+}
+
+// src/index.ts
+var MAX_BUFFER_SIZE = 1e3;
+var config = null;
+var buffer = [];
+var flushTimer = null;
+var initialized = false;
+var flushing = false;
+function pushEvent(event) {
+  if (buffer.length >= MAX_BUFFER_SIZE) {
+    buffer.shift();
+  }
+  buffer.push(event);
+}
+function shouldFlush() {
+  return buffer.length >= (config?.batchSize ?? 50);
+}
+function triggerFlush() {
+  void flush();
+}
+async function flush() {
+  if (!config || buffer.length === 0 || flushing) return;
+  flushing = true;
+  const batch = buffer.slice();
+  try {
+    const response = await fetch(config.endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${config.apiKey}`
+      },
+      body: JSON.stringify({ events: batch })
+    });
+    if (!response.ok) {
+      const error = new Error(
+        `Token Warden: flush failed with status ${response.status}`
+      );
+      config.onError?.(error);
+      return;
+    }
+    buffer.splice(0, batch.length);
+  } catch (err) {
+    config.onError?.(err);
+  } finally {
+    flushing = false;
+  }
+}
+var beforeExitHandler = () => void flush();
+function scheduleFlush() {
+  if (flushTimer) return;
+  const interval = config?.flushIntervalMs ?? 5e3;
+  flushTimer = setInterval(() => {
+    void flush();
+  }, interval);
+  flushTimer.unref();
+  if (typeof process !== "undefined" && process.once) {
+    process.once("beforeExit", beforeExitHandler);
+  }
+}
+var warden = {
+  init(cfg) {
+    if (initialized) {
+      throw new Error(
+        "Token Warden: already initialized. Call warden.shutdown() before re-initializing."
+      );
+    }
+    if (!cfg.endpoint) {
+      throw new Error("Token Warden: endpoint is required in config");
+    }
+    config = cfg;
+    initialized = true;
+    scheduleFlush();
+  },
+  wrap(client, opts) {
+    if (!initialized || !config) {
+      throw new Error(
+        "Token Warden: call warden.init() before guardian.wrap()"
+      );
+    }
+    const provider = detectProvider(client);
+    return new Proxy(client, {
+      get(target, prop) {
+        const value = target[prop];
+        if (prop === "chat" && value && typeof value === "object") {
+          return new Proxy(value, {
+            get(chatTarget, chatProp) {
+              if (chatProp === "completions") {
+                const completions = chatTarget.completions;
+                if (completions && typeof completions === "object") {
+                  return createMethodProxy(
+                    completions,
+                    {
+                      methodName: "create",
+                      provider,
+                      modelExtractor: modelFromArgs,
+                      tokenExtractor: extractCompletionTokens,
+                      opts,
+                      pushEvent,
+                      shouldFlush,
+                      triggerFlush
+                    }
+                  );
+                }
+              }
+              return chatTarget[chatProp];
+            }
+          });
+        }
+        if (prop === "messages" && value && typeof value === "object") {
+          return createMethodProxy(value, {
+            methodName: "create",
+            provider: provider === "unknown" ? "anthropic" : provider,
+            modelExtractor: modelFromArgs,
+            tokenExtractor: extractCompletionTokens,
+            opts,
+            pushEvent,
+            shouldFlush,
+            triggerFlush
+          });
+        }
+        if (prop === "getGenerativeModel" && typeof value === "function") {
+          return (...args) => {
+            const modelInstance = value.apply(target, args);
+            const modelName = args[0]?.model ?? "unknown";
+            return createMethodProxy(
+              modelInstance,
+              {
+                methodName: "generateContent",
+                provider: provider === "unknown" ? "google" : provider,
+                modelExtractor: () => modelName,
+                tokenExtractor: extractGoogleTokens,
+                opts,
+                pushEvent,
+                shouldFlush,
+                triggerFlush
+              }
+            );
+          };
+        }
+        if (prop === "send" && typeof value === "function" && provider === "amazon") {
+          return async (...args) => {
+            const start = Date.now();
+            const command = args[0];
+            const modelId = command?.modelId ?? command?.input?.modelId ?? "unknown";
+            try {
+              const result = await value.apply(target, args);
+              const usage = result.usage;
+              const inputTokens = usage?.inputTokens ?? 0;
+              const outputTokens = usage?.outputTokens ?? 0;
+              pushEvent({
+                feature: opts.feature,
+                team: opts.team,
+                userId: opts.userId,
+                provider,
+                model: modelId,
+                inputTokens,
+                outputTokens,
+                totalTokens: inputTokens + outputTokens,
+                latencyMs: Date.now() - start,
+                status: "success",
+                timestamp: Date.now()
+              });
+              if (shouldFlush()) triggerFlush();
+              return result;
+            } catch (err) {
+              pushEvent({
+                feature: opts.feature,
+                team: opts.team,
+                userId: opts.userId,
+                provider,
+                model: modelId,
+                inputTokens: 0,
+                outputTokens: 0,
+                totalTokens: 0,
+                latencyMs: Date.now() - start,
+                status: "error",
+                timestamp: Date.now()
+              });
+              throw err;
+            }
+          };
+        }
+        return value;
+      }
+    });
+  },
+  track(event) {
+    if (!initialized || !config) {
+      throw new Error(
+        "Token Warden: call warden.init() before guardian.track()"
+      );
+    }
+    if (!event.feature) {
+      throw new Error("Token Warden: feature is required in track event");
+    }
+    if (!event.provider) {
+      throw new Error("Token Warden: provider is required in track event");
+    }
+    if (!event.model) {
+      throw new Error("Token Warden: model is required in track event");
+    }
+    pushEvent({
+      ...event,
+      timestamp: Date.now()
+    });
+    if (shouldFlush()) triggerFlush();
+  },
+  flush,
+  async shutdown() {
+    if (flushTimer) {
+      clearInterval(flushTimer);
+      flushTimer = null;
+    }
+    if (typeof process !== "undefined") {
+      process.removeListener("beforeExit", beforeExitHandler);
+    }
+    flushing = false;
+    await flush();
+    buffer.length = 0;
+    config = null;
+    initialized = false;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  warden
+});

package/dist/index.d.cts

@@ -0,0 +1,43 @@
+type WardenConfig = {
+    apiKey: string;
+    endpoint: string;
+    batchSize?: number;
+    flushIntervalMs?: number;
+    onError?: (error: unknown) => void;
+};
+type WrapOptions = {
+    feature: string;
+    team?: string;
+    userId?: string;
+};
+type CostEvent = {
+    feature: string;
+    team?: string;
+    userId?: string;
+    provider: string;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    latencyMs: number;
+    status: "success" | "error";
+    timestamp: number;
+    metadata?: Record<string, unknown>;
+};
+type TrackEvent = Omit<CostEvent, "timestamp">;
+type TokenUsage = {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+};
+
+declare function flush(): Promise<void>;
+declare const warden: {
+    init(cfg: WardenConfig): void;
+    wrap<T>(client: T, opts: WrapOptions): T;
+    track(event: TrackEvent): void;
+    flush: typeof flush;
+    shutdown(): Promise<void>;
+};
+
+export { type CostEvent, type TokenUsage, type TrackEvent, type WardenConfig, type WrapOptions, warden };

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+type WardenConfig = {
+    apiKey: string;
+    endpoint: string;
+    batchSize?: number;
+    flushIntervalMs?: number;
+    onError?: (error: unknown) => void;
+};
+type WrapOptions = {
+    feature: string;
+    team?: string;
+    userId?: string;
+};
+type CostEvent = {
+    feature: string;
+    team?: string;
+    userId?: string;
+    provider: string;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    latencyMs: number;
+    status: "success" | "error";
+    timestamp: number;
+    metadata?: Record<string, unknown>;
+};
+type TrackEvent = Omit<CostEvent, "timestamp">;
+type TokenUsage = {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+};
+
+declare function flush(): Promise<void>;
+declare const warden: {
+    init(cfg: WardenConfig): void;
+    wrap<T>(client: T, opts: WrapOptions): T;
+    track(event: TrackEvent): void;
+    flush: typeof flush;
+    shutdown(): Promise<void>;
+};
+
+export { type CostEvent, type TokenUsage, type TrackEvent, type WardenConfig, type WrapOptions, warden };

package/dist/index.js

@@ -0,0 +1,304 @@
+// src/providers.ts
+function detectProvider(client) {
+  const proto = Object.getPrototypeOf(client);
+  const name = proto?.constructor?.name?.toLowerCase() ?? "";
+  if (name.includes("openai")) return "openai";
+  if (name.includes("anthropic")) return "anthropic";
+  if (name.includes("google") || name.includes("generativeai")) return "google";
+  if (name.includes("deepseek")) return "deepseek";
+  if (name.includes("mistral")) return "mistral";
+  if (name.includes("xai")) return "xai";
+  if (name.includes("cohere")) return "cohere";
+  if (name.includes("bedrock")) return "amazon";
+  return "unknown";
+}
+
+// src/proxy.ts
+function extractCompletionTokens(result) {
+  const usage = result.usage;
+  const inputTokens = usage?.prompt_tokens ?? usage?.input_tokens ?? 0;
+  const outputTokens = usage?.completion_tokens ?? usage?.output_tokens ?? 0;
+  return { inputTokens, outputTokens, totalTokens: inputTokens + outputTokens };
+}
+function extractGoogleTokens(result) {
+  const usageMetadata = result.response?.usageMetadata;
+  const inputTokens = usageMetadata?.promptTokenCount ?? 0;
+  const outputTokens = usageMetadata?.candidatesTokenCount ?? 0;
+  const totalTokens = usageMetadata?.totalTokenCount ?? inputTokens + outputTokens;
+  return { inputTokens, outputTokens, totalTokens };
+}
+function modelFromArgs(args) {
+  return args[0]?.model ?? "unknown";
+}
+function createMethodProxy(original, cfg) {
+  return new Proxy(original, {
+    get(target, prop) {
+      if (prop === cfg.methodName) {
+        return async (...args) => {
+          const start = Date.now();
+          const model = cfg.modelExtractor(args);
+          try {
+            const fn = target[cfg.methodName];
+            const result = await fn.apply(target, args);
+            const usage = cfg.tokenExtractor(result);
+            cfg.pushEvent({
+              feature: cfg.opts.feature,
+              team: cfg.opts.team,
+              userId: cfg.opts.userId,
+              provider: cfg.provider,
+              model,
+              ...usage,
+              latencyMs: Date.now() - start,
+              status: "success",
+              timestamp: Date.now()
+            });
+            if (cfg.shouldFlush()) cfg.triggerFlush();
+            return result;
+          } catch (err) {
+            cfg.pushEvent({
+              feature: cfg.opts.feature,
+              team: cfg.opts.team,
+              userId: cfg.opts.userId,
+              provider: cfg.provider,
+              model,
+              inputTokens: 0,
+              outputTokens: 0,
+              totalTokens: 0,
+              latencyMs: Date.now() - start,
+              status: "error",
+              timestamp: Date.now()
+            });
+            throw err;
+          }
+        };
+      }
+      return target[prop];
+    }
+  });
+}
+
+// src/index.ts
+var MAX_BUFFER_SIZE = 1e3;
+var config = null;
+var buffer = [];
+var flushTimer = null;
+var initialized = false;
+var flushing = false;
+function pushEvent(event) {
+  if (buffer.length >= MAX_BUFFER_SIZE) {
+    buffer.shift();
+  }
+  buffer.push(event);
+}
+function shouldFlush() {
+  return buffer.length >= (config?.batchSize ?? 50);
+}
+function triggerFlush() {
+  void flush();
+}
+async function flush() {
+  if (!config || buffer.length === 0 || flushing) return;
+  flushing = true;
+  const batch = buffer.slice();
+  try {
+    const response = await fetch(config.endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${config.apiKey}`
+      },
+      body: JSON.stringify({ events: batch })
+    });
+    if (!response.ok) {
+      const error = new Error(
+        `Token Warden: flush failed with status ${response.status}`
+      );
+      config.onError?.(error);
+      return;
+    }
+    buffer.splice(0, batch.length);
+  } catch (err) {
+    config.onError?.(err);
+  } finally {
+    flushing = false;
+  }
+}
+var beforeExitHandler = () => void flush();
+function scheduleFlush() {
+  if (flushTimer) return;
+  const interval = config?.flushIntervalMs ?? 5e3;
+  flushTimer = setInterval(() => {
+    void flush();
+  }, interval);
+  flushTimer.unref();
+  if (typeof process !== "undefined" && process.once) {
+    process.once("beforeExit", beforeExitHandler);
+  }
+}
+var warden = {
+  init(cfg) {
+    if (initialized) {
+      throw new Error(
+        "Token Warden: already initialized. Call warden.shutdown() before re-initializing."
+      );
+    }
+    if (!cfg.endpoint) {
+      throw new Error("Token Warden: endpoint is required in config");
+    }
+    config = cfg;
+    initialized = true;
+    scheduleFlush();
+  },
+  wrap(client, opts) {
+    if (!initialized || !config) {
+      throw new Error(
+        "Token Warden: call warden.init() before guardian.wrap()"
+      );
+    }
+    const provider = detectProvider(client);
+    return new Proxy(client, {
+      get(target, prop) {
+        const value = target[prop];
+        if (prop === "chat" && value && typeof value === "object") {
+          return new Proxy(value, {
+            get(chatTarget, chatProp) {
+              if (chatProp === "completions") {
+                const completions = chatTarget.completions;
+                if (completions && typeof completions === "object") {
+                  return createMethodProxy(
+                    completions,
+                    {
+                      methodName: "create",
+                      provider,
+                      modelExtractor: modelFromArgs,
+                      tokenExtractor: extractCompletionTokens,
+                      opts,
+                      pushEvent,
+                      shouldFlush,
+                      triggerFlush
+                    }
+                  );
+                }
+              }
+              return chatTarget[chatProp];
+            }
+          });
+        }
+        if (prop === "messages" && value && typeof value === "object") {
+          return createMethodProxy(value, {
+            methodName: "create",
+            provider: provider === "unknown" ? "anthropic" : provider,
+            modelExtractor: modelFromArgs,
+            tokenExtractor: extractCompletionTokens,
+            opts,
+            pushEvent,
+            shouldFlush,
+            triggerFlush
+          });
+        }
+        if (prop === "getGenerativeModel" && typeof value === "function") {
+          return (...args) => {
+            const modelInstance = value.apply(target, args);
+            const modelName = args[0]?.model ?? "unknown";
+            return createMethodProxy(
+              modelInstance,
+              {
+                methodName: "generateContent",
+                provider: provider === "unknown" ? "google" : provider,
+                modelExtractor: () => modelName,
+                tokenExtractor: extractGoogleTokens,
+                opts,
+                pushEvent,
+                shouldFlush,
+                triggerFlush
+              }
+            );
+          };
+        }
+        if (prop === "send" && typeof value === "function" && provider === "amazon") {
+          return async (...args) => {
+            const start = Date.now();
+            const command = args[0];
+            const modelId = command?.modelId ?? command?.input?.modelId ?? "unknown";
+            try {
+              const result = await value.apply(target, args);
+              const usage = result.usage;
+              const inputTokens = usage?.inputTokens ?? 0;
+              const outputTokens = usage?.outputTokens ?? 0;
+              pushEvent({
+                feature: opts.feature,
+                team: opts.team,
+                userId: opts.userId,
+                provider,
+                model: modelId,
+                inputTokens,
+                outputTokens,
+                totalTokens: inputTokens + outputTokens,
+                latencyMs: Date.now() - start,
+                status: "success",
+                timestamp: Date.now()
+              });
+              if (shouldFlush()) triggerFlush();
+              return result;
+            } catch (err) {
+              pushEvent({
+                feature: opts.feature,
+                team: opts.team,
+                userId: opts.userId,
+                provider,
+                model: modelId,
+                inputTokens: 0,
+                outputTokens: 0,
+                totalTokens: 0,
+                latencyMs: Date.now() - start,
+                status: "error",
+                timestamp: Date.now()
+              });
+              throw err;
+            }
+          };
+        }
+        return value;
+      }
+    });
+  },
+  track(event) {
+    if (!initialized || !config) {
+      throw new Error(
+        "Token Warden: call warden.init() before guardian.track()"
+      );
+    }
+    if (!event.feature) {
+      throw new Error("Token Warden: feature is required in track event");
+    }
+    if (!event.provider) {
+      throw new Error("Token Warden: provider is required in track event");
+    }
+    if (!event.model) {
+      throw new Error("Token Warden: model is required in track event");
+    }
+    pushEvent({
+      ...event,
+      timestamp: Date.now()
+    });
+    if (shouldFlush()) triggerFlush();
+  },
+  flush,
+  async shutdown() {
+    if (flushTimer) {
+      clearInterval(flushTimer);
+      flushTimer = null;
+    }
+    if (typeof process !== "undefined") {
+      process.removeListener("beforeExit", beforeExitHandler);
+    }
+    flushing = false;
+    await flush();
+    buffer.length = 0;
+    config = null;
+    initialized = false;
+  }
+};
+export {
+  warden
+};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "token-warden",
+  "version": "1.0.0",
+  "description": "Lightweight LLM cost tracking SDK — auto-instrument OpenAI, Anthropic, Google, Bedrock, and more",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Flagship-Software/token-warden.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://github.com/Flagship-Software/token-warden#readme",
+  "bugs": {
+    "url": "https://github.com/Flagship-Software/token-warden/issues"
+  },
+  "keywords": [
+    "llm",
+    "cost",
+    "monitoring",
+    "openai",
+    "anthropic",
+    "google",
+    "bedrock",
+    "ai",
+    "tokens",
+    "usage",
+    "budget",
+    "tracking"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "cp ../../README.md ./README.md && npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.2.0"
+  }
+}