caplyr 0.1.2 → 0.1.7

package/README.md

@@ -2,7 +2,7 @@
 
 **AI Cost Control Plane** — Stop runaway API bills automatically.
 
-Caplyr sits between your app and AI providers, controlling how requests execute based on cost constraints. Budget guardrails, auto-downgrade, and kill switch — in 2 lines of code.
+Caplyr wraps your AI client and enforces cost controls based on your project settings in the Caplyr dashboard. Budget guardrails, auto-downgrade, and kill switch — in 2 lines of code.
 
 ## Install
 
@@ -18,9 +18,10 @@ import { protect } from "caplyr";
 
 // Wrap your client — everything else stays the same
 const client = protect(new Anthropic(), {
-  apiKey: "caplyr_...",       // Get yours at https://app.caplyr.com
-  budget: 500,                // Monthly cap in dollars
-  fallback: "claude-haiku-3-5-20241022",  // Auto-downgrade target
+  apiKey: "caplyr_...",                    // Get yours at https://app.caplyr.com
+  mode: "cost_protect",                    // Enforce budget limits
+  budget: { monthly: 500, daily: 50 },    // Budget caps in dollars
+  fallback: "claude-haiku-4-5-20251001",   // Auto-downgrade target
 });
 
 // Use exactly as before — Caplyr is invisible
@@ -39,7 +40,8 @@ import { protect } from "caplyr";
 
 const client = protect(new OpenAI(), {
   apiKey: "caplyr_...",
-  budget: 500,
+  mode: "cost_protect",
+  budget: { monthly: 500 },
   fallback: "gpt-4o-mini",
 });
 
