vibezcheck 0.2.0 → 0.4.0

package/dist/types-Zbzxg-Ka.d.ts

@@ -0,0 +1,261 @@
+import Stripe from 'stripe';
+
+/**
+ * Known supported model identifiers with full IDE autocomplete
+ */
+type SupportedOpenAIModel = 'openai/gpt-4o' | 'openai/gpt-4o-mini' | 'openai/o1' | 'openai/o1-mini' | 'openai/o3' | 'openai/o3-mini' | 'openai/gpt-5' | 'openai/gpt-5-mini' | 'openai/gpt-5.6-sol' | 'openai/gpt-5.6-terra' | 'openai/gpt-5.6-luna' | 'gpt-4o' | 'gpt-4o-mini' | 'o1' | 'o1-mini' | 'o3' | 'o3-mini' | 'gpt-5' | 'gpt-5-mini' | 'gpt-5.6-sol' | 'gpt-5.6-terra' | 'gpt-5.6-luna';
+type SupportedAnthropicModel = 'anthropic/claude-3-7-sonnet' | 'anthropic/claude-3-5-sonnet' | 'anthropic/claude-3-5-haiku' | 'anthropic/claude-opus-5' | 'anthropic/haiku-4.5' | 'claude-3-7-sonnet' | 'claude-3-5-sonnet' | 'claude-3-5-haiku' | 'claude-opus-5' | 'haiku-4.5';
+type SupportedGoogleModel = 'google/gemini-2.0-flash' | 'google/gemini-1.5-pro' | 'google/gemini-3.7-flash' | 'google/gemini-3.1-pro' | 'gemini-2.0-flash' | 'gemini-1.5-pro' | 'gemini-3.7-flash' | 'gemini-3.1-pro';
+type SupportedDeepSeekModel = 'deepseek/deepseek-chat' | 'deepseek/deepseek-reasoner' | 'deepseek/deepseek-v4-pro' | 'deepseek-chat' | 'deepseek-reasoner' | 'deepseek-v4-pro';
+type KnownModel = SupportedOpenAIModel | SupportedAnthropicModel | SupportedGoogleModel | SupportedDeepSeekModel;
+/**
+ * Union of all known model IDs with loose string fallback for custom / future models
+ */
+type SupportedModel = KnownModel | (string & {});
+/**
+ * Detailed token usage breakdown
+ */
+interface TokenUsage {
+    /** Input/Prompt tokens */
+    inputTokens: number;
+    /** Total output/completion tokens (including reasoning) */
+    outputTokens: number;
+    /** Total tokens (input + output) */
+    totalTokens: number;
+    /** Hidden reasoning / thinking tokens (e.g. o1/o3/GPT-5, Claude 3.7 Thinking, Gemini 3.7 Thoughts) */
+    reasoningTokens?: number;
+    /** Visible output tokens (outputTokens - reasoningTokens) */
+    visibleOutputTokens?: number;
+    /** Cached input tokens read from KV cache / prompt cache */
+    cachedTokens?: number;
+    /** Cache write / creation tokens */
+    cacheWriteTokens?: number;
+}
+/**
+ * Calculated inference cost breakdown
+ */
+interface InferenceCost {
+    /** Cost for standard input prompt tokens in USD */
+    inputCostUSD: number;
+    /** Cost for output completion tokens in USD */
+    outputCostUSD: number;
+    /** Cost for reasoning/thinking tokens in USD (if applicable) */
+    reasoningCostUSD?: number;
+    /** Savings from prompt caching in USD */
+    cachedDiscountUSD?: number;
+    /** Total computed base inference cost in USD */
+    totalUSD: number;
+    /** Retail price after developer markup (if markup applied) */
+    retailUSD?: number;
+    /** Currency (defaults to 'USD') */
+    currency: string;
+}
+/**
+ * Full usage event emitted upon completion of an LLM call or stream
+ */
+interface UsageEvent {
+    /** Unique ID for the event */
+    id?: string;
+    /** Timestamp ISO string */
+    timestamp: string;
+    /** Model name (e.g. 'gpt-5.6-sol', 'claude-3-7-sonnet') */
+    model: string;
+    /** Provider (e.g. 'openai', 'anthropic', 'google', 'mistral', 'groq', 'deepseek', 'generic') */
+    provider: string;
+    /** Token breakdown */
+    usage: TokenUsage;
+    /** Computed cost */
+    cost: InferenceCost;
+    /** Customer ID (Stripe customer ID, internal userId, or anonymous) */
+    customerId?: string;
+    /** Optional customer email */
+    customerEmail?: string;
+    /** Custom developer metadata (e.g. userId, orgId, feature, session) */
+    metadata?: Record<string, string | number | boolean>;
+}
+/**
+ * Customer identification parameter: can be a string ('cus_xxx' or 'user@example.com') or an object
+ */
+type CustomerParam = string | {
+    id?: string;
+    userId?: string;
+    email?: string;
+    name?: string;
+    metadata?: Record<string, string>;
+};
+/**
+ * Event emitted when a circuit breaker budget or token limit is reached
+ */
+interface BudgetExceededEvent {
+    reason: 'cost_per_call_exceeded' | 'total_budget_exceeded' | 'max_tokens_exceeded';
+    limit: number;
+    current: number;
+    model: string;
+    customerId?: string;
+    message: string;
+}
+/**
+ * Error thrown when an Agent Circuit Breaker trips
+ */
+declare class VibezCircuitBreakerError extends Error {
+    readonly event: BudgetExceededEvent;
+    constructor(event: BudgetExceededEvent);
+}
+/**
+ * Circuit Breaker / Budget Guardrail Configuration
+ */
+interface CircuitBreakerOptions {
+    /** Maximum allowed USD cost for a single generation or stream (default: 0.50) */
+    maxCostPerCallUSD?: number;
+    /** Cumulative budget limit for customer/session in USD (e.g. 5.00) */
+    maxBudgetUSD?: number;
+    /** Hard ceiling on total tokens per generation (e.g. 10000) */
+    maxTokensPerCall?: number;
+    /** Model to gracefully fall back to if budget limit is exceeded instead of hard erroring */
+    fallbackModelOnBudget?: string;
+    /** Callback fired when circuit breaker trips */
+    onBudgetExceeded?: (event: BudgetExceededEvent) => void | Promise<void>;
+    /** Whether to throw a VibezCircuitBreakerError if limit exceeded (default: false) */
+    throwOnBudgetExceeded?: boolean;
+}
+/**
+ * Billing Configuration (Postpaid metered invoice vs Prepaid credit wallet)
+ */
+interface BillingConfig {
+    /** 'postpaid' = Invoiced at month's end; 'prepaid' = Deducted from credit wallet, locks at $0 */
+    mode?: 'postpaid' | 'prepaid';
+    /** Available prepaid credit balance in USD */
+    balanceUSD?: number;
+    /** Action when balance is low: 'warn' logs/sends event, 'throw' throws CreditExhaustedError */
+    onLowBalance?: 'warn' | 'throw';
+}
+/**
+ * Profit Pricing & Markup Configuration
+ */
+interface PricingConfig {
+    /** Profit margin multiplier (e.g. 1.5 = Cost + 50% profit margin automatically added) */
+    margin?: number;
+    /** Minimum charge in USD for any single call (e.g. 0.01 = at least 1 cent) */
+    minimumChargeUSD?: number;
+}
+/**
+ * Inline Rate Card Configuration for 1-line custom/newly released model pricing
+ */
+interface InlineRateConfig {
+    /** Input tokens price per 1 Million tokens in USD */
+    in: number;
+    /** Output tokens price per 1 Million tokens in USD */
+    out?: number;
+    output?: number;
+    /** Reasoning/thinking tokens price per 1 Million tokens in USD (optional) */
+    reasoning?: number;
+    /** Cached input tokens price per 1 Million tokens in USD (optional) */
+    cached?: number;
+}
+/**
+ * Non-LLM Tool execution metering options
+ */
+interface ToolMeterOptions {
+    /** Fixed cost in USD for this tool execution (e.g. 0.01 for search, 0.04 for image) */
+    costUSD: number;
+    /** Customer identifier to attribute tool cost to */
+    customer?: CustomerParam;
+    /** Additional metadata */
+    metadata?: Record<string, string | number | boolean>;
+}
+/**
+ * Configuration options for the VibezCheck Meter
+ */
+interface MeterOptions extends CircuitBreakerOptions {
+    /** Stripe API Key (sk_* or rk_*). If omitted, runs in local telemetry/free mode */
+    apiKey?: string;
+    /** Existing Stripe SDK instance (optional) */
+    stripe?: Stripe;
+    /** Default Stripe Meter Event Name (default: 'token-billing-tokens') */
+    eventName?: string;
+    /** Batching options to optimize Stripe API calls */
+    batching?: {
+        /** Max events per batch (default: 50) */
+        maxBatchSize?: number;
+        /** Flush interval in milliseconds (default: 50ms) */
+        flushIntervalMs?: number;
+    };
+    /** Callback fired whenever usage is extracted (works with or without Stripe) */
+    onUsage?: (event: UsageEvent) => void | Promise<void>;
+    /** Error handler callback */
+    onError?: (error: Error, events: UsageEvent[]) => void;
+    /** Markup multiplier for retail price calculations (e.g. 1.3 for 30% profit) */
+    markupMultiplier?: number;
+    /** Enable debug console logging (default: false) */
+    debug?: boolean;
+}
+/**
+ * Stream wrap options
+ */
+interface StreamWrapOptions extends CircuitBreakerOptions {
+    /** Customer identifier or email or object */
+    customer?: CustomerParam;
+    /** Direct customer ID string */
+    customerId?: string;
+    /** Model override if not automatically detectable */
+    model?: string;
+    /** Provider override if not automatically detectable */
+    provider?: string;
+    /** Billing mode configuration (postpaid vs prepaid) */
+    billing?: BillingConfig;
+    /** Profit margin & minimum charge configuration */
+    pricing?: PricingConfig;
+    /** 1-line inline pricing rate card */
+    rate?: InlineRateConfig;
+    /** Whether to capture tokens if the client aborts or closes tab mid-stream (default: true) */
+    captureOnAbort?: boolean;
+    /** Execution runtime environment (default: 'auto') */
+    runtime?: 'auto' | 'serverless' | 'edge' | 'node';
+    /** Custom metadata attached to the usage event */
+    metadata?: Record<string, string | number | boolean>;
+    /** Custom usage callback for this specific stream */
+    onUsage?: (event: UsageEvent) => void | Promise<void>;
+}
+/**
+ * Direct usage recording options
+ */
+interface RecordUsageOptions {
+    model: string;
+    provider?: string;
+    inputTokens: number;
+    outputTokens: number;
+    reasoningTokens?: number;
+    cachedTokens?: number;
+    customer?: CustomerParam;
+    customerId?: string;
+    metadata?: Record<string, string | number | boolean>;
+}
+/**
+ * Model Pricing Rates (per 1 Million Tokens in USD)
+ */
+interface ModelPricingRates {
+    inputPer1M: number;
+    outputPer1M: number;
+    cachedInputPer1M?: number;
+    reasoningPer1M?: number;
+    cacheWritePer1M?: number;
+    currency?: string;
+}
+/**
+ * Aggregated Usage Summary
+ */
+interface UsageSummary {
+    totalRequests: number;
+    totalTokens: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalReasoningTokens: number;
+    totalCostUSD: number;
+    byModel: Record<string, {
+        requests: number;
+        tokens: number;
+        costUSD: number;
+    }>;
+}
+
+export { type BillingConfig as B, type CustomerParam as C, type InferenceCost as I, type KnownModel as K, type MeterOptions as M, type PricingConfig as P, type RecordUsageOptions as R, type StreamWrapOptions as S, type TokenUsage as T, type UsageEvent as U, VibezCircuitBreakerError as V, type UsageSummary as a, type BudgetExceededEvent as b, type CircuitBreakerOptions as c, type InlineRateConfig as d, type ModelPricingRates as e, type SupportedAnthropicModel as f, type SupportedDeepSeekModel as g, type SupportedGoogleModel as h, type SupportedModel as i, type SupportedOpenAIModel as j, type ToolMeterOptions as k };

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "vibezcheck",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "The 1-line Stripe Billing and Token Metering engine for LLMs. Track tokens, compute real-time dollar costs, and bill customers with 0ms added latency.",
   "author": "VibezCheck <dev@vibezcheck.xyz> (https://vibezcheck.xyz)",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/seeyouin2x5x/vibezcheck-sdk.git"
