[SCR-383] Auto-Mode (mode=auto) support

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

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

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;

dist/version.d.ts

@@ -1 +1 @@
-export declare const LIB_VERSION = "1.8.2";
+export declare const LIB_VERSION = "1.8.3";

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";

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",

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;

src/version.ts

@@ -1 +1 @@
-export const LIB_VERSION = "1.8.2";
+export const LIB_VERSION = "1.8.3";