@hunt-labs/bytekit-cli 0.2.2 → 0.5.0

package/dist/commands/monitors.js

@@ -1,6 +1,19 @@
 import { Command } from 'commander';
 import { buildClient } from '../client.js';
 import { printResult, handleError } from '../output.js';
+import { parseEnum, parseIntFlag, parseNumberFlag, parseJsonFlag } from '../lib/parse-flags.js';
+/** The `listMonitors` `status` query enum (5-value list FILTER). */
+const MONITOR_STATUSES = ['active', 'processing', 'paused', 'cancelled', 'suspended'];
+/**
+ * The `MonitorUpdateRequest.status` enum — DISTINCT from {@link MONITOR_STATUSES}. Only `active`
+ * (resume) and `paused` (pause) are valid update targets (openapi.yaml MonitorUpdateRequest.status);
+ * the other three list-filter states are server-managed lifecycle states, not settable via PATCH.
+ */
+const MONITOR_UPDATE_STATUSES = ['active', 'paused'];
+/** The `notify_on` enum shared by MonitorCreateRequest / MonitorUpdateRequest. */
+const NOTIFY_ONS = ['change', 'every'];
+/** The create-only `type` enum (PATCH rejects `type` with 422 — immutable, issue #1984). */
+const MONITOR_TYPES = ['screenshot', 'scrape'];
 export function makeMonitorsCommand(getGlobal) {
     const cmd = new Command('monitors').description('Page-change monitor operations');
     const capturesCmd = new Command('captures').description('Monitor capture sub-resources');
@@ -26,9 +39,21 @@ export function makeMonitorsCommand(getGlobal) {
         .requiredOption('--interval-type <type>', 'Check interval: hourly, daily, weekly, or cron')
         .requiredOption('--webhook-url <url>', 'HTTPS webhook URL notified on change')
         .option('--cron <expr>', 'Cron expression (required when --interval-type is cron, e.g. "0 * * * *")')
+        // `--type` is CREATE-ONLY (a monitor's type is immutable per #1984); the PATCH builder below
+        // deliberately omits it.
+        .option('--type <type>', `Monitor type: ${MONITOR_TYPES.join(', ')} (omitted → server default screenshot)`, (v) => parseEnum('--type', MONITOR_TYPES, v))
+        .option('--change-threshold <pct>', 'Change percentage that triggers a notification (float; omitted → server default 5)', (v) => parseNumberFlag('--change-threshold', v))
+        .option('--notify-on <event>', `When to notify: ${NOTIFY_ONS.join(', ')} (omitted → server default change)`, (v) => parseEnum('--notify-on', NOTIFY_ONS, v))
+        .option('--webhook-secret <secret>', 'HMAC secret for webhook signature verification')
+        .option('--webhook-headers <json>', `Extra webhook headers as a JSON object, e.g. '{"X-Sig":"abc"}' (omitted → none)`, (v) => parseJsonFlag('--webhook-headers', v, 'object'))
+        .option('--options <json>', `Screenshot-monitor options as a JSON object (omitted → server defaults)`, (v) => parseJsonFlag('--options', v, 'object'))
+        .option('--scrape-options <json>', `Scrape-monitor options as a JSON object (type=scrape only; omitted → server defaults)`, (v) => parseJsonFlag('--scrape-options', v, 'object'))
         .action(async (opts) => {
         const g = getGlobal();
         const client = buildClient(g);
+        // Omit-when-absent body (same rule as scrape.ts): each key is written ONLY when its flag is
+        // present, so a bare create never materializes a server default (#2480 E1). Typed via an
+        // assertion at the call site — the wire body is pinned by request-shapes.test.ts.
         const body = {
             url: opts.url,
             interval_type: opts.intervalType,
@@ -36,6 +61,20 @@ export function makeMonitorsCommand(getGlobal) {
         };
         if (opts.cron !== undefined)
             body['cron_expression'] = opts.cron;
+        if (opts.type !== undefined)
+            body['type'] = opts.type;
+        if (opts.changeThreshold !== undefined)
+            body['change_threshold'] = opts.changeThreshold;
+        if (opts.notifyOn !== undefined)
+            body['notify_on'] = opts.notifyOn;
+        if (opts.webhookSecret !== undefined)
+            body['webhook_secret'] = opts.webhookSecret;
+        if (opts.webhookHeaders !== undefined)
+            body['webhook_headers'] = opts.webhookHeaders;
+        if (opts.options !== undefined)
+            body['options'] = opts.options;
+        if (opts.scrapeOptions !== undefined)
+            body['scrape_options'] = opts.scrapeOptions;
         try {
             const result = await client.monitors.create(body);
             printResult(result, g.json);
@@ -47,11 +86,29 @@ export function makeMonitorsCommand(getGlobal) {
     cmd
         .command('list')
         .description('List all monitors')
-        .action(async () => {
+        .option('--limit <n>', 'Maximum number of monitors to return', (v) => parseIntFlag('--limit', v))
+        .option('--cursor <cursor>', 'Pagination cursor from a previous page')
+        .option('--status <status>', `Filter by status: ${MONITOR_STATUSES.join(', ')} (default active)`, (v) => parseEnum('--status', MONITOR_STATUSES, v))
+        // `status` is the SDK's spec-derived `MonitorStatus` union, not a bare string (#2547) —
+        // `parseEnum` above already returns exactly that union, so this is a type-only narrowing
+        // with no runtime change.
+        .action(async (opts) => {
         const g = getGlobal();
         const client = buildClient(g);
+        // Build the params object with the same omit-when-absent rule as the body builders. When NO
+        // query flag is passed, call list() with ZERO arguments (never list({}) / list(undefined)) so
+        // the inverse-case request-shape assertion `monitors.list` args length 0 stays green (#2480).
+        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;
         try {
-            const result = await client.monitors.list();
+            const result = Object.keys(params).length > 0
+                ? await client.monitors.list(params)
+                : await client.monitors.list();
             printResult(result, g.json);
         }
         catch (err) {
@@ -74,10 +131,19 @@ export function makeMonitorsCommand(getGlobal) {
     });
     cmd
         .command('update <id>')
-        .description('Update a monitor')
+        .description('Update a monitor (including pause/resume via --status)')
         .option('--interval-type <type>', 'New check interval: hourly, daily, weekly, or cron')
         .option('--cron <expr>', 'New cron expression (when interval-type is cron, e.g. "0 * * * *")')
         .option('--webhook-url <url>', 'New HTTPS webhook URL')
+        // `--status` is the 2-value MonitorUpdateRequest.status enum — NOT the 5-value list filter.
+        // Deliberately NO `--type`: PATCH /v1/monitors/{id} rejects `type` with 422 (immutable, #1984).
+        .option('--status <status>', `Pause or resume the monitor: ${MONITOR_UPDATE_STATUSES.join(', ')}`, (v) => parseEnum('--status', MONITOR_UPDATE_STATUSES, v))
+        .option('--change-threshold <pct>', 'New change percentage that triggers a notification (float)', (v) => parseNumberFlag('--change-threshold', v))
+        .option('--notify-on <event>', `When to notify: ${NOTIFY_ONS.join(', ')}`, (v) => parseEnum('--notify-on', NOTIFY_ONS, v))
+        .option('--webhook-secret <secret>', 'New HMAC secret for webhook signature verification')
+        .option('--webhook-headers <json>', `New webhook headers as a JSON object, e.g. '{"X-Sig":"abc"}'`, (v) => parseJsonFlag('--webhook-headers', v, 'object'))
+        .option('--options <json>', `New screenshot-monitor options as a JSON object`, (v) => parseJsonFlag('--options', v, 'object'))
+        .option('--scrape-options <json>', `New scrape-monitor options as a JSON object`, (v) => parseJsonFlag('--scrape-options', v, 'object'))
         .action(async (id, opts) => {
         const g = getGlobal();
         const client = buildClient(g);
@@ -88,6 +154,20 @@ export function makeMonitorsCommand(getGlobal) {
             body['cron_expression'] = opts.cron;
         if (opts.webhookUrl !== undefined)
             body['webhook_url'] = opts.webhookUrl;
+        if (opts.status !== undefined)
+            body['status'] = opts.status;
+        if (opts.changeThreshold !== undefined)
+            body['change_threshold'] = opts.changeThreshold;
+        if (opts.notifyOn !== undefined)
+            body['notify_on'] = opts.notifyOn;
+        if (opts.webhookSecret !== undefined)
+            body['webhook_secret'] = opts.webhookSecret;
+        if (opts.webhookHeaders !== undefined)
+            body['webhook_headers'] = opts.webhookHeaders;
+        if (opts.options !== undefined)
+            body['options'] = opts.options;
+        if (opts.scrapeOptions !== undefined)
+            body['scrape_options'] = opts.scrapeOptions;
         try {
             const result = await client.monitors.update(id, body);
             printResult(result, g.json);

package/dist/commands/scrape.js

@@ -2,6 +2,43 @@ 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, parseCacheTtl, parseJsonFlag, collectFormats, } from '../lib/parse-flags.js';
+/** The `ScrapeRequest.markdown_mode` spec enum. */
+const MARKDOWN_MODES = ['article', 'raw', 'llm'];
+/** The `ScrapeRequest.events` item enum. */
+const SCRAPE_EVENTS = ['queued', 'completed', 'failed'];
+/** The `ScrapeRequest.token_encoding` spec enum. */
+const TOKEN_ENCODINGS = ['cl100k_base', 'o200k_base'];
+/** The `markdown_links` / `markdown_images` render-mode enum. */
+const MARKDOWN_RENDER_MODES = ['inline', 'references', 'none', 'text'];
+/**
+ * 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.
+ *
+ * BOTH modes carry it as a soft `process.exitCode` (#2544): raw mode used to hard-`process.exit`,
+ * which runs before Node drains an ASYNC piped stdout and could discard the id it had just
+ * written — the exact `$(…)` capture the raw branch exists for. Human mode was already soft.
+ */
+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');
@@ -42,18 +79,113 @@ export function makeScrapeCommand(getGlobal) {
         .command('create')
         .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')
+        // Repeatable AND CSV-aware: `--format raw_html --format markdown` and `--format raw_html,markdown`
+        // both send formats: ['raw_html','markdown']. Sent as the `formats` array; omitted → server
+        // default. `--raw`/`-o` require EXACTLY ONE format (validated pre-request; see the action).
+        .option('--format <format>', 'Output format; repeat or comma-separate for multiple (e.g. --format raw_html --format markdown, or --format raw_html,markdown). Sent as the formats array; omitted → server default.', collectFormats)
+        .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('--markdown-query <q>', 'BM25 query string for relevance-ranked markdown filtering (omitted → disabled)')
+        .option('--cache-ttl <ttl>', 'Cache freshness: 0, Nh (hours), or Nd (days), e.g. 48h, 2d, 0 (omitted → server default)', (v) => parseCacheTtl('--cache-ttl', v))
+        .option('--cookies <json>', `Cookies as a JSON array, e.g. '[{"name":"a","value":"b"}]' (omitted → none)`, (v) => parseJsonFlag('--cookies', v, 'array'))
+        .option('--headers <json>', `Extra request headers as a JSON object, e.g. '{"X-A":"b"}' (omitted → none)`, (v) => parseJsonFlag('--headers', v, 'object'))
+        .option('--delay-ms <n>', 'Post-load delay in milliseconds before capture', (v) => parseIntFlag('--delay-ms', v))
+        .option('--events <csv>', `Webhook events (comma-separated): ${SCRAPE_EVENTS.join(', ')} (omitted → server default)`, (v) => parseCsv(v).map((e) => parseEnum('--events', SCRAPE_EVENTS, e)))
+        .option('--token-encoding <enc>', `Tokenizer for --token-budget: ${TOKEN_ENCODINGS.join(', ')} (omitted → server default)`, (v) => parseEnum('--token-encoding', TOKEN_ENCODINGS, v))
+        .option('--custom <json>', `User payload echoed on the envelope as a JSON object, e.g. '{"job":"1"}' (omitted → none)`, (v) => parseJsonFlag('--custom', v, 'object'))
+        // Server default is TRUE, so this is a tri-state pair: --remove-base64-images → true,
+        // --no-remove-base64-images → false, neither → key omitted (never materialize the default, E6).
+        .option('--remove-base64-images', 'Strip base64 data: images before conversion (server default)')
+        .option('--no-remove-base64-images', 'Preserve base64 data: images in the pipeline output')
+        .option('--markdown-links <mode>', `Link rendering: ${MARKDOWN_RENDER_MODES.join(', ')}`, (v) => parseEnum('--markdown-links', MARKDOWN_RENDER_MODES, v))
+        .option('--markdown-images <mode>', `Image retention: ${MARKDOWN_RENDER_MODES.join(', ')}`, (v) => parseEnum('--markdown-images', MARKDOWN_RENDER_MODES, v))
+        .option('--with-links-summary', 'Append a Links footer to the markdown output')
+        .option('--with-images-summary', 'Append an Images footer to the markdown output')
+        .option('--markdown-compact', 'Collapse excessive whitespace in the markdown output')
+        .option('--markdown-filter-images', 'Filter low-signal images from the markdown output')
+        .option('--markdown-include-media', 'Return rich link/image objects and a tables array')
+        .option('--markdown-include-warnings', 'Include markdown-pipeline and tag-filter warnings')
+        .option('--markdown-include-stats', 'Include a top-level stats object (chars, tokens, blocks)')
+        .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) => {
         const g = getGlobal();
         const client = buildClient(g);
         const body = { url: opts.url };
-        // The v1 scrape validator expects `formats` (array), not `format` (string).
-        // Omit the key entirely when --format is not provided so we never send
-        // formats: ["undefined"].
-        if (opts.format !== undefined)
-            body['formats'] = [opts.format];
+        // The v1 scrape validator expects `formats` (array). The --format collector already
+        // accumulates repeated/CSV occurrences into an array; write it verbatim, omitting the key
+        // entirely when --format is absent so we never send formats: [] or ["undefined"].
+        const formats = opts.format;
+        if (formats !== undefined)
+            body['formats'] = formats;
+        // 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.markdownQuery !== undefined)
+            body['markdown_query'] = opts.markdownQuery;
+        if (opts.cacheTtl !== undefined)
+            body['cache_ttl'] = opts.cacheTtl;
+        if (opts.cookies !== undefined)
+            body['cookies'] = opts.cookies;
+        if (opts.headers !== undefined)
+            body['headers'] = opts.headers;
+        if (opts.delayMs !== undefined)
+            body['delay_ms'] = opts.delayMs;
+        if (opts.events !== undefined)
+            body['events'] = opts.events;
+        if (opts.tokenEncoding !== undefined)
+            body['token_encoding'] = opts.tokenEncoding;
+        if (opts.custom !== undefined)
+            body['custom'] = opts.custom;
+        // Tri-state boolean: commander yields `undefined` when neither --remove-base64-images nor
+        // --no-remove-base64-images is passed, so the key is omitted and the server default holds.
+        if (opts.removeBase64Images !== undefined)
+            body['remove_base64_images'] = opts.removeBase64Images;
+        if (opts.markdownLinks !== undefined)
+            body['markdown_links'] = opts.markdownLinks;
+        if (opts.markdownImages !== undefined)
+            body['markdown_images'] = opts.markdownImages;
+        if (opts.withLinksSummary === true)
+            body['with_links_summary'] = true;
+        if (opts.withImagesSummary === true)
+            body['with_images_summary'] = true;
+        if (opts.markdownCompact === true)
+            body['markdown_compact'] = true;
+        if (opts.markdownFilterImages === true)
+            body['markdown_filter_images'] = true;
+        if (opts.markdownIncludeMedia === true)
+            body['markdown_include_media'] = true;
+        if (opts.markdownIncludeWarnings === true)
+            body['markdown_include_warnings'] = true;
+        if (opts.markdownIncludeStats === true)
+            body['markdown_include_stats'] = true;
+        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
@@ -62,8 +194,47 @@ export function makeScrapeCommand(getGlobal) {
             // handleError()'s clean one-liner. buildClient() does no network I/O, so rejecting the
             // --json/--raw conflict here still happens before any request is issued.
             const mode = resolveOutputMode({ json: g.json, raw: opts.raw, output: opts.output });
+            // Raw mode (--raw or a bare -o) emits a SINGLE format body; more than one format is
+            // ambiguous, so reject before the request (E2). Thrown inside the try so handleError()
+            // prints the clean one-liner and no scrape.create call is ever recorded.
+            if (mode.kind === 'raw' && formats !== undefined && formats.length > 1) {
+                throw new Error('--raw requires exactly one --format');
+            }
             const result = await client.scrape.create(body);
-            emitResult(result, mode, { file: opts.output }, opts.format);
+            // 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 via soft `process.exitCode` (#2544 — a hard `process.exit` runs
+            //     before Node drains an ASYNC piped stdout and would discard the very id this
+            //     branch exists to deliver). 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.exitCode = QUEUED_EXIT_CODE;
+                    return;
+                }
+                if (mode.kind === 'human') {
+                    printResult(result, false);
+                    process.exitCode = QUEUED_EXIT_CODE;
+                    return;
+                }
+            }
+            // At this point raw mode has at most one format (E2 guard above), so formats[0] is the
+            // single requested body selector; json/human modes ignore the argument.
+            emitResult(result, mode, { file: opts.output }, formats?.[0]);
         }
         catch (err) {
             handleError(err);
@@ -71,13 +242,22 @@ export function makeScrapeCommand(getGlobal) {
     });
     cmd
         .command('get <id>')
-        .description('Get a scrape job by ID')
-        .action(async (id) => {
+        .description('Get a scrape job by ID (use --raw/-o/--format to retrieve a completed body)')
+        .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)')
+        .option('--format <format>', 'Which persisted format to emit raw when several are present')
+        .action(async (id, opts) => {
         const g = getGlobal();
         const client = buildClient(g);
         try {
+            // Mirror `scrape create`'s output path: resolveOutputMode FIRST inside the try (so a
+            // --json/--raw conflict rejects before the request), then emitResult. The request body is
+            // unchanged — scrape.get(id) takes no options — so the inverse-case arg-length assertion in
+            // request-shapes.test.ts stays green. A still-queued job flows through emitResult's
+            // queued-envelope branch (id + soft exit 2, #2508/#2544); a completed job emits its body.
+            const mode = resolveOutputMode({ json: g.json, raw: opts.raw, output: opts.output });
             const result = await client.scrape.get(id);
-            printResult(result, g.json);
+            emitResult(result, mode, { file: opts.output }, opts.format);
         }
         catch (err) {
             handleError(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,66 @@
-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'];
+/** `device_scale_factor` accepts only 1 or 2 (spec enum [1, 2, null]); parsed as a string, sent numeric. */
+const DEVICE_SCALE_FACTORS = ['1', '2'];
+/** 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 +68,91 @@ 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)
+        // Tri-state pairs — server default is TRUE, so define BOTH --x and --no-x: commander yields
+        // `undefined` when neither is passed, and the key is omitted (never materialize the default, E6).
+        .option('--block-ads', 'Block ads before capture (server default)')
+        .option('--no-block-ads', 'Do not block ads')
+        .option('--block-cookie-banners', 'Block cookie-consent banners before capture (server default)')
+        .option('--no-block-cookie-banners', 'Do not block cookie-consent banners')
+        .option('--scroll', 'Scroll the page before capture to trigger lazy content (server default)')
+        .option('--no-scroll', 'Do not scroll the page before capture')
+        .option('--wait-for-selector <sel>', 'Wait until this CSS selector is present before capture')
+        .option('--delay-ms <n>', 'Post-load delay in milliseconds before capture', (v) => parseIntFlag('--delay-ms', v))
+        .option('--dark-mode', 'Emulate prefers-color-scheme: dark')
+        .option('--device-scale-factor <n>', `Device pixel ratio: ${DEVICE_SCALE_FACTORS.join(', ')}`, (v) => parseEnum('--device-scale-factor', DEVICE_SCALE_FACTORS, v))
+        .option('--include-html', 'Include the rendered HTML alongside the screenshot')
+        .option('--country <cc>', 'Two-letter country code to route the request through (e.g. us, de)')
+        .option('--language <lang>', 'Accept-Language override (e.g. en-US)')
+        .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;
+        // Tri-state booleans: commander yields `undefined` when neither --x nor --no-x is passed,
+        // so the key is omitted and the server default (true) holds (E6).
+        if (opts.blockAds !== undefined)
+            body['block_ads'] = opts.blockAds;
+        if (opts.blockCookieBanners !== undefined)
+            body['block_cookie_banners'] = opts.blockCookieBanners;
+        if (opts.scroll !== undefined)
+            body['scroll'] = opts.scroll;
+        if (opts.waitForSelector !== undefined)
+            body['wait_for_selector'] = opts.waitForSelector;
+        if (opts.delayMs !== undefined)
+            body['delay_ms'] = opts.delayMs;
+        if (opts.darkMode === true)
+            body['dark_mode'] = true;
+        // device_scale_factor is a spec integer enum [1, 2]; the parser validates the string, and
+        // the wire value is numeric.
+        if (opts.deviceScaleFactor !== undefined)
+            body['device_scale_factor'] = Number(opts.deviceScaleFactor);
+        if (opts.includeHtml === true)
+            body['include_html'] = true;
+        if (opts.country !== undefined)
+            body['country'] = opts.country;
+        if (opts.language !== undefined)
+            body['language'] = opts.language;
         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 +161,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

@@ -1,17 +1,33 @@
 import { Command } from 'commander';
 import { buildClient } from '../client.js';
 import { printResult, handleError } from '../output.js';
+import { parseEnum, parseIntFlag } from '../lib/parse-flags.js';
+/** The `SitemapRequest.strategy` spec enum. */
+const SITEMAP_STRATEGIES = ['quick', 'standard', 'deep'];
 export function makeSitemapCommand(getGlobal) {
     const cmd = new Command('sitemap').description('Sitemap crawl operations');
     cmd
         .command('create')
         .description('Start a sitemap crawl')
         .requiredOption('--url <url>', 'Root URL to crawl')
+        .option('--strategy <strategy>', `Crawl strategy: ${SITEMAP_STRATEGIES.join(', ')} (omitted → server default standard)`, (v) => parseEnum('--strategy', SITEMAP_STRATEGIES, v))
+        .option('--max-depth <n>', 'Maximum crawl depth 1-5 (omitted → server default 2)', (v) => parseIntFlag('--max-depth', v))
+        .option('--max-urls <n>', 'Maximum URLs to collect (omitted → server default 5000)', (v) => parseIntFlag('--max-urls', v))
         .action(async (opts) => {
         const g = getGlobal();
         const client = buildClient(g);
+        // Omit-when-absent body; the remaining SitemapRequest fields keep their server defaults.
+        // The generated request type marks defaulted fields required, so the call needs an explicit
+        // assertion — type-level only; the wire body is pinned by request-shapes.test.ts.
+        const body = { url: opts.url };
+        if (opts.strategy !== undefined)
+            body['strategy'] = opts.strategy;
+        if (opts.maxDepth !== undefined)
+            body['max_depth'] = opts.maxDepth;
+        if (opts.maxUrls !== undefined)
+            body['max_urls'] = opts.maxUrls;
         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/commands/usage.d.ts

@@ -0,0 +1,13 @@
+import { Command } from 'commander';
+import { type GlobalOptions } from '../client.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 declare function makeUsageCommand(getGlobal: () => GlobalOptions & {
+    json: boolean;
+}): Command;