thordata-js-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Thordata
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,342 @@
+# Thordata JS SDK (Node.js / TypeScript)
+
+Official JavaScript/TypeScript SDK for <!--citation:1-->.
+
+This SDK supports:
+
+- **SERP API** (Google / Bing / Yandex / DuckDuckGo / Baidu)
+- **Web Unlocker / Universal API**
+- **Web Scraper API** (task-based scraping)
+
+It is designed to be:
+
+- **TypeScript-first**
+- **ESM-ready**
+- **Offline-test friendly** (base URLs can be overridden to run examples/tests against a mock server)
+
+---
+
+## 📦 Installation
+
+```bash
+npm install thordata-js-sdk
+```
+
+If you are developing locally:
+
+```bash
+git clone https://github.com/Thordata/thordata-js-sdk.git
+cd thordata-js-sdk
+npm install
+npm run build
+```
+
+---
+
+## 🔐 Configuration
+
+Set environment variables:
+
+```bash
+export THORDATA_SCRAPER_TOKEN=your_scraper_token
+export THORDATA_PUBLIC_TOKEN=your_public_token
+export THORDATA_PUBLIC_KEY=your_public_key
+```
+
+Or create a `.env` file (examples may use dotenv):
+
+```env
+THORDATA_SCRAPER_TOKEN=your_scraper_token
+THORDATA_PUBLIC_TOKEN=your_public_token
+THORDATA_PUBLIC_KEY=your_public_key
+```
+
+---
+
+## 🚀 Quick Start
+
+### Create a client
+
+```typescript
+import { ThordataClient } from "thordata-js-sdk";
+
+const client = new ThordataClient({
+  scraperToken: process.env.THORDATA_SCRAPER_TOKEN!,
+  publicToken: process.env.THORDATA_PUBLIC_TOKEN,
+  publicKey: process.env.THORDATA_PUBLIC_KEY,
+});
+```
+
+---
+
+## 🔍 SERP API
+
+### Basic Google Search
+
+```typescript
+import { ThordataClient, Engine } from "thordata-js-sdk";
+
+const client = new ThordataClient({ scraperToken: process.env.THORDATA_SCRAPER_TOKEN! });
+
+const data = await client.serpSearch({
+  query: "Thordata proxy network",
+  engine: Engine.GOOGLE,
+  num: 5,
+});
+
+const organic = data?.organic ?? [];
+console.log(`Found ${organic.length} organic results`);
+
+for (const item of organic.slice(0, 3)) {
+  console.log("-", item.title, "->", item.link);
+}
+```
+
+### Recommended engines for Google verticals (News / Shopping)
+
+Thordata supports both:
+
+- Dedicated engines (recommended): `google_news`, `google_shopping`
+- Generic Google + tbm via `searchType` (alternative)
+
+#### Google News (recommended):
+
+```typescript
+const data = await client.serpSearch({
+  query: "AI regulation",
+  engine: "google_news",
+  country: "us",
+  language: "en",
+  num: 10,
+  so: 1, // 0=relevance, 1=date (Google News)
+});
+```
+
+#### Google Shopping (recommended):
+
+```typescript
+const data = await client.serpSearch({
+  query: "iPhone 15",
+  engine: "google_shopping",
+  country: "us",
+  language: "en",
+  num: 10,
+  min_price: 500,
+  max_price: 1500,
+});
+```
+
+#### Alternative: Google generic engine + tbm (via searchType):
+
+```typescript
+const data = await client.serpSearch({
+  query: "iPhone 15",
+  engine: "google",
+  searchType: "shopping", // maps to tbm=shop
+  country: "us",
+  language: "en",
+  num: 10,
+});
+```
+
+Official and up-to-date parameters are documented at: https://doc.thordata.com
+
+---
+
+## 🔓 Web Unlocker / Universal API
+
+### Basic HTML scraping
+
+```typescript
+const html = await client.universalScrape({
+  url: "https://httpbin.org/html",
+  jsRender: false,
+  outputFormat: "html",
+});
+
+console.log(String(html).slice(0, 300));
+```
+
+### JS rendering + wait for selector
+
+```typescript
+const html = await client.universalScrape({
+  url: "https://example.com/spa",
+  jsRender: true,
+  outputFormat: "html",
+  waitFor: ".main-content",
+});
+```
+
+### Screenshot (PNG)
+
+```typescript
+import { writeFileSync } from "node:fs";
+
+const pngBytes = await client.universalScrape({
+  url: "https://example.com",
+  jsRender: true,
+  outputFormat: "png",
+});
+
+writeFileSync("screenshot.png", pngBytes as Buffer);
+```
+
+---
+
+## 🕷️ Web Scraper API (Task-based)
+
+Requires `THORDATA_PUBLIC_TOKEN` and `THORDATA_PUBLIC_KEY`.
+
+```typescript
+const client = new ThordataClient({
+  scraperToken: process.env.THORDATA_SCRAPER_TOKEN!,
+  publicToken: process.env.THORDATA_PUBLIC_TOKEN,
+  publicKey: process.env.THORDATA_PUBLIC_KEY,
+});
+
+const taskId = await client.createScraperTask({
+  fileName: "demo_task",
+  spiderId: "example-spider-id",
+  spiderName: "example.com",
+  parameters: { url: "https://example.com" },
+});
+
+console.log("Task created:", taskId);
+
+const status = await client.waitForTask(taskId, {
+  pollIntervalMs: 5000,
+  maxWaitMs: 60000,
+});
+
+console.log("Final status:", status);
+
+if (["ready", "success", "finished"].includes(status.toLowerCase())) {
+  const downloadUrl = await client.getTaskResult(taskId, "json");
+  console.log("Download URL:", downloadUrl);
+}
+```
+
+---
+
+## 🔧 Errors & Response Codes
+
+The SDK throws typed errors when the API returns a non-success code (or non-2xx HTTP status).
+
+| Code    | Typical Meaning       | Error class                                    |
+| ------- | --------------------- | ---------------------------------------------- |
+| 200     | Success               | -                                              |
+| 300     | Not collected         | `ThordataNotCollectedError`                    |
+| 400     | Bad request           | `ThordataValidationError`                      |
+| 401/403 | Auth/Forbidden        | `ThordataAuthError`                            |
+| 402/429 | Quota/Rate limit      | `ThordataRateLimitError`                       |
+| 5xx     | Server/timeout issues | `ThordataServerError` / `ThordataTimeoutError` |
+
+### Example error handling:
+
+```typescript
+import {
+  ThordataAuthError,
+  ThordataRateLimitError,
+  ThordataTimeoutError,
+  ThordataNotCollectedError,
+} from "thordata-js-sdk";
+
+try {
+  const data = await client.serpSearch({ query: "test", engine: "google" });
+  console.log(data);
+} catch (e) {
+  if (e instanceof ThordataAuthError) {
+    console.error("Auth error: check your token.");
+  } else if (e instanceof ThordataRateLimitError) {
+    console.error(`Rate limited. Retry after: ${e.retryAfter ?? "N/A"} seconds.`);
+  } else if (e instanceof ThordataNotCollectedError) {
+    console.error("Not collected (code=300). Consider retrying.");
+  } else if (e instanceof ThordataTimeoutError) {
+    console.error("Request timed out.");
+  } else {
+    console.error("Unexpected error:", e);
+  }
+}
+```
+
+---
+
+## 🌍 Base URL Overrides (for offline tests / custom routing)
+
+You can override API base URLs via environment variables:
+
+```bash
+export THORDATA_SCRAPERAPI_BASE_URL=http://127.0.0.1:12345
+export THORDATA_UNIVERSALAPI_BASE_URL=http://127.0.0.1:12345
+export THORDATA_WEB_SCRAPER_API_BASE_URL=http://127.0.0.1:12345
+export THORDATA_LOCATIONS_BASE_URL=http://127.0.0.1:12345
+```
+
+Or via client config:
+
+```typescript
+const client = new ThordataClient({
+  scraperToken: "dummy",
+  baseUrls: { scraperapiBaseUrl: "http://127.0.0.1:12345" },
+});
+```
+
+---
+
+## 🧪 Development
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+### Run examples (compiled):
+
+```bash
+node dist/examples/basic_serp.js
+node dist/examples/basic_universal.js
+```
+
+---
+
+## 📁 Project Structure
+
+```
+thordata-js-sdk/
+├── src/
+│   ├── index.ts
+│   ├── client.ts
+│   ├── models.ts
+│   ├── enums.ts
+│   ├── errors.ts
+│   ├── retry.ts
+│   ├── endpoints.ts
+│   └── utils.ts
+├── examples/
+│   ├── basic_serp.ts
+│   ├── basic_universal.ts
+│   ├── basic_scraper_task.ts
+│   └── serp_google_news.ts
+├── tests/
+│   ├── serp.offline.test.ts
+│   ├── mockServer.ts
+│   └── examples.e2e.test.ts
+├── .github/workflows/ci.yml
+├── package.json
+├── tsconfig.json
+├── tsconfig.build.json
+└── README.md
+```
+
+---
+
+## 🔮 Roadmap
+
+- Publish stable releases to npm
+- Add async streaming / higher-level helpers for AI agents
+- Expand coverage for more engines/verticals (Flights/Maps/Scholar/Jobs, etc.)
+- Add integration tests (optional scheduled job with real tokens)
+
+---

