@tokenwall/sdk 0.1.0

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@tokenwall/sdk",
+  "version": "0.1.0",
+  "description": "TokenWall SDK — enforce hard spend limits on LLM API calls in real time",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "files": [
+    "src/"
+  ],
+  "keywords": [
+    "tokenwall",
+    "llm",
+    "openai",
+    "anthropic",
+    "spend",
+    "cost",
+    "guardrail",
+    "ai"
+  ],
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,32 @@
+export interface Wall {
+  wallUsd: number;
+  window: 'hourly' | 'daily' | 'weekly' | 'monthly';
+  scope?: 'org' | 'key' | 'user' | 'feature';
+  feature?: string;
+}
+
+export interface TokenWallOptions {
+  apiKey: string;
+  wallUsd?: number;
+  window?: 'hourly' | 'daily' | 'weekly' | 'monthly';
+  walls?: Wall[];
+  userId?: string;
+  feature?: string;
+  tags?: Record<string, string>;
+}
+
+export interface TokenWallCallContext {
+  tokenwall?: {
+    userId?: string;
+    feature?: string;
+    tags?: Record<string, string>;
+  };
+}
+
+export class TokenWallBlockedError extends Error {
+  reason: 'wall_exceeded' | 'rate_limited';
+  wall: number;
+  spent: number;
+}
+
+export function tokenwall<T>(client: T, options: TokenWallOptions): T;

package/src/index.js

@@ -0,0 +1,121 @@
+'use strict';
+
+const TOKENWALL_API = 'https://api.tokenwall.dev/v1';
+
+class TokenWallBlockedError extends Error {
+  constructor({ reason, wall, spent }) {
+    super(`TokenWall blocked: ${reason} (spent $${spent} of $${wall} wall)`);
+    this.name = 'TokenWallBlockedError';
+    this.reason = reason;
+    this.wall = wall;
+    this.spent = spent;
+  }
+}
+
+function tokenwall(client, options = {}) {
+  const {
+    apiKey,
+    wallUsd,
+    window: timeWindow,
+    walls,
+    userId,
+    feature,
+    tags,
+  } = options;
+
+  if (!apiKey) throw new Error('TokenWall: apiKey is required');
+
+  // Proxy the client's chat.completions.create (OpenAI-compatible)
+  const originalCreate = client.chat?.completions?.create?.bind(client.chat.completions);
+
+  const guardrail = async (params, callOptions = {}) => {
+    const ctx = callOptions.tokenwall ?? {};
+    const effectiveUserId = ctx.userId ?? userId;
+    const effectiveFeature = ctx.feature ?? feature;
+    const effectiveTags = { ...tags, ...ctx.tags };
+
+    // Resolve walls for this call
+    const activeWalls = walls ?? (wallUsd != null ? [{ wallUsd, window: timeWindow ?? 'monthly' }] : []);
+
+    // Pre-flight check with TokenWall
+    let checkRes;
+    try {
+      checkRes = await fetch(`${TOKENWALL_API}/check`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({
+          model: params.model,
+          walls: activeWalls,
+          userId: effectiveUserId,
+          feature: effectiveFeature,
+          tags: effectiveTags,
+        }),
+      });
+    } catch {
+      // If TokenWall is unreachable, fail open (let the call through)
+      return originalCreate(params, callOptions);
+    }
+
+    const check = await checkRes.json();
+
+    if (check.blocked) {
+      throw new TokenWallBlockedError({
+        reason: check.reason,
+        wall: check.wall,
+        spent: check.spent,
+      });
+    }
+
+    // Make the real call
+    const response = await originalCreate(params, callOptions);
+
+    // Post-call: report actual usage
+    const usage = response?.usage;
+    if (usage) {
+      fetch(`${TOKENWALL_API}/ingest`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({
+          model: params.model,
+          promptTokens: usage.prompt_tokens,
+          completionTokens: usage.completion_tokens,
+          userId: effectiveUserId,
+          feature: effectiveFeature,
+          tags: effectiveTags,
+        }),
+      }).catch(() => {}); // fire-and-forget, never block the caller
+    }
+
+    return response;
+  };
+
+  // Return a proxy that wraps chat.completions.create
+  return new Proxy(client, {
+    get(target, prop) {
+      if (prop === 'chat') {
+        return new Proxy(target.chat, {
+          get(chatTarget, chatProp) {
+            if (chatProp === 'completions') {
+              return new Proxy(chatTarget.completions, {
+                get(compTarget, compProp) {
+                  if (compProp === 'create') return guardrail;
+                  return compTarget[compProp];
+                },
+              });
+            }
+            return chatTarget[chatProp];
+          },
+        });
+      }
+      return target[prop];
+    },
+  });
+}
+
+module.exports = { tokenwall, TokenWallBlockedError };