@hunt-labs/bytekit-cli 0.3.0 → 0.6.0

package/dist/client.js

@@ -18,6 +18,24 @@ export const MIN_RETRY_AFTER_MS = 1_000;
 export const MAX_RETRY_AFTER_MS = 60_000;
 /** Exactly one retry. A second 429 is terminal — no loop. */
 export const MAX_RETRIES = 1;
+/**
+ * Cap on a best-effort, discard-only body drain (#2587 cr2-1). Independent of the per-attempt
+ * abort budget: the 429 drain below (`response.text().catch(() => {})`) exists ONLY so undici can
+ * return the socket to the connection pool — nothing downstream reads the drained bytes — but
+ * binding that read to the FULL per-attempt budget (120 s default, or, under `timeoutMs <= 0`,
+ * to no bound at all) let a stalled 429 body burn the whole budget, or hang forever, before a
+ * retry that needs nothing from that body. Short enough that a legitimately stalled 429 body costs
+ * the retry very little wall-clock time.
+ *
+ * #2587 cr3-2: past this cap, the read is not merely abandoned — {@link drainBestEffort} actively
+ * ABORTS its underlying request. Resolving the race without aborting anything (the earlier
+ * cr2-1 shape) let the retry proceed on schedule while the abandoned `response.text()` kept
+ * reading against a live socket forever, which — because the CLI exits via a soft
+ * `process.exitCode` (#2544) rather than `process.exit()` — kept the whole process alive
+ * indefinitely. `.catch`-guarding the read only made it safe to abandon the RESULT; it never made
+ * abandoning the underlying READ safe.
+ */
+export const DRAIN_TIMEOUT_MS = 2_000;
 /**
  * Default CLIENT-SIDE abort budget for a single fetch attempt, in ms.
  *
@@ -36,34 +54,79 @@ function timeoutReason(ms) {
     return reason;
 }
 /**
- * A per-attempt abort budget: an `AbortController` fired by a `setTimeout`.
+ * A per-attempt abort budget: an `AbortController`, optionally fired by a `setTimeout`.
+ *
+ * The budget spans the WHOLE attempt — time-to-headers **and** the response body read (#2546).
+ * Arming it only until headers arrive left `response.text()` / `response.arrayBuffer()` unbounded,
+ * so a server that answered with headers and then stalled its body hung the CLI forever.
+ *
+ * The controller ALWAYS exists, even when `ms <= 0` — only its own timeout timer is conditional
+ * on `ms > 0`. `sendWithRetry`'s 429-drain cap ({@link DRAIN_TIMEOUT_MS}, via the returned
+ * `abort()`) needs a live controller to tear down an abandoned body read regardless of whether the
+ * OVERALL per-attempt budget is enabled — `ms <= 0` must still mean "no full-attempt timeout", not
+ * "no controller to abort a stalled drain with" (#2587 cr3-2: the earlier drain fix abandoned the
+ * read entirely rather than aborting it, so the socket — and the event loop — stayed alive
+ * indefinitely, worse than the pre-fix baseline it replaced).
  *
  * Deliberately NOT `AbortSignal.timeout` (which the SDK prefers): that schedules on a timer the
  * test runner's fake timers cannot advance, so the transport's timeout would be untestable under
  * `vi.useFakeTimers()`. CLI requests are short-lived and single-shot, so the GC advantage
  * `AbortSignal.timeout` buys the long-running SDK does not apply here. The timer is `unref`'d so a
  * pending budget never keeps the process alive, and `cleanup()` clears it on every exit path.
+ *
+ * Exported so `lib/download-artifact.ts` can reuse the same budget for the artifact-download path
+ * (#2587) rather than growing a second timeout implementation — that path sits entirely outside
+ * `sendWithRetry` (it is not a JSON/raw API call), so it would otherwise never inherit this bound.
  */
-function createAttemptBudget(ms) {
+export function createAttemptBudget(ms) {
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(timeoutReason(ms)), ms);
-    timer.unref?.();
+    let timer;
+    if (ms > 0) {
+        timer = setTimeout(() => controller.abort(timeoutReason(ms)), ms);
+        timer.unref?.();
+    }
     return {
         signal: controller.signal,
-        cleanup: () => clearTimeout(timer),
+        cleanup: () => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        },
+        abort: (reason) => controller.abort(reason),
     };
 }