+    "url": "git+https://github.com/seeyouin2x5x/vibezcheck-sdk.git"
   },
   "keywords": [
     "stripe",
@@ -71,8 +71,12 @@
       "require": "./dist/react/index.js"
     }
   },
+  "bin": {
+    "vibezcheck": "./bin/vibezcheck.js"
+  },
   "files": [
     "dist",
+    "bin",
     "README.md",
     "LICENSE",
     "package.json"

package/dist/types-CSrSmsd1.d.mts

@@ -1,159 +0,0 @@
-import Stripe from 'stripe';
-
-/**
- * Detailed token usage breakdown
- */
-interface TokenUsage {
-    /** Input/Prompt tokens */
-    inputTokens: number;
-    /** Total output/completion tokens (including reasoning) */
-    outputTokens: number;
-    /** Total tokens (input + output) */
-    totalTokens: number;
-    /** Hidden reasoning / thinking tokens (e.g. o1/o3/GPT-5, Claude 3.7 Thinking, Gemini 3.7 Thoughts) */
-    reasoningTokens?: number;
-    /** Visible output tokens (outputTokens - reasoningTokens) */
-    visibleOutputTokens?: number;
-    /** Cached input tokens read from KV cache / prompt cache */
-    cachedTokens?: number;
-    /** Cache write / creation tokens */
-    cacheWriteTokens?: number;
-}
-/**
- * Calculated inference cost breakdown
- */
-interface InferenceCost {
-    /** Cost for standard input prompt tokens in USD */
-    inputCostUSD: number;
-    /** Cost for output completion tokens in USD */
-    outputCostUSD: number;
-    /** Cost for reasoning/thinking tokens in USD (if applicable) */
-    reasoningCostUSD?: number;
-    /** Savings from prompt caching in USD */
-    cachedDiscountUSD?: number;
-    /** Total computed base inference cost in USD */
-    totalUSD: number;
-    /** Retail price after developer markup (if markup applied) */
-    retailUSD?: number;
-    /** Currency (defaults to 'USD') */
-    currency: string;
-}
-/**
- * Full usage event emitted upon completion of an LLM call or stream
- */
-interface UsageEvent {
-    /** Unique ID for the event */
-    id?: string;
-    /** Timestamp ISO string */
-    timestamp: string;
-    /** Model name (e.g. 'gpt-5.6-sol', 'claude-3-7-sonnet') */
-    model: string;
-    /** Provider (e.g. 'openai', 'anthropic', 'google', 'mistral', 'groq', 'deepseek', 'generic') */
-    provider: string;
-    /** Token breakdown */
-    usage: TokenUsage;
-    /** Computed cost */
-    cost: InferenceCost;
-    /** Customer ID (Stripe customer ID, internal userId, or anonymous) */
-    customerId?: string;
-    /** Optional customer email */
-    customerEmail?: string;
-    /** Custom developer metadata (e.g. userId, orgId, feature, session) */
-    metadata?: Record<string, string | number | boolean>;
-}
-/**
- * Customer identification parameter: can be a string ('cus_xxx' or 'user@example.com') or an object
- */
-type CustomerParam = string | {
-    id?: string;
-    userId?: string;
-    email?: string;
-    name?: string;
-    metadata?: Record<string, string>;
-};
-/**
- * Configuration options for the VibezCheck Meter
- */
-interface MeterOptions {
-    /** Stripe API Key (sk_* or rk_*). If omitted, runs in local telemetry/free mode */
-    apiKey?: string;
-    /** Existing Stripe SDK instance (optional) */
-    stripe?: Stripe;
-    /** Default Stripe Meter Event Name (default: 'token-billing-tokens') */
-    eventName?: string;
-    /** Batching options to optimize Stripe API calls */
-    batching?: {
-        /** Max events per batch (default: 50) */
-        maxBatchSize?: number;
-        /** Flush interval in milliseconds (default: 50ms) */
-        flushIntervalMs?: number;
-    };
-    /** Callback fired whenever usage is extracted (works with or without Stripe) */
-    onUsage?: (event: UsageEvent) => void | Promise<void>;
-    /** Error handler callback */
-    onError?: (error: Error, events: UsageEvent[]) => void;
-    /** Markup multiplier for retail price calculations (e.g. 1.3 for 30% profit) */
-    markupMultiplier?: number;
-    /** Enable debug console logging (default: false) */
-    debug?: boolean;
-}
-/**
- * Stream wrap options
- */
-interface StreamWrapOptions {
-    /** Customer identifier or email or object */
-    customer?: CustomerParam;
-    /** Direct customer ID string */
-    customerId?: string;
-    /** Model override if not automatically detectable */
-    model?: string;
-    /** Provider override if not automatically detectable */
-    provider?: string;
-    /** Custom metadata attached to the usage event */
-    metadata?: Record<string, string | number | boolean>;
-    /** Custom usage callback for this specific stream */
-    onUsage?: (event: UsageEvent) => void | Promise<void>;
-}
-/**
- * Direct usage recording options
- */
-interface RecordUsageOptions {
-    model: string;
-    provider?: string;
-    inputTokens: number;
-    outputTokens: number;
-    reasoningTokens?: number;
-    cachedTokens?: number;
-    customer?: CustomerParam;
-    customerId?: string;
-    metadata?: Record<string, string | number | boolean>;
-}
-/**
- * Model Pricing Rates (per 1 Million Tokens in USD)
- */
-interface ModelPricingRates {
-    inputPer1M: number;
-    outputPer1M: number;
-    cachedInputPer1M?: number;
-    reasoningPer1M?: number;
-    cacheWritePer1M?: number;
-    currency?: string;
-}
-/**
- * Aggregated Usage Summary
- */
-interface UsageSummary {
-    totalRequests: number;
-    totalTokens: number;
-    totalInputTokens: number;
-    totalOutputTokens: number;
-    totalReasoningTokens: number;
-    totalCostUSD: number;
-    byModel: Record<string, {
-        requests: number;
-        tokens: number;
-        costUSD: number;
-    }>;
-}
-
-export type { CustomerParam as C, InferenceCost as I, MeterOptions as M, RecordUsageOptions as R, StreamWrapOptions as S, TokenUsage as T, UsageEvent as U, UsageSummary as a, ModelPricingRates as b };

package/dist/types-CSrSmsd1.d.ts

@@ -1,159 +0,0 @@
-import Stripe from 'stripe';
-
-/**
- * Detailed token usage breakdown
- */
-interface TokenUsage {
-    /** Input/Prompt tokens */
-    inputTokens: number;
-    /** Total output/completion tokens (including reasoning) */
-    outputTokens: number;
-    /** Total tokens (input + output) */
-    totalTokens: number;
-    /** Hidden reasoning / thinking tokens (e.g. o1/o3/GPT-5, Claude 3.7 Thinking, Gemini 3.7 Thoughts) */
-    reasoningTokens?: number;
-    /** Visible output tokens (outputTokens - reasoningTokens) */
-    visibleOutputTokens?: number;
-    /** Cached input tokens read from KV cache / prompt cache */
-    cachedTokens?: number;
-    /** Cache write / creation tokens */
-    cacheWriteTokens?: number;
-}
-/**
- * Calculated inference cost breakdown
- */
-interface InferenceCost {
-    /** Cost for standard input prompt tokens in USD */
-    inputCostUSD: number;
-    /** Cost for output completion tokens in USD */
-    outputCostUSD: number;
-    /** Cost for reasoning/thinking tokens in USD (if applicable) */
-    reasoningCostUSD?: number;
-    /** Savings from prompt caching in USD */
-    cachedDiscountUSD?: number;
-    /** Total computed base inference cost in USD */
-    totalUSD: number;
-    /** Retail price after developer markup (if markup applied) */
-    retailUSD?: number;
-    /** Currency (defaults to 'USD') */
-    currency: string;
-}
-/**
- * Full usage event emitted upon completion of an LLM call or stream
- */
-interface UsageEvent {
-    /** Unique ID for the event */
-    id?: string;
-    /** Timestamp ISO string */
-    timestamp: string;
-    /** Model name (e.g. 'gpt-5.6-sol', 'claude-3-7-sonnet') */
-    model: string;
-    /** Provider (e.g. 'openai', 'anthropic', 'google', 'mistral', 'groq', 'deepseek', 'generic') */
-    provider: string;
-    /** Token breakdown */
-    usage: TokenUsage;
-    /** Computed cost */
-    cost: InferenceCost;
-    /** Customer ID (Stripe customer ID, internal userId, or anonymous) */
-    customerId?: string;
-    /** Optional customer email */
-    customerEmail?: string;
-    /** Custom developer metadata (e.g. userId, orgId, feature, session) */
-    metadata?: Record<string, string | number | boolean>;
-}
-/**
- * Customer identification parameter: can be a string ('cus_xxx' or 'user@example.com') or an object
- */
-type CustomerParam = string | {
-    id?: string;
-    userId?: string;
-    email?: string;
-    name?: string;
-    metadata?: Record<string, string>;
-};
-/**
- * Configuration options for the VibezCheck Meter
- */
-interface MeterOptions {
-    /** Stripe API Key (sk_* or rk_*). If omitted, runs in local telemetry/free mode */
-    apiKey?: string;
-    /** Existing Stripe SDK instance (optional) */
-    stripe?: Stripe;
-    /** Default Stripe Meter Event Name (default: 'token-billing-tokens') */
-    eventName?: string;
-    /** Batching options to optimize Stripe API calls */
-    batching?: {
-        /** Max events per batch (default: 50) */
-        maxBatchSize?: number;
-        /** Flush interval in milliseconds (default: 50ms) */
-        flushIntervalMs?: number;
-    };
-    /** Callback fired whenever usage is extracted (works with or without Stripe) */
-    onUsage?: (event: UsageEvent) => void | Promise<void>;
-    /** Error handler callback */
-    onError?: (error: Error, events: UsageEvent[]) => void;
-    /** Markup multiplier for retail price calculations (e.g. 1.3 for 30% profit) */
-    markupMultiplier?: number;
-    /** Enable debug console logging (default: false) */
-    debug?: boolean;
-}
-/**
- * Stream wrap options
- */
-interface StreamWrapOptions {
-    /** Customer identifier or email or object */
-    customer?: CustomerParam;
-    /** Direct customer ID string */
-    customerId?: string;
-    /** Model override if not automatically detectable */
-    model?: string;
-    /** Provider override if not automatically detectable */
-    provider?: string;
-    /** Custom metadata attached to the usage event */
-    metadata?: Record<string, string | number | boolean>;
-    /** Custom usage callback for this specific stream */
-    onUsage?: (event: UsageEvent) => void | Promise<void>;
-}
-/**
- * Direct usage recording options
- */
-interface RecordUsageOptions {
-    model: string;
-    provider?: string;
-    inputTokens: number;
-    outputTokens: number;
-    reasoningTokens?: number;
-    cachedTokens?: number;
-    customer?: CustomerParam;
-    customerId?: string;
-    metadata?: Record<string, string | number | boolean>;
-}
-/**
- * Model Pricing Rates (per 1 Million Tokens in USD)
- */
-interface ModelPricingRates {
-    inputPer1M: number;
-    outputPer1M: number;
-    cachedInputPer1M?: number;
-    reasoningPer1M?: number;
-    cacheWritePer1M?: number;
-    currency?: string;
-}
-/**
- * Aggregated Usage Summary
- */
-interface UsageSummary {
-    totalRequests: number;
-    totalTokens: number;
-    totalInputTokens: number;
-    totalOutputTokens: number;
-    totalReasoningTokens: number;
-    totalCostUSD: number;
-    byModel: Record<string, {
-        requests: number;
-        tokens: number;
-        costUSD: number;
-    }>;
-}
-
-export type { CustomerParam as C, InferenceCost as I, MeterOptions as M, RecordUsageOptions as R, StreamWrapOptions as S, TokenUsage as T, UsageEvent as U, UsageSummary as a, ModelPricingRates as b };