package/dist/examples/basic_scraper_task.d.ts

@@ -0,0 +1 @@
+import "dotenv/config";

package/dist/examples/basic_scraper_task.js

@@ -0,0 +1,46 @@
+// examples/basic_scraper_task.ts
+import "dotenv/config";
+import { ThordataClient } from "../src/index.js";
+async function main() {
+    const scraperToken = process.env.THORDATA_SCRAPER_TOKEN;
+    const publicToken = process.env.THORDATA_PUBLIC_TOKEN;
+    const publicKey = process.env.THORDATA_PUBLIC_KEY;
+    if (!scraperToken || !publicToken || !publicKey) {
+        console.error("Please set THORDATA_SCRAPER_TOKEN, THORDATA_PUBLIC_TOKEN, THORDATA_PUBLIC_KEY in .env");
+        process.exit(1);
+    }
+    const client = new ThordataClient({
+        scraperToken,
+        publicToken,
+        publicKey,
+    });
+    console.log("🕷️  Creating Web Scraper task (example only)...");
+    try {
+        const taskId = await client.createScraperTask({
+            fileName: "demo_task",
+            spiderId: "example-spider-id",
+            spiderName: "example.com",
+            parameters: {
+                url: "https://example.com",
+            },
+        });
+        console.log("Task created:", taskId);
+        console.log("⏱️  Waiting for task completion...");
+        const status = await client.waitForTask(taskId, {
+            pollIntervalMs: 5000,
+            maxWaitMs: 60_000,
+        });
+        console.log("Final status:", status);
+        if (status.toLowerCase() === "ready" || status.toLowerCase() === "success") {
+            const downloadUrl = await client.getTaskResult(taskId, "json");
+            console.log("Download URL:", downloadUrl);
+        }
+    }
+    catch (err) {
+        console.error("Error:", err);
+    }
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+});
+//# sourceMappingURL=basic_scraper_task.js.map

