@useairfoil/effect-vcr 0.0.1 → 0.3.0

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["CassetteStore: Context.Service<CassetteStore, CassetteStore>","layer","CassetteStore.CassetteStore","rootDir: string","CassetteStore.toStoreError","CassetteStore.parseCassette","CassetteStore.createEmptyCassetteFile","CassetteStore.make","record: Record<string, string>","record","filtered: Record<string, string>","next: Record<string, unknown>","record: Record<string, string>","record","next: Cassette"],"sources":["../src/cassette-store.ts","../src/vitest-state.ts","../src/file-system-cassette-store.ts","../src/sanitize.ts","../src/vcr-http-client.ts"],"sourcesContent":["import { Context, DateTime, Effect, Schema } from \"effect\";\n\nimport type { Cassette, CassetteFile } from \"./types\";\n\n/**\n * Storage contract for VCR cassettes.\n *\n */\nexport interface CassetteStore {\n  /** Returns true if a cassette with the given name exists. */\n  readonly exists: (name: string) => Effect.Effect<boolean, CassetteStoreError>;\n\n  /** Loads a cassette by name, returning a `CassetteFile` if found. */\n  readonly load: (name: string) => Effect.Effect<CassetteFile, CassetteStoreError>;\n\n  /** Saves a cassette by name, overwriting any existing cassette with the same name. */\n  readonly save: (name: string, content: CassetteFile) => Effect.Effect<void, CassetteStoreError>;\n\n  /** Loads a cassette by name, initializing a new empty cassette if not found. */\n  readonly loadOrInit: (name: string) => Effect.Effect<CassetteFile, CassetteStoreError>;\n}\n\n/**\n * Effect service tag for the cassette store.\n */\nexport const CassetteStore: Context.Service<CassetteStore, CassetteStore> = Context.Service(\n  \"@useairfoil/effect-vcr/CassetteStore\",\n);\n\n/**\n * Creates a new empty cassette with a timestamp and format version.\n */\nexport const createEmptyCassette = (): Effect.Effect<Cassette> =>\n  Effect.gen(function* () {\n    const now = yield* DateTime.now;\n    return {\n      meta: {\n        createdAt: DateTime.formatIso(now),\n        version: \"1\",\n      },\n      entries: {},\n    };\n  });\n\nexport const createEmptyCassetteFile = (): Effect.Effect<CassetteFile> =>\n  Effect.map(createEmptyCassette(), (cassette) => ({\n    exports: { default: cassette },\n  }));\n\n/**\n * Structured error for cassette persistence operations.\n *\n * `operation` indicates which store function failed.\n * `path` is the file or directory path that was targeted.\n */\nexport class CassetteStoreError extends Schema.TaggedErrorClass<CassetteStoreError>()(\n  \"CassetteStoreError\",\n  {\n    operation: Schema.String,\n    path: Schema.String,\n    message: Schema.optional(Schema.String),\n    cause: Schema.optional(Schema.Unknown),\n  },\n) {}\n\nexport const toStoreError = (\n  operation: \"exists\" | \"load\" | \"save\" | \"loadOrInit\",\n  path: string,\n  cause?: unknown,\n  message?: string,\n) =>\n  new CassetteStoreError({\n    operation,\n    path,\n    cause,\n    message,\n  });\n\n/**\n * Parses cassette JSON and maps invalid JSON to a store error.\n */\nexport const parseCassette = (content: string, path: string) =>\n  Effect.try({\n    try: () => JSON.parse(content) as CassetteFile,\n    catch: (error) => toStoreError(\"load\", path, error, \"Invalid JSON\"),\n  }).pipe(\n    Effect.flatMap((parsed) => {\n      if (!parsed || typeof parsed !== \"object\" || !(\"exports\" in parsed)) {\n        return Effect.fail(toStoreError(\"load\", path, undefined, \"Invalid cassette file format\"));\n      }\n      return Effect.succeed(parsed);\n    }),\n  );\n\n/** Creates a `CassetteStore` implementation that uses the given `impl` object. */\nexport const make = (impl: CassetteStore): CassetteStore =>\n  CassetteStore.of({\n    ...impl,\n  });\n","export type VitestState = {\n  readonly testPath?: string;\n  readonly currentTestName?: string;\n};\n\nexport const getVitestState = (): VitestState => {\n  const expectGlobal =\n    // biome-ignore lint/suspicious/noExplicitAny: --\n    (globalThis as { expect?: { getState?: () => any } }).expect;\n  const symbolExpect =\n    // biome-ignore lint/suspicious/noExplicitAny: --\n    (globalThis as { [key: symbol]: { getState?: () => any } })[Symbol.for(\"expect-global\")];\n  const state = expectGlobal?.getState?.() ?? symbolExpect?.getState?.();\n  return {\n    testPath: state?.testPath as string | undefined,\n    currentTestName: state?.currentTestName as string | undefined,\n  };\n};\n","import { Effect, Layer, FileSystem, Path } from \"effect\";\n\nimport type { CassetteFile } from \"./types\";\n\nimport * as CassetteStore from \"./cassette-store\";\nimport { getVitestState } from \"./vitest-state\";\n\n/**\n * FileSystem-backed cassette store.\n *\n * Requires a platform FileSystem layer (Node/Bun) to be provided by the user.\n */\nexport const layer = ({ cassetteDir }: { cassetteDir?: string } = {}) =>\n  Layer.effect(CassetteStore.CassetteStore)(\n    Effect.gen(function* () {\n      const fs = yield* FileSystem.FileSystem;\n      const path = yield* Path.Path;\n\n      let rootDir: string;\n      if (cassetteDir) {\n        rootDir = cassetteDir;\n      } else {\n        const { testPath } = getVitestState();\n        if (!testPath) {\n          return yield* Effect.fail(new Error(\"vcr must be used within a vitest test\"));\n        }\n        const testFolder = path.dirname(testPath);\n        rootDir = path.join(testFolder, \"__cassettes__\");\n      }\n\n      const fullPath = (name: string) => path.join(rootDir, name);\n\n      const load = (name: string) =>\n        fs.readFileString(fullPath(name)).pipe(\n          Effect.mapError((error) => CassetteStore.toStoreError(\"load\", name, error)),\n          Effect.flatMap((content) => CassetteStore.parseCassette(content, name)),\n        );\n\n      const save = (name: string, cassette: CassetteFile) => {\n        const filePath = fullPath(name);\n        const dir = path.dirname(filePath);\n        const ensureDir =\n          dir === \"\"\n            ? Effect.void\n            : fs\n                .makeDirectory(dir, { recursive: true })\n                .pipe(Effect.mapError((error) => CassetteStore.toStoreError(\"save\", dir, error)));\n        return ensureDir.pipe(\n          Effect.andThen(\n            fs\n              .writeFileString(filePath, JSON.stringify(cassette, null, 2))\n              .pipe(Effect.mapError((error) => CassetteStore.toStoreError(\"save\", name, error))),\n          ),\n        );\n      };\n\n      const loadOrInit = (name: string) =>\n        fs.exists(fullPath(name)).pipe(\n          Effect.mapError((error) => CassetteStore.toStoreError(\"loadOrInit\", name, error)),\n          Effect.flatMap((exists) =>\n            exists\n              ? load(name)\n              : CassetteStore.createEmptyCassetteFile().pipe(\n                  Effect.tap((cassette) => save(name, cassette)),\n                ),\n          ),\n        );\n\n      return CassetteStore.make({\n        exists: (name: string) =>\n          fs\n            .exists(fullPath(name))\n            .pipe(Effect.mapError((error) => CassetteStore.toStoreError(\"exists\", name, error))),\n        load,\n        save,\n        loadOrInit,\n      });\n    }),\n  );\n","import { Effect, Option } from \"effect\";\nimport stableStringify from \"json-stable-stringify\";\n\nimport type { VcrRequest, VcrResponse } from \"./types\";\n\n/**\n * Normalize header names to match HttpClient's lowercase behavior.\n */\nconst normalizeHeaderKey = (key: string) => key.toLowerCase();\n\n/**\n * Canonicalize headers: lowercase keys and stable ordering.\n */\nconst toHeaderRecord = (headers?: Record<string, string>) => {\n  if (!headers) return undefined;\n  const entries = Object.entries(headers).map(\n    ([key, value]) => [normalizeHeaderKey(key), value] as const,\n  );\n  entries.sort(([a], [b]) => a.localeCompare(b));\n  const record: Record<string, string> = {};\n  for (const [key, value] of entries) {\n    record[key] = value;\n  }\n  return record;\n};\n\n/**\n * Remove specified header names (case-insensitive).\n */\nconst omitHeaderKeys = (\n  headers: Record<string, string> | undefined,\n  ignore: ReadonlyArray<string> | undefined,\n): Option.Option<Record<string, string>> => {\n  if (!headers) return Option.none();\n  if (!ignore || ignore.length === 0) return Option.some(headers);\n  const ignoreSet = new Set(ignore.map(normalizeHeaderKey));\n  const filtered: Record<string, string> = {};\n  for (const [key, value] of Object.entries(headers)) {\n    if (!ignoreSet.has(normalizeHeaderKey(key))) {\n      filtered[key] = value;\n    }\n  }\n  return Option.some(filtered);\n};\n\n/**\n * Best-effort JSON parse; returns undefined for non-JSON bodies.\n */\nconst tryParseJson = Option.liftThrowable((input: string) => JSON.parse(input));\n\n/**\n * Recursively drop keys from JSON objects to build stable request keys.\n */\nconst stripKeys = (value: unknown, ignore: Set<string>): unknown => {\n  if (Array.isArray(value)) {\n    return value.map((item) => stripKeys(item, ignore));\n  }\n  if (value && typeof value === \"object\") {\n    const record = value as Record<string, unknown>;\n    const next: Record<string, unknown> = {};\n    for (const [key, entry] of Object.entries(record)) {\n      if (!ignore.has(key)) {\n        next[key] = stripKeys(entry, ignore);\n      }\n    }\n    return next;\n  }\n  return value;\n};\n\n/**\n * Remove JSON keys from a string body when possible.\n */\nconst omitBodyKeys = (\n  body: string | undefined,\n  ignore: ReadonlyArray<string> | undefined,\n): Option.Option<string> => {\n  if (!body) return Option.none();\n  return Option.some(\n    tryParseJson(body).pipe(\n      Option.match({\n        onNone: () => body,\n        onSome: (parsed) => {\n          if (!ignore || ignore.length === 0) {\n            return stableStringify(parsed) ?? body;\n          }\n          const ignoreSet = new Set(ignore);\n          return stableStringify(stripKeys(parsed, ignoreSet)) ?? body;\n        },\n      }),\n    ),\n  );\n};\n\n/**\n * Normalize request for matching: header canonicalization + JSON body filtering.\n */\nexport const sanitizeRequest = (\n  request: VcrRequest,\n  options: {\n    readonly ignoreHeaders?: ReadonlyArray<string>;\n    readonly ignoreBodyKeys?: ReadonlyArray<string>;\n  },\n): VcrRequest => {\n  const filteredHeaders = omitHeaderKeys(request.headers, options.ignoreHeaders);\n  return {\n    ...request,\n    headers: toHeaderRecord(Option.getOrUndefined(filteredHeaders)),\n    body: Option.getOrUndefined(omitBodyKeys(request.body, options.ignoreBodyKeys)),\n  };\n};\n\n/**\n * Compute the stable request key used for cassette lookups.\n */\nexport const buildRequestKey = (\n  request: VcrRequest,\n  options: {\n    readonly ignoreHeaders?: ReadonlyArray<string>;\n    readonly ignoreBodyKeys?: ReadonlyArray<string>;\n  },\n): Effect.Effect<string> =>\n  Effect.sync(() => {\n    const sanitized = sanitizeRequest(request, {\n      ignoreHeaders: options.ignoreHeaders,\n      ignoreBodyKeys: options.ignoreBodyKeys,\n    });\n    const key = stableStringify({\n      method: sanitized.method.toUpperCase(),\n      url: sanitized.url,\n      headers: sanitized.headers ?? {},\n      body: sanitized.body ?? \"\",\n    });\n    if (!key) {\n      throw new Error(\"Failed to build VCR request key\");\n    }\n    return key;\n  });\n\n/**\n * Remove sensitive request data before persisting to a cassette.\n */\nexport const redactRequest = (\n  request: VcrRequest,\n  options: {\n    readonly redactHeaders?: ReadonlyArray<string>;\n    readonly redactBodyKeys?: ReadonlyArray<string>;\n  },\n): VcrRequest => ({\n  ...request,\n  headers: Option.getOrUndefined(omitHeaderKeys(request.headers, options.redactHeaders)),\n  body: Option.getOrUndefined(omitBodyKeys(request.body, options.redactBodyKeys)),\n});\n\n/**\n * Remove sensitive response data before persisting to a cassette.\n */\nexport const redactResponse = (\n  response: VcrResponse,\n  options: {\n    readonly redactHeaders?: ReadonlyArray<string>;\n    readonly redactBodyKeys?: ReadonlyArray<string>;\n  },\n): VcrResponse => ({\n  ...response,\n  headers: Option.getOrUndefined(omitHeaderKeys(response.headers, options.redactHeaders)),\n  body: Option.getOrElse(omitBodyKeys(response.body, options.redactBodyKeys), () => response.body),\n});\n","import { Config, Effect, Option, Path } from \"effect\";\nimport {\n  HttpClient,\n  HttpClientError,\n  type HttpClientRequest,\n  HttpClientResponse,\n} from \"effect/unstable/http\";\n\nimport type {\n  Cassette,\n  CassetteFile,\n  Configuration,\n  VcrEntry,\n  VcrRequest,\n  VcrResponse,\n} from \"./types\";\n\nimport { CassetteStore, createEmptyCassette } from \"./cassette-store\";\nimport { buildRequestKey, redactRequest, redactResponse } from \"./sanitize\";\nimport { getVitestState } from \"./vitest-state\";\n\n/**\n * Decoder for Uint8Array request bodies when building cassette keys.\n */\nconst decoder = new TextDecoder();\n\n/**\n * Resolve the cassette file name and export key.\n *\n * If explicit cassetteName are provided, use them and default to\n * the \"default\" export. Otherwise infer from Vitest state:\n * - <file-name>.cassette file name\n * - export key = current test name (describe > test)\n */\nconst resolveCassetteLocation = (config: Configuration) =>\n  Effect.gen(function* () {\n    const path = yield* Path.Path;\n    if (config.cassetteName) {\n      return {\n        name: `${config.cassetteName}.cassette`,\n        exportKey: \"default\",\n      };\n    }\n\n    const { testPath, currentTestName } = getVitestState();\n    if (!testPath || !currentTestName) {\n      throw new Error(\"VCR cassette path could not be inferred. Provide cassetteName.\");\n    }\n\n    const fileName = path.basename(testPath, \".ts\");\n    const cassetteName = `${fileName}.cassette`;\n\n    return {\n      name: cassetteName,\n      exportKey: currentTestName,\n    };\n  });\n\n/**\n * Apply defaults for common VCR behavior while preserving explicit overrides.\n */\nconst normalizeConfig = (config: Configuration) => ({\n  vcrName: config.vcrName,\n  cassetteName: config.cassetteName,\n  mode: config.mode ?? \"auto\",\n  matchIgnore: {\n    requestHeaders: [\"authorization\"],\n    ...config.matchIgnore,\n  },\n  redact: {\n    requestHeaders: [\"authorization\"],\n    ...config.redact,\n  },\n  match: config.match,\n});\n\nconst AckDisableVcrConfig = Config.option(Config.string(\"ACK_DISABLE_VCR\")).pipe(\n  Config.map((value) =>\n    Option.match(value, {\n      onNone: () => new Set<string>(),\n      onSome: (raw) =>\n        raw === \"*\"\n          ? \"*\"\n          : new Set(\n              raw\n                .split(\",\")\n                .map((segment) => segment.trim().toLowerCase())\n                .filter((segment) => segment.length > 0),\n            ),\n    }),\n  ),\n);\n\nconst shouldDisableVcr = (name: string | undefined, disabled: \"*\" | Set<string>): boolean => {\n  if (disabled === \"*\") return true;\n  if (!name) return false;\n  const normalized = name.trim().toLowerCase();\n  return disabled.has(normalized);\n};\n\n/**\n * Convert store or replay failures into HttpClient transport errors.\n */\nconst toRequestError = (\n  request: HttpClientRequest.HttpClientRequest,\n  cause: unknown,\n  description?: string,\n) =>\n  new HttpClientError.HttpClientError({\n    reason: new HttpClientError.TransportError({\n      request,\n      cause,\n      description,\n    }),\n  });\n\n/**\n * Convert header map to a plain record for JSON persistence.\n */\nconst recordFromHeaders = (headers: Record<string, string>) => {\n  const record: Record<string, string> = {};\n  for (const [key, value] of Object.entries(headers)) {\n    record[key] = value;\n  }\n  return record;\n};\n\n/**\n * Serialize an Effect HttpClientRequest into a cassette request shape.\n *\n * Note: some body variants (Stream, FormData) are not safely serializable\n * without consuming the body, so we store placeholders to avoid breaking\n * live requests.\n */\nconst toVcrRequest = (request: HttpClientRequest.HttpClientRequest): VcrRequest => {\n  const headers = recordFromHeaders(request.headers as Record<string, string>);\n  const body = (() => {\n    switch (request.body._tag) {\n      case \"Empty\":\n        return \"\";\n      case \"Uint8Array\":\n        return decoder.decode(request.body.body);\n      case \"Raw\": {\n        const raw = request.body.body as unknown;\n        if (typeof raw === \"string\") return raw;\n        if (raw instanceof Uint8Array) return decoder.decode(raw);\n        try {\n          return JSON.stringify(raw);\n        } catch {\n          return \"[raw]\";\n        }\n      }\n      case \"FormData\":\n        return \"[form-data]\";\n      case \"Stream\":\n        return \"[stream]\";\n    }\n  })();\n\n  return {\n    method: request.method,\n    url: request.url,\n    headers,\n    body,\n  };\n};\n\n/**\n * Serialize an Effect HttpClientResponse into a cassette response shape.\n */\nconst toVcrResponse = (\n  response: HttpClientResponse.HttpClientResponse,\n  body: string,\n): VcrResponse => ({\n  status: response.status,\n  body,\n  headers: recordFromHeaders(response.headers as Record<string, string>),\n});\n\n/**\n * Load a cassette and map store errors into HttpClient errors.\n */\nconst readCassetteFile = (\n  store: CassetteStore,\n  name: string,\n  request: HttpClientRequest.HttpClientRequest,\n) => store.load(name).pipe(Effect.mapError((error) => toRequestError(request, error)));\n\n/**\n * Load a cassette or initialize a new one if missing.\n */\nconst loadOrInitCassetteFile = (\n  store: CassetteStore,\n  name: string,\n  request: HttpClientRequest.HttpClientRequest,\n) => store.loadOrInit(name).pipe(Effect.mapError((error) => toRequestError(request, error)));\n\n/**\n * Persist the updated cassette.\n */\nconst saveCassetteFile = (\n  store: CassetteStore,\n  name: string,\n  cassette: CassetteFile,\n  request: HttpClientRequest.HttpClientRequest,\n) => store.save(name, cassette).pipe(Effect.mapError((error) => toRequestError(request, error)));\n\n/**\n * Load a named cassette export from the file, or return a fresh empty cassette.\n */\nconst readCassetteExport = (\n  store: CassetteStore,\n  name: string,\n  exportKey: string,\n  request: HttpClientRequest.HttpClientRequest,\n) =>\n  readCassetteFile(store, name, request).pipe(\n    Effect.flatMap((file) => {\n      const found = file.exports[exportKey];\n      if (found) return Effect.succeed(found);\n      return createEmptyCassette();\n    }),\n  );\n\n/**\n * Locate a cassette entry by custom matcher or stable request key.\n */\nconst findEntry = (\n  request: VcrRequest,\n  cassette: Cassette,\n  config: Configuration,\n): Effect.Effect<VcrEntry | undefined> => {\n  if (config.match) {\n    return Effect.succeed(\n      Object.values(cassette.entries).find((entry) => config.match?.(request, entry)),\n    );\n  }\n  return buildRequestKey(request, {\n    ignoreHeaders: config.matchIgnore?.requestHeaders,\n    ignoreBodyKeys: config.matchIgnore?.requestBodyKeys,\n  }).pipe(Effect.map((key) => cassette.entries[key]));\n};\n\n/**\n * Replay a response from cassette data using HttpClientResponse.fromWeb.\n */\nconst replay = (\n  store: CassetteStore,\n  request: HttpClientRequest.HttpClientRequest,\n  vcrRequest: VcrRequest,\n  config: Configuration,\n  name: string,\n  exportKey: string,\n) =>\n  readCassetteExport(store, name, exportKey, request).pipe(\n    Effect.flatMap((cassette) =>\n      findEntry(vcrRequest, cassette, config).pipe(\n        Effect.flatMap((entry) => {\n          if (!entry) {\n            return Effect.fail(\n              new HttpClientError.HttpClientError({\n                reason: new HttpClientError.TransportError({\n                  request,\n                  description: `VCR replay missing entry for ${request.method} ${request.url}`,\n                }),\n              }),\n            );\n          }\n\n          const web = new Response(entry.response.body, {\n            status: entry.response.status,\n            headers: entry.response.headers,\n          });\n          return Effect.succeed(HttpClientResponse.fromWeb(request, web));\n        }),\n      ),\n    ),\n  );\n\n/**\n * Record a live response into the cassette and return the original response.\n */\nconst record = (\n  store: CassetteStore,\n  request: HttpClientRequest.HttpClientRequest,\n  vcrRequest: VcrRequest,\n  effect: Effect.Effect<HttpClientResponse.HttpClientResponse, HttpClientError.HttpClientError>,\n  config: Configuration,\n  name: string,\n  exportKey: string,\n) =>\n  Effect.gen(function* () {\n    // Execute the live request and capture the response body (Effect caches reads).\n    const response = yield* effect;\n    const body = yield* response.text;\n    const vcrResponse = toVcrResponse(response, body);\n\n    const sanitizedRequest = config.redact\n      ? redactRequest(vcrRequest, {\n          redactHeaders: config.redact.requestHeaders,\n          redactBodyKeys: config.redact.requestBodyKeys,\n        })\n      : vcrRequest;\n    const sanitizedResponse = config.redact\n      ? redactResponse(vcrResponse, {\n          redactHeaders: config.redact.responseHeaders,\n          redactBodyKeys: config.redact.responseBodyKeys,\n        })\n      : vcrResponse;\n\n    // Load or create the cassette before inserting the new entry.\n    const file = yield* loadOrInitCassetteFile(store, name, request);\n    const cassette = file.exports[exportKey] ?? (yield* createEmptyCassette());\n    const key = yield* buildRequestKey(vcrRequest, {\n      ignoreHeaders: config.matchIgnore?.requestHeaders,\n      ignoreBodyKeys: config.matchIgnore?.requestBodyKeys,\n    });\n    const next: Cassette = {\n      ...cassette,\n      entries: {\n        ...cassette.entries,\n        [key]: {\n          request: sanitizedRequest,\n          response: sanitizedResponse,\n        },\n      },\n    };\n    const nextFile: CassetteFile = {\n      ...file,\n      exports: {\n        ...file.exports,\n        [exportKey]: next,\n      },\n    };\n    // Persist updated cassette to disk.\n    yield* saveCassetteFile(store, name, nextFile, request);\n    return response;\n  });\n\n/**\n * Build a VCR-aware HttpClient that replays or records per config.\n */\nconst makeVcrHttpClient = (config: Configuration) =>\n  Effect.gen(function* () {\n    const live = yield* HttpClient.HttpClient;\n    const normalized = normalizeConfig(config);\n\n    const isCi = yield* Config.boolean(\"CI\").pipe(Config.withDefault(false));\n\n    const disabledVcrs = yield* AckDisableVcrConfig;\n    if (shouldDisableVcr(normalized.vcrName, disabledVcrs)) {\n      return live;\n    }\n\n    // CassetteStore is provided via Layer for platform-specific persistence.\n    const store = yield* CassetteStore;\n\n    const { name, exportKey } = yield* resolveCassetteLocation(normalized);\n\n    return live.pipe(\n      HttpClient.transform((effect, request) =>\n        Effect.gen(function* () {\n          const vcrRequest = toVcrRequest(request);\n          if (normalized.mode === \"replay\") {\n            return yield* replay(store, request, vcrRequest, normalized, name, exportKey);\n          }\n\n          if (normalized.mode === \"record\") {\n            return yield* record(store, request, vcrRequest, effect, normalized, name, exportKey);\n          }\n\n          // Auto mode: replay if cassette exists, otherwise record (or fail in CI).\n          const available = yield* store\n            .exists(name)\n            .pipe(Effect.mapError((error) => toRequestError(request, error)));\n\n          if (!available) {\n            if (isCi) {\n              return yield* Effect.fail(\n                new HttpClientError.HttpClientError({\n                  reason: new HttpClientError.TransportError({\n                    request,\n                    description: \"VCR cassette missing in CI for auto mode\",\n                  }),\n                }),\n              );\n            }\n\n            return yield* record(store, request, vcrRequest, effect, normalized, name, exportKey);\n          }\n\n          const cassette = yield* readCassetteExport(store, name, exportKey, request);\n          const entry = yield* findEntry(vcrRequest, cassette, normalized);\n\n          if (entry) {\n            const web = new Response(entry.response.body, {\n              status: entry.response.status,\n              headers: entry.response.headers,\n            });\n            return HttpClientResponse.fromWeb(request, web);\n          }\n\n          return yield* record(store, request, vcrRequest, effect, normalized, name, exportKey);\n        }),\n      ),\n    );\n  });\n\n/**\n * Layer that provides a VCR-wrapped HttpClient.\n */\nexport const layer = (config: Configuration = {}) =>\n  HttpClient.layerMergedContext(makeVcrHttpClient(config));\n"],"mappings":"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"}

