@avivbenhamo/polly-kit 0.1.0 → 0.5.0

package/dist/node.js

@@ -0,0 +1,108 @@
+/**
+ * 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 NodeHttpAdapter from '@pollyjs/adapter-node-http';
+import FSPersister from '@pollyjs/persister-fs';
+import UndiciAdapter from './adapters/undici.js';
+import { KEEP_UNUSED_REQUESTS, POLLY_DEFAULTS } from './defaults.js';
+import { applyPolicy, toOrigins } 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';
+const MODES = ['off', 'record', 'replay'];
+const RECORDINGS_DIR = './recordings';
+/** How long to wait for more responses before flushing a recording to disk. */
+const SAVE_DEBOUNCE_MS = 500;
+/**
+ * Polly's own default is `'warn'`, and in a Node process the only
+ * WARN it emits is a false one: `@pollyjs/adapter` warns on EVERY recorded request
+ * when `'navigator' in global && !navigator.onLine`, and Node 22 has a global
+ * `navigator` with no `onLine` — so the check is always true, the claim is always
+ * wrong, and each occurrence drags a full stringified request and config into the
+ * log. A service recording fifty requests logs fifty paragraphs.
+ *
+ * Errors still print. The other WARN Polly has, recording expiry, needs `expiresIn`,
+ * which this entry never sets. Pass `logLevel` to get Polly's default back.
+ */
+const DEFAULT_LOG_LEVEL = 'error';
+let registered = false;
+/**
+ * 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 function resolveMode(raw) {
+    return MODES.includes(raw) ? raw : 'off';
+}
+/**
+ * Flush recordings while the process runs.
+ *
+ * Polly persists on `stop()`, which suits a test that ends. A long-running
+ * server would hold every recording in memory and lose all of them to a SIGKILL.
+ * Debounced rather than per-response because each save rewrites the whole HAR.
+ */
+function autoSave(polly, debounceMs) {
+    let timer;
+    polly.server.any().on('response', () => {
+        clearTimeout(timer);
+        timer = setTimeout(() => {
+            void polly.persister?.persist();
+        }, debounceMs);
+    });
+}
+/** Returns null when the mode is `off`, having constructed and patched nothing. */
+export function startPolly(options) {
+    const { mode, recordingName, policy, recordingsDir = RECORDINGS_DIR, alwaysPassthrough = [], saveDebounceMs = SAVE_DEBOUNCE_MS, logLevel = DEFAULT_LOG_LEVEL, } = options;
+    if (mode === 'off') {
+        return null;
+    }
+    if (!registered) {
+        Polly.register(NodeHttpAdapter);
+        Polly.register(UndiciAdapter);
+        Polly.register(FSPersister);
+        registered = true;
+    }
+    const polly = new Polly(recordingName, {
+        mode,
+        logLevel,
+        adapters: ['node-http', 'undici'],
+        persister: 'fs',
+        persisterOptions: {
+            keepUnusedRequests: KEEP_UNUSED_REQUESTS,
+            fs: { recordingsDir },
+        },
+        ...POLLY_DEFAULTS,
+    });
+    applyPolicy(polly.server, { policy, alwaysPassthrough });
+    // The adapters are process-wide, so which hosts are and are not mocked belongs
+    // in the boot log. Without it, "why is my database call being intercepted" is
+    // answered by reading source instead of scrollback.
+    const scope = policy.kind === 'all'
+        ? 'every host'
+        : `${policy.kind === 'only' ? 'only' : 'all except'} ${toOrigins(policy.hosts).join(', ') || '(none)'}`;
+    console.log(`polly-kit: ${mode} mode, mocking ${scope}; recordings in ${recordingsDir}`);
+    if (mode === 'record') {
+        autoSave(polly, saveDebounceMs);
+    }
+    return polly;
+}

package/dist/studio/body.d.ts

