@loopers/client 0.4.3

package/README.md

@@ -0,0 +1,79 @@
+# Loopers TypeScript SDK (`@loopers/client`)
+
+The `@loopers/client` package provides a drop-in wrapper around official OpenAI and Anthropic SDK clients to make integration with the Loopers cost firewall seamless in Node.js and browser environments.
+
+## Installation
+
+```bash
+npm install @loopers/client
+```
+
+Additionally, install the official provider package you plan to use:
+
+```bash
+npm install openai
+# or
+npm install @anthropic-ai/sdk
+```
+
+## Features
+
+- **Automatic Headers Injection**: Automatically handles injection of Loopers proxy keys (`Authorization`), upstream provider keys (`X-Loopers-Provider-Key`), and session budget limits.
+- **Custom Attributes**: Intercepts response parsing and attaches cost metadata directly to the returned objects.
+
+## Usage
+
+### OpenAI Integration
+
+Replace `OpenAI` with `LoopersOpenAI`:
+
+```typescript
+import { LoopersOpenAI } from '@loopers/client';
+
+// Initialize client
+const client = new LoopersOpenAI({
+  loopersUrl: 'http://localhost:8080',
+  loopersKey: 'lp-xxx',          // Loopers proxy key
+  providerKey: 'sk-proj-xxx',    // Upstream OpenAI key
+  sessionId: 'agent-run-123',    // Optional: track steps and budget for an agent session
+  sessionBudget: 2.50,           // Optional: limit session to $2.50
+  maxSteps: 20                   // Optional: limit session to 20 steps
+});
+
+// Call completions exactly like the official client
+const response = await client.chat.completions.create({
+  model: 'gpt-4o',
+  messages: [{ role: 'user', content: 'Hello!' }],
+});
+
+// Inspect budget/cost metadata attached to response
+console.log(`Request Cost: $${(response as any).loopers_cost} USD`);
+console.log(`Estimated Cost: $${(response as any).loopers_cost_estimated} USD`);
+console.log(`Session Spend: $${(response as any).loopers_session_spend} USD`);
+console.log(`Session Steps: ${(response as any).loopers_session_steps}`);
+console.log(`Session Remaining: $${(response as any).loopers_session_remaining} USD`);
+```
+
+### Anthropic Integration
+
+```typescript
+import { LoopersAnthropic } from '@loopers/client';
+
+const client = new LoopersAnthropic({
+  loopersUrl: 'http://localhost:8080',
+  loopersKey: 'lp-xxx',
+  providerKey: 'sk-ant-xxx'
+});
+
+const response = await client.messages.create({
+  model: 'claude-3-5-sonnet-latest',
+  max_tokens: 1000,
+  messages: [{ role: 'user', content: 'Hello!' }]
+});
+
+console.log(`Request Cost: $${(response as any).loopers_cost} USD`);
+```
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,20 @@
+import OpenAI from 'openai';
+import Anthropic from '@anthropic-ai/sdk';
+export interface LoopersClientOptions {
+    loopersUrl: string;
+    loopersKey: string;
+    providerKey?: string;
+    sessionId?: string;
+    sessionBudget?: number;
+    maxSteps?: number;
+}
+export declare class LoopersOpenAI extends OpenAI {
+    constructor(options: LoopersClientOptions & {
+        [key: string]: any;
+    });
+}
+export declare class LoopersAnthropic extends Anthropic {
+    constructor(options: LoopersClientOptions & {
+        [key: string]: any;
+    });
+}

package/dist/client.js