package/dist/examples/basic_scraper_task.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"basic_scraper_task.js","sourceRoot":"","sources":["../../examples/basic_scraper_task.ts"],"names":[],"mappings":"AAAA,iCAAiC;AAEjC,OAAO,eAAe,CAAC;AACvB,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD,KAAK,UAAU,IAAI;IACjB,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC;IACxD,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC;IACtD,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC;IAElD,IAAI,CAAC,YAAY,IAAI,CAAC,WAAW,IAAI,CAAC,SAAS,EAAE,CAAC;QAChD,OAAO,CAAC,KAAK,CACX,uFAAuF,CACxF,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC;QAChC,YAAY;QACZ,WAAW;QACX,SAAS;KACV,CAAC,CAAC;IAEH,OAAO,CAAC,GAAG,CAAC,kDAAkD,CAAC,CAAC;IAChE,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC;YAC5C,QAAQ,EAAE,WAAW;YACrB,QAAQ,EAAE,mBAAmB;YAC7B,UAAU,EAAE,aAAa;YACzB,UAAU,EAAE;gBACV,GAAG,EAAE,qBAAqB;aAC3B;SACF,CAAC,CAAC;QAEH,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;QAErC,OAAO,CAAC,GAAG,CAAC,oCAAoC,CAAC,CAAC;QAClD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,MAAM,EAAE;YAC9C,cAAc,EAAE,IAAI;YACpB,SAAS,EAAE,MAAM;SAClB,CAAC,CAAC;QAEH,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;QAErC,IAAI,MAAM,CAAC,WAAW,EAAE,KAAK,OAAO,IAAI,MAAM,CAAC,WAAW,EAAE,KAAK,SAAS,EAAE,CAAC;YAC3E,MAAM,WAAW,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YAC/D,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,WAAW,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IAC/B,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;AACrC,CAAC,CAAC,CAAC"}

