@hunt-labs/bytekit-cli 0.9.3 → 0.9.4

package/CHANGELOG.md

@@ -10,6 +10,18 @@ today, see [README.md](./README.md), which remains the authoritative usage guide
 
 ## [Unreleased]
 
+## [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

@@ -276,8 +276,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) {

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.9.4",
   "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.10.0"
   },
   "scripts": {
     "build": "rm -rf dist tsconfig.tsbuildinfo && tsc",