@avivbenhamo/polly-kit 0.1.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 avivbenhamo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,8 +1,19 @@
 # @avivbenhamo/polly-kit
 
-Record a Vite app's real HTTP traffic to HAR files, then replay it so the app runs with no
-backends. Wraps Polly.JS, the recording store and the [polly-studio](https://www.npmjs.com/package/@avivbenhamo/polly-studio)
-editor into one plugin and one function.
+Record an app's real HTTP traffic to HAR files, then replay it so the app runs with no
+backends. Polly.JS, the recording store and the HAR editor in one package — one install, no
+companion to keep in step.
+
+Entry points:
+
+| | |
+|---|---|
+| `@avivbenhamo/polly-kit` | a Vite app, in the browser |
+| [`@avivbenhamo/polly-kit/node`](#non-browser-apps) | a Node process — NestJS, a service, a CLI. `http(s)` **and** the built-in `fetch` |
+| [`@avivbenhamo/polly-kit/studio`](#the-editor) | the editor's handler and HAR API, to mount anywhere |
+| `@avivbenhamo/polly-kit/studio/browser` | the editor for a browser app with no server at all |
+| `@avivbenhamo/polly-kit/vite` | the Vite plugin |
+| `@avivbenhamo/polly-kit/store` | the recording store as bare connect middleware |
 
 Nothing in here knows a hostname. You supply a policy; the package is the machinery.
 
@@ -79,6 +90,84 @@ Record once against reachable backends, then replay forever. Recordings land in
 `recordings/<recordingName>_<hash>/recording.har`, editable at **http://localhost:<port>/__polly**
 — the URL is printed on startup.
 
+## Non-browser apps
+
+`@avivbenhamo/polly-kit/node` is the same thing for a Node process — NestJS, a plain
+service, a CLI. It intercepts **both** transports: `http(s).request`/`get` (axios, got,
+Nest's `HttpModule`) and Node's built-in `fetch`.
+
+```ts
+// src/polly/mock.ts
+import {startPolly, resolveMode} from '@avivbenhamo/polly-kit/node';
+
+export const polly = startPolly({
+    mode: resolveMode(process.env.POLLY_MODE),
+    recordingName: 'my-api',
+    recordingsDir: './recordings',
+    policy: {kind: 'only', hosts: [process.env.PARTNER_API_URL]},
+});
+```
+
+```ts
+// main.ts
+import {polly} from './polly/mock';               // FIRST import
+import {pollyUi} from '@avivbenhamo/polly-kit/node';
+
+// startPolly() runs above NestFactory.create: providers can fire requests during
+// module init, and anything that goes out ahead of it is not recorded.
+const app = await NestFactory.create(AppModule);
+
+if (polly) {
+    app.use('/__polly', pollyUi({recordingsDir: './recordings'}));
+}
+
+// Polly persists on stop. A SIGKILL still loses whatever the debounce had not flushed.
+for (const signal of ['SIGINT', 'SIGTERM']) {
+    process.on(signal, async () => {
+        await polly?.stop();
+        process.exit(0);
+    });
+}
+```
+
+```powershell
+$env:POLLY_MODE='record'; npm run start:dev
+```
+
+No Vite plugin and no recording store: `persister-fs` writes the HAR straight to disk.
+Add `/recordings` to `.gitignore`.
+
+**Use `{kind: 'only'}`, not `{kind: 'all'}`.** In a browser Polly sees the page's own
+requests. In Node the adapters are process-wide: they also see your service talking to
+Postgres, Redis, the broker, its health checks and its telemetry collector. `{kind: 'all'}`
+on a server mocks the database. `startPolly` logs the policy it resolved on startup — read
+that line once.
+
+**Call `http.get(...)` off the namespace, never `import {get} from 'node:http'`.** A named
+ESM import of a builtin is bound before the adapter patches the module object, and the
+already-bound name never sees the patch. Measured on Node v22.14.0: every request completes
+against the real upstream and Polly records none of them. axios is unaffected — it resolves
+`request` off the module object at call time.
+
+**Streaming is buffered.** Polly hands an adapter a complete response, so a
+server-sent-events or long-poll endpoint will not stream in record mode. Put such hosts in
+`alwaysPassthrough`.
+
+**Compressed responses are decompressed before they are stored**, and their
+`content-encoding` and `content-length` go with the compression. The undici dispatcher sees
+bodies still gzipped — `fetch` decompresses in a layer above it — so storing them raw would
+put base64 of compressed bytes in the HAR and leave nothing editable in the editor.
+
+**Quieter than Polly's default.** `logLevel` defaults to `'error'` here, not Polly's
+`'warn'`: `@pollyjs/adapter` warns on every recorded request when
+`'navigator' in global && !navigator.onLine`, and Node has a global `navigator` with no
+`onLine` — so the claim is always false, and each one drags a full stringified request and
+config into the log. Pass `logLevel: 'warn'` to get Polly's default back.
+
+Requires Node >= 22.6. Node 24 ships undici 7, whose handler protocol differs; `fetch`
+interception then fails with a message naming your Node version rather than silently
+recording nothing.
+
 ## Policies
 
 ```ts
@@ -91,8 +180,12 @@ Hosts match by origin, so a trailing slash or a path on the value is fine — th
 in practice, and `toOrigin` reduces them. An entry that resolves to `undefined` (an env var
 that was never set) is skipped rather than throwing at startup.
 
-The app's own origin is always passed through: it serves the HMR socket, the recording store
-and every static asset, so mocking it breaks the dev server.
+**What is never mocked differs by entry point.** In the browser, the app's own origin is
+always passed through: it serves the HMR socket, the recording store and every static asset,
+so mocking it breaks the dev server. On `./node` there is no such origin, so
+`alwaysPassthrough` starts **empty** — nothing is exempt until you name it. That is deliberate:
+the adapters are process-wide, and a default that guessed which of your hosts were
+infrastructure would guess wrong quietly.
 
 **Passed-through hosts still hit the real network in `replay` mode.** That is what passthrough
 means, but it has a sharp edge: the hosts you exclude are usually auth and analytics, which are
@@ -100,6 +193,36 @@ also the least likely to be reachable from an isolated environment. Replaying of
 gives you hanging calls to exactly those while everything else replays fine — which reads as
 "Polly is broken" and isn't. For true isolation use `{kind: 'all'}` and record them too.
 
+## The editor
+
+The editor ships inside this package — there is nothing else to install. On the Vite path the
+plugin mounts it for you at `/__polly`. Anywhere else, `pollyUi()` is a bare `(req, res)`
+handler:
+
+```ts
+import {pollyUi} from '@avivbenhamo/polly-kit/studio';
+
+app.use('/__polly', pollyUi({recordingsDir: './recordings'}));
+```
+
+On a raw `http.createServer` also pass `basePath: '/__polly'`, since nothing stripped the
+prefix for you. Options: `recordingsDir` (required), `basePath`, `cwd`, and `enabled`, which
+defaults to `process.env.NODE_ENV !== 'production'`.
+
+**It answers 404, not 403, when disabled** — the same answer an unmounted path gives, rather
+than confirming something is there. Recordings hold real request and response bodies, so
+"someone mounted this and shipped it" must not become a data leak.
+
+For a browser app with no server at all, recording through Polly's
+`persister-local-storage`, `@avivbenhamo/polly-kit/studio/browser` mounts the same UI against
+that one localStorage key:
+
+```ts
+import {mountPollyStudio} from '@avivbenhamo/polly-kit/studio/browser';
+
+mountPollyStudio(document.getElementById('polly')!);
+```
+
 ## API
 
 | Export | From | What |
@@ -109,17 +232,32 @@ gives you hanging calls to exactly those while everything else replays fine —
 | `toOrigin` / `toOrigins` | `.` | The origin reduction the policy matcher uses. |
 | `pollyKit(options)` | `./vite` | The Vite plugin: recording store + studio. |
 | `recordingStore(options)` | `./store` | The store as a bare connect middleware, for mounting on something that isn't Vite. |
+| `startPolly` / `resolveMode` | `./node` | The Node entry: `http(s)` and `fetch`, HAR straight to disk. |
+| `pollyUi(options)` | `./node`, `./studio` | The editor as a bare `(req, res)` handler. Mounts on Express, Fastify, Koa, Vite or raw `http`. |
+| `FsStore` / `serializeHar` | `./studio` | The HAR file store the editor reads and writes through. |
+| `parseHar` / `findEntry` | `./studio` | Reading a HAR, with the Polly-specific quirks handled. |
+| `applyResponsePatch` / `deleteEntry` | `./studio` | Editing an entry, returning a typed `EditError` rather than throwing. |
+| `mountPollyStudio(root)` | `./studio/browser` | The editor with no server at all, against Polly's `persister-local-storage`. |
 
 `startPolly` options beyond the policy config: `mode` (required), `alwaysPassthrough`,
-`apiNamespace`, `saveDebounceMs`. `pollyKit` options: `recordingsDir`, `studioPath`,
+`apiNamespace`, `saveDebounceMs`; on `./node`, `recordingsDir` and `logLevel` instead of
+`apiNamespace`. `pollyKit` options: `recordingsDir`, `studioPath`,
 `apiNamespace`, `studio`. Change `apiNamespace` in one place and you must change it in both.
 
 ## Notes on why it is built this way
 
-**The XHR adapter, not fetch.** axios resolves its adapter as `['xhr', 'http', 'fetch']`, so in
-a browser it uses `XMLHttpRequest`. `@pollyjs/adapter-fetch` would attach cleanly and then see
-no traffic at all. `adapter-xhr` patches `window.XMLHttpRequest`, which axios picks up with no
-awareness — so no axios instance in your app needs to change.
+**In the browser: the XHR adapter, not fetch.** axios resolves its adapter as
+`['xhr', 'http', 'fetch']`, so in a browser it uses `XMLHttpRequest`. `@pollyjs/adapter-fetch`
+would attach cleanly and then see no traffic at all. `adapter-xhr` patches
+`window.XMLHttpRequest`, which axios picks up with no awareness — so no axios instance in your
+app needs to change.
+
+**On Node: two adapters, one of them ours.** `@pollyjs/adapter-node-http` patches
+`http.request`/`http.get`, which covers axios, got and Nest's `HttpModule`. It sees nothing of
+the built-in `fetch`: that is undici, which reads its dispatcher off a global symbol and opens
+a socket without going through `http.request`. Polly ships no adapter for that layer, so this
+package contains one. An `http`-only wrapper would attach cleanly and record none of your
+`fetch` traffic — silently, which is the failure this package exists to prevent.
 
 **The `global` shim.** `@pollyjs/persister-rest` reads a bare, unbound `global` at module top
 level, which throws in a browser. `startPolly`'s module imports the shim as its own first

package/dist/adapters/encoding.d.ts

@@ -0,0 +1,7 @@
+export declare function decompress(body: Buffer, contentEncoding: string | undefined): Buffer;
+/**
+ * `content-encoding` goes because the stored body is no longer encoded.
+ * `content-length` goes with it: it described the compressed bytes, and nothing
+ * recomputes it on replay.
+ */
+export declare function stripEncodingHeaders(headers: Record<string, string>): Record<string, string>;

package/dist/adapters/encoding.js

@@ -0,0 +1,46 @@
+/**
+ * The undici dispatcher sees response bodies still compressed — `fetch`
+ * decompresses in a layer above it. Measured, not assumed.
+ *
+ * Stored as-is, a gzipped JSON response is not utf8-representable, so it lands in
+ * the HAR as base64 and polly-studio shows an opaque blob. Since editing
+ * recordings is the reason polly-studio exists, the adapter decompresses at record
+ * time and drops the headers that described the compression.
+ */
+import { brotliDecompressSync, gunzipSync, inflateSync } from 'node:zlib';
+const DROPPED = new Set(['content-encoding', 'content-length']);
+export function decompress(body, contentEncoding) {
+    if (body.length === 0 || contentEncoding === undefined) {
+        return body;
+    }
+    // A comma-separated list is legal; the last applied encoding is the outermost.
+    const encoding = contentEncoding.split(',').pop()?.trim().toLowerCase();
+    try {
+        switch (encoding) {
+            case 'gzip':
+            case 'x-gzip':
+                return gunzipSync(body);
+            case 'deflate':
+                return inflateSync(body);
+            case 'br':
+                return brotliDecompressSync(body);
+            default:
+                // `identity`, or something we do not know how to undo. Leave it
+                // alone and leave its header on, so replay stays consistent.
+                return body;
+        }
+    }
+    catch {
+        // A truncated or mislabelled body is not worth failing the request over.
+        // It stays compressed, its header stays, and replay still works.
+        return body;
+    }
+}
+/**
+ * `content-encoding` goes because the stored body is no longer encoded.
+ * `content-length` goes with it: it described the compressed bytes, and nothing
+ * recomputes it on replay.
+ */
+export function stripEncodingHeaders(headers) {
+    return Object.fromEntries(Object.entries(headers).filter(([name]) => !DROPPED.has(name.toLowerCase())));
+}

package/dist/adapters/undici.d.ts

@@ -0,0 +1,36 @@
+/**
+ * A Polly adapter for Node's built-in `fetch`.
+ *
+ * `@pollyjs/adapter-node-http` patches `http.request`/`http.get` on the module
+ * object, which covers axios, got, node-fetch and Nest's HttpModule. It does not
+ * cover `fetch`: that is undici, which reads its dispatcher off a well-known
+ * global symbol and opens a socket without ever calling `http.request`. Polly
+ * ships no adapter for that layer, so this is it.
+ *
+ * The interception is ported from `mock-env/src/adapters/undici.ts`, where every
+ * detail below was measured on Node 22.14 rather than read off a doc. What is new
+ * here is the mapping onto Polly's four hooks.
+ */
+import Adapter from '@pollyjs/adapter';
+export default class UndiciAdapter extends Adapter {
+    /**
+     * A getter, not a static field. `@pollyjs/adapter` defines `id` as a static
+     * getter that asserts, and its declaration types it as a readonly property —
+     * so a field assignment compiles and then dies at import time with "Cannot set
+     * property id of class Adapter which has only a getter". The cast is for the
+     * declaration; the getter is what the runtime requires.
+     */
+    static get id(): string;
+    private previous;
+    onConnect(): void;
+    onDisconnect(): void;
+    /**
+     * Everything is wrapped. An escaped rejection here means the app's `fetch()`
+     * never settles — no response, no error, just a hang.
+     */
+    private dispatch;
+    /** Record and passthrough: delegate to the dispatcher we displaced. */
+    onFetchResponse(pollyRequest: never): Promise<never>;
+    /** Deliver whatever Polly settled on to the caller's handler. */
+    onRespond(pollyRequest: never, error?: Error): Promise<void>;
+}

package/dist/adapters/undici.js

@@ -0,0 +1,231 @@
+/**
+ * A Polly adapter for Node's built-in `fetch`.
+ *
+ * `@pollyjs/adapter-node-http` patches `http.request`/`http.get` on the module
+ * object, which covers axios, got, node-fetch and Nest's HttpModule. It does not
+ * cover `fetch`: that is undici, which reads its dispatcher off a well-known
+ * global symbol and opens a socket without ever calling `http.request`. Polly
+ * ships no adapter for that layer, so this is it.
+ *
+ * The interception is ported from `mock-env/src/adapters/undici.ts`, where every
+ * detail below was measured on Node 22.14 rather than read off a doc. What is new
+ * here is the mapping onto Polly's four hooks.
+ */
+import Adapter from '@pollyjs/adapter';
+import { decompress, stripEncodingHeaders } from './encoding.js';
+const GLOBAL_DISPATCHER = Symbol.for('undici.globalDispatcher.1');
+export default class UndiciAdapter extends Adapter {
+    /**
+     * A getter, not a static field. `@pollyjs/adapter` defines `id` as a static
+     * getter that asserts, and its declaration types it as a readonly property —
+     * so a field assignment compiles and then dies at import time with "Cannot set
+     * property id of class Adapter which has only a getter". The cast is for the
+     * declaration; the getter is what the runtime requires.
+     */
+    static get id() {
+        return 'undici';
+    }
+    onConnect() {
+        const holder = globalThis;
+        this.previous = holder[GLOBAL_DISPATCHER];
+        const adapter = {
+            dispatch: (opts, handler) => {
+                if (typeof handler.onHeaders !== 'function') {
+                    // Node 24 ships undici 7, whose handler protocol differs. Fail
+                    // by name: the alternative is recording nothing, silently.
+                    handler.onError(new Error(`polly-kit: this Node build (${process.version}) uses an undici handler ` +
+                        'protocol polly-kit does not support. Node >=22.6 with undici 6 is required.'));
+                    return false;
+                }
+                void this.dispatch(opts, handler);
+                return true;
+            },
+            close: async () => { },
+            destroy: async () => { },
+        };
+        holder[GLOBAL_DISPATCHER] = adapter;
+    }
+    onDisconnect() {
+        const holder = globalThis;
+        holder[GLOBAL_DISPATCHER] = this.previous;
+    }
+    /**
+     * Everything is wrapped. An escaped rejection here means the app's `fetch()`
+     * never settles — no response, no error, just a hang.
+     */
+    async dispatch(opts, handler) {
+        try {
+            const body = await drain(opts.body);
+            await this.handleRequest({
+                url: new URL(opts.path, String(opts.origin)).href,
+                method: (opts.method ?? 'GET').toUpperCase(),
+                headers: normalizeHeaders(opts.headers),
+                body: body === null ? undefined : body.toString('utf8'),
+                requestArguments: { opts, handler, body },
+            });
+        }
+        catch (error) {
+            handler.onError(error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+    /** Record and passthrough: delegate to the dispatcher we displaced. */
+    async onFetchResponse(pollyRequest) {
+        const { opts, body } = pollyRequest.requestArguments;
+        const previous = this.previous;
+        if (previous === undefined) {
+            throw new Error('polly-kit: record mode found no underlying dispatcher to call');
+        }
+        return new Promise((resolve, reject) => {
+            const chunks = [];
+            let statusCode = 0;
+            let headers = {};
+            // The original body was consumed to build the match key, so hand over
+            // the bytes we drained.
+            previous.dispatch({ ...opts, body }, {
+                onConnect: () => { },
+                onError: reject,
+                onHeaders(status, rawHeaders) {
+                    statusCode = status;
+                    headers = fromRawHeaders(rawHeaders);
+                    return true;
+                },
+                onData(chunk) {
+                    chunks.push(Buffer.from(chunk));
+                    return true;
+                },
+                onComplete: () => {
+                    const raw = Buffer.concat(chunks);
+                    const decoded = decompress(raw, headers['content-encoding']);
+                    const isBinary = !isUtf8Representable(decoded);
+                    resolve({
+                        statusCode,
+                        // Headers are stripped only when something was actually
+                        // decompressed, so an `identity` or unrecognised encoding
+                        // keeps its headers and replays unchanged.
+                        headers: decoded === raw ? headers : stripEncodingHeaders(headers),
+                        encoding: isBinary ? 'base64' : undefined,
+                        body: decoded.toString(isBinary ? 'base64' : 'utf8'),
+                    });
+                },
+            });
+        });
+    }
+    /** Deliver whatever Polly settled on to the caller's handler. */
+    async onRespond(pollyRequest, error) {
+        const request = pollyRequest;
+        const { handler } = request.requestArguments;
+        if (error) {
+            handler.onError(error);
+            return;
+        }
+        if (request.aborted === true) {
+            handler.onError(new Error('polly-kit: request aborted'));
+            return;
+        }
+        const { statusCode = 0, headers = {}, body, encoding } = request.response ?? {};
+        const buffer = body === undefined || body === null
+            ? Buffer.alloc(0)
+            : Buffer.from(body, encoding === 'base64' ? 'base64' : 'utf8');
+        handler.onConnect(() => { });
+        handler.onHeaders(statusCode, toRawHeaders(withRealLength(headers, buffer)), () => { }, '');
+        if (buffer.length > 0) {
+            handler.onData(buffer);
+        }
+        handler.onComplete([]);
+    }
+}
+/**
+ * `content-length`, corrected to the body actually being delivered.
+ *
+ * A recording is meant to be edited in polly-studio — that is why the editor
+ * exists — and an edited body no longer matches the length recorded with it.
+ * undici's dispatcher layer sits below HTTP framing so it does not enforce the
+ * header, which is what makes this quiet: the body arrives intact and the header
+ * lies about it. Anything downstream that trusts `content-length` then reads a
+ * wrong value.
+ *
+ * Only rewritten when the header is already there. A response recorded with
+ * `transfer-encoding: chunked` has no length, and inventing one alongside that
+ * header would contradict it.
+ */
+function withRealLength(headers, body) {
+    const name = Object.keys(headers).find((key) => key.toLowerCase() === 'content-length');
+    if (name === undefined) {
+        return headers;
+    }
+    return { ...headers, [name]: String(body.length) };
+}
+/**
+ * Polly's own check, reimplemented rather than imported: `@pollyjs/utils` ships no
+ * declaration for `isBufferUtf8Representable`, and this is the whole of it.
+ */
+function isUtf8Representable(buffer) {
+    return Buffer.compare(Buffer.from(buffer.toString('utf8'), 'utf8'), buffer) === 0;
+}
+function normalizeHeaders(headers) {
+    const out = {};
+    if (headers === undefined) {
+        return out;
+    }
+    if (Array.isArray(headers)) {
+        for (let i = 0; i + 1 < headers.length; i += 2) {
+            const name = headers[i];
+            const value = headers[i + 1];
+            if (name !== undefined && value !== undefined) {
+                out[name.toLowerCase()] = value;
+            }
+        }
+        return out;
+    }
+    for (const [name, value] of Object.entries(headers)) {
+        out[name.toLowerCase()] = String(value);
+    }
+    return out;
+}
+/** `rawHeaders` is flat, alternating name/value Buffers. */
+function fromRawHeaders(raw) {
+    const out = {};
+    for (let i = 0; i + 1 < raw.length; i += 2) {
+        const name = raw[i];
+        const value = raw[i + 1];
+        if (name !== undefined && value !== undefined) {
+            out[name.toString('latin1').toLowerCase()] = value.toString('latin1');
+        }
+    }
+    return out;
+}
+/**
+ * HTTP header values are latin1 by spec, and `fromRawHeaders` decoded them as
+ * latin1 on the way in. Encoding with the default utf8 here corrupts every byte
+ * >= 0x80 on replay: the two sides must match.
+ */
+function toRawHeaders(headers) {
+    const raw = [];
+    for (const [name, value] of Object.entries(headers)) {
+        raw.push(Buffer.from(name, 'latin1'), Buffer.from(String(value), 'latin1'));
+    }
+    return raw;
+}
+/** `fetch` always hands the dispatcher an async iterable, never a string. */
+async function drain(body) {
+    if (body === null || body === undefined) {
+        return null;
+    }
+    if (typeof body === 'string') {
+        return Buffer.from(body);
+    }
+    if (Buffer.isBuffer(body)) {
+        return body;
+    }
+    if (body instanceof Uint8Array) {
+        return Buffer.from(body);
+    }
+    if (typeof body[Symbol.asyncIterator] === 'function') {
+        const chunks = [];
+        for await (const chunk of body) {
+            chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : Buffer.from(chunk));
+        }
+        return Buffer.concat(chunks);
+    }
+    return null;
+}

package/dist/browser.js

@@ -22,6 +22,7 @@ import './global-shim.js';
 import { Polly } from '@pollyjs/core';
 import XHRAdapter from '@pollyjs/adapter-xhr';
 import RestPersister from '@pollyjs/persister-rest';
+import { KEEP_UNUSED_REQUESTS, POLLY_DEFAULTS } from './defaults.js';
 import { applyPolicy } from './policy.js';
 export { toOrigin, toOrigins } from './policy.js';
 const MODES = ['off', 'record', 'replay'];
@@ -72,27 +73,12 @@ export function startPolly(options) {
         adapters: ['xhr'],
         persister: 'rest',
         persisterOptions: {
-            // Without this, every save drops the entries that were not replayed
-            // this session. Exercising one screen would throw away every other
-            // screen's recording.
-            keepUnusedRequests: true,
+            keepUnusedRequests: KEEP_UNUSED_REQUESTS,
             rest: { host: window.location.origin, apiNamespace },
         },
-        // A replay miss must fail loudly. The default `true` quietly goes to the
-        // network and records it, which looks identical to replay working.
-        recordIfMissing: false,
-        // A 401 or a 500 is worth having on disk. The default drops it, and the
-        // gap only surfaces later as a replay miss with no obvious cause.
-        recordFailedRequests: true,
-        matchRequestsBy: {
-            // Screens refetch, and the same request is issued many times. With
-            // `order: true` the second one looks for a second recording and misses.
-            order: false,
-            // Apps attach bearer tokens and per-session headers. Matching on
-            // headers would make a recording valid only for the session that
-            // produced it.
-            headers: false,
-        },
+        // The opinionated defaults, shared with the Node entry so the two cannot
+        // drift. Each one's reasoning is in defaults.ts.
+        ...POLLY_DEFAULTS,
     });
     applyPolicy(polly.server, { policy, alwaysPassthrough });
     if (mode === 'record') {

package/dist/defaults.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The Polly options that differ from Polly's own defaults, shared by the browser
+ * and Node entry points.
+ *
+ * They live here because they are the package's opinion, and an opinion that
+ * holds in one runtime and not the other is a bug nobody notices: a replay miss
+ * that silently hits the network looks exactly like replay working.
+ */
+export declare const POLLY_DEFAULTS: {
+    /**
+     * A replay miss must fail loudly. Polly's default `true` quietly goes to the
+     * network and records what comes back, which is indistinguishable from
+     * replay working.
+     */
+    readonly recordIfMissing: false;
+    /**
+     * A 401 or a 500 is worth having on disk. The default drops it, and the gap
+     * only surfaces later as a replay miss with no obvious cause.
+     */
+    readonly recordFailedRequests: true;
+    readonly matchRequestsBy: {
+        /**
+         * Screens refetch and clients retry, so the same request is issued many
+         * times. With `order: true` the second one looks for a second recording
+         * and misses.
+         */
+        readonly order: false;
+        /**
+         * Apps attach bearer tokens and per-session headers. Matching on headers
+         * would make a recording valid only for the session that produced it.
+         */
+        readonly headers: false;
+    };
+};
+/**
+ * Without this, every save drops the entries that were not replayed this
+ * session. Exercising one screen would throw away every other screen's
+ * recording.
+ */
+export declare const KEEP_UNUSED_REQUESTS = true;

package/dist/defaults.js

@@ -0,0 +1,40 @@
+/**
+ * The Polly options that differ from Polly's own defaults, shared by the browser
+ * and Node entry points.
+ *
+ * They live here because they are the package's opinion, and an opinion that
+ * holds in one runtime and not the other is a bug nobody notices: a replay miss
+ * that silently hits the network looks exactly like replay working.
+ */
+export const POLLY_DEFAULTS = {
+    /**
+     * A replay miss must fail loudly. Polly's default `true` quietly goes to the
+     * network and records what comes back, which is indistinguishable from
+     * replay working.
+     */
+    recordIfMissing: false,
+    /**
+     * A 401 or a 500 is worth having on disk. The default drops it, and the gap
+     * only surfaces later as a replay miss with no obvious cause.
+     */
+    recordFailedRequests: true,
+    matchRequestsBy: {
+        /**
+         * Screens refetch and clients retry, so the same request is issued many
+         * times. With `order: true` the second one looks for a second recording
+         * and misses.
+         */
+        order: false,
+        /**
+         * Apps attach bearer tokens and per-session headers. Matching on headers
+         * would make a recording valid only for the session that produced it.
+         */
+        headers: false,
+    },
+};
+/**
+ * Without this, every save drops the entries that were not replayed this
+ * session. Exercising one screen would throw away every other screen's
+ * recording.
+ */
+export const KEEP_UNUSED_REQUESTS = true;