package/dist/examples/basic_serp.d.ts

@@ -0,0 +1 @@
+import "dotenv/config";

package/dist/examples/basic_serp.js

@@ -0,0 +1,29 @@
+// examples/basic_serp.ts
+import "dotenv/config";
+import { ThordataClient, Engine } from "../src/index.js";
+async function main() {
+    const token = process.env.THORDATA_SCRAPER_TOKEN;
+    if (!token) {
+        console.error("Please set THORDATA_SCRAPER_TOKEN in .env");
+        process.exit(1);
+    }
+    const client = new ThordataClient({ scraperToken: token });
+    console.log("🔍 Google Search: 'Thordata proxy network'");
+    const results = await client.serpSearch({
+        query: "Thordata proxy network",
+        engine: Engine.GOOGLE,
+        num: 5,
+    });
+    // 调试用：看真实返回结构
+    console.dir(results, { depth: 4 });
+    // 优先找 'organic'，其次才是 'organic_results'
+    const organic = results?.organic ?? results?.organic_results ?? [];
+    console.log(`Found ${organic.length} organic results`);
+    for (const item of organic.slice(0, 3)) {
+        console.log("-", item.title, "->", item.link);
+    }
+}
+main().catch((err) => {
+    console.error("Error:", err);
+});
+//# sourceMappingURL=basic_serp.js.map

package/dist/examples/basic_serp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"basic_serp.js","sourceRoot":"","sources":["../../examples/basic_serp.ts"],"names":[],"mappings":"AAAA,yBAAyB;AAEzB,OAAO,eAAe,CAAC;AACvB,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEzD,KAAK,UAAU,IAAI;IACjB,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC;IACjD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,CAAC,KAAK,CAAC,2CAA2C,CAAC,CAAC;QAC3D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC,CAAC;IAE3D,OAAO,CAAC,GAAG,CAAC,4CAA4C,CAAC,CAAC;IAC1D,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC;QACtC,KAAK,EAAE,wBAAwB;QAC/B,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,GAAG,EAAE,CAAC;KACP,CAAC,CAAC;IAEH,cAAc;IACd,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;IAEnC,uCAAuC;IACvC,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,eAAe,IAAI,EAAE,CAAC;IACnE,OAAO,CAAC,GAAG,CAAC,SAAS,OAAO,CAAC,MAAM,kBAAkB,CAAC,CAAC;IACvD,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;QACvC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IAChD,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;AAC/B,CAAC,CAAC,CAAC"}

package/dist/examples/basic_universal.d.ts