@@ -0,0 +1,106 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LoopersAnthropic = exports.LoopersOpenAI = void 0;
+const openai_1 = __importDefault(require("openai"));
+const sdk_1 = __importDefault(require("@anthropic-ai/sdk"));
+function createLoopersFetch(loopersKey, providerKey, sessionId, sessionBudget, maxSteps, customFetch) {
+    const originalFetch = customFetch || (typeof fetch !== 'undefined' ? fetch : undefined);
+    if (!originalFetch) {
+        throw new Error('A global fetch function is not available. Please pass a custom fetch implementation.');
+    }
+    return async (input, init) => {
+        // In JS/TS, headers can be in different structures
+        const headers = new Headers(init?.headers || {});
+        // Set Loopers headers
+        headers.set('Authorization', `Bearer ${loopersKey}`);
+        if (providerKey) {
+            headers.set('X-Loopers-Provider-Key', providerKey);
+        }
+        if (sessionId) {
+            headers.set('X-Loopers-Session-ID', sessionId);
+        }
+        if (sessionBudget !== undefined) {
+            headers.set('X-Loopers-Session-Budget', String(sessionBudget));
+        }
+        if (maxSteps !== undefined) {
+            headers.set('X-Loopers-Session-Max-Steps', String(maxSteps));
+        }
+        const modifiedInit = {
+            ...init,
+            headers,
+        };
+        const res = await originalFetch(input, modifiedInit);
+        // Intercept response.json() to attach loopers properties to the returned parsed object
+        const originalJson = res.json;
+        res.json = async () => {
+            const data = await originalJson.call(res);
+            if (data && typeof data === 'object') {
+                const costVal = res.headers.get('X-Loopers-Request-Cost');
+                const estCostVal = res.headers.get('X-Loopers-Request-Cost-Estimated');
+                const spendVal = res.headers.get('X-Loopers-Session-Spend');
+                const stepsVal = res.headers.get('X-Loopers-Session-Steps');
+                const remainingVal = res.headers.get('X-Loopers-Session-Remaining');
+                Object.defineProperties(data, {
+                    loopers_cost: {
+                        value: costVal ? Number(costVal) : null,
+                        writable: true,
+                        enumerable: true,
+                    },
+                    loopers_cost_estimated: {
+                        value: estCostVal ? Number(estCostVal) : null,
+                        writable: true,
+                        enumerable: true,
+                    },
+                    loopers_session_spend: {
+                        value: spendVal ? Number(spendVal) : null,
+                        writable: true,
+                        enumerable: true,
+                    },
+                    loopers_session_steps: {
+                        value: stepsVal ? Number(stepsVal) : null,
+                        writable: true,
+                        enumerable: true,
+                    },
+                    loopers_session_remaining: {
+                        value: remainingVal ? Number(remainingVal) : null,
+                        writable: true,
+                        enumerable: true,
+                    },
+                });
+            }
+            return data;
+        };
+        return res;
+    };
+}
+class LoopersOpenAI extends openai_1.default {
+    constructor(options) {
+        const { loopersUrl, loopersKey, providerKey, sessionId, sessionBudget, maxSteps, ...openaiOptions } = options;
+        const baseFetch = openaiOptions.fetch;
+        const loopersFetch = createLoopersFetch(loopersKey, providerKey, sessionId, sessionBudget, maxSteps, baseFetch);
+        super({
+            ...openaiOptions,
+            baseURL: `${loopersUrl.replace(/\/$/, '')}/openai/v1`,
+            apiKey: loopersKey,
+            fetch: loopersFetch,
+        });
+    }
+}
+exports.LoopersOpenAI = LoopersOpenAI;
+class LoopersAnthropic extends sdk_1.default {
+    constructor(options) {
+        const { loopersUrl, loopersKey, providerKey, sessionId, sessionBudget, maxSteps, ...anthropicOptions } = options;
+        const baseFetch = anthropicOptions.fetch;
+        const loopersFetch = createLoopersFetch(loopersKey, providerKey, sessionId, sessionBudget, maxSteps, baseFetch);
+        super({
+            ...anthropicOptions,
+            baseURL: `${loopersUrl.replace(/\/$/, '')}/anthropic`,
+            authToken: loopersKey,
+            fetch: loopersFetch,
+        });
+    }
+}
+exports.LoopersAnthropic = LoopersAnthropic;

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { LoopersOpenAI, LoopersAnthropic, LoopersClientOptions } from './client';

package/dist/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LoopersAnthropic = exports.LoopersOpenAI = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "LoopersOpenAI", { enumerable: true, get: function () { return client_1.LoopersOpenAI; } });
+Object.defineProperty(exports, "LoopersAnthropic", { enumerable: true, get: function () { return client_1.LoopersAnthropic; } });

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@loopers/client",
+  "version": "0.4.3",
+  "description": "A premium TypeScript client wrapper for the Loopers AI budget & rate-limit proxy.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc"
+  },
+  "keywords": [
+    "loopers",
+    "budget",
+    "firewall",
+    "openai",
+    "anthropic",
+    "proxy"
+  ],
+  "author": "Loopers OSS Contributors",
+  "license": "MIT",
+  "peerDependencies": {
+    "openai": "^4.0.0",
+    "@anthropic-ai/sdk": "^0.30.0"
+  },
+  "peerDependenciesMeta": {
+    "openai": {
+      "optional": true
+    },
+    "@anthropic-ai/sdk": {
+      "optional": true
+    }
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "openai": "^4.0.0",
+    "@anthropic-ai/sdk": "^0.30.0"
+  }
+}

package/src/client.ts