+/** The `name` of an error-shaped value, or `undefined` when it carries none. */
+const nameOf = (e) => typeof e === 'object' && e !== null && 'name' in e ? String(e.name) : undefined;
+/** The `cause` of an error-shaped value, or `undefined` when it carries none. */
+const causeOf = (e) => typeof e === 'object' && e !== null && 'cause' in e ? e.cause : undefined;
 /**
- * Map a `fetch` rejection (no HTTP response was produced) onto the SDK's `ByteKitConnectionError`
- * taxonomy, so a CLI failure carries the same `{name, code, cause}` a direct SDK call would.
+ * The abort-taxonomy name of a rejection, seeing through undici's mid-body wrapper.
+ *
+ * When a request is aborted while its BODY is streaming, undici does not reject with the abort
+ * reason itself — it rejects with `TypeError: terminated` carrying the reason on `.cause` (#2546).
+ * A name-only check would read that as a plain connection failure. Nothing that reached this
+ * function before #2546 carried a `.cause`, so every previously-asserted classification is
+ * unchanged; a `.cause` whose own name is not abort-shaped still falls through to `'connection'`.
+ */
+function abortNameOf(err) {
+    const top = nameOf(err);
+    if (top === 'TimeoutError' || top === 'AbortError')
+        return top;
+    return nameOf(causeOf(err));
+}
+/**
+ * Map a `fetch` or body-read rejection (no usable HTTP payload was produced) onto the SDK's
+ * `ByteKitConnectionError` taxonomy, so a CLI failure carries the same `{name, code, cause}` a
+ * direct SDK call would.
  *
  * `timedOut` is true when this attempt's own budget fired the abort, which is the reliable
- * discriminator (undici rejects with the signal's reason, whose `name` we also inspect as a
- * fallback for a caller-style AbortError).
+ * discriminator (undici rejects with the signal's reason — or a wrapper carrying it, see
+ * {@link abortNameOf} — whose `name` we also inspect as a fallback for a caller-style AbortError).
+ *
+ * Exported so `lib/download-artifact.ts` reuses the same taxonomy for the artifact-download path
+ * (#2587) instead of hand-rolling a second error mapping.
  */
