@diogonzafe/tokenwatch 0.2.0 → 0.4.0

package/dist/{index-BQZaFcHQ.d.cts → index-CJKk1hHw.d.ts}

@@ -3,6 +3,10 @@ interface ModelPrice {
     input: number;
     /** USD per 1 million output tokens */
     output: number;
+    /** USD per 1 million cached-read input tokens (e.g. OpenAI: 50% of input, Anthropic: 10% of input) */
+    cachedInput?: number;
+    /** USD per 1 million cache-creation input tokens (Anthropic only, typically 125% of input) */
+    cacheCreationInput?: number;
     /** Maximum context window (input tokens) for this model */
     maxInputTokens?: number;
 }
@@ -12,6 +16,14 @@ interface PricesFile {
     source: string;
     models: PriceMap;
 }
+interface BudgetConfig {
+    /** USD threshold — fires webhookUrl when per-entity cost exceeds this */
+    threshold: number;
+    /** Discord / Slack / generic webhook URL */
+    webhookUrl: string;
+    /** 'once' (default) — fire once per entity lifetime; 'always' — fire on every call that exceeds */
+    mode?: 'once' | 'always';
+}
 interface TrackerConfig {
     /** 'memory' (default), 'sqlite', or a custom IStorage instance (e.g. PostgresStorage, MySQLStorage, MongoStorage) */
     storage?: 'memory' | 'sqlite' | IStorage;
@@ -23,15 +35,29 @@ interface TrackerConfig {
     syncPrices?: boolean;
     /** Per-model price overrides — highest priority */
     customPrices?: PriceMap;
+    /** Warn if bundled/remote prices are older than N hours (default: 72). Set to 0 to disable. */
+    warnIfStaleAfterHours?: number;
+    /** Per-user and per-session budget alerts */
+    budgets?: {
+        perUser?: BudgetConfig;
+        perSession?: BudgetConfig;
+    };
+    /** Log a hint after each call suggesting a cheaper model in the same family when savings > 50% */
+    suggestions?: boolean;
 }
 interface UsageEntry {
     model: string;
+    /** Regular (non-cached) input tokens */
     inputTokens: number;
     outputTokens: number;
     /** Reasoning/thinking tokens (OpenAI o1/o3/o4). Priced as output tokens.
      *  For Anthropic, this is an approximation (thinking block chars ÷ 4) and is
      *  informational only — thinking output is already included in outputTokens. */
     reasoningTokens?: number;
+    /** Cache-read input tokens (OpenAI: subset of prompt_tokens at 50% price; Anthropic: cache_read_input_tokens at 10% price) */
+    cachedTokens?: number;
+    /** Cache-creation input tokens (Anthropic only: cache_creation_input_tokens at 125% price) */
+    cacheCreationTokens?: number;
     costUSD: number;
     sessionId?: string;
     userId?: string;
@@ -46,6 +72,7 @@ interface ModelStats {
         input: number;
         output: number;
         reasoning: number;
+        cached: number;
     };
 }
 interface SessionStats {
@@ -60,6 +87,14 @@ interface FeatureStats {
     costUSD: number;
     calls: number;
 }
+interface ReportOptions {
+    /** ISO string or Date — only include entries at or after this time */
+    since?: string | Date;
+    /** ISO string or Date — only include entries at or before this time */
+    until?: string | Date;
+    /** Shorthand window: '1h', '6h', '24h', '7d', '30d' — sets `since` relative to now */
+    last?: string;
+}
 interface Report {
     totalCostUSD: number;
     totalTokens: {
@@ -74,6 +109,23 @@ interface Report {
         from: string;
         to: string;
     };
+    /** ISO date of the prices data in use (bundled or remote) */
+    pricesUpdatedAt?: string;
+}
+interface ForecastOptions {
+    /** How many recent hours to use for burn-rate calculation (default: 24) */
+    windowHours?: number;
+}
+interface CostForecast {
+    burnRatePerHour: number;
+    projectedDailyCostUSD: number;
+    projectedMonthlyCostUSD: number;
+    /** Number of hours of data the forecast is based on (may be less than windowHours if tracker is new) */
+    basedOnHours: number;
+    basedOnPeriod: {
+        from: string;
+        to: string;
+    } | null;
 }
 interface IStorage {
     /** Fire-and-forget — implementations may write async and swallow errors internally */
@@ -85,7 +137,8 @@ interface IStorage {
 interface Tracker {
     /** Accumulate a usage entry (called by providers) */
     track(entry: Omit<UsageEntry, 'costUSD' | 'timestamp'>): void;
-    getReport(): Promise<Report>;
+    getReport(options?: ReportOptions): Promise<Report>;
+    getCostForecast(options?: ForecastOptions): Promise<CostForecast>;
     reset(): Promise<void>;
     resetSession(sessionId: string): Promise<void>;
     exportJSON(): Promise<string>;
@@ -93,6 +146,13 @@ interface Tracker {
     /** Returns price and context window info for a model, or null if unknown */
     getModelInfo(model: string): ModelPrice | null;
 }
+interface LazyTracker extends Tracker {
+    /**
+     * Initialize the tracker with the given config. Must be called before any cost is tracked.
+     * Calls before init() are silent no-ops. May only be called once — subsequent calls throw.
+     */
+    init(config?: TrackerConfig): void;
+}
 interface TrackingMeta {
     __sessionId?: string;
     __userId?: string;
@@ -100,4 +160,4 @@ interface TrackingMeta {
     __feature?: string;
 }
 
-export type { IStorage as I, ModelPrice as M, PriceMap as P, Report as R, SessionStats as S, TrackerConfig as T, UsageEntry as U, Tracker as a, TrackingMeta as b, ModelStats as c, PricesFile as d, UserStats as e };
+export type { BudgetConfig as B, CostForecast as C, FeatureStats as F, IStorage as I, LazyTracker as L, ModelPrice as M, PriceMap as P, Report as R, SessionStats as S, TrackerConfig as T, UsageEntry as U, Tracker as a, TrackingMeta as b, ForecastOptions as c, ModelStats as d, PricesFile as e, ReportOptions as f, UserStats as g };