zenrows 2.0.1 → 2.0.3

package/.github/assets/logo/dark.svg

@@ -0,0 +1,3 @@
+<svg width="7495" height="1080" viewBox="0 0 7495 1080" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M7115.77 18C7228.28 18.0001 7314.32 42.4821 7373.88 91.4463C7434.77 140.411 7473.82 194.007 7491.03 252.235L7316.3 329.652C7305.72 293.921 7283.21 263.484 7248.8 238.34C7214.38 211.873 7168.05 198.64 7109.81 198.64C7055.54 198.64 7012.52 209.227 6980.75 230.4C6948.99 250.251 6933.1 276.718 6933.1 309.802C6933.1 337.592 6943.69 360.09 6964.87 377.294C6987.37 394.498 7018.48 408.393 7058.19 418.979L7205.12 458.681C7303.07 485.148 7375.87 524.849 7423.52 577.783C7471.17 629.394 7495 690.931 7495 762.393C7495 823.267 7478.45 878.187 7445.36 927.151C7413.59 974.792 7367.27 1012.51 7306.38 1040.3C7245.49 1066.77 7174.01 1080 7091.94 1080C6980.75 1080 6890.08 1056.18 6819.93 1008.54C6749.77 959.574 6700.8 899.361 6673 827.899L6841.77 740.557C6860.3 785.551 6890.74 822.606 6933.1 851.72C6975.46 880.834 7029.73 895.391 7095.91 895.391C7154.15 895.391 7199.82 884.142 7232.91 861.645C7266 839.147 7282.55 808.71 7282.55 770.333C7282.55 713.428 7238.21 672.404 7149.52 647.26L7000.61 605.574C6918.54 583.077 6853.02 548.007 6804.04 500.366C6755.07 451.402 6730.58 389.865 6730.58 315.757C6730.58 225.768 6765.66 153.645 6835.81 99.3867C6905.97 45.1288 6999.29 18 7115.77 18ZM1324.42 0C1425.05 0 1511.77 23.8208 1584.59 71.4619C1658.74 119.103 1715.01 181.963 1753.41 260.041C1791.8 338.119 1811 422.154 1811 512.143V599.484H1026.52C1038.43 686.826 1070.87 754.318 1123.83 801.959C1176.79 849.6 1244.98 873.421 1328.4 873.421C1401.22 873.421 1460.8 858.202 1507.14 827.765C1554.8 797.327 1590.55 756.965 1614.38 706.677L1777.24 790.049C1741.49 866.804 1684.56 931.649 1606.44 984.583C1528.32 1036.19 1433.65 1062 1322.44 1062C1225.78 1062 1138.4 1038.84 1060.28 992.523C983.488 944.882 923.245 880.699 879.553 799.974C837.184 719.249 816 629.26 816 530.008C816 430.755 837.184 340.766 879.553 260.041C921.921 179.316 981.502 115.794 1058.29 69.4766C1136.41 23.1588 1225.12 3.79646e-05 1324.42 0ZM2364.04 18C2435.47 18.0001 2499.62 34.5404 2556.5 67.6201C2614.7 99.3768 2660.33 145.027 2693.4 204.57C2726.47 262.791 2743 328.951 2743 403.05V1062H2534.67V458.624C2534.67 385.848 2514.17 327.627 2473.16 283.962C2432.16 240.297 2377.27 218.464 2308.48 218.464C2239.7 218.464 2184.15 241.62 2141.82 287.932C2099.49 332.92 2078.33 389.818 2078.33 458.624V1062H1870V35.8633H2078.33V158.92C2104.78 116.578 2141.82 82.837 2189.44 57.6963C2238.38 31.2324 2296.58 18 2364.04 18ZM3830 36.0127C3830.33 36.0108 3830.67 36.0072 3831 36.0059V36H4827C5108.16 36 5334 266.385 5334 548C5334 829.615 5108.16 1060 4827 1060H3831V1059.99C3550.45 1058.91 3325 829.18 3325 548C3325 426.676 3366.98 314.932 3437.24 227H3321.48L3161.96 226.515C3076.44 226.515 3033.68 279.435 3033.68 385.276V1062H2861V379.323C2861 281.42 2884.02 200.054 2930.07 135.227C2977.22 69.0759 3050.67 36.0001 3150.45 36H3830V36.0127ZM5652.65 758.367L5876.85 36H6095.1L6317.32 758.367L6511.76 36H6732L6434.38 1062H6214.15L5985.98 335.663L5753.84 1062H5533.6L5234 36H5460.19L5652.65 758.367ZM800.103 200.576L262.068 861.424H814V1044H0V861.424L540.02 200.576H11.9121V18H800.103V200.576ZM3833 236C3663.81 236 3525 374.765 3525 548C3525 721.235 3663.81 860 3833 860H4827C4995.4 860 5134 721.468 5134 548C5134 374.532 4995.4 236 4827 236H3833ZM1328.4 180.64C1250.28 180.64 1184.74 203.136 1131.78 248.131C1080.14 291.802 1047.04 352.676 1032.48 430.755H1596.51C1595.18 389.731 1583.93 350.03 1562.75 311.652C1541.56 273.275 1510.45 242.176 1469.4 218.355C1429.68 193.212 1382.68 180.64 1328.4 180.64Z" fill="#FFFFFF"/>
+</svg>