-function toConnectionError(err, method, path, timedOut) {
-    const rawName = typeof err === 'object' && err !== null && 'name' in err ? err.name : undefined;
-    const name = typeof rawName === 'string' ? rawName : '';
+export function toConnectionError(err, method, path, timedOut) {
+    const name = abortNameOf(err) ?? '';
     let code;
     if (timedOut || name === 'TimeoutError') {
         code = 'timeout';
@@ -105,19 +168,84 @@ function sleep(ms) {
     });
 }
 /**
- * Shape a failed response into the SDK's OWN error class, using the SDK's own body parsing.
+ * Read (and discard) `body`, TEARING DOWN its underlying request after `DRAIN_TIMEOUT_MS` if it
+ * has not settled by then (#2587 cr3-2). `body` must already be guarded against rejection by its
+ * caller — this function only races it against a short local timer, it never itself decides what
+ * a rejection means.
+ *
+ * `abort` MUST be the abort function of the SAME `AbortController` the read's request was made
+ * with. Merely resolving this promise when the cap fires (the earlier, defective version of this
+ * function) let the retry proceed promptly while the abandoned `response.text()` kept running
+ * against a live socket forever — nothing else in the process held a reference to that read, but
+ * the open socket itself kept the event loop alive, so the CLI's soft `process.exitCode` exit
+ * (#2544) never actually fired. `response.body?.cancel()` cannot substitute for this: `text()` has
+ * already locked the stream by the time this function is called (property 4), so cancelling the
+ * body is not an option — aborting the ORIGINAL request's controller is the only way left to
+ * release a read already in flight. This is the same mechanism `sendWithRetry`'s headers+body
+ * budget already relies on to bound a normal successful read (#2546), so it is a proven pattern:
+ * undici rejects the pending read when its controller aborts, and tears down the socket rather
+ * than leaving it open.
+ *
+ * Deliberately a plain `setTimeout` (not `AbortSignal.timeout`), same reasoning as
+ * {@link createAttemptBudget}: a timer scheduled that way cannot be advanced by the test runner's
+ * fake timers, which would make this cap untestable under `vi.useFakeTimers()`. The cap timer is
+ * cleared as soon as `body` itself settles, so a fast drain never leaves a stray timer pending;
+ * conversely, if `body` settles only AFTER the cap fires, that later settlement is simply ignored
+ * — abandoning the VALUE is always safe because the caller already discards it either way (only
+ * the underlying READ itself must not be left running, which `abort` above now guarantees).
+ */
+function drainBestEffort(body, abort) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const cap = setTimeout(() => {
+            if (!settled) {
+                settled = true;
+                abort(timeoutReason(DRAIN_TIMEOUT_MS));
+                resolve();
+            }
+        }, DRAIN_TIMEOUT_MS);
+        cap.unref?.();
+        void body.then(() => {
+            if (!settled) {
+                settled = true;
+                clearTimeout(cap);
+                resolve();
+            }
+        });
+    });
+}
+/**
+ * Shape a failed response into the SDK's OWN error class, mirroring the SDK's own `send()` body
+ * parsing (`packages/sdk-typescript/src/client.ts`) EXACTLY — precedence rule included — so
+ * `{status, code, message}` stays identical to what a direct SDK call would throw and
+ * `handleError()`'s `'status' in err` branch renders the same `Error: <message> (<code>, status:
+ * <n>)` either way.
+ *
+ * Two error-body shapes exist across the API:
+ *   - the canonical unified envelope `{error: {code, message}}` — tested FIRST, so it always wins;
+ *   - a flat vendor-masked shape `{error: "<code>"}` (e.g. `/v1/search` 502:
+ *     `{"error":"search_provider_error"}`, docs/api/openapi.yaml §/v1/search 502) — the flat form
+ *     is strictly a FALLBACK and can never override an envelope (#2541, mirrored here for #2586:
+ *     the CLI's own copy of this parser had drifted from the SDK's and still only read the
+ *     envelope shape, so a flat 502 rendered `internal_error` instead of `search_provider_error`).
  *
- * Reusing `ByteKitError` keeps `{status, code, message}` identical to what a direct SDK call
- * would throw, so `handleError()`'s `'status' in err` branch still renders
- * `Error: <message> (status: <n>)` and exits 1.
+ * The explicit `!== null` guard on the envelope check matters — `typeof null` is `'object'`.
  */
 async function toApiError(response) {
     let code = 'internal_error';
     let message = response.statusText;
     try {
         const json = (await response.json());
-        code = json.error?.code ?? code;
-        message = json.error?.message ?? message;
+        if (typeof json.error === 'object' && json.error !== null) {
+            code = json.error.code ?? code;
+            message = json.error.message ?? message;
+        }
+        else if (typeof json.error === 'string' && json.error.length > 0) {
+            // The string IS the error code. `message` falls back to it only when the response carried
+            // no statusText, so the thrown error is never message-empty.
+            code = json.error;
+            message = message || json.error;
+        }
     }
     catch {
         // leave defaults
@@ -125,64 +253,58 @@ async function toApiError(response) {
     return new ByteKitError(response.status, code, message);
 }
 /**
- * Is this request targeting a `/v1/fetch` CONTENT endpoint (POST or GET), whose body IS the fetched
- * content rather than a JSON envelope?
+ * Perform the authenticated round-trip with a single bounded retry on 429, returning whatever the
+ * caller's `readBody` continuation makes of the successful response.
  *
- * Keyed off the request TARGET, never the response content-type: a fetched page can itself serve
- * `application/json`, and that body must still be returned raw, not parsed. The `/v1/fetch/bulk`
- * job endpoints are NOT content endpoints — they return a JSON envelope and keep parsing as JSON.
- */
-function isFetchContentPath(path) {
-    return (path.split('?')[0] ?? path) === '/v1/fetch';
-}
-/** Title-Case an HTTP header name segment-by-segment: `x-fetch-status` → `X-Fetch-Status`. */
-function titleCaseHeader(name) {
-    return name
-        .split('-')
-        .map((seg) => seg.charAt(0).toUpperCase() + seg.slice(1).toLowerCase())
-        .join('-');
-}
-/** Collect the `X-Fetch-*` response headers into a Title-Cased metadata object. */
-function collectFetchMetadata(headers) {
-    const meta = {};
-    headers.forEach((value, key) => {
-        if (key.toLowerCase().startsWith('x-fetch-')) {
-            meta[titleCaseHeader(key)] = value;
-        }
-    });
-    return meta;
-}
-/**
- * Build the CLI's HTTP transport: the SDK's `request` contract, plus a single bounded retry on 429.
+ * This is the CLI's one transport core: it owns auth, the per-attempt abort budget, the 429 retry,
+ * and the error taxonomy — mirroring the SDK's own private `send()`. Taking the body reader as a
+ * continuation (rather than handing the `Response` back with its body unread) is what lets the two
+ * public transports built on it ({@link createRetryingRequest} and {@link createRetryingRequestRaw})
+ * differ ONLY in how they decode a successful body, so no endpoint can ever ride one behavior and
+ * miss the other (#2535: `/v1/fetch` silently bypassed the retry because only `request` was
+ * overridden) — while keeping the abort budget armed ACROSS that read (#2546).
+ *
+ * The budget spans headers **and** body. Returning the `Response` used to end the guarded region
+ * at the headers boundary, leaving `response.text()` / `response.arrayBuffer()` — and
+ * `toApiError`'s error-body `response.json()` — unbounded: a server that sent headers and then
+ * stalled its body hung the CLI forever. `readBody` therefore MUST only consume the stream;
+ * `JSON.parse` / `TextDecoder` run in the callers, OUTSIDE the guard, so a malformed body still
+ * surfaces its own parse error instead of being remapped to a connection error.
  *
- * Why the CLI owns the `fetch` instead of wrapping the SDK's `request()`: the SDK throws a
+ * The budget stays PER ATTEMPT: `cleanup()` runs in an attempt-wide `finally`, and the 429 retry
+ * sleep happens after that `finally` — so a retry can never be cut short by time already spent on
+ * the first attempt.
+ *
+ * Why the CLI owns the `fetch` instead of wrapping the SDK's transports: the SDK throws a
  * header-less `ByteKitError` and discards the `Response`, so a delegating wrapper can see
  * `status === 429` but can never read `Retry-After`. Owning the fetch is the only way to honor the
  * server's advertised backoff without editing the SDK.
  *
- * Every SDK resource dereferences `this.client.request` at call time, so installing this as an own
- * property of the client (see {@link buildClient}) routes *all* commands through it from one seam.
- *
  * Retries apply to 429 only. Non-429 statuses and network rejections propagate untouched.
  */
-export function createRetryingRequest(apiKey, baseUrl, timeoutMs = DEFAULT_TIMEOUT_MS) {
-    return async function request(method, path, body) {
-        for (let attempt = 0;; attempt++) {
-            const init = {
-                method,
-                headers: {
-                    Authorization: `Bearer ${apiKey}`,
-                    'Content-Type': 'application/json',
-                },
-            };
-            if (body !== undefined) {
-                init.body = JSON.stringify(body);
-            }
-            // Per-attempt abort budget: a fresh timer for THIS fetch. A budget of 0 disables it.
-            const budget = timeoutMs > 0 ? createAttemptBudget(timeoutMs) : undefined;
-            if (budget !== undefined) {
-                init.signal = budget.signal;
-            }
+async function sendWithRetry(apiKey, baseUrl, timeoutMs, method, path, body, readBody) {
+    for (let attempt = 0;; attempt++) {
+        const init = {
+            method,
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                'Content-Type': 'application/json',
+            },
+        };
+        if (body !== undefined) {
+            init.body = JSON.stringify(body);
+        }
+        // Per-attempt abort budget: a fresh controller for THIS attempt. `timeoutMs <= 0` disables
+        // the OVERALL attempt timer (unchanged), but the controller itself always exists — the 429
+        // drain below needs something to abort even when the full-attempt timeout is off (#2587
+        // cr3-2).
+        const budget = createAttemptBudget(timeoutMs);
+        init.signal = budget.signal;
+        // Set only by the 429-retry branch below — the one path that falls out of the `try` rather
+        // than returning or throwing. Left `undefined` on every other path, which never reaches the
+        // `sleep` after the `finally`.
+        let retryAfterMs;
+        try {
             let response;
             try {
                 response = await fetch(`${baseUrl}${path}`, init);
@@ -191,40 +313,179 @@ export function createRetryingRequest(apiKey, baseUrl, timeoutMs = DEFAULT_TIMEO
                 // No HTTP response was produced (timeout, abort, socket/DNS/TLS). Re-throw as the SDK's
                 // own ByteKitConnectionError so a hung server can never hang the CLI and a network failure
                 // no longer surfaces as a bare `Error: fetch failed`.
-                throw toConnectionError(err, method, path, budget?.signal.aborted === true);
-            }
-            finally {
-                // Clear the timer on every exit path — success, HTTP error, or abort — so a healthy
-                // request leaves no dangling 120s timer.
-                budget?.cleanup();
+                throw toConnectionError(err, method, path, budget.signal.aborted === true);
             }
             if (response.ok) {
-                // A /v1/fetch content response body IS the fetched content (HTML/markdown/binary), with its
-                // metadata in X-Fetch-* headers. Return the raw bytes untouched — JSON-parsing it is the
-                // #2467 DOA crash. Every other endpoint returns a JSON envelope, parsed below.
-                if (isFetchContentPath(path)) {
-                    const bodyBytes = Buffer.from(await response.arrayBuffer());
-                    const fetchResult = {
-                        __bytekitFetchBody: true,
-                        body: bodyBytes,
-                        metadata: collectFetchMetadata(response.headers),
-                    };
-                    return fetchResult;
+                try {
+                    return await readBody(response);
                 }
-                const text = await response.text();
-                if (response.status === 204 || text.trim().length === 0) {
-                    return undefined;
+                catch (err) {
+                    // A body read that never completes is aborted by the same budget; undici then rejects
+                    // the stream (#2546). Map it into the same taxonomy the headers phase uses.
+                    throw toConnectionError(err, method, path, budget.signal.aborted === true);
                 }
-                return JSON.parse(text);
             }
             if (response.status === 429 && attempt < MAX_RETRIES) {
-                await sleep(parseRetryAfterMs(response.headers.get('Retry-After')));
-                continue;
+                retryAfterMs = parseRetryAfterMs(response.headers.get('Retry-After'));
+                // This 429 body is never read on the retry path (only the headers/Retry-After matter), so
+                // it must be fully CONSUMED before the retry — not merely cancelled — for undici to
+                // reclaim the underlying socket for connection-pool reuse (#2587 dod-4).
+                //
+                // #2587 cr-3 correction: an earlier version of this fix used `response.body?.cancel()`,
+                // reasoning that cancelling let undici reclaim the socket. That is backwards —
+                // `cancel()` ABORTS the fetch and DESTROYS the socket rather than returning it to the
+                // pool. Measured against a real `node:http` server and real undici (5x 429->200
+                // sequences, counting `connection` events): `cancel()` was inert for the gateway's actual
+                // tiny-JSON 429 body (2 conns, identical to no drain at all) and strictly WORSE than no
+                // drain for a large body (7 conns vs 6). A full read via `response.text()` is what
+                // actually lets undici return the connection to the pool (2 conns at either size). The
+                // `.catch(() => {})` guard stays: a real body read can still reject on an already-errored
+                // or locked stream, and that must never turn a recoverable 429 into a hard failure.
+                //
+                // #2587 cr2-1 correction: the read above was previously awaited directly, bounded only by
+                // the FULL per-attempt abort budget (120 s default) or, under `timeoutMs <= 0`, by nothing
+                // at all — a stalled 429 body could burn the whole budget (or hang forever) before a retry
+                // that needs nothing from that body (`Retry-After` is already parsed above).
+                // {@link drainBestEffort} bounds the read by its own short, independent cap
+                // ({@link DRAIN_TIMEOUT_MS}) instead, so a stalled drain can never delay the retry by more
+                // than that cap regardless of the attempt budget's size or absence.
+                //
+                // #2587 cr3-2 correction: cr2-1's `drainBestEffort` bounded only how long the RETRY
+                // waited — the cap resolved the returned promise but never touched the abandoned
+                // `response.text()` call itself, which kept reading against a live (never-aborted) socket
+                // indefinitely. Because every CLI success path exits via a soft `process.exitCode`
+                // (#2544) rather than `process.exit()`, that orphaned read then kept the event loop open
+                // forever: strictly WORSE than the pre-#2587 baseline (which at least exited once its own
+                // unbounded read finally settled or errored). `drainBestEffort` now takes this attempt's
+                // own `budget.abort` and calls it when the cap fires, so the abandoned read is actually
+                // torn down — not merely ignored — and the socket (and the event loop) is released.
+                await drainBestEffort(response.text().catch(() => { }), budget.abort);
+            }
+            else {
+                // `toApiError` reads the error body, so it too runs inside the budget.
+                throw await toApiError(response);
             }
-            throw await toApiError(response);
         }
+        finally {
+            // Clear the timer on every exit path — success (body read included), HTTP error, or
+            // abort — so a healthy request leaves no dangling 120s timer.
+            budget.cleanup();
+        }
+        // OUTSIDE the budget's `finally`: the backoff is not spent against any attempt's budget, and
+        // the next attempt arms a fresh one. The `??` is unreachable in practice (only the branch
+        // that assigns `retryAfterMs` falls through to here) and exists solely to keep the delay a
+        // `number` without an assertion; it uses the same value `parseRetryAfterMs(null)` returns.
+        await sleep(retryAfterMs ?? DEFAULT_RETRY_AFTER_MS);
+    }
+}
+/**
+ * Build the CLI's JSON transport: the SDK's `request` contract, plus the single bounded 429 retry.
+ *
+ * Every SDK resource dereferences `this.client.request` at call time, so installing this as an own
+ * property of the client (see {@link buildClient}) routes all JSON commands through it from one
+ * seam. `/v1/fetch` does NOT ride this transport — it rides `requestRaw` (see
+ * {@link createRetryingRequestRaw}); `/v1/fetch/bulk` is a JSON job envelope and does.
+ *
+ * DECISION (#2586 dod-4): the 4th `RequestOptions` parameter of the SDK's contract is accepted
+ * here — so the signature matches `ByteKit['request']` exactly, closing the gap where a caller-typo
+ * of a 5th positional argument would silently no-op instead of a compile error — but deliberately
+ * NOT forwarded into `sendWithRetry`. Two reasons: (1) no CLI command constructs a `RequestOptions`
+ * today (no `--timeout` flag exists yet, and `signal` has no CLI-level source), so the parameter is
+ * always `undefined` in practice; (2) the CLI already owns a per-attempt abort budget with its own
+ * semantics (`createAttemptBudget`, `timeoutMs` above) that would need explicit composition with a
+ * caller `signal` to honor `RequestOptions` correctly (the SDK's `composeSignals`) — inventing that
+ * unexercised composition here, with no caller able to reach it, would be undertested surface for no
+ * present behavior change. If a future CLI flag needs per-call overrides, wire it through
+ * `sendWithRetry`'s `timeoutMs` (already per-attempt) at that point, with its own tests.
+ */
+export function createRetryingRequest(apiKey, baseUrl, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    return async function request(method, path, body, _options) {
+        // The reader consumes the stream and nothing else, so the abort budget covers the read
+        // (#2546) while the 204/empty guard and `JSON.parse` stay OUTSIDE the guarded region —
+        // a malformed 200 body must still surface its own SyntaxError, never a connection error.
+        // Read-first ordering is preserved verbatim from before #2546: `.text()` is called
+        // unconditionally, and only then is the status inspected.
+        const { status, text } = await sendWithRetry(apiKey, baseUrl, timeoutMs, method, path, body, async (response) => ({ status: response.status, text: await response.text() }));
+        if (status === 204 || text.trim().length === 0) {
+            return undefined;
+        }
+        return JSON.parse(text);
     };
 }
+/**
+ * Build the CLI's RAW transport: the SDK's `requestRaw` contract, plus the same bounded 429 retry.
+ *
+ * `/v1/fetch` returns the fetched content AS the body (HTML, markdown, or true binary) with its
+ * metadata in `X-Fetch-*` headers, so the SDK routes it through `requestRaw` rather than the JSON
+ * `request`. The CLI must override BOTH seams or fetch commands silently bypass the retry and the
+ * CLI's error taxonomy — the #2535 defect, where only `request` was replaced.
+ *
+ * The returned shape is the SDK's `requestRaw` contract verbatim (`{body, bytes, headers, status}`)
+ * so `FetchResource` builds an ordinary `FetchResult` from it and the CLI never forks fetch
+ * handling away from the SDK. `bytes` is byte-exact (binary-safe); `body` is the best-effort UTF-8
+ * decode, matching the SDK's own semantics.
+ *
+ * The 4th `RequestOptions` parameter is accepted but not forwarded — see the DECISION note on
+ * {@link createRetryingRequest}, which applies here verbatim. `FetchResource.create`/`get` DO thread
+ * a `requestOptions` argument through to this seam (unlike every other resource), but no CLI `fetch`
+ * command constructs one today (no `--timeout` flag), so it is still always `undefined` in practice.
+ */
+export function createRetryingRequestRaw(apiKey, baseUrl, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    return async function requestRaw(method, path, body, _options) {
+        // As in `createRetryingRequest`: the reader only drains the stream (so the abort budget
+        // covers it, #2546); the UTF-8 decode happens outside the guarded region.
+        const { bytes, headers, status } = await sendWithRetry(apiKey, baseUrl, timeoutMs, method, path, body, async (response) => ({
+            bytes: new Uint8Array(await response.arrayBuffer()),
+            headers: response.headers,
+            status: response.status,
+        }));
+        return {
+            body: new TextDecoder('utf-8').decode(bytes),
+            bytes,
+            headers,
+            status,
+        };
+    };
+}
+/**
+ * Build the CLI's header-carrying JSON transport: the SDK's `requestWithResponse` contract
+ * (`{data, headers, status}`, #2547), plus the same bounded 429 retry every other CLI transport
+ * gets.
+ *
+ * Unused by any CLI command today — `screenshots.createWithResponse` / `getWithResponse` and
+ * `sitemap.getWithResponse` all exist on the SDK surface but no command builds on them yet. It is
+ * still installed (see {@link buildClient}) rather than left un-overridden: the transport-coverage
+ * contract test (#2586 dod-3) derives its method list from the real SDK prototype, and leaving a
+ * transport method un-overridden is exactly how #2535 shipped broken — the first command that DOES
+ * call a `*WithResponse` resource method must not silently ride the bare SDK transport and skip the
+ * CLI's retry/timeout/error taxonomy.
+ *
+ * Same body-read shape as {@link createRetryingRequest} (204/empty → `undefined`, `JSON.parse`
+ * otherwise), with `headers` and `status` threaded through from the successful response alongside
+ * the parsed `data`. The 4th `RequestOptions` parameter is accepted but not forwarded — see the
+ * DECISION note on {@link createRetryingRequest}.
+ */
+export function createRetryingRequestWithResponse(apiKey, baseUrl, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    return async function requestWithResponse(method, path, body, _options) {
+        const { status, text, headers } = await sendWithRetry(apiKey, baseUrl, timeoutMs, method, path, body, async (response) => ({
+            status: response.status,
+            text: await response.text(),
+            headers: response.headers,
+        }));
+        const data = status === 204 || text.trim().length === 0 ? undefined : JSON.parse(text);
+        return { data, headers, status };
+    };
+}
+/**
+ * Strip a trailing slash (or run of them) from a base URL, mirroring the SDK's own constructor
+ * normalization verbatim (`packages/sdk-typescript/src/client.ts`, `/\/+$/`, #2481) — so
+ * `baseUrl + path` (every CLI-owned path already starts with `/`) never yields a double-slash URL.
+ * Only the trailing slash is removed; a path-carrying baseUrl (e.g. a reverse-proxy prefix
+ * `…/bytekit`) is preserved.
+ */
+function normalizeBaseUrl(url) {
+    return url.replace(/\/+$/, '');
+}
 /**
  * Build an authenticated SDK client from global CLI options.
  *
@@ -233,8 +494,19 @@ export function createRetryingRequest(apiKey, baseUrl, timeoutMs = DEFAULT_TIMEO
  *   baseUrl: --base-url flag → BYTEKIT_BASE_URL → DEFAULT_BASE_URL.
  * Exits with a descriptive error when no key is available.
  *
- * The returned client's `request` is replaced by the retrying transport, so every command inherits
- * the 429 retry from this one seam.
+ * The returned client's `request`, `requestRaw`, AND `requestWithResponse` are all replaced by the
+ * retrying transports, so every command inherits the 429 retry — JSON commands via `request`, the
+ * `/v1/fetch` content commands via `requestRaw`, and the header-carrying `*WithResponse` surface via
+ * `requestWithResponse`. Overriding only `request` is the #2535 defect: the SDK's fetch resource
+ * rides `requestRaw`, so fetch bypassed the retry and the CLI's error taxonomy entirely; leaving
+ * `requestWithResponse` un-overridden is the same class of defect (#2586) — it is unused by any CLI
+ * command TODAY, but a future command built on `screenshots.createWithResponse` /
+ * `sitemap.getWithResponse` would otherwise silently ride the bare SDK transport.
+ *
+ * `baseUrl` is normalized ONCE, here, before it reaches either the SDK constructor or the CLI's own
+ * transport builders below — the CLI's transports build their request URL from this local variable
+ * directly (they do not call the SDK's own normalized `send()`), so a trailing-slash flag would
+ * otherwise double-slash every request the CLI makes (#2586).
  */
 export function buildClient(opts) {
     const apiKey = opts.key ?? process.env['BYTEKIT_API_KEY'];
@@ -242,8 +514,10 @@ export function buildClient(opts) {
         console.error('Error: API key required. Pass --key or set BYTEKIT_API_KEY.');
         process.exit(1);
     }
-    const baseUrl = opts.baseUrl ?? process.env['BYTEKIT_BASE_URL'] ?? DEFAULT_BASE_URL;
+    const baseUrl = normalizeBaseUrl(opts.baseUrl ?? process.env['BYTEKIT_BASE_URL'] ?? DEFAULT_BASE_URL);
     const client = new ByteKit({ apiKey, baseUrl });
     client.request = createRetryingRequest(apiKey, baseUrl);
+    client.requestRaw = createRetryingRequestRaw(apiKey, baseUrl);
+    client.requestWithResponse = createRetryingRequestWithResponse(apiKey, baseUrl);
     return client;
 }

package/dist/commands/account.d.ts

@@ -1,5 +1,16 @@
 import { Command } from 'commander';
 import { type GlobalOptions } from '../client.js';
+/**
+ * The `account` command group.
+ *
+ * Key management is DELIBERATELY absent (#2536). Those operations are mounted behind
+ * `clerkSession(db)` in the gateway and are annotated `x-internal: true` / `x-sdk-scope: internal`
+ * in the OpenAPI spec, so a bearer `sk_` key — the CLI's only credential — can never satisfy them.
+ * Keys are managed from the dashboard instead. Widening the gateway to accept bearer auth was
+ * rejected on security grounds: the reveal operation returns the live plaintext of any key on the
+ * account and there is no per-key scope model, so any leaked key would become a full
+ * account-credential factory. `internal-scope-guard.test.ts` mechanically enforces this boundary.
+ */
 export declare function makeAccountCommand(getGlobal: () => GlobalOptions & {
     json: boolean;
 }): Command;