@@ -0,0 +1,166 @@
+import OpenAI from 'openai';
+import Anthropic from '@anthropic-ai/sdk';
+
+export interface LoopersClientOptions {
+  loopersUrl: string;
+  loopersKey: string;
+  providerKey?: string;
+  sessionId?: string;
+  sessionBudget?: number;
+  maxSteps?: number;
+}
+
+function createLoopersFetch(
+  loopersKey: string,
+  providerKey?: string,
+  sessionId?: string,
+  sessionBudget?: number,
+  maxSteps?: number,
+  customFetch?: typeof fetch
+) {
+  const originalFetch = customFetch || (typeof fetch !== 'undefined' ? fetch : undefined);
+  if (!originalFetch) {
+    throw new Error('A global fetch function is not available. Please pass a custom fetch implementation.');
+  }
+
+  return async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+    // In JS/TS, headers can be in different structures
+    const headers = new Headers(init?.headers || {});
+
+    // Set Loopers headers
+    headers.set('Authorization', `Bearer ${loopersKey}`);
+    if (providerKey) {
+      headers.set('X-Loopers-Provider-Key', providerKey);
+    }
+    if (sessionId) {
+      headers.set('X-Loopers-Session-ID', sessionId);
+    }
+    if (sessionBudget !== undefined) {
+      headers.set('X-Loopers-Session-Budget', String(sessionBudget));
+    }
+    if (maxSteps !== undefined) {
+      headers.set('X-Loopers-Session-Max-Steps', String(maxSteps));
+    }
+
+    const modifiedInit = {
+      ...init,
+      headers,
+    };
+
+    const res = await originalFetch(input, modifiedInit);
+
+    // Intercept response.json() to attach loopers properties to the returned parsed object
+    const originalJson = res.json;
+    res.json = async () => {
+      const data = await originalJson.call(res);
+      if (data && typeof data === 'object') {
+        const costVal = res.headers.get('X-Loopers-Request-Cost');
+        const estCostVal = res.headers.get('X-Loopers-Request-Cost-Estimated');
+        const spendVal = res.headers.get('X-Loopers-Session-Spend');
+        const stepsVal = res.headers.get('X-Loopers-Session-Steps');
+        const remainingVal = res.headers.get('X-Loopers-Session-Remaining');
+
+        Object.defineProperties(data, {
+          loopers_cost: {
+            value: costVal ? Number(costVal) : null,
+            writable: true,
+            enumerable: true,
+          },
+          loopers_cost_estimated: {
+            value: estCostVal ? Number(estCostVal) : null,
+            writable: true,
+            enumerable: true,
+          },
+          loopers_session_spend: {
+            value: spendVal ? Number(spendVal) : null,
+            writable: true,
+            enumerable: true,
+          },
+          loopers_session_steps: {
+            value: stepsVal ? Number(stepsVal) : null,
+            writable: true,
+            enumerable: true,
+          },
+          loopers_session_remaining: {
+            value: remainingVal ? Number(remainingVal) : null,
+            writable: true,
+            enumerable: true,
+          },
+        });
+      }
+      return data;
+    };
+
+    return res;
+  };
+}
+
+export class LoopersOpenAI extends OpenAI {
+  constructor(
+    options: LoopersClientOptions & {
+      [key: string]: any;
+    }
+  ) {
+    const {
+      loopersUrl,
+      loopersKey,
+      providerKey,
+      sessionId,
+      sessionBudget,
+      maxSteps,
+      ...openaiOptions
+    } = options;
+
+    const baseFetch = openaiOptions.fetch;
+    const loopersFetch = createLoopersFetch(
+      loopersKey,
+      providerKey,
+      sessionId,
+      sessionBudget,
+      maxSteps,
+      baseFetch
+    );
+
+    super({
+      ...openaiOptions,
+      baseURL: `${loopersUrl.replace(/\/$/, '')}/openai/v1`,
+      apiKey: loopersKey,
+      fetch: loopersFetch,
+    });
+  }
+}
+
+export class LoopersAnthropic extends Anthropic {
+  constructor(
+    options: LoopersClientOptions & {
+      [key: string]: any;
+    }
+  ) {
+    const {
+      loopersUrl,
+      loopersKey,
+      providerKey,
+      sessionId,
+      sessionBudget,
+      maxSteps,
+      ...anthropicOptions
+    } = options;
+
+    const baseFetch = anthropicOptions.fetch;
+    const loopersFetch = createLoopersFetch(
+      loopersKey,
+      providerKey,
+      sessionId,
+      sessionBudget,
+      maxSteps,
+      baseFetch
+    );
+
+    super({
+      ...anthropicOptions,
+      baseURL: `${loopersUrl.replace(/\/$/, '')}/anthropic`,
+      authToken: loopersKey,
+      fetch: loopersFetch,
+    });
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { LoopersOpenAI, LoopersAnthropic, LoopersClientOptions } from './client';

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "CommonJS",
+    "lib": ["ES2020", "DOM"],
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"]
+}