@weckr/sdk 0.1.0 → 0.1.1

package/dist/index.d.mts

@@ -3,6 +3,13 @@ interface WeckrConfig {
     apiKey: string;
     plans?: Record<string, number>;
     endpoint?: string;
+    /** Optional override for the cap-check endpoint. Derived from `endpoint` by default. */
+    checkEndpoint?: string;
+    /**
+     * Disable cap checking entirely. Off by default — the SDK will hit /api/v1/check
+     * before each LLM call (with a 60s per-user/plan cache).
+     */
+    disableCapCheck?: boolean;
     fetch?: typeof fetch;
     onError?: (err: unknown) => void;
 }
@@ -41,11 +48,21 @@ interface ProviderAdapter<TClient = unknown, TResult = unknown> {
     call(client: TClient, options: ChatOptions): Promise<TResult>;
     extractUsage(result: TResult): NormalizedUsage;
 }
+interface CapCheckResult {
+    allowed: boolean;
+    action?: 'block' | 'downgrade';
+    alternativeModel?: string;
+    remainingBudget?: number;
+    currentSpend?: number;
+    cap?: number;
+}
 
 declare class Weckr {
     private readonly apiKey;
     private readonly plans;
     private readonly log;
+    private readonly checkCap;
+    private readonly onError?;
     constructor(config: WeckrConfig);
     chat<TClient, TResult = unknown>(client: TClient, options: ChatOptions): Promise<TResult>;
 }
@@ -62,4 +79,34 @@ declare function calculateCost(model: string, inputTokens: number, outputTokens:
     provider: Provider | null;
 };
 
-export { type ChatOptions, type LogPayload, type NormalizedUsage, PRICING, type Provider, type ProviderAdapter, Weckr, type WeckrConfig, calculateCost, resolvePricing };
+/**
+ * Thrown by `wk.chat(...)` when the configured spending cap has been hit and
+ * the cap's action is `"block"`. The LLM call is never made.
+ *
+ * ```ts
+ * try {
+ *   await wk.chat(openai, opts);
+ * } catch (err) {
+ *   if (err instanceof WeckrCapError) {
+ *     // show the user a friendly upgrade prompt
+ *   }
+ * }
+ * ```
+ */
+declare class WeckrCapError extends Error {
+    readonly name: "WeckrCapError";
+    readonly userId: string;
+    readonly planName: string;
+    readonly currentSpend?: number;
+    readonly cap?: number;
+    constructor(opts: {
+        userId: string;
+        planName: string;
+        currentSpend?: number;
+        cap?: number;
+        message?: string;
+    });
+}
+declare function isWeckrCapError(e: unknown): e is WeckrCapError;
+
+export { type CapCheckResult, type ChatOptions, type LogPayload, type NormalizedUsage, PRICING, type Provider, type ProviderAdapter, Weckr, WeckrCapError, type WeckrConfig, calculateCost, isWeckrCapError, resolvePricing };

package/dist/index.d.ts

@@ -3,6 +3,13 @@ interface WeckrConfig {
     apiKey: string;
     plans?: Record<string, number>;
     endpoint?: string;
+    /** Optional override for the cap-check endpoint. Derived from `endpoint` by default. */
+    checkEndpoint?: string;
+    /**
+     * Disable cap checking entirely. Off by default — the SDK will hit /api/v1/check
+     * before each LLM call (with a 60s per-user/plan cache).
+     */
+    disableCapCheck?: boolean;
     fetch?: typeof fetch;
     onError?: (err: unknown) => void;
 }
@@ -41,11 +48,21 @@ interface ProviderAdapter<TClient = unknown, TResult = unknown> {
     call(client: TClient, options: ChatOptions): Promise<TResult>;
     extractUsage(result: TResult): NormalizedUsage;
 }
+interface CapCheckResult {
+    allowed: boolean;
+    action?: 'block' | 'downgrade';
+    alternativeModel?: string;
+    remainingBudget?: number;
+    currentSpend?: number;
+    cap?: number;
+}
 
 declare class Weckr {
     private readonly apiKey;
     private readonly plans;
     private readonly log;
+    private readonly checkCap;
+    private readonly onError?;
     constructor(config: WeckrConfig);
     chat<TClient, TResult = unknown>(client: TClient, options: ChatOptions): Promise<TResult>;
 }
@@ -62,4 +79,34 @@ declare function calculateCost(model: string, inputTokens: number, outputTokens:
     provider: Provider | null;
 };
 
