cassette-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Cassette — optional one-call TS/JS shim.
+ *
+ * Not strictly required: setting `OPENAI_BASE_URL` / `ANTHROPIC_BASE_URL` to the gateway URL works
+ * on its own. `cassetteBaseURL()` composes the right URL; `use()` sets the standard env vars.
+ *
+ *   import { use } from "cassette-sdk";
+ *   use(); // reads CASSETTE_GATEWAY / CASSETTE_PROJECT / CASSETTE_MODE
+ *
+ * Or pass it explicitly when constructing a client:
+ *
+ *   import OpenAI from "openai";
+ *   import { cassetteBaseURL } from "cassette-sdk";
+ *   const client = new OpenAI({ baseURL: cassetteBaseURL("openai") });
+ */
+export type Provider = "openai" | "anthropic" | "google";
+export type Mode = "record" | "replay" | "auto";
+interface Opts {
+    gateway?: string;
+    project?: string;
+    mode?: Mode;
+}
+export declare function cassetteBaseURL(provider: Provider, opts?: Opts): string;
+/** Set the standard SDK base-URL env vars to point at the gateway. Returns what it set. */
+export declare function use(opts?: Opts): Record<string, string>;
+export {};

package/dist/index.js

@@ -0,0 +1,29 @@
+const PROVIDER_SUFFIX = {
+    openai: "/openai/v1",
+    anthropic: "/anthropic",
+    google: "/google",
+};
+function resolve(opts = {}) {
+    const env = globalThis.process?.env ?? {};
+    return {
+        gateway: (opts.gateway ?? env.CASSETTE_GATEWAY ?? "http://localhost:8787").replace(/\/+$/, ""),
+        project: opts.project ?? env.CASSETTE_PROJECT ?? "default",
+        mode: (opts.mode ?? env.CASSETTE_MODE ?? "auto"),
+    };
+}
+export function cassetteBaseURL(provider, opts = {}) {
+    const { gateway, project, mode } = resolve(opts);
+    return `${gateway}/${project}/${mode}${PROVIDER_SUFFIX[provider]}`;
+}
+/** Set the standard SDK base-URL env vars to point at the gateway. Returns what it set. */
+export function use(opts = {}) {
+    const env = globalThis.process?.env;
+    const map = {
+        OPENAI_BASE_URL: cassetteBaseURL("openai", opts),
+        ANTHROPIC_BASE_URL: cassetteBaseURL("anthropic", opts),
+        GOOGLE_GEMINI_BASE_URL: cassetteBaseURL("google", opts),
+    };
+    if (env)
+        Object.assign(env, map);
+    return map;
+}

package/dist/recorder.d.ts

@@ -0,0 +1,10 @@
+type Mode = "record" | "replay" | "auto";
+export declare class CassetteMiss extends Error {
+}
+export interface RecorderOpts {
+    project?: string;
+    mode?: Mode;
+    cassetteDir?: string;
+}
+export declare function recordingFetch(opts?: RecorderOpts): typeof fetch;
+export {};

package/dist/recorder.js

@@ -0,0 +1,90 @@
+/**
+ * In-process recorder for Node (the surface we own — no gateway required).
+ *
+ * Returns a `fetch`-compatible function that records/replays at the HTTP layer. Pass it to the SDK:
+ *
+ *   import OpenAI from "openai";
+ *   import { recordingFetch } from "cassette-sdk/recorder";
+ *   const client = new OpenAI({ fetch: recordingFetch({ project: "demo" }) });
+ *
+ * In vitest/jest, wrap the global fetch in setup:
+ *   globalThis.fetch = recordingFetch({ project: "demo" });
+ *
+ * Cassettes conform to SPEC.md and interoperate with the Python recorder and the gateway.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+const VOLATILE = new Set(["stream_options", "user", "metadata"]);
+const DROP_RESP = new Set(["content-length", "content-encoding", "transfer-encoding", "connection"]);
+function canonical(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return "[" + value.map(canonical).join(",") + "]";
+    const obj = value;
+    return ("{" +
+        Object.keys(obj)
+            .filter((k) => !VOLATILE.has(k))
+            .sort()
+            .map((k) => JSON.stringify(k) + ":" + canonical(obj[k]))
+            .join(",") +
+        "}");
+}
+function fingerprint(method, url, body) {
+    let norm = body;
+    if (body) {
+        try {
+            norm = canonical(JSON.parse(body));
+        }
+        catch {
+            /* non-JSON body — hash verbatim */
+        }
+    }
+    return createHash("sha256").update([method.toUpperCase(), url, norm].join("\n")).digest("hex");
+}
+export class CassetteMiss extends Error {
+}
+export function recordingFetch(opts = {}) {
+    const env = globalThis.process?.env ?? {};
+    const project = opts.project ?? env.CASSETTE_PROJECT ?? "default";
+    const mode = opts.mode ?? env.CASSETTE_MODE ?? "auto";
+    const dir = join(opts.cassetteDir ?? env.CASSETTE_DIR ?? ".cassettes", project);
+    mkdirSync(dir, { recursive: true });
+    const realFetch = globalThis.fetch.bind(globalThis);
+    return async function cassetteFetch(input, init) {
+        const req = new Request(input, init);
+        const body = req.method === "GET" || req.method === "HEAD" ? "" : await req.clone().text();
+        const fp = fingerprint(req.method, req.url, body);
+        const path = join(dir, `${fp}.json`);
+        if ((mode === "replay" || mode === "auto") && existsSync(path)) {
+            const rec = JSON.parse(readFileSync(path, "utf8"));
+            const headers = new Headers();
+            for (const [k, v] of Object.entries(rec.response.headers)) {
+                if (!DROP_RESP.has(k.toLowerCase()))
+                    headers.set(k, v);
+            }
+            headers.set("x-cassette", "replay");
+            return new Response(rec.response.body, { status: rec.response.status, headers });
+        }
+        if (mode === "replay") {
+            throw new CassetteMiss(`no cassette for ${req.method} ${req.url} (fp=${fp.slice(0, 12)})`);
+        }
+        const resp = await realFetch(req);
+        const text = await resp.text();
+        if (resp.ok) {
+            const headers = {};
+            resp.headers.forEach((v, k) => {
+                if (!/^(authorization|set-cookie)$/i.test(k))
+                    headers[k] = v;
+            });
+            writeFileSync(path, JSON.stringify({
+                v: 1,
+                fingerprint: fp,
+                request: { method: req.method, url: req.url, body },
+                response: { status: resp.status, headers, body: text },
+            }, null, 2));
+        }
+        return new Response(text, { status: resp.status, headers: resp.headers });
+    };
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "cassette-sdk",
+  "version": "0.1.0",
+  "description": "Record/replay LLM & agent API calls for fast, free, deterministic tests. In-process recorder + optional gateway shim.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
+    "./recorder": { "types": "./dist/recorder.d.ts", "import": "./dist/recorder.js" }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["llm", "agent", "testing", "record", "replay", "vcr", "openai", "anthropic", "ci", "vitest", "jest"],
+  "license": "MIT",
+  "repository": { "type": "git", "url": "https://github.com/NOVUS-STUDIOS-DEV/cassette" },
+  "homepage": "https://github.com/NOVUS-STUDIOS-DEV/cassette",
+  "engines": { "node": ">=18" },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.6.0"
+  }
+}