@@ -0,0 +1 @@
+import "dotenv/config";

package/dist/examples/basic_universal.js

@@ -0,0 +1,23 @@
+// examples/basic_universal.ts
+import "dotenv/config";
+import { ThordataClient } from "../src/index.js";
+async function main() {
+    const token = process.env.THORDATA_SCRAPER_TOKEN;
+    if (!token) {
+        console.error("Please set THORDATA_SCRAPER_TOKEN in .env");
+        process.exit(1);
+    }
+    const client = new ThordataClient({ scraperToken: token });
+    console.log("🌐 Universal Scrape: https://httpbin.org/html");
+    const html = await client.universalScrape({
+        url: "https://httpbin.org/html",
+        jsRender: false,
+        outputFormat: "html",
+    });
+    console.log("Preview:");
+    console.log(String(html).slice(0, 300));
+}
+main().catch((err) => {
+    console.error("Error:", err);
+});
+//# sourceMappingURL=basic_universal.js.map

package/dist/examples/basic_universal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"basic_universal.js","sourceRoot":"","sources":["../../examples/basic_universal.ts"],"names":[],"mappings":"AAAA,8BAA8B;AAE9B,OAAO,eAAe,CAAC;AACvB,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD,KAAK,UAAU,IAAI;IACjB,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC;IACjD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,CAAC,KAAK,CAAC,2CAA2C,CAAC,CAAC;QAC3D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC,CAAC;IAE3D,OAAO,CAAC,GAAG,CAAC,+CAA+C,CAAC,CAAC;IAC7D,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC;QACxC,GAAG,EAAE,0BAA0B;QAC/B,QAAQ,EAAE,KAAK;QACf,YAAY,EAAE,MAAM;KACrB,CAAC,CAAC;IAEH,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACxB,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;AAC1C,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;AAC/B,CAAC,CAAC,CAAC"}

package/dist/examples/proxy_ip_check.d.ts

@@ -0,0 +1 @@
+import "dotenv/config";

package/dist/examples/proxy_ip_check.js

@@ -0,0 +1,37 @@
+// examples/proxy_ip_check.ts
+import "dotenv/config";
+import { ThordataClient, ProxyConfig } from "../src/index.js";
+async function main() {
+    const scraperToken = process.env.THORDATA_SCRAPER_TOKEN;
+    const proxyUser = process.env.THORDATA_PROXY_USERNAME;
+    const proxyPass = process.env.THORDATA_PROXY_PASSWORD;
+    const proxyHost = process.env.THORDATA_PROXY_HOST || "t.pr.thordata.net";
+    const proxyPort = Number(process.env.THORDATA_PROXY_PORT || "9999");
+    if (!scraperToken) {
+        console.error("Please set THORDATA_SCRAPER_TOKEN in .env");
+        process.exit(1);
+    }
+    if (!proxyUser || !proxyPass) {
+        console.error("Please set THORDATA_PROXY_USERNAME and THORDATA_PROXY_PASSWORD in .env");
+        process.exit(1);
+    }
+    const client = new ThordataClient({ scraperToken });
+    const proxy = new ProxyConfig({
+        baseUsername: proxyUser,
+        password: proxyPass,
+        host: proxyHost,
+        port: proxyPort,
+        country: "us",
+    });
+    // 使用 HTTP 避免 HTTPS + 证书域名不匹配问题
+    const targetUrl = "http://ipinfo.thordata.com";
+    // 或者用 http://httpbin.org/ip 做演示
+    // const targetUrl = "http://httpbin.org/ip";
+    console.log(`🌐 Requesting ${targetUrl} via Thordata proxy...`);
+    const data = await client.requestViaProxy(targetUrl, proxy);
+    console.log("Response JSON:", data);
+}
+main().catch((err) => {
+    console.error("Error:", err);
+});
+//# sourceMappingURL=proxy_ip_check.js.map

