@hunt-labs/bytekit-cli 0.3.0 → 0.6.0

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.
  *
@@ -42,19 +103,64 @@ export declare const DEFAULT_TIMEOUT_MS = 120000;
  */
 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 `ByteKitError` and discards the `Response`, so a delegating wrapper can see
- * `status === 429` but can never read `Retry-After`. Owning the fetch is the only way to honor the
- * server's advertised backoff without editing the SDK.
+ * 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.
  *
- * Retries apply to 429 only. Non-429 statuses and network rejections propagate untouched.
+ * 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'];
+/**
+ * Build the CLI's RAW transport: the SDK's `requestRaw` contract, plus the same bounded 429 retry.
+ *
+ * `/v1/fetch` returns the fetched content AS the body (HTML, markdown, or true binary) with its
+ * metadata in `X-Fetch-*` headers, so the SDK routes it through `requestRaw` rather than the JSON
+ * `request`. The CLI must override BOTH seams or fetch commands silently bypass the retry and the
+ * CLI's error taxonomy — the #2535 defect, where only `request` was replaced.
+ *
+ * The returned shape is the SDK's `requestRaw` contract verbatim (`{body, bytes, headers, status}`)
+ * so `FetchResource` builds an ordinary `FetchResult` from it and the CLI never forks fetch
+ * handling away from the SDK. `bytes` is byte-exact (binary-safe); `body` is the best-effort UTF-8
+ * decode, matching the SDK's own semantics.
+ *
+ * The 4th `RequestOptions` parameter is accepted but not forwarded — see the DECISION note on
+ * {@link createRetryingRequest}, which applies here verbatim. `FetchResource.create`/`get` DO thread
+ * a `requestOptions` argument through to this seam (unlike every other resource), but no CLI `fetch`
+ * command constructs one today (no `--timeout` flag), so it is still always `undefined` in practice.
+ */
+export 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.
  *
@@ -63,7 +169,18 @@ export declare function createRetryingRequest(apiKey: string, baseUrl: string, t
  *   baseUrl: --base-url flag → BYTEKIT_BASE_URL → DEFAULT_BASE_URL.
  * Exits with a descriptive error when no key is available.
  *
- * The returned client's `request` is replaced by the retrying transport, so every command inherits
- * the 429 retry from this one seam.
+ * The returned client's `request`, `requestRaw`, AND `requestWithResponse` are all replaced by the
+ * retrying transports, so every command inherits the 429 retry — JSON commands via `request`, the
+ * `/v1/fetch` content commands via `requestRaw`, and the header-carrying `*WithResponse` surface via
+ * `requestWithResponse`. Overriding only `request` is the #2535 defect: the SDK's fetch resource
+ * rides `requestRaw`, so fetch bypassed the retry and the CLI's error taxonomy entirely; leaving
+ * `requestWithResponse` un-overridden is the same class of defect (#2586) — it is unused by any CLI
+ * command TODAY, but a future command built on `screenshots.createWithResponse` /
+ * `sitemap.getWithResponse` would otherwise silently ride the bare SDK transport.
+ *
+ * `baseUrl` is normalized ONCE, here, before it reaches either the SDK constructor or the CLI's own
+ * transport builders below — the CLI's transports build their request URL from this local variable
+ * directly (they do not call the SDK's own normalized `send()`), so a trailing-slash flag would
+ * otherwise double-slash every request the CLI makes (#2586).
  */
 export declare function buildClient(opts: GlobalOptions): ByteKit;