@avivbenhamo/polly-kit 0.1.0 → 0.5.0

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.d.ts

@@ -5,11 +5,19 @@
  * first request goes out. Import the module that calls it FIRST in your entry
  * point — see the README.
  *
- * WHY THE XHR ADAPTER. axios resolves its adapter in the order
- * `['xhr', 'http', 'fetch']`, so in a browser it uses XMLHttpRequest. The fetch
- * adapter 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 the host app needs to change.
+ * WHY BOTH ADAPTERS. A browser has two request transports and an app can use
+ * either, so covering one is covering half the app — silently, because an
+ * adapter attaches cleanly whether or not any traffic reaches it.
+ *
+ *   - `adapter-xhr` patches `window.XMLHttpRequest`. axios resolves its adapter
+ *     in the order `['xhr', 'http', 'fetch']`, so in a browser it uses XHR —
+ *     which means no axios instance in the host app needs to change.
+ *   - `adapter-fetch` patches `window.fetch`, which is what application code
+ *     written against the platform uses directly.
+ *
+ * They patch different globals and do not interact. This mirrors `./node`, which
+ * has always intercepted both of its transports (`http(s)` and `fetch`) for the
+ * same reason.
  *
  * Nothing here reads the environment. The caller resolves the mode and passes it
  * in, which is what keeps this file free of any bundler's env API.

package/dist/browser.js

@@ -5,11 +5,19 @@
  * first request goes out. Import the module that calls it FIRST in your entry
  * point — see the README.
  *
- * WHY THE XHR ADAPTER. axios resolves its adapter in the order
- * `['xhr', 'http', 'fetch']`, so in a browser it uses XMLHttpRequest. The fetch
- * adapter 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 the host app needs to change.
+ * WHY BOTH ADAPTERS. A browser has two request transports and an app can use
+ * either, so covering one is covering half the app — silently, because an
+ * adapter attaches cleanly whether or not any traffic reaches it.
+ *
+ *   - `adapter-xhr` patches `window.XMLHttpRequest`. axios resolves its adapter
+ *     in the order `['xhr', 'http', 'fetch']`, so in a browser it uses XHR —
+ *     which means no axios instance in the host app needs to change.
+ *   - `adapter-fetch` patches `window.fetch`, which is what application code
+ *     written against the platform uses directly.
+ *
+ * They patch different globals and do not interact. This mirrors `./node`, which
+ * has always intercepted both of its transports (`http(s)` and `fetch`) for the
+ * same reason.
  *
  * Nothing here reads the environment. The caller resolves the mode and passes it
  * in, which is what keeps this file free of any bundler's env API.
@@ -20,8 +28,10 @@
 // rather than in the host app so the host app cannot get the order wrong.
 import './global-shim.js';
 import { Polly } from '@pollyjs/core';
+import FetchAdapter from '@pollyjs/adapter-fetch';
 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'];