@@ -0,0 +1,28 @@
+import type { HarContent } from './types.js';
+/**
+ * Bodies, in the two forms Polly stores them. Nothing here uses `Buffer`: this module
+ * runs unchanged in the browser mount, where there is no Node.
+ */
+export declare function utf8ByteLength(text: string): number;
+/**
+ * A base64 body may or may not be text. `encoding: 'base64'` is set by the adapter for
+ * any binary buffer, so a PNG and a UTF-8 string with an odd byte both arrive the same
+ * way; only decoding tells them apart.
+ *
+ * `binary` is not a failure. It is the signal that the editor must show this entry
+ * read-only, because writing plaintext into a base64 field produces a mock that replays
+ * garbage with nothing to indicate it.
+ */
+export declare function decodeContent(content: HarContent): {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'binary';
+};
+/** Puts edited text back in whichever form the entry was stored in. */
+export declare function encodeContent(text: string, encoding: string | undefined): string;
+/**
+ * The length of the bytes an app will receive, which is what a `Content-Length` header
+ * has to agree with — not the length of the base64 text that describes them.
+ */
+export declare function bodyByteLength(text: string, encoding: string | undefined): number;

package/dist/studio/body.js

@@ -0,0 +1,66 @@
+/**
+ * Bodies, in the two forms Polly stores them. Nothing here uses `Buffer`: this module
+ * runs unchanged in the browser mount, where there is no Node.
+ */
+export function utf8ByteLength(text) {
+    return new TextEncoder().encode(text).length;
+}
+/**
+ * A base64 body may or may not be text. `encoding: 'base64'` is set by the adapter for
+ * any binary buffer, so a PNG and a UTF-8 string with an odd byte both arrive the same
+ * way; only decoding tells them apart.
+ *
+ * `binary` is not a failure. It is the signal that the editor must show this entry
+ * read-only, because writing plaintext into a base64 field produces a mock that replays
+ * garbage with nothing to indicate it.
+ */
+export function decodeContent(content) {
+    const text = content.text ?? '';
+    if (content.encoding !== 'base64')
+        return { kind: 'text', text };
+    const bytes = base64ToBytes(text);
+    if (bytes === null)
+        return { kind: 'binary' };
+    try {
+        return { kind: 'text', text: new TextDecoder('utf-8', { fatal: true }).decode(bytes) };
+    }
+    catch {
+        return { kind: 'binary' };
+    }
+}
+/** Puts edited text back in whichever form the entry was stored in. */
+export function encodeContent(text, encoding) {
+    if (encoding !== 'base64')
+        return text;
+    return bytesToBase64(new TextEncoder().encode(text));
+}
+/**
+ * The length of the bytes an app will receive, which is what a `Content-Length` header
+ * has to agree with — not the length of the base64 text that describes them.
+ */
+export function bodyByteLength(text, encoding) {
+    if (encoding !== 'base64')
+        return utf8ByteLength(text);
+    return base64ToBytes(text)?.length ?? 0;
+}
+function base64ToBytes(text) {
+    try {
+        const binary = atob(text);
+        const bytes = new Uint8Array(binary.length);
+        for (let i = 0; i < binary.length; i++)
+            bytes[i] = binary.charCodeAt(i);
+        return bytes;
+    }
+    catch {
+        return null;
+    }
+}
+function bytesToBase64(bytes) {
+    let binary = '';
+    // Chunked so a large body cannot blow the argument limit of String.fromCharCode.
+    const chunk = 0x8000;
+    for (let i = 0; i < bytes.length; i += chunk) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+    }
+    return btoa(binary);
+}

package/dist/studio/browser.d.ts

@@ -0,0 +1,22 @@
+import type { RecordingStore } from './stores/types.js';
+export interface MountOptions {
+    /** Polly's localStorage namespace. Defaults to `'pollyjs'`. */
+    key?: string;
+    storage?: Storage;
+    /** Overrides the store entirely. Mainly for tests. */
+    store?: RecordingStore;
+}
+/**
+ * Mounts the editor into a browser app that has no server at all — the case where
+ * Polly records through `persister-local-storage` and there are no HAR *files* anywhere,
+ * only a JSON blob under one key.
+ *
+ * ```js
+ * mountPollyStudio(document.getElementById('polly'))
+ * ```
+ */
+export declare function mountPollyStudio(root: HTMLElement, options?: MountOptions): void;
+export { LocalStorageStore } from './stores/local-storage-store.js';
+export { applyResponsePatch, deleteEntry } from './edit.js';
+export { parseHar } from './har.js';
+export type { Har, HarEntry, ResponsePatch } from './types.js';

