@hunt-labs/bytekit-cli 0.2.2 → 0.5.0

package/dist/commands/usage.js

@@ -0,0 +1,81 @@
+import { Command } from 'commander';
+import { buildClient } from '../client.js';
+import { printResult, handleError } from '../output.js';
+/**
+ * The `usage` command group (#2545) — the `x-sdk-scope: v0.1` usage endpoints, previously curl-only.
+ *
+ * `daily` / `by-endpoint` accept the same three optional query flags (`--from`, `--to`,
+ * `--api-key`). Each maps 1:1 to its snake_case query param and is written ONLY when present; when
+ * NO flag is passed the SDK method is invoked with ZERO arguments (the `monitors list` pattern), so
+ * the bare `/v1/usage/daily` URL is serialized unchanged.
+ */
+export function makeUsageCommand(getGlobal) {
+    const cmd = new Command('usage').description('Account usage and billing-period reporting');
+    cmd
+        .command('get')
+        .description('Get current billing-period usage summary')
+        .action(async () => {
+        const g = getGlobal();
+        const client = buildClient(g);
+        try {
+            const result = await client.usage.get();
+            printResult(result, g.json);
+        }
+        catch (err) {
+            handleError(err);
+        }
+    });
+    cmd
+        .command('daily')
+        .description('Get daily usage breakdown (default last 30 days; max 366)')
+        .option('--from <date>', 'Start date YYYY-MM-DD (omitted → server default, 30 days ago)')
+        .option('--to <date>', 'End date YYYY-MM-DD (omitted → server default, today)')
+        .option('--api-key <ak_id>', 'Filter by API key prefixed ID (omitted → all keys)')
+        .action(async (opts) => {
+        const g = getGlobal();
+        const client = buildClient(g);
+        const params = {};
+        if (opts.from !== undefined)
+            params.from = opts.from;
+        if (opts.to !== undefined)
+            params.to = opts.to;
+        if (opts.apiKey !== undefined)
+            params.api_key = opts.apiKey;
+        try {
+            const result = Object.keys(params).length > 0
+                ? await client.usage.daily(params)
+                : await client.usage.daily();
+            printResult(result, g.json);
+        }
+        catch (err) {
+            handleError(err);
+        }
+    });
+    cmd
+        .command('by-endpoint')
+        .description('Get per-endpoint bandwidth breakdown (default last 30 days; max 366)')
+        .option('--from <date>', 'Start date YYYY-MM-DD (omitted → server default, 30 days ago)')
+        .option('--to <date>', 'End date YYYY-MM-DD (omitted → server default, today)')
+        .option('--api-key <ak_id>', 'Filter by API key prefixed ID (omitted → all keys)')
+        .action(async (opts) => {
+        const g = getGlobal();
+        const client = buildClient(g);
+        const params = {};
+        if (opts.from !== undefined)
+            params.from = opts.from;
+        if (opts.to !== undefined)
+            params.to = opts.to;
+        if (opts.apiKey !== undefined)
+            params.api_key = opts.apiKey;
+        try {
+            const result = Object.keys(params).length > 0
+                ? await client.usage.byEndpoint(params)
+                : await client.usage.byEndpoint();
+            printResult(result, g.json);
+        }
+        catch (err) {
+            handleError(err);
+        }
+    });
+    return cmd;
+}

package/dist/commands/webhook-deliveries.d.ts

@@ -0,0 +1,11 @@
+import { Command } from 'commander';
+import { type GlobalOptions } from '../client.js';
+/**
+ * The `webhook-deliveries` command group (#2545) — inspect and requeue webhook delivery attempts.
+ *
+ * `list` flags map 1:1 to their query params and are omitted-when-absent; a bare `list` calls the
+ * SDK with ZERO args so the plain `/v1/webhook-deliveries` URL is serialized unchanged.
+ */
+export declare function makeWebhookDeliveriesCommand(getGlobal: () => GlobalOptions & {
+    json: boolean;
+}): Command;

package/dist/commands/webhook-deliveries.js