package/package.json

@@ -1,12 +1,47 @@
 {
   "name": "@useairfoil/effect-vcr",
-  "version": "0.0.1",
-  "description": "",
-  "license": "ISC",
-  "author": "",
-  "type": "commonjs",
-  "main": "index.js",
+  "version": "0.3.0",
+  "keywords": [
+    "effect"
+  ],
+  "repository": "useairfoil/typescript-sdk",
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:ci": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "json-stable-stringify": "^1.3.0"
+  },
+  "devDependencies": {
+    "@effect/platform-node": "4.0.0-beta.54",
+    "@effect/vitest": "4.0.0-beta.54",
+    "@types/node": "^24.2.0",
+    "tsdown": "^0.15.6",
+    "vitest": "^3.2.4"
+  },
+  "peerDependencies": {
+    "effect": "4.0.0-beta.54"
+  },
+  "peerDependenciesMeta": {
+    "effect": {
+      "optional": false
+    }
   }
 }

package/src/cassette-store.ts

@@ -0,0 +1,99 @@
+import { Context, DateTime, Effect, Schema } from "effect";
+
+import type { Cassette, CassetteFile } from "./types";
+
+/**
+ * Storage contract for VCR cassettes.
+ *
+ */
+export interface CassetteStore {
+  /** Returns true if a cassette with the given name exists. */
+  readonly exists: (name: string) => Effect.Effect<boolean, CassetteStoreError>;
+
+  /** Loads a cassette by name, returning a `CassetteFile` if found. */
+  readonly load: (name: string) => Effect.Effect<CassetteFile, CassetteStoreError>;
+
+  /** Saves a cassette by name, overwriting any existing cassette with the same name. */
+  readonly save: (name: string, content: CassetteFile) => Effect.Effect<void, CassetteStoreError>;
+
+  /** Loads a cassette by name, initializing a new empty cassette if not found. */
+  readonly loadOrInit: (name: string) => Effect.Effect<CassetteFile, CassetteStoreError>;
+}
+
+/**
+ * Effect service tag for the cassette store.
+ */
+export const CassetteStore: Context.Service<CassetteStore, CassetteStore> = Context.Service(
+  "@useairfoil/effect-vcr/CassetteStore",
+);
+
+/**
+ * Creates a new empty cassette with a timestamp and format version.
+ */
+export const createEmptyCassette = (): Effect.Effect<Cassette> =>
+  Effect.gen(function* () {
+    const now = yield* DateTime.now;
+    return {
+      meta: {
+        createdAt: DateTime.formatIso(now),
+        version: "1",
+      },
+      entries: {},
+    };
+  });
+
+export const createEmptyCassetteFile = (): Effect.Effect<CassetteFile> =>
+  Effect.map(createEmptyCassette(), (cassette) => ({
+    exports: { default: cassette },
+  }));
+
+/**
+ * Structured error for cassette persistence operations.
+ *
+ * `operation` indicates which store function failed.
+ * `path` is the file or directory path that was targeted.
+ */
+export class CassetteStoreError extends Schema.TaggedErrorClass<CassetteStoreError>()(
+  "CassetteStoreError",
+  {
+    operation: Schema.String,
+    path: Schema.String,
+    message: Schema.optional(Schema.String),
+    cause: Schema.optional(Schema.Unknown),
+  },
+) {}
+
+export const toStoreError = (
+  operation: "exists" | "load" | "save" | "loadOrInit",
+  path: string,
+  cause?: unknown,
+  message?: string,
+) =>
+  new CassetteStoreError({
+    operation,
+    path,
+    cause,
+    message,
+  });
+
+/**
+ * Parses cassette JSON and maps invalid JSON to a store error.
+ */
+export const parseCassette = (content: string, path: string) =>
+  Effect.try({
+    try: () => JSON.parse(content) as CassetteFile,
+    catch: (error) => toStoreError("load", path, error, "Invalid JSON"),
+  }).pipe(
+    Effect.flatMap((parsed) => {
+      if (!parsed || typeof parsed !== "object" || !("exports" in parsed)) {
+        return Effect.fail(toStoreError("load", path, undefined, "Invalid cassette file format"));
+      }
+      return Effect.succeed(parsed);
+    }),
+  );
+
+/** Creates a `CassetteStore` implementation that uses the given `impl` object. */
+export const make = (impl: CassetteStore): CassetteStore =>
+  CassetteStore.of({
+    ...impl,
+  });