package/dist/studio/browser.js

@@ -0,0 +1,24 @@
+import { mountStudio } from './ui/app.js';
+import { LocalStorageStore } from './stores/local-storage-store.js';
+import { STUDIO_MARKUP, STUDIO_STYLE } from './ui/page.js';
+/**
+ * Mounts the editor into a browser app that has no server at all — the case where
+ * Polly records through `persister-local-storage` and there are no HAR *files* anywhere,
+ * only a JSON blob under one key.
+ *
+ * ```js
+ * mountPollyStudio(document.getElementById('polly'))
+ * ```
+ */
+export function mountPollyStudio(root, options = {}) {
+    const store = options.store ??
+        new LocalStorageStore({
+            ...(options.key === undefined ? {} : { key: options.key }),
+            ...(options.storage === undefined ? {} : { storage: options.storage }),
+        });
+    root.innerHTML = `<style>${STUDIO_STYLE}</style>${STUDIO_MARKUP}`;
+    mountStudio(root, store);
+}
+export { LocalStorageStore } from './stores/local-storage-store.js';
+export { applyResponsePatch, deleteEntry } from './edit.js';
+export { parseHar } from './har.js';

package/dist/studio/client.bundle.js

@@ -0,0 +1,290 @@
+// dist/studio/body.js
+function decodeContent(content) {
+  const text = content.text ?? "";
+  if (content.encoding !== "base64")
+    return { kind: "text", text };
+  const bytes = base64ToBytes(text);
+  if (bytes === null)
+    return { kind: "binary" };
+  try {
+    return { kind: "text", text: new TextDecoder("utf-8", { fatal: true }).decode(bytes) };
+  } catch {
+    return { kind: "binary" };
+  }
+}
+function base64ToBytes(text) {
+  try {
+    const binary = atob(text);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+      bytes[i] = binary.charCodeAt(i);
+    return bytes;
+  } catch {
+    return null;
+  }
+}
+
+// dist/studio/headers.js
+function getHeader(headers, name) {
+  const wanted = name.toLowerCase();
+  return headers.find((header) => header.name.toLowerCase() === wanted)?.value;
+}
+
+// dist/studio/ui/render.js
+function escapeHtml(value) {
+  return String(value).replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
+}
+function renderNumeric(value) {
+  return escapeHtml(String(value));
+}
+function renderRecordingList(recordings) {
+  if (recordings.length === 0) {
+    return `<p class="empty">No recordings here yet. Run your app in Polly's record mode first.</p>`;
+  }
+  const rows = recordings.map((recording) => {
+    const note = recording.problem ? `<p class="ps-rec-note problem">${escapeHtml(recording.problem)}</p>` : recording.pollyWillReject ? `<p class="ps-rec-note warn">Polly will reject this: ${escapeHtml(recording.pollyWillReject)}</p>` : "";
+    return `<li><button class="recording" data-id="${escapeHtml(recording.id)}"><span class="ps-rec-name">${escapeHtml(recording.id)}</span><span class="count">${renderNumeric(recording.entryCount)}</span></button>${note}</li>`;
+  }).join("");
+  return `<ul class="recordings">${rows}</ul>`;
+}
+function unrenderable(err) {
+  return escapeHtml(err instanceof Error ? err.message : String(err));
+}
+function renderEntryRow(entry) {
+  try {
+    const order = entry._order > 0 ? ` <span class="order">#${renderNumeric(entry._order)}</span>` : "";
+    return `<li><button class="entry" data-id="${escapeHtml(entry._id)}" data-order="${renderNumeric(entry._order)}"><span class="method">${escapeHtml(entry.request.method)}</span> <span class="status s${Math.floor(entry.response.status / 100)}">${renderNumeric(entry.response.status)}</span> <span class="url">${escapeHtml(entry.request.url)}</span>${order}</button></li>`;
+  } catch (err) {
+    console.error("polly-studio: could not render entry row", err);
+    return `<li class="problem">this entry could not be rendered: ${unrenderable(err)}</li>`;
+  }
+}
+function renderEntryDetail(entry) {
+  try {
+    return entryDetail(entry);
+  } catch (err) {
+    console.error("polly-studio: could not render entry detail", err);
+    return `<section class="problem"><p>this entry could not be rendered: ${unrenderable(err)}</p></section>`;
+  }
+}
+function entryDetail(entry) {
+  const response = entry.response;
+  const decoded = decodeContent(response.content);
+  const body = decoded.kind === "binary" ? `<p class="ps-notice warn">This body is binary (${escapeHtml(getHeader(response.headers, "content-type") ?? "unknown type")}, ${renderNumeric(response.content.size)} bytes). Editing it as text would replace the recorded bytes with a UTF-8 rendering of them, so it is shown read-only.</p>` : `<textarea name="bodyText" rows="16" spellcheck="false" aria-label="Response body">${escapeHtml(decoded.text)}</textarea>`;
+  const headers = response.headers.map((header, index) => `<div class="header-row"><input name="headerName${index}" value="${escapeHtml(header.name)}" class="ps-header-name" spellcheck="false" aria-label="Header name"><input name="headerValue${index}" value="${escapeHtml(header.value)}" class="ps-header-value" spellcheck="false" aria-label="Header value"></div>`).join("");
+  return `
+<section class="detail" data-id="${escapeHtml(entry._id)}" data-order="${renderNumeric(entry._order)}">
+  <div class="ps-block ps-block--request">
+    <h2>Request <small>read-only</small></h2>
+    <p class="note">Polly matches a replayed request on <code>_id</code>, an md5 of the request built
+    from your <code>matchRequestsBy</code> config \u2014 and that config is not stored in the recording.
+    Editing any of this would leave an entry that looks right and never matches again.</p>
+    <dl>
+      <dt>Method</dt><dd>${escapeHtml(entry.request.method)}</dd>
+      <dt>URL</dt><dd>${escapeHtml(entry.request.url)}</dd>
+      <dt>Recorded</dt><dd>${escapeHtml(entry.startedDateTime)}</dd>
+      <dt>_id / _order</dt><dd><code>${escapeHtml(entry._id)}</code> / ${renderNumeric(entry._order)}</dd>
+    </dl>
+  </div>
+
+  <div class="ps-block ps-block--response">
+    <h2>Response</h2>
+    <div class="ps-fields">
+      <label class="ps-field"><span class="ps-field-label">Status</span><input name="status" type="number" value="${renderNumeric(response.status)}" class="ps-input" min="100" max="599"></label>
+      <label class="ps-field"><span class="ps-field-label">Status text</span><input name="statusText" value="${escapeHtml(response.statusText)}" class="ps-input" spellcheck="false"></label>
+    </div>
+
+    <h3 class="ps-group-title">Headers</h3>
+    ${headers === "" ? '<p class="empty">This response was recorded without headers.</p>' : `<div class="headers">${headers}</div>`}
+
+    <h3 class="ps-group-title">Body</h3>
+    ${body}
+
+    <div class="actions">
+      <button name="save">Save response</button>
+      <button name="delete" class="danger">Delete entry</button>
+    </div>
+  </div>
+</section>`;
+}
+
+// dist/studio/stores/types.js
+var StoreError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "StoreError";
+    this.code = code;
+  }
+};
+
+// dist/studio/ui/app.js
+function mountStudio(root, store) {
+  const recordings = required(root, "#recordings");
+  const entries = required(root, "#entries");
+  const detail = required(root, "#detail");
+  let currentId = null;
+  let current = null;
+  refreshRecordings().catch(report);
+  async function refreshRecordings() {
+    recordings.innerHTML = renderRecordingList(await store.list());
+  }
+  async function openRecording(id) {
+    const read = await store.read(id);
+    currentId = id;
+    current = { har: read.har, etag: read.etag };
+    entries.innerHTML = `<ul>${read.har.log.entries.map(renderEntryRow).join("")}</ul>`;
+    detail.innerHTML = "";
+  }
+  function openEntry(entryId, order) {
+    const entry = current?.har.log.entries.find((e) => String(e._id) === entryId && e._order === order);
+    if (entry === void 0) {
+      detail.innerHTML = "";
+      report(new Error(`no entry with _id ${entryId} and _order ${order} in this recording`));
+      return;
+    }
+    detail.innerHTML = renderEntryDetail(entry);
+  }
+  async function save(entryId, order) {
+    if (currentId === null || current === null)
+      return;
+    try {
+      const patch = readPatch(detail, entryId, order, current.har);
+      await store.patchEntry(currentId, entryId, order, current.etag, patch);
+      await openRecording(currentId);
+      openEntry(entryId, order);
+    } catch (err) {
+      report(err);
+    }
+  }
+  async function remove(entryId, order) {
+    if (currentId === null || current === null)
+      return;
+    try {
+      await store.deleteEntry(currentId, entryId, order, current.etag);
+      await openRecording(currentId);
+    } catch (err) {
+      report(err);
+    }
+  }
+  function report(err) {
+    const message = err instanceof StoreError && err.code === "conflict" ? "the recording changed underneath \u2014 reload and retry" : err instanceof Error ? err.message : String(err);
+    const banner = detail.ownerDocument.createElement("p");
+    banner.className = "problem";
+    banner.textContent = message;
+    detail.prepend(banner);
+  }
+  root.addEventListener("click", (event) => {
+    const target = event.target?.closest("button");
+    if (target === null || target === void 0)
+      return;
+    if (target.classList.contains("recording")) {
+      openRecording(target.dataset["id"]).catch(report);
+      return;
+    }
+    if (target.classList.contains("entry")) {
+      try {
+        openEntry(target.dataset["id"], Number(target.dataset["order"]));
+      } catch (err) {
+        report(err);
+      }
+      return;
+    }
+    const section = target.closest(".detail");
+    if (section === null)
+      return;
+    const entryId = section.dataset["id"];
+    const order = Number(section.dataset["order"]);
+    if (target.getAttribute("name") === "save")
+      void save(entryId, order);
+    if (target.getAttribute("name") === "delete")
+      void remove(entryId, order);
+  });
+}
+function required(root, selector) {
+  const el = root.querySelector(selector);
+  if (el === null) {
+    throw new Error(`polly-studio: mountStudio could not find "${selector}" in the given root`);
+  }
+  return el;
+}
+function readPatch(root, entryId, order, har) {
+  const value = (name) => root.querySelector(`[name="${name}"]`)?.value;
+  const headers = [];
+  for (let index = 0; ; index++) {
+    const name = value(`headerName${index}`);
+    if (name === void 0)
+      break;
+    const existing = har.log.entries.find((e) => String(e._id) === entryId && e._order === order)?.response.headers[index];
+    headers.push({
+      ...existing?._fromType === "array" ? { _fromType: "array" } : {},
+      name,
+      value: value(`headerValue${index}`) ?? ""
+    });
+  }
+  const rawStatus = value("status");
+  const status = rawStatus === void 0 || rawStatus === "" ? void 0 : Number(rawStatus);
+  if (status !== void 0 && (!Number.isFinite(status) || status < 100 || status > 599)) {
+    throw new Error(`status must be a number between 100 and 599, got "${rawStatus}"`);
+  }
+  const bodyText = value("bodyText");
+  return {
+    ...status === void 0 ? {} : { status },
+    ...value("statusText") === void 0 ? {} : { statusText: value("statusText") },
+    headers,
+    ...bodyText === void 0 ? {} : { bodyText }
+  };
+}
+
+// dist/studio/stores/http-store.js
+var HttpStore = class {
+  constructor(basePath) {
+    this.basePath = basePath.endsWith("/") ? basePath.slice(0, -1) : basePath;
+  }
+  async list() {
+    const body = await this.json("GET", "/api/recordings");
+    return body.recordings;
+  }
+  async read(id) {
+    return await this.json("GET", `/api/recordings/${encodeURIComponent(id)}`);
+  }
+  /**
+   * Not on the wire protocol. The UI edits through `patchEntry`/`deleteEntry`. The
+   * parameters are declared (and ignored) rather than dropped so a caller holding a
+   * concrete `HttpStore` — not just a `RecordingStore` — can still call this with the
+   * interface's arity; TypeScript checks a direct call against the class's own
+   * declared signature, not the interface it implements.
+   */
+  async write(id, har, etag) {
+    throw new StoreError("forbidden", "the HTTP API applies edits itself \u2014 use patchEntry");
+  }
+  async delete(id) {
+    throw new StoreError("forbidden", "deleting a whole recording is not exposed over the API");
+  }
+  async patchEntry(id, entryId, order, etag, patch) {
+    return await this.json("PATCH", `/api/recordings/${encodeURIComponent(id)}/entries/${encodeURIComponent(entryId)}/${order}`, { etag, patch });
+  }
+  async deleteEntry(id, entryId, order, etag) {
+    return await this.json("DELETE", `/api/recordings/${encodeURIComponent(id)}/entries/${encodeURIComponent(entryId)}/${order}?etag=${encodeURIComponent(etag)}`);
+  }
+  async json(method, path, body) {
+    const res = await fetch(`${this.basePath}${path}`, {
+      method,
+      ...body === void 0 ? {} : { headers: { "content-type": "application/json" }, body: JSON.stringify(body) }
+    });
+    const parsed = await res.json().catch(() => ({}));
+    if (res.ok)
+      return parsed;
+    const code = res.status === 404 ? "not-found" : res.status === 409 ? "conflict" : res.status === 403 ? "forbidden" : res.status === 422 ? "unprocessable" : null;
+    if (code !== null)
+      throw new StoreError(code, parsed.error ?? `${method} ${path} failed`);
+    throw new Error(parsed.error ?? `${method} ${path} failed with ${res.status}`);
+  }
+};
+
+// dist/studio/ui/client.js
+function start(basePath) {
+  mountStudio(document, new HttpStore(basePath));
+}
+export {
+  start
+};

