burnwatch 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,246 @@
+/**
+ * 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";
+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 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;
+}
+/** 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;
+}
+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";
+    data: Record<string, unknown>;
+}
+
+/**
+ * Load the service registry.
+ * Checks project-local override first, then falls back to bundled registry.
+ */
+declare function loadRegistry(projectRoot?: string): Map<string, ServiceDefinition>;
+/** Get a single service definition by ID. */
+declare function getService(id: string, projectRoot?: string): ServiceDefinition | undefined;
+/** Get all service definitions. */
+declare function getAllServices(projectRoot?: string): ServiceDefinition[];
+
+interface DetectionResult {
+    service: ServiceDefinition;
+    sources: DetectionSource[];
+    details: string[];
+}
+/**
+ * Run all detection surfaces against the current project.
+ * Returns services detected via any combination of:
+ * - package.json dependencies
+ * - environment variable patterns
+ * - import statement scanning
+ * - (prompt mention scanning is handled separately in hooks)
+ */
+declare function detectServices(projectRoot: string): DetectionResult[];
+/**
+ * Detect services mentioned in a prompt string.
+ * Used by the UserPromptSubmit hook.
+ */
+declare function detectMentions(prompt: string, projectRoot?: string): DetectionResult[];
+/**
+ * Detect new services introduced in a file change.
+ * Used by the PostToolUse hook for Write/Edit events.
+ */
+declare function detectInFileChange(filePath: string, content: string, projectRoot?: string): DetectionResult[];
+
+/**
+ * Format a spend brief as a text block for injection into Claude's context.
+ */
+declare function formatBrief(brief: SpendBrief): string;
+/**
+ * Format a single-service spend card for injection on mention.
+ */
+declare function formatSpendCard(snapshot: SpendSnapshot): string;
+/**
+ * Build a SpendBrief from snapshots and project config.
+ */
+declare function buildBrief(projectName: string, snapshots: SpendSnapshot[], blindCount: number): SpendBrief;
+/**
+ * Build a SpendSnapshot from tracked service data.
+ */
+declare function buildSnapshot(serviceId: string, tier: ConfidenceTier, spend: number, budget?: number): SpendSnapshot;
+
+/**
+ * Write the spend ledger as a human-readable markdown file.
+ * Designed to be git-committable and readable in 10 seconds.
+ */
+declare function writeLedger(brief: SpendBrief, projectRoot?: string): void;
+/**
+ * Append an event to the append-only event log.
+ */
+declare function logEvent(event: SpendEvent, projectRoot?: string): void;
+/**
+ * Read recent events from the event log.
+ */
+declare function readRecentEvents(count: number, projectRoot?: string): SpendEvent[];
+/**
+ * Save a spend snapshot to the snapshots directory.
+ * Used for delta computation across sessions.
+ */
+declare function saveSnapshot(brief: SpendBrief, projectRoot?: string): void;
+/**
+ * Read the most recent snapshot, if any.
+ */
+declare function readLatestSnapshot(projectRoot?: string): SpendBrief | null;
+
+/**
+ * Paths for burnwatch configuration and data.
+ *
+ * Hybrid model:
+ * - Global config (API keys, service credentials): ~/.config/burnwatch/
+ * - Project config (budgets, tracked services): .burnwatch/
+ * - Project data (ledger, events, cache): .burnwatch/data/
+ */
+/** Global config directory — stores API keys, never in project dirs. */
+declare function globalConfigDir(): string;
+/** Project config directory — stores budgets, tracked services. */
+declare function projectConfigDir(projectRoot?: string): string;
+/** Project data directory — stores ledger, events, cache. */
+declare function projectDataDir(projectRoot?: string): string;
+interface GlobalConfig {
+    services: Record<string, {
+        apiKey?: string;
+        token?: string;
+        orgId?: string;
+    }>;
+}
+declare function readGlobalConfig(): GlobalConfig;
+declare function writeGlobalConfig(config: GlobalConfig): void;
+interface ProjectConfig {
+    projectName: string;
+    services: Record<string, TrackedService>;
+    createdAt: string;
+    updatedAt: string;
+}
+declare function readProjectConfig(projectRoot?: string): ProjectConfig | null;
+declare function writeProjectConfig(config: ProjectConfig, projectRoot?: string): void;
+/** Ensure all project directories exist. */
+declare function ensureProjectDirs(projectRoot?: string): void;
+/** Check if burnwatch is initialized in the given project. */
+declare function isInitialized(projectRoot?: string): boolean;
+
+export { type BillingModel, CONFIDENCE_BADGES, type ConfidenceTier, type DetectionSource, type LedgerEntry, type ScalingShape, type ServiceDefinition, type SpendAlert, type SpendBrief, type SpendEvent, type SpendSnapshot, type TrackedService, buildBrief, buildSnapshot, detectInFileChange, detectMentions, detectServices, ensureProjectDirs, formatBrief, formatSpendCard, getAllServices, getService, globalConfigDir, isInitialized, loadRegistry, logEvent, projectConfigDir, projectDataDir, readGlobalConfig, readLatestSnapshot, readProjectConfig, readRecentEvents, saveSnapshot, writeGlobalConfig, writeLedger, writeProjectConfig };