@avivbenhamo/polly-kit 0.1.0 → 0.5.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,138 +1,298 @@
-# @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.
-
-Nothing in here knows a hostname. You supply a policy; the package is the machinery.
-
-## Install
-
-```sh
-npm i -D @avivbenhamo/polly-kit
-```
-
-## Three steps
-
-**1. `vite.config.ts`** — one plugin, dev-server only (it registers in `configureServer`, so a
-production build never sees it):
-
-```ts
-import pollyKit from '@avivbenhamo/polly-kit/vite';
-
-export default defineConfig({
-    plugins: [react(), pollyKit({recordingsDir: 'recordings'})],
-});
-```
-
-**2. A config file** — the only file you write:
-
-```ts
-// src/polly/config.ts
-import type {PollyPolicyConfig} from '@avivbenhamo/polly-kit';
-
-export const pollyConfig: PollyPolicyConfig = {
-    recordingName: 'my-app',
-    policy: {kind: 'except', hosts: [import.meta.env.VITE_AUTH_URL]},
-};
-```
-
-**3. A bootstrap module, imported FIRST in your entry point:**
-
-```ts
-// src/polly/bootstrap.ts
-import {resolveMode, startPolly} from '@avivbenhamo/polly-kit';
-import {pollyConfig} from './config';
-
-const mode = import.meta.env.PROD ? 'off' : resolveMode(import.meta.env.VITE_POLLY_MODE);
-
-startPolly({...pollyConfig, mode});
-```
-
-```ts
-// src/index.tsx — FIRST import, above everything
-import './polly/bootstrap';
-```
-
-`bootstrap.ts` exists so that `startPolly()` runs before your component tree is evaluated. ES
-module imports are hoisted and fully evaluated before any statement in the importing module's
-body, so a bare `startPolly()` call in `index.tsx` runs *after* `./App` and everything it
-imports — and any module that fires a request at import time would escape interception,
-silently and only sometimes.
-
-Add `/recordings` to `.gitignore`. A HAR holds complete response bodies.
-
-## Running it
-
-Off unless `VITE_POLLY_MODE` is set, so the default behaviour of your app is unchanged.
-
-```powershell
-$env:VITE_POLLY_MODE='record'; npm run dev     # capture real traffic
-$env:VITE_POLLY_MODE='replay'; npm run dev     # serve from recordings
-```
-
-```sh
-VITE_POLLY_MODE=record npm run dev             # bash
-```
-
-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.
-
-## Policies
-
-```ts
-policy: {kind: 'all'}                    // mock every host
-policy: {kind: 'except', hosts: [...]}   // mock everything EXCEPT these
-policy: {kind: 'only',   hosts: [...]}   // mock ONLY these
-```
-
-Hosts match by origin, so a trailing slash or a path on the value is fine — they are `baseURL`s
-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.
-
-**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
-also the least likely to be reachable from an isolated environment. Replaying off-network then
-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.
-
-## API
-
-| Export | From | What |
-|---|---|---|
-| `startPolly(options)` | `.` | Starts Polly. Returns `null` when `mode` is `'off'`, having constructed nothing. |
-| `resolveMode(raw)` | `.` | Narrows an env value to `'off' \| 'record' \| 'replay'`. Anything unrecognised is `off`. |
-| `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` options beyond the policy config: `mode` (required), `alwaysPassthrough`,
-`apiNamespace`, `saveDebounceMs`. `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.
-
-**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
-import, so you cannot get the order wrong.
-
-**Recordings flush while you browse.** Polly only persists on `stop()`, which suits a test that
-ends; a dev server page stays open and would write nothing. The kit debounces a `persist()` per
-response instead.
-
-**Defaults that differ from Polly's.** `recordIfMissing: false` (a replay miss must fail loudly
-— the default quietly hits the network and records it, which looks identical to replay working),
-`recordFailedRequests: true`, `matchRequestsBy.order: false` (screens refetch) and
-`.headers: false` (bearer tokens would pin a recording to one session).
-
-**If you also run MSW, Polly wins.** It patches `XMLHttpRequest` in-page, so the request is
-answered before the service worker sees it. Run one or the other.
+# @avivbenhamo/polly-kit
+
+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.
+
+## Install
+
+```sh
+npm i -D @avivbenhamo/polly-kit
+```
+
+## Three steps
+
+**1. `vite.config.ts`** — one plugin, dev-server only (it registers in `configureServer`, so a
+production build never sees it):
+
+```ts
+import pollyKit from '@avivbenhamo/polly-kit/vite';
+
+export default defineConfig({
+    plugins: [react(), pollyKit({recordingsDir: 'recordings'})],
+});
+```
+
+**2. A config file** — the only file you write:
+
+```ts
+// src/polly/config.ts
+import type {PollyPolicyConfig} from '@avivbenhamo/polly-kit';
+
+export const pollyConfig: PollyPolicyConfig = {
+    recordingName: 'my-app',
+    policy: {kind: 'except', hosts: [import.meta.env.VITE_AUTH_URL]},
+};
+```
+
+**3. A bootstrap module, imported FIRST in your entry point:**
+
+```ts
+// src/polly/bootstrap.ts
+import {resolveMode, startPolly} from '@avivbenhamo/polly-kit';
+import {pollyConfig} from './config';
+
+const mode = import.meta.env.PROD ? 'off' : resolveMode(import.meta.env.VITE_POLLY_MODE);
+
+startPolly({...pollyConfig, mode});
+```
+
+```ts
+// src/index.tsx — FIRST import, above everything
+import './polly/bootstrap';
+```
+
+`bootstrap.ts` exists so that `startPolly()` runs before your component tree is evaluated. ES
+module imports are hoisted and fully evaluated before any statement in the importing module's
+body, so a bare `startPolly()` call in `index.tsx` runs *after* `./App` and everything it
+imports — and any module that fires a request at import time would escape interception,
+silently and only sometimes.
+
+Add `/recordings` to `.gitignore`. A HAR holds complete response bodies.
+
+## Running it
+
+Off unless `VITE_POLLY_MODE` is set, so the default behaviour of your app is unchanged.
+
+```powershell
+$env:VITE_POLLY_MODE='record'; npm run dev     # capture real traffic
+$env:VITE_POLLY_MODE='replay'; npm run dev     # serve from recordings
+```
+
+```sh
+VITE_POLLY_MODE=record npm run dev             # bash
+```
+
+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
+policy: {kind: 'all'}                    // mock every host
+policy: {kind: 'except', hosts: [...]}   // mock everything EXCEPT these
+policy: {kind: 'only',   hosts: [...]}   // mock ONLY these
+```
+
+Hosts match by origin, so a trailing slash or a path on the value is fine — they are `baseURL`s
+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.
+
+**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
+also the least likely to be reachable from an isolated environment. Replaying off-network then
+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'`.
+
+### Without an app
+
+```sh
+npx polly-kit studio --dir recordings      # http://127.0.0.1:7788
+```
+
+For a checkout with no dev server to mount on: reviewing the recordings in a pull request,
+pruning a stale one, opening somebody else's `recordings/` without installing their app. Same
+editor, same files — the recordings directory is the only state, so an app recording into it
+from another process shows up without restarting anything. If the port is taken it walks up to
+the next free one and says so.
+
+**The mounted form is still the default**, and the better one when there is a dev server: no
+second process, no second port, no CORS, and it stops when the server does. Recordings kept in
+a browser's `localStorage` cannot be served this way at all — no separate process can see them,
+which is what `mountPollyStudio` is for.
+
+Unlike the mounted handler this ignores `NODE_ENV`. Something mounted into an app can be
+deployed by accident; an `npx` invocation cannot, and a shell that happens to export
+`NODE_ENV=production` would otherwise get 404s with no explanation.
+
+**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 |
+|---|---|---|
+| `startPolly(options)` | `.` | Starts Polly. Returns `null` when `mode` is `'off'`, having constructed nothing. |
+| `resolveMode(raw)` | `.` | Narrows an env value to `'off' \| 'record' \| 'replay'`. Anything unrecognised is `off`. |
+| `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`; 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
+
+**In the browser: both adapters.** A browser has two request transports and an app can use
+either, so covering one covers half the app — silently, because an adapter attaches cleanly
+whether or not any traffic reaches it. `adapter-xhr` patches `window.XMLHttpRequest`, which is
+what axios uses (it resolves its adapter as `['xhr', 'http', 'fetch']`), so no axios instance
+in your app needs to change. `adapter-fetch` patches `window.fetch`, which is what code
+written against the platform calls directly. They patch different globals and do not interact.
+
+**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
+import, so you cannot get the order wrong.
+
+**Recordings flush while you browse.** Polly only persists on `stop()`, which suits a test that
+ends; a dev server page stays open and would write nothing. The kit debounces a `persist()` per
+response instead.
+
+**Defaults that differ from Polly's.** `recordIfMissing: false` (a replay miss must fail loudly
+— the default quietly hits the network and records it, which looks identical to replay working),
+`recordFailedRequests: true`, `matchRequestsBy.order: false` (screens refetch) and
+`.headers: false` (bearer tokens would pin a recording to one session).
+
+**If you also run MSW, Polly wins.** It patches `XMLHttpRequest` and `fetch` in-page, so the
+request is answered before the service worker sees it. Run one or the other.

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>;
+}