@@ -53,42 +55,57 @@ const response = await client.chat.completions.create({
 
 | Feature | Description |
 |---------|-------------|
-| **Budget Guardrails** | Daily and monthly caps enforced at the SDK level. Hit the limit → requests are blocked or downgraded. |
+| **Budget Guardrails** | Daily and monthly caps. Hit the limit → requests are blocked. Budget limits are configured in the Caplyr dashboard and enforced via the SDK. |
 | **Auto Downgrade** | When budget threshold is reached, automatically route to a cheaper model. Your app keeps working. |
-| **Kill Switch** | One-click emergency stop. Halts all AI API calls instantly. |
+| **Kill Switch** | One-click emergency stop from the dashboard. Halts all AI API calls instantly. |
+
+## How Enforcement Works
+
+Budget limits are managed **server-side** in your Caplyr project settings. The SDK sends your configured `budget` values to the server via heartbeats, and the server returns the current budget status (usage, limits, kill switch state). The SDK enforces limits locally based on that server response — the server is the source of truth, not the local config.
+
+If you set `budget` in the SDK but have different limits in your dashboard, the dashboard settings take precedence.
 
 ## Modes
 
 ```typescript
-// Alert-only (default): observe and project, don't enforce
-protect(client, { apiKey: "...", mode: "alert_only" });
+// Alert-only (default): observe and log, don't enforce
+protect(client, { apiKey: "..." });
 
 // Cost protect: enforce budget caps and auto-downgrade
-protect(client, { apiKey: "...", mode: "cost_protect", budget: 500 });
+protect(client, { apiKey: "...", mode: "cost_protect", budget: { monthly: 500 } });
 ```
 
+> **Tip:** Setting `budget` without specifying `mode` will automatically enable `cost_protect`.
+
+## Currently Wrapped Endpoints
+
+- **Anthropic:** `client.messages.create()`
+- **OpenAI:** `client.chat.completions.create()`
+
+Other endpoints (embeddings, images, Responses API) are not yet wrapped. Streaming requests (`stream: true`) are passed through but usage tracking may be incomplete.
+
 ## Configuration
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `apiKey` | `string` | required | Your Caplyr project API key |
-| `budget` | `number` | — | Monthly budget cap in dollars |
-| `dailyBudget` | `number` | — | Daily budget cap in dollars |
+| `budget` | `{ monthly?: number, daily?: number }` | — | Budget caps in dollars |
 | `fallback` | `string` | auto | Fallback model for auto-downgrade |
-| `mode` | `string` | `"alert_only"` | `"alert_only"` \| `"cost_protect"` \| `"kill_switch"` |
+| `mode` | `"alert_only" \| "cost_protect"` | `"alert_only"` | Enforcement mode |
 | `downgradeThreshold` | `number` | `0.8` | Budget % at which downgrade activates |
 | `endpoint_tag` | `string` | — | Custom tag for cost attribution |
+| `dashboardUrl` | `string` | `https://app.caplyr.com` | Dashboard URL for error messages |
+| `endpoint` | `string` | `https://api.caplyr.com` | API endpoint for heartbeat/ingestion |
 
 ## Handling Blocked Requests
 
-When a request is blocked, Caplyr throws a structured error:
+When a request is blocked in `cost_protect` mode, Caplyr throws a structured error:
 
 ```typescript
 try {
   const response = await client.messages.create({ ... });
 } catch (err) {
   if (err.caplyr) {
-    // Caplyr enforcement event
     console.log(err.caplyr.code);        // "BUDGET_EXCEEDED" | "KILL_SWITCH_ACTIVE"
     console.log(err.caplyr.retry_after); // ISO timestamp for next reset
     console.log(err.caplyr.budget_used); // Current spend
@@ -96,19 +113,28 @@ try {
 }
 ```
 
+In `alert_only` mode, the request proceeds and the `onEnforcement` callback is fired instead.
+
 ## Shutdown
 
+Caplyr does **not** register SIGINT/SIGTERM handlers — your app owns its process lifecycle. Call `shutdown()` in your own signal handler to flush pending logs before exit:
+
 ```typescript
 import { shutdown } from "caplyr";
 
-// Flush pending logs on app exit
-process.on("SIGTERM", () => shutdown());
+async function gracefulShutdown() {
+  await shutdown();
+  process.exit(0);
+}
+
+process.on("SIGTERM", gracefulShutdown);
+process.on("SIGINT", gracefulShutdown);
 ```
 
 ## Links
 
 - **Dashboard**: [app.caplyr.com](https://app.caplyr.com)
-- **Docs**: [docs.caplyr.com](https://docs.caplyr.com)
+- **Docs**: [caplyr.com/docs](https://caplyr.com/docs)
 - **Website**: [caplyr.com](https://caplyr.com)
 
 ## License

package/dist/index.d.mts

@@ -1,168 +1,53 @@
-/** Protection status of the SDK connection */
-type ProtectionStatus = "ACTIVE" | "DEGRADED" | "OFF";
-/** Supported AI providers */
-type Provider = "anthropic" | "openai";
-/** Operating mode for the SDK */
-type CaplyrMode = "cost_protect" | "alert_only" | "kill_switch";
-/** Configuration for the protect() function */
 interface CaplyrConfig {
-    /** Your Caplyr project API key */
     apiKey: string;
-    /** Caplyr backend URL (defaults to https://api.caplyr.com) */
-    endpoint?: string;
-    /** Operating mode (defaults to "alert_only" for trust-building) */
-    mode?: CaplyrMode;
-    /** Monthly budget cap in dollars */
-    budget?: number;
-    /** Daily budget cap in dollars */
-    dailyBudget?: number;
-    /** Fallback model when budget is approached/exceeded */
-    fallback?: string;
-    /** Budget threshold (0-1) at which auto-downgrade activates (default: 0.8) */
+    mode?: 'alert_only' | 'cost_protect';
+    /** Budget limits. Enforcement is server-side, based on project settings tied to your API key. */
+    budget?: {
+        daily?: number;
+        monthly?: number;
+    };
     downgradeThreshold?: number;
-    /** Custom endpoint tag for attribution */
+    fallback?: string;
+    /** API endpoint for heartbeat and log ingestion (default: https://api.caplyr.com) */
+    endpoint?: string;
+    /** Dashboard URL for error messages (default: https://app.caplyr.com) */
+    dashboardUrl?: string;
     endpoint_tag?: string;
-    /** Batch size before flushing logs (default: 10) */
     batchSize?: number;
-    /** Max interval in ms between log flushes (default: 30000) */
     flushInterval?: number;
-    /** Heartbeat interval in ms (default: 60000) */
     heartbeatInterval?: number;
-    /** Called when protection status changes */
-    onStatusChange?: (status: ProtectionStatus) => void;
-    /** Called when an enforcement event occurs */
-    onEnforcement?: (event: EnforcementEvent) => void;
-    /** Called when an error occurs in the SDK (non-blocking) */
-    onError?: (error: Error) => void;
-}
-/** Metadata captured for every AI API call */
-interface RequestLog {
-    /** Unique request ID */
-    id: string;
-    /** Timestamp of the request */
-    timestamp: number;
-    /** Provider: "anthropic" | "openai" */
-    provider: Provider;
-    /** Model used (e.g., "claude-sonnet-4-20250514") */
-    model: string;
-    /** Input tokens consumed */
-    input_tokens: number;
-    /** Output tokens consumed */
-    output_tokens: number;
-    /** Calculated cost in dollars */
-    cost: number;
-    /** Request latency in milliseconds */
-    latency_ms: number;
-    /** Endpoint tag for attribution */
-    endpoint_tag?: string;
-    /** Whether this request was auto-downgraded */
-    downgraded: boolean;
-    /** Original model if downgraded */
-    original_model?: string;
-    /** Whether this request was blocked */
-    blocked: boolean;
-    /** Reason for block/downgrade if applicable */
-    enforcement_reason?: string;
+    onError?: (err: Error) => void;
+    onEnforcement?: (event: any) => void;
 }
-/** Enforcement event emitted when guardrails activate */
-interface EnforcementEvent {
-    type: "downgrade" | "block" | "kill_switch";
-    timestamp: number;
-    reason: string;
-    original_model?: string;
-    fallback_model?: string;
-    budget_used: number;
-    budget_limit: number;
-    estimated_savings: number;
+interface ResolvedConfig extends CaplyrConfig {
+    mode: 'alert_only' | 'cost_protect';
+    downgradeThreshold: number;
+    dashboardUrl: string;
+    /** @internal Called by interceptors to track request count */
+    _onRequest?: () => void;
 }
-/** Budget status returned from the backend */
-interface BudgetStatus {
-    daily_used: number;
-    daily_limit: number | null;
-    monthly_used: number;
-    monthly_limit: number | null;
-    status: ProtectionStatus;
-    kill_switch_active: boolean;
-}
-/** Structured error returned when a request is blocked */
-interface CaplyrBlockedError {
-    code: "BUDGET_EXCEEDED" | "KILL_SWITCH_ACTIVE" | "RATE_LIMITED";
-    message: string;
-    budget_used: number;
-    budget_limit: number;
-    retry_after?: string;
-    dashboard_url: string;
-}
-/** Internal state of the SDK */
-interface CaplyrState {
-    status: ProtectionStatus;
-    mode: CaplyrMode;
+declare function protect(client: any, config: CaplyrConfig): any;
+declare function getStatus(apiKey: string): string;
+declare function getState(apiKey: string): {
+    status: string;
+    mode: "alert_only" | "cost_protect";
     budget_daily_used: number;
     budget_monthly_used: number;
     kill_switch_active: boolean;
-    last_heartbeat: number;
+    last_heartbeat: number | null;
     request_count: number;
     total_cost: number;
-    total_savings: number;
-}
-
-/**
- * Wrap an AI provider client with Caplyr cost control.
- *
- * Returns a proxy that is type-compatible with the original client.
- * All existing code works unchanged — Caplyr is invisible to callers.
- *
- * @param client - An Anthropic or OpenAI client instance
- * @param config - Caplyr configuration
- * @returns A proxied client with cost control applied
- *
- * @example
- * ```ts
- * import Anthropic from "@anthropic-ai/sdk"
- * import { protect } from "caplyr"
- *
- * const client = protect(new Anthropic(), {
- *   apiKey: "caplyr_...",
- *   budget: 500,
- * })
- * ```
- */
-declare function protect<T>(client: T, config: CaplyrConfig): T;
-/**
- * Get the current protection status for a given API key.
- */
-declare function getStatus(apiKey: string): ProtectionStatus;
-/**
- * Get the full SDK state for a given API key.
- */
-declare function getState(apiKey: string): CaplyrState | null;
-/**
- * Flush all pending logs and stop background tasks.
- * Call this during application shutdown.
- */
+} | null;
 declare function shutdown(apiKey?: string): Promise<void>;
 
+/** Per-million-token pricing: { input, output } */
 interface ModelPricing {
     input: number;
     output: number;
 }
-/**
- * Calculate the cost of a single API request.
- * Returns cost in dollars.
- */
 declare function calculateCost(model: string, inputTokens: number, outputTokens: number): number;
-/**
- * Register a custom model with pricing at runtime.
- * Useful for new models not yet in the built-in table.
- */
 declare function registerModel(model: string, pricing: ModelPricing, fallback?: string): void;
-/**
- * Check if a model is known to the pricing table.
- */
 declare function isKnownModel(model: string): boolean;
-/**
- * Get pricing for a model. Returns null if unknown.
- */
 declare function getModelPricing(model: string): ModelPricing | null;
 
-export { type BudgetStatus, type CaplyrBlockedError, type CaplyrConfig, type CaplyrMode, type CaplyrState, type EnforcementEvent, type ProtectionStatus, type Provider, type RequestLog, calculateCost, getModelPricing, getState, getStatus, isKnownModel, protect, registerModel, shutdown };
+export { type CaplyrConfig, type ResolvedConfig, calculateCost, getModelPricing, getState, getStatus, isKnownModel, protect, registerModel, shutdown };

package/dist/index.d.ts

@@ -1,168 +1,53 @@
-/** Protection status of the SDK connection */
-type ProtectionStatus = "ACTIVE" | "DEGRADED" | "OFF";
-/** Supported AI providers */
-type Provider = "anthropic" | "openai";
-/** Operating mode for the SDK */
-type CaplyrMode = "cost_protect" | "alert_only" | "kill_switch";
-/** Configuration for the protect() function */
 interface CaplyrConfig {
-    /** Your Caplyr project API key */
     apiKey: string;
-    /** Caplyr backend URL (defaults to https://api.caplyr.com) */
-    endpoint?: string;
-    /** Operating mode (defaults to "alert_only" for trust-building) */
-    mode?: CaplyrMode;
-    /** Monthly budget cap in dollars */
-    budget?: number;
-    /** Daily budget cap in dollars */
-    dailyBudget?: number;
-    /** Fallback model when budget is approached/exceeded */
-    fallback?: string;
-    /** Budget threshold (0-1) at which auto-downgrade activates (default: 0.8) */
+    mode?: 'alert_only' | 'cost_protect';
+    /** Budget limits. Enforcement is server-side, based on project settings tied to your API key. */
+    budget?: {
+        daily?: number;
+        monthly?: number;
+    };
     downgradeThreshold?: number;
-    /** Custom endpoint tag for attribution */
+    fallback?: string;
+    /** API endpoint for heartbeat and log ingestion (default: https://api.caplyr.com) */
+    endpoint?: string;
+    /** Dashboard URL for error messages (default: https://app.caplyr.com) */
+    dashboardUrl?: string;
     endpoint_tag?: string;
-    /** Batch size before flushing logs (default: 10) */
     batchSize?: number;
-    /** Max interval in ms between log flushes (default: 30000) */
     flushInterval?: number;
-    /** Heartbeat interval in ms (default: 60000) */
     heartbeatInterval?: number;
-    /** Called when protection status changes */
-    onStatusChange?: (status: ProtectionStatus) => void;
-    /** Called when an enforcement event occurs */
-    onEnforcement?: (event: EnforcementEvent) => void;
-    /** Called when an error occurs in the SDK (non-blocking) */
-    onError?: (error: Error) => void;
-}
-/** Metadata captured for every AI API call */
-interface RequestLog {
-    /** Unique request ID */
-    id: string;
-    /** Timestamp of the request */
-    timestamp: number;
-    /** Provider: "anthropic" | "openai" */
-    provider: Provider;
-    /** Model used (e.g., "claude-sonnet-4-20250514") */
-    model: string;
-    /** Input tokens consumed */
-    input_tokens: number;
-    /** Output tokens consumed */
-    output_tokens: number;
-    /** Calculated cost in dollars */
-    cost: number;
-    /** Request latency in milliseconds */
-    latency_ms: number;
-    /** Endpoint tag for attribution */
-    endpoint_tag?: string;
-    /** Whether this request was auto-downgraded */
-    downgraded: boolean;
-    /** Original model if downgraded */
-    original_model?: string;
-    /** Whether this request was blocked */
-    blocked: boolean;
-    /** Reason for block/downgrade if applicable */
-    enforcement_reason?: string;
+    onError?: (err: Error) => void;
+    onEnforcement?: (event: any) => void;
 }
-/** Enforcement event emitted when guardrails activate */
-interface EnforcementEvent {
-    type: "downgrade" | "block" | "kill_switch";
-    timestamp: number;
-    reason: string;
-    original_model?: string;
-    fallback_model?: string;
-    budget_used: number;
-    budget_limit: number;
-    estimated_savings: number;
+interface ResolvedConfig extends CaplyrConfig {
+    mode: 'alert_only' | 'cost_protect';
+    downgradeThreshold: number;
+    dashboardUrl: string;
+    /** @internal Called by interceptors to track request count */
+    _onRequest?: () => void;
 }
-/** Budget status returned from the backend */
-interface BudgetStatus {
-    daily_used: number;
-    daily_limit: number | null;
-    monthly_used: number;
-    monthly_limit: number | null;
-    status: ProtectionStatus;
-    kill_switch_active: boolean;
-}
-/** Structured error returned when a request is blocked */
-interface CaplyrBlockedError {
-    code: "BUDGET_EXCEEDED" | "KILL_SWITCH_ACTIVE" | "RATE_LIMITED";
-    message: string;
-    budget_used: number;
-    budget_limit: number;
-    retry_after?: string;
-    dashboard_url: string;
-}
-/** Internal state of the SDK */
-interface CaplyrState {
-    status: ProtectionStatus;
-    mode: CaplyrMode;
+declare function protect(client: any, config: CaplyrConfig): any;
+declare function getStatus(apiKey: string): string;
+declare function getState(apiKey: string): {
+    status: string;
+    mode: "alert_only" | "cost_protect";
     budget_daily_used: number;
     budget_monthly_used: number;
     kill_switch_active: boolean;
-    last_heartbeat: number;
+    last_heartbeat: number | null;
     request_count: number;
     total_cost: number;
-    total_savings: number;
-}
-
-/**
- * Wrap an AI provider client with Caplyr cost control.
- *
- * Returns a proxy that is type-compatible with the original client.
- * All existing code works unchanged — Caplyr is invisible to callers.
- *
- * @param client - An Anthropic or OpenAI client instance
- * @param config - Caplyr configuration
- * @returns A proxied client with cost control applied
- *
- * @example
- * ```ts
- * import Anthropic from "@anthropic-ai/sdk"
- * import { protect } from "caplyr"
- *
- * const client = protect(new Anthropic(), {
- *   apiKey: "caplyr_...",
- *   budget: 500,
- * })
- * ```
- */
-declare function protect<T>(client: T, config: CaplyrConfig): T;
-/**
- * Get the current protection status for a given API key.
- */
-declare function getStatus(apiKey: string): ProtectionStatus;
-/**
- * Get the full SDK state for a given API key.
- */
-declare function getState(apiKey: string): CaplyrState | null;
-/**
- * Flush all pending logs and stop background tasks.
- * Call this during application shutdown.
- */
+} | null;
 declare function shutdown(apiKey?: string): Promise<void>;
 
+/** Per-million-token pricing: { input, output } */
 interface ModelPricing {
     input: number;
     output: number;
 }
-/**
- * Calculate the cost of a single API request.
- * Returns cost in dollars.
- */
 declare function calculateCost(model: string, inputTokens: number, outputTokens: number): number;
-/**
- * Register a custom model with pricing at runtime.
- * Useful for new models not yet in the built-in table.
- */
 declare function registerModel(model: string, pricing: ModelPricing, fallback?: string): void;
-/**
- * Check if a model is known to the pricing table.
- */
 declare function isKnownModel(model: string): boolean;
-/**
- * Get pricing for a model. Returns null if unknown.
- */
 declare function getModelPricing(model: string): ModelPricing | null;
 
-export { type BudgetStatus, type CaplyrBlockedError, type CaplyrConfig, type CaplyrMode, type CaplyrState, type EnforcementEvent, type ProtectionStatus, type Provider, type RequestLog, calculateCost, getModelPricing, getState, getStatus, isKnownModel, protect, registerModel, shutdown };
+export { type CaplyrConfig, type ResolvedConfig, calculateCost, getModelPricing, getState, getStatus, isKnownModel, protect, registerModel, shutdown };