package/dist/studio/edit.d.ts

@@ -0,0 +1,42 @@
+import type { Har, ResponsePatch } from './types.js';
+export type EditError = {
+    code: 'entry-not-found' | 'binary-body';
+    message: string;
+};
+export type EditResult = {
+    ok: true;
+    har: Har;
+} | {
+    ok: false;
+    error: EditError;
+};
+/**
+ * Applies a response edit and re-derives everything that described the old response.
+ *
+ * Five fields are read at replay (`adapter/src/utils/normalize-recorded-response.js`):
+ * `status`, `statusText`, `headers`, `content.text` and `content.encoding`. Those must
+ * be right. `Content-Length` counts as one of them, because headers are handed to the
+ * app verbatim — a stale length contradicts the body beside it.
+ *
+ * The rest — `content.size`, `bodySize`, `headersSize`, `content.mimeType`,
+ * `redirectURL` — are HAR metadata Polly never reads. They are maintained anyway,
+ * because these are HAR files and other tools do read them.
+ *
+ * `cookies` is the exception. Polly builds it with `set-cookie-parser`, keeping
+ * attributes this package has no dependency to reproduce, so a regenerated list would
+ * be strictly worse than the recorded one. It is left alone, except that removing the
+ * last `Set-Cookie` header clears it — the one case where leaving it would be plainly
+ * wrong rather than merely stale.
+ */
+export declare function applyResponsePatch(har: Har, id: string, order: number, patch: ResponsePatch): EditResult;
+export declare function notFound(id: string, order: number): string;
+/**
+ * Removes one entry and closes the gap it leaves in its `_id` group.
+ *
+ * `_order` is not a label, it is a position. Polly derives a request's order at replay
+ * by counting how many earlier requests in the recording produced the same `_id`,
+ * starting at 0 — so after deleting the `_order: 0` member of a pair, the survivor
+ * sitting at `_order: 1` is asked for as order 0 and never found again. It stays in the
+ * file, looks correct, and is dead. Renumbering the group from 0 is the whole fix.
+ */
+export declare function deleteEntry(har: Har, id: string, order: number): EditResult;

