@hunt-labs/bytekit-cli 0.3.0 → 0.6.0

package/dist/lib/download-artifact.d.ts

@@ -9,5 +9,34 @@
  * test that stubs `globalThis.fetch` in a `beforeEach` — after this module was imported — still
  * sees its stub (G-049). A non-2xx response throws with the HTTP status so `handleError` renders a
  * clean one-liner and exits 1.
+ *
+ * TIMEOUT (#2587): this path sat entirely outside the transport seam — no abort signal, no
+ * connection-error taxonomy — so a stalled artifact host (headers, then a body that never
+ * completes) hung the CLI forever, even though the 0.5.0 CHANGELOG's "a stalled body hung the CLI
+ * forever" note (#2546) reads as if every response body were covered. #2546 only covered API-call
+ * bodies read through `sendWithRetry`; this download never rode that seam. The fix REUSES
+ * `sendWithRetry`'s own per-attempt abort budget and connection-error taxonomy
+ * (`createAttemptBudget` / `toConnectionError`, exported from `../client.js`) rather than a second
+ * timeout implementation, and mirrors the same default (`DEFAULT_TIMEOUT_MS`, 120 s per attempt) —
+ * there is no retry here, since artifact GETs are not the API's 429 domain.
+ *
+ * PARTIAL-FILE POLICY (#2587 dod-1 / E1, decided + recorded, scoped to the DOWNLOAD phase only —
+ * cr-4): the response is buffered COMPLETELY in memory (`res.arrayBuffer()`) before either write
+ * path (`writeFileSync` / `process.stdout.write`) runs, so an ABORT — whether from the timeout or
+ * any other connection failure — always fails BEFORE a single byte is written; no partial file is
+ * ever left at `dest` from a download-side failure. This does NOT cover a failure DURING the write
+ * itself: `writeFileSync` opens `dest` with `O_TRUNC` and writes in a loop, so e.g. an `ENOSPC`
+ * partway through a large write leaves a created, truncated file at `dest` (any pre-existing file
+ * there already clobbered by the `O_TRUNC` open). That failure mode is accepted as-is for now (no
+ * write-to-temp-then-`renameSync` here) — the CLI still exits 1, and the write phase's tiny
+ * (post-buffering) failure window is a separate, unaddressed edge from the abort guarantee above.
+ *
+ * @param timeoutMs Per-attempt abort budget in ms; defaults to {@link DEFAULT_TIMEOUT_MS} (120 s).
+ *   `<= 0` DISABLES the budget entirely (no `AbortSignal` is attached, restoring the exact
+ *   unbounded-hang behavior this ticket fixes) rather than meaning "no override" — there is no
+ *   sentinel for that. #2587 cr-8: no CLI command reaches this parameter today
+ *   (`commands/screenshots.ts` always calls the 2-arg form), so a future caller — e.g. an
+ *   anticipated `--timeout` flag threaded through here — must NOT pass `0` to mean "use the
+ *   default"; it must omit the argument or pass `DEFAULT_TIMEOUT_MS` explicitly.
  */
-export declare function downloadArtifact(url: string, dest: string): Promise<void>;
+export declare function downloadArtifact(url: string, dest: string, timeoutMs?: number): Promise<void>;

package/dist/lib/download-artifact.js

@@ -1,4 +1,25 @@
 import { writeFileSync } from 'node:fs';
+import { createAttemptBudget, toConnectionError, DEFAULT_TIMEOUT_MS } from '../client.js';
+/**
+ * Redact a URL for error-message rendering: origin + pathname only, query string dropped.
+ *
+ * #2587 cr-2: `image_url` for a completed screenshot is an AWS SigV4 PRESIGNED URL
+ * (`X-Amz-Credential=…&X-Amz-Signature=…`, `gateway/src/lib/signed-url.ts`), unlike every other
+ * `toConnectionError` call site in `client.ts` which passes a bare relative API path with no
+ * credential material. Rendering the full URL in `handleError`'s unmodified `err.message` would
+ * print a live 600s-valid signature to stderr on every new failure path this diff adds. On a
+ * malformed URL (should not happen — `image_url` is always an absolute URL from the API) fall
+ * back to the original string rather than throwing out of an error-handling path.
+ */
+function redactedPath(url) {
+    try {
+        const u = new URL(url);
+        return `${u.origin}${u.pathname}`;
+    }
+    catch {
+        return url;
+    }
+}
 /**
  * Download a screenshot artifact from its `image_url` and write the raw bytes to `dest`.
  *
@@ -10,13 +31,76 @@ import { writeFileSync } from 'node:fs';
  * test that stubs `globalThis.fetch` in a `beforeEach` — after this module was imported — still
  * sees its stub (G-049). A non-2xx response throws with the HTTP status so `handleError` renders a
  * clean one-liner and exits 1.
+ *
+ * TIMEOUT (#2587): this path sat entirely outside the transport seam — no abort signal, no
+ * connection-error taxonomy — so a stalled artifact host (headers, then a body that never
+ * completes) hung the CLI forever, even though the 0.5.0 CHANGELOG's "a stalled body hung the CLI
+ * forever" note (#2546) reads as if every response body were covered. #2546 only covered API-call
+ * bodies read through `sendWithRetry`; this download never rode that seam. The fix REUSES
+ * `sendWithRetry`'s own per-attempt abort budget and connection-error taxonomy
+ * (`createAttemptBudget` / `toConnectionError`, exported from `../client.js`) rather than a second
+ * timeout implementation, and mirrors the same default (`DEFAULT_TIMEOUT_MS`, 120 s per attempt) —
+ * there is no retry here, since artifact GETs are not the API's 429 domain.
+ *
+ * PARTIAL-FILE POLICY (#2587 dod-1 / E1, decided + recorded, scoped to the DOWNLOAD phase only —
+ * cr-4): the response is buffered COMPLETELY in memory (`res.arrayBuffer()`) before either write
+ * path (`writeFileSync` / `process.stdout.write`) runs, so an ABORT — whether from the timeout or
+ * any other connection failure — always fails BEFORE a single byte is written; no partial file is
+ * ever left at `dest` from a download-side failure. This does NOT cover a failure DURING the write
+ * itself: `writeFileSync` opens `dest` with `O_TRUNC` and writes in a loop, so e.g. an `ENOSPC`
+ * partway through a large write leaves a created, truncated file at `dest` (any pre-existing file
+ * there already clobbered by the `O_TRUNC` open). That failure mode is accepted as-is for now (no
+ * write-to-temp-then-`renameSync` here) — the CLI still exits 1, and the write phase's tiny
+ * (post-buffering) failure window is a separate, unaddressed edge from the abort guarantee above.
+ *
+ * @param timeoutMs Per-attempt abort budget in ms; defaults to {@link DEFAULT_TIMEOUT_MS} (120 s).
+ *   `<= 0` DISABLES the budget entirely (no `AbortSignal` is attached, restoring the exact
+ *   unbounded-hang behavior this ticket fixes) rather than meaning "no override" — there is no
+ *   sentinel for that. #2587 cr-8: no CLI command reaches this parameter today
+ *   (`commands/screenshots.ts` always calls the 2-arg form), so a future caller — e.g. an
+ *   anticipated `--timeout` flag threaded through here — must NOT pass `0` to mean "use the
+ *   default"; it must omit the argument or pass `DEFAULT_TIMEOUT_MS` explicitly.
  */
-export async function downloadArtifact(url, dest) {
-    const res = await globalThis.fetch(url);
-    if (!res.ok) {
-        throw new Error(`artifact download failed: HTTP ${res.status}`);
+export async function downloadArtifact(url, dest, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    const budget = timeoutMs > 0 ? createAttemptBudget(timeoutMs) : undefined;
+    const safePath = redactedPath(url);
+    let bytes;
+    try {
+        let res;
+        try {
+            res = await globalThis.fetch(url, budget ? { signal: budget.signal } : {});
+        }
+        catch (err) {
+            // No HTTP response was produced (timeout, abort, socket/DNS/TLS) — re-throw as the SDK's own
+            // ByteKitConnectionError, exactly like the API transport, so a hung/broken artifact host can
+            // never hang the CLI and `handleError` renders the same taxonomy either way. `safePath` (not
+            // `url`) is what gets rendered — see {@link redactedPath}.
+            throw toConnectionError(err, 'GET', safePath, budget?.signal.aborted === true);
+        }
+        if (!res.ok) {
+            // #2587 cr2-1: no drain here, unlike client.ts's 429 path. cr-11 originally added one
+            // (mirroring client.ts's corrected 429-drain mechanism, cr-3), reasoning that a full
+            // `text()` read lets undici return the connection to the pool. That reasoning does not
+            // apply on THIS path: `commands/screenshots.ts` throws this error straight into
+            // `handleError`, which `process.exit(1)`s immediately after — there is no next request in
+            // this process for a reclaimed socket to serve. A drain here was bounded only by the FULL
+            // per-attempt abort budget (or, under `timeoutMs <= 0`, by nothing at all) for zero benefit,
+            // so it is removed outright rather than merely capped.
+            throw new Error(`artifact download failed: HTTP ${res.status}`);
+        }
+        try {
+            bytes = Buffer.from(await res.arrayBuffer());
+        }
+        catch (err) {
+            // A body read that never completes is aborted by the same budget; undici then rejects the
+            // stream (mirrors #2546's body-read guard). Map it into the same taxonomy as above.
+            throw toConnectionError(err, 'GET', safePath, budget?.signal.aborted === true);
+        }
+    }
+    finally {
+        // Clear the timer on every exit path so a healthy download leaves no dangling budget timer.
+        budget?.cleanup();
     }
-    const bytes = Buffer.from(await res.arrayBuffer());
     if (dest === '-') {
         process.stdout.write(bytes);
         return;

package/dist/lib/parse-flags.d.ts

@@ -14,3 +14,33 @@ export declare function parseIntFlag(flag: string, value: string): number;
 export declare function parseEnum<T extends string>(flag: string, allowed: readonly T[], value: string): T;
 /** Split a comma-separated flag value into a trimmed, non-empty string array. */
 export declare function parseCsv(value: string): string[];
+/**
+ * Parse a finite decimal flag value (#2545). Unlike {@link parseIntFlag}, the `/^\d+(\.\d+)?$/`
+ * test accepts a fractional value such as `2.5` — required for spec `type: number` fields like
+ * `monitors change_threshold` (default 5, range 0–100) that `parseIntFlag`'s `/^\d+$/` would reject
+ * at parse time. Rejects `abc`, ``, `-5`, `1.` and `1e2` with the flag named in the message.
+ */
+export declare function parseNumberFlag(flag: string, value: string): number;
+/**
+ * Parse a `cache_ttl` flag value (#2545). Mirrors the gateway validator's own format grammar
+ * (`^(0|\d+[hd])$`, `packages/gateway/src/validators/shared.ts`) locally so an off-grammar value
+ * (`30m`, `soon`) is rejected at parse time with an actionable message instead of a server 422.
+ * The string is returned verbatim — the validator accepts the string `'0'`, and the range cap
+ * (7d/168h for scrape+fetch) stays a server-side concern.
+ */
+export declare function parseCacheTtl(flag: string, value: string): string;
+/**
+ * Parse a JSON-object- or JSON-array-valued flag (#2545). The ONLY `JSON.parse` call site for CLI
+ * flag values — every JSON-shaped flag (`--cookies`, `--headers`, `--custom`,
+ * `--webhook-headers`, `--options`, `--scrape-options`) routes through here, so command modules
+ * carry no raw `JSON.parse` (grep-gated). Rejects malformed JSON AND a value whose top-level shape
+ * does not match `expect`, with a copy-pasteable example in the message (E5).
+ */
+export declare function parseJsonFlag(flag: string, value: string, expect: 'object' | 'array'): unknown;
+/**
+ * Commander collector for a repeatable, CSV-aware `--format` flag (#2545). Each occurrence is
+ * CSV-split and appended to the accumulator, so `--format raw_html --format markdown` and
+ * `--format raw_html,markdown` both yield `['raw_html','markdown']`. Commander seeds `prev` with
+ * the option default (or the previous return) on each occurrence.
+ */
+export declare function collectFormats(value: string, prev: string[] | undefined): string[];

package/dist/lib/parse-flags.js

@@ -30,3 +30,61 @@ export function parseCsv(value) {
         .map((s) => s.trim())
         .filter((s) => s.length > 0);
 }
+/**
+ * Parse a finite decimal flag value (#2545). Unlike {@link parseIntFlag}, the `/^\d+(\.\d+)?$/`
+ * test accepts a fractional value such as `2.5` — required for spec `type: number` fields like
+ * `monitors change_threshold` (default 5, range 0–100) that `parseIntFlag`'s `/^\d+$/` would reject
+ * at parse time. Rejects `abc`, ``, `-5`, `1.` and `1e2` with the flag named in the message.
+ */
+export function parseNumberFlag(flag, value) {
+    if (!/^\d+(\.\d+)?$/.test(value)) {
+        throw new InvalidArgumentError(`${flag} must be a number.`);
+    }
+    return Number(value);
+}
+/**
+ * Parse a `cache_ttl` flag value (#2545). Mirrors the gateway validator's own format grammar
+ * (`^(0|\d+[hd])$`, `packages/gateway/src/validators/shared.ts`) locally so an off-grammar value
+ * (`30m`, `soon`) is rejected at parse time with an actionable message instead of a server 422.
+ * The string is returned verbatim — the validator accepts the string `'0'`, and the range cap
+ * (7d/168h for scrape+fetch) stays a server-side concern.
+ */
+export function parseCacheTtl(flag, value) {
+    if (!/^(0|\d+[hd])$/.test(value)) {
+        throw new InvalidArgumentError(`${flag} must be 0, Nh (hours), or Nd (days) — e.g. 48h, 2d, 0.`);
+    }
+    return value;
+}
+/**
+ * Parse a JSON-object- or JSON-array-valued flag (#2545). The ONLY `JSON.parse` call site for CLI
+ * flag values — every JSON-shaped flag (`--cookies`, `--headers`, `--custom`,
+ * `--webhook-headers`, `--options`, `--scrape-options`) routes through here, so command modules
+ * carry no raw `JSON.parse` (grep-gated). Rejects malformed JSON AND a value whose top-level shape
+ * does not match `expect`, with a copy-pasteable example in the message (E5).
+ */
+export function parseJsonFlag(flag, value, expect) {
+    const example = expect === 'array' ? `[{"name":"a","value":"b"}]` : `{"X-Header":"value"}`;
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw new InvalidArgumentError(`${flag} must be valid JSON (a ${expect}), e.g. '${example}'.`);
+    }
+    const matches = expect === 'array'
+        ? Array.isArray(parsed)
+        : typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed);
+    if (!matches) {
+        throw new InvalidArgumentError(`${flag} must be a JSON ${expect}, e.g. '${example}'.`);
+    }
+    return parsed;
+}
+/**
+ * Commander collector for a repeatable, CSV-aware `--format` flag (#2545). Each occurrence is
+ * CSV-split and appended to the accumulator, so `--format raw_html --format markdown` and
+ * `--format raw_html,markdown` both yield `['raw_html','markdown']`. Commander seeds `prev` with
+ * the option default (or the previous return) on each occurrence.
+ */
+export function collectFormats(value, prev) {
+    return [...(prev ?? []), ...parseCsv(value)];
+}

package/dist/lib/url-lines.d.ts

@@ -1,12 +1,50 @@
 /**
- * Read a newline-delimited file of URLs and return a flat array of URL strings.
+ * One parsed `--file` line: a bare URL string, or a per-item config object carrying `url`.
  *
- * Each non-blank line is either a plain URL or a JSON object of the form
- * `{"url":"https://..."}`. Both forms normalize to the bare URL string, because
- * the v1 bulk endpoints (`/v1/bulk`, `/v1/scrape/bulk`, `/v1/fetch/bulk`) expect
- * `urls` to be an array of URL strings — NOT an array of objects.
+ * The two arms are not interchangeable on the wire. `/v1/bulk` and `/v1/scrape/bulk` accept
+ * `urls` (strings) XOR `items` (objects); `/v1/fetch/bulk` has no `items` property at all and
+ * takes a heterogeneous `urls` union. Callers pick the right shape — see {@link toBulkItems}.
+ */
+export type BulkLine = string | Record<string, unknown>;
+/**
+ * Read a newline-delimited `--file` and return one {@link BulkLine} per non-blank line.
+ *
+ * Line grammar:
+ * - a non-JSON line                            -> the raw line (a plain URL string)
+ * - a JSON object whose ONLY key is `url`      -> the bare url string
+ * - a JSON object carrying other keys too      -> the object verbatim (per-item config)
+ * - a JSON object with a missing/non-string url -> `InvalidArgumentError` (rejected locally)
+ * - a JSON non-object (number, array, string)  -> the raw line
+ *
+ * The "only key is `url`" arm is what keeps the inverse case BYTE-IDENTICAL rather than merely
+ * equivalent: a file of url-only lines produces the exact same `{ urls, webhook_url }` body as
+ * before per-item config existed (#2596 E2).
+ *
+ * Rejecting a malformed `url` is a deliberate behavior change (#2596 DoD 8). The previous parser
+ * fell through to the raw line, so `{"url": 123}` was sent to the server AS a URL — a confusing
+ * 422 for what is a local input mistake. `InvalidArgumentError` surfaces through the same
+ * local-usage-error path as every argParser rejection (exit 1), before any request is issued.
+ *
+ * Throws on a missing file (ENOENT from readFileSync) — callers surface this via their
+ * handleError path.
+ *
+ * The rejection message for a malformed line (#2596 cr-1 / E12) names the 1-based PHYSICAL line
+ * NUMBER (i.e. the line's own position in the file, counting blank lines) and the line's own KEY
+ * NAMES only — never the raw line or any value. A `--file` line is where per-item `cookies`,
+ * `headers`, and auth-bearing `metadata` now live (#2596), so echoing the raw line back would
+ * leak session tokens and similar secrets to stderr, CI logs, and shell transcripts. Because the
+ * raw line is deliberately never echoed, the line number is the ONLY locator left in the message —
+ * it must be computed BEFORE blank lines are filtered out, or it silently mis-locates the bad
+ * entry whenever the file contains blank lines above it (#2596 cr-2).
+ */
+export declare function parseBulkLines(file: string): BulkLine[];
+/**
+ * Promote every {@link BulkLine} to the `items[]` object shape used by `/v1/bulk` and
+ * `/v1/scrape/bulk`.
  *
- * Throws on a missing file (ENOENT from readFileSync) — callers surface this via
- * their handleError path.
+ * Deliberately stamps NOTHING beyond `url`. `/v1/bulk` owns capture-kind precedence server-side
+ * (per-item value, then `defaults`, then the endpoint default) since #2641 made the per-item
+ * field optional; a CLI-side default would silently override a caller's `--defaults` and is
+ * grep-gated out (#2596 G7).
  */
-export declare function parseUrlLines(file: string): string[];
+export declare function toBulkItems(lines: BulkLine[]): Array<Record<string, unknown>>;

package/dist/lib/url-lines.js

@@ -1,34 +1,73 @@
 import { readFileSync } from 'node:fs';
+import { InvalidArgumentError } from 'commander';
 /**
- * Read a newline-delimited file of URLs and return a flat array of URL strings.
+ * Read a newline-delimited `--file` and return one {@link BulkLine} per non-blank line.
  *
- * Each non-blank line is either a plain URL or a JSON object of the form
- * `{"url":"https://..."}`. Both forms normalize to the bare URL string, because
- * the v1 bulk endpoints (`/v1/bulk`, `/v1/scrape/bulk`, `/v1/fetch/bulk`) expect
- * `urls` to be an array of URL strings — NOT an array of objects.
+ * Line grammar:
+ * - a non-JSON line                            -> the raw line (a plain URL string)
+ * - a JSON object whose ONLY key is `url`      -> the bare url string
+ * - a JSON object carrying other keys too      -> the object verbatim (per-item config)
+ * - a JSON object with a missing/non-string url -> `InvalidArgumentError` (rejected locally)
+ * - a JSON non-object (number, array, string)  -> the raw line
  *
- * Throws on a missing file (ENOENT from readFileSync) — callers surface this via
- * their handleError path.
+ * The "only key is `url`" arm is what keeps the inverse case BYTE-IDENTICAL rather than merely
+ * equivalent: a file of url-only lines produces the exact same `{ urls, webhook_url }` body as
+ * before per-item config existed (#2596 E2).
+ *
+ * Rejecting a malformed `url` is a deliberate behavior change (#2596 DoD 8). The previous parser
+ * fell through to the raw line, so `{"url": 123}` was sent to the server AS a URL — a confusing
+ * 422 for what is a local input mistake. `InvalidArgumentError` surfaces through the same
+ * local-usage-error path as every argParser rejection (exit 1), before any request is issued.
+ *
+ * Throws on a missing file (ENOENT from readFileSync) — callers surface this via their
+ * handleError path.
+ *
+ * The rejection message for a malformed line (#2596 cr-1 / E12) names the 1-based PHYSICAL line
+ * NUMBER (i.e. the line's own position in the file, counting blank lines) and the line's own KEY
+ * NAMES only — never the raw line or any value. A `--file` line is where per-item `cookies`,
+ * `headers`, and auth-bearing `metadata` now live (#2596), so echoing the raw line back would
+ * leak session tokens and similar secrets to stderr, CI logs, and shell transcripts. Because the
+ * raw line is deliberately never echoed, the line number is the ONLY locator left in the message —
+ * it must be computed BEFORE blank lines are filtered out, or it silently mis-locates the bad
+ * entry whenever the file contains blank lines above it (#2596 cr-2).
  */
-export function parseUrlLines(file) {
+export function parseBulkLines(file) {
     return readFileSync(file, 'utf8')
         .split('\n')
-        .map((l) => l.trim())
-        .filter((l) => l.length > 0)
-        .map((line) => {
+        .map((raw, index) => ({ line: raw.trim(), lineNumber: index + 1 }))
+        .filter(({ line }) => line.length > 0)
+        .map(({ line, lineNumber }) => {
+        let parsed;
         try {
-            const parsed = JSON.parse(line);
-            if (parsed !== null && typeof parsed === 'object' && 'url' in parsed) {
-                const url = parsed.url;
-                if (typeof url === 'string')
-                    return url;
-            }
-            // Parsed as JSON but not a {url:string} object — fall back to the raw line.
-            return line;
+            parsed = JSON.parse(line);
         }
         catch {
             // Not JSON — treat the whole line as a plain URL string.
             return line;
         }
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            // Parsed as JSON but not an object — fall back to the raw line, as before.
+            return line;
+        }
+        const obj = parsed;
+        if (typeof obj['url'] !== 'string' || obj['url'].length === 0) {
+            const keys = Object.keys(obj).join(', ') || '(none)';
+            throw new InvalidArgumentError(`--file line ${lineNumber} must carry a non-empty string "url" (keys present: ${keys})`);
+        }
+        // A line whose only key is `url` is indistinguishable from a plain URL line — keep it a
+        // bare string so url-only files stay byte-identical on the wire.
+        return Object.keys(obj).length === 1 ? obj['url'] : obj;
     });
 }
+/**
+ * Promote every {@link BulkLine} to the `items[]` object shape used by `/v1/bulk` and
+ * `/v1/scrape/bulk`.
+ *
+ * Deliberately stamps NOTHING beyond `url`. `/v1/bulk` owns capture-kind precedence server-side
+ * (per-item value, then `defaults`, then the endpoint default) since #2641 made the per-item
+ * field optional; a CLI-side default would silently override a caller's `--defaults` and is
+ * grep-gated out (#2596 G7).
+ */
+export function toBulkItems(lines) {
+    return lines.map((l) => (typeof l === 'string' ? { url: l } : l));
+}

package/dist/output.d.ts

@@ -22,6 +22,24 @@ export interface OutputFlags {
     raw?: boolean | undefined;
     output?: string | undefined;
 }
+/**
+ * Serialize a value as the CLI's `--json` payload text. The single serializer EVERY `--json`
+ * branch in this module goes through, so no branch can regress to a raw `JSON.stringify`.
+ *
+ * `JSON.stringify` returns the VALUE `undefined` — not a string — for `undefined`, functions and
+ * symbols. Handed to `console.log` that prints the literal text `undefined`, which is NOT valid
+ * JSON and breaks every `| jq` pipeline; handed to `writeFileSync` it throws
+ * `ERR_INVALID_ARG_TYPE`. A `204 No Content` response resolves to `undefined` in the SDK
+ * (`monitors.delete` is typed `Promise<void>`), so this is the ORDINARY shape of
+ * `bytekit monitors delete <id> --json`, not an exotic edge case (#2544).
+ *
+ * The representation is JSON `null` — the canonical JSON spelling of "no content". Deliberately
+ * NOT a synthesized envelope such as `{"status":"deleted"}`: that is a shape the API never
+ * returned, and it would have to be re-invented (and kept consistent) per command. `null` is
+ * uniform across every 204-returning path, and `… --json | jq .` prints `null` and exits 0.
+ * The contract is documented in README (`Exit codes and output contracts`) and CHANGELOG.
+ */
+export declare function toJsonText(data: unknown): string;
 /**
  * Resolve the output mode from the flags, and enforce the `--json` / `--raw` exclusion.
  *
@@ -75,10 +93,21 @@ interface QueuedEnvelope {
  * The user asked for a content body that does not exist yet — but the job was accepted, so losing
  * the handle (the old behaviour: throw `--raw: response contains no formats`, exit 1) is the real
  * defect. Instead: emit the `sc_` id to STDOUT so `$(bytekit scrape create … --raw)` still captures
- * a usable handle, print a human note to STDERR explaining it is queued and how to poll, and exit
- * with {@link QUEUED_RAW_EXIT_CODE} — distinguishable from both success and error.
+ * a usable handle, print a human note to STDERR explaining it is queued and how to poll, and signal
+ * {@link QUEUED_RAW_EXIT_CODE} — distinguishable from both success and error.
+ *
+ * The exit code is a SOFT `process.exitCode`, never a hard `process.exit` (#2544). Node documents
+ * `process.stdout` as ASYNCHRONOUS when it points at a pipe: a write that cannot be handed to the
+ * kernel in one go is queued in userspace and drained on a later event-loop turn, and
+ * `process.exit()` runs before any of those turns and DISCARDS the queue. That is exactly the
+ * `sc=$(bytekit scrape create … --async --raw)` case this branch exists to serve — the id would be
+ * truncated away whenever stdout is backlogged. Setting `process.exitCode` instead lets the process
+ * end naturally once stdout has drained, with the same observable exit code.
+ *
+ * Returns `void` (not `never`): callers MUST `return` after invoking it, since execution now
+ * continues past this function.
  */
-export declare function emitQueuedRaw(env: QueuedEnvelope): never;
+export declare function emitQueuedRaw(env: QueuedEnvelope): void;
 /**
  * Emit a raw body to the target.
  *
@@ -101,18 +130,27 @@ export declare function emitRaw(body: string, target: OutputTarget): void;
  * `--json | jq` pipelines stay byte-identical.
  */
 export declare function emitResult(result: unknown, mode: OutputMode, target: OutputTarget, requestedFormat?: string): void;
+/**
+ * Collect the `X-Fetch-*` response headers of a {@link FetchResult} into a Title-Cased object —
+ * the documented `--json` payload for a fetch command.
+ */
+export declare function collectFetchMetadata(headers: Headers): Record<string, string>;
 /**
  * Render a `/v1/fetch` content result.
  *
- * The transport hands back a {@link FetchBodyResult} whose body IS the fetched content and whose
- * metadata are the `X-Fetch-*` headers. Default: write the raw body bytes to stdout verbatim
- * (`process.stdout.write`, never `console.log` — no coercion, no appended newline, binary-safe).
- * With `--json`: print the `X-Fetch-*` metadata as JSON instead of the body.
+ * The SDK's fetch resource resolves a {@link FetchResult} whose `bytes` ARE the fetched content and
+ * whose `headers` carry the `X-Fetch-*` metadata.
+ *
+ * - default — write the raw body BYTES verbatim (`process.stdout.write`, never `console.log`: no
+ *   coercion, no appended newline, binary-safe). `bytes` is used rather than the `body` string
+ *   because the string is a lossy UTF-8 decode for true binary passthrough (images, PDFs).
+ * - `--json` — print the `X-Fetch-*` metadata object instead of the body.
+ * - `target.file` — write the same bytes to that path instead of stdout, byte-for-byte.
  *
- * Falls back to {@link printResult} for any result that is not a fetch body (defensive — e.g. a
+ * Falls back to {@link printResult} for any result that is not a fetch result (defensive — e.g. a
  * bulk-fetch envelope routed here by mistake), so no path can silently emit nothing.
  */
-export declare function emitFetchResult(result: unknown, jsonMode: boolean): void;
+export declare function emitFetchResult(result: unknown, jsonMode: boolean, target?: OutputTarget): void;
 /**
  * Print a result to stdout.
  *