@@ -64,35 +74,21 @@ export function startPolly(options) {
     }
     if (!registered) {
         Polly.register(XHRAdapter);
+        Polly.register(FetchAdapter);
         Polly.register(RestPersister);
         registered = true;
     }
     const polly = new Polly(recordingName, {
         mode,
-        adapters: ['xhr'],
+        adapters: ['xhr', 'fetch'],
         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/cli.d.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+export declare function main(argv: string[]): Promise<number>;
+export interface StudioOptions {
+    recordingsDir: string;
+    port?: number;
+}
+export interface Studio {
+    /** The port it actually got, which is not always the one asked for. */
+    port: number;
+    close(): Promise<void>;
+}
+/**
+ * The server, without the process around it.
+ *
+ * Separate from `main` because stopping it has to be something a caller does,
+ * not something a signal does: `process.once('SIGINT')` listeners are global,
+ * so a second studio started in the same process would be stopped by the first
+ * one's Ctrl-C. That is only ever a test, but it is also the shape anything
+ * embedding this would want.
+ */
+export declare function startStudio(options: StudioOptions): Promise<Studio>;

package/dist/cli.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+/**
+ * The studio, served on its own, for a checkout with no app running.
+ *
+ * The mounted form stays the default and is the better one when there *is* a dev
+ * server: `app.use('/__polly', pollyUi(...))` — or the Vite plugin, which does
+ * it for you — costs no second process, no second port and no CORS, and it goes
+ * away when the dev server does.
+ *
+ * This exists for the times there is no dev server to mount on. Reviewing the
+ * recordings in a pull request, pruning a stale one on a CI box, opening a
+ * colleague's `recordings/` without installing their app's dependencies: all of
+ * them are file-editing, and the editor is already a plain handler over a
+ * directory, so they do not need the app at all.
+ *
+ * What this *cannot* serve is the browser case. `mountPollyStudio` edits
+ * recordings held in the page's own localStorage, and no separate process can
+ * see those.
+ */
+import { createServer } from 'node:http';
+import { existsSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { pollyUi } from './studio/server.js';
+const DEFAULT_PORT = 7788;
+const DEFAULT_DIR = 'recordings';
+/**
+ * How far to walk up from the asked-for port before giving up. A studio left
+ * open in another window is the normal case, and `EADDRINUSE` with a stack
+ * trace is a poor answer to it.
+ */
+const PORT_TRIES = 20;
+const USAGE = `polly-kit — Polly recordings, in a browser
+
+  npx polly-kit studio [--dir DIR] [--port PORT]
+
+  studio    Serve the recording editor on 127.0.0.1. Reads and writes the HAR
+            files under DIR (default ${DEFAULT_DIR}), the same ones the mounted
+            editor edits.
+
+Mounted in a dev server instead — no second port, and it stops when the server
+does — this is the Vite plugin, or app.use('/__polly', pollyUi({recordingsDir})).
+Recordings held in a browser's localStorage are reachable only from the page
+that owns them, through mountPollyStudio.
+`;
+export async function main(argv) {
+    const command = argv[0] ?? 'help';
+    if (command === 'help' || command === '--help' || command === '-h') {
+        process.stdout.write(USAGE);
+        return 0;
+    }
+    if (command !== 'studio') {
+        process.stderr.write(`unknown command: ${command}\n\n${USAGE}`);
+        return 2;
+    }
+    const dir = flag(argv, 'dir') ?? DEFAULT_DIR;
+    const root = isAbsolute(dir) ? dir : join(process.cwd(), dir);
+    const port = Number(flag(argv, 'port') ?? DEFAULT_PORT);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        process.stderr.write(`--port must be a port number, not "${flag(argv, 'port')}"\n`);
+        return 2;
+    }
+    // Said, not refused. An empty or missing directory is what you get before the
+    // first recording, and the editor explains that better than an exit code —
+    // but the path is printed either way, because "no recordings" almost always
+    // means the studio is looking somewhere else than the app records to.
+    if (!existsSync(root)) {
+        process.stdout.write(`no ${resolve(root)} yet — the editor will be empty until something records\n`);
+    }
+    const studio = await startStudio({ recordingsDir: root, port });
+    if (studio.port !== port)
+        process.stdout.write(`port ${port} was busy — using ${studio.port}\n`);
+    process.stdout.write(`polly studio on http://127.0.0.1:${studio.port}\n`);
+    process.stdout.write(`recordings: ${resolve(root)}\n`);
+    await new Promise((done) => {
+        process.once('SIGINT', () => done());
+        process.once('SIGTERM', () => done());
+    });
+    await studio.close();
+    return 0;
+}
+/**
+ * The server, without the process around it.
+ *
+ * Separate from `main` because stopping it has to be something a caller does,
+ * not something a signal does: `process.once('SIGINT')` listeners are global,
+ * so a second studio started in the same process would be stopped by the first
+ * one's Ctrl-C. That is only ever a test, but it is also the shape anything
+ * embedding this would want.
+ */
+export async function startStudio(options) {
+    // `enabled` is forced on. The mounted handler defaults it to NODE_ENV not
+    // being production, because something mounted into an app can be deployed by
+    // accident and recordings hold recorded request and response bodies. Nobody
+    // deploys an npx invocation by accident, and a shell that happens to export
+    // NODE_ENV=production would otherwise serve 404s with no explanation.
+    const server = createServer(pollyUi({ recordingsDir: options.recordingsDir, enabled: true }));
+    const port = await listenNearby(server, options.port ?? DEFAULT_PORT);
+    return {
+        port,
+        close: () => new Promise((done) => server.close(() => done())),
+    };
+}
+/** Loopback only: this serves recorded bodies, and it is a tool for one person. */
+async function listenNearby(server, port) {
+    for (let offset = 0; offset < PORT_TRIES; offset++) {
+        try {
+            await new Promise((done, fail) => {
+                server.once('error', fail);
+                server.listen(port + offset, '127.0.0.1', () => {
+                    server.removeListener('error', fail);
+                    done();
+                });
+            });
+            return port + offset;
+        }
+        catch (err) {
+            if (err.code !== 'EADDRINUSE')
+                throw err;
+        }
+    }
+    throw new Error(`ports ${port}-${port + PORT_TRIES - 1} are all in use. Pass --port to pick another.`);
+}
+/** `--dir recordings` and `--dir=recordings`, both. */
+function flag(argv, name) {
+    const index = argv.indexOf(`--${name}`);
+    if (index !== -1)
+        return argv[index + 1];
+    const inline = argv.find((arg) => arg.startsWith(`--${name}=`));
+    return inline === undefined ? undefined : inline.slice(name.length + 3);
+}
+// Only when run as a program. Importing this from a test must not start a
+// server — and the comparison is through fileURLToPath rather than string
+// matching on the URL, because on Windows argv[1] is `C:\...\cli.js` and
+// import.meta.url is `file:///C:/.../cli.js`.
+if (process.argv[1] !== undefined && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    main(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
+        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+    });
+}

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;

package/dist/node.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Record and replay a Node app's HTTP calls with Polly.JS.
+ *
+ * The browser entry's sibling. Two differences that matter:
+ *
+ * 1. `persister-fs` writes the HAR straight to disk, so there is no recording
+ *    store to host and no `apiNamespace` to keep in sync with a Vite plugin.
+ * 2. The adapters are PROCESS-WIDE. They also see this app talking to its
+ *    database, its broker, its health checks and its telemetry collector.
+ *    `{kind: 'all'}` on a server mocks Postgres. Prefer `{kind: 'only'}` and
+ *    read the policy line this logs at startup.
+ *
+ * `global-shim.js` is deliberately NOT imported here. It works around
+ * `@pollyjs/persister-rest` reading an unbound `global`, which this entry does
+ * not use, and assigning `global` in a real Node process is not harmless.
+ */
+import { Polly } from '@pollyjs/core';
+import { type PollyPolicyConfig } from './policy.js';
+export type { HostPolicy, PollyPolicyConfig } from './policy.js';
+export { toOrigin, toOrigins } from './policy.js';
+/**
+ * Re-exported so an app mounting the editor installs and imports one package. On
+ * the Vite path this package mounts polly-studio itself; on a server the app owns
+ * its own middleware chain, and reaching into a transitive dependency for
+ * `pollyUi` would work only by hoisting luck.
+ */
+export { pollyUi } from './studio/index.js';
+export type PollyMode = 'off' | 'record' | 'replay';
+/**
+ * Narrows whatever the app read out of its environment to a mode.
+ *
+ * Anything unrecognised — including `undefined` from an unset variable — is
+ * `off`, so a typo in the variable disables mocking rather than half-enabling it.
+ */
+export declare function resolveMode(raw: unknown): PollyMode;
+export interface StartPollyNodeOptions extends PollyPolicyConfig {
+    /** Resolve it with `resolveMode(process.env.POLLY_MODE)`. */
+    mode: PollyMode;
+    /** Where HARs are read from and written to. Gitignore it. */
+    recordingsDir?: string;
+    /**
+     * Hosts that are never mocked, whatever the policy says. Empty by default:
+     * unlike a browser there is no one origin that must survive, and the honest
+     * default is to make the caller name its own infrastructure.
+     */
+    alwaysPassthrough?: readonly (string | undefined | null)[];
+    /** Debounce on flushing to disk while recording. */
+    saveDebounceMs?: number;
+    /**
+     * Polly's log level. Defaults to `'error'` — see `DEFAULT_LOG_LEVEL` for why
+     * Polly's own `'warn'` is unusable in a Node process.
+     */
+    logLevel?: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent';
+}
+/** Returns null when the mode is `off`, having constructed and patched nothing. */
+export declare function startPolly(options: StartPollyNodeOptions): Polly | null;