-export { type ChatOptions, type LogPayload, type NormalizedUsage, PRICING, type Provider, type ProviderAdapter, Weckr, type WeckrConfig, calculateCost, resolvePricing };
+/**
+ * Thrown by `wk.chat(...)` when the configured spending cap has been hit and
+ * the cap's action is `"block"`. The LLM call is never made.
+ *
+ * ```ts
+ * try {
+ *   await wk.chat(openai, opts);
+ * } catch (err) {
+ *   if (err instanceof WeckrCapError) {
+ *     // show the user a friendly upgrade prompt
+ *   }
+ * }
+ * ```
+ */
+declare class WeckrCapError extends Error {
+    readonly name: "WeckrCapError";
+    readonly userId: string;
+    readonly planName: string;
+    readonly currentSpend?: number;
+    readonly cap?: number;
+    constructor(opts: {
+        userId: string;
+        planName: string;
+        currentSpend?: number;
+        cap?: number;
+        message?: string;
+    });
+}
+declare function isWeckrCapError(e: unknown): e is WeckrCapError;
+
+export { type CapCheckResult, type ChatOptions, type LogPayload, type NormalizedUsage, PRICING, type Provider, type ProviderAdapter, Weckr, WeckrCapError, type WeckrConfig, calculateCost, isWeckrCapError, resolvePricing };

package/dist/index.js

@@ -22,7 +22,9 @@ var index_exports = {};
 __export(index_exports, {
   PRICING: () => PRICING,
   Weckr: () => Weckr,
+  WeckrCapError: () => WeckrCapError,
   calculateCost: () => calculateCost,
+  isWeckrCapError: () => isWeckrCapError,
   resolvePricing: () => resolvePricing
 });
 module.exports = __toCommonJS(index_exports);
@@ -164,24 +166,112 @@ function createLogger(opts) {
   };
 }
 