@@ -0,0 +1,59 @@
+import { Command } from 'commander';
+import { buildClient } from '../client.js';
+import { printResult, handleError } from '../output.js';
+import { parseEnum, parseIntFlag } from '../lib/parse-flags.js';
+/** The `listWebhookDeliveries` `status` query enum (DISTINCT from the monitor status enum). */
+const DELIVERY_STATUSES = ['pending', 'delivered', 'failed', 'exhausted'];
+/**
+ * The `webhook-deliveries` command group (#2545) — inspect and requeue webhook delivery attempts.
+ *
+ * `list` flags map 1:1 to their query params and are omitted-when-absent; a bare `list` calls the
+ * SDK with ZERO args so the plain `/v1/webhook-deliveries` URL is serialized unchanged.
+ */
+export function makeWebhookDeliveriesCommand(getGlobal) {
+    const cmd = new Command('webhook-deliveries').description('Webhook delivery operations');
+    cmd
+        .command('list')
+        .description('List webhook deliveries')
+        .option('--limit <n>', 'Maximum number of deliveries to return', (v) => parseIntFlag('--limit', v))
+        .option('--cursor <cursor>', 'Pagination cursor from a previous page')
+        .option('--status <status>', `Filter by delivery status: ${DELIVERY_STATUSES.join(', ')}`, (v) => parseEnum('--status', DELIVERY_STATUSES, v))
+        .option('--since <iso>', 'Only deliveries created after this ISO date-time')
+        .action(async (opts) => {
+        const g = getGlobal();
+        const client = buildClient(g);
+        const params = {};
+        if (opts.limit !== undefined)
+            params.limit = opts.limit;
+        if (opts.cursor !== undefined)
+            params.cursor = opts.cursor;
+        if (opts.status !== undefined)
+            params.status = opts.status;
+        if (opts.since !== undefined)
+            params.since = opts.since;
+        try {
+            const result = Object.keys(params).length > 0
+                ? await client.webhooks.list(params)
+                : await client.webhooks.list();
+            printResult(result, g.json);
+        }
+        catch (err) {
+            handleError(err);
+        }
+    });
+    cmd
+        .command('retry <id>')
+        .description('Requeue a failed or exhausted webhook delivery')
+        .action(async (id) => {
+        const g = getGlobal();
+        const client = buildClient(g);
+        try {
+            const result = await client.webhooks.retry(id);
+            printResult(result, g.json);
+        }
+        catch (err) {
+            handleError(err);
+        }
+    });
+    return cmd;
+}

package/dist/index.js

@@ -11,6 +11,8 @@ import { makeMonitorsCommand } from './commands/monitors.js';
 import { makeSitemapCommand } from './commands/sitemap.js';
 import { makeSearchCommand } from './commands/search.js';
 import { makeAccountCommand } from './commands/account.js';
+import { makeUsageCommand } from './commands/usage.js';
+import { makeWebhookDeliveriesCommand } from './commands/webhook-deliveries.js';
 // Resolve version from package.json at runtime (supports compiled output).
 const require = createRequire(import.meta.url);
 // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
@@ -44,6 +46,8 @@ export function buildProgram() {
     program.addCommand(makeSitemapCommand(getGlobal));
     program.addCommand(makeSearchCommand(getGlobal));
     program.addCommand(makeAccountCommand(getGlobal));
+    program.addCommand(makeUsageCommand(getGlobal));
+    program.addCommand(makeWebhookDeliveriesCommand(getGlobal));
     return program;
 }
 /** Resolve symlinks and `..` segments, falling back to the raw path if it cannot be resolved. */

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

@@ -0,0 +1,13 @@
+/**
+ * Download a screenshot artifact from its `image_url` and write the raw bytes to `dest`.
+ *
+ * - `dest === '-'` writes the bytes to stdout (the conventional dash-is-stdout convention),
+ *   never with `console.log` — binary must not be coerced or newline-appended.
+ * - any other `dest` is a file path written verbatim.
+ *
+ * `globalThis.fetch` is resolved at CALL time (never captured at module/construction load) so a
+ * 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.
+ */
+export declare function downloadArtifact(url: string, dest: string): Promise<void>;

package/dist/lib/download-artifact.js

@@ -0,0 +1,25 @@
+import { writeFileSync } from 'node:fs';
+/**
+ * Download a screenshot artifact from its `image_url` and write the raw bytes to `dest`.
+ *
+ * - `dest === '-'` writes the bytes to stdout (the conventional dash-is-stdout convention),
+ *   never with `console.log` — binary must not be coerced or newline-appended.
+ * - any other `dest` is a file path written verbatim.
+ *
+ * `globalThis.fetch` is resolved at CALL time (never captured at module/construction load) so a
+ * 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.
+ */
+export async function downloadArtifact(url, dest) {
+    const res = await globalThis.fetch(url);
+    if (!res.ok) {
+        throw new Error(`artifact download failed: HTTP ${res.status}`);
+    }
+    const bytes = Buffer.from(await res.arrayBuffer());
+    if (dest === '-') {
+        process.stdout.write(bytes);
+        return;
+    }
+    writeFileSync(dest, bytes);
+}

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

