@specific.dev/spectest 0.99.0 → 0.101.0

package/dist/components/index.d.ts

@@ -13,6 +13,6 @@ export { github, type GithubOptions } from "./github.js";
 export { apple, type AppleOptions } from "./apple.js";
 export { microsoft, type MicrosoftOptions } from "./microsoft.js";
 export { okta, type OktaOptions } from "./okta.js";
-export { replayFake, type ReplayFakeOptions, type ReplayMatch, type InjectRule, type InjectMatch, type StringMatch, type SignConfig, type AwsSigV4Sign, type ReplayHelpers, type ReplaySummary, type Cassette, type CassetteInteraction, type CassetteRequest, type CassetteResponse, type CassetteState, } from "./replayFake.js";
+export { replayFake, type ReplayFakeOptions, type ReplayFakeContext, type ReplayHandler, type ReplayKey, type ReplayRequest, type MatchKey, type JsonValue, type InjectRule, type InjectMatch, type StringMatch, type SignConfig, type AwsSigV4Sign, type ReplayHelpers, type ReplaySummary, type Cassette, type CassetteInteraction, type CassetteRequest, type CassetteResponse, type CassetteState, } from "./replayFake.js";
 export { electron, type ElectronOptions } from "./electron.js";
 export { android, type AndroidOptions } from "./android.js";

package/dist/components/replay-key.d.ts

@@ -0,0 +1,27 @@
+import type { CassetteRequest } from "./replayFake.js";
+export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+/** Identity content. Objects compare independently of property order; arrays
+ *  preserve order. Bytes are distinct from strings, arrays, and objects. */
+export type MatchKey = null | boolean | number | string | Uint8Array | readonly MatchKey[] | {
+    readonly [key: string]: MatchKey;
+};
+/** A buffered request view shared by incoming and recorded requests.
+ *  Headers are lowercase and exclude credentials. Recorded values may be
+ *  redacted; choose identity fields that survive recording. */
+export interface ReplayRequest {
+    readonly method: string;
+    readonly path: string;
+    readonly query: Readonly<Record<string, readonly string[]>>;
+    readonly headers: Readonly<Record<string, string>>;
+    /** Decode UTF-8, throwing on invalid text. */
+    text(): string;
+    /** Parse JSON. The type parameter is not runtime validation. */
+    json<T = JsonValue>(): T;
+    /** Return an independent copy of the body bytes. */
+    bytes(): Uint8Array;
+}
+export type ReplayKey = (request: ReplayRequest) => MatchKey;
+/** Internal only; the SDK exports the request/key types, not this function. */
+export declare function replaySignature(request: CassetteRequest, key?: ReplayKey): string;

package/dist/components/replay-key.js