+// src/cap-cache.ts
+var TTL_MS = 6e4;
+function createCapChecker(opts) {
+  const f = opts.fetch ?? globalThis.fetch;
+  const cache = /* @__PURE__ */ new Map();
+  function key(userId, planName) {
+    return `${userId}\0${planName}`;
+  }
+  return async function checkCap(userId, planName, model) {
+    const k = key(userId, planName);
+    const now = Date.now();
+    const hit = cache.get(k);
+    if (hit && hit.expiresAt > now) return hit.result;
+    if (typeof f !== "function") {
+      return { allowed: true };
+    }
+    try {
+      const url = new URL(opts.endpoint);
+      url.searchParams.set("userId", userId);
+      url.searchParams.set("planName", planName);
+      if (model) url.searchParams.set("model", model);
+      const res = await f(url.toString(), {
+        method: "GET",
+        headers: { "x-api-key": opts.apiKey }
+      });
+      if (!res.ok) {
+        opts.onError?.(
+          new Error(`Weckr cap check failed: ${res.status} ${res.statusText}`)
+        );
+        return { allowed: true };
+      }
+      const json = await res.json();
+      cache.set(k, { result: json, expiresAt: now + TTL_MS });
+      return json;
+    } catch (err) {
+      opts.onError?.(err);
+      return { allowed: true };
+    }
+  };
+}
+function deriveCheckEndpoint(logEndpoint) {
+  if (logEndpoint.endsWith("/log")) return logEndpoint.slice(0, -"/log".length) + "/check";
+  return logEndpoint.replace(/\/$/, "") + "/../check";
+}
+
+// src/errors.ts
+var WeckrCapError = class extends Error {
+  name = "WeckrCapError";
+  userId;
+  planName;
+  currentSpend;
+  cap;
+  constructor(opts) {
+    super(
+      opts.message ?? `Weckr: spending cap reached for user ${opts.userId} on plan ${opts.planName}`
+    );
+    this.userId = opts.userId;
+    this.planName = opts.planName;
+    this.currentSpend = opts.currentSpend;
+    this.cap = opts.cap;
+  }
+};
+function isWeckrCapError(e) {
+  return e instanceof Error && e.name === "WeckrCapError";
+}
+function capCheckToError(opts) {
+  return new WeckrCapError({
+    userId: opts.userId,
+    planName: opts.planName,
+    currentSpend: opts.result.currentSpend,
+    cap: opts.result.cap
+  });
+}
+
 // src/weckr.ts
 var DEFAULT_ENDPOINT = "https://useweckr.com/api/v1/log";
 var Weckr = class {
   apiKey;
   plans;
   log;
+  checkCap;
+  onError;
   constructor(config) {
     if (!config?.apiKey) {
       throw new Error("Weckr: apiKey is required.");
     }
     this.apiKey = config.apiKey;
     this.plans = config.plans ?? {};
+    this.onError = config.onError;
+    const logEndpoint = config.endpoint ?? DEFAULT_ENDPOINT;
     this.log = createLogger({
       apiKey: config.apiKey,
-      endpoint: config.endpoint ?? DEFAULT_ENDPOINT,
+      endpoint: logEndpoint,
       fetch: config.fetch,
       onError: config.onError
     });
+    if (config.disableCapCheck) {
+      this.checkCap = null;
+    } else {
+      this.checkCap = createCapChecker({
+        apiKey: config.apiKey,
+        endpoint: config.checkEndpoint ?? deriveCheckEndpoint(logEndpoint),
+        fetch: config.fetch,
+        onError: config.onError
+      });
+    }
   }
   async chat(client, options) {
     const adapter = detectAdapter(client);
@@ -190,19 +280,39 @@ var Weckr = class {
         "Weckr: could not detect provider. Pass an OpenAI, Anthropic, or Gemini client instance."
       );
     }
+    let effectiveOptions = options;
+    if (this.checkCap && options.userId && options.plan) {
+      const check = await this.checkCap(options.userId, options.plan, options.model);
+      if (!check.allowed) {
+        if (check.action === "downgrade" && check.alternativeModel) {
+          if (typeof console !== "undefined" && console.warn) {
+            console.warn(
+              `Weckr: downgrading ${options.userId} from ${options.model} to ${check.alternativeModel} (cap reached).`
+            );
+          }
+          effectiveOptions = { ...options, model: check.alternativeModel };
+        } else {
+          throw capCheckToError({
+            userId: options.userId,
+            planName: options.plan,
+            result: check
+          });
+        }
+      }
+    }
     const startedAt = nowMs();
-    const result = await adapter.call(client, options);
+    const result = await adapter.call(client, effectiveOptions);
     const latencyMs = Math.round(nowMs() - startedAt);
     try {
       const usage = adapter.extractUsage(result);
-      const { costUsd } = calculateCost(options.model, usage.inputTokens, usage.outputTokens);
-      const planName = options.plan ?? null;
+      const { costUsd } = calculateCost(effectiveOptions.model, usage.inputTokens, usage.outputTokens);
+      const planName = effectiveOptions.plan ?? null;
       const planRevenueUsd = planName != null && Object.prototype.hasOwnProperty.call(this.plans, planName) ? this.plans[planName] : null;
       const marginUsd = planRevenueUsd != null ? round2(planRevenueUsd - costUsd) : null;
       const payload = {
-        userId: options.userId ?? null,
-        feature: options.feature ?? null,
-        model: options.model,
+        userId: effectiveOptions.userId ?? null,
+        feature: effectiveOptions.feature ?? null,
+        model: effectiveOptions.model,
         provider: adapter.name,
         inputTokens: usage.inputTokens,
         outputTokens: usage.outputTokens,
@@ -214,7 +324,8 @@ var Weckr = class {
         timestamp: (/* @__PURE__ */ new Date()).toISOString()
       };
       this.log(payload);
-    } catch {
+    } catch (err) {
+      this.onError?.(err);
     }
     return result;
   }
@@ -232,6 +343,8 @@ function round2(n) {
 0 && (module.exports = {
   PRICING,
   Weckr,
+  WeckrCapError,
   calculateCost,
+  isWeckrCapError,
   resolvePricing
 });

package/dist/index.mjs

@@ -135,24 +135,112 @@ function createLogger(opts) {
   };
 }
 
+// src/cap-cache.ts
+var TTL_MS = 6e4;
+function createCapChecker(opts) {
+  const f = opts.fetch ?? globalThis.fetch;
+  const cache = /* @__PURE__ */ new Map();
+  function key(userId, planName) {
+    return `${userId}\0${planName}`;
+  }
+  return async function checkCap(userId, planName, model) {
+    const k = key(userId, planName);
+    const now = Date.now();
+    const hit = cache.get(k);
+    if (hit && hit.expiresAt > now) return hit.result;
+    if (typeof f !== "function") {
+      return { allowed: true };
+    }
+    try {
+      const url = new URL(opts.endpoint);
+      url.searchParams.set("userId", userId);
+      url.searchParams.set("planName", planName);
+      if (model) url.searchParams.set("model", model);
+      const res = await f(url.toString(), {
+        method: "GET",
+        headers: { "x-api-key": opts.apiKey }
+      });
+      if (!res.ok) {
+        opts.onError?.(
+          new Error(`Weckr cap check failed: ${res.status} ${res.statusText}`)
+        );
+        return { allowed: true };
+      }
+      const json = await res.json();
+      cache.set(k, { result: json, expiresAt: now + TTL_MS });
+      return json;
+    } catch (err) {
+      opts.onError?.(err);
+      return { allowed: true };
+    }
+  };
+}
+function deriveCheckEndpoint(logEndpoint) {
+  if (logEndpoint.endsWith("/log")) return logEndpoint.slice(0, -"/log".length) + "/check";
+  return logEndpoint.replace(/\/$/, "") + "/../check";
+}
+
+// src/errors.ts
+var WeckrCapError = class extends Error {
+  name = "WeckrCapError";
+  userId;
+  planName;
+  currentSpend;
+  cap;
+  constructor(opts) {
+    super(
+      opts.message ?? `Weckr: spending cap reached for user ${opts.userId} on plan ${opts.planName}`
+    );
+    this.userId = opts.userId;
+    this.planName = opts.planName;
+    this.currentSpend = opts.currentSpend;
+    this.cap = opts.cap;
+  }
+};
+function isWeckrCapError(e) {
+  return e instanceof Error && e.name === "WeckrCapError";
+}
+function capCheckToError(opts) {
+  return new WeckrCapError({
+    userId: opts.userId,
+    planName: opts.planName,
+    currentSpend: opts.result.currentSpend,
+    cap: opts.result.cap
+  });
+}
+
 // src/weckr.ts
 var DEFAULT_ENDPOINT = "https://useweckr.com/api/v1/log";
 var Weckr = class {
   apiKey;
   plans;
   log;
+  checkCap;
+  onError;
   constructor(config) {
     if (!config?.apiKey) {
       throw new Error("Weckr: apiKey is required.");
     }
     this.apiKey = config.apiKey;
     this.plans = config.plans ?? {};
+    this.onError = config.onError;
+    const logEndpoint = config.endpoint ?? DEFAULT_ENDPOINT;
     this.log = createLogger({
       apiKey: config.apiKey,
-      endpoint: config.endpoint ?? DEFAULT_ENDPOINT,
+      endpoint: logEndpoint,
       fetch: config.fetch,
       onError: config.onError
     });
+    if (config.disableCapCheck) {
+      this.checkCap = null;
+    } else {
+      this.checkCap = createCapChecker({
+        apiKey: config.apiKey,
+        endpoint: config.checkEndpoint ?? deriveCheckEndpoint(logEndpoint),
+        fetch: config.fetch,
+        onError: config.onError
+      });
+    }
   }
   async chat(client, options) {
     const adapter = detectAdapter(client);
@@ -161,19 +249,39 @@ var Weckr = class {
         "Weckr: could not detect provider. Pass an OpenAI, Anthropic, or Gemini client instance."
       );
     }
+    let effectiveOptions = options;
+    if (this.checkCap && options.userId && options.plan) {
+      const check = await this.checkCap(options.userId, options.plan, options.model);
+      if (!check.allowed) {
+        if (check.action === "downgrade" && check.alternativeModel) {
+          if (typeof console !== "undefined" && console.warn) {
+            console.warn(
+              `Weckr: downgrading ${options.userId} from ${options.model} to ${check.alternativeModel} (cap reached).`
+            );
+          }
+          effectiveOptions = { ...options, model: check.alternativeModel };
+        } else {
+          throw capCheckToError({
+            userId: options.userId,
+            planName: options.plan,
+            result: check
+          });
+        }
+      }
+    }
     const startedAt = nowMs();
-    const result = await adapter.call(client, options);
+    const result = await adapter.call(client, effectiveOptions);
     const latencyMs = Math.round(nowMs() - startedAt);
     try {
       const usage = adapter.extractUsage(result);
-      const { costUsd } = calculateCost(options.model, usage.inputTokens, usage.outputTokens);
-      const planName = options.plan ?? null;
+      const { costUsd } = calculateCost(effectiveOptions.model, usage.inputTokens, usage.outputTokens);
+      const planName = effectiveOptions.plan ?? null;
       const planRevenueUsd = planName != null && Object.prototype.hasOwnProperty.call(this.plans, planName) ? this.plans[planName] : null;
       const marginUsd = planRevenueUsd != null ? round2(planRevenueUsd - costUsd) : null;
       const payload = {
-        userId: options.userId ?? null,
-        feature: options.feature ?? null,
-        model: options.model,
+        userId: effectiveOptions.userId ?? null,
+        feature: effectiveOptions.feature ?? null,
+        model: effectiveOptions.model,
         provider: adapter.name,
         inputTokens: usage.inputTokens,
         outputTokens: usage.outputTokens,
@@ -185,7 +293,8 @@ var Weckr = class {
         timestamp: (/* @__PURE__ */ new Date()).toISOString()
       };
       this.log(payload);
-    } catch {
+    } catch (err) {
+      this.onError?.(err);
     }
     return result;
   }
@@ -202,6 +311,8 @@ function round2(n) {
 export {
   PRICING,
   Weckr,
+  WeckrCapError,
   calculateCost,
+  isWeckrCapError,
   resolvePricing
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weckr/sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "AI cost and margin intelligence for SaaS founders",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -46,9 +46,15 @@
     "openai": ">=4.0.0"
   },
   "peerDependenciesMeta": {
-    "openai": { "optional": true },
-    "@anthropic-ai/sdk": { "optional": true },
-    "@google/generative-ai": { "optional": true }
+    "openai": {
+      "optional": true
+    },
+    "@anthropic-ai/sdk": {
+      "optional": true
+    },
+    "@google/generative-ai": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/node": "^22.10.0",