usagepilot/index.d.ts

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

/* SPDX-FileCopyrightText: 2025-present UsagePilot */
/* SPDX-License-Identifier: MIT */

/**
 * Configuration options for UsagePilot
 */
export interface UsagePilotConfig {
  /** Storage adapter for persisting usage data */
  storage?: StorageAdapter;
  /** Custom dimension extractors for multi-tenant tracking */
  dimensions?: Record<string, DimensionExtractor>;
  /** Batch processing configuration */
  batch?: BatchConfig;
  /** Provider-specific configurations */
  providers?: ProviderConfig;
}

/**
 * Batch processing configuration
 */
export interface BatchConfig {
  /** Maximum number of events per batch (default: 100) */
  size?: number;
  /** Flush interval in milliseconds (default: 30000) */
  flushIntervalMs?: number;
  /** Maximum retry attempts for failed batches (default: 3) */
  maxRetries?: number;
  /** Base delay for exponential backoff in milliseconds (default: 1000) */
  retryDelayMs?: number;
}

/**
 * Provider-specific configuration
 */
export interface ProviderConfig {
  /** OpenAI configuration */
  openai?: {
    apiKey?: string;
    baseURL?: string;
  };
  /** Anthropic configuration */
  anthropic?: {
    apiKey?: string;
    baseURL?: string;
  };
  /** Custom provider configurations */
  [provider: string]: any;
}

/**
 * Function that extracts dimension values from request context
 */
export type DimensionExtractor = (
  request: Request,
  response?: Response,
) => string | Promise<string>;

/**
 * Storage adapter interface for persisting usage data
 */
export interface StorageAdapter {
  /** Initialize the storage adapter */
  initialize(): Promise<void>;
  /** Store usage events */
  store(events: UsageEvent[]): Promise<void>;
  /** Query aggregated usage data */
  query(params: QueryParams): Promise<QueryResult>;
  /** Close storage connections */
  close(): Promise<void>;
}

/**
 * Usage event data structure
 */
export interface UsageEvent {
  /** Timestamp of the event */
  timestamp: Date;
  /** Provider (e.g., 'openai', 'anthropic') */
  provider: string;
  /** Model identifier */
  model: string;
  /** Event type (e.g., 'completion', 'embedding') */
  type: string;
  /** Dimension values for multi-tenant tracking */
  dimensions: Record<string, string>;
  /** Token counts */
  tokens: {
    input?: number;
    output?: number;
    total?: number;
  };
  /** Cost information */
  cost?: {
    input?: number;
    output?: number;
    total?: number;
  };
}

/**
 * Query parameters for usage data
 */
export interface QueryParams {
  /** Filter by dimensions */
  dimensions?: Record<string, string | string[]>;
  /** Start time for query range */
  startTime?: Date;
  /** End time for query range */
  endTime?: Date;
  /** Group by dimensions */
  groupBy?: string[];
  /** Aggregation granularity */
  granularity?: "hour" | "day" | "week" | "month";
  /** Limit number of results */
  limit?: number;
  /** Offset for pagination */
  offset?: number;
}

/**
 * Query result structure
 */
export interface QueryResult {
  /** Aggregated usage data */
  aggregates: UsageAggregate[];
  /** Total count of matching records */
  totalCount: number;
  /** Whether there are more results available */
  hasMore: boolean;
}

/**
 * Aggregated usage data point
 */
export interface UsageAggregate {
  /** Time window for this aggregate */
  timeWindow: {
    start: Date;
    end: Date;
  };
  /** Dimension values for this aggregate */
  dimensions: Record<string, string>;
  /** Aggregated metrics */
  metrics: {
    /** Total events in this aggregate */
    eventCount: number;
    /** Token usage */
    tokens: {
      input: number;
      output: number;
      total: number;
    };
    /** Cost breakdown */
    cost: {
      input: number;
      output: number;
      total: number;
    };
    /** Provider breakdown */
    providers: Record<
      string,
      {
        tokens: { input: number; output: number; total: number };
        cost: { input: number; output: number; total: number };
      }
    >;
  };
}

/**
 * Main UsagePilot class for AI token usage tracking
 */
export class UsagePilot {
  /**
   * Create a new UsagePilot instance
   * @param config Configuration options
   */
  constructor(config?: UsagePilotConfig);

  /**
   * Create a fetch wrapper that automatically tracks token usage
   * @param dimensionExtractor Function to extract dimensions from requests
   * @returns Enhanced fetch function with usage tracking
   */
  createFetch(dimensionExtractor?: DimensionExtractor): typeof fetch;

  /**
   * Query aggregated usage data
   * @param params Query parameters
   * @returns Promise resolving to query results
   */
  query(params: QueryParams): Promise<QueryResult>;
}

/**
 * Default export
 */
export default UsagePilot;