@@ -0,0 +1,46 @@
+/**
+ * Shared commander argParser helpers for CLI flag values (#2480 cr-3). One home for the parser
+ * family that scrape.ts, screenshots.ts, and monitors.ts previously each held private copies of —
+ * every off-spec value is rejected locally, at parse time, with an actionable message, before any
+ * HTTP request is issued.
+ */
+/**
+ * Parse a whole-number flag value. The strict `/^\d+$/` test deterministically rejects `abc`, ``,
+ * `1.5`, `-5`, `1e2`, so an off-spec value fails at parse time with an actionable message instead
+ * of a server 422 or a NaN on the wire.
+ */
+export declare function parseIntFlag(flag: string, value: string): number;
+/** Reject an off-spec enum value at parse time with the allowed set in the message. */
+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

@@ -0,0 +1,90 @@
+import { InvalidArgumentError } from 'commander';
+/**
+ * Shared commander argParser helpers for CLI flag values (#2480 cr-3). One home for the parser
+ * family that scrape.ts, screenshots.ts, and monitors.ts previously each held private copies of —
+ * every off-spec value is rejected locally, at parse time, with an actionable message, before any
+ * HTTP request is issued.
+ */
+/**
+ * Parse a whole-number flag value. The strict `/^\d+$/` test deterministically rejects `abc`, ``,
+ * `1.5`, `-5`, `1e2`, so an off-spec value fails at parse time with an actionable message instead
+ * of a server 422 or a NaN on the wire.
+ */
+export function parseIntFlag(flag, value) {
+    if (!/^\d+$/.test(value)) {
+        throw new InvalidArgumentError(`${flag} must be a whole number.`);
+    }
+    return Number(value);
+}
+/** Reject an off-spec enum value at parse time with the allowed set in the message. */
+export function parseEnum(flag, allowed, value) {
+    if (!allowed.includes(value)) {
+        throw new InvalidArgumentError(`${flag} must be one of: ${allowed.join(', ')}.`);
+    }
+    return value;
+}
+/** Split a comma-separated flag value into a trimmed, non-empty string array. */
+export function parseCsv(value) {
+    return value
+        .split(',')
+        .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/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.
  *
@@ -56,6 +74,40 @@ export declare function resolveOutputMode(flags: OutputFlags): OutputMode;
  * not text, so `--raw` can never print `[object Object]` or a format the caller did not ask for.
  */
 export declare function extractRawBody(response: unknown, requestedFormat?: string): string;
+/**
+ * Exit code for `--raw`/`-o` against a 202 queued (async) scrape.
+ *
+ * Deliberately NOT 0 (a full raw-body success) and NOT 1 (a usage/API error): the job WAS accepted
+ * and billed, there is simply no content body to emit yet. A distinct code lets a caller branch on
+ * "queued" without parsing stderr.
+ */
+export declare const QUEUED_RAW_EXIT_CODE = 2;
+/** A 202 ScrapeQueuedEnvelope: `status: 'queued'` plus a stable `sc_` id (openapi.yaml). */
+interface QueuedEnvelope {
+    status: 'queued';
+    id: string;
+}
+/**
+ * Handle `--raw`/`-o` on a 202 queued envelope.
+ *
+ * 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 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): void;
 /**
  * Emit a raw body to the target.
  *
@@ -78,6 +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 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 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, target?: OutputTarget): void;
 /**
  * Print a result to stdout.
  *
@@ -86,5 +159,20 @@ export declare function emitResult(result: unknown, mode: OutputMode, target: Ou
 export declare function printResult(data: unknown, jsonMode: boolean): void;
 /**
  * Handle a CLI command error: print to stderr and exit 1.
+ *
+ * The message always begins `Error: ` (a prefix scripts grep on) followed by the error message and
+ * an optional parenthesised suffix built from the two diagnostic axes the ByteKit errors carry:
+ *
+ * - a `ByteKitError` from the transport carries both a numeric `status` and an API `code`
+ *   (`rate_limited`, `invalid_url`, …) → `Error: <message> (<code>, status: <n>)`;
+ * - a `ByteKitConnectionError` (client-side timeout / abort / socket failure) carries a `code`
+ *   (`timeout` | `aborted` | `connection`) but NO status → `Error: <message> (<code>)`;
+ * - a plain error with neither → `Error: <message>`.
+ *
+ * The `code` axis is read only off the two ByteKit error classes (see {@link errorCode}) — a plain
+ * error carrying an unrelated string `.code` (a Node errno error) gets NO code suffix. When a
+ * status is present but no code (a hand-built error), the suffix is `(status: <n>)` with no empty
+ * placeholder — never `(, status: <n>)`.
  */
 export declare function handleError(err: unknown): never;
+export {};