caplyr 0.1.0

package/README.md

@@ -0,0 +1,116 @@
+# Caplyr
+
+**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.
+
+## Install
+
+```bash
+npm install caplyr
+```
+
+## Quick Start
+
+```typescript
+import Anthropic from "@anthropic-ai/sdk";
+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
+});
+
+// Use exactly as before — Caplyr is invisible
+const response = await client.messages.create({
+  model: "claude-sonnet-4-20250514",
+  max_tokens: 1024,
+  messages: [{ role: "user", content: "Hello" }],
+});
+```
+
+Works with OpenAI too:
+
+```typescript
+import OpenAI from "openai";
+import { protect } from "caplyr";
+
+const client = protect(new OpenAI(), {
+  apiKey: "caplyr_...",
+  budget: 500,
+  fallback: "gpt-4o-mini",
+});
+
+const response = await client.chat.completions.create({
+  model: "gpt-4o",
+  messages: [{ role: "user", content: "Hello" }],
+});
+```
+
+## What It Does
+
+| Feature | Description |
+|---------|-------------|
+| **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. Halts all AI API calls instantly. |
+
+## Modes
+
+```typescript
+// 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: 500 });
+```
+
+## 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 |
+| `fallback` | `string` | auto | Fallback model for auto-downgrade |
+| `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 |
+
+## Handling Blocked Requests
+
+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
+  }
+}
+```
+
+## Shutdown
+
+```typescript
+import { shutdown } from "caplyr";
+
+// Flush pending logs on app exit
+process.on("SIGTERM", () => shutdown());
+```
+
+## Links
+
+- **Dashboard**: [app.caplyr.com](https://app.caplyr.com)
+- **Docs**: [docs.caplyr.com](https://docs.caplyr.com)
+- **Website**: [caplyr.com](https://caplyr.com)
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +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;
+    /** 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) */
+    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;
+    /** 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;
+}
+/** 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;
+}
+/** 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;
+    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.
+ */
+declare function shutdown(apiKey?: string): Promise<void>;
+
+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 };

package/dist/index.d.ts

@@ -0,0 +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;
+    /** 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) */
+    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;
+    /** 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;
+}
+/** 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;
+}
+/** 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;
+    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.
+ */
+declare function shutdown(apiKey?: string): Promise<void>;
+
+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 };