package/dist/studio/edit.js

@@ -0,0 +1,90 @@
+import { findEntry } from './har.js';
+import { bodyByteLength, decodeContent, encodeContent } from './body.js';
+import { getHeader, hasHeader, responseHeadersSize, setHeader } from './headers.js';
+/**
+ * Applies a response edit and re-derives everything that described the old response.
+ *
+ * Five fields are read at replay (`adapter/src/utils/normalize-recorded-response.js`):
+ * `status`, `statusText`, `headers`, `content.text` and `content.encoding`. Those must
+ * be right. `Content-Length` counts as one of them, because headers are handed to the
+ * app verbatim — a stale length contradicts the body beside it.
+ *
+ * The rest — `content.size`, `bodySize`, `headersSize`, `content.mimeType`,
+ * `redirectURL` — are HAR metadata Polly never reads. They are maintained anyway,
+ * because these are HAR files and other tools do read them.
+ *
+ * `cookies` is the exception. Polly builds it with `set-cookie-parser`, keeping
+ * attributes this package has no dependency to reproduce, so a regenerated list would
+ * be strictly worse than the recorded one. It is left alone, except that removing the
+ * last `Set-Cookie` header clears it — the one case where leaving it would be plainly
+ * wrong rather than merely stale.
+ */
+export function applyResponsePatch(har, id, order, patch) {
+    const existing = findEntry(har, id, order);
+    if (existing === undefined) {
+        return { ok: false, error: { code: 'entry-not-found', message: notFound(id, order) } };
+    }
+    if (patch.bodyText !== undefined && decodeContent(existing.response.content).kind === 'binary') {
+        return {
+            ok: false,
+            error: {
+                code: 'binary-body',
+                message: 'this response body is binary — editing it as text would replace the recorded bytes with a UTF-8 rendering of them',
+            },
+        };
+    }
+    const next = structuredClone(har);
+    const entry = findEntry(next, id, order);
+    const response = entry.response;
+    if (patch.status !== undefined)
+        response.status = patch.status;
+    if (patch.statusText !== undefined)
+        response.statusText = patch.statusText;
+    const hadSetCookie = hasHeader(response.headers, 'set-cookie');
+    if (patch.headers !== undefined)
+        response.headers = patch.headers;
+    if (patch.bodyText !== undefined) {
+        response.content.text = encodeContent(patch.bodyText, response.content.encoding);
+    }
+    const bytes = bodyByteLength(response.content.text ?? '', response.content.encoding);
+    response.content.size = bytes;
+    response.bodySize = bytes;
+    // Set it only where the recording had one: adding a Content-Length to a response
+    // that was chunked would describe the transfer differently than it was recorded.
+    if (hasHeader(response.headers, 'content-length')) {
+        response.headers = setHeader(response.headers, 'content-length', String(bytes));
+    }
+    response.content.mimeType = getHeader(response.headers, 'content-type') ?? 'text/plain';
+    response.redirectURL = getHeader(response.headers, 'location') ?? '';
+    response.headersSize = responseHeadersSize(response.headers);
+    if (hadSetCookie && !hasHeader(response.headers, 'set-cookie')) {
+        response.cookies = [];
+    }
+    return { ok: true, har: next };
+}
+export function notFound(id, order) {
+    return `no entry with _id ${id} and _order ${order} — it may have been deleted since the page loaded`;
+}
+/**
+ * Removes one entry and closes the gap it leaves in its `_id` group.
+ *
+ * `_order` is not a label, it is a position. Polly derives a request's order at replay
+ * by counting how many earlier requests in the recording produced the same `_id`,
+ * starting at 0 — so after deleting the `_order: 0` member of a pair, the survivor
+ * sitting at `_order: 1` is asked for as order 0 and never found again. It stays in the
+ * file, looks correct, and is dead. Renumbering the group from 0 is the whole fix.
+ */
+export function deleteEntry(har, id, order) {
+    if (findEntry(har, id, order) === undefined) {
+        return { ok: false, error: { code: 'entry-not-found', message: notFound(id, order) } };
+    }
+    const next = structuredClone(har);
+    next.log.entries = next.log.entries.filter((entry) => !(entry._id === id && entry._order === order));
+    const group = next.log.entries
+        .filter((entry) => entry._id === id)
+        .sort((a, b) => a._order - b._order);
+    group.forEach((entry, index) => {
+        entry._order = index;
+    });
+    return { ok: true, har: next };
+}