package/.github/assets/logo/light.svg

@@ -0,0 +1,3 @@
+<svg width="7495" height="1080" viewBox="0 0 7495 1080" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M7115.77 18C7228.28 18.0001 7314.32 42.4821 7373.88 91.4463C7434.77 140.411 7473.82 194.007 7491.03 252.235L7316.3 329.652C7305.72 293.921 7283.21 263.484 7248.8 238.34C7214.38 211.873 7168.05 198.64 7109.81 198.64C7055.54 198.64 7012.52 209.227 6980.75 230.4C6948.99 250.251 6933.1 276.718 6933.1 309.802C6933.1 337.592 6943.69 360.09 6964.87 377.294C6987.37 394.498 7018.48 408.393 7058.19 418.979L7205.12 458.681C7303.07 485.148 7375.87 524.849 7423.52 577.783C7471.17 629.394 7495 690.931 7495 762.393C7495 823.267 7478.45 878.187 7445.36 927.151C7413.59 974.792 7367.27 1012.51 7306.38 1040.3C7245.49 1066.77 7174.01 1080 7091.94 1080C6980.75 1080 6890.08 1056.18 6819.93 1008.54C6749.77 959.574 6700.8 899.361 6673 827.899L6841.77 740.557C6860.3 785.551 6890.74 822.606 6933.1 851.72C6975.46 880.834 7029.73 895.391 7095.91 895.391C7154.15 895.391 7199.82 884.142 7232.91 861.645C7266 839.147 7282.55 808.71 7282.55 770.333C7282.55 713.428 7238.21 672.404 7149.52 647.26L7000.61 605.574C6918.54 583.077 6853.02 548.007 6804.04 500.366C6755.07 451.402 6730.58 389.865 6730.58 315.757C6730.58 225.768 6765.66 153.645 6835.81 99.3867C6905.97 45.1288 6999.29 18 7115.77 18ZM1324.42 0C1425.05 0 1511.77 23.8208 1584.59 71.4619C1658.74 119.103 1715.01 181.963 1753.41 260.041C1791.8 338.119 1811 422.154 1811 512.143V599.484H1026.52C1038.43 686.826 1070.87 754.318 1123.83 801.959C1176.79 849.6 1244.98 873.421 1328.4 873.421C1401.22 873.421 1460.8 858.202 1507.14 827.765C1554.8 797.327 1590.55 756.965 1614.38 706.677L1777.24 790.049C1741.49 866.804 1684.56 931.649 1606.44 984.583C1528.32 1036.19 1433.65 1062 1322.44 1062C1225.78 1062 1138.4 1038.84 1060.28 992.523C983.488 944.882 923.245 880.699 879.553 799.974C837.184 719.249 816 629.26 816 530.008C816 430.755 837.184 340.766 879.553 260.041C921.921 179.316 981.502 115.794 1058.29 69.4766C1136.41 23.1588 1225.12 3.79646e-05 1324.42 0ZM2364.04 18C2435.47 18.0001 2499.62 34.5404 2556.5 67.6201C2614.7 99.3768 2660.33 145.027 2693.4 204.57C2726.47 262.791 2743 328.951 2743 403.05V1062H2534.67V458.624C2534.67 385.848 2514.17 327.627 2473.16 283.962C2432.16 240.297 2377.27 218.464 2308.48 218.464C2239.7 218.464 2184.15 241.62 2141.82 287.932C2099.49 332.92 2078.33 389.818 2078.33 458.624V1062H1870V35.8633H2078.33V158.92C2104.78 116.578 2141.82 82.837 2189.44 57.6963C2238.38 31.2324 2296.58 18 2364.04 18ZM3830 36.0127C3830.33 36.0108 3830.67 36.0072 3831 36.0059V36H4827C5108.16 36 5334 266.385 5334 548C5334 829.615 5108.16 1060 4827 1060H3831V1059.99C3550.45 1058.91 3325 829.18 3325 548C3325 426.676 3366.98 314.932 3437.24 227H3321.48L3161.96 226.515C3076.44 226.515 3033.68 279.435 3033.68 385.276V1062H2861V379.323C2861 281.42 2884.02 200.054 2930.07 135.227C2977.22 69.0759 3050.67 36.0001 3150.45 36H3830V36.0127ZM5652.65 758.367L5876.85 36H6095.1L6317.32 758.367L6511.76 36H6732L6434.38 1062H6214.15L5985.98 335.663L5753.84 1062H5533.6L5234 36H5460.19L5652.65 758.367ZM800.103 200.576L262.068 861.424H814V1044H0V861.424L540.02 200.576H11.9121V18H800.103V200.576ZM3833 236C3663.81 236 3525 374.765 3525 548C3525 721.235 3663.81 860 3833 860H4827C4995.4 860 5134 721.468 5134 548C5134 374.532 4995.4 236 4827 236H3833ZM1328.4 180.64C1250.28 180.64 1184.74 203.136 1131.78 248.131C1080.14 291.802 1047.04 352.676 1032.48 430.755H1596.51C1595.18 389.731 1583.93 350.03 1562.75 311.652C1541.56 273.275 1510.45 242.176 1469.4 218.355C1429.68 193.212 1382.68 180.64 1328.4 180.64Z" fill="#7C4FE8"/>
+</svg>

