@hunt-labs/bytekit-cli 0.2.2 → 0.3.0

package/dist/commands/scrape.js

@@ -2,6 +2,34 @@ import { Command } from 'commander';
 import { buildClient } from '../client.js';
 import { printResult, handleError, resolveOutputMode, emitResult } from '../output.js';
 import { parseUrlLines } from '../lib/url-lines.js';
+import { parseIntFlag, parseEnum, parseCsv } from '../lib/parse-flags.js';
+/** The `ScrapeRequest.markdown_mode` spec enum. */
+const MARKDOWN_MODES = ['article', 'raw', 'llm'];
+/**
+ * Exit code when a queued (202 async) envelope reaches a non-JSON output mode.
+ *
+ * Mirrors the transport-hardening ticket's `QUEUED_RAW_EXIT_CODE` in `output.ts` (PR #2508)
+ * EXACTLY — deliberately a local constant, not an import, so this branch carries no dependency on
+ * that PR's symbols while the two guards still compose idempotently post-merge. Deliberately NOT 0
+ * (a content-body success) and NOT 1 (a usage/API error): the job WAS accepted and billed, there
+ * is simply no content body yet, and a distinct code lets a caller branch on "queued" without
+ * parsing stderr. Human mode shares the same code (soft `process.exitCode`) so "queued, not
+ * complete" is branchable there too, for consistency with the raw-mode signal.
+ */
+const QUEUED_EXIT_CODE = 2;
+/**
+ * A 202 ScrapeQueuedEnvelope: `status: 'queued'` plus a stable `sc_` id (openapi.yaml).
+ *
+ * The strict discriminator — identical to #2508's `output.ts` guard, so both guards agree on
+ * every input post-merge. A malformed queued-ish shape (no id, or a non-'queued' status) falls
+ * through to the normal output path and surfaces `output.ts`'s own diagnostics (#2480 E4s).
+ */
+function isQueuedEnvelope(result) {
+    if (typeof result !== 'object' || result === null)
+        return false;
+    const obj = result;
+    return obj.status === 'queued' && typeof obj.id === 'string' && obj.id.length > 0;
+}
 export function makeScrapeCommand(getGlobal) {
     const cmd = new Command('scrape').description('Scrape URL content');
     const bulkCmd = new Command('bulk').description('Bulk scrape operations');
@@ -43,6 +71,16 @@ export function makeScrapeCommand(getGlobal) {
         .description('Create a scrape job')
         .requiredOption('--url <url>', 'URL to scrape')
         .option('--format <format>', 'Output format (e.g. markdown, html); sent as the formats array')
+        .option('--country <cc>', 'Two-letter country code to route the request through (e.g. us, de)')
+        .option('--timeout-ms <n>', 'Per-request timeout in milliseconds', (v) => parseIntFlag('--timeout-ms', v))
+        .option('--markdown-mode <mode>', `Markdown extraction mode: ${MARKDOWN_MODES.join(', ')}`, (v) => parseEnum('--markdown-mode', MARKDOWN_MODES, v))
+        .option('--async', 'Queue the scrape and return a job envelope immediately (no wait)')
+        .option('--webhook-url <url>', 'HTTPS webhook URL notified when an async scrape completes')
+        .option('--token-budget <n>', 'Maximum tokens of markdown to return', (v) => parseIntFlag('--token-budget', v))
+        .option('--clean-markdown', 'Post-process markdown with the LLM cleaner (billed 3x)')
+        .option('--include-tags <csv>', 'Comma-separated HTML tags to keep (e.g. article,main)')
+        .option('--exclude-tags <csv>', 'Comma-separated HTML tags to drop (e.g. nav,footer)')
+        .option('--mobile', 'Render with a mobile viewport/user-agent')
         .option('--raw', 'Print the requested format body raw, with no JSON wrapper')
         .option('-o, --output <file>', 'Write the output to the given file path (implies --raw unless --json is set)')
         .action(async (opts) => {
@@ -54,6 +92,28 @@ export function makeScrapeCommand(getGlobal) {
         // formats: ["undefined"].
         if (opts.format !== undefined)
             body['formats'] = [opts.format];
+        // Each optional flag maps 1:1 to its snake_case ScrapeRequest field and is written ONLY
+        // when the flag is present — a boolean must never serialize `false` (#2480 E1).
+        if (opts.country !== undefined)
+            body['country'] = opts.country;
+        if (opts.timeoutMs !== undefined)
+            body['timeout_ms'] = opts.timeoutMs;
+        if (opts.markdownMode !== undefined)
+            body['markdown_mode'] = opts.markdownMode;
+        if (opts.async === true)
+            body['async'] = true;
+        if (opts.webhookUrl !== undefined)
+            body['webhook_url'] = opts.webhookUrl;
+        if (opts.tokenBudget !== undefined)
+            body['token_budget'] = opts.tokenBudget;
+        if (opts.cleanMarkdown === true)
+            body['clean_markdown'] = true;
+        if (opts.includeTags !== undefined)
+            body['include_tags'] = parseCsv(opts.includeTags);
+        if (opts.excludeTags !== undefined)
+            body['exclude_tags'] = parseCsv(opts.excludeTags);
+        if (opts.mobile === true)
+            body['mobile'] = true;
         try {
             // FIRST statement inside the try — deliberately NOT hoisted next to buildClient() where
             // the other handlers put pre-request logic. index.ts drives commander with .parse(), not
@@ -63,6 +123,34 @@ export function makeScrapeCommand(getGlobal) {
             // --json/--raw conflict here still happens before any request is issued.
             const mode = resolveOutputMode({ json: g.json, raw: opts.raw, output: opts.output });
             const result = await client.scrape.create(body);
+            // Queued-envelope precedence (#2480 E4s): a `--async` scrape returns a 202
+            // `{ id, status: 'queued' }` envelope with NO formats map. Detect that shape here —
+            // AFTER the request returns, BEFORE raw-format extraction — per the contract the
+            // transport-hardening ticket (#2508) establishes in `output.ts`, mirrored verbatim so
+            // the two guards compose idempotently post-merge (this one runs first and must be
+            // indistinguishable from that one):
+            //   - raw mode (`--raw` or a bare `-o`): the bare sc_ id on STDOUT (a usable
+            //     `$(bytekit scrape create … --raw)` handle), a human poll note on STDERR, exit
+            //     QUEUED_EXIT_CODE. The `-o` file is deliberately NEVER written — there is no
+            //     content body yet, and a file holding a bare id would masquerade as content.
+            //   - json mode (`--json`, with or without `-o`): OUTSIDE the raw rule — fall through
+            //     to emitResult, which emits the envelope verbatim (exit 0).
+            //   - human default: keep the readable id/status dump, but signal queued-not-complete
+            //     with the same exit code 2 — via soft `process.exitCode` (not `process.exit`) so
+            //     the dump is guaranteed to flush before the process ends naturally.
+            if (isQueuedEnvelope(result)) {
+                if (mode.kind === 'raw') {
+                    console.error(`Note: scrape ${result.id} was queued (async) — no content body is available yet. ` +
+                        `Poll it with: bytekit scrape get ${result.id}`);
+                    process.stdout.write(`${result.id}\n`);
+                    process.exit(QUEUED_EXIT_CODE);
+                }
+                if (mode.kind === 'human') {
+                    printResult(result, false);
+                    process.exitCode = QUEUED_EXIT_CODE;
+                    return;
+                }
+            }
             emitResult(result, mode, { file: opts.output }, opts.format);
         }
         catch (err) {

package/dist/commands/screenshots.d.ts

@@ -1,5 +1,17 @@
 import { Command } from 'commander';
 import { type GlobalOptions } from '../client.js';
+/** Parse `--viewport WxH` (e.g. `1280x720`) into `{ width, height }`; reject malformed input. */
+export declare function parseViewport(value: string): {
+    width: number;
+    height: number;
+};
+/** Parse `--clip x,y,w,h` into `{ x, y, width, height }`; reject malformed input. */
+export declare function parseClip(value: string): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
 export declare function makeScreenshotsCommand(getGlobal: () => GlobalOptions & {
     json: boolean;
 }): Command;

package/dist/commands/screenshots.js

@@ -1,6 +1,64 @@
-import { Command } from 'commander';
+import { Command, InvalidArgumentError } from 'commander';
 import { buildClient } from '../client.js';
 import { printResult, handleError } from '../output.js';
+import { downloadArtifact } from '../lib/download-artifact.js';
+import { parseEnum, parseIntFlag } from '../lib/parse-flags.js';
+/** `ScreenshotRequest` spec enums. */
+const DEVICES = ['desktop', 'mobile'];
+const FORMATS = ['jpeg', 'png'];
+const WAIT_UNTILS = ['load', 'domcontentloaded', 'networkidle'];
+/** Parse `--viewport WxH` (e.g. `1280x720`) into `{ width, height }`; reject malformed input. */
+export function parseViewport(value) {
+    const m = /^(\d+)x(\d+)$/.exec(value);
+    if (!m)
+        throw new InvalidArgumentError('--viewport must be WIDTHxHEIGHT (e.g. 1280x720).');
+    return { width: Number(m[1]), height: Number(m[2]) };
+}
+/** Parse `--clip x,y,w,h` into `{ x, y, width, height }`; reject malformed input. */
+export function parseClip(value) {
+    const m = /^(\d+),(\d+),(\d+),(\d+)$/.exec(value);
+    if (!m)
+        throw new InvalidArgumentError('--clip must be X,Y,WIDTH,HEIGHT (e.g. 0,0,800,600).');
+    return { x: Number(m[1]), y: Number(m[2]), width: Number(m[3]), height: Number(m[4]) };
+}
+/**
+ * Extract a non-empty string `image_url` from a screenshot envelope, or throw an actionable error.
+ *
+ * A pending/processing envelope has no `image_url` yet; a terminal-`failed` screenshot returns the
+ * unified `Error` envelope on a 200 (#2027). Either way the artifact was never materialized, so we
+ * throw rather than fetching `undefined` (#2480 E5).
+ */
+function extractImageUrl(result) {
+    if (typeof result === 'object' && result !== null) {
+        const obj = result;
+        if (obj.error) {
+            throw new Error(`screenshot failed: ${obj.error.message ?? obj.error.code ?? 'unknown error'}`);
+        }
+        if (typeof obj.image_url === 'string' && obj.image_url.length > 0) {
+            return obj.image_url;
+        }
+        const status = typeof obj.status === 'string' ? obj.status : 'unknown';
+        throw new Error(`not ready yet: screenshot is ${status}`);
+    }
+    throw new Error('not ready yet: screenshot is unknown');
+}
+/**
+ * Render a screenshot result: with `-o` download the `image_url` artifact bytes (to a file, or to
+ * stdout with `-o -`); otherwise print the envelope. `--async` + `-o` prints the queued envelope
+ * and skips the download (queued-envelope precedence, #2480 E4). `--json` + `-o` is rejected by the
+ * caller BEFORE any request so `--json` can never emit binary (#2480 E2).
+ */
+async function emitScreenshot(result, opts) {
+    if (opts.isAsync === true) {
+        printResult(result, opts.json);
+        return;
+    }
+    if (opts.output !== undefined) {
+        await downloadArtifact(extractImageUrl(result), opts.output);
+        return;
+    }
+    printResult(result, opts.json);
+}
 export function makeScreenshotsCommand(getGlobal) {
     const cmd = new Command('screenshots').description('Screenshot operations');
     cmd
@@ -8,15 +66,52 @@ export function makeScreenshotsCommand(getGlobal) {
         .description('Capture a screenshot')
         .requiredOption('--url <url>', 'URL to screenshot')
         .option('--full-page', 'Capture the full page (default: viewport only)')
+        .option('--device <device>', `Device profile: ${DEVICES.join(', ')}`, (v) => parseEnum('--device', DEVICES, v))
+        .option('--viewport <WxH>', 'Viewport size WIDTHxHEIGHT (e.g. 1280x720)', parseViewport)
+        .option('--format <format>', `Image format: ${FORMATS.join(', ')}`, (v) => parseEnum('--format', FORMATS, v))
+        .option('--quality <n>', 'JPEG quality (1-100)', (v) => parseIntFlag('--quality', v))
+        .option('--wait-until <event>', `Wait condition: ${WAIT_UNTILS.join(', ')}`, (v) => parseEnum('--wait-until', WAIT_UNTILS, v))
+        .option('--clip <x,y,w,h>', 'Clip region X,Y,WIDTH,HEIGHT (e.g. 0,0,800,600)', parseClip)
+        .option('--async', 'Queue the screenshot and return a job envelope immediately (no wait)')
+        .option('-o, --output <file>', 'Download the captured image to this file path (use - for stdout). Not valid with --json.')
         .action(async (opts) => {
         const g = getGlobal();
         const client = buildClient(g);
         const body = { url: opts.url };
+        // Each optional flag maps 1:1 to its snake_case ScreenshotRequest field, written ONLY when
+        // present — a boolean never serializes `false` (#2480 E1).
         if (opts.fullPage === true)
-            body.full_page = true;
+            body['full_page'] = true;
+        if (opts.device !== undefined)
+            body['device'] = opts.device;
+        if (opts.viewport !== undefined)
+            body['viewport'] = opts.viewport;
+        if (opts.format !== undefined)
+            body['format'] = opts.format;
+        if (opts.quality !== undefined)
+            body['quality'] = opts.quality;
+        if (opts.waitUntil !== undefined)
+            body['wait_until'] = opts.waitUntil;
+        if (opts.clip !== undefined)
+            body['clip'] = opts.clip;
         try {
-            const result = await client.screenshots.create(body);
-            printResult(result, g.json);
+            // Reject --json + -o BEFORE issuing the request: -o downloads BINARY artifact bytes, so
+            // it can never coexist with --json (which must stay a text envelope). Thrown here so no
+            // request — and therefore no download fetch — is ever issued (#2480 E2).
+            if (g.json && opts.output !== undefined) {
+                throw new Error('-o cannot be used with --json');
+            }
+            const typedBody = body;
+            // --async is a QUERY param; pass the second arg ONLY when present so existing single-arg
+            // callers stay byte-identical (#2480 inverse case).
+            const result = opts.async === true
+                ? await client.screenshots.create(typedBody, { async: true })
+                : await client.screenshots.create(typedBody);
+            await emitScreenshot(result, {
+                output: opts.output,
+                json: g.json,
+                isAsync: opts.async === true,
+            });
         }
         catch (err) {
             handleError(err);
@@ -25,12 +120,16 @@ export function makeScreenshotsCommand(getGlobal) {
     cmd
         .command('get <id>')
         .description('Get a screenshot by ID')
-        .action(async (id) => {
+        .option('-o, --output <file>', 'Download the captured image to this file path (use - for stdout). Not valid with --json.')
+        .action(async (id, opts) => {
         const g = getGlobal();
         const client = buildClient(g);
         try {
+            if (g.json && opts.output !== undefined) {
+                throw new Error('-o cannot be used with --json');
+            }
             const result = await client.screenshots.get(id);
-            printResult(result, g.json);
+            await emitScreenshot(result, { output: opts.output, json: g.json });
         }
         catch (err) {
             handleError(err);

package/dist/commands/search.js

@@ -11,7 +11,11 @@ function renderTable(response) {
     for (const result of response.results) {
         console.log(`${result.position}. ${result.title}`);
         console.log(`   ${result.url}`);
-        console.log(`   ${result.snippet}`);
+        // `snippet` is typed as required but is OMITTED for `--type images` results (openapi.yaml),
+        // so guard against printing a literal `undefined` line when it is absent or empty.
+        if (typeof result.snippet === 'string' && result.snippet.length > 0) {
+            console.log(`   ${result.snippet}`);
+        }
     }
 }
 const LIMIT_MIN = 1;

package/dist/commands/sitemap.js

@@ -10,8 +10,15 @@ export function makeSitemapCommand(getGlobal) {
         .action(async (opts) => {
         const g = getGlobal();
         const client = buildClient(g);
+        // Key-checked subset of the SDK's SitemapCreateRequest (same pattern as monitors.ts).
+        // The CLI intentionally sends only `url` and relies on the server-side defaults the spec
+        // declares for the remaining SitemapRequest fields (strategy, max_depth, max_urls, …).
+        // The generated request type marks those fields required, so the final call needs an
+        // explicit assertion — type-level only; the wire body is unchanged (pinned by
+        // __tests__/request-shapes.test.ts).
+        const body = { url: opts.url };
         try {
-            const result = await client.sitemap.create({ url: opts.url });
+            const result = await client.sitemap.create(body);
             printResult(result, g.json);
         }
         catch (err) {

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/fetch-body.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A raw (non-JSON) response body from a `/v1/fetch` content request, plus its `X-Fetch-*` metadata.
+ *
+ * The `/v1/fetch` content endpoints (POST and GET) return the fetched bytes AS the body — HTML,
+ * markdown, or arbitrary binary — with all metadata in `X-Fetch-*` response headers. Every OTHER
+ * endpoint (including `/v1/fetch/bulk`) returns a JSON envelope. The CLI transport tags a content
+ * result with this shape so the `fetch` command can print the body verbatim (default) or the
+ * metadata as JSON (`--json`), instead of JSON-parsing a body that was never JSON to begin with.
+ */
+export interface FetchBodyResult {
+    readonly __bytekitFetchBody: true;
+    /** The raw response body bytes, uncorrupted — safe for binary content (no string coercion). */
+    readonly body: Buffer;
+    /** The `X-Fetch-*` response headers, Title-Cased (`x-fetch-status` → `X-Fetch-Status`). */
+    readonly metadata: Record<string, string>;
+}
+/** Narrow an arbitrary transport result to a {@link FetchBodyResult}. */
+export declare function isFetchBodyResult(value: unknown): value is FetchBodyResult;

package/dist/lib/fetch-body.js

@@ -0,0 +1,6 @@
+/** Narrow an arbitrary transport result to a {@link FetchBodyResult}. */
+export function isFetchBodyResult(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value.__bytekitFetchBody === true);
+}

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

@@ -0,0 +1,16 @@
+/**
+ * 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[];

package/dist/lib/parse-flags.js

@@ -0,0 +1,32 @@
+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);
+}

package/dist/output.d.ts

@@ -56,6 +56,29 @@ 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 exit
+ * with {@link QUEUED_RAW_EXIT_CODE} — distinguishable from both success and error.
+ */
+export declare function emitQueuedRaw(env: QueuedEnvelope): never;
 /**
  * Emit a raw body to the target.
  *
@@ -78,6 +101,18 @@ 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;
+/**
+ * Render a `/v1/fetch` content result.
+ *
+ * The transport hands back a {@link FetchBodyResult} whose body IS the fetched content and whose
+ * metadata are the `X-Fetch-*` headers. Default: write the raw body bytes to stdout verbatim
+ * (`process.stdout.write`, never `console.log` — no coercion, no appended newline, binary-safe).
+ * With `--json`: print the `X-Fetch-*` metadata as JSON instead of the body.
+ *
+ * Falls back to {@link printResult} for any result that is not a fetch body (defensive — e.g. a
+ * bulk-fetch envelope routed here by mistake), so no path can silently emit nothing.
+ */
+export declare function emitFetchResult(result: unknown, jsonMode: boolean): void;
 /**
  * Print a result to stdout.
  *
@@ -86,5 +121,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 {};

package/dist/output.js

@@ -1,4 +1,5 @@
 import { writeFileSync } from 'node:fs';
+import { isFetchBodyResult } from './lib/fetch-body.js';
 /** Text formats whose bodies are strings and can therefore be emitted raw. */
 const TEXT_FORMATS = 'markdown, html, raw_html';
 /**
@@ -71,6 +72,36 @@ export function extractRawBody(response, requestedFormat) {
     }
     return value;
 }
+/**
+ * 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 const QUEUED_RAW_EXIT_CODE = 2;
+/** Is `result` a 202 queued scrape envelope carrying a job id? */
+function isQueuedEnvelope(result) {
+    if (typeof result !== 'object' || result === null)
+        return false;
+    const obj = result;
+    return obj.status === 'queued' && typeof obj.id === 'string' && obj.id.length > 0;
+}
+/**
+ * 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 exit
+ * with {@link QUEUED_RAW_EXIT_CODE} — distinguishable from both success and error.
+ */
+export function emitQueuedRaw(env) {
+    console.error(`Note: scrape ${env.id} was queued (async) — no content body is available yet. ` +
+        `Poll it with: bytekit scrape get ${env.id}`);
+    process.stdout.write(`${env.id}\n`);
+    process.exit(QUEUED_RAW_EXIT_CODE);
+}
 /**
  * Emit a raw body to the target.
  *
@@ -101,6 +132,14 @@ export function emitRaw(body, target) {
  */
 export function emitResult(result, mode, target, requestedFormat) {
     if (mode.kind === 'raw') {
+        // A 202 queued scrape has no format body to print — surface its `sc_` handle instead of
+        // throwing away the accepted (and billed) job. Scoped to raw mode only: json/human rendering
+        // of a queued envelope stays unchanged (falls through to printResult below). A `-o <file>`
+        // target is deliberately ignored here (id always on STDOUT, never written to the file): there
+        // is no content body yet, and a file holding a bare `sc_` id would masquerade as content.
+        if (isQueuedEnvelope(result)) {
+            emitQueuedRaw(result);
+        }
         emitRaw(extractRawBody(result, requestedFormat), target);
         return;
     }
@@ -115,6 +154,28 @@ export function emitResult(result, mode, target, requestedFormat) {
     // human — unreachable with a file destination (resolveOutputMode never yields it alongside one).
     printResult(result, false);
 }
+/**
+ * Render a `/v1/fetch` content result.
+ *
+ * The transport hands back a {@link FetchBodyResult} whose body IS the fetched content and whose
+ * metadata are the `X-Fetch-*` headers. Default: write the raw body bytes to stdout verbatim
+ * (`process.stdout.write`, never `console.log` — no coercion, no appended newline, binary-safe).
+ * With `--json`: print the `X-Fetch-*` metadata as JSON instead of the body.
+ *
+ * Falls back to {@link printResult} for any result that is not a fetch body (defensive — e.g. a
+ * bulk-fetch envelope routed here by mistake), so no path can silently emit nothing.
+ */
+export function emitFetchResult(result, jsonMode) {
+    if (isFetchBodyResult(result)) {
+        if (jsonMode) {
+            console.log(JSON.stringify(result.metadata, null, 2));
+            return;
+        }
+        process.stdout.write(result.body);
+        return;
+    }
+    printResult(result, jsonMode);
+}
 /**
  * Print a result to stdout.
  *
@@ -139,19 +200,52 @@ export function printResult(data, jsonMode) {
     }
     console.log(JSON.stringify(data, null, 2));
 }
+/** The SDK error classes whose `code` is a ByteKit diagnostic worth surfacing as a suffix. */
+const BYTEKIT_ERROR_NAMES = new Set(['ByteKitError', 'ByteKitConnectionError']);
+/**
+ * A non-empty API/connection error `code`, or undefined when absent.
+ *
+ * Scoped by `err.name` to the ByteKit taxonomy: plenty of OTHER errors also carry a string
+ * `.code` — Node fs/system errors (ENOENT from `parseUrlLines`'s readFileSync, EACCES on a `-o`
+ * write) — whose message already embeds the code, so suffixing them would render the redundant
+ * `Error: ENOENT: … (ENOENT)`. Only `ByteKitError` / `ByteKitConnectionError` codes qualify.
+ */
+function errorCode(err) {
+    if (!BYTEKIT_ERROR_NAMES.has(err.name))
+        return undefined;
+    const raw = err.code;
+    return typeof raw === 'string' && raw.length > 0 ? raw : undefined;
+}
 /**
  * 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 function handleError(err) {
     if (err instanceof Error) {
-        const hasStatus = 'status' in err && typeof err.status === 'number';
+        const status = err.status;
+        const hasStatus = typeof status === 'number';
+        const code = errorCode(err);
+        let suffix = '';
         if (hasStatus) {
-            const apiErr = err;
-            console.error(`Error: ${apiErr.message} (status: ${apiErr.status})`);
+            suffix = code !== undefined ? ` (${code}, status: ${status})` : ` (status: ${status})`;
         }
-        else {
-            console.error(`Error: ${err.message}`);
+        else if (code !== undefined) {
+            suffix = ` (${code})`;
         }
+        console.error(`Error: ${err.message}${suffix}`);
     }
     else {
         console.error(`Error: ${String(err)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hunt-labs/bytekit-cli",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "ByteKit CLI — wraps @hunt-labs/bytekit-sdk as shell subcommands",
   "license": "MIT",
   "type": "module",
@@ -41,7 +41,7 @@
   ],
   "dependencies": {
     "commander": "^12.0.0",
-    "@hunt-labs/bytekit-sdk": "^0.2.2"
+    "@hunt-labs/bytekit-sdk": "^0.3.0"
   },
   "scripts": {
     "build": "tsc",