package/dist/examples/proxy_ip_check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy_ip_check.js","sourceRoot":"","sources":["../../examples/proxy_ip_check.ts"],"names":[],"mappings":"AAAA,6BAA6B;AAE7B,OAAO,eAAe,CAAC;AACvB,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9D,KAAK,UAAU,IAAI;IACjB,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC;IACxD,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC;IACtD,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC;IACtD,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,mBAAmB,CAAC;IACzE,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,MAAM,CAAC,CAAC;IAEpE,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,OAAO,CAAC,KAAK,CAAC,2CAA2C,CAAC,CAAC;QAC3D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,IAAI,CAAC,SAAS,IAAI,CAAC,SAAS,EAAE,CAAC;QAC7B,OAAO,CAAC,KAAK,CAAC,wEAAwE,CAAC,CAAC;QACxF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC;IAEpD,MAAM,KAAK,GAAG,IAAI,WAAW,CAAC;QAC5B,YAAY,EAAE,SAAS;QACvB,QAAQ,EAAE,SAAS;QACnB,IAAI,EAAE,SAAS;QACf,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,IAAI;KACd,CAAC,CAAC;IAEH,+BAA+B;IAC/B,MAAM,SAAS,GAAG,4BAA4B,CAAC;IAC/C,gCAAgC;IAChC,6CAA6C;IAE7C,OAAO,CAAC,GAAG,CAAC,iBAAiB,SAAS,wBAAwB,CAAC,CAAC;IAEhE,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IAC5D,OAAO,CAAC,GAAG,CAAC,gBAAgB,EAAE,IAAI,CAAC,CAAC;AACtC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;AAC/B,CAAC,CAAC,CAAC"}

package/dist/examples/serp_google_news.d.ts

@@ -0,0 +1,7 @@
+/**
+ * SERP Google News Demo
+ *
+ * Usage:
+ *   npx ts-node examples/serp_google_news.ts
+ */
+import "dotenv/config";

package/dist/examples/serp_google_news.js

@@ -0,0 +1,64 @@
+/**
+ * SERP Google News Demo
+ *
+ * Usage:
+ *   npx ts-node examples/serp_google_news.ts
+ */
+import "dotenv/config";
+import { ThordataClient, Engine } from "../src/index.js";
+async function main() {
+    const token = process.env.THORDATA_SCRAPER_TOKEN;
+    if (!token) {
+        console.error("❌ Error: THORDATA_SCRAPER_TOKEN not found in .env");
+        process.exit(1);
+    }
+    const client = new ThordataClient({
+        scraperToken: token,
+        maxRetries: 3,
+    });
+    // 1. Basic News Search
+    console.log("\n📰 1. Basic Google News Search: 'AI regulation'");
+    try {
+        const results = await client.serpSearch({
+            query: "AI regulation",
+            engine: Engine.GOOGLE_NEWS,
+            country: "us",
+            language: "en",
+            num: 5,
+        });
+        printNewsResults(results);
+    }
+    catch (e) {
+        console.error("❌ Search failed:", e.message);
+    }
+    // 2. Advanced News Filters
+    console.log("\n📰 2. Advanced Filters (Sort by Date)");
+    try {
+        const results = await client.serpSearch({
+            query: "Artificial Intelligence",
+            engine: Engine.GOOGLE_NEWS,
+            country: "us",
+            language: "en",
+            num: 5,
+            so: 1, // Sort by date
+        });
+        printNewsResults(results);
+    }
+    catch (e) {
+        console.error("❌ Advanced search failed:", e.message);
+    }
+}
+function printNewsResults(results) {
+    const news = results?.news ?? [];
+    console.log(`✅ Found ${news.length} news items:`);
+    news.slice(0, 5).forEach((item) => {
+        console.log(`   ${item.rank}. [${item.source}] ${item.title}`);
+        console.log(`      📅 ${item.date}`);
+        console.log(`      🔗 ${item.link}`);
+    });
+    console.log("");
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+});
+//# sourceMappingURL=serp_google_news.js.map

