burnwatch 0.2.0 → 0.4.0

package/dist/types-fDMu4rOd.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Confidence tiers for spend tracking.
+ *
+ * LIVE  — Real billing API data
+ * CALC  — Fixed monthly cost, user-entered
+ * EST   — Estimated from usage signals + pricing formula
+ * BLIND — Detected in project, no tracking configured
+ */
+type ConfidenceTier = "live" | "calc" | "est" | "blind" | "excluded";
+declare const CONFIDENCE_BADGES: Record<ConfidenceTier, string>;
+/** How a service charges — determines tracking strategy. */
+type BillingModel = "token_usage" | "credit_pool" | "per_unit" | "percentage" | "flat_monthly" | "tiered" | "compute" | "unknown";
+/** How cost scales — helps the agent reason about future spend. */
+type ScalingShape = "linear" | "linear_burndown" | "tiered_jump" | "percentage" | "fixed" | "unknown";
+/** A plan tier option for a service in the registry. */
+interface PlanTier {
+    /** Human-readable plan name */
+    name: string;
+    /** Plan type: usage (pay-as-you-go), flat (fixed monthly), exclude (don't track) */
+    type: "usage" | "flat" | "exclude";
+    /** Monthly base cost for flat plans */
+    monthlyBase?: number;
+    /** Whether this plan requires an API key for tracking */
+    requiresKey?: boolean;
+    /** Whether this is the default/most common plan */
+    default?: boolean;
+}
+/** Risk category for service grouping in interactive init. */
+type ServiceRiskCategory = "llm" | "usage" | "infra" | "flat";
+/** A service definition from the registry. */
+interface ServiceDefinition {
+    /** Unique service identifier */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Package names in npm/pip that indicate this service */
+    packageNames: string[];
+    /** Env var patterns that indicate this service */
+    envPatterns: string[];
+    /** Import patterns to scan for (regex strings) */
+    importPatterns: string[];
+    /** Keywords that indicate mentions in prompts */
+    mentionKeywords: string[];
+    /** Billing model */
+    billingModel: BillingModel;
+    /** How cost scales */
+    scalingShape: ScalingShape;
+    /** What tier of tracking is available */
+    apiTier: ConfidenceTier;
+    /** Billing API endpoint, if available */
+    apiEndpoint?: string;
+    /** Pricing details */
+    pricing?: {
+        /** Human-readable formula */
+        formula?: string;
+        /** Rate per unit, if applicable */
+        unitRate?: number;
+        /** Unit name (token, credit, email, session, etc.) */
+        unitName?: string;
+        /** Monthly base cost, if flat */
+        monthlyBase?: number;
+    };
+    /** Known gotchas that affect cost */
+    gotchas?: string[];
+    /** Alternative services (free or cheaper) */
+    alternatives?: string[];
+    /** Documentation URL */
+    docsUrl?: string;
+    /** Last time pricing was verified */
+    lastVerified?: string;
+    /** Notes about recent pricing changes */
+    pricingNotes?: string;
+    /** Available plan tiers for interactive init */
+    plans?: PlanTier[];
+    /** Whether the plan can be auto-detected from an API key */
+    autoDetectPlan?: boolean;
+}
+/** A tracked service instance — a service definition + user config. */
+interface TrackedService {
+    /** Service definition ID */
+    serviceId: string;
+    /** How this service was detected */
+    detectedVia: DetectionSource[];
+    /** User-configured monthly budget */
+    budget?: number;
+    /** Whether the user has provided an API/billing key */
+    hasApiKey: boolean;
+    /** Override confidence tier (e.g., user provided billing key upgrades to LIVE) */
+    tierOverride?: ConfidenceTier;
+    /** User-entered monthly plan cost (for CALC tier) */
+    planCost?: number;
+    /** When this service was first detected */
+    firstDetected: string;
+    /** Explicitly excluded from tracking by user */
+    excluded?: boolean;
+    /** Plan name selected during interactive init */
+    planName?: string;
+}
+type DetectionSource = "package_json" | "env_var" | "import_scan" | "prompt_mention" | "git_diff" | "manual";
+/** A spend snapshot for a single service at a point in time. */
+interface SpendSnapshot {
+    serviceId: string;
+    /** Current period spend (or estimate) */
+    spend: number;
+    /** Is the spend figure exact or estimated? */
+    isEstimate: boolean;
+    /** Confidence tier for this reading */
+    tier: ConfidenceTier;
+    /** Budget allocated */
+    budget?: number;
+    /** Percentage of budget consumed */
+    budgetPercent?: number;
+    /** Budget status */
+    status: "healthy" | "caution" | "over" | "unknown";
+    /** Human-readable status label */
+    statusLabel: string;
+    /** Raw data from billing API, if available */
+    raw?: Record<string, unknown>;
+    /** Timestamp of this snapshot */
+    timestamp: string;
+}
+/** The full spend brief, injected at session start. */
+interface SpendBrief {
+    projectName: string;
+    generatedAt: string;
+    period: string;
+    services: SpendSnapshot[];
+    totalSpend: number;
+    totalIsEstimate: boolean;
+    estimateMargin: number;
+    untrackedCount: number;
+    alerts: SpendAlert[];
+}
+interface SpendAlert {
+    serviceId: string;
+    type: "over_budget" | "near_budget" | "new_service" | "stale_data" | "blind_service";
+    message: string;
+    severity: "warning" | "critical" | "info";
+}
+/** Ledger entry — one row in spend-ledger.md */
+interface LedgerEntry {
+    serviceId: string;
+    serviceName: string;
+    spend: number;
+    isEstimate: boolean;
+    tier: ConfidenceTier;
+    budget?: number;
+    statusLabel: string;
+}
+/** Event logged to events.jsonl */
+interface SpendEvent {
+    timestamp: string;
+    sessionId: string;
+    type: "session_start" | "session_end" | "service_detected" | "service_mentioned" | "spend_polled" | "budget_alert" | "ledger_written" | "cost_impact";
+    data: Record<string, unknown>;
+}
+/** A cost impact estimate for a file change. */
+interface CostImpact {
+    serviceId: string;
+    serviceName: string;
+    filePath: string;
+    /** Number of SDK call sites found */
+    callCount: number;
+    /** Detected multipliers (loops, .map(), etc.) */
+    multipliers: string[];
+    /** Effective multiplier applied to call count */
+    multiplierFactor: number;
+    /** Estimated monthly invocations */
+    monthlyInvocations: number;
+    /** Low estimate monthly cost */
+    costLow: number;
+    /** High estimate monthly cost */
+    costHigh: number;
+    /** Gotcha-based cost range explanation */
+    rangeExplanation?: string;
+}
+
+export { type BillingModel as B, type CostImpact as C, type DetectionSource as D, type LedgerEntry as L, type PlanTier as P, type ServiceDefinition as S, type TrackedService as T, type SpendSnapshot as a, type SpendBrief as b, type ConfidenceTier as c, type SpendEvent as d, CONFIDENCE_BADGES as e, type ScalingShape as f, type ServiceRiskCategory as g, type SpendAlert as h };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "burnwatch",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Passive cost memory for vibe coding — detects paid services, tracks spend, injects budget context into your AI coding sessions.",
   "type": "module",
   "bin": {

package/registry.json

@@ -1,6 +1,6 @@
 {
   "$schema": "./registry.schema.json",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "lastUpdated": "2026-03-24",
   "services": {
     "anthropic": {
@@ -18,6 +18,13 @@
         "formula": "input_tokens * input_rate + output_tokens * output_rate",
         "unitName": "token"
       },
+      "plans": [
+        { "name": "API Usage", "type": "usage", "requiresKey": true, "default": true },
+        { "name": "Max ($100/mo)", "type": "flat", "monthlyBase": 100 },
+        { "name": "Max ($200/mo)", "type": "flat", "monthlyBase": 200 },
+        { "name": "Pro ($20/mo)", "type": "flat", "monthlyBase": 20 },
+        { "name": "Don't track for this project", "type": "exclude" }
+      ],
       "gotchas": [
         "Admin API key required for billing data — standard API key only allows inference",
         "Costs vary significantly by model: Haiku ~$0.25/MTok, Sonnet ~$3/MTok, Opus ~$15/MTok"
@@ -41,6 +48,13 @@
         "formula": "input_tokens * input_rate + output_tokens * output_rate",
         "unitName": "token"
       },
+      "plans": [
+        { "name": "API Usage", "type": "usage", "requiresKey": true, "default": true },
+        { "name": "ChatGPT Plus ($20/mo)", "type": "flat", "monthlyBase": 20 },
+        { "name": "ChatGPT Pro ($200/mo)", "type": "flat", "monthlyBase": 200 },
+        { "name": "ChatGPT Team ($25/user/mo)", "type": "flat", "monthlyBase": 25 },
+        { "name": "Don't track for this project", "type": "exclude" }
+      ],
       "gotchas": [
         "Organization-level API key may be needed for usage data",
         "Image generation (DALL-E) billed per image, not per token"
@@ -63,6 +77,12 @@
         "formula": "input_tokens * input_rate + output_tokens * output_rate",
         "unitName": "token"
       },
+      "plans": [
+        { "name": "API Usage (pay-as-you-go)", "type": "usage", "requiresKey": false, "default": true },
+        { "name": "Free tier (rate-limited)", "type": "flat", "monthlyBase": 0 },
+        { "name": "Google One AI Premium ($20/mo)", "type": "flat", "monthlyBase": 20 },
+        { "name": "Don't track for this project", "type": "exclude" }
+      ],
       "gotchas": [
         "Free tier available with rate limits",
         "No standalone billing API for AI Studio — check Google Cloud Console"
@@ -85,6 +105,11 @@
         "formula": "tokens * rate_per_token",
         "unitName": "token"
       },
+      "plans": [
+        { "name": "API Usage (pay-as-you-go)", "type": "usage", "requiresKey": false, "default": true },
+        { "name": "Free tier (50M tokens)", "type": "flat", "monthlyBase": 0 },
+        { "name": "Don't track for this project", "type": "exclude" }
+      ],
       "gotchas": [
         "Embedding-only service — cost scales with document corpus size"
       ],
@@ -107,6 +132,12 @@
         "formula": "base_plan + function_invocations + bandwidth + edge_requests",
         "monthlyBase": 20
       },
+      "plans": [
+        { "name": "Hobby (Free)", "type": "flat", "monthlyBase": 0, "default": true },
+        { "name": "Pro ($20/mo)", "type": "flat", "monthlyBase": 20 },
+        { "name": "Enterprise (custom)", "type": "usage", "requiresKey": true },
+        { "name": "Don't track for this project", "type": "exclude" }
+      ],
       "gotchas": [
         "Pro plan is $20/mo base, but overages on functions, bandwidth, and edge requests can spike",
         "Edge Function pricing differs from Serverless Function pricing",
@@ -131,6 +162,13 @@
         "formula": "plan_base + storage_overage + bandwidth_overage + function_invocations",
         "monthlyBase": 25
       },
+      "plans": [
+        { "name": "Free", "type": "flat", "monthlyBase": 0, "default": true },
+        { "name": "Pro ($25/mo)", "type": "flat", "monthlyBase": 25 },
+        { "name": "Team ($599/mo)", "type": "flat", "monthlyBase": 599 },
+        { "name": "Enterprise (custom)", "type": "usage", "requiresKey": true },
+        { "name": "Don't track for this project", "type": "exclude" }
+      ],
       "gotchas": [
         "Storage charges accumulate even when idle",
         "Database size can grow quickly with unoptimized queries or missing cleanup",
@@ -156,6 +194,10 @@
         "unitRate": 0.029,
         "unitName": "transaction"
       },
+      "plans": [
+        { "name": "Standard (2.9% + 30¢)", "type": "usage", "requiresKey": true, "default": true },
+        { "name": "Don't track for this project", "type": "exclude" }
+      ],
       "gotchas": [
         "2.9% + $0.30 per successful card charge — this is processing fees, not SaaS cost",
         "International cards and currency conversion add extra fees",
@@ -181,6 +223,15 @@
         "unitRate": 0.00015,
         "unitName": "credit"
       },
+      "plans": [
+        { "name": "Discovery (Free, 1K credits)", "type": "flat", "monthlyBase": 0 },
+        { "name": "Starter ($30/mo, 200K credits)", "type": "flat", "monthlyBase": 30 },
+        { "name": "Scale ($80/mo, 1M credits)", "type": "flat", "monthlyBase": 80, "default": true },
+        { "name": "Business ($200/mo, 5M credits)", "type": "flat", "monthlyBase": 200 },
+        { "name": "Enterprise (custom)", "type": "usage", "requiresKey": true },
+        { "name": "Don't track for this project", "type": "exclude" }
+      ],
+      "autoDetectPlan": true,
       "gotchas": [
         "Anti-bot bypass options consume 5-25x base credits per request",
         "JavaScript rendering adds extra credit cost",
@@ -204,6 +255,13 @@
         "formula": "sessions * per_session_rate",
         "unitName": "session"
       },
+      "plans": [
+        { "name": "Hobby (Free, 100 sessions)", "type": "flat", "monthlyBase": 0, "default": true },
+        { "name": "Startup ($150/mo)", "type": "flat", "monthlyBase": 150 },
+        { "name": "Scale ($600/mo)", "type": "flat", "monthlyBase": 600 },
+        { "name": "Enterprise (custom)", "type": "usage", "requiresKey": false },
+        { "name": "Don't track for this project", "type": "exclude" }
+      ],
       "gotchas": [
         "Session duration affects cost — long-running browser sessions burn more",
         "Concurrent session limits may cause queuing on lower plans"
@@ -227,6 +285,12 @@
         "unitRate": 0.000002,
         "unitName": "command"
       },
+      "plans": [
+        { "name": "Free (10K commands/day)", "type": "flat", "monthlyBase": 0, "default": true },
+        { "name": "Pay-as-you-go", "type": "usage", "requiresKey": false },
+        { "name": "Pro ($280/mo)", "type": "flat", "monthlyBase": 280 },
+        { "name": "Don't track for this project", "type": "exclude" }
+      ],
       "gotchas": [
         "Free tier includes 10K commands/day",
         "Pay-as-you-go is $0.2 per 100K commands after free tier"
@@ -249,6 +313,12 @@
         "formula": "emails_sent * per_email_rate",
         "unitName": "email"
       },
+      "plans": [
+        { "name": "Free (100 emails/day)", "type": "flat", "monthlyBase": 0, "default": true },
+        { "name": "Pro ($20/mo, 50K emails)", "type": "flat", "monthlyBase": 20 },
+        { "name": "Enterprise ($400/mo)", "type": "flat", "monthlyBase": 400 },
+        { "name": "Don't track for this project", "type": "exclude" }
+      ],
       "gotchas": [
         "Free tier: 100 emails/day, 3000/month",
         "Pro plan: $20/mo for 50K emails",
@@ -272,6 +342,13 @@
         "formula": "plan_base + function_runs_overage",
         "unitName": "function run"
       },
+      "plans": [
+        { "name": "Free (5K runs/mo)", "type": "flat", "monthlyBase": 0, "default": true },
+        { "name": "Launch ($50/mo)", "type": "flat", "monthlyBase": 50 },
+        { "name": "Growth ($150/mo)", "type": "flat", "monthlyBase": 150 },
+        { "name": "Enterprise (custom)", "type": "usage", "requiresKey": false },
+        { "name": "Don't track for this project", "type": "exclude" }
+      ],
       "gotchas": [
         "Free tier: 24hr event history, community support",
         "Cost scales with function step count, not just invocation count"
@@ -294,6 +371,11 @@
         "formula": "events beyond free tier * per_event_rate",
         "unitName": "event"
       },
+      "plans": [
+        { "name": "Free (1M events/mo)", "type": "flat", "monthlyBase": 0, "default": true },
+        { "name": "Pay-as-you-go (usage-based)", "type": "usage", "requiresKey": false },
+        { "name": "Don't track for this project", "type": "exclude" }
+      ],
       "gotchas": [
         "Free tier: 1M events/month — generous but easy to exceed with high-traffic apps",
         "Session replay, feature flags, and surveys have separate pricing",
@@ -316,6 +398,12 @@
       "pricing": {
         "formula": "Varies by service — S3, ECS, Lambda, etc. each have distinct pricing"
       },
+      "plans": [
+        { "name": "Pay-as-you-go", "type": "usage", "requiresKey": false, "default": true },
+        { "name": "AWS Free Tier (12 months)", "type": "flat", "monthlyBase": 0 },
+        { "name": "Set custom budget estimate", "type": "usage", "requiresKey": false },
+        { "name": "Don't track for this project", "type": "exclude" }
+      ],
       "gotchas": [
         "AWS Cost Explorer API exists but requires IAM permissions and is itself billed",
         "Data transfer costs are the most common surprise on AWS bills",