@hunt-labs/bytekit-sdk 0.11.13 → 0.11.15

package/CHANGELOG.md

@@ -10,6 +10,38 @@ today, see [README.md](./README.md), which remains the authoritative usage guide
 
 ## [Unreleased]
 
+## [0.11.15] - 2026-11-04
+
+### Changed
+
+- **New internal `GET /v1/bulk/concurrency` operation (#3718).** The generated `getBulkConcurrency`
+  types record a read-only operation that returns `{ active, limit }`: the account's in-use bulk
+  concurrency slots (`null` when the slot count cannot be read) and the plan cap, for the dashboard's
+  bulk playground. It is `x-sdk-scope: internal` and adds no SDK method, so no published method
+  signature moves; `GET /v1/bulk` is unchanged.
+- **`device_scale_factor` accepts only `1` (#5630).** The generated `ScreenshotRequest` and the bulk
+  `defaults` types narrow `device_scale_factor` from `1 | 2 | null` to `1 | null`. The API now answers
+  `2` (or any other value) with a 422 `validation_error`; omitting the field still means `null`.
+  Regenerated `src/generated/api.d.ts`.
+
+## [0.11.14] - 2026-10-27
+
+### Added
+
+- **`'outline'` is now a `scrape` format (#5473).** `formats: ['outline']` on `scrape.create` (and the
+  bulk entry points) returns `formats.outline`, an indented text accessibility tree of the
+  browser-rendered page with no element IDs. Experimental; it forces the browser path and adds no
+  credits. Regenerated `src/generated/api.d.ts`.
+
+### Changed
+
+- **`solve_challenge` is documented as a held browser render that can return the 202 receipt
+  (#5541).** Since #5532 a synchronous `scrape.create` with `solve_challenge: true` is routed to the
+  browser render and held up to the hold window (28 s by default); a solve that outlasts it resolves
+  to the `queued` receipt. The `ScrapeCreateResponse` and `solve_challenge` JSDoc and the regenerated
+  `src/generated/api.d.ts` say so, and the routing triggers now list `solve_challenge` and `outline`
+  next to `delay_ms`. Description text only; no SDK method signature moves.
+
 ## [0.11.13] - 2026-10-21
 
 ### Changed

package/dist/generated/api.d.ts

@@ -201,7 +201,7 @@ export interface paths {
          *     **The response shape is decided by your request, not by how we route it.** In precedence order:
          *
          *     1. `async: true` in the body, or `?async=true` in the query string (either one is enough; `false` in one never cancels `true` in the other) → **202** with a `ScrapeQueuedEnvelope` receipt, returned immediately. Poll `GET /v1/scrape/{id}` for the result.
-         *     2. Otherwise, a request that needs a full page render — today that is `delay_ms > 0` — is **held open** until the render reaches a terminal state, then returns **200** with the content envelope (`success` or `failed`). If the render is still running when the hold window expires (28 seconds by default), the request returns the **202** receipt instead and the job continues in the background.
+         *     2. Otherwise, a request that needs a full page render — today that is any of `delay_ms > 0`, `solve_challenge: true`, or `outline` in `formats` — is **held open** until the render reaches a terminal state, then returns **200** with the content envelope (`success` or `failed`). If the render is still running when the hold window expires (28 seconds by default), the request returns the **202** receipt instead and the job continues in the background. A `solve_challenge` render can outlast the hold window, so expect the 202 receipt from such a request.
          *     3. Otherwise the request is served by the fast HTTP path and returns **200** with the content envelope, typically in under a second.
          *
          *     **A failed fetch is a result, not a transport error.** An unreachable host, a refused connection, or a target whose bot protection defeats every proxy tier all come back on the same **200** as a `failed` envelope — never a 5xx. Narrow on the envelope's `status` before reading the body. A failure the fast path decides inline is recorded as a failed job, so its envelope normally carries that job's `id` and `GET /v1/scrape/{id}` returns the same envelope; if recording the failed job itself fails, the envelope still arrives on the same 200 with `id` set to `null` and there is nothing to poll. A failure a held render reaches carries that render's real `id`. Either way the request transfers no billable bytes and is charged nothing.
@@ -465,6 +465,33 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/bulk/concurrency": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get bulk concurrency usage
+         * @description Returns how many of the account's bulk concurrency slots are in use and
+         *     the plan cap they count against, so a dashboard can tell a bulk job that
+         *     is waiting on the cap from one that is stalled. `active` is a live
+         *     approximation of dispatched bulk children: a slot whose release never
+         *     arrived drops out of the count after 5 minutes. It is for display only
+         *     and never decides a job's state or progress, which come from the job's
+         *     own counters, nor enforcement or billing. Authenticates with an API key
+         *     or a dashboard session, like the other `/v1/bulk` operations.
+         */
+        get: operations["getBulkConcurrency"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/bulk/{id}": {
         parameters: {
             query?: never;
@@ -1859,7 +1886,7 @@ export interface components {
              */
             mobile: boolean;
             /**
-             * @description Attempts to clear a Cloudflare challenge; success is not guaranteed. Billed as a normal browser render.
+             * @description Attempts to clear a Cloudflare challenge; success is not guaranteed. Billed as a normal browser render. On a synchronous `POST /v1/scrape` this routes the request to the held browser render; a solve can outlast the hold window (28 seconds by default), and the request then returns the 202 receipt while the job continues in the background. With `async: true` the 202 receipt is returned immediately.
              * @default false
              */
             solve_challenge: boolean;
@@ -1905,7 +1932,7 @@ export interface components {
          * @description A string entry of `ScrapeRequest.formats`.
          * @enum {string}
          */
-        ScrapeRequestFormatsItem: "raw" | "markdown" | "links" | "images";
+        ScrapeRequestFormatsItem: "raw" | "markdown" | "links" | "images" | "outline";
         /**
          * @description The `json` entry of `ScrapeRequest.formats`: structured extraction over the scraped
          *     page, using the same extractor as `POST /v1/schema`.
@@ -2017,6 +2044,14 @@ export interface components {
                 /** @description The extraction model that ran. */
                 model: string;
             };
+            /**
+             * @description Experimental. An indented text accessibility tree of the browser-rendered page, one
+             *     `- role: name = value` line per node, with no element IDs. Requesting `outline`
+             *     forces the slow (browser) path and adds no credits. Omitted, with an
+             *     `artifact_unavailable` warning, when the page cannot be rendered or captured. Not
+             *     accepted on `/v1/monitors`.
+             */
+            outline?: string;
         };
         ScrapeMetadata: {
             title: string | null;
@@ -2204,7 +2239,7 @@ export interface components {
                 code: "validation_error" | "invalid_url" | "request_too_large" | "payload_too_large" | "unsupported_content_type" | "rate_limited" | "upstream_error" | "blocked" | "target_rate_limited" | "timeout" | "internal_error";
                 message: string;
                 http_status?: number;
-                /** @description Whole seconds the target site asked us to wait before the next request. Present only with `code: target_rate_limited`, only on the inline `POST /v1/scrape` failure the fast path decides, and only when the target sent a usable `Retry-After` (delta-seconds, or an HTTP-date still in the future, converted to seconds; values above 2147483647 are reported as 2147483647). Informational: ByteKit never enforces it on your next request. A held render (`delay_ms > 0`), `GET /v1/scrape/{id}` and webhooks omit it, because the value is relative to the moment the target answered. */
+                /** @description Whole seconds the target site asked us to wait before the next request. Present only with `code: target_rate_limited`, only on the inline `POST /v1/scrape` failure the fast path decides, and only when the target sent a usable `Retry-After` (delta-seconds, or an HTTP-date still in the future, converted to seconds; values above 2147483647 are reported as 2147483647). Informational: ByteKit never enforces it on your next request. A held render (`delay_ms > 0`, `solve_challenge: true`, or `outline` in `formats`), `GET /v1/scrape/{id}` and webhooks omit it, because the value is relative to the moment the target answered. */
                 retry_after_seconds?: number;
                 /** Format: date-time */
                 failed_at: string;
@@ -2310,10 +2345,11 @@ export interface components {
             /** @default false */
             dark_mode: boolean;
             /**
+             * @description Pixel density. Only `1` is supported; any other value is a 422 `validation_error`.
              * @default null
              * @enum {integer|null}
              */
-            device_scale_factor: 1 | 2 | null;
+            device_scale_factor: 1 | null;
             /** @default false */
             include_html: boolean;
             /** @default US */
@@ -3705,7 +3741,7 @@ export interface operations {
                     "X-Screenshot-Status"?: string;
                     /** @description The originally requested URL. */
                     "X-Screenshot-URL"?: string;
-                    /** @description Legacy credit weight for this capture (1, 2 or 4, doubling for `full_page` and again for retina/mobile). It is recorded for reporting only — screenshots are billed on bandwidth, not credits: the charge is the Phase 1 wire bytes x 1.5, and zero when Phase 1 is skipped or fails. */
+                    /** @description Legacy credit weight for this capture (1, 2 or 4, doubling for `full_page` and again for mobile). It is recorded for reporting only — screenshots are billed on bandwidth, not credits: the charge is the Phase 1 wire bytes x 1.5, and zero when Phase 1 is skipped or fails. */
                     "X-Screenshot-Credits-Charged"?: number;
                     /** @description Handler elapsed time in milliseconds. */
                     "X-Screenshot-Duration-Ms"?: number;
@@ -3746,7 +3782,7 @@ export interface operations {
                     "X-Screenshot-Status"?: string;
                     /** @description The originally requested URL. */
                     "X-Screenshot-URL"?: string;
-                    /** @description Legacy credit weight for this capture (1, 2 or 4, doubling for `full_page` and again for retina/mobile). It is recorded for reporting only — screenshots are billed on bandwidth, not credits: the charge is the Phase 1 wire bytes x 1.5, and zero when Phase 1 is skipped or fails. */
+                    /** @description Legacy credit weight for this capture (1, 2 or 4, doubling for `full_page` and again for mobile). It is recorded for reporting only — screenshots are billed on bandwidth, not credits: the charge is the Phase 1 wire bytes x 1.5, and zero when Phase 1 is skipped or fails. */
                     "X-Screenshot-Credits-Charged"?: number;
                     /** @description Handler elapsed time in milliseconds. */
                     "X-Screenshot-Duration-Ms"?: number;
@@ -4049,6 +4085,22 @@ export interface operations {
             };
             401: components["responses"]["Unauthorized"];
             402: components["responses"]["PaymentRequired"];
+            /**
+             * @description `unsupported_content_type`, in two cases:
+             *     - The `url` path ends in `.pdf`: the path, lowercased, ends in `.pdf`; the query string and
+             *       fragment are not looked at. It is refused before anything is drawn. A PDF served from
+             *       another path, or reached through a redirect, is not caught by this check.
+             *     - The page was fetched (or served from cache) and its content type cannot produce the
+             *       requested formats. The charge is refunded.
+             */
+            415: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
             /**
              * @description Validation error. A `json` format entry whose `schema` the extractor cannot take is
              *     refused with `schema_incompatible`, before anything is drawn.
@@ -4208,7 +4260,7 @@ export interface operations {
                     items?: {
                         /** Format: uri */
                         url: string;
-                        formats?: (("raw" | "markdown" | "links" | "images") | components["schemas"]["ScrapeRequestJsonFormat"])[];
+                        formats?: (("raw" | "markdown" | "links" | "images" | "outline") | components["schemas"]["ScrapeRequestJsonFormat"])[];
                         country?: string;
                         delay_ms?: number;
                         timeout_ms?: number;
@@ -4241,7 +4293,7 @@ export interface operations {
                          *       "raw"
                          *     ]
                          */
-                        formats?: (("raw" | "markdown" | "links" | "images") | components["schemas"]["ScrapeRequestJsonFormat"])[];
+                        formats?: (("raw" | "markdown" | "links" | "images" | "outline") | components["schemas"]["ScrapeRequestJsonFormat"])[];
                         /** @default US */
                         country?: string;
                         /** @default 0 */
@@ -4317,6 +4369,20 @@ export interface operations {
                         estimated_credits: number | null;
                         /** @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported) */
                         webhook_url: string;
+                        /**
+                         * @description Items refused at intake and not queued, by their index in `items` or `urls`.
+                         *     An item is refused with `unsupported_content_type` when its URL path, lowercased,
+                         *     ends in `.pdf` (the query string and fragment are not looked at). Refused items
+                         *     are not counted in `total` and nothing is reserved for them. Empty when every
+                         *     item was accepted.
+                         */
+                        rejected: {
+                            index: number;
+                            url: string;
+                            /** @enum {string} */
+                            code: "unsupported_content_type";
+                            message: string;
+                        }[];
                     };
                 };
             };
@@ -4372,9 +4438,25 @@ export interface operations {
                 };
             };
             /**
-             * @description Validation error. `bulk_too_large` is returned when the item count
-             *     exceeds the account plan's `max_bulk_size` cap (also surfaced as
-             *     `max_bulk_size` on `GET /v1/account`).
+             * @description `unsupported_content_type`: every item in the batch was refused because its URL path ends in
+             *     `.pdf` (the path, lowercased; the query string and fragment are not looked at). Nothing is
+             *     queued or billed. `details.rejected` lists each item as `{ index, url, code, message }`.
+             *     When only some items are refused the batch is accepted with `202` and those items are
+             *     listed in `rejected` instead.
+             */
+            415: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /**
+             * @description Validation error. `bulk_too_large` is returned when the count of
+             *     accepted items exceeds the account plan's `max_bulk_size` cap (also
+             *     surfaced as `max_bulk_size` on `GET /v1/account`). Items refused
+             *     for a `.pdf` path are listed in `rejected` and do not count.
              */
             422: {
                 headers: {
@@ -5253,8 +5335,7 @@ export interface operations {
                  *         "country": "US",
                  *         "formats": [
                  *           "raw"
-                 *         ],
-                 *         "device_scale_factor": 2
+                 *         ]
                  *       },
                  *       "metadata": {
                  *         "campaign": "q3"
@@ -5289,7 +5370,7 @@ export interface operations {
                         language?: string | null;
                         dark_mode?: boolean;
                         /** @description Scrape output formats (scrape entries). */
-                        formats?: (("raw" | "markdown" | "links" | "images") | components["schemas"]["ScrapeRequestJsonFormat"])[];
+                        formats?: (("raw" | "markdown" | "links" | "images" | "outline") | components["schemas"]["ScrapeRequestJsonFormat"])[];
                         /** @enum {string} */
                         wait_until?: "load" | "domcontentloaded" | "networkidle";
                         wait_for_selector?: string | null;
@@ -5342,7 +5423,7 @@ export interface operations {
                         language?: string | null;
                         /** @default false */
                         dark_mode?: boolean;
-                        formats?: (("raw" | "markdown" | "links" | "images") | components["schemas"]["ScrapeRequestJsonFormat"])[];
+                        formats?: (("raw" | "markdown" | "links" | "images" | "outline") | components["schemas"]["ScrapeRequestJsonFormat"])[];
                         /**
                          * @default load
                          * @enum {string}
@@ -5358,10 +5439,11 @@ export interface operations {
                             height: number;
                         } | null;
                         /**
+                         * @description Pixel density. Only `1` is supported; any other value is a 422 `validation_error`.
                          * @default null
                          * @enum {integer|null}
                          */
-                        device_scale_factor?: 1 | 2 | null;
+                        device_scale_factor?: 1 | null;
                     };
                     /**
                      * Format: uri
@@ -5487,6 +5569,32 @@ export interface operations {
             };
         };
     };
+    getBulkConcurrency: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful response. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @description Bulk slots in use right now. `0` is a real zero (nothing running). `null` means the slot count could not be read right now; it is not zero. */
+                        active: number | null;
+                        /** @description The plan's maximum concurrency, the cap `active` counts against. */
+                        limit: number;
+                    };
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+        };
+    };
     getBulk: {
         parameters: {
             query?: never;
@@ -5833,6 +5941,21 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            /**
+             * @description `unsupported_content_type`: a `scrape` monitor whose `url` path ends in `.pdf` is refused
+             *     before it is stored. The check is on the URL only: the path, lowercased, ends in `.pdf`;
+             *     the query string and fragment are not looked at. A PDF served from another path, or reached
+             *     through a redirect, is not caught here — its polls fail as `unsupported_content_type` and
+             *     count toward auto-suspension. A `screenshot` monitor is not affected.
+             */
+            415: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
             /** @description Validation error. */
             422: {
                 headers: {
@@ -5969,6 +6092,21 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            /**
+             * @description `unsupported_content_type`: a `scrape` monitor whose `url` path ends in `.pdf` is refused
+             *     before it is stored. The check is on the URL only: the path, lowercased, ends in `.pdf`;
+             *     the query string and fragment are not looked at. A PDF served from another path, or reached
+             *     through a redirect, is not caught here — its polls fail as `unsupported_content_type` and
+             *     count toward auto-suspension. A `screenshot` monitor is not affected.
+             */
+            415: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
             /** @description Validation error. */
             422: {
                 headers: {

package/dist/resources/scrape.d.ts

@@ -13,8 +13,8 @@ import type { ScrapeId, BulkId } from '../types.js';
  * The shape follows from the request, in this order:
  *
  * 1. `async: true` → 202 receipt, immediately. Poll `scrape.get(id)`.
- * 2. Otherwise a request that needs a full page render — today that is
- *    `delay_ms > 0` — is held open until the render reaches a terminal state
+ * 2. Otherwise a request that needs a full page render — today that is any of
+ *    `delay_ms > 0`, `solve_challenge: true`, or `outline` in `formats` — is held open until the render reaches a terminal state
  *    and returns 200 with that state: the content envelope on success, or the
  *    `failed` error envelope when the render itself failed. If the render is
  *    still running when the server's hold window expires (28 s by default), it
@@ -54,7 +54,7 @@ export type ScrapeJsonFormat = components['schemas']['ScrapeRequestJsonFormat'];
 export interface ScrapeOpts {
     url: string;
     /** String formats, plus at most one `{ type: 'json', schema }` entry for structured extraction (the entry's result is `formats.json`). */
-    formats?: Array<'raw' | 'markdown' | 'links' | 'images' | ScrapeJsonFormat>;
+    formats?: Array<'raw' | 'markdown' | 'links' | 'images' | 'outline' | ScrapeJsonFormat>;
     country?: string;
     delay_ms?: number;
     /** SERVER-side scrape budget in ms — how long the server may spend on the scrape itself. For the CLIENT-side abort budget (when this SDK gives up on the wire), see `RequestOptions.requestTimeoutMs`. */
@@ -88,7 +88,7 @@ export interface ScrapeOpts {
     token_budget?: number;
     /** Tokenizer encoding hint for `token_budget`. `cl100k_base` (default) matches GPT-4/4o; `o200k_base` matches GPT-4o-mini / o-series. */
     token_encoding?: TokenEncoding;
-    /** Attempts to clear a Cloudflare challenge; success is not guaranteed. Billed as a normal browser render. */
+    /** Attempts to clear a Cloudflare challenge; success is not guaranteed. Billed as a normal browser render. On a synchronous scrape this routes the request to the held browser render; a solve can outlast the hold window (28 seconds by default), and the request then returns the 202 receipt while the job continues in the background. With `async: true` the 202 receipt is returned immediately. */
     solve_challenge?: boolean;
     /** When true, emulate a mobile device (mobile UA + viewport). Default false (desktop). Part of the cache key, so mobile and desktop responses cache independently. */
     mobile?: boolean;

package/dist/version.d.ts

@@ -5,4 +5,4 @@
  * outbound request carries — see the emit site in `client.ts`. The header name is spelled
  * only there, so issue #2905's pre-merge gate 1 counts exactly one occurrence in `src/`.
  */
-export declare const SDK_VERSION = "0.11.13";
+export declare const SDK_VERSION = "0.11.15";

package/dist/version.js

@@ -9,4 +9,4 @@
  * outbound request carries — see the emit site in `client.ts`. The header name is spelled
  * only there, so issue #2905's pre-merge gate 1 counts exactly one occurrence in `src/`.
  */
-export const SDK_VERSION = '0.11.13';
+export const SDK_VERSION = '0.11.15';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hunt-labs/bytekit-sdk",
-  "version": "0.11.13",
+  "version": "0.11.15",
   "description": "Official TypeScript SDK for the ByteKit API",
   "license": "MIT",
   "type": "module",