caplyr 0.1.0

package/dist/index.mjs

@@ -0,0 +1,701 @@
+// src/logger.ts
+var LogShipper = class {
+  constructor(config) {
+    this.buffer = [];
+    this.timer = null;
+    this.endpoint = config.endpoint ?? "https://api.caplyr.com";
+    this.apiKey = config.apiKey;
+    this.batchSize = config.batchSize ?? 10;
+    this.flushInterval = config.flushInterval ?? 3e4;
+    this.onError = config.onError;
+    this.timer = setInterval(() => this.flush(), this.flushInterval);
+    if (typeof process !== "undefined" && process.on) {
+      process.on("beforeExit", () => this.flush());
+    }
+  }
+  /**
+   * Add a log entry to the buffer.
+   * Auto-flushes when batch size is reached.
+   */
+  push(log) {
+    this.buffer.push(log);
+    if (this.buffer.length >= this.batchSize) {
+      this.flush();
+    }
+  }
+  /**
+   * Flush all buffered logs to the backend.
+   * Non-blocking — errors are swallowed and reported via onError.
+   */
+  async flush() {
+    if (this.buffer.length === 0) return;
+    const batch = this.buffer.splice(0);
+    try {
+      const res = await fetch(`${this.endpoint}/api/ingest`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.apiKey}`
+        },
+        body: JSON.stringify({ logs: batch }),
+        signal: AbortSignal.timeout(1e4)
+      });
+      if (!res.ok) {
+        this.buffer.unshift(...batch);
+        throw new Error(`Ingest failed: ${res.status} ${res.statusText}`);
+      }
+    } catch (err) {
+      this.onError?.(err instanceof Error ? err : new Error(String(err)));
+    }
+  }
+  /**
+   * Stop the periodic flush timer.
+   * Call this when tearing down the SDK.
+   */
+  destroy() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    this.flush();
+  }
+};
+
+// src/heartbeat.ts
+var Heartbeat = class {
+  constructor(config) {
+    this.timer = null;
+    this.consecutiveFailures = 0;
+    this.maxFailuresBeforeDegraded = 3;
+    /** Current budget status from the backend */
+    this.budgetStatus = {
+      daily_used: 0,
+      daily_limit: null,
+      monthly_used: 0,
+      monthly_limit: null,
+      status: "ACTIVE",
+      kill_switch_active: false
+    };
+    /** Current protection status */
+    this.status = "ACTIVE";
+    this.endpoint = config.endpoint ?? "https://api.caplyr.com";
+    this.apiKey = config.apiKey;
+    this.interval = config.heartbeatInterval ?? 6e4;
+    this.onStatusChange = config.onStatusChange;
+    this.onError = config.onError;
+  }
+  /**
+   * Start the heartbeat loop.
+   * Immediately sends first heartbeat, then repeats on interval.
+   */
+  start() {
+    this.beat();
+    this.timer = setInterval(() => this.beat(), this.interval);
+  }
+  /**
+   * Send a single heartbeat and update local state.
+   */
+  async beat() {
+    try {
+      const res = await fetch(`${this.endpoint}/api/heartbeat`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.apiKey}`
+        },
+        body: JSON.stringify({ timestamp: Date.now() }),
+        signal: AbortSignal.timeout(5e3)
+      });
+      if (!res.ok) {
+        throw new Error(`Heartbeat failed: ${res.status}`);
+      }
+      const data = await res.json();
+      this.budgetStatus = data;
+      this.consecutiveFailures = 0;
+      const newStatus = data.kill_switch_active ? "OFF" : data.status;
+      if (newStatus !== this.status) {
+        this.status = newStatus;
+        this.onStatusChange?.(newStatus);
+      }
+    } catch (err) {
+      this.consecutiveFailures++;
+      this.onError?.(err instanceof Error ? err : new Error(String(err)));
+      if (this.consecutiveFailures >= this.maxFailuresBeforeDegraded && this.status === "ACTIVE") {
+        this.status = "DEGRADED";
+        this.onStatusChange?.("DEGRADED");
+      }
+    }
+  }
+  /**
+   * Update local budget tracking (called after each request).
+   * This provides real-time budget awareness between heartbeats.
+   */
+  trackSpend(cost) {
+    this.budgetStatus.daily_used += cost;
+    this.budgetStatus.monthly_used += cost;
+  }
+  /**
+   * Check if the monthly budget is exceeded.
+   */
+  isMonthlyBudgetExceeded() {
+    if (this.budgetStatus.monthly_limit === null) return false;
+    return this.budgetStatus.monthly_used >= this.budgetStatus.monthly_limit;
+  }
+  /**
+   * Check if the daily budget is exceeded.
+   */
+  isDailyBudgetExceeded() {
+    if (this.budgetStatus.daily_limit === null) return false;
+    return this.budgetStatus.daily_used >= this.budgetStatus.daily_limit;
+  }
+  /**
+   * Check if the downgrade threshold is reached.
+   * Returns true if usage exceeds the given threshold (0-1) of any budget.
+   */
+  isDowngradeThresholdReached(threshold) {
+    if (this.budgetStatus.monthly_limit !== null && this.budgetStatus.monthly_used >= this.budgetStatus.monthly_limit * threshold) {
+      return true;
+    }
+    if (this.budgetStatus.daily_limit !== null && this.budgetStatus.daily_used >= this.budgetStatus.daily_limit * threshold) {
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Check if the kill switch is active.
+   */
+  isKillSwitchActive() {
+    return this.budgetStatus.kill_switch_active;
+  }
+  /**
+   * Stop the heartbeat loop.
+   */
+  destroy() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+};
+
+// src/pricing.ts
+var MODEL_PRICING = {
+  // ---- Anthropic ----
+  "claude-opus-4-20250514": { input: 15, output: 75 },
+  "claude-sonnet-4-20250514": { input: 3, output: 15 },
+  "claude-haiku-4-5-20251001": { input: 0.8, output: 4 },
+  // Aliases
+  "claude-opus-4": { input: 15, output: 75 },
+  "claude-sonnet-4": { input: 3, output: 15 },
+  "claude-3-5-sonnet-20241022": { input: 3, output: 15 },
+  // ---- OpenAI ----
+  "gpt-4o": { input: 2.5, output: 10 },
+  "gpt-4o-2024-11-20": { input: 2.5, output: 10 },
+  "gpt-4o-mini": { input: 0.15, output: 0.6 },
+  "gpt-4o-mini-2024-07-18": { input: 0.15, output: 0.6 },
+  "gpt-4-turbo": { input: 10, output: 30 },
+  "gpt-4-turbo-2024-04-09": { input: 10, output: 30 },
+  "gpt-4": { input: 30, output: 60 },
+  "gpt-3.5-turbo": { input: 0.5, output: 1.5 },
+  "o1": { input: 15, output: 60 },
+  "o1-mini": { input: 3, output: 12 },
+  "o3-mini": { input: 1.1, output: 4.4 }
+};
+var DEFAULT_FALLBACKS = {
+  // Anthropic downgrades
+  "claude-opus-4-20250514": "claude-sonnet-4-20250514",
+  "claude-opus-4": "claude-sonnet-4",
+  "claude-sonnet-4-20250514": "claude-haiku-4-5-20251001",
+  "claude-sonnet-4": "claude-haiku-4-5-20251001",
+  "claude-3-5-sonnet-20241022": "claude-haiku-4-5-20251001",
+  // OpenAI downgrades
+  "gpt-4o": "gpt-4o-mini",
+  "gpt-4o-2024-11-20": "gpt-4o-mini",
+  "gpt-4-turbo": "gpt-4o-mini",
+  "gpt-4": "gpt-3.5-turbo",
+  "o1": "o1-mini",
+  "o1-mini": "o3-mini"
+};
+function calculateCost(model, inputTokens, outputTokens) {
+  const pricing = MODEL_PRICING[model];
+  if (!pricing) {
+    return (inputTokens * 3 + outputTokens * 15) / 1e6;
+  }
+  return (inputTokens * pricing.input + outputTokens * pricing.output) / 1e6;
+}
+function getDefaultFallback(model) {
+  return DEFAULT_FALLBACKS[model];
+}
+function registerModel(model, pricing, fallback) {
+  MODEL_PRICING[model] = pricing;
+  if (fallback) {
+    DEFAULT_FALLBACKS[model] = fallback;
+  }
+}
+function isKnownModel(model) {
+  return model in MODEL_PRICING;
+}
+function getModelPricing(model) {
+  return MODEL_PRICING[model] ?? null;
+}
+
+// src/interceptors/anthropic.ts
+var idCounter = 0;
+function generateId() {
+  return `caplyr_${Date.now()}_${++idCounter}`;
+}
+function wrapAnthropic(client, config, shipper, heartbeat) {
+  const downgradeThreshold = config.downgradeThreshold ?? 0.8;
+  const dashboardUrl = `${config.endpoint ?? "https://app.caplyr.com"}/dashboard`;
+  const messagesProxy = new Proxy(client.messages, {
+    get(target, prop, receiver) {
+      if (prop === "create") {
+        return async function caplyrInterceptedCreate(params, options) {
+          const startTime = Date.now();
+          let model = params.model;
+          let downgraded = false;
+          let originalModel;
+          let blocked = false;
+          let enforcementReason;
+          if (heartbeat.isKillSwitchActive()) {
+            blocked = true;
+            enforcementReason = "kill_switch_active";
+            const blockError = {
+              code: "KILL_SWITCH_ACTIVE",
+              message: "Caplyr kill switch is active. All AI API calls are halted.",
+              budget_used: heartbeat.budgetStatus.monthly_used,
+              budget_limit: heartbeat.budgetStatus.monthly_limit ?? 0,
+              dashboard_url: dashboardUrl
+            };
+            shipper.push({
+              id: generateId(),
+              timestamp: startTime,
+              provider: "anthropic",
+              model,
+              input_tokens: 0,
+              output_tokens: 0,
+              cost: 0,
+              latency_ms: Date.now() - startTime,
+              endpoint_tag: config.endpoint_tag,
+              downgraded: false,
+              blocked: true,
+              enforcement_reason: enforcementReason
+            });
+            if (config.mode === "alert_only") {
+            } else {
+              throw Object.assign(new Error(blockError.message), {
+                caplyr: blockError
+              });
+            }
+          }
+          if (config.mode === "cost_protect") {
+            if (heartbeat.isMonthlyBudgetExceeded() || heartbeat.isDailyBudgetExceeded()) {
+              blocked = true;
+              enforcementReason = heartbeat.isDailyBudgetExceeded() ? "daily_budget_exceeded" : "monthly_budget_exceeded";
+              const blockError = {
+                code: "BUDGET_EXCEEDED",
+                message: `AI budget exceeded. ${enforcementReason.replace(/_/g, " ")}.`,
+                budget_used: heartbeat.budgetStatus.monthly_used,
+                budget_limit: heartbeat.budgetStatus.monthly_limit ?? 0,
+                retry_after: getNextResetTime(enforcementReason),
+                dashboard_url: dashboardUrl
+              };
+              shipper.push({
+                id: generateId(),
+                timestamp: startTime,
+                provider: "anthropic",
+                model,
+                input_tokens: 0,
+                output_tokens: 0,
+                cost: 0,
+                latency_ms: Date.now() - startTime,
+                endpoint_tag: config.endpoint_tag,
+                downgraded: false,
+                blocked: true,
+                enforcement_reason: enforcementReason
+              });
+              throw Object.assign(new Error(blockError.message), {
+                caplyr: blockError
+              });
+            }
+            if (heartbeat.isDowngradeThresholdReached(downgradeThreshold)) {
+              const fallback = config.fallback ?? getDefaultFallback(model);
+              if (fallback && fallback !== model) {
+                originalModel = model;
+                model = fallback;
+                downgraded = true;
+                enforcementReason = "auto_downgrade_threshold";
+                config.onEnforcement?.({
+                  type: "downgrade",
+                  timestamp: Date.now(),
+                  reason: `Budget at ${Math.round(downgradeThreshold * 100)}% \u2014 downgraded ${originalModel} \u2192 ${model}`,
+                  original_model: originalModel,
+                  fallback_model: model,
+                  budget_used: heartbeat.budgetStatus.monthly_used,
+                  budget_limit: heartbeat.budgetStatus.monthly_limit ?? 0,
+                  estimated_savings: 0
+                  // Calculated after response
+                });
+              }
+            }
+          }
+          const requestParams = downgraded ? { ...params, model } : params;
+          try {
+            const response = await target.create.call(
+              target,
+              requestParams,
+              options
+            );
+            const latency = Date.now() - startTime;
+            const inputTokens = response?.usage?.input_tokens ?? 0;
+            const outputTokens = response?.usage?.output_tokens ?? 0;
+            const cost = calculateCost(model, inputTokens, outputTokens);
+            heartbeat.trackSpend(cost);
+            let estimatedSavings = 0;
+            if (downgraded && originalModel) {
+              const originalCost = calculateCost(
+                originalModel,
+                inputTokens,
+                outputTokens
+              );
+              estimatedSavings = originalCost - cost;
+            }
+            shipper.push({
+              id: generateId(),
+              timestamp: startTime,
+              provider: "anthropic",
+              model,
+              input_tokens: inputTokens,
+              output_tokens: outputTokens,
+              cost,
+              latency_ms: latency,
+              endpoint_tag: config.endpoint_tag,
+              downgraded,
+              original_model: originalModel,
+              blocked: false,
+              enforcement_reason: enforcementReason
+            });
+            return response;
+          } catch (err) {
+            if (err?.caplyr) throw err;
+            shipper.push({
+              id: generateId(),
+              timestamp: startTime,
+              provider: "anthropic",
+              model,
+              input_tokens: 0,
+              output_tokens: 0,
+              cost: 0,
+              latency_ms: Date.now() - startTime,
+              endpoint_tag: config.endpoint_tag,
+              downgraded,
+              original_model: originalModel,
+              blocked: false,
+              enforcement_reason: "provider_error"
+            });
+            throw err;
+          }
+        };
+      }
+      return Reflect.get(target, prop, receiver);
+    }
+  });
+  return new Proxy(client, {
+    get(target, prop, receiver) {
+      if (prop === "messages") {
+        return messagesProxy;
+      }
+      return Reflect.get(target, prop, receiver);
+    }
+  });
+}
+function getNextResetTime(reason) {
+  const now = /* @__PURE__ */ new Date();
+  if (reason.includes("daily")) {
+    const tomorrow = new Date(now);
+    tomorrow.setDate(tomorrow.getDate() + 1);
+    tomorrow.setHours(0, 0, 0, 0);
+    return tomorrow.toISOString();
+  }
+  const nextMonth = new Date(now.getFullYear(), now.getMonth() + 1, 1);
+  return nextMonth.toISOString();
+}
+
+// src/interceptors/openai.ts
+var idCounter2 = 0;
+function generateId2() {
+  return `caplyr_${Date.now()}_${++idCounter2}`;
+}
+function wrapOpenAI(client, config, shipper, heartbeat) {
+  const downgradeThreshold = config.downgradeThreshold ?? 0.8;
+  const dashboardUrl = `${config.endpoint ?? "https://app.caplyr.com"}/dashboard`;
+  const completionsProxy = new Proxy(client.chat.completions, {
+    get(target, prop, receiver) {
+      if (prop === "create") {
+        return async function caplyrInterceptedCreate(params, options) {
+          const startTime = Date.now();
+          let model = params.model;
+          let downgraded = false;
+          let originalModel;
+          let blocked = false;
+          let enforcementReason;
+          if (heartbeat.isKillSwitchActive()) {
+            blocked = true;
+            enforcementReason = "kill_switch_active";
+            const blockError = {
+              code: "KILL_SWITCH_ACTIVE",
+              message: "Caplyr kill switch is active. All AI API calls are halted.",
+              budget_used: heartbeat.budgetStatus.monthly_used,
+              budget_limit: heartbeat.budgetStatus.monthly_limit ?? 0,
+              dashboard_url: dashboardUrl
+            };
+            shipper.push({
+              id: generateId2(),
+              timestamp: startTime,
+              provider: "openai",
+              model,
+              input_tokens: 0,
+              output_tokens: 0,
+              cost: 0,
+              latency_ms: Date.now() - startTime,
+              endpoint_tag: config.endpoint_tag,
+              downgraded: false,
+              blocked: true,
+              enforcement_reason: enforcementReason
+            });
+            if (config.mode === "alert_only") {
+            } else {
+              throw Object.assign(new Error(blockError.message), {
+                caplyr: blockError
+              });
+            }
+          }
+          if (config.mode === "cost_protect") {
+            if (heartbeat.isMonthlyBudgetExceeded() || heartbeat.isDailyBudgetExceeded()) {
+              blocked = true;
+              enforcementReason = heartbeat.isDailyBudgetExceeded() ? "daily_budget_exceeded" : "monthly_budget_exceeded";
+              const blockError = {
+                code: "BUDGET_EXCEEDED",
+                message: `AI budget exceeded. ${enforcementReason.replace(/_/g, " ")}.`,
+                budget_used: heartbeat.budgetStatus.monthly_used,
+                budget_limit: heartbeat.budgetStatus.monthly_limit ?? 0,
+                retry_after: getNextResetTime2(enforcementReason),
+                dashboard_url: dashboardUrl
+              };
+              shipper.push({
+                id: generateId2(),
+                timestamp: startTime,
+                provider: "openai",
+                model,
+                input_tokens: 0,
+                output_tokens: 0,
+                cost: 0,
+                latency_ms: Date.now() - startTime,
+                endpoint_tag: config.endpoint_tag,
+                downgraded: false,
+                blocked: true,
+                enforcement_reason: enforcementReason
+              });
+              throw Object.assign(new Error(blockError.message), {
+                caplyr: blockError
+              });
+            }
+            if (heartbeat.isDowngradeThresholdReached(downgradeThreshold)) {
+              const fallback = config.fallback ?? getDefaultFallback(model);
+              if (fallback && fallback !== model) {
+                originalModel = model;
+                model = fallback;
+                downgraded = true;
+                enforcementReason = "auto_downgrade_threshold";
+                config.onEnforcement?.({
+                  type: "downgrade",
+                  timestamp: Date.now(),
+                  reason: `Budget at ${Math.round(downgradeThreshold * 100)}% \u2014 downgraded ${originalModel} \u2192 ${model}`,
+                  original_model: originalModel,
+                  fallback_model: model,
+                  budget_used: heartbeat.budgetStatus.monthly_used,
+                  budget_limit: heartbeat.budgetStatus.monthly_limit ?? 0,
+                  estimated_savings: 0
+                });
+              }
+            }
+          }
+          const requestParams = downgraded ? { ...params, model } : params;
+          try {
+            const response = await target.create.call(
+              target,
+              requestParams,
+              options
+            );
+            const latency = Date.now() - startTime;
+            const usage = response?.usage;
+            const inputTokens = usage?.prompt_tokens ?? 0;
+            const outputTokens = usage?.completion_tokens ?? 0;
+            const cost = calculateCost(model, inputTokens, outputTokens);
+            heartbeat.trackSpend(cost);
+            shipper.push({
+              id: generateId2(),
+              timestamp: startTime,
+              provider: "openai",
+              model,
+              input_tokens: inputTokens,
+              output_tokens: outputTokens,
+              cost,
+              latency_ms: latency,
+              endpoint_tag: config.endpoint_tag,
+              downgraded,
+              original_model: originalModel,
+              blocked: false,
+              enforcement_reason: enforcementReason
+            });
+            return response;
+          } catch (err) {
+            if (err?.caplyr) throw err;
+            shipper.push({
+              id: generateId2(),
+              timestamp: startTime,
+              provider: "openai",
+              model,
+              input_tokens: 0,
+              output_tokens: 0,
+              cost: 0,
+              latency_ms: Date.now() - startTime,
+              endpoint_tag: config.endpoint_tag,
+              downgraded,
+              original_model: originalModel,
+              blocked: false,
+              enforcement_reason: "provider_error"
+            });
+            throw err;
+          }
+        };
+      }
+      return Reflect.get(target, prop, receiver);
+    }
+  });
+  const chatProxy = new Proxy(client.chat, {
+    get(target, prop, receiver) {
+      if (prop === "completions") {
+        return completionsProxy;
+      }
+      return Reflect.get(target, prop, receiver);
+    }
+  });
+  return new Proxy(client, {
+    get(target, prop, receiver) {
+      if (prop === "chat") {
+        return chatProxy;
+      }
+      return Reflect.get(target, prop, receiver);
+    }
+  });
+}
+function getNextResetTime2(reason) {
+  const now = /* @__PURE__ */ new Date();
+  if (reason.includes("daily")) {
+    const tomorrow = new Date(now);
+    tomorrow.setDate(tomorrow.getDate() + 1);
+    tomorrow.setHours(0, 0, 0, 0);
+    return tomorrow.toISOString();
+  }
+  const nextMonth = new Date(now.getFullYear(), now.getMonth() + 1, 1);
+  return nextMonth.toISOString();
+}
+
+// src/protect.ts
+function detectProvider(client) {
+  if (client?.messages?.create && typeof client.messages.create === "function") {
+    return "anthropic";
+  }
+  if (client?.chat?.completions?.create && typeof client.chat.completions.create === "function") {
+    return "openai";
+  }
+  return "unknown";
+}
+var instances = /* @__PURE__ */ new Map();
+function protect(client, config) {
+  if (!config.apiKey) {
+    throw new Error(
+      "Caplyr: apiKey is required. Get yours at https://app.caplyr.com"
+    );
+  }
+  const resolvedConfig = {
+    mode: "alert_only",
+    downgradeThreshold: 0.8,
+    batchSize: 10,
+    flushInterval: 3e4,
+    heartbeatInterval: 6e4,
+    ...config
+  };
+  if (resolvedConfig.budget && !resolvedConfig.mode) {
+    resolvedConfig.mode = "cost_protect";
+  }
+  let shared = instances.get(resolvedConfig.apiKey);
+  if (!shared) {
+    const shipper2 = new LogShipper(resolvedConfig);
+    const heartbeat2 = new Heartbeat(resolvedConfig);
+    heartbeat2.start();
+    shared = { shipper: shipper2, heartbeat: heartbeat2 };
+    instances.set(resolvedConfig.apiKey, shared);
+  }
+  const { shipper, heartbeat } = shared;
+  const provider = detectProvider(client);
+  switch (provider) {
+    case "anthropic":
+      return wrapAnthropic(client, resolvedConfig, shipper, heartbeat);
+    case "openai":
+      return wrapOpenAI(client, resolvedConfig, shipper, heartbeat);
+    default:
+      throw new Error(
+        `Caplyr: Unrecognized AI client. Supported providers: Anthropic, OpenAI. Make sure you're passing a client instance (e.g., new Anthropic() or new OpenAI()).`
+      );
+  }
+}
+function getStatus(apiKey) {
+  const shared = instances.get(apiKey);
+  return shared?.heartbeat.status ?? "OFF";
+}
+function getState(apiKey) {
+  const shared = instances.get(apiKey);
+  if (!shared) return null;
+  const { heartbeat } = shared;
+  return {
+    status: heartbeat.status,
+    mode: "alert_only",
+    // Will be stored properly in next iteration
+    budget_daily_used: heartbeat.budgetStatus.daily_used,
+    budget_monthly_used: heartbeat.budgetStatus.monthly_used,
+    kill_switch_active: heartbeat.budgetStatus.kill_switch_active,
+    last_heartbeat: Date.now(),
+    request_count: 0,
+    // Will be tracked in next iteration
+    total_cost: heartbeat.budgetStatus.monthly_used,
+    total_savings: 0
+  };
+}
+async function shutdown(apiKey) {
+  if (apiKey) {
+    const shared = instances.get(apiKey);
+    if (shared) {
+      shared.heartbeat.destroy();
+      shared.shipper.destroy();
+      instances.delete(apiKey);
+    }
+  } else {
+    for (const [key, shared] of instances) {
+      shared.heartbeat.destroy();
+      shared.shipper.destroy();
+    }
+    instances.clear();
+  }
+}
+export {
+  calculateCost,
+  getModelPricing,
+  getState,
+  getStatus,
+  isKnownModel,
+  protect,
+  registerModel,
+  shutdown
+};