@@ -0,0 +1,96 @@
+import { createHash } from "node:crypto";
+/** Stream a typed, length-delimited canonical representation into the hash.
+ *  Never call toJSON: unsupported values must fail rather than silently lose
+ *  identity fields. In particular, an async callback must not become `{}`. */
+function hashKey(key) {
+    const hash = createHash("sha256");
+    const ancestors = new Set();
+    const visit = (value) => {
+        if (value === null || typeof value === "boolean" || typeof value === "string") {
+            hash.update(JSON.stringify(value));
+            return;
+        }
+        if (typeof value === "number" && Number.isFinite(value)) {
+            hash.update(JSON.stringify(value));
+            return;
+        }
+        if (value instanceof Uint8Array) {
+            hash.update(`bytes:${value.byteLength}:`);
+            hash.update(value);
+            return;
+        }
+        if (value instanceof Promise) {
+            // Report the invalid callback synchronously without leaving a rejected
+            // async callback to become an unrelated unhandled-rejection failure.
+            void value.catch(() => { });
+            throw new Error("key callbacks must be synchronous, not return promises");
+        }
+        if (typeof value !== "object" || value === null) {
+            throw new Error("key must contain only JSON values or Uint8Array bytes (no undefined, functions, or non-finite numbers)");
+        }
+        if (ancestors.has(value))
+            throw new Error("key must not contain cycles");
+        if (Object.getOwnPropertySymbols(value).length > 0) {
+            throw new Error("key must not contain symbol properties");
+        }
+        ancestors.add(value);
+        if (Array.isArray(value)) {
+            if (Object.keys(value).length !== value.length) {
+                throw new Error("key arrays must be dense and have no extra properties");
+            }
+            hash.update("[");
+            for (let i = 0; i < value.length; i++) {
+                if (!Object.hasOwn(value, i))
+                    throw new Error("key arrays must be dense");
+                visit(value[i]);
+                hash.update(",");
+            }
+            hash.update("]");
+        }
+        else {
+            const proto = Object.getPrototypeOf(value);
+            if (proto !== Object.prototype && proto !== null) {
+                throw new Error("key must use plain objects, not promises, dates, maps, or class instances; callbacks must be synchronous");
+            }
+            hash.update("{");
+            for (const name of Object.keys(value).sort()) {
+                hash.update(JSON.stringify(name));
+                hash.update(":");
+                visit(value[name]);
+                hash.update(",");
+            }
+            hash.update("}");
+        }
+        ancestors.delete(value);
+    };
+    visit(key);
+    return hash.digest("hex");
+}
+function bodyBytes(request) {
+    return Buffer.from(request.body ?? "", request.bodyEncoding === "base64" ? "base64" : "utf8");
+}
+function requestView(request) {
+    let bytes;
+    let text;
+    const readBytes = () => bytes ??= bodyBytes(request);
+    const readText = () => text ??= new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(readBytes());
+    const query = Object.fromEntries(Object.entries(request.query).map(([k, v]) => [k, Object.freeze([...v])]));
+    return Object.freeze({
+        method: request.method.toUpperCase(),
+        path: request.path,
+        query: Object.freeze(query),
+        headers: Object.freeze({ ...request.headers }),
+        text: readText,
+        json: () => JSON.parse(readText()),
+        bytes: () => Uint8Array.from(readBytes()),
+    });
+}
+/** Internal only; the SDK exports the request/key types, not this function. */
+export function replaySignature(request, key) {
+    if (key)
+        return hashKey(key(requestView(request)));
+    // Existing cassettes retain the original byte hash even when their stored
+    // text was redacted. Older/hand-written cassettes may only have the body.
+    const body = request.bodyHash ?? `sha256:${createHash("sha256").update(bodyBytes(request)).digest("hex")}`;
+    return hashKey({ method: request.method.toUpperCase(), path: request.path, query: request.query, body });
+}

package/dist/components/replayFake.d.ts

