caplyr 0.1.9 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 **AI Cost Control Plane** — Stop runaway API bills automatically.
 
-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.
+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.
 
 ## Install
 
@@ -18,10 +18,9 @@ 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
-  mode: "cost_protect",                    // Enforce budget limits
-  budget: { monthly: 500, daily: 50 },    // Budget caps in dollars
-  fallback: "claude-haiku-4-5-20251001",   // Auto-downgrade target
+  apiKey: "caplyr_...",       // Get yours at https://app.caplyr.com
+  budget: 500,                // Monthly cap in dollars
+  fallback: "claude-haiku-3-5-20241022",  // Auto-downgrade target
 });
 
 // Use exactly as before — Caplyr is invisible
@@ -40,8 +39,7 @@ import { protect } from "caplyr";
 
 const client = protect(new OpenAI(), {
   apiKey: "caplyr_...",
-  mode: "cost_protect",
-  budget: { monthly: 500 },
+  budget: 500,
   fallback: "gpt-4o-mini",
 });
 
@@ -55,57 +53,42 @@ const response = await client.chat.completions.create({
 
 | Feature | Description |
 |---------|-------------|
-| **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. |
+| **Budget Guardrails** | Daily and monthly caps enforced at the SDK level. Hit the limit → requests are blocked or downgraded. |
 | **Auto Downgrade** | When budget threshold is reached, automatically route to a cheaper model. Your app keeps working. |
-| **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.
+| **Kill Switch** | One-click emergency stop. Halts all AI API calls instantly. |
 
 ## Modes
 
 ```typescript
-// Alert-only (default): observe and log, don't enforce
-protect(client, { apiKey: "..." });
+// Alert-only (default): observe and project, don't enforce
+protect(client, { apiKey: "...", mode: "alert_only" });
 
 // Cost protect: enforce budget caps and auto-downgrade
-protect(client, { apiKey: "...", mode: "cost_protect", budget: { monthly: 500 } });
+protect(client, { apiKey: "...", mode: "cost_protect", budget: 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` | `{ monthly?: number, daily?: number }` | — | Budget caps in dollars |
+| `budget` | `number` | — | Monthly budget cap in dollars |
+| `dailyBudget` | `number` | — | Daily budget cap in dollars |
 | `fallback` | `string` | auto | Fallback model for auto-downgrade |
-| `mode` | `"alert_only" \| "cost_protect"` | `"alert_only"` | Enforcement mode |
+| `mode` | `string` | `"alert_only"` | `"alert_only"` \| `"cost_protect"` \| `"kill_switch"` |
 | `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 in `cost_protect` mode, Caplyr throws a structured error:
+When a request is blocked, 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
@@ -113,28 +96,19 @@ 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";
 
-async function gracefulShutdown() {
-  await shutdown();
-  process.exit(0);
-}
-
-process.on("SIGTERM", gracefulShutdown);
-process.on("SIGINT", gracefulShutdown);
+// Flush pending logs on app exit
+process.on("SIGTERM", () => shutdown());
 ```
 
 ## Links
 
 - **Dashboard**: [app.caplyr.com](https://app.caplyr.com)
-- **Docs**: [caplyr.com/docs](https://caplyr.com/docs)
+- **Docs**: [docs.caplyr.com](https://docs.caplyr.com)
 - **Website**: [caplyr.com](https://caplyr.com)
 
 ## License

package/dist/index.d.mts

@@ -1,53 +1,168 @@
+/** 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;
-    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;
-    fallback?: string;
-    /** API endpoint for heartbeat and log ingestion (default: https://caplyr.com) */
+    /** Caplyr backend URL (defaults to https://api.caplyr.com) */
     endpoint?: string;
-    /** Dashboard URL for error messages (default: https://app.caplyr.com) */
-    dashboardUrl?: 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) */
+    downgradeThreshold?: number;
+    /** Custom endpoint tag for attribution */
     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;
-    onError?: (err: Error) => void;
-    onEnforcement?: (event: any) => void;
+    /** 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;
 }
-interface ResolvedConfig extends CaplyrConfig {
-    mode: 'alert_only' | 'cost_protect';
-    downgradeThreshold: number;
-    dashboardUrl: string;
-    /** @internal Called by interceptors to track request count */
-    _onRequest?: () => 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;
 }
-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 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;
     budget_daily_used: number;
     budget_monthly_used: number;
     kill_switch_active: boolean;
-    last_heartbeat: number | null;
+    last_heartbeat: number;
     request_count: number;
     total_cost: number;
-} | null;
+    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.
+ */
 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 CaplyrConfig, type ResolvedConfig, calculateCost, getModelPricing, getState, getStatus, isKnownModel, protect, registerModel, shutdown };
+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 };

package/dist/index.d.ts

@@ -1,53 +1,168 @@
+/** 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;
-    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;
-    fallback?: string;
-    /** API endpoint for heartbeat and log ingestion (default: https://caplyr.com) */
+    /** Caplyr backend URL (defaults to https://api.caplyr.com) */
     endpoint?: string;
-    /** Dashboard URL for error messages (default: https://app.caplyr.com) */
-    dashboardUrl?: 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) */
+    downgradeThreshold?: number;
+    /** Custom endpoint tag for attribution */
     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;
-    onError?: (err: Error) => void;
-    onEnforcement?: (event: any) => void;
+    /** 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;
 }
-interface ResolvedConfig extends CaplyrConfig {
-    mode: 'alert_only' | 'cost_protect';
-    downgradeThreshold: number;
-    dashboardUrl: string;
-    /** @internal Called by interceptors to track request count */
-    _onRequest?: () => 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;
 }
-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 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;
     budget_daily_used: number;
     budget_monthly_used: number;
     kill_switch_active: boolean;
-    last_heartbeat: number | null;
+    last_heartbeat: number;
     request_count: number;
     total_cost: number;
-} | null;
+    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.
+ */
 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 CaplyrConfig, type ResolvedConfig, calculateCost, getModelPricing, getState, getStatus, isKnownModel, protect, registerModel, shutdown };
+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 };