package/src/file-system-cassette-store.ts

@@ -0,0 +1,79 @@
+import { Effect, Layer, FileSystem, Path } from "effect";
+
+import type { CassetteFile } from "./types";
+
+import * as CassetteStore from "./cassette-store";
+import { getVitestState } from "./vitest-state";
+
+/**
+ * FileSystem-backed cassette store.
+ *
+ * Requires a platform FileSystem layer (Node/Bun) to be provided by the user.
+ */
+export const layer = ({ cassetteDir }: { cassetteDir?: string } = {}) =>
+  Layer.effect(CassetteStore.CassetteStore)(
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+
+      let rootDir: string;
+      if (cassetteDir) {
+        rootDir = cassetteDir;
+      } else {
+        const { testPath } = getVitestState();
+        if (!testPath) {
+          return yield* Effect.fail(new Error("vcr must be used within a vitest test"));
+        }
+        const testFolder = path.dirname(testPath);
+        rootDir = path.join(testFolder, "__cassettes__");
+      }
+
+      const fullPath = (name: string) => path.join(rootDir, name);
+
+      const load = (name: string) =>
+        fs.readFileString(fullPath(name)).pipe(
+          Effect.mapError((error) => CassetteStore.toStoreError("load", name, error)),
+          Effect.flatMap((content) => CassetteStore.parseCassette(content, name)),
+        );
+
+      const save = (name: string, cassette: CassetteFile) => {
+        const filePath = fullPath(name);
+        const dir = path.dirname(filePath);
+        const ensureDir =
+          dir === ""
+            ? Effect.void
+            : fs
+                .makeDirectory(dir, { recursive: true })
+                .pipe(Effect.mapError((error) => CassetteStore.toStoreError("save", dir, error)));
+        return ensureDir.pipe(
+          Effect.andThen(
+            fs
+              .writeFileString(filePath, JSON.stringify(cassette, null, 2))
+              .pipe(Effect.mapError((error) => CassetteStore.toStoreError("save", name, error))),
+          ),
+        );
+      };
+
+      const loadOrInit = (name: string) =>
+        fs.exists(fullPath(name)).pipe(
+          Effect.mapError((error) => CassetteStore.toStoreError("loadOrInit", name, error)),
+          Effect.flatMap((exists) =>
+            exists
+              ? load(name)
+              : CassetteStore.createEmptyCassetteFile().pipe(
+                  Effect.tap((cassette) => save(name, cassette)),
+                ),
+          ),
+        );
+
+      return CassetteStore.make({
+        exists: (name: string) =>
+          fs
+            .exists(fullPath(name))
+            .pipe(Effect.mapError((error) => CassetteStore.toStoreError("exists", name, error))),
+        load,
+        save,
+        loadOrInit,
+      });
+    }),
+  );