package/dist/examples/serp_google_news.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serp_google_news.js","sourceRoot":"","sources":["../../examples/serp_google_news.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,eAAe,CAAC;AACvB,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEzD,KAAK,UAAU,IAAI;IACjB,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC;IACjD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,CAAC,KAAK,CAAC,mDAAmD,CAAC,CAAC;QACnE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC;QAChC,YAAY,EAAE,KAAK;QACnB,UAAU,EAAE,CAAC;KACd,CAAC,CAAC;IAEH,uBAAuB;IACvB,OAAO,CAAC,GAAG,CAAC,mDAAmD,CAAC,CAAC;IACjE,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC;YACtC,KAAK,EAAE,eAAe;YACtB,MAAM,EAAE,MAAM,CAAC,WAAW;YAC1B,OAAO,EAAE,IAAI;YACb,QAAQ,EAAE,IAAI;YACd,GAAG,EAAE,CAAC;SACP,CAAC,CAAC;QACH,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,CAAM,EAAE,CAAC;QAChB,OAAO,CAAC,KAAK,CAAC,kBAAkB,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;IAC/C,CAAC;IAED,2BAA2B;IAC3B,OAAO,CAAC,GAAG,CAAC,yCAAyC,CAAC,CAAC;IACvD,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC;YACtC,KAAK,EAAE,yBAAyB;YAChC,MAAM,EAAE,MAAM,CAAC,WAAW;YAC1B,OAAO,EAAE,IAAI;YACb,QAAQ,EAAE,IAAI;YACd,GAAG,EAAE,CAAC;YACN,EAAE,EAAE,CAAC,EAAE,eAAe;SACvB,CAAC,CAAC;QACH,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,CAAM,EAAE,CAAC;QAChB,OAAO,CAAC,KAAK,CAAC,2BAA2B,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;IACxD,CAAC;AACH,CAAC;AAED,SAAS,gBAAgB,CAAC,OAAY;IACpC,MAAM,IAAI,GAAG,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC;IAEjC,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,CAAC,MAAM,cAAc,CAAC,CAAC;IAElD,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAS,EAAE,EAAE;QACrC,OAAO,CAAC,GAAG,CAAC,MAAM,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;QAC/D,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QACrC,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;IACH,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AAClB,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;AACrC,CAAC,CAAC,CAAC"}

package/dist/src/client.d.ts

@@ -0,0 +1,39 @@
+import { SerpOptions, UniversalOptions, ScraperTaskOptions, WaitForTaskOptions, ProxyConfig } from "./models.js";
+import { type ThordataBaseUrls } from "./endpoints.js";
+export interface ThordataClientConfig {
+    scraperToken: string;
+    publicToken?: string;
+    publicKey?: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+    baseUrls?: Partial<ThordataBaseUrls>;
+    userAgent?: string;
+}
+export declare class ThordataClient {
+    private scraperToken;
+    private publicToken?;
+    private publicKey?;
+    private timeoutMs;
+    private maxRetries;
+    private http;
+    private baseUrls;
+    private userAgent;
+    private serpUrl;
+    private universalUrl;
+    private scraperBuilderUrl;
+    private scraperStatusUrl;
+    private scraperDownloadUrl;
+    constructor(config: ThordataClientConfig);
+    /**
+     * Internal helper to execute request with retry logic
+     */
+    private execute;
+    serpSearch(options: SerpOptions): Promise<any>;
+    universalScrape(options: UniversalOptions): Promise<string | Buffer>;
+    createScraperTask(options: ScraperTaskOptions): Promise<string>;
+    private requirePublicCreds;
+    getTaskStatus(taskId: string): Promise<string>;
+    getTaskResult(taskId: string, fileType?: "json" | "csv" | "xlsx"): Promise<string>;
+    waitForTask(taskId: string, options?: WaitForTaskOptions): Promise<string>;
+    requestViaProxy(url: string, proxyConfig: ProxyConfig, axiosConfig?: Record<string, any>): Promise<any>;
+}