@chrischall/mcp-utils 2.15.0 → 3.0.0

package/dist/http/index.js

@@ -18,18 +18,49 @@
  */
 import { responseHeader } from '../internal/headers.js';
 import { currentCallSignal, withAmbientCancellation } from '../cancel/index.js';
-import { truncateErrorMessage } from '../errors/index.js';
+import { McpToolError, UpstreamFormatError, messageOf, truncateErrorMessage } from '../errors/index.js';
 import { isCloudflareChallenge } from '../scrape/index.js';
 export * from './throttle.js';
 export * from './response-cache.js';
 export * from './net-atoms.js';
+export * from './fetch-bounded.js';
+export * from './url-safety.js';
+import { readBytesCapped, ResponseTooLargeError } from './body-limit.js';
 import { parseRetryAfterMs } from './net-atoms.js';
+import { RedirectRefusedError, findPathHazard } from './url-safety.js';
 import { retryAfterToMs } from '../internal/retry-after.js';
 const DEFAULT_RETRY = { count: 1, delayMs: 2000 };
 const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
-/** Thrown for an upstream 401. Carries the status so callers can trigger a re-auth. */
+/**
+ * The per-attempt timeout {@link createApiClient} (and {@link fetchBounded})
+ * apply when the caller names none: 30 s, the same budget
+ * `createGraphqlClient` has always used, so every fleet transport bounds a
+ * hung upstream the same way.
+ */
+export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+/** Default hop limit for `createApiClient({ redirect: 'same-origin' })`. */
+export const DEFAULT_MAX_REDIRECTS = 5;
+/** The statuses `redirect: 'same-origin'` follows (when they carry a `Location`). */
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+/** Cancel a response body we will not read. Never throws (a custom fetchImpl's body may be odd). */
+function cancelBody(res) {
+    try {
+        const body = res.body;
+        body?.cancel?.()?.catch(() => { });
+    }
+    catch {
+        // nothing left to release
+    }
+}
+/**
+ * Thrown for an upstream 401. Carries the status so callers can trigger a
+ * re-auth, and `kind: 'credential_rejected'` (an `McpToolErrorKind`) so a
+ * classifier reads it without matching the message.
+ */
 export class UnauthorizedError extends Error {
     status = 401;
+    /** Always `'credential_rejected'` unless a subclass says otherwise. */
+    kind = 'credential_rejected';
     constructor(service) {
         super(`Unauthorized (401) from ${service} — the token is missing, invalid, or expired.`);
         this.name = 'UnauthorizedError';
@@ -43,6 +74,8 @@ export class UnauthorizedError extends Error {
  */
 export class RateLimitedError extends Error {
     status = 429;
+    /** `'http'`: the far side answered, with a 429 (see `status`). */
+    kind = 'http';
     retryAfterMs;
     constructor(service, retryAfterMs) {
         super(`Rate limited (429) by ${service} after retries.`);
@@ -51,9 +84,11 @@ export class RateLimitedError extends Error {
         Object.setPrototypeOf(this, new.target.prototype);
     }
 }
-/** Thrown when a request exceeds {@link ApiClientOptions.timeout}. */
+/** Thrown when a request exceeds {@link ApiClientOptions.timeout}. Its `kind` is `'timeout'`. */
 export class RequestTimeoutError extends Error {
     timeoutMs;
+    /** Always `'timeout'` unless a subclass says otherwise. */
+    kind = 'timeout';
     constructor(service, timeoutMs) {
         super(`Request to ${service} timed out after ${timeoutMs}ms.`);
         this.name = 'RequestTimeoutError';
@@ -61,6 +96,56 @@ export class RequestTimeoutError extends Error {
         Object.setPrototypeOf(this, new.target.prototype);
     }
 }
+/** The default `hint` on a {@link WriteOutcomeUnknownError}. */
+export const DEFAULT_WRITE_OUTCOME_HINT = 'The write may have happened — check before retrying; do not resend blindly.';
+/**
+ * A write (a request whose method is not safe) was SENT, but no usable
+ * response came back: it timed out, the connection dropped, or the response
+ * body broke off. The server may already have committed it, so the outcome is
+ * UNKNOWN, and re-sending it blindly can duplicate an email, a booking or a
+ * payment (fleet audit 2026-09, cluster 7: opentable #632, honeybook #1023,
+ * office-outlook #1073, vibo #1135, untappd #1132).
+ *
+ * An {@link McpToolError}, so its {@link McpToolError.hint} ("check before
+ * retrying") reaches the model through `wrapToolError` / `errorResult`. It
+ * still DECLARES a timeout when one caused it (`timedOut: true`, the marker
+ * `isTimeoutError` reads), but carries `retrySafe: false`, so
+ * `retryOnceOnTimeout` never replays it. Mirrors `GraphqlTransportError`'s
+ * `outcomeUnknown` and fetchproxy's `FetchproxyTimeoutError.retrySafe`.
+ *
+ * Thrown by {@link createApiClient} (see
+ * {@link ApiClientOptions.writeOutcomeUnknown}); exported so a hand-rolled
+ * client can throw the same thing.
+ */
+export class WriteOutcomeUnknownError extends McpToolError {
+    /** Always `true`: whether the write happened is not known. */
+    outcomeUnknown = true;
+    /** Always `false`: never replay this request without checking first. */
+    retrySafe = false;
+    /** `true` when the request's timeout expired; `false` for a dropped connection or broken body. */
+    timedOut;
+    /** The timeout that expired, when {@link timedOut}. */
+    timeoutMs;
+    /** The request method, upper-cased. */
+    method;
+    constructor(service, method, opts = {}) {
+        const verb = method.toUpperCase();
+        const what = opts.timeoutMs !== undefined
+            ? `${verb} to ${service} timed out after ${opts.timeoutMs}ms`
+            : `${verb} to ${service} failed: ${truncateErrorMessage(messageOf(opts.cause), 200)}`;
+        super(`${what} — the write may already have been applied (outcome is unknown).`, {
+            hint: opts.hint ?? DEFAULT_WRITE_OUTCOME_HINT,
+            cause: opts.cause,
+            kind: opts.timeoutMs !== undefined ? 'timeout' : 'transport',
+        });
+        this.name = 'WriteOutcomeUnknownError';
+        this.timedOut = opts.timeoutMs !== undefined;
+        this.timeoutMs = opts.timeoutMs;
+        this.method = verb;
+    }
+}
+/** RFC 9110 safe methods: a request with one of these never writes. */
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS', 'TRACE']);
 /**
  * Thrown by {@link ApiClient.fetchJson} / {@link ApiClient.fetchHtml} for a
  * non-2xx response that isn't a 401/429 (those map to
@@ -114,6 +199,8 @@ export class UpstreamHttpError extends ApiError {
 export class EdgeBlockedError extends ApiError {
     /** Which edge refused the request, e.g. `'CloudFront'` or `'Cloudflare'`. */
     vendor;
+    /** Always `'edge_blocked'`: the credential was never judged. */
+    kind = 'edge_blocked';
     /**
      * @param where The service the request was for, and — when the thrower knows
      *   it — the method and path, which the message names.
@@ -218,6 +305,67 @@ export function detectEdgeBlock(input) {
     }
     return null;
 }
+function jsonKind(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+/**
+ * Parse an upstream response body as JSON, turning every way it can fail into
+ * a typed, message-safe error instead of a raw `SyntaxError` (whose message
+ * quotes the body) or a later `TypeError` on `null`:
+ *
+ *  - a body that is not JSON is first checked with {@link detectEdgeBlock}
+ *    (a Cloudflare challenge served with a 200 becomes {@link EdgeBlockedError});
+ *    otherwise it throws {@link UpstreamFormatError} with `received: 'non-json'`,
+ *    naming the service, request, status and content type but never the body;
+ *  - with `expect`, an empty body, `null`, a scalar or the wrong container
+ *    throws {@link UpstreamFormatError} too.
+ *
+ * An empty (or whitespace-only) body without `expect` returns `undefined`, the
+ * same contract `fetchJson` has for a 204. `fetchJson` runs every 2xx body
+ * through this; export it for hand-rolled clients and OAuth token exchanges
+ * that read the body themselves (skylight, ofw).
+ */
+export function parseJsonBody(text, opts = {}) {
+    const contentType = opts.contentType ?? headerOf(opts.headers, 'content-type');
+    const details = {
+        service: opts.service,
+        method: opts.method,
+        path: opts.path,
+        status: opts.status,
+        contentType,
+        expected: opts.expect,
+    };
+    if (text.trim().length === 0) {
+        if (opts.expect === undefined)
+            return undefined;
+        throw new UpstreamFormatError({ ...details, received: 'empty' });
+    }
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (cause) {
+        const edge = detectEdgeBlock({ body: text, headers: opts.headers, status: opts.status });
+        if (edge) {
+            throw new EdgeBlockedError(opts.status ?? 200, edge.vendor, {
+                service: opts.service ?? 'the upstream service',
+                method: opts.method,
+                path: opts.path,
+            });
+        }
+        throw new UpstreamFormatError({ ...details, expected: undefined, received: 'non-json', cause });
+    }
+    if (opts.expect !== undefined) {
+        const kind = jsonKind(value);
+        if (kind !== opts.expect)
+            throw new UpstreamFormatError({ ...details, received: kind });
+    }
+    return value;
+}
 /**
  * The error a non-2xx response becomes: {@link EdgeBlockedError} when an edge
  * refused it, otherwise the {@link ApiError} the client has always thrown.
@@ -293,10 +441,32 @@ export function createApiClient(opts) {
     const sleep = opts.sleep ?? defaultSleep;
     const unauthorized = () => (opts.onUnauthorized ? opts.onUnauthorized() : new UnauthorizedError(service));
     const retryStatuses = retry.statuses ?? [429];
-    const timeoutMs = opts.timeout;
+    const timeoutMs = opts.timeout === false ? 0 : (opts.timeout ?? DEFAULT_REQUEST_TIMEOUT_MS);
+    const redirectMode = opts.redirect;
+    const maxRedirects = opts.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
+    const reportWriteOutcome = opts.writeOutcomeUnknown !== false;
+    const defaultMaxBytes = checkMaxBytes('maxResponseBytes', opts.maxResponseBytes);
+    // NaN would make `hops >= maxRedirects` never true: an endless redirect loop.
+    if (!Number.isSafeInteger(maxRedirects) || maxRedirects < 0) {
+        throw new TypeError(`createApiClient: maxRedirects must be a non-negative integer, got ${String(maxRedirects)}.`);
+    }
     // Default: `Authorization: Bearer <token>`. With `tokenHeader`, the raw
     // token goes in that named header instead (no `Bearer ` prefix).
     const authHeader = (token) => !token ? {} : opts.tokenHeader ? { [opts.tokenHeader]: token } : { Authorization: `Bearer ${token}` };
+    /**
+     * Errors that came out of the TRANSPORT — `fetch` itself, or reading a
+     * response body — as opposed to whatever else runs in between (a
+     * `tokenManager` refresh, a redirect refusal, JSON parsing). Only these,
+     * and this client's own {@link RequestTimeoutError}, make a write's
+     * outcome unknown.
+     */
+    const transportFailures = new WeakSet();
+    const markTransportFailure = (err) => {
+        // A cancellation is not a failure: the caller's abort is rethrown untouched.
+        if (typeof err === 'object' && err !== null && err.name !== 'AbortError') {
+            transportFailures.add(err);
+        }
+    };
     // Bound `run` with an AbortController when a timeout is configured, mapping the
     // abort to a RequestTimeoutError. No timeout → no timer (the caller's
     // cancellation still applies).
@@ -311,9 +481,9 @@ export function createApiClient(opts) {
         // NO TIMEOUT is no longer "no signal": a service configured without one
         // still honours the caller, which is the case where it matters most,
         // since nothing else was ever going to stop that request.
-        if (timeoutMs == null || timeoutMs <= 0) {
+        if (timeoutMs <= 0) {
             const res = await run(withAmbientCancellation(undefined));
-            return { res, done: () => { }, expired: undefined };
+            return { res, done: () => { }, expired: undefined, timedOut: () => false };
         }
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), timeoutMs);
@@ -340,7 +510,7 @@ export function createApiClient(opts) {
         });
         // Only observed if a body read is racing it; never an unhandled rejection.
         expired.catch(() => { });
-        return { res, done: () => clearTimeout(timer), expired };
+        return { res, done: () => clearTimeout(timer), expired, timedOut: () => controller.signal.aborted };
     }
     /**
      * Abandon `attempt` without reading its body: disarm the timer AND cancel
@@ -353,13 +523,7 @@ export function createApiClient(opts) {
      */
     function discard(attempt) {
         attempt.done();
-        try {
-            const body = attempt.res.body;
-            body?.cancel?.()?.catch(() => { });
-        }
-        catch {
-            // A body that refuses cancellation has nothing left to release.
-        }
+        cancelBody(attempt.res);
     }
     /**
      * Read the body of `attempt` under its timeout, then disarm the timer.
@@ -374,15 +538,70 @@ export function createApiClient(opts) {
             return await Promise.race([read(attempt.res), attempt.expired]);
         }
         catch (err) {
-            if (err instanceof RequestTimeoutError) {
-                attempt.res.body?.cancel().catch(() => { });
+            // The body's own abort listener was registered (at fetch time) before
+            // the timer's, so when OUR timer fires its `AbortError` can win the
+            // race: that is still this timeout, not a caller cancellation.
+            const timeout = err instanceof RequestTimeoutError ||
+                (err instanceof Error && err.name === 'AbortError' && attempt.timedOut());
+            if (timeout) {
+                cancelBody(attempt.res);
+                throw err instanceof RequestTimeoutError ? err : new RequestTimeoutError(service, timeoutMs);
             }
+            // The response arrived; only its size was refused. Not a transport
+            // failure, so a write that hit the cap is not outcome-unknown.
+            if (!(err instanceof ResponseTooLargeError))
+                markTransportFailure(err);
             throw err;
         }
         finally {
             attempt.done();
         }
     }
+    /**
+     * The body of `attempt` as bytes under `maxBytes` (`undefined` = no cap),
+     * through {@link readBody} so the timer, the timeout mapping and the
+     * transport-failure bookkeeping are the same as an uncapped read. Uncapped,
+     * it is exactly the historical `arrayBuffer()` read.
+     */
+    function readBytes(attempt, maxBytes) {
+        if (maxBytes === undefined)
+            return readBody(attempt, async (r) => new Uint8Array(await r.arrayBuffer()));
+        // Not redundant with readBody's own race: that one rejects the CALL on
+        // timeout, but the reader holds the stream's lock, so readBody's
+        // `cancelBody` cannot cancel it. Racing each `read()` makes the pending
+        // read reject too, and readBytesCapped then cancels the reader itself, so a
+        // stalled body is released instead of held until GC.
+        const race = (p) => (attempt.expired ? Promise.race([p, attempt.expired]) : p);
+        return readBody(attempt, (r) => readBytesCapped(r, maxBytes, service, race));
+    }
+    /** The body as text under `maxBytes`; uncapped, exactly `res.text()`. */
+    async function readText(attempt, maxBytes) {
+        if (maxBytes === undefined)
+            return readBody(attempt, (r) => r.text());
+        return new TextDecoder().decode(await readBytes(attempt, maxBytes));
+    }
+    /**
+     * A non-2xx's error body under the cap. Over it, the body is dropped ('')
+     * so the caller still throws the status-carrying {@link ApiError} rather
+     * than a size error that hides the status.
+     */
+    function readErrorText(attempt, maxBytes) {
+        return readText(attempt, maxBytes).catch((err) => {
+            if (err instanceof ResponseTooLargeError)
+                return '';
+            throw err;
+        });
+    }
+    /**
+     * A 401 / 429 body read only to scan it for an edge refusal page, under the
+     * call's cap. Any failure — over the cap, the timer, a broken stream — is
+     * no evidence of a block (''), so the status-specific error still throws.
+     */
+    function scanText(attempt, maxBytes) {
+        return readText(attempt, maxBytes).catch(() => '');
+    }
+    /** This call's cap: its own `maxBytes`, else the client default. */
+    const capOf = (opt) => opt.maxBytes !== undefined ? checkMaxBytes('maxBytes', opt.maxBytes) : defaultMaxBytes;
     // The base's own origin and userinfo. A baseUrl may legitimately carry
     // userinfo (`https://u:pw@host`); a resolved URL must then carry exactly
     // that userinfo, never a different or newly-introduced one.
@@ -405,6 +624,19 @@ export function createApiClient(opts) {
      * can neither introduce nor change it. Checked before any token is minted.
      */
     function resolveUrl(path, query) {
+        // Dot segments and backslashes first: they stay on the base ORIGIN, so the
+        // origin check below never saw them, but normalisation rewrites them —
+        // `/trails/../admin` is sent as `/admin` with the credential attached
+        // (fleet audit 2026-09, cluster 5). `encodeURIComponent('..')` is `..`,
+        // so encoding the value was never enough; see `apiPath`.
+        const hazard = findPathHazard(path);
+        if (hazard !== undefined) {
+            throw new Error(
+            // Quote only the path part: this fires on hostile input, and the
+            // query may carry values that do not belong in a log line.
+            `Refusing request to ${service}: path ${JSON.stringify(path.split(/[?#]/, 1)[0])} contains a ${hazard}, which URL ` +
+                'normalisation would rewrite. Build paths with apiPath`...` so each value is one encoded segment.');
+        }
         const url = `${base}${path}${query}`;
         if (baseOrigin === undefined)
             return url; // unparseable base: nothing to compare against
@@ -423,25 +655,80 @@ export function createApiClient(opts) {
         }
         return url;
     }
-    async function send(method, path, opt) {
+    /**
+     * Resolve a redirect's `Location` against the URL that returned it and
+     * refuse it unless it stays on the base origin with the base's own
+     * userinfo — the same rule {@link resolveUrl} applies to a path. The message
+     * names only the target origin: the rest may carry a token.
+     */
+    function sameOriginHop(location, from) {
+        let next;
+        try {
+            next = new URL(location, from);
+        }
+        catch {
+            throw new RedirectRefusedError(`Refusing redirect from ${service}: the Location header is not a valid URL.`);
+        }
+        if (baseOrigin === undefined ||
+            next.origin !== baseOrigin ||
+            next.username !== baseParts?.username ||
+            next.password !== baseParts?.password) {
+            throw new RedirectRefusedError(`Refusing redirect from ${service} to ${next.origin}: it leaves the base origin ${baseOrigin ?? '(unparseable)'}, ` +
+                'and following it would re-send the credential there.');
+        }
+        return next.href;
+    }
+    async function send(method, path, opt, dispatch) {
         const { body: reqBody, contentType } = encodeBody(opt);
         const query = opt.query ? buildQueryString(opt.query) : '';
         const url = resolveUrl(path, query);
         const bodyInit = reqBody !== undefined ? { body: reqBody } : {};
         // One fetch with the given token; Authorization comes last from the auth
         // mechanism, then per-request headers can still override it if needed.
-        const fetchWith = (token, signal) => doFetch(url, {
-            method,
-            headers: {
-                Accept: 'application/json',
-                ...(contentType !== undefined ? { 'Content-Type': contentType } : {}),
-                ...opts.baseHeaders,
-                ...authHeader(token || undefined),
-                ...opt.headers,
-            },
-            ...(signal ? { signal } : {}),
-            ...bodyInit,
-        });
+        const fetchHop = (hopUrl, hopMethod, withBody, token, signal) => {
+            // A fetch handed an already-aborted signal rejects without sending.
+            if (!signal?.aborted)
+                dispatch.sent = true;
+            return doFetch(hopUrl, {
+                method: hopMethod,
+                headers: {
+                    Accept: 'application/json',
+                    ...(withBody && contentType !== undefined ? { 'Content-Type': contentType } : {}),
+                    ...opts.baseHeaders,
+                    ...authHeader(token || undefined),
+                    ...opt.headers,
+                },
+                ...(signal ? { signal } : {}),
+                ...(redirectMode !== undefined ? { redirect: redirectMode === 'same-origin' ? 'manual' : redirectMode } : {}),
+                ...(withBody ? bodyInit : {}),
+            }).catch((err) => {
+                markTransportFailure(err);
+                throw err;
+            });
+        };
+        const fetchWith = async (token, signal) => {
+            if (redirectMode !== 'same-origin')
+                return fetchHop(url, method, true, token, signal);
+            let hopUrl = url;
+            let hopMethod = method;
+            let withBody = true;
+            for (let hops = 0;; hops += 1) {
+                const res = await fetchHop(hopUrl, hopMethod, withBody, token, signal);
+                const location = REDIRECT_STATUSES.has(res.status) ? responseHeader(res, 'location') : undefined;
+                if (location === undefined || location === null)
+                    return res;
+                cancelBody(res);
+                if (hops >= maxRedirects) {
+                    throw new RedirectRefusedError(`Refusing request to ${service}: too many redirects (more than ${maxRedirects}).`);
+                }
+                hopUrl = sameOriginHop(location, hopUrl);
+                if (res.status === 303 || ((res.status === 301 || res.status === 302) && hopMethod === 'POST')) {
+                    if (hopMethod !== 'HEAD')
+                        hopMethod = 'GET';
+                    withBody = false;
+                }
+            }
+        };
         // tokenManager (reactive refresh + 401-replay) takes precedence over getToken.
         // Each attempt is wrapped by withTimeout, so the abort signal reaches fetch
         // through whichever auth path is in play.
@@ -482,14 +769,14 @@ export function createApiClient(opts) {
      * be read is treated as no evidence of a block. The body is only scanned,
      * never echoed, so the token cannot leak through it.
      */
-    async function unauthorizedOrEdge(attempt, method, path) {
+    async function unauthorizedOrEdge(attempt, method, path, maxBytes) {
         const res = attempt.res;
         let text = '';
         if (/json/i.test(responseHeader(res, 'content-type') ?? '')) {
             discard(attempt);
         }
         else {
-            text = await readBody(attempt, (r) => r.text()).catch(() => '');
+            text = await scanText(attempt, maxBytes);
         }
         const edge = detectEdgeBlock({ body: text, headers: res.headers, status: res.status });
         if (edge)
@@ -503,7 +790,7 @@ export function createApiClient(opts) {
      * for an edge refusal page (same rule and JSON short-cut as
      * {@link unauthorizedOrEdge}), then the hook gets the whole context.
      */
-    async function rateLimitedError(attempt, method, path) {
+    async function rateLimitedError(attempt, method, path, maxBytes) {
         const res = attempt.res;
         const retryAfter = responseHeader(res, 'retry-after');
         const retryAfterMs = retryAfterToMs(retryAfter);
@@ -516,61 +803,99 @@ export function createApiClient(opts) {
             discard(attempt);
         }
         else {
-            text = await readBody(attempt, (r) => r.text()).catch(() => '');
+            text = await scanText(attempt, maxBytes);
         }
         const edgeBlock = detectEdgeBlock({ body: text, headers: res.headers, status: res.status });
         return opts.onRateLimited({ status: res.status, retryAfter, retryAfterMs, edgeBlock, method, path });
     }
-    async function fetchJson(method, path, opt = {}) {
-        const attempt = await send(method, path, opt);
+    /**
+     * Run one client call, turning a SENT write's transport failure into
+     * {@link WriteOutcomeUnknownError}. Everything else — a read, an
+     * `idempotent` request, a failure before anything was sent, any HTTP
+     * response, a caller's cancellation — propagates exactly as before.
+     */
+    async function guardWrite(method, opt, call) {
+        const dispatch = { sent: false };
+        try {
+            return await call(dispatch);
+        }
+        catch (err) {
+            const write = reportWriteOutcome && opt.idempotent !== true && !SAFE_METHODS.has(method.toUpperCase());
+            if (!write || !dispatch.sent)
+                throw err;
+            if (err instanceof RequestTimeoutError) {
+                throw new WriteOutcomeUnknownError(service, method, {
+                    timeoutMs: err.timeoutMs,
+                    cause: err,
+                    hint: opts.writeOutcomeHint,
+                });
+            }
+            if (typeof err === 'object' && err !== null && transportFailures.has(err)) {
+                throw new WriteOutcomeUnknownError(service, method, { cause: err, hint: opts.writeOutcomeHint });
+            }
+            throw err;
+        }
+    }
+    const fetchJson = (method, path, opt = {}) => guardWrite(method, opt, (dispatch) => fetchJsonOnce(method, path, opt, dispatch));
+    const fetchHtml = (method, path, opt = {}) => guardWrite(method, opt, (dispatch) => fetchHtmlOnce(method, path, opt, dispatch));
+    const fetchRaw = (method, path, opt = {}) => guardWrite(method, opt, (dispatch) => fetchRawOnce(method, path, opt, dispatch));
+    async function fetchJsonOnce(method, path, opt, dispatch) {
+        const maxBytes = capOf(opt);
+        const attempt = await send(method, path, opt, dispatch);
         const res = attempt.res;
         if (res.status === 401)
-            throw await unauthorizedOrEdge(attempt, method, path);
+            throw await unauthorizedOrEdge(attempt, method, path, maxBytes);
         if (res.status === 429)
-            throw await rateLimitedError(attempt, method, path);
+            throw await rateLimitedError(attempt, method, path, maxBytes);
         if (res.status === 204) {
             discard(attempt);
-            return undefined;
+            return parseJsonBody('', { expect: opt.expect, service, method, path, status: 204 });
         }
-        const text = await readBody(attempt, (r) => r.text());
         if (!res.ok) {
-            throw httpError(res, text, method, path, service);
+            throw httpError(res, await readErrorText(attempt, maxBytes), method, path, service);
         }
-        if (text.length === 0)
-            return undefined;
-        return JSON.parse(text);
+        const text = await readText(attempt, maxBytes);
+        return parseJsonBody(text, {
+            expect: opt.expect,
+            service,
+            method,
+            path,
+            status: res.status,
+            headers: res.headers,
+        });
     }
-    async function fetchHtml(method, path, opt = {}) {
+    async function fetchHtmlOnce(method, path, opt, dispatch) {
+        const maxBytes = capOf(opt);
         const headers = { Accept: 'text/html,*/*', ...opt.headers };
-        const attempt = await send(method, path, { ...opt, headers });
+        const attempt = await send(method, path, { ...opt, headers }, dispatch);
         const res = attempt.res;
         if (res.status === 401)
-            throw await unauthorizedOrEdge(attempt, method, path);
+            throw await unauthorizedOrEdge(attempt, method, path, maxBytes);
         if (res.status === 429)
-            throw await rateLimitedError(attempt, method, path);
-        const text = await readBody(attempt, (r) => r.text());
+            throw await rateLimitedError(attempt, method, path, maxBytes);
         if (!res.ok) {
-            throw httpError(res, text, method, path, service);
+            throw httpError(res, await readErrorText(attempt, maxBytes), method, path, service);
         }
-        return text;
+        return readText(attempt, maxBytes);
     }
-    async function fetchRaw(method, path, opt = {}) {
+    async function fetchRawOnce(method, path, opt, dispatch) {
+        const maxBytes = capOf(opt);
         const headers = { Accept: '*/*', ...opt.headers };
-        const attempt = await send(method, path, { ...opt, headers });
+        const attempt = await send(method, path, { ...opt, headers }, dispatch);
         const res = attempt.res;
         if (res.status === 401)
-            throw await unauthorizedOrEdge(attempt, method, path);
+            throw await unauthorizedOrEdge(attempt, method, path, maxBytes);
         if (res.status === 429)
-            throw await rateLimitedError(attempt, method, path);
+            throw await rateLimitedError(attempt, method, path, maxBytes);
         if (!res.ok) {
-            const text = await readBody(attempt, (r) => r.text()).catch((err) => {
+            const text = await readText(attempt, maxBytes).catch((err) => {
                 if (err instanceof RequestTimeoutError)
                     throw err;
                 return '';
             });
             throw httpError(res, text, method, path, service);
         }
-        const bytes = new Uint8Array(await readBody(attempt, (r) => r.arrayBuffer()));
+        const bytes = await readBytes(attempt, maxBytes);
         return {
             status: res.status,
             contentType: responseHeader(res, 'content-type'),
@@ -580,6 +905,18 @@ export function createApiClient(opts) {
     }
     return { fetchJson, fetchHtml, fetchRaw };
 }
+/**
+ * Validate a byte cap: `undefined` passes through; anything but a
+ * non-negative number throws, since `NaN` would silently mean "no cap".
+ */
+function checkMaxBytes(name, value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'number' || Number.isNaN(value) || value < 0) {
+        throw new TypeError(`createApiClient: ${name} must be a non-negative number, got ${String(value)}.`);
+    }
+    return value === Infinity ? undefined : value;
+}
 // ---------------------------------------------------------------------------
 // buildQueryString
 // ---------------------------------------------------------------------------
@@ -783,6 +1120,45 @@ function setCookieEntries(source) {
     const joined = source.get('set-cookie');
     return joined ? splitSetCookie(joined) : [];
 }
+/**
+ * Apply a response's `Set-Cookie`s to a caller-owned name→value jar, in place,
+ * and report whether the jar changed (so the caller knows when to persist it).
+ *
+ *  - A deletion marker — `Max-Age <= 0`, an `Expires` before 2000 (comma- or
+ *    dash-format epoch), or an **empty value** — removes the name. Unlike
+ *    {@link CookieJar.absorb}, an empty value is a delete here, so a cleared
+ *    session cookie never lingers in a persisted jar as `name=`.
+ *  - Any other entry sets the name (later entries win).
+ *  - Entries with no name (`=v`, `noequals`) are ignored.
+ *
+ * Returns `true` only when a value was added, replaced with a different value,
+ * or removed; re-setting an identical value or deleting an absent name is
+ * `false`. Accepts the same sources as {@link CookieJar.absorb}: a `Headers`
+ * object (prefers `getSetCookie()`), the `getSetCookie()` array, or a single
+ * comma-joined string (split safely around `Expires` commas).
+ *
+ * Consolidates the hand-rolled `getSetCookie` absorb loops in artsonia,
+ * canvas-parent, crowntowncompost, evite, infinitecampus, myatriumhealth, ofw
+ * and simplepractice (myatriumhealth's stored deletions as empty values).
+ */
+export function mergeSetCookies(jar, setCookie) {
+    let changed = false;
+    for (const entry of setCookieEntries(setCookie)) {
+        const pair = parseNameValue(entry);
+        if (!pair)
+            continue;
+        if (!pair.value || isDeletionCookie(entry)) {
+            if (jar.delete(pair.name))
+                changed = true;
+            continue;
+        }
+        if (jar.get(pair.name) !== pair.value) {
+            jar.set(pair.name, pair.value);
+            changed = true;
+        }
+    }
+    return changed;
+}
 /**
  * Stateful cookie jar for multi-step session logins (login page → CSRF prime →
  * credential POST → API calls), built on the {@link parseCookieJar} semantics.