package/src/index.ts

@@ -0,0 +1,4 @@
+export * as CassetteStore from "./cassette-store";
+export * as FileSystemCassetteStore from "./file-system-cassette-store";
+
+export * as VcrHttpClient from "./vcr-http-client";

package/src/sanitize.ts

@@ -0,0 +1,168 @@
+import { Effect, Option } from "effect";
+import stableStringify from "json-stable-stringify";
+
+import type { VcrRequest, VcrResponse } from "./types";
+
+/**
+ * Normalize header names to match HttpClient's lowercase behavior.
+ */
+const normalizeHeaderKey = (key: string) => key.toLowerCase();
+
+/**
+ * Canonicalize headers: lowercase keys and stable ordering.
+ */
+const toHeaderRecord = (headers?: Record<string, string>) => {
+  if (!headers) return undefined;
+  const entries = Object.entries(headers).map(
+    ([key, value]) => [normalizeHeaderKey(key), value] as const,
+  );
+  entries.sort(([a], [b]) => a.localeCompare(b));
+  const record: Record<string, string> = {};
+  for (const [key, value] of entries) {
+    record[key] = value;
+  }
+  return record;
+};
+
+/**
+ * Remove specified header names (case-insensitive).
+ */
+const omitHeaderKeys = (
+  headers: Record<string, string> | undefined,
+  ignore: ReadonlyArray<string> | undefined,
+): Option.Option<Record<string, string>> => {
+  if (!headers) return Option.none();
+  if (!ignore || ignore.length === 0) return Option.some(headers);
+  const ignoreSet = new Set(ignore.map(normalizeHeaderKey));
+  const filtered: Record<string, string> = {};
+  for (const [key, value] of Object.entries(headers)) {
+    if (!ignoreSet.has(normalizeHeaderKey(key))) {
+      filtered[key] = value;
+    }
+  }
+  return Option.some(filtered);
+};
+
+/**
+ * Best-effort JSON parse; returns undefined for non-JSON bodies.
+ */
+const tryParseJson = Option.liftThrowable((input: string) => JSON.parse(input));
+
+/**
+ * Recursively drop keys from JSON objects to build stable request keys.
+ */
+const stripKeys = (value: unknown, ignore: Set<string>): unknown => {
+  if (Array.isArray(value)) {
+    return value.map((item) => stripKeys(item, ignore));
+  }
+  if (value && typeof value === "object") {
+    const record = value as Record<string, unknown>;
+    const next: Record<string, unknown> = {};
+    for (const [key, entry] of Object.entries(record)) {
+      if (!ignore.has(key)) {
+        next[key] = stripKeys(entry, ignore);
+      }
+    }
+    return next;
+  }
+  return value;
+};
+
+/**
+ * Remove JSON keys from a string body when possible.
+ */
+const omitBodyKeys = (
+  body: string | undefined,
+  ignore: ReadonlyArray<string> | undefined,
+): Option.Option<string> => {
+  if (!body) return Option.none();
+  return Option.some(
+    tryParseJson(body).pipe(
+      Option.match({
+        onNone: () => body,
+        onSome: (parsed) => {
+          if (!ignore || ignore.length === 0) {
+            return stableStringify(parsed) ?? body;
+          }
+          const ignoreSet = new Set(ignore);
+          return stableStringify(stripKeys(parsed, ignoreSet)) ?? body;
+        },
+      }),
+    ),
+  );
+};
+
+/**
+ * Normalize request for matching: header canonicalization + JSON body filtering.
+ */
+export const sanitizeRequest = (
+  request: VcrRequest,
+  options: {
+    readonly ignoreHeaders?: ReadonlyArray<string>;
+    readonly ignoreBodyKeys?: ReadonlyArray<string>;
+  },
+): VcrRequest => {
+  const filteredHeaders = omitHeaderKeys(request.headers, options.ignoreHeaders);
+  return {
+    ...request,
+    headers: toHeaderRecord(Option.getOrUndefined(filteredHeaders)),
+    body: Option.getOrUndefined(omitBodyKeys(request.body, options.ignoreBodyKeys)),
+  };
+};
+
+/**
+ * Compute the stable request key used for cassette lookups.
+ */
+export const buildRequestKey = (
+  request: VcrRequest,
+  options: {
+    readonly ignoreHeaders?: ReadonlyArray<string>;
+    readonly ignoreBodyKeys?: ReadonlyArray<string>;
+  },
+): Effect.Effect<string> =>
+  Effect.sync(() => {
+    const sanitized = sanitizeRequest(request, {
+      ignoreHeaders: options.ignoreHeaders,
+      ignoreBodyKeys: options.ignoreBodyKeys,
+    });
+    const key = stableStringify({
+      method: sanitized.method.toUpperCase(),
+      url: sanitized.url,
+      headers: sanitized.headers ?? {},
+      body: sanitized.body ?? "",
+    });
+    if (!key) {
+      throw new Error("Failed to build VCR request key");
+    }
+    return key;
+  });
+
+/**
+ * Remove sensitive request data before persisting to a cassette.
+ */
+export const redactRequest = (
+  request: VcrRequest,
+  options: {
+    readonly redactHeaders?: ReadonlyArray<string>;
+    readonly redactBodyKeys?: ReadonlyArray<string>;
+  },
+): VcrRequest => ({
+  ...request,
+  headers: Option.getOrUndefined(omitHeaderKeys(request.headers, options.redactHeaders)),
+  body: Option.getOrUndefined(omitBodyKeys(request.body, options.redactBodyKeys)),
+});
+
+/**
+ * Remove sensitive response data before persisting to a cassette.
+ */
+export const redactResponse = (
+  response: VcrResponse,
+  options: {
+    readonly redactHeaders?: ReadonlyArray<string>;
+    readonly redactBodyKeys?: ReadonlyArray<string>;
+  },
+): VcrResponse => ({
+  ...response,
+  headers: Option.getOrUndefined(omitHeaderKeys(response.headers, options.redactHeaders)),
+  body: Option.getOrElse(omitBodyKeys(response.body, options.redactBodyKeys), () => response.body),
+});

