@hunt-labs/bytekit-cli 0.9.3 → 0.10.0

package/CHANGELOG.md

@@ -10,6 +10,27 @@ today, see [README.md](./README.md), which remains the authoritative usage guide
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-09-14
+
+### Added
+
+- `--solve-challenge` on `scrape create` (#4449). It sends `solve_challenge: true`, which asks
+  the scrape to attempt to clear a Cloudflare challenge; success is not guaranteed. It is billed
+  as a normal browser render. Without the flag the request body is unchanged and carries no
+  `solve_challenge` key.
+
+## [0.9.4] - 2026-09-10
+
+### Added
+
+- `--cursor`, `--limit` and `--status` on the three bulk recovery commands (#3717):
+  `bulk screenshots list <id>`, `scrape bulk get <id>` and `fetch bulk get <id>`.
+  They forward the cursor pagination the API already exposed, so a job whose webhook
+  manifest came back incomplete can be enumerated page by page from the CLI.
+  `--limit` is bounded 1-500 and `--status` accepts only the documented result
+  statuses; both are rejected locally before a request is made. No new command and no
+  `--all` flag — the existing commands gained options, nothing else moved.
+
 ## [0.9.3] - 2026-09-03
 
 ### Changed

package/README.md

@@ -129,6 +129,7 @@ materialized):
 | `--include-tags <csv>`                                 | Comma-separated HTML tags to keep.                                                                                                                                                  |
 | `--exclude-tags <csv>`                                 | Comma-separated HTML tags to drop.                                                                                                                                                  |
 | `--mobile`                                             | Render with a mobile viewport/user-agent.                                                                                                                                           |
+| `--solve-challenge`                                    | Attempt to clear a Cloudflare challenge; success is not guaranteed. Billed as a normal browser render.                                                                              |
 | `--async`                                              | Queue the scrape and return a job envelope immediately.                                                                                                                             |
 | `--webhook-url <url>`                                  | Webhook notified when an async scrape completes.                                                                                                                                    |
 
@@ -276,8 +277,10 @@ bytekit bulk screenshots list "$bulk_id"
 `urls.txt` is newline-delimited: one plain URL (or `{"url":"https://..."}`) per
 line. A line whose only key is `url` is sent as a bare URL string; any line with
 additional keys switches that entry to the per-item shape. `bulk cancel <id>`
-stops an in-flight job; `bulk get <id>` and `bulk screenshots list <id>` take no
-flags.
+stops an in-flight job. Recover another result page with `--cursor <cursor>`,
+bound it with `--limit <n>`, or filter it with `--status <status>` on
+`bulk screenshots list <id>`. The same recovery options are available on
+`scrape bulk get <id>` and `fetch bulk get <id>`.
 
 The three bulk-job creators — `bulk create`, `scrape bulk create` and
 `fetch bulk create` — share one flag set:

package/dist/commands/bulk.js

@@ -2,19 +2,34 @@ import { Command } from 'commander';
 import { buildClient } from '../client.js';
 import { printResult, handleError } from '../output.js';
 import { parseBulkLines, toBulkItems } from '../lib/url-lines.js';
-import { parseJsonFlag } from '../lib/parse-flags.js';
+import { parseEnum, parseIntFlag, parseJsonFlag } from '../lib/parse-flags.js';
+const BULK_RESULT_STATUSES = ['pending', 'processing', 'completed', 'failed', 'cancelled'];
+// Mirrors the `limit` query schema (`minimum: 1, maximum: 500`) on this job's recovery route in
+// docs/api/openapi.yaml, so the range the `--limit` help text advertises is enforced locally.
+const PAGE_LIMIT_BOUNDS = { min: 1, max: 500 };
 export function makeBulkCommand(getGlobal) {
     const cmd = new Command('bulk').description('Bulk screenshot operations');
     const screenshotsCmd = new Command('screenshots').description('Bulk screenshot sub-resources');
     screenshotsCmd
         .command('list <id>')
-        .description('List screenshots in a bulk job')
-        .action(async (id) => {
+        .description('List items in a mixed bulk job')
+        .option('--cursor <cursor>', 'Continue from a cursor returned by the preceding page')
+        .option('--limit <n>', 'Maximum items per type to return (1-500)', (v) => parseIntFlag('--limit', v, PAGE_LIMIT_BOUNDS))
+        .option('--status <status>', `Filter items by status: ${BULK_RESULT_STATUSES.join(', ')}`, (v) => parseEnum('--status', BULK_RESULT_STATUSES, v))
+        .action(async (id, opts) => {
         const g = getGlobal();
         try {
             // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
             const client = buildClient(g);
-            const result = await client.bulk.screenshots.list(id);
+            const bulkId = id;
+            const pageParams = {
+                ...(opts.cursor !== undefined ? { cursor: opts.cursor } : {}),
+                ...(opts.limit !== undefined ? { limit: opts.limit } : {}),
+                ...(opts.status !== undefined ? { status: opts.status } : {}),
+            };
+            const result = Object.keys(pageParams).length === 0
+                ? await client.bulk.screenshots.list(bulkId)
+                : await client.bulk.screenshots.list(bulkId, pageParams);
             printResult(result, g.json);
         }
         catch (err) {

package/dist/commands/fetch.js

@@ -2,7 +2,11 @@ import { Command } from 'commander';
 import { buildClient } from '../client.js';
 import { printResult, emitFetchResult, handleError } from '../output.js';
 import { parseBulkLines } from '../lib/url-lines.js';
-import { parseIntFlag, parseCacheTtl, parseJsonFlag } from '../lib/parse-flags.js';
+import { parseIntFlag, parseCacheTtl, parseJsonFlag, parseEnum } from '../lib/parse-flags.js';
+const BULK_RESULT_STATUSES = ['pending', 'processing', 'completed', 'failed', 'cancelled'];
+// Mirrors the `limit` query schema (`minimum: 1, maximum: 500`) on this job's recovery route in
+// docs/api/openapi.yaml, so the range the `--limit` help text advertises is enforced locally.
+const PAGE_LIMIT_BOUNDS = { min: 1, max: 500 };
 export function makeFetchCommand(getGlobal) {
     const cmd = new Command('fetch').description('Fetch URL content operations');
     const bulkCmd = new Command('bulk').description('Bulk fetch operations');
@@ -44,12 +48,23 @@ export function makeFetchCommand(getGlobal) {
     bulkCmd
         .command('get <id>')
         .description('Get a bulk fetch job')
-        .action(async (id) => {
+        .option('--cursor <cursor>', 'Continue from a cursor returned by the preceding page')
+        .option('--limit <n>', 'Maximum items to return (1-500)', (v) => parseIntFlag('--limit', v, PAGE_LIMIT_BOUNDS))
+        .option('--status <status>', `Filter items by status: ${BULK_RESULT_STATUSES.join(', ')}`, (v) => parseEnum('--status', BULK_RESULT_STATUSES, v))
+        .action(async (id, opts) => {
         const g = getGlobal();
         try {
             // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
             const client = buildClient(g);
-            const result = await client.fetch.bulk.get(id);
+            const bulkId = id;
+            const pageParams = {
+                ...(opts.cursor !== undefined ? { cursor: opts.cursor } : {}),
+                ...(opts.limit !== undefined ? { limit: opts.limit } : {}),
+                ...(opts.status !== undefined ? { status: opts.status } : {}),
+            };
+            const result = Object.keys(pageParams).length === 0
+                ? await client.fetch.bulk.get(bulkId)
+                : await client.fetch.bulk.get(bulkId, pageParams);
             printResult(result, g.json);
         }
         catch (err) {

package/dist/commands/scrape.js

@@ -11,6 +11,10 @@ const SCRAPE_EVENTS = ['queued', 'completed', 'failed'];
 const TOKEN_ENCODINGS = ['cl100k_base', 'o200k_base'];
 /** The `markdown_links` / `markdown_images` render-mode enum. */
 const MARKDOWN_RENDER_MODES = ['inline', 'references', 'none', 'text'];
+const BULK_RESULT_STATUSES = ['pending', 'processing', 'completed', 'failed', 'cancelled'];
+// Mirrors the `limit` query schema (`minimum: 1, maximum: 500`) on this job's recovery route in
+// docs/api/openapi.yaml, so the range the `--limit` help text advertises is enforced locally.
+const PAGE_LIMIT_BOUNDS = { min: 1, max: 500 };
 /**
  * Exit code when a queued (202 async) envelope reaches a non-JSON output mode.
  *
@@ -83,12 +87,23 @@ export function makeScrapeCommand(getGlobal) {
     bulkCmd
         .command('get <id>')
         .description('Get a bulk scrape job')
-        .action(async (id) => {
+        .option('--cursor <cursor>', 'Continue from a cursor returned by the preceding page')
+        .option('--limit <n>', 'Maximum items to return (1-500)', (v) => parseIntFlag('--limit', v, PAGE_LIMIT_BOUNDS))
+        .option('--status <status>', `Filter items by status: ${BULK_RESULT_STATUSES.join(', ')}`, (v) => parseEnum('--status', BULK_RESULT_STATUSES, v))
+        .action(async (id, opts) => {
         const g = getGlobal();
         try {
             // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
             const client = buildClient(g);
-            const result = await client.scrape.bulk.get(id);
+            const bulkId = id;
+            const pageParams = {
+                ...(opts.cursor !== undefined ? { cursor: opts.cursor } : {}),
+                ...(opts.limit !== undefined ? { limit: opts.limit } : {}),
+                ...(opts.status !== undefined ? { status: opts.status } : {}),
+            };
+            const result = Object.keys(pageParams).length === 0
+                ? await client.scrape.bulk.get(bulkId)
+                : await client.scrape.bulk.get(bulkId, pageParams);
             printResult(result, g.json);
         }
         catch (err) {
@@ -139,6 +154,7 @@ export function makeScrapeCommand(getGlobal) {
         .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('--solve-challenge', 'Attempt to clear a Cloudflare challenge; success is not guaranteed. Billed as a normal browser render.')
         .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) => {
@@ -206,6 +222,8 @@ export function makeScrapeCommand(getGlobal) {
             body['exclude_tags'] = parseCsv(opts.excludeTags);
         if (opts.mobile === true)
             body['mobile'] = true;
+        if (opts.solveChallenge === true)
+            body['solve_challenge'] = true;
         try {
             // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
             const client = buildClient(g);

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

@@ -8,8 +8,16 @@
  * 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.
+ *
+ * `bounds` extends that guarantee to flags whose spec schema declares a range (#3717): a
+ * well-formed integer outside `[min, max]` is just as certain to 422 as `abc` is, so it is
+ * rejected here rather than spending a round trip to be told so. Pass it wherever the flag's help
+ * text states a range; omit it where the spec declares none.
  */
-export declare function parseIntFlag(flag: string, value: string): number;
+export declare function parseIntFlag(flag: string, value: string, bounds?: {
+    min: number;
+    max: number;
+}): 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. */

package/dist/lib/parse-flags.js

@@ -9,12 +9,21 @@ import { InvalidArgumentError } from 'commander';
  * 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.
+ *
+ * `bounds` extends that guarantee to flags whose spec schema declares a range (#3717): a
+ * well-formed integer outside `[min, max]` is just as certain to 422 as `abc` is, so it is
+ * rejected here rather than spending a round trip to be told so. Pass it wherever the flag's help
+ * text states a range; omit it where the spec declares none.
  */
-export function parseIntFlag(flag, value) {
+export function parseIntFlag(flag, value, bounds) {
     if (!/^\d+$/.test(value)) {
         throw new InvalidArgumentError(`${flag} must be a whole number.`);
     }
-    return Number(value);
+    const parsed = Number(value);
+    if (bounds && (parsed < bounds.min || parsed > bounds.max)) {
+        throw new InvalidArgumentError(`${flag} must be between ${bounds.min} and ${bounds.max}.`);
+    }
+    return parsed;
 }
 /** Reject an off-spec enum value at parse time with the allowed set in the message. */
 export function parseEnum(flag, allowed, value) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hunt-labs/bytekit-cli",
-  "version": "0.9.3",
+  "version": "0.10.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.9.2"
+    "@hunt-labs/bytekit-sdk": "^0.11.0"
   },
   "scripts": {
     "build": "rm -rf dist tsconfig.tsbuildinfo && tsc",