@hunt-labs/bytekit-cli 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -8,8 +8,186 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 This file records only the delta between versions. For how to use the package
 today, see [README.md](./README.md), which remains the authoritative usage guide.
 
+## [Unreleased]
+
+## [0.7.0] - 2026-08-07
+
+### Breaking
+
+- **A not-ready `screenshots get -o` / `screenshots create -o` now exits `2` and prints the bare
+  `ss_` id, instead of exiting `1` with `not ready yet: screenshot is pending`.** The two poll
+  commands disagreed: `scrape get --raw` on a still-queued scrape already wrote the bare `sc_` id
+  to stdout and exited `2` — a distinct, scriptable "accepted but not ready" signal — while the
+  screenshots side reported the same state as a failure and threw the handle away, so a polling
+  script could branch on "queued" for one command and not the other. The screenshots branch now
+  mirrors scrape exactly: bare `ss_` id on stdout, a poll note on stderr, exit `2`, and (as before)
+  no file written. A script that treated any non-zero exit as "this screenshot failed" now sees `2`
+  for a job that is merely still running — branch on the code (`2` = poll again, `1` = failed)
+  rather than on non-zero. Three states deliberately do **not** move: a terminally `failed`
+  screenshot stays exit `1` with its error surfaced (it will never complete, so a "poll again"
+  signal would loop a script forever), an envelope carrying no `ss_` id stays exit `1` (there is no
+  handle to hand back), and `--json` keeps the envelope at exit `0`.
+- **`--json` on a `fetch` command now emits `X-Fetch-ID` and `X-Fetch-URL`, not `X-Fetch-Id` and
+  `X-Fetch-Url`.** The metadata keys were derived by a generic segment-wise Title-Caser, which
+  lowercases every non-initial character of a segment — so the two acronym-bearing headers came out
+  in a spelling the API reference never uses, and a `jq '."X-Fetch-ID"'` filter written from the
+  docs returned `null`. All 16 `X-Fetch-*` keys now match the spec names byte-for-byte. The
+  **values** are unchanged, the non-`X-Fetch-*` headers stay filtered out, and every other key
+  (`X-Fetch-Waf-Vendor`, `X-Fetch-Duration-Ms`, `X-Fetch-Fast-Path`, …) is spelled exactly as
+  before. A consumer reading `.["X-Fetch-Id"]` must switch to `.["X-Fetch-ID"]`.
+
+### Fixed
+
+- **A `screenshots get -o` / `screenshots create -o` poll only says "poll again" for a `pending` or
+  `processing` screenshot.** The not-ready predicate decided from the presence of an `image_url`,
+  an `id` and a nested error alone — `status` was read only to phrase the message — so a
+  `completed` screenshot whose `image_url` never materialized, a status outside the closed enum,
+  and the flat `error_code`/`error_message` failed shape all received exit `2` and "no image
+  artifact is available yet. Poll it with: …" for a job that would never complete. Those states now
+  exit `1`: a terminal failure prints `screenshot failed: …`, and any other artifact-less state
+  prints `no image artifact available: screenshot is <status>`. Genuine `pending` / `processing`
+  polls keep the bare `ss_` id, the poll note and exit `2` exactly as before — **including** a
+  poll whose envelope carries an `error_code` from an attempt that failed and is being retried,
+  since the status, not the error, decides whether polling can still help. `--json` still prints
+  the envelope at exit `0`.
+- **A terminally failed screenshot reported through the spec's flat `error_code`/`error_message`
+  fields now reaches stderr.** Only the nested `{error:{code,message}}` envelope was read, so the
+  shape `ScreenshotResponse` actually declares surfaced neither code nor message. It now prints
+  `screenshot failed: <message> (<code>)` — the formatting `scrape get --raw` already uses for a
+  failed scrape. The nested envelope's own message is unchanged.
+- **`scrape get --raw` on a terminally failed scrape now reports why it failed.** It printed
+  `--raw: response contains no formats` — technically true of a `ScrapeErrorEnvelope`, and the one
+  diagnostic that cannot explain anything — while the envelope's own `error.code` and
+  `error.message` never reached the caller. Both now go to stderr (exit `1`, unchanged). The
+  failure is reported ahead of the format diagnostics, so an envelope carrying both a failure and
+  an empty `formats: {}` still says why it failed rather than pointing at a `--format` choice that
+  cannot help.
+- **An empty-formats success now names the warning that explains it.** A completed scrape whose
+  persisted artifact could not be rehydrated comes back with `formats: {}` and an
+  `artifact_unavailable` warning; `--raw` rendered that as `--raw requires --format when the
+response contains multiple formats`, which is false on both counts. It now names the warning's
+  code and message, or says plainly that the formats map is empty when no warning explains it.
+- **Error paths no longer risk losing their own diagnostic.** `handleError` and the missing-API-key
+  path each wrote to stderr and then immediately hard-`process.exit(1)`. Node's stderr is
+  asynchronous when it points at a pipe, and `process.exit` discards whatever is still queued — so
+  the one line a script greps was the line most at risk of being thrown away, which is exactly the
+  defect this package's flush policy exists to prevent. Both now set `process.exitCode` and let the
+  process end naturally once stderr has drained. The exit codes and the rendered messages are
+  byte-identical.
+- `--headers`, `--custom` and `--metadata` said `must be valid JSON (a object)` on a malformed
+  value; the article now agrees — `an object` / `an array`.
+- The `[0.6.0]` link reference, missing from the bottom of this file, is restored.
+
+## [0.6.0] - 2026-07-29
+
+### Breaking
+
+- **`screenshots create --async` now exits `2` in human mode instead of `0`.** The queued 202 is
+  not a completed capture — there is no artifact yet — and every other queued path in the CLI
+  already signalled that with exit code `2` (`scrape create --async`). A script that relied on
+  exit `0` to mean "the screenshot is ready" was reading a false success; under `set -e` such a
+  script now stops at the queue step, which is the intended correction. The envelope itself is
+  unchanged and still printed. Two carve-outs: **`--json` keeps exit `0`** (the envelope is a
+  complete machine-readable payload — identical to `scrape create --async --json`), and
+  `--async -o <file>` also exits `2` while still writing no file (it prints the queued envelope
+  and skips the download, as before). Poll with `bytekit screenshots get <id>`.
+- **A `--file` per-item key outside a bulk endpoint's own strict schema now fails the whole
+  create with a `422`** instead of silently succeeding with that key ignored. In 0.5.x, `--file`
+  never read anything but `url` from a JSON line — every other key was dropped client-side
+  before the request was ever built. As of 0.6.0 those keys ride to the server (`items` on
+  `bulk create` / `scrape bulk create`; inside `urls` on `fetch bulk create`), and `/v1/bulk` /
+  `/v1/scrape/bulk` reject any key their `.strict()` per-item schema doesn't recognize. A file
+  that worked in 0.5.x purely because its extra keys were quietly discarded may now `422` — see
+  each command's `--file` help for the keys actually honored on that endpoint.
+- **`fetch bulk create --file` per-item keys outside `url`/`format`/`country`/`cache_ttl` now
+  fail the whole create with a `422`** instead of silently succeeding with that key ignored.
+  `/v1/fetch/bulk`'s per-item override schema (inside `urls[]`) is now `.strict()` on the
+  gateway (issue #2648), matching the `/v1/bulk` / `/v1/scrape/bulk` posture above. The
+  `--file` help text for `fetch bulk create` is now uniform with `bulk create` /
+  `scrape bulk create` and no longer enumerates keys — this entry is where the honored set
+  (`url`, `format`, `country`, `cache_ttl`) is documented instead.
+
+### Added
+
+- **Per-item bulk configuration on all three bulk creates** (`bulk create`, `scrape bulk create`,
+  `fetch bulk create`). A `--file` line may now be a JSON object carrying `url` plus per-item
+  fields instead of only a bare URL; such a file is sent as `items` on `/v1/bulk` and
+  `/v1/scrape/bulk`, and as a heterogeneous `urls` array on `/v1/fetch/bulk` (which has no
+  `items` property). A line whose only key is `url` still normalizes to a bare URL string, so a
+  file of url-only lines produces a byte-identical request to before. A JSON line with a missing
+  or non-string `url` is now rejected locally with a usage error (exit `1`) instead of being sent
+  to the server as a URL. (See Breaking, above, for the per-item strict-schema behavior change
+  this enables.)
+- `--defaults`, `--webhook-secret` and `--metadata` on all three bulk creates, plus `--custom` on
+  `scrape bulk create` only (`/v1/bulk` and `/v1/fetch/bulk` have no top-level `custom`, so the
+  flag would be rejected or stripped there). `--defaults` is forwarded verbatim; the server owns
+  precedence and unknown-key handling.
+- The full markdown-tuning surface on `fetch create`: `--markdown-query`, `--markdown-links`,
+  `--markdown-images`, `--with-links-summary`, `--with-images-summary`, `--markdown-compact`,
+  `--markdown-filter-images`, `--markdown-include-media`, `--markdown-include-warnings`,
+  `--markdown-include-stats`, and `--custom`.
+- Webhook delivery and processing flags on `sitemap create`: `--webhook-url`, `--webhook-secret`,
+  `--cache-ttl`, `--compact`, `--process`, `--metadata`. Webhook-driven sitemap crawls were
+  previously unreachable from the shell.
+- `--headers`, `--cookies` and `--metadata` on `screenshots create`.
+- `--metadata` on `monitors create`, and `--metadata` + `--url` on `monitors update`. `--type`
+  remains deliberately absent from `update` — it is immutable server-side.
+
+## [0.5.1] - 2026-07-28 [NEVER PUBLISHED]
+
+> **Never published to npm.** This version was cut in-tree but no `@hunt-labs/bytekit-cli@0.5.1`
+> tarball exists — `npm i @hunt-labs/bytekit-cli@0.5.1` fails. Everything below shipped to users in
+> **0.6.0**, which is the first published release containing it. Reconciled by issue #2680; the
+> `release-drift` CI gate now blocks a new phantom heading from being introduced.
+
+### Fixed
+
+- **Corrects the scope of the 0.5.0 "stalled body" fix claim.** `screenshots create`/`get -o`
+  downloads the `image_url` artifact bytes with a bare `globalThis.fetch` call
+  (`lib/download-artifact.ts`) that sat entirely outside the transport seam `sendWithRetry` owns —
+  no abort signal, no connection-error taxonomy. The 0.5.0 entry below ("The per-attempt request
+  timeout now covers the response body read... a server that answered with headers and then
+  stalled its body... hung the CLI forever", #2546) reads as if it covered every response body; it
+  only ever covered API-call bodies read through the JSON/raw transports. A stalled artifact host
+  (headers, then a body that never completes) still hung the CLI indefinitely until now. The
+  download path now shares the same per-attempt abort budget and `ByteKitConnectionError` timeout
+  taxonomy as the API transport (`createAttemptBudget` / `toConnectionError`, exported from
+  `client.ts` — no second timeout implementation), with the same 120 s per-attempt default and no
+  retry (artifact GETs are not the API's 429 domain). Partial-file policy: the response is
+  buffered fully in memory before any write, so an aborted download never leaves a
+  partial/truncated file at the `-o` destination. **User-visible consequence:** a legitimately
+  slow (but not stalled) large artifact download now hard-fails after 120 s instead of waiting
+  indefinitely, and there is currently no CLI flag to raise that budget for a single command.
+  (#2587)
+- While in the file: the 429-retry path left its (unread) response body undrained before sleeping
+  and retrying — undici cannot reclaim the underlying socket for connection-pool reuse until a body
+  is fully read. The body is now drained with `response.text()` on that path, bounded by its own
+  short (2 s) cap independent of the 120 s per-attempt budget, so a 429 whose body stalls can no
+  longer delay the retry by anywhere near the full attempt budget (or, with the budget disabled,
+  forever). **Correction to an intermediate `Unreleased` draft of this same fix:** that draft's cap
+  only bounded how long the _retry_ waited — it resolved on schedule but never touched the
+  abandoned `response.text()` call itself, which kept reading against a live socket indefinitely.
+  Because every CLI success path exits via a soft `process.exitCode` (#2544) rather than
+  `process.exit()`, that orphaned read kept the whole process alive forever — strictly worse than
+  having no drain at all, and on the exact class of hang this ticket exists to eliminate. The cap
+  now also **aborts** the request when it fires, so the abandoned read is actually torn down, not
+  merely ignored; this holds even when the per-attempt timeout itself is disabled
+  (`timeoutMs <= 0`). **User-visible consequence:** a 429 with a stalled body still costs the retry
+  at most ~2 s, exactly as before, but the CLI process now reliably exits afterward instead of
+  hanging forever regardless of that visible latency. The same discard-drain on the
+  artifact-download's non-2xx path is removed outright rather than capped: that path throws
+  straight into `process.exit(1)`, so there is no subsequent request in the process for a reclaimed
+  socket to serve, and the drain there bought nothing. (#2587)
+
 ## [0.5.0] - 2026-07-24
 
+### Note
+
+- The `0.3.1` and `0.4.0` versions below document real, tagged changes but were
+  never published to npm — the registry's version history jumps straight from
+  `0.3.0` to `0.5.0`. Don't go looking for those tarballs; the changes they
+  describe ship for the first time in this release.
+
 ### Added
 
 - Surface parity round 2 (#2545): every `x-sdk-scope: v0.1` endpoint the SDK
@@ -83,7 +261,12 @@ today, see [README.md](./README.md), which remains the authoritative usage guide
   `sc_` id** on stdout with a note on stderr (it does not print the queued job
   envelope). (#2544)
 
-## [0.4.0] - 2026-07-23
+## [0.4.0] - 2026-07-23 [NEVER PUBLISHED]
+
+> **Never published to npm.** This version was cut in-tree but no `@hunt-labs/bytekit-cli@0.4.0`
+> tarball exists — `npm i @hunt-labs/bytekit-cli@0.4.0` fails. Everything below shipped to users in
+> **0.5.0**, which is the first published release containing it. Reconciled by issue #2680; the
+> `release-drift` CI gate now blocks a new phantom heading from being introduced.
 
 ### Removed (**BREAKING**)
 
@@ -104,7 +287,13 @@ today, see [README.md](./README.md), which remains the authoritative usage guide
   **Replacement:** manage API keys from the dashboard at
   [app.bytekit.com](https://app.bytekit.com). (#2536)
 
-## [0.3.1] - 2026-07-22
+## [0.3.1] - 2026-07-22 [NEVER PUBLISHED]
+
+> **Never published to npm.** This version was cut in-tree but no `@hunt-labs/bytekit-cli@0.3.1`
+> tarball exists — `npm i @hunt-labs/bytekit-cli@0.3.1` fails. Everything below shipped to users in
+> **0.5.0**, which is the first published release containing it (0.4.0 was never published either —
+> see its heading above). Reconciled by issue #2680; the `release-drift` CI gate now blocks a new
+> phantom heading from being introduced.
 
 ### Fixed
 
@@ -187,7 +376,12 @@ today, see [README.md](./README.md), which remains the authoritative usage guide
   rebuilding the shared `dist`), which is now fixed. No consumer-facing changes
   beyond 0.2.1.
 
-## [0.2.1] - 2026-07-16
+## [0.2.1] - 2026-07-16 [NEVER PUBLISHED]
+
+> **Never published to npm.** This version was cut in-tree but no `@hunt-labs/bytekit-cli@0.2.1`
+> tarball exists — `npm i @hunt-labs/bytekit-cli@0.2.1` fails. Everything below shipped to users in
+> **0.2.2**, which is the first published release containing it. Reconciled by issue #2680; the
+> `release-drift` CI gate now blocks a new phantom heading from being introduced.
 
 ### Changed
 
@@ -236,7 +430,13 @@ Additive, lower-risk release — no breaking changes to existing commands.
 - Initial release of the ByteKit CLI, wrapping the ByteKit SDK as shell
   subcommands, published under the original `rapidcrawl-cli` name.
 
+[Unreleased]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/cli
+[0.7.0]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/cli
+[0.6.0]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/cli
+[0.5.1]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/cli
+[0.5.0]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/cli
 [0.4.0]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/cli
+[0.3.1]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/cli
 [0.3.0]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/cli
 [0.2.2]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/cli
 [0.2.1]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/cli

package/README.md

@@ -172,6 +172,17 @@ response metadata instead of the body. `-o <file>` writes the body bytes to a
 file byte-for-byte (with `--json`, the metadata object goes to the file
 instead). `fetch bulk` returns an ordinary JSON job envelope.
 
+The `--json` metadata keys are the **spec header names exactly** as the API
+reference declares them, so a filter written from the docs works unchanged:
+
+```bash
+bytekit fetch get --url https://example.com --json | jq -r '."X-Fetch-ID"'
+```
+
+Note the acronym casing — `X-Fetch-ID` and `X-Fetch-URL`, not `X-Fetch-Id` /
+`X-Fetch-Url`. (Versions up to 0.6.0 emitted the Title-Cased spellings; see the
+CHANGELOG.)
+
 Both verbs accept `--country <cc>`, `--timeout-ms <n>`, and `--cache-ttl <ttl>`
 (`0`, `Nh`, or `Nd`), each omitted when absent. `--markdown-mode`
 (`article`, `raw`, `llm`) is `fetch create` only.
@@ -182,6 +193,11 @@ Both verbs accept `--country <cc>`, `--timeout-ms <n>`, and `--cache-ttl <ttl>`
 bytekit search "ai web scraping" --limit 10 --country us
 ```
 
+`search` also accepts `--type <type>` (`web` (default), `news`, or `images`),
+`--language <code>` (two-letter language code, e.g. `en`, `fr`), and
+`--date-range <window>` (recency filter: `any` (default), `hour`, `day`,
+`week`, `month`, `year`). Each flag is omitted from the request when absent.
+
 ### `screenshots` — capture a page
 
 ```bash
@@ -232,7 +248,7 @@ bytekit monitors create --url https://example.com/pricing --interval-type daily
 bytekit monitors list --limit 25 --status active
 bytekit monitors update mon_123abc --status paused    # pause
 bytekit monitors update mon_123abc --status active    # resume
-bytekit monitors captures list mon_123abc
+bytekit monitors captures list mon_123abc --limit 25
 bytekit monitors delete mon_123abc
 ```
 
@@ -240,6 +256,10 @@ bytekit monitors delete mon_123abc
 (`active`, `processing`, `paused`, `cancelled`, `suspended`) as query filters,
 each omitted when absent.
 
+`monitors captures list <id>` accepts `--limit <n>` and `--cursor <cursor>` to
+page through a monitor's capture history — pass the response's `next_cursor`
+back as `--cursor` to fetch the next page. Both flags are omitted when absent.
+
 `monitors update` gains `--status` (`active` | `paused` — pause and resume from
 the shell), `--change-threshold <pct>` (accepts a float), `--notify-on`
 (`change`, `every`), `--webhook-secret <secret>`, and three JSON-object flags:
@@ -294,11 +314,47 @@ omitted when absent. `retry <id>` requeues a failed or exhausted delivery.
 
 ## Exit codes
 
-| Code | Meaning                                                                                                                                                                                                                                                                                                            |
-| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `0`  | Success.                                                                                                                                                                                                                                                                                                           |
-| `1`  | Usage error, or an API/connection error. The reason is on stderr, always prefixed `Error: `.                                                                                                                                                                                                                       |
-| `2`  | The scrape was accepted but is still **queued**, so there is no content body to emit — `scrape create --async` with `--raw` or a bare `-o` (which writes the bare `sc_` id to stdout), and the same command in human mode. Not a failure: the job was accepted and billed. Poll it with `bytekit scrape get <id>`. |
+| Code | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `0`  | Success.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `1`  | Usage error, or an API/connection error.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `2`  | The job was accepted but is **not ready**, so there is no content body or artifact to emit. Applies to `scrape create --async` with `--raw` or a bare `-o` (which writes the bare `sc_` id to stdout) and in human mode; to `scrape get --raw`/`-o` on a still-queued job (bare `sc_` id to stdout); to `screenshots create --async` in human mode (including with `-o`, which deliberately writes no file); and to `screenshots create -o` / `screenshots get -o` on a pending or processing screenshot (bare `ss_` id to stdout, no file written). Not a failure: the job was accepted and billed. Poll it with `bytekit scrape get <id>` / `bytekit screenshots get <id>`. **`--json` keeps exit `0` in every case** — the envelope is a complete machine-readable payload. |
+
+A **terminally failed** job is NOT code `2` — it will never complete, so it is
+exit `1` with the reason on stderr. `scrape get --raw` on a failed scrape prints
+that scrape's own `error.code` and message, and `screenshots get -o` on a failed
+screenshot prints `screenshot failed: …`.
+
+Only `pending` and `processing` earn code `2`. Any other screenshot state that
+still has no artifact — a `completed` screenshot whose `image_url` never
+materialized, or a status this CLI build does not know — is exit `1` with
+`no image artifact available: screenshot is <status>` on stderr, because
+polling it again cannot change the outcome.
+
+The status is what decides, not the presence of an error. A `pending` or
+`processing` screenshot that reports an `error_code` from an attempt that failed
+and is being **retried** is still code `2` with its `ss_` id — the job has not
+finished, and abandoning it there would throw away a capture the server is still
+working on.
+
+A **human-mode poll without `-o`/`--raw`** stays exit `0` whatever the job's
+state: `bytekit scrape get <id>` and `bytekit screenshots get <id>` were asked
+for the envelope, and the envelope is exactly what they printed — the status
+field in it is the answer. Code `2` is reserved for the case where you asked for
+a **body or artifact** that does not exist yet.
+
+The stderr message for exit code `1` has two shapes, depending on where the
+error originates:
+
+- **App-level errors** (a rejected API call, a connection failure, a missing
+  key) are always prefixed `Error: ` (uppercase) — e.g.
+  `Error: API key required. Pass --key or set BYTEKIT_API_KEY.`
+- **Commander-level usage errors** (an unknown command, a missing required
+  argument, an unrecognized flag) come from the `commander` library itself and
+  use its own lowercase `error: ` prefix — e.g. `error: unknown command 'bogus'`.
+
+Scripts that grep stderr for a failure reason should match case-insensitively,
+or handle both prefixes.
 
 Code `2` is deliberately distinct from both `0` and `1` so a script can branch
 on "queued" without parsing stderr:
@@ -312,6 +368,18 @@ case $? in
 esac
 ```
 
+The same branch works for a screenshot poll, because both commands now signal
+"not ready" identically:
+
+```bash
+ss_id=$(bytekit screenshots get "$ss_id" -o shot.png)
+case $? in
+  0) echo "downloaded shot.png" ;;
+  2) echo "$ss_id not ready — poll again" ;;
+  *) exit 1 ;;                 # terminal failure, reason on stderr
+esac
+```
+
 ## Documentation
 
 Full API reference: [bytekit.com/docs](https://bytekit.com/docs).

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { ByteKit } from '@hunt-labs/bytekit-sdk';
+import { ByteKit, ByteKitConnectionError } from '@hunt-labs/bytekit-sdk';
 export interface GlobalOptions {
     key?: string | undefined;
     baseUrl?: string | undefined;
@@ -22,6 +22,24 @@ export declare const MIN_RETRY_AFTER_MS = 1000;
 export declare const MAX_RETRY_AFTER_MS = 60000;
 /** Exactly one retry. A second 429 is terminal — no loop. */
 export declare 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 declare const DRAIN_TIMEOUT_MS = 2000;
 /**
  * Default CLIENT-SIDE abort budget for a single fetch attempt, in ms.
  *
@@ -33,6 +51,49 @@ export declare const MAX_RETRIES = 1;
  * exists.
  */
 export declare const DEFAULT_TIMEOUT_MS = 120000;
+/**
+ * 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.
+ */
+export declare function createAttemptBudget(ms: number): {
+    signal: AbortSignal;
+    cleanup: () => void;
+    abort: (reason: unknown) => void;
+};
+/**
+ * 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 — 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.
+ */
+export declare function toConnectionError(err: unknown, method: string, path: string, timedOut: boolean): ByteKitConnectionError;
 /**
  * Parse a `Retry-After` header into a clamped millisecond delay.
  *
@@ -48,6 +109,18 @@ export declare function parseRetryAfterMs(raw: string | null): number;
  * 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 declare function createRetryingRequest(apiKey: string, baseUrl: string, timeoutMs?: number): ByteKit['request'];
 /**
@@ -62,19 +135,66 @@ export declare function createRetryingRequest(apiKey: string, baseUrl: string, t
  * 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 declare function createRetryingRequestRaw(apiKey: string, baseUrl: string, timeoutMs?: number): ByteKit['requestRaw'];
+/**
+ * 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 declare function createRetryingRequestWithResponse(apiKey: string, baseUrl: string, timeoutMs?: number): ByteKit['requestWithResponse'];
 /**
  * Build an authenticated SDK client from global CLI options.
  *
  * Resolution order (explicit input beats environment):
  *   apiKey:  --key flag → BYTEKIT_API_KEY.
  *   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` AND `requestRaw` are both replaced by the retrying transports, so
- * every command inherits the 429 retry — JSON commands via `request`, the `/v1/fetch` content
- * commands via `requestRaw`. 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.
+ * THROWS a plain `Error` when no key is available (#2686 item 4). It used to `console.error` and
+ * then hard-exit — an async stderr write followed immediately by the one call that discards
+ * the userspace stdio queue, which is exactly the defect the package's #2544 flush policy exists to
+ * prevent. Throwing stops just as hard (there is no client to return, E4) while routing the message
+ * through `handleError`, whose soft `process.exitCode` lets stderr drain first. The rendered stderr
+ * line is byte-identical: `handleError` supplies the `Error: ` prefix, and a plain Error carries
+ * neither a status nor a ByteKit code, so no parenthesised suffix is added.
+ *
+ * Because it throws, EVERY caller invokes it from inside its action's `try` block. `index.ts` drives
+ * commander with `.parse()`, not `.parseAsync()`, so nothing awaits an action's promise: a throw
+ * raised above the try would escape as an unhandled rejection and print a raw stack trace instead of
+ * the clean one-liner — the same constraint `commands/scrape.ts` already documents for
+ * `resolveOutputMode`. `error-exit-contract.test.ts` pins that placement structurally, across every
+ * call site at once.
+ *
+ * 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 declare function buildClient(opts: GlobalOptions): ByteKit;