package/src/types.ts

@@ -0,0 +1,81 @@
+/**
+ * VCR operating mode.
+ * - record: always call the live client and persist.
+ * - replay: serve only from cassette, fail if missing.
+ * - auto: replay if cassette exists, otherwise record (fail in CI).
+ */
+export type VcrMode = "record" | "replay" | "auto";
+
+/**
+ * Serialized request shape stored in a cassette.
+ */
+export type VcrRequest = {
+  readonly method: string;
+  readonly url: string;
+  readonly headers?: Record<string, string>;
+  readonly body?: string;
+};
+
+/**
+ * Serialized response shape stored in a cassette.
+ */
+export type VcrResponse = {
+  readonly status: number;
+  readonly body: string;
+  readonly headers?: Record<string, string>;
+};
+
+/**
+ * A single request/response pair keyed in the cassette.
+ */
+export type VcrEntry = {
+  readonly request: VcrRequest;
+  readonly response: VcrResponse;
+};
+
+/**
+ * Cassette file format.
+ */
+export type Cassette = {
+  readonly meta: {
+    readonly createdAt: string;
+    readonly version: string;
+  };
+  readonly entries: Record<string, VcrEntry>;
+};
+
+/**
+ * Cassette file format with multiple exports.
+ */
+export type CassetteFile = {
+  readonly exports: Record<string, Cassette>;
+};
+
+/**
+ * VCR configuration.
+ */
+export type Configuration = {
+  readonly vcrName?: string;
+  readonly cassetteName?: string;
+  readonly mode?: VcrMode;
+  /**
+   * Remove sensitive data before writing to disk.
+   */
+  readonly redact?: {
+    readonly requestHeaders?: ReadonlyArray<string>;
+    readonly responseHeaders?: ReadonlyArray<string>;
+    readonly requestBodyKeys?: ReadonlyArray<string>;
+    readonly responseBodyKeys?: ReadonlyArray<string>;
+  };
+  /**
+   * Ignore fields when computing the request key for replay matching.
+   */
+  readonly matchIgnore?: {
+    readonly requestHeaders?: ReadonlyArray<string>;
+    readonly requestBodyKeys?: ReadonlyArray<string>;
+  };
+  /**
+   * Custom matcher to override key-based lookup.
+   */
+  readonly match?: (request: VcrRequest, entry: VcrEntry) => boolean;
+};