package/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm check
+      - run: pnpm test -- --run

package/.github/workflows/release.yml

@@ -0,0 +1,38 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - name: Verify tag matches package.json version
+        if: github.event_name == 'release'
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          PKG=$(node -p "require('./package.json').version")
+          if [ "$TAG" != "$PKG" ]; then
+            echo "tag $GITHUB_REF_NAME ($TAG) does not match package.json version $PKG"
+            exit 1
+          fi
+      - run: pnpm check
+      - run: pnpm test -- --run
+      - run: pnpm build
+      - run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -1,6 +1,28 @@
-# ZenRows Node.js SDK
-
-SDK to access [ZenRows](https://www.zenrows.com/) API directly from Node.js. ZenRows handles proxies rotation, headless browsers, and CAPTCHAs for you.
+<p align="center">
+    <picture>
+        <source media="(prefers-color-scheme: dark)" srcset=".github/assets/logo/dark.svg"/>
+        <img alt="Zenrows Logo" src=".github/assets/logo/light.svg" width="300" />
+    </picture>
+</p>
+
+# Zenrows Node.js SDK
+
+SDK to access [Zenrows](https://www.zenrows.com/) API directly from Node.js. Zenrows handles proxies rotation, headless browsers, and CAPTCHAs for you.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Adaptive Stealth Mode](#adaptive-stealth-mode)
+  - [POST Requests](#post-requests)
+  - [Extract](#extract)
+  - [Batch](#batch)
+    - [Extract in a batch](#extract-in-a-batch)
+  - [Concurrency](#concurrency)
+    - [An important note about Promise.allSettled() on TypeScript](#an-important-note-about-promiseallsettled-on-typescript)
+- [Examples](#examples)
+- [Contributing](#contributing)
+- [License](#license)
 
 ## Installation
 
@@ -21,6 +43,8 @@ The SDK uses the official [fetch api](https://nodejs.org/dist/latest-v18.x/docs/
 
 It also uses [fetch-retry](https://github.com/jonbern/fetch-retry) to automatically retry failed requests (status code 429 and 5XX). Retries are not active by default; you need to specify the number of retries, as shown below. It already includes an exponential back-off retry delay between failed requests.
 
+> `client.fetch()` is the primary method for the main page-scraping product. `client.get()` still works and is kept as a deprecated alias — new code should call `fetch()`.
+
 ```javascript
 const { ZenRows } = require("zenrows");
 
@@ -30,7 +54,7 @@ const url = "https://www.zenrows.com/";
 (async () => {
   const client = new ZenRows(apiKey, { retries: 1 });
 
-  const response = await client.get(
+  const response = await client.fetch(
     url,
     {
       // Our algorithm allows to automatically extract content from any website
@@ -99,6 +123,16 @@ You can also pass optional parameters and headers; the list above is a reference
 
 Sending headers to the target URL will overwrite our defaults. Be careful when doing it and contact us if there is any problem.
 
+### Adaptive Stealth Mode
+
+Set `mode: "auto"` to let Zenrows pick the request configuration for you — it starts with the cheapest viable setup and escalates to `js_render`/`premium_proxy` only when the target needs it, billing only for the configuration that succeeds.
+
+```javascript
+const response = await client.get(url, { mode: "auto" });
+```
+
+Compatible with `proxy_country`, `js_instructions`, and `custom_headers`.
+
 ### POST Requests
 
 The SDK also offers POST requests by calling the `client.post` method. It can receive a new parameter `data` that represents the data sent in, for example, a form.
@@ -136,6 +170,89 @@ const url = "https://httpbin.org/anything";
 })();
 ```
 
+### Extract
+
+[Extract](https://docs.zenrows.com) (beta) runs a page through Zenrows' AI-powered structured extraction instead of returning raw HTML. Use `client.extract()` — it's the same request as `fetch()`, with the `extract` param set for you (defaults to `"auto"`; pass `"native"` or `"standard"` for the other contracts).
+
+```javascript
+const { ZenRows } = require("zenrows");
+
+const apiKey = "YOUR-API-KEY";
+const url = "https://www.zenrows.com/";
+
+(async () => {
+  const client = new ZenRows(apiKey);
+
+  const response = await client.extract(url); // extract: "auto"
+  // const response = await client.extract(url, { extract: "native" });
+
+  const data = await response.json();
+  console.log(data);
+})();
+```
+
+### Batch
+
+The [Batch API](https://docs.zenrows.com) (beta) runs many URLs asynchronously as a job, and is reachable via `client.batch`. A job is either **open** — it keeps accepting tasks via `addTasks()` until you `closeJob()` it, useful when you're streaming URLs in over time — or a normal one-shot batch where every task is known upfront.
+
+```javascript
+const { ZenRows } = require("zenrows");
+
+const apiKey = "YOUR-API-KEY";
+
+(async () => {
+  const client = new ZenRows(apiKey);
+
+  // One-shot batch: every task known upfront.
+  const job = await client.batch.submitJob({
+    tasks: [{ url: "https://example.com/1" }, { url: "https://example.com/2" }],
+  });
+
+  // Streaming batch: keep the job open, add tasks as they arrive, close when done.
+  const streamingJob = await client.batch.submitJob({ status: "open" });
+  await client.batch.addTasks(streamingJob.job_id, [{ url: "https://example.com/3" }]);
+  // Or close it as part of the last addTasks() call instead of a separate request:
+  // await client.batch.addTasks(streamingJob.job_id, [...], { lastBatch: true });
+  await client.batch.closeJob(streamingJob.job_id);
+
+  // Poll for progress and page through results once it's done.
+  const status = await client.batch.getJob(job.job_id);
+  const { results, next_cursor } = await client.batch.getResults(job.job_id);
+
+  // Retry only the tasks that failed, inheriting the rest from the previous run.
+  await client.batch.rerun(job.job_id, { status: "failed" });
+})();
+```
+
+`client.batch` also exposes `listJobs()`, `deleteJob()`, `stopRun()`, `rerun()`, `listRuns()`, `getRun()`, `deleteRun()`, and `getTaskContent()` (returns the scraped page's raw content as a string, not JSON — the endpoint can return HTML or plain text depending on what the target page served). Scheduling, webhook config, HMAC key rotation, CSV task uploads, and results exports aren't wrapped yet — call the [Batch API](https://docs.zenrows.com) directly for those.
+
+#### Extract in a batch
+
+Set `extract` in the batch params to run tasks through Extract — structured data instead of raw HTML. It works job-wide or per task, and per-task values win on collision.
+
+```js
+const job = await client.batch.submitRegular(
+  [
+    // Inherits the job-level params below.
+    { url: "https://example.com/products", external_id: "p1" },
+    // Overrides them for this task only.
+    { url: "https://example.com/raw", zenrows_params: {} },
+  ],
+  undefined,
+  { zenrowsParams: { extract: "auto" } },
+);
+```
+
+An Extract task's result carries two keys — `html` (the raw page) and `parsed` (the structured data). It costs the same as a regular task, so `estimateCost` prices it correctly. `extract_fields` is not supported in Batch yet.
+
+The batch client (`ZenRowsBatchClient`) also works standalone, without a `ZenRows` instance — matching the Go and Python SDKs' batch clients:
+
+```javascript
+const { ZenRowsBatchClient } = require("zenrows");
+
+const batch = new ZenRowsBatchClient(apiKey, { baseURL: "https://async.api.zenrows.com/v1" }); // baseURL is optional
+```
+
 ### Concurrency
 
 To limit the concurrency, it uses [fastq](https://github.com/mcollina/fastq), which will simultaneously send a maximum of requests. The concurrency is determined by the plan you are in, so take a look at the [pricing](https://www.zenrows.com/pricing) and set it accordingly. Take into account that each client instance will have its own limit, meaning that two different scripts will not share it, and 429 (Too Many Requests) errors might arise.
@@ -155,7 +272,7 @@ const apiKey = "YOUR-API-KEY";
     // ...
   ];
 
-  const promises = urls.map((url) => client.get(url));
+  const promises = urls.map((url) => client.fetch(url));
 
   const results = await Promise.allSettled(promises);
   console.log(results);
@@ -182,7 +299,7 @@ const apiKey = "YOUR-API-KEY";
 `Promise.allSettled()` does not narrow the type of the array elements in the callback function. This means that you will need to cast the type of the array elements to `PromiseSettledResult<Response>` to access the `status` and `value` properties.
 
 ```typescript
-const promises = urls.map((url) => client.get(url));
+const promises = urls.map((url) => client.fetch(url));
 
 const results = await Promise.allSettled(promises);