JSPM

usagepilot

0.0.3
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 4
  • Score
    100M100P100Q30052F
  • License MIT

Open-core usage tracking for AI applications. Record, aggregate, and bill for token consumption across tenants with 95% storage reduction

Package Exports

  • usagepilot
  • usagepilot/package.json
  • usagepilot/storage

Readme

UsagePilot

Open-core usage tracking for AI applications. Record, aggregate, and bill for token consumption across tenants with 95% storage reduction.

The Problem

Building AI-powered SaaS applications comes with unique challenges:

  • Token costs add up fast - Each API call to OpenAI, Anthropic, or other providers costs money
  • Usage varies wildly - Some users consume 100x more tokens than others
  • Attribution is complex - You need to track usage per user, team, and organization
  • Storage explodes - Storing every API call creates massive databases
  • Billing is manual - Converting usage data into invoices takes custom code

Why UsagePilot?

UsagePilot is purpose-built for AI token tracking in multi-tenant SaaS applications:

💾 95% Storage Reduction

  • Aggregates usage into 60-minute windows instead of storing every event
  • Keeps query performance under 100ms even at scale
  • Automatically finalizes historical data for immutable storage

👥 True Multi-tenancy

  • Flexible dimension-based tracking (user, team, organization, workspace, etc.)
  • No rigid tenant structure - adapt to your application's needs
  • Efficient indexing for fast lookups across any dimension

💳 Billing-Ready

  • Integrates with Stripe, Orb, Metronome, and other billing providers
  • Accurate cost calculation with up-to-date pricing models
  • Export usage data in billing-friendly formats

🚀 Production Performance

  • Sub-100ms queries for hourly aggregations
  • Handles 10,000+ events per second
  • Exponential backoff and retry for reliability

Installation

npm install usagepilot
# or
pnpm add usagepilot
# or
yarn add usagepilot

Basic Usage

Initialize UsagePilot

import { UsagePilot } from "usagepilot";
import { PostgresStorage } from "usagepilot/storage";

// Define your dimension structure
type Dimensions = {
  user_id: string;
  team_id: string;
  organization_id: string;
};

// Create the storage adapter
const storage = new PostgresStorage({
  connectionString: process.env.DATABASE_URL,
  // Optional configuration
  batchSize: 100,
  flushInterval: 30000, // 30 seconds
  maxRetries: 3,
  retryDelay: 1000,
});

// Initialize UsagePilot
const usage = new UsagePilot<Dimensions>({
  storage,
});

Track AI Usage with Vercel AI SDK

import { streamText } from "ai";
import { createOpenAI } from "@ai-sdk/openai";

// Create a fetch wrapper that tracks usage
const trackedFetch = usage.createFetch((req) => ({
  user_id: req.headers.get("x-user-id"),
  team_id: req.headers.get("x-team-id"),
  organization_id: req.headers.get("x-organization-id"),
}));

// Create OpenAI instance with tracked fetch
const openai = createOpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  fetch: trackedFetch,
});

// Use it with Vercel AI SDK
async function generateResponse(prompt: string, userId: string) {
  const result = await streamText({
    model: openai("gpt-4"),
    prompt,
    headers: {
      "x-user-id": userId,
      "x-team-id": "team_456",
      "x-organization-id": "org_123",
    },
  });

  // Usage is automatically tracked and stored!
  return result;
}

Query Usage Data

// Get usage for a specific organization this month
const startOfMonth = new Date();
startOfMonth.setDate(1);
startOfMonth.setHours(0, 0, 0, 0);

const result = await usage.query({
  dimensions: {
    organization_id: "org_123",
  },
  timeRange: {
    start: startOfMonth,
    end: new Date(),
  },
});

// Calculate total tokens used
const totalTokens = result.aggregates.reduce(
  (sum, agg) => sum + agg.metrics.totalTokens,
  0,
);

console.log(`Organization used ${totalTokens} tokens this month`);

Export for Billing

// Get daily usage for billing
const dailyUsage = await usage.query({
  dimensions: {
    organization_id: "org_123",
  },
  timeRange: {
    start: billingPeriodStart,
    end: billingPeriodEnd,
  },
  granularity: "day", // Aggregate by day
});

// Calculate total tokens from daily aggregates
const totalTokens = dailyUsage.aggregates.reduce(
  (sum, agg) => sum + agg.metrics.totalTokens,
  0,
);

// Send to your billing provider
await stripe.usageRecords.create({
  subscription_item: "si_123",
  quantity: totalTokens,
  timestamp: Math.floor(Date.now() / 1000),
});

Advanced Features

  • Multiple Storage Backends: PostgreSQL, ClickHouse, Redis (coming soon)
  • Provider Support: OpenAI, Anthropic, Google, Mistral, and more
  • Real-time Dashboards: Pre-aggregated materialized views
  • Anomaly Detection: Identify unusual usage patterns
  • Cost Optimization: Track and optimize model usage
  • GDPR Compliant: Built-in data retention policies

Documentation

For comprehensive documentation, visit https://github.com/usagepilot/usagepilot

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

UsagePilot is licensed under the MIT License. See LICENSE for details.