@tozil/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tozil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# tozil
+
+Know what every AI user costs you. Track AI costs per user, per model, per endpoint — with 2 lines of code.
+
+## Install
+
+```bash
+npm install tozil
+```
+
+## Quick Start
+
+```typescript
+import tozil from "tozil";
+
+tozil.init(); // reads TOZIL_API_KEY from env
+```
+
+That's it. Tozil automatically patches the Anthropic and OpenAI SDKs to track every API call — tokens, latency, model, and cost.
+
+## Setup
+
+1. Sign up at [tozil.dev](https://tozil.dev) and grab your API key
+2. Set your environment variable:
+
+```bash
+TOZIL_API_KEY=tz_your_key_here
+```
+
+3. Call `tozil.init()` before creating any Anthropic/OpenAI clients:
+
+```typescript
+import tozil from "tozil";
+import Anthropic from "@anthropic-ai/sdk";
+
+tozil.init();
+
+const client = new Anthropic();
+const response = await client.messages.create({
+  model: "claude-sonnet-4-20250514",
+  max_tokens: 1024,
+  messages: [{ role: "user", content: "Hello" }],
+});
+// ^ This call is automatically tracked
+```
+
+## Track Users & Endpoints
+
+Use the Express middleware to automatically tag requests with user and endpoint info:
+
+```typescript
+import tozil from "tozil";
+import { tozilMiddleware } from "tozil/express";
+import express from "express";
+
+tozil.init();
+
+const app = express();
+app.use(tozilMiddleware({
+  getUserId: (req) => req.headers["x-user-id"] as string,
+}));
+```
+
+Or set context manually anywhere in your code:
+
+```typescript
+import { withContext } from "tozil";
+
+await withContext({ userId: "user_123", endpoint: "/chat" }, async () => {
+  // All AI calls inside here are tagged with this user & endpoint
+  await client.messages.create({ ... });
+});
+```
+
+## Options
+
+```typescript
+tozil.init({
+  apiKey: "tz_...",         // default: process.env.TOZIL_API_KEY
+  baseUrl: "https://...",   // default: https://app.tozil.dev/api/v1
+  flushInterval: 5000,      // ms between flushes (default: 5000)
+  maxBatchSize: 100,         // events per batch (default: 100)
+  debug: false,              // log tracking events to console
+});
+```
+
+## How It Works
+
+- Monkey-patches Anthropic and OpenAI SDK prototypes at init time
+- Uses Node.js AsyncLocalStorage for zero-config context propagation
+- Buffers events in memory, flushes every 5s (or at batch size)
+- Silent failure — never throws, never blocks your critical path
+- Zero runtime dependencies
+
+## Requirements
+
+- Node.js >= 18
+- `@anthropic-ai/sdk` and/or `openai` as peer dependencies (install whichever you use)
+
+## License
+
+MIT

package/dist/express.d.ts

@@ -0,0 +1,4 @@
+export declare function tozilMiddleware(options?: {
+    getUserId?: (req: any) => string | null;
+}): (req: any, _res: any, next: any) => void;
+export default tozilMiddleware;

package/dist/express.js

@@ -0,0 +1,17 @@
+import { runWithContext, setUser, setEndpoint } from "./index.js";
+export function tozilMiddleware(options) {
+    return (req, _res, next) => {
+        runWithContext(() => {
+            // Set endpoint from request
+            setEndpoint(req.path || req.url);
+            // Set user ID if extractor provided, or from common patterns
+            const userId = options?.getUserId
+                ? options.getUserId(req)
+                : req.user?.id || req.user?.email || req.body?.user_id || null;
+            if (userId)
+                setUser(userId);
+            next();
+        });
+    };
+}
+export default tozilMiddleware;

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+export interface TozilEvent {
+    timestamp: string;
+    user_id: string | null;
+    model: string;
+    provider: "anthropic" | "openai" | "unknown";
+    endpoint: string | null;
+    input_tokens: number;
+    output_tokens: number;
+    latency_ms: number;
+    metadata: Record<string, string>;
+}
+export declare function init(options?: {
+    apiKey?: string;
+    baseUrl?: string;
+    flushInterval?: number;
+    maxBatchSize?: number;
+    debug?: boolean;
+    clients?: {
+        Anthropic?: any;
+        OpenAI?: any;
+    };
+}): void;
+export declare function setUser(userId: string): void;
+export declare function setEndpoint(endpoint: string): void;
+export declare function setMetadata(key: string, value: string): void;
+export declare function withContext<T>(context: {
+    userId?: string;
+    endpoint?: string;
+    metadata?: Record<string, string>;
+}, fn: () => T): T;
+export declare function runWithContext<T>(fn: () => T): T;
+export declare function shutdown(): void;
+declare const _default: {
+    init: typeof init;
+    setUser: typeof setUser;
+    setEndpoint: typeof setEndpoint;
+    setMetadata: typeof setMetadata;
+    withContext: typeof withContext;
+    runWithContext: typeof runWithContext;
+    shutdown: typeof shutdown;
+};
+export default _default;

package/dist/index.js

@@ -0,0 +1,321 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createRequire } from "node:module";
+// --- State ---
+const als = new AsyncLocalStorage();
+let config = null;
+let eventBuffer = [];
+let flushTimer = null;
+let initialized = false;
+// --- Auto-discovery ---
+// Resolve an SDK module from the host app's node_modules (not tozil's own).
+// Uses createRequire anchored at cwd so it finds the host app's dependencies.
+// CJS require returns the CJS entry which shares the same prototype chain as
+// the ESM import when the package uses conditional exports pointing both to
+// the same underlying class. For packages where CJS and ESM are separate
+// builds, we fall back to async import() from the resolved file path.
+function autoDiscover(modName, patchFn) {
+    try {
+        const hostRequire = createRequire(process.cwd() + "/package.json");
+        // First try: resolve the path, then use import() to get the ESM version
+        // This ensures we patch the same prototype the host app uses
+        const resolved = hostRequire.resolve(modName);
+        import(/* @vite-ignore */ "file://" + resolved)
+            .then((m) => patchFn(m.default || m))
+            .catch(() => {
+            // Fallback: use the CJS module directly
+            try {
+                const mod = hostRequire(modName);
+                patchFn(mod.default || mod);
+            }
+            catch { }
+        });
+    }
+    catch {
+        if (config?.debug)
+            console.log(`[tozil] ${modName} not installed, skipping`);
+    }
+}
+// --- Public API ---
+export function init(options) {
+    if (initialized)
+        return;
+    const apiKey = options?.apiKey || process.env.TOZIL_API_KEY;
+    if (!apiKey) {
+        if (options?.debug)
+            console.warn("[tozil] No API key found. Set TOZIL_API_KEY or pass apiKey option.");
+        return;
+    }
+    config = {
+        apiKey,
+        baseUrl: options?.baseUrl || process.env.TOZIL_BASE_URL || "https://app.tozil.dev/api/v1",
+        flushInterval: options?.flushInterval || 5000,
+        maxBatchSize: options?.maxBatchSize || 100,
+        debug: options?.debug || false,
+    };
+    // Patch explicitly passed clients
+    if (options?.clients?.Anthropic)
+        patchAnthropic(options.clients.Anthropic);
+    if (options?.clients?.OpenAI)
+        patchOpenAI(options.clients.OpenAI);
+    // Auto-discover SDKs if not explicitly passed
+    if (!options?.clients?.Anthropic)
+        autoDiscover("@anthropic-ai/sdk", patchAnthropic);
+    if (!options?.clients?.OpenAI)
+        autoDiscover("openai", patchOpenAI);
+    flushTimer = setInterval(() => flush(), config.flushInterval);
+    process.on("beforeExit", () => flush());
+    initialized = true;
+    if (config.debug)
+        console.log("[tozil] Initialized");
+}
+export function setUser(userId) {
+    const store = als.getStore();
+    if (store)
+        store.userId = userId;
+}
+export function setEndpoint(endpoint) {
+    const store = als.getStore();
+    if (store)
+        store.endpoint = endpoint;
+}
+export function setMetadata(key, value) {
+    const store = als.getStore();
+    if (store)
+        store.metadata[key] = value;
+}
+export function withContext(context, fn) {
+    return als.run({ userId: context.userId || null, endpoint: context.endpoint || null, metadata: context.metadata || {} }, fn);
+}
+export function runWithContext(fn) {
+    return als.run({ userId: null, endpoint: null, metadata: {} }, fn);
+}
+export function shutdown() {
+    if (flushTimer)
+        clearInterval(flushTimer);
+    flush();
+    initialized = false;
+    config = null;
+}
+// --- Event tracking ---
+function trackEvent(event) {
+    if (!config)
+        return;
+    eventBuffer.push(event);
+    if (config.debug) {
+        console.log(`[tozil] ${event.provider}/${event.model} | user=${event.user_id} endpoint=${event.endpoint} | in=${event.input_tokens} out=${event.output_tokens} | ${event.latency_ms}ms`);
+    }
+    if (eventBuffer.length >= config.maxBatchSize)
+        flush();
+}
+async function flush() {
+    if (!config || eventBuffer.length === 0)
+        return;
+    const events = eventBuffer.splice(0);
+    try {
+        const res = await fetch(`${config.baseUrl}/events`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${config.apiKey}`,
+            },
+            body: JSON.stringify({ events }),
+        });
+        if (!res.ok && config.debug)
+            console.warn(`[tozil] Flush failed: ${res.status}`);
+    }
+    catch (e) {
+        if (config?.debug)
+            console.warn(`[tozil] Flush failed (silent):`, e.message);
+    }
+}
+// --- Context helper ---
+function getContext() {
+    const store = als.getStore();
+    return {
+        userId: store?.userId || null,
+        endpoint: store?.endpoint || null,
+        metadata: store?.metadata || {},
+    };
+}
+// --- Monkey patching ---
+// Strategy: create a temp instance to find the prototype, patch it there.
+// This way all future instances are patched too.
+function trackFromResult(provider, params, result, latency) {
+    try {
+        const ctx = getContext();
+        const isAnthropic = provider === "anthropic";
+        trackEvent({
+            timestamp: new Date().toISOString(),
+            user_id: ctx.userId,
+            model: params.model || result?.model || "unknown",
+            provider,
+            endpoint: ctx.endpoint,
+            input_tokens: isAnthropic ? (result?.usage?.input_tokens || 0) : (result?.usage?.prompt_tokens || 0),
+            output_tokens: isAnthropic ? (result?.usage?.output_tokens || 0) : (result?.usage?.completion_tokens || 0),
+            latency_ms: latency,
+            metadata: { ...ctx.metadata },
+        });
+    }
+    catch { }
+}
+function wrapStream(provider, params, stream, start) {
+    // Anthropic streams have a finalMessage or final usage event
+    // OpenAI streams have a .usage property after iteration
+    const origSymbol = Symbol.asyncIterator in stream ? Symbol.asyncIterator : null;
+    if (!origSymbol)
+        return stream;
+    let inputTokens = 0;
+    let outputTokens = 0;
+    const isAnthropic = provider === "anthropic";
+    const origIterator = stream[Symbol.asyncIterator].bind(stream);
+    stream[Symbol.asyncIterator] = async function* () {
+        for await (const chunk of origIterator()) {
+            // Anthropic: message_delta event contains usage
+            if (isAnthropic && chunk?.type === "message_start" && chunk?.message?.usage) {
+                inputTokens = chunk.message.usage.input_tokens || 0;
+            }
+            if (isAnthropic && chunk?.type === "message_delta" && chunk?.usage) {
+                outputTokens = chunk.usage.output_tokens || 0;
+            }
+            // OpenAI: last chunk sometimes has usage
+            if (!isAnthropic && chunk?.usage) {
+                inputTokens = chunk.usage.prompt_tokens || 0;
+                outputTokens = chunk.usage.completion_tokens || 0;
+            }
+            yield chunk;
+        }
+        // After stream ends, track the event
+        const latency = Date.now() - start;
+        try {
+            const ctx = getContext();
+            trackEvent({
+                timestamp: new Date().toISOString(),
+                user_id: ctx.userId,
+                model: params.model || "unknown",
+                provider,
+                endpoint: ctx.endpoint,
+                input_tokens: inputTokens,
+                output_tokens: outputTokens,
+                latency_ms: latency,
+                metadata: { ...ctx.metadata },
+            });
+        }
+        catch { }
+        // Anthropic streams have finalMessage — also check after iteration
+        if (isAnthropic && typeof stream.finalMessage === "function") {
+            try {
+                const msg = await stream.finalMessage();
+                if (msg?.usage && inputTokens === 0) {
+                    trackFromResult(provider, params, msg, Date.now() - start);
+                }
+            }
+            catch { }
+        }
+    };
+    return stream;
+}
+function patchAnthropic(Client) {
+    try {
+        const temp = new Client({ apiKey: "tozil-patch-probe" });
+        const messagesProto = Object.getPrototypeOf(temp.messages);
+        if (messagesProto && typeof messagesProto.create === "function" && !messagesProto._tozilPatched) {
+            const origCreate = messagesProto.create;
+            messagesProto.create = async function (...args) {
+                const params = args[0] || {};
+                // Streaming: when stream is true, the SDK returns a stream object
+                if (params.stream) {
+                    try {
+                        const start = Date.now();
+                        const stream = await origCreate.apply(this, args);
+                        return wrapStream("anthropic", params, stream, start);
+                    }
+                    catch (e) {
+                        if (e?.status || e?.error)
+                            throw e;
+                        return origCreate.apply(this, args);
+                    }
+                }
+                try {
+                    const start = Date.now();
+                    const result = await origCreate.apply(this, args);
+                    const latency = Date.now() - start;
+                    trackFromResult("anthropic", params, result, latency);
+                    return result;
+                }
+                catch (e) {
+                    if (e?.status || e?.error)
+                        throw e;
+                    return origCreate.apply(this, args);
+                }
+            };
+            // Also patch .stream() if it exists (Anthropic SDK helper)
+            if (typeof messagesProto.stream === "function" && !messagesProto._tozilStreamPatched) {
+                const origStream = messagesProto.stream;
+                messagesProto.stream = async function (...args) {
+                    try {
+                        const start = Date.now();
+                        const stream = await origStream.apply(this, args);
+                        return wrapStream("anthropic", args[0] || {}, stream, start);
+                    }
+                    catch (e) {
+                        if (e?.status || e?.error)
+                            throw e;
+                        return origStream.apply(this, args);
+                    }
+                };
+                messagesProto._tozilStreamPatched = true;
+            }
+            messagesProto._tozilPatched = true;
+            if (config?.debug)
+                console.log("[tozil] Patched Anthropic SDK");
+        }
+    }
+    catch (e) {
+        if (config?.debug)
+            console.log("[tozil] Anthropic SDK not found, skipping");
+    }
+}
+function patchOpenAI(Client) {
+    try {
+        const temp = new Client({ apiKey: "tozil-patch-probe" });
+        const completionsProto = Object.getPrototypeOf(temp.chat.completions);
+        if (completionsProto && typeof completionsProto.create === "function" && !completionsProto._tozilPatched) {
+            const origCreate = completionsProto.create;
+            completionsProto.create = async function (...args) {
+                const params = args[0] || {};
+                if (params.stream) {
+                    try {
+                        const start = Date.now();
+                        const stream = await origCreate.apply(this, args);
+                        return wrapStream("openai", params, stream, start);
+                    }
+                    catch (e) {
+                        if (e?.status || e?.error)
+                            throw e;
+                        return origCreate.apply(this, args);
+                    }
+                }
+                try {
+                    const start = Date.now();
+                    const result = await origCreate.apply(this, args);
+                    const latency = Date.now() - start;
+                    trackFromResult("openai", params, result, latency);
+                    return result;
+                }
+                catch (e) {
+                    if (e?.status || e?.error)
+                        throw e;
+                    return origCreate.apply(this, args);
+                }
+            };
+            completionsProto._tozilPatched = true;
+            if (config?.debug)
+                console.log("[tozil] Patched OpenAI SDK");
+        }
+    }
+    catch (e) {
+        if (config?.debug)
+            console.log("[tozil] OpenAI SDK not found, skipping");
+    }
+}
+export default { init, setUser, setEndpoint, setMetadata, withContext, runWithContext, shutdown };

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@tozil/sdk",
+  "version": "0.1.0",
+  "description": "Know what every AI user costs you — track AI costs per user with 2 lines of code",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./express": {
+      "import": "./dist/express.js",
+      "types": "./dist/express.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "files": ["dist"],
+  "keywords": ["ai", "llm", "cost", "tracking", "anthropic", "openai", "claude", "gpt", "observability"],
+  "license": "MIT",
+  "homepage": "https://tozil.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tozil-dev/tozil"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0"
+  }
+}