From 167848072a6fcd022e0d639b38d7f8c13b608f0b Mon Sep 17 00:00:00 2001 From: kostas-jakeliunas-sb Date: Tue, 30 Jun 2026 15:26:27 +0300 Subject: [PATCH] [SCR-383] Add Auto-Mode (mode=auto) support to HTML API Adds discoverability + docs for the server-side Auto-Mode feature (mode=auto): server picks the cheapest scraping config that succeeds, charges only the winning config. The SDK is pass-through, so the params already work on the wire; this surfaces them for autocomplete and docs. - src/index.ts: add `mode?: 'auto'` and `max_cost?: number` to the HtmlApiParams type (index signature already permitted them; this is pure additive for autocomplete/discoverability). - README.md: new "Auto-Mode" subsection in the HTML API section with a GET example and a note on reading the `spb-auto-cost` response header (axios lowercases header keys), plus GET-only / max_cost / param incompatibility caveats. - CHANGELOG.md: 1.8.3 entry. - package.json: 1.8.2 -> 1.8.3 (prebuild synced src/version.ts). - dist/: rebuilt committed output (npm run build) for the new type + version. Tests: 67 passing (mocha, mocked). Co-Authored-By: Claude Opus 4.8 (1M context) --- CHANGELOG.md | 7 +++++++ README.md | 38 ++++++++++++++++++++++++++++++++++++++ dist/index.d.ts | 2 ++ dist/version.d.ts | 2 +- dist/version.js | 2 +- package.json | 2 +- src/index.ts | 2 ++ src/version.ts | 2 +- 8 files changed, 53 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8f19798..365ce7c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## [1.8.3](https://github.com/ScrapingBee/scrapingbee-node/compare/v1.8.2...v1.8.3) (2026-06-30) + +### Features + +- Added Auto-Mode support for the HTML API: pass `mode: 'auto'` (GET only) to let ScrapingBee pick the cheapest scraping config that succeeds, charged only for the winning config. Optional `max_cost` (integer ≥ 1) caps the credits a request may cost. The credits charged are returned in the `Spb-auto-cost` response header. +- Added `mode` and `max_cost` to the `HtmlApiParams` type for autocomplete. + ## [1.8.2](https://github.com/ScrapingBee/scrapingbee-node/compare/v1.8.0...v1.8.2) (2026-01-22) ### Bugfix diff --git a/README.md b/README.md index 7822ce2..33d63fd 100644 --- a/README.md +++ b/README.md @@ -62,6 +62,44 @@ async function get(url) { get('https://example.com'); ``` +### Auto-Mode + +With `mode: 'auto'`, ScrapingBee automatically picks the cheapest scraping config that +successfully returns the page — trying cheaper configs first and escalating only as needed. +You are charged **only for the config that succeeded** (0 credits if none did). + +```javascript +const { ScrapingBeeClient } = require('scrapingbee'); + +async function autoScrape(url) { + const client = new ScrapingBeeClient('YOUR-API-KEY'); + const response = await client.htmlApi({ + url: url, + // Auto-Mode: ScrapingBee picks the cheapest config that works; + // charged only for the winning one. + params: { + mode: 'auto', + max_cost: 25, // optional credit cap; omit for uncapped + }, + }); + + // Credits actually charged for the winning config (0 if it failed). + // axios lowercases header keys, so read the lowercase key. + console.log(response.headers['spb-auto-cost']); + + const decoder = new TextDecoder(); + console.log(decoder.decode(response.data)); +} + +autoScrape('https://example.com'); +``` + +Notes: + +- Auto-Mode is **GET only**. +- `max_cost` is optional (an integer ≥ 1). It caps the credits a request may cost; omit it for uncapped escalation. +- Don't combine `mode: 'auto'` with `render_js`, `premium_proxy`, or `stealth_proxy` — the API rejects those combinations. + ### POST Request ```javascript diff --git a/dist/index.d.ts b/dist/index.d.ts index e2db34b..9b78b2c 100644 --- a/dist/index.d.ts +++ b/dist/index.d.ts @@ -14,6 +14,8 @@ export declare type HtmlApiParams = { forward_headers_pure?: boolean; js_scenario?: object | string; json_response?: boolean; + max_cost?: number; + mode?: 'auto'; own_proxy?: string; premium_proxy?: boolean; render_js?: boolean; diff --git a/dist/version.d.ts b/dist/version.d.ts index a87c636..69c1342 100644 --- a/dist/version.d.ts +++ b/dist/version.d.ts @@ -1 +1 @@ -export declare const LIB_VERSION = "1.8.2"; +export declare const LIB_VERSION = "1.8.3"; diff --git a/dist/version.js b/dist/version.js index 210c879..502968c 100644 --- a/dist/version.js +++ b/dist/version.js @@ -1,4 +1,4 @@ "use strict"; Object.defineProperty(exports, "__esModule", { value: true }); exports.LIB_VERSION = void 0; -exports.LIB_VERSION = "1.8.2"; +exports.LIB_VERSION = "1.8.3"; diff --git a/package.json b/package.json index 7c3cab1..096e354 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "scrapingbee", - "version": "1.8.2", + "version": "1.8.3", "description": "ScrapingBee Node SDK", "main": "dist/index.js", "types": "dist/index.d.ts", diff --git a/src/index.ts b/src/index.ts index eb650f7..b26be22 100644 --- a/src/index.ts +++ b/src/index.ts @@ -34,6 +34,8 @@ export type HtmlApiParams = { forward_headers_pure?: boolean; js_scenario?: object | string; json_response?: boolean; + max_cost?: number; + mode?: 'auto'; own_proxy?: string; premium_proxy?: boolean; render_js?: boolean; diff --git a/src/version.ts b/src/version.ts index 6e60eb6..f99a7cf 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const LIB_VERSION = "1.8.2"; +export const LIB_VERSION = "1.8.3";