@hunt-labs/bytekit-cli 0.2.2 → 0.5.0

package/CHANGELOG.md

@@ -8,6 +8,176 @@ 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.
 
+## [0.5.0] - 2026-07-24
+
+### Added
+
+- Surface parity round 2 (#2545): every `x-sdk-scope: v0.1` endpoint the SDK
+  exposes now has a CLI command, and the high-value request fields are reachable
+  by flags. Each new flag follows the omit-when-absent rule — absent → the key is
+  left out of the request, so a server default is never materialized.
+  - **New command groups:** `usage get | daily | by-endpoint` (billing-period
+    usage reporting), `webhook-deliveries list | retry <id>` (inspect and requeue
+    deliveries), and `bulk cancel <id>` (stop an in-flight bulk job).
+  - **Monitor pause/resume:** `monitors update --status paused` / `--status active`.
+    `monitors create`/`update` also gain `--change-threshold` (float), `--notify-on`,
+    `--webhook-secret`, and the JSON-object flags `--webhook-headers`, `--options`,
+    `--scrape-options`. `--type` is **create-only** (a monitor's type is immutable).
+  - **`scrape create` multi-format `--format`:** repeatable AND comma-separated —
+    `--format raw_html --format markdown` and `--format raw_html,markdown` both send
+    `formats: ["raw_html","markdown"]`. Raw output (`--raw`/`-o`) requires exactly one
+    format. New scrape flags: `--cache-ttl`, `--markdown-query`, `--cookies`,
+    `--headers`, `--delay-ms`, `--events`, `--token-encoding`, `--custom`,
+    `--remove-base64-images` / `--no-remove-base64-images` (tri-state), and the
+    `--markdown-*` / `--with-*-summary` family.
+  - **`scrape get --raw` / `-o` / `--format`:** retrieve a completed queued scrape's
+    body from the shell (a still-queued job prints the id and exits `2`).
+  - **`screenshots create`:** `--block-ads`/`--no-block-ads`,
+    `--block-cookie-banners`/`--no-block-cookie-banners`, `--scroll`/`--no-scroll`
+    (tri-state pairs), `--wait-for-selector`, `--delay-ms`, `--dark-mode`,
+    `--device-scale-factor`, `--include-html`, `--country`, `--language`.
+  - **`fetch create` / `fetch get`:** `--country`, `--timeout-ms`, `--cache-ttl`
+    (both verbs); `--markdown-mode` (create only).
+  - **`sitemap create`:** `--strategy`, `--max-depth`, `--max-urls`.
+
+### Fixed
+
+- `--json` no longer emits the literal text `undefined` — which is not valid JSON —
+  for a response with no body. `JSON.stringify(undefined)` returns the _value_
+  `undefined`, so `bytekit monitors delete <id> --json | jq .` failed with a parse
+  error on every delete, and `--json -o <file>` on the same response crashed with
+  `ERR_INVALID_ARG_TYPE` instead of writing anything. Every `--json` code path now
+  serializes through one helper. (#2544)
+- `scrape create --async --raw` (and the bare `-o` form) no longer risks losing the
+  `sc_` id it writes. The id went to stdout immediately followed by a hard
+  `process.exit(2)`; Node documents `process.stdout` as **asynchronous** when it
+  points at a pipe, so anything still queued at that moment is discarded — exactly
+  the `sc_id=$(bytekit scrape create … --async --raw)` capture the flag exists for.
+  The queued signal is now a soft `process.exitCode`, so the process ends naturally
+  once stdout has drained. The exit code is unchanged. (#2544)
+- The per-attempt request timeout now covers the **response body read**, not just the
+  time to first byte of headers. The abort budget was armed for `fetch` and cleared the
+  moment headers arrived, after which reading the body was unbounded — so a server that
+  answered with headers and then stalled its body (including a non-2xx whose error body
+  never finished) hung the CLI forever. The budget now spans headers **and** body on both
+  transports (`request` and the `/v1/fetch` raw path), and a mid-body abort surfaces as
+  the usual `ByteKitConnectionError` with `code: 'timeout'`.
+
+  The default is **unchanged at 120 s**, and the budget is still **per attempt** — the
+  single 429 retry and its backoff sleep still get a fresh full budget. One consequence
+  worth planning for: a legitimately large body (a multi-MB `/v1/fetch` document) now
+  counts against that same 120 s, where previously only the wait for headers did. (#2546)
+
+### Documented
+
+- **Output contract:** with `--json`, a `204 No Content` response (e.g.
+  `monitors delete`) renders as JSON `null`. Human mode still prints nothing for
+  the same response. (#2544)
+- **Exit codes** now have their own README section. In particular exit code `2` —
+  "accepted but still queued", emitted by `scrape create --async` in raw and human
+  modes — was previously documented nowhere despite being observable since 0.3.0.
+  It is deliberately neither `0` (a content-body success) nor `1` (an error). (#2544)
+- Corrected two false README claims about `scrape` output: a bare `-o` implies
+  `--raw` and writes the requested format's **body** (it does not write "the same
+  text rendering the terminal would show"), and `--async --raw` prints the **bare
+  `sc_` id** on stdout with a note on stderr (it does not print the queued job
+  envelope). (#2544)
+
+## [0.4.0] - 2026-07-23
+
+### Removed (**BREAKING**)
+
+- The entire `bytekit account api-keys` command group — `create`, `list`, `get`,
+  `update`, `reveal`, and `revoke`. Every one of these subcommands was
+  structurally unreachable: they target `/v1/account/api-keys*`, which the API
+  mounts behind a **Clerk dashboard session** and marks `x-internal` in the
+  OpenAPI spec. The CLI's only credential is a bearer `sk_` API key, which can
+  never satisfy a session verifier, so all six returned `401 unauthorized` in
+  every published version. Running one now exits `1` with
+  `error: unknown command 'api-keys'`.
+
+  Key management was deliberately NOT moved onto bearer auth. The reveal
+  operation returns the **live plaintext** of any key on the account, and there
+  is no per-key scope or permission model, so accepting API-key auth there would
+  turn any leaked key into a self-perpetuating credential factory.
+
+  **Replacement:** manage API keys from the dashboard at
+  [app.bytekit.com](https://app.bytekit.com). (#2536)
+
+## [0.3.1] - 2026-07-22
+
+### Fixed
+
+- `bytekit fetch get` / `fetch create` print the fetched content again. **0.3.0's
+  claim that fetch "prints the raw body by default, or the `X-Fetch-*` metadata
+  as JSON with `--json`" was not true of the shipped artifact**: the CLI replaced
+  only `client.request`, but SDK 0.3.0 moved `/v1/fetch` onto `client.requestRaw`,
+  so the CLI's raw-body branch was unreachable and every fetch fell through to the
+  generic key/value printer — emitting `body: …`, a JSON map of every byte under
+  `bytes:`, and `headers: {}`. The CLI now overrides BOTH transport seams and
+  renders the SDK's real `FetchResult`. Binary content is byte-exact in every
+  mode. (#2535)
+- Fetch commands honor the CLI's single 429 retry again. Riding the
+  un-overridden SDK transport also bypassed the retry, the per-attempt 120 s
+  timeout, and the connection-error taxonomy; all three now apply to fetch
+  exactly as they do to the JSON commands. (#2535)
+
+### Added
+
+- `-o, --output <file>` on `fetch get` / `fetch create`: writes the fetched body
+  bytes to a file, byte-for-byte (with `--json`, writes the `X-Fetch-*` metadata
+  object instead). (#2535)
+
+## [0.3.0] - 2026-07-21
+
+### Removed (**BREAKING**)
+
+- The legacy `RAPIDCRAWL_API_KEY` and `RAPIDCRAWL_BASE_URL` environment-variable
+  fallbacks (kept as a one-minor-version bridge in #2421) are removed. Use
+  `BYTEKIT_API_KEY` and `BYTEKIT_BASE_URL` (or the `--key` / `--base-url` flags).
+  (#2473)
+
+### Fixed
+
+- `bytekit fetch get` / `fetch create` no longer crash on non-JSON bodies. The
+  transport JSON-parsed every 2xx response, but `/v1/fetch` returns the fetched
+  content AS the body. The fetch command now prints the raw body by default, or
+  the `X-Fetch-*` metadata as JSON with `--json`; `fetch bulk` and every other
+  command still parse JSON. (#2467)
+- `204 No Content` / empty-body responses (e.g. `monitors delete`,
+  `account api-keys revoke`) no longer throw a JSON-parse error, including after
+  a 429 retry. (#2467, #2468)
+- `search --type images` no longer prints an `undefined` snippet line for
+  results that omit the field. (#2479)
+
+### Added
+
+- `scrape create` accepts the full `ScrapeRequest` surface: `--country`,
+  `--timeout-ms`, `--markdown-mode`, `--async`, `--webhook-url`,
+  `--token-budget`, `--clean-markdown`, `--include-tags`, `--exclude-tags`,
+  `--mobile`. Each flag is omitted from the request when absent. (#2480)
+- `screenshots create` accepts `--device`, `--viewport WxH`, `--format`,
+  `--quality`, `--wait-until`, `--clip x,y,w,h`, and `--async`; `-o <file>`
+  on `screenshots create`/`get` downloads the captured image bytes (`-o -` for
+  stdout). `-o` cannot be combined with `--json` on screenshots. (#2480)
+- `monitors list` accepts `--limit`, `--cursor`, and `--status` query
+  filters. (#2480)
+- `account api-keys reveal <ak_id>`: prints the key masked by default
+  (`sk_live_…2345`); pass `--show` for the full plaintext. (#2480)
+- Per-attempt transport timeout (120s, mirroring the SDK default): a hung
+  request now fails with `code: 'timeout'` instead of hanging forever. Network
+  failures are mapped onto the SDK's connection-error taxonomy
+  (`timeout` / `aborted` / `connection`), and error output renders the API or
+  connection error code. (#2479)
+- A queued async job (HTTP 202) under `--raw` prints the job envelope with its
+  `sc_` id instead of an empty body. (#2479)
+
+### Changed (**BREAKING**)
+
+- `fetch --format` is validated locally against the spec union
+  `'markdown' | 'html'`; off-spec values are rejected with a clear error before
+  a request is sent (previously forwarded as-is). (#2475)
+
 ## [0.2.2] - 2026-07-16
 
 ### Changed
@@ -66,6 +236,8 @@ 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.
 
+[0.4.0]: 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
 [0.2.0]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/cli

package/README.md

@@ -43,8 +43,7 @@ over the environment variable):
 bytekit --key sk_live_xxx scrape create --url https://example.com
 ```
 
-Precedence is `--key` flag → `BYTEKIT_API_KEY` → `RAPIDCRAWL_API_KEY` (legacy
-fallback, deprecated — kept for existing scripts, will eventually be removed).
+Precedence is `--key` flag → `BYTEKIT_API_KEY`.
 
 Without a key, the CLI exits with `Error: API key required. Pass --key or set BYTEKIT_API_KEY.`
 
@@ -52,8 +51,7 @@ Without a key, the CLI exits with `Error: API key required. Pass --key or set BY
 
 Requests go to `https://api.bytekit.com` by default. Point the CLI at staging, a
 local gateway, or a proxy with the global `--base-url` flag or the
-`BYTEKIT_BASE_URL` environment variable (the flag wins; `RAPIDCRAWL_BASE_URL` is
-a deprecated legacy fallback):
+`BYTEKIT_BASE_URL` environment variable (the flag wins):
 
 ```bash
 bytekit --base-url https://api-stg.bytekit.com scrape create --url https://example.com
@@ -62,11 +60,21 @@ export BYTEKIT_BASE_URL=http://localhost:3001
 
 ## Global options
 
-| Flag               | Env var                                                     | Purpose                                                              |
-| ------------------ | ----------------------------------------------------------- | -------------------------------------------------------------------- |
-| `--key <key>`      | `BYTEKIT_API_KEY` (legacy fallback: `RAPIDCRAWL_API_KEY`)   | API key used for every request.                                      |
-| `--base-url <url>` | `BYTEKIT_BASE_URL` (legacy fallback: `RAPIDCRAWL_BASE_URL`) | API base URL (default `https://api.bytekit.com`).                    |
-| `--json`           | —                                                           | Print the raw JSON response instead of the human-readable rendering. |
+| Flag               | Env var            | Purpose                                                                                                                                 |
+| ------------------ | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `--key <key>`      | `BYTEKIT_API_KEY`  | API key used for every request.                                                                                                         |
+| `--base-url <url>` | `BYTEKIT_BASE_URL` | API base URL (default `https://api.bytekit.com`).                                                                                       |
+| `--json`           | —                  | Print the raw JSON response instead of the human-readable rendering (for `fetch`, prints the `X-Fetch-*` metadata instead of the body). |
+
+`--json` always emits a document `JSON.parse` (or `jq`) accepts. A command whose
+API response carries no body — a `204 No Content`, as `monitors delete` returns
+— prints JSON `null`:
+
+```bash
+bytekit monitors delete mon_123abc --json | jq .   # → null
+```
+
+Human mode (no `--json`) prints nothing at all for the same response.
 
 ## Commands
 
@@ -78,13 +86,96 @@ bytekit scrape get sc_123abc
 bytekit scrape bulk create --file urls.txt --webhook-url https://your.app/hooks/bytekit
 ```
 
+`scrape create` also accepts the full `ScrapeRequest` surface, each flag omitted
+from the request when absent (a boolean flag never sends `false`, so a server
+default is never materialized):
+
+| Flag                                                   | Effect                                                                                                                                                                                             |
+| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--format <fmt>`                                       | Output format. **Repeatable and comma-separated** — `--format raw_html --format markdown` and `--format raw_html,markdown` both send `formats: ["raw_html","markdown"]`. Omitted → server default. |
+| `--country <cc>`                                       | Route through a country (e.g. `us`, `de`).                                                                                                                                                         |
+| `--timeout-ms <n>`                                     | Per-request timeout in milliseconds.                                                                                                                                                               |
+| `--cache-ttl <ttl>`                                    | Cache freshness: `0`, `Nh` (hours), or `Nd` (days) — e.g. `48h`, `2d`, `0`. Omitted → server default.                                                                                              |
+| `--markdown-mode <mode>`                               | Markdown extraction mode: `article`, `raw`, `llm`.                                                                                                                                                 |
+| `--markdown-query <q>`                                 | BM25 query for relevance-ranked markdown filtering.                                                                                                                                                |
+| `--cookies <json>`                                     | Cookies as a JSON array, e.g. `'[{"name":"a","value":"b"}]'`.                                                                                                                                      |
+| `--headers <json>`                                     | Extra request headers as a JSON object, e.g. `'{"X-A":"b"}'`.                                                                                                                                      |
+| `--delay-ms <n>`                                       | Post-load delay before capture, in milliseconds.                                                                                                                                                   |
+| `--events <csv>`                                       | Webhook events (comma-separated): `queued`, `completed`, `failed`.                                                                                                                                 |
+| `--token-budget <n>`                                   | Cap the markdown returned to `n` tokens.                                                                                                                                                           |
+| `--token-encoding <enc>`                               | Tokenizer for `--token-budget`: `cl100k_base`, `o200k_base`.                                                                                                                                       |
+| `--custom <json>`                                      | User payload echoed on the envelope, as a JSON object.                                                                                                                                             |
+| `--remove-base64-images` / `--no-remove-base64-images` | Tri-state: strip / preserve base64 `data:` images. Omitted → server default (strip).                                                                                                               |
+| `--markdown-links <mode>`                              | Link rendering: `inline`, `references`, `none`, `text`.                                                                                                                                            |
+| `--markdown-images <mode>`                             | Image retention: `inline`, `references`, `none`, `text`.                                                                                                                                           |
+| `--with-links-summary`                                 | Append a Links footer to the markdown.                                                                                                                                                             |
+| `--with-images-summary`                                | Append an Images footer to the markdown.                                                                                                                                                           |
+| `--markdown-compact`                                   | Collapse excessive whitespace.                                                                                                                                                                     |
+| `--markdown-filter-images`                             | Filter low-signal images.                                                                                                                                                                          |
+| `--markdown-include-media`                             | Return rich link/image objects and a tables array.                                                                                                                                                 |
+| `--markdown-include-warnings`                          | Include markdown-pipeline and tag-filter warnings.                                                                                                                                                 |
+| `--markdown-include-stats`                             | Include a top-level stats object (chars, tokens, blocks).                                                                                                                                          |
+| `--clean-markdown`                                     | LLM-clean the markdown (billed 3x).                                                                                                                                                                |
+| `--include-tags <csv>`                                 | Comma-separated HTML tags to keep.                                                                                                                                                                 |
+| `--exclude-tags <csv>`                                 | Comma-separated HTML tags to drop.                                                                                                                                                                 |
+| `--mobile`                                             | Render with a mobile viewport/user-agent.                                                                                                                                                          |
+| `--async`                                              | Queue the scrape and return a job envelope immediately.                                                                                                                                            |
+| `--webhook-url <url>`                                  | Webhook notified when an async scrape completes.                                                                                                                                                   |
+
+`scrape get` accepts the same output flags as `scrape create` —
+`--raw`, `-o <file>`, and `--format <fmt>` — so a job queued with `--async --raw`
+can be finished raw once it completes:
+
+```bash
+sc_id=$(bytekit scrape create --url https://example.com --async --raw) || true
+bytekit scrape get "$sc_id" --raw          # prints the body once completed
+bytekit scrape get "$sc_id" --format markdown -o page.md
+```
+
+`--raw`/`-o` require **exactly one** format: with several `--format` values,
+`scrape create --raw` is a usage error (raw mode emits a single body). A
+still-queued `scrape get --raw` prints the bare id and exits [code `2`](#exit-codes),
+same as `scrape create --async --raw`.
+
+On `scrape`, a bare `-o <file>` implies `--raw`: the file receives the requested
+format's body (so `-o page.md` holds markdown), not a JSON envelope. Add
+`--json` to write the full envelope to the file instead. `--json` and `--raw`
+together are a usage error.
+
+`--async` combined with `--raw` (or a bare `-o`) has no format body to print
+yet, so it writes the bare `sc_` id — and nothing else — to **stdout**, prints a
+human "queued, poll it with…" note to **stderr**, and exits with
+[code `2`](#exit-codes). The `-o` file is deliberately never created: a file
+holding a bare id would masquerade as scraped content. This makes the handle
+directly capturable:
+
+```bash
+sc_id=$(bytekit scrape create --url https://example.com --async --raw) || true
+bytekit scrape get "$sc_id"
+```
+
+`--async --json` is outside that rule — it prints the full queued envelope and
+exits `0`.
+
 ### `fetch` — raw, unprocessed response bodies
 
 ```bash
 bytekit fetch create --url https://example.com
+bytekit fetch get --url https://example.com --format markdown
+bytekit fetch get --url https://example.com/logo.png -o logo.png
 bytekit fetch bulk create --file urls.txt --webhook-url https://your.app/hooks/bytekit
 ```
 
+`fetch create` / `fetch get` print the fetched body to stdout verbatim — no JSON
+wrapper, no appended newline, binary-safe. `--json` prints the `X-Fetch-*`
+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.
+
+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.
+
 ### `search` — ranked web search
 
 ```bash
@@ -95,43 +186,130 @@ bytekit search "ai web scraping" --limit 10 --country us
 
 ```bash
 bytekit screenshots create --url https://example.com --full-page
-bytekit screenshots get ss_123abc
+bytekit screenshots create --url https://example.com --device mobile --format png -o shot.png
+bytekit screenshots get ss_123abc -o shot.png
 ```
 
+`screenshots create` accepts `--device` (`desktop`, `mobile`), `--viewport WxH`
+(e.g. `1280x720`), `--format` (`jpeg`, `png`), `--quality <n>`, `--wait-until`
+(`load`, `domcontentloaded`, `networkidle`), `--clip x,y,w,h`, and `--async`
+(queue and return a job envelope). Each flag is omitted from the request when
+absent.
+
+It also accepts `--wait-for-selector <sel>`, `--delay-ms <n>`,
+`--device-scale-factor` (`1` or `2`), `--dark-mode`, `--include-html`,
+`--country <cc>`, `--language <lang>`, and three **tri-state** blocker pairs:
+`--block-ads` / `--no-block-ads`, `--block-cookie-banners` /
+`--no-block-cookie-banners`, and `--scroll` / `--no-scroll`. Each of these three
+defaults to `true` server-side, so passing neither half omits the key entirely
+(the server default stands) — the `--no-` half sends `false`, the bare flag sends
+`true`.
+
+`-o <file>` downloads the captured image bytes to that file (use `-o -` for
+stdout). Because `-o` writes BINARY on `screenshots`, it cannot be combined with
+`--json` (that would emit binary into a JSON pipeline) — pass one or the other.
+`--async` + `-o` prints the queued job envelope and skips the download (the
+image is not ready yet).
+
 ### `bulk` — bulk screenshot jobs
 
 ```bash
 bytekit bulk create --file urls.txt --webhook-url https://your.app/hooks/bytekit
 bulk_id=bulk_123abc
 bytekit bulk get "$bulk_id"
+bytekit bulk cancel "$bulk_id"
 bytekit bulk screenshots list "$bulk_id"
 ```
 
 `urls.txt` is newline-delimited: one plain URL (or `{"url":"https://..."}`) per line.
+`bulk cancel <id>` stops an in-flight job.
 
 ### `monitors` — watch a page for changes
 
 ```bash
 bytekit monitors create --url https://example.com/pricing --interval-type daily \
   --webhook-url https://your.app/hooks/bytekit
-bytekit monitors list
+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 delete mon_123abc
 ```
 
+`monitors list` accepts `--limit <n>`, `--cursor <cursor>`, and `--status`
+(`active`, `processing`, `paused`, `cancelled`, `suspended`) as query filters,
+each 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:
+`--webhook-headers`, `--options`, and `--scrape-options` (e.g.
+`--options '{"device":"mobile"}'`). `monitors create` accepts the same set plus
+`--type` (`screenshot` | `scrape`). `--type` is **create-only** — a monitor's
+type is immutable, so `monitors update` deliberately has no `--type`. Every flag
+is omitted from the request when absent.
+
 ### `sitemap` — crawl a site's URL graph
 
 ```bash
-bytekit sitemap create --url https://example.com
+bytekit sitemap create --url https://example.com --strategy deep --max-depth 3 --max-urls 500
 bytekit sitemap get sm_123abc
 ```
 
-### `account` — account details and API keys
+`sitemap create` accepts `--strategy` (`quick`, `standard`, `deep`),
+`--max-depth <n>`, and `--max-urls <n>`, each omitted when absent.
+
+### `account` — account details
 
 ```bash
 bytekit account get
-bytekit account api-keys list
-bytekit account api-keys create --name "ci-key"
+```
+
+API key management is not available from the CLI: it requires a signed-in
+dashboard session, not a bearer API key. Create, rename, reveal, and revoke keys
+at [app.bytekit.com](https://app.bytekit.com).
+
+### `usage` — account usage and billing-period reporting
+
+```bash
+bytekit usage get
+bytekit usage daily --from 2026-01-01 --to 2026-01-31
+bytekit usage by-endpoint --api-key ak_123abc
+```
+
+`usage get` returns the current billing-period summary. `usage daily` and
+`usage by-endpoint` accept `--from <date>`, `--to <date>` (YYYY-MM-DD), and
+`--api-key <ak_id>`, each omitted when absent (default range: last 30 days).
+
+### `webhook-deliveries` — inspect and retry webhook deliveries
+
+```bash
+bytekit webhook-deliveries list --status failed --limit 10
+bytekit webhook-deliveries retry wh_123abc
+```
+
+`list` accepts `--limit <n>`, `--cursor <cursor>`, `--status`
+(`pending`, `delivered`, `failed`, `exhausted`), and `--since <iso>`, each
+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 `2` is deliberately distinct from both `0` and `1` so a script can branch
+on "queued" without parsing stderr:
+
+```bash
+sc_id=$(bytekit scrape create --url https://example.com --async --raw)
+case $? in
+  0) echo "content: $sc_id" ;;
+  2) echo "queued as $sc_id — poll it" ;;
+  *) exit 1 ;;
+esac
 ```
 
 ## Documentation

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { RapidCrawl } from '@hunt-labs/bytekit-sdk';
+import { ByteKit } from '@hunt-labs/bytekit-sdk';
 export interface GlobalOptions {
     key?: string | undefined;
     baseUrl?: string | undefined;
@@ -22,6 +22,17 @@ 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;
+/**
+ * Default CLIENT-SIDE abort budget for a single fetch attempt, in ms.
+ *
+ * Mirrors the SDK's own `DEFAULT_TIMEOUT_MS` (120s). Overriding `client.request` with this
+ * transport had discarded the SDK's default, so a hung server hung the CLI forever; this restores
+ * the same bound. The budget is **per attempt**, not per command: the single 429 retry (and its
+ * backoff sleep) gets a fresh budget, so the retry can never be cut short by time already spent on
+ * the first attempt. A future `--timeout` flag would override this default; today only the default
+ * exists.
+ */
+export declare const DEFAULT_TIMEOUT_MS = 120000;
 /**
  * Parse a `Retry-After` header into a clamped millisecond delay.
  *
@@ -31,29 +42,39 @@ export declare const MAX_RETRIES = 1;
  */
 export declare function parseRetryAfterMs(raw: string | null): number;
 /**
- * Build the CLI's HTTP transport: the SDK's `request` contract, plus a single bounded retry on 429.
- *
- * Why the CLI owns the `fetch` instead of wrapping the SDK's `request()`: the SDK throws a
- * header-less `RapidCrawlError` 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.
+ * 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* commands through it from one seam.
+ * 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.
+ */
+export declare function createRetryingRequest(apiKey: string, baseUrl: string, timeoutMs?: number): ByteKit['request'];
+/**
+ * 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.
  *
- * Retries apply to 429 only. Non-429 statuses and network rejections propagate untouched.
+ * 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.
  */
-export declare function createRetryingRequest(apiKey: string, baseUrl: string): RapidCrawl['request'];
+export declare function createRetryingRequestRaw(apiKey: string, baseUrl: string, timeoutMs?: number): ByteKit['requestRaw'];
 /**
  * Build an authenticated SDK client from global CLI options.
  *
- * Resolution order (explicit input beats environment; new brand beats legacy brand):
- *   apiKey:  --key flag → BYTEKIT_API_KEY → RAPIDCRAWL_API_KEY (legacy fallback).
- *   baseUrl: --base-url flag → BYTEKIT_BASE_URL → RAPIDCRAWL_BASE_URL (legacy) → DEFAULT_BASE_URL.
- * The legacy RAPIDCRAWL_* vars stay silently honored so existing setups keep working; exits with a
- * descriptive error when no key is available.
+ * 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` is replaced by the retrying transport, so every command inherits
- * the 429 retry from this one seam.
+ * 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.
  */
-export declare function buildClient(opts: GlobalOptions): RapidCrawl;
+export declare function buildClient(opts: GlobalOptions): ByteKit;