@@ -1,18 +1,6 @@
-import type { FakeDefinition } from "../index.js";
-/** Which parts of a request define a match against the cassette. */
-export interface ReplayMatch {
-    /** Match on HTTP method. Default `true`. */
-    method?: boolean;
-    /** Match on path (no query). Default `true`. */
-    path?: boolean;
-    /** Match on normalized query string. Default `true`. */
-    query?: boolean;
-    /** Match on body: `true` = exact decoded body, `"hash"` = sha256 only.
-     *  Default off. */
-    body?: boolean | "hash";
-    /** Header names (lowercase) to include in the match. Default none. */
-    headers?: string[];
-}
+import type { FakeContext, FakeDefinition } from "../index.js";
+import { type ReplayKey } from "./replay-key.js";
+export type { JsonValue, MatchKey, ReplayRequest, ReplayKey } from "./replay-key.js";
 /** Match one request dimension. A bare string is an exact match; the
  *  object forms cover prefix and regex matching. */
 export type StringMatch = string | {
@@ -66,7 +54,15 @@ export interface AwsSigV4Sign {
     sessionToken?: string;
 }
 export type SignConfig = AwsSigV4Sign;
-export interface ReplayFakeOptions {
+/** A normal fake context with explicit delegation to recording/replay. */
+export interface ReplayFakeContext extends FakeContext {
+    /** Record against the real upstream in record mode, or consume a matching
+     *  cassette interaction in replay mode. A replay miss returns 599; there
+     *  is no fallback to scripted logic. Inspect a body's clone before calling. */
+    replay(request: Request): Promise<Response>;
+}
+export type ReplayHandler<S> = (request: Request, state: S, ctx: ReplayFakeContext) => Response | Promise<Response>;
+export interface ReplayFakeOptions<S = undefined, H extends Record<string, unknown> = {}> {
     /** Stable name — the `ctx.fakes` key. */
     name: string;
     /** The REAL host to fake, e.g. `"api.stripe.com"`. The fake answers for
@@ -75,8 +71,12 @@ export interface ReplayFakeOptions {
      *  resolved via an external DNS server — see the module header). Your
      *  app points at this real host directly; no separate stand-in. */
     host: string;
-    /** What defines a request match. Default `{ method, path, query }`. */
-    match?: ReplayMatch;
+    /** Complete request identity. Default: method, path, normalized query,
+     *  and exact body bytes. The same synchronous, deterministic callback runs
+     *  on recorded and incoming requests. Return JSON values and/or Uint8Array
+     *  bytes; objects compare independently of property order. No implicit
+     *  matching dimensions or fallback apply when a key is supplied. */
+    key?: ReplayKey;
     /** Per-fake credential brokering. Rules are evaluated in
      *  order; the first whose `match` matches wins (a rule without `match`
      *  matches everything and shadows later rules). Applied at the
@@ -95,13 +95,27 @@ export interface ReplayFakeOptions {
     /** `"auto"` (default) records under eval and replays under test;
      *  `"record"` / `"replay"` force a mode. */
     mode?: "auto" | "record" | "replay";
+    /** Custom state, with the same lifecycle as a normal fake's state. Kept
+     *  separate from cassette internals; helpers and handler see only S. */
+    state?: () => S | Promise<S>;
+    /** Custom helpers exposed alongside replay/dump/recorded/count. Those
+     *  names are reserved. Loading a cassette does not change custom state. */
+    helpers?: (args: {
+        name: string;
+        state: S;
+        ctx: FakeContext;
+    }) => H | Promise<H>;
+    /** Decide whether to answer in code or call ctx.replay(request). Without
+     *  a handler, every request delegates. Only delegated requests record. */
+    handler?: ReplayHandler<S>;
 }
 export interface CassetteRequest {
     method: string;
     path: string;
     /** Normalized: keys + repeated values sorted, so matching is order-free. */
     query: Record<string, string[]>;
-    /** Matched/readable header subset only — never `authorization`/`cookie`. */
+    /** Captured non-sensitive headers — never `authorization`/`cookie`.
+     *  Older cassettes may contain only content-type and selected headers. */
     headers: Record<string, string>;
     bodyHash?: string;
     /** Request body (omitted when empty): decoded + redacted UTF-8 text, or
@@ -131,6 +145,8 @@ export interface Cassette {
 /** Forked-per-test state for one replay fake. */
 export interface CassetteState {
     cassette: Cassette;
+    /** Complete signature → cassette interaction indexes, in cassette order. */
+    index: Map<string, number[]>;
     /** Per-match-signature replay cursor (call-order sequencing). */
     cursor: Map<string, number>;
     /** Interactions captured this record session. */
@@ -149,8 +165,9 @@ export interface ReplaySummary {
     interactions: number;
 }
 export interface ReplayHelpers extends Record<string, unknown> {
-    /** Load a cassette into THIS fork's replay set and replay from it,
+    /** Load a cassette into THIS fork's replay set for delegated requests,
      *  replacing whatever was loaded before and resetting the replay cursor.
+     *  Does not change custom state or bypass a custom handler.
      *  Cassettes are NOT auto-loaded — call this at the top of a test. Pass a
      *  path relative to `spectest/tests/` (e.g. `"recordings/stripe.json"`; it
      *  must stay under `spectest/tests/`) or a cassette object; a missing file
@@ -166,4 +183,6 @@ export interface ReplayHelpers extends Record<string, unknown> {
     /** Count of interactions captured this record session. */
     count(): number;
 }
-export declare function replayFake(opts: ReplayFakeOptions): FakeDefinition<CassetteState, ReplayHelpers>;
+export declare function replayFake<S = undefined, H extends Record<string, unknown> = {}>(opts: ReplayFakeOptions<S, H>): FakeDefinition<CassetteState & {
+    custom: S;
+}, ReplayHelpers & H>;

package/dist/components/replayFake.js

@@ -14,7 +14,7 @@
 //   - REPLAY (hermetic): the request is matched against the cassette the
 //     test EXPLICITLY loaded (`ctx.fakes.<name>.replay(file)`) and the
 //     recorded response is returned. No network. Nothing is auto-loaded:
-//     a test that loads no cassette gets a fail-loud 599 on every request.
+//     a test that loads no cassette gets a fail-loud 599 on every delegated request.
 //     This is what runs under `spectest test`.
 //   - RECORD (MITM): the request is forwarded to the REAL host and the
 //     request/response pair is captured (decoded, redacted), and the real
@@ -35,6 +35,8 @@
 // recorder (a `spectest test` case), false in eval/manual. So `auto`
 // (the default) replays under test and records during manual use — no new
 // control-plane mode flag. `mode: "record" | "replay"` overrides it.
+// An optional custom handler can return scripted responses or explicitly
+// delegate with ctx.replay(request). Only delegated traffic uses this engine.
 //
 // Credential brokering (per-fake): `inject` rules set
 // headers on the egress forward — overwriting whatever the app sent — so
@@ -62,6 +64,7 @@ import { brotliDecompressSync, gunzipSync, inflateSync } from "node:zlib";
 import * as dnsPacket from "dns-packet";
 import { isRecording } from "../recorder.js";
 import { getRecordSecret } from "../record-secrets.js";
+import { replaySignature } from "./replay-key.js";
 import { inferSigV4Scope, signAwsV4Request, } from "../aws-sigv4.js";
 // ────────────────────────────────────────────────────────────────────────
 // Helpers
@@ -71,7 +74,9 @@ const SENSITIVE_HEADERS = new Set([
     "cookie",
     "set-cookie",
     "proxy-authorization",
+    "api-key",
     "x-api-key",
+    "x-goog-api-key",
     "x-amz-security-token",
 ]);
 /** Hop-by-hop + body-framing headers never forwarded / never replayed
@@ -97,15 +102,6 @@ const STRIP_FORWARD_HEADERS = new Set([
  *  resolver (which points the faked host back at the daemon). */
 const EXTERNAL_DNS = process.env.SPECTEST_UPSTREAM_DNS ?? "1.1.1.1";
 const EXTERNAL_DNS_PORT = Number(process.env.SPECTEST_UPSTREAM_PORT ?? "53");
-function defaultMatch(m) {
-    return {
-        method: m?.method ?? true,
-        path: m?.path ?? true,
-        query: m?.query ?? true,
-        body: m?.body,
-        headers: m?.headers,
-    };
-}
 /** SigV4 puts per-request signing params (`X-Amz-Signature`, `X-Amz-Date`, …)
  *  in the query for presigned URLs — they change every call and would poison
  *  query matching, so they're dropped from both the match key and the forward
@@ -144,31 +140,6 @@ function recordable(headers, want) {
     }
     return out;
 }
-/** Canonical match signature for an interaction's request, used as both
- *  the replay-cursor key and the equality basis (two requests match iff
- *  their signatures are equal). Computed identically for an incoming
- *  request and a stored `CassetteRequest`. */
-function signature(req, match) {
-    const sig = {};
-    if (match.method)
-        sig.method = req.method.toUpperCase();
-    if (match.path)
-        sig.path = req.path;
-    if (match.query)
-        sig.query = req.query;
-    if (match.body === true)
-        sig.body = req.body ?? "";
-    else if (match.body === "hash")
-        sig.bodyHash = req.bodyHash ?? "";
-    if (match.headers && match.headers.length > 0) {
-        const h = {};
-        for (const name of match.headers.map((n) => n.toLowerCase()).sort()) {
-            h[name] = req.headers[name] ?? "";
-        }
-        sig.headers = h;
-    }
-    return JSON.stringify(sig);
-}
 /** The project's `spectest/tests/` dir — cassettes live alongside the
  *  tests, and a `replay(path)` argument is a path relative to here. Keeping
  *  them under `tests/` means re-recording is picked up on the next run with
@@ -190,7 +161,7 @@ function coerceCassette(parsed, name, host) {
         version: 1,
         fake: parsed.fake ?? name,
         host: parsed.host ?? host,
-        interactions: parsed.interactions,
+        interactions: structuredClone(parsed.interactions),
     };
 }
 /** Read a cassette by its path relative to `spectest/tests/` (e.g.
@@ -218,7 +189,7 @@ function readCassetteFile(name, file, host) {
 /** Decode response bytes to a string, falling back to base64 for binary. */
 function decodeBody(bytes) {
     try {
-        const text = new TextDecoder("utf8", { fatal: true }).decode(bytes);
+        const text = new TextDecoder("utf8", { fatal: true, ignoreBOM: true }).decode(bytes);
         return { body: text, bodyEncoding: "utf8" };
     }
     catch {
@@ -434,7 +405,12 @@ export function replayFake(opts) {
         throw new Error(`replayFake(${opts.name}): "host" (the real hostname) is required`);
     }
     const host = opts.host.toLowerCase().replace(/^https?:\/\//, "").replace(/\/.*$/, "");
-    const match = defaultMatch(opts.match);
+    if ("match" in opts) {
+        throw new Error(`replayFake(${opts.name}): \`match\` has been replaced by \`key(request)\`, which defines the complete request identity`);
+    }
+    if (opts.key !== undefined && typeof opts.key !== "function") {
+        throw new Error(`replayFake(${opts.name}): \`key\` must be a synchronous function`);
+    }
     const injectRules = opts.inject ?? [];
     // Refs every header template references — the control plane resolves these
     // server-side and pushes them for the environment lifetime (see the daemon's
@@ -448,19 +424,33 @@ export function replayFake(opts) {
         return isRecording() ? "replay" : "record";
     };
     // ── REPLAY ──────────────────────────────────────────────────────────
+    function signature(request, location) {
+        try {
+            return replaySignature(request, opts.key);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`replayFake(${opts.name}): invalid replay key for ${location}: ${message}`);
+        }
+    }
     function replay(reqLike, state) {
-        const sig = signature(reqLike, match);
-        const matches = [];
-        for (const it of state.cassette.interactions) {
-            if (signature(it.request, match) === sig)
-                matches.push(it);
+        let sig;
+        try {
+            sig = signature(reqLike, "incoming request");
         }
+        catch (error) {
+            return new Response(error.message + "\n", {
+                status: 599, headers: { "content-type": "text/plain" },
+            });
+        }
+        const matches = state.index.get(sig) ?? [];
         const idx = state.cursor.get(sig) ?? 0;
-        const hit = matches[idx];
+        const interactionIndex = matches[idx];
+        const hit = interactionIndex === undefined ? undefined : state.cassette.interactions[interactionIndex];
         if (!hit) {
             const body = `replayFake(${opts.name}): no cassette interaction for ` +
-                `${reqLike.method} ${reqLike.path} (matched ${matches.length}, wanted #${idx + 1}). ` +
-                `Re-record the cassette, or relax \`match\`.\n`;
+                `${reqLike.method} ${reqLike.path} (${matches.length === 0 ? "unknown key" : "exhausted key"}; matched ${matches.length}, wanted #${idx + 1}). ` +
+                `Check \`key\` or re-record the cassette.\n`;
             return new Response(body, {
                 status: 599,
                 headers: { "content-type": "text/plain" },
@@ -618,7 +608,7 @@ export function replayFake(opts) {
                 method: reqLike.method,
                 path: reqLike.path,
                 query: redactedQuery,
-                headers: reqLike.headers,
+                headers: Object.fromEntries(Object.entries(reqLike.headers).map(([k, v]) => [k, redact(v)])),
                 ...(reqLike.body !== undefined
                     ? {
                         bodyHash: reqLike.bodyHash,
@@ -656,6 +646,9 @@ export function replayFake(opts) {
     }
     // ── handler ─────────────────────────────────────────────────────────
     const handler = async (req, state, _ctx) => {
+        if (req.bodyUsed) {
+            throw new Error(`replayFake(${opts.name}): cannot delegate a consumed request body; inspect request.clone() before calling ctx.replay(request)`);
+        }
         const url = new URL(req.url);
         const bodyBytes = req.method === "GET" || req.method === "HEAD"
             ? new Uint8Array(0)
@@ -667,7 +660,7 @@ export function replayFake(opts) {
             // Strip SigV4 `x-amz-*` query params from the match key when signing —
             // presigned URLs carry a per-request signature there.
             query: normalizeQuery(url.searchParams, opts.sign !== undefined),
-            headers: recordable(req.headers, ["content-type", ...(match.headers ?? [])]),
+            headers: recordable(req.headers, [...req.headers.keys()]),
             ...(decodedBody
                 ? {
                     bodyHash: sha256Bytes(bodyBytes),
@@ -680,58 +673,89 @@ export function replayFake(opts) {
             return replay(reqLike, state);
         return record(req, url, reqLike, bodyBytes, state);
     };
+    const replayHelpers = (state) => ({
+        replay(file) {
+            let loaded;
+            let label;
+            if (file && typeof file === "object") {
+                loaded = coerceCassette(file, opts.name, host);
+                label = file.fake || "(inline)";
+            }
+            else if (typeof file === "string" && file.length > 0) {
+                label = file;
+                loaded = readCassetteFile(opts.name, file, host);
+            }
+            else {
+                throw new Error(`replayFake(${opts.name}): replay(...) needs a cassette path under spectest/tests/ ` +
+                    `(e.g. "recordings/${opts.name}.json").`);
+            }
+            // Build/validate before replacing live state: a bad key/cassette
+            // must leave the previous cassette and consumption cursors intact.
+            const index = new Map();
+            for (const [i, interaction] of loaded.interactions.entries()) {
+                const sig = signature(interaction.request, `${JSON.stringify(label)} interaction #${i + 1}`);
+                const queue = index.get(sig);
+                if (queue)
+                    queue.push(i);
+                else
+                    index.set(sig, [i]);
+            }
+            // Mutate the live state object (the handler reads the same
+            // reference); reset the cursor so replay starts from the top.
+            state.cassette = loaded;
+            state.index = index;
+            state.cursor = new Map();
+            return { cassette: label, host: loaded.host, interactions: loaded.interactions.length };
+        },
+        dump() {
+            return structuredClone({
+                version: 1,
+                fake: opts.name,
+                host,
+                interactions: [...state.cassette.interactions, ...state.recorded],
+            });
+        },
+        recorded() {
+            return structuredClone(state.recorded);
+        },
+        count() {
+            return state.recorded.length;
+        },
+    });
+    const initialState = (custom) => ({
+        cassette: emptyCassette(opts.name, host),
+        index: new Map(),
+        cursor: new Map(),
+        recorded: [],
+        dirty: false,
+        custom,
+    });
     const def = {
         name: opts.name,
-        // Fake = real: we answer for the real host on :80 and :443.
         hostnames: [host],
         secretRefs,
-        // Cassettes are NOT auto-loaded — a fork starts with an empty replay
-        // set, so a test that loads nothing fails loud (599). Tests call
-        // `replay(...)` to populate it.
-        state: () => ({
-            cassette: emptyCassette(opts.name, host),
-            cursor: new Map(),
-            recorded: [],
-            dirty: false,
-        }),
-        handler,
-        helpers: ({ state }) => ({
-            replay(file) {
-                let loaded;
-                let label;
-                if (file && typeof file === "object") {
-                    loaded = coerceCassette(file, opts.name, host);
-                    label = file.fake || "(inline)";
-                }
-                else if (typeof file === "string" && file.length > 0) {
-                    label = file;
-                    loaded = readCassetteFile(opts.name, file, host);
-                }
-                else {
-                    throw new Error(`replayFake(${opts.name}): replay(...) needs a cassette path under spectest/tests/ ` +
-                        `(e.g. "recordings/${opts.name}.json").`);
+        state: () => opts.state
+            ? Promise.resolve(opts.state()).then(initialState)
+            : initialState(undefined),
+        handler: (request, state, ctx) => opts.handler
+            ? opts.handler(request, state.custom, {
+                ...ctx,
+                replay: (delegated) => handler(delegated, state, ctx),
+            })
+            : handler(request, state, ctx),
+        helpers: ({ name, state, ctx }) => {
+            const builtins = replayHelpers(state);
+            if (!opts.helpers)
+                return builtins;
+            return Promise.resolve(opts.helpers({ name, state: state.custom, ctx })).then((custom) => {
+                for (const key of Object.keys(builtins)) {
+                    if (key in custom) {
+                        throw new Error(`replayFake(${opts.name}): custom helper ${JSON.stringify(key)} is reserved for recording/replay; choose another name`);
+                    }
                 }
-                // Mutate the live state object (the handler reads the same
-                // reference); reset the cursor so replay starts from the top.
-                state.cassette = loaded;
-                state.cursor = new Map();
-                return { cassette: label, host: loaded.host, interactions: loaded.interactions.length };
-            },
-            dump() {
-                return {
-                    version: 1,
-                    fake: opts.name,
-                    host,
-                    interactions: [...state.cassette.interactions, ...state.recorded],
-                };
-            },
-            recorded() {
-                return state.recorded.slice();
-            },
-            count() {
-                return state.recorded.length;
-            },
-        }),
+                return { ...custom, ...builtins };
+            });
+        },
     };
     return def;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.99.0",
+  "version": "0.101.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/index.ts

@@ -85,7 +85,12 @@ export { okta, type OktaOptions } from "./okta.js";
 export {
   replayFake,
   type ReplayFakeOptions,
-  type ReplayMatch,
+  type ReplayFakeContext,
+  type ReplayHandler,
+  type ReplayKey,
+  type ReplayRequest,
+  type MatchKey,
+  type JsonValue,
   type InjectRule,
   type InjectMatch,
   type StringMatch,