ai-cost-tracker

ai-cost-tracker is a production-ready TypeScript/Node.js library for tracking LLM API token usage and USD costs per user and feature.

Problem

LLM usage costs are easy to lose track of when your application only monitors provider-level totals.

Typical pain points:

• Surprise bills at the end of the month.
• No breakdown by user or feature.
• No simple way to analyze high-cost paths.

Solution

Wrap your OpenAI/Anthropic calls with trackCosts(...). The library extracts usage metadata, computes cost from model pricing, and writes logs to a fast SQLite backend (better-sqlite3).

Installation

npm install ai-cost-tracker better-sqlite3

Optional peer SDKs:

npm install openai @anthropic-ai/sdk

Quick Start

import OpenAI from 'openai';
import { initTracker, trackCosts } from 'ai-cost-tracker';

const storage = initTracker({ storagePath: 'costs.db', orgId: 'acme-inc' });
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

async function chat(prompt: string) {
  return trackCosts(
    async () => {
      return openai.chat.completions.create({
        model: 'gpt-4o-mini',
        messages: [{ role: 'user', content: prompt }],
      });
    },
    { userId: 'user_123', feature: 'chat' }
  );
}

await chat('Hello!');

console.log(storage.getTotalCost());
console.log(storage.getTopUsers(10));
console.log(storage.getTopFeatures(10));

Supported Providers

• OpenAI (usage.prompt_tokens, usage.completion_tokens)
• Anthropic (usage.input_tokens, usage.output_tokens)

API Reference

initTracker(options)

Initializes global tracker state and returns a SQLiteStorage instance.

initTracker({ storagePath: string, orgId?: string }): SQLiteStorage

trackCosts(fn, options)

Wraps an async/promise-producing function, measures latency, extracts token usage, computes cost, and logs usage.

trackCosts<T>(fn: () => Promise<T> | T, options: TrackOptions): Promise<T>

TrackOptions:

• userId: string
• feature: string
• metadata?: Record<string, unknown>
• orgId?: string

trackManual(input)

Manually logs usage when no provider response is available.

trackManual({
  userId,
  feature,
  model,
  tokensIn,
  tokensOut,
  latencyMs?,
  metadata?,
  orgId?,
  timestamp?
}): CostLog

calculateCost(model, tokensIn, tokensOut)

Computes USD cost using built-in pricing table and partial model matching.

getModelPricing(model)

Returns { input, output } rates in USD per 1M tokens.

SQLiteStorage

• initDb(): void
• log(costLog: CostLog): void
• getTotalCost(filters?: FilterOptions): number
• getTopUsers(limit?: number): Array<{ userId, cost, count }>
• getTopFeatures(limit?: number): Array<{ feature, cost, count }>
• close(): void

FilterOptions:

• userId?: string
• feature?: string
• orgId?: string
• model?: string
• startTime?: Date | string
• endTime?: Date | string

FAQ

Does this support both CommonJS and ESM imports?

Yes. Package exports support both require('ai-cost-tracker') and import { ... } from 'ai-cost-tracker'.

What happens if usage extraction fails?

The tracked function result is still returned. Logging failures are caught to avoid breaking request handling.

Can I use my own SQLite database path?

Yes. Pass any writable path via initTracker({ storagePath: 'path/to/file.db' }).

Examples

• OpenAI example: /examples/example-openai.ts
• Anthropic example: /examples/example-anthropic.ts
• Express + request context example: /examples/example-express.ts

Development

npm install
npm run build
npm test
npm run lint