thordata-js-sdk 1.0.1 → 1.2.0

package/README.md

@@ -1,17 +1,30 @@
-# Thordata JS SDK (Node.js / TypeScript)
+# Thordata Node.js SDK
 
-Official JavaScript/TypeScript SDK for Thordata APIs.
+<div align="center">
 
-[![npm version](https://img.shields.io/npm/v/thordata-js-sdk.svg)](https://www.npmjs.com/package/thordata-js-sdk)
-[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+<img src="https://img.shields.io/badge/Thordata-AI%20Infrastructure-blue?style=for-the-badge" alt="Thordata Logo">
 
-Supports:
+**The Official Node.js/TypeScript Client for Thordata APIs**
 
-- **SERP API** (Google / Bing / Yandex)
-- **Web Unlocker** (Universal API)
-- **Web Scraper API** (Text & Video Tasks)
-- **Proxy Network** (Residential / Datacenter / Mobile / ISP)
-- **Account Management** (Usage, Users, Whitelist)
+*Proxy Network • SERP API • Web Unlocker • Web Scraper API*
+
+[![npm version](https://img.shields.io/npm/v/thordata-js-sdk.svg?style=flat-square)](https://www.npmjs.com/package/thordata-js-sdk)
+[![License](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/Thordata/thordata-js-sdk/ci.yml?branch=main&style=flat-square)](https://github.com/Thordata/thordata-js-sdk/actions)
+
+</div>
+
+---
+
+## 📖 Introduction
+
+A fully typed TypeScript SDK for Thordata, optimized for Node.js environments. It provides seamless integration with Thordata's proxy network and scraping APIs.
+
+**Key Features:**
+*   **🔒 Type-Safe:** Written in TypeScript with complete definitions.
+*   **🌐 Modern:** Uses `axios` and standard `https-proxy-agent` for reliable connectivity.
+*   **⚡ Lazy Validation:** Zero-config initialization; only provide credentials for the features you use.
+*   **🛡️ Proxy Support:** Full support for HTTPS and SOCKS5h protocols with authentication.
 
 ---
 
@@ -19,112 +32,110 @@ Supports:
 
 ```bash
 npm install thordata-js-sdk
+# or
+yarn add thordata-js-sdk
 ```
 
 ---
 
 ## 🔐 Configuration
 
+We recommend using `dotenv` to manage credentials.
+
 ```bash
-export THORDATA_SCRAPER_TOKEN=your_token
-export THORDATA_PUBLIC_TOKEN=your_public_token
-export THORDATA_PUBLIC_KEY=your_public_key
+# .env file
+THORDATA_SCRAPER_TOKEN=your_token
+THORDATA_RESIDENTIAL_USERNAME=your_username
+THORDATA_RESIDENTIAL_PASSWORD=your_password
+THORDATA_PROXY_HOST=vpnXXXX.pr.thordata.net
 ```
 
 ---
 
 ## 🚀 Quick Start
 
-```typescript
-import { Thordata } from "thordata-js-sdk";
+### 1. SERP Search
 
-const client = new Thordata(); // Reads from env vars
+```typescript
+import { ThordataClient, Engine } from "thordata-js-sdk";
+
+const client = new ThordataClient({}); // Auto-loads from env
+
+async function search() {
+  const result = await client.serpSearch({
+    query: "SpaceX launch",
+    engine: Engine.GOOGLE_NEWS,
+    country: "us",
+    num: 5
+  });
+  
+  console.log(result.news_results);
+}
 
-// SERP Search
-const results = await client.serpSearch({
-  query: "Thordata SDK",
-  engine: "google",
-  country: "us",
-});
-console.log(results.organic?.[0]?.link);
+search();
 ```
 
----
-
-## 📖 Features
-
-### SERP API
+### 2. Universal Scrape (Web Unlocker)
 
 ```typescript
-const news = await client.serpSearch({
-  query: "AI News",
-  engine: "google_news",
-  num: 10,
-});
+async function scrape() {
+  const html = await client.universalScrape({
+    url: "https://www.g2.com/products/thordata",
+    jsRender: true,
+    waitFor: ".reviews-list",
+    country: "us"
+  });
+  
+  console.log("Page HTML length:", html.length);
+}
 ```
 
-### Web Unlocker (Universal)
+### 3. Using the Proxy Network
 
 ```typescript
-const html = await client.universalScrape({
-  url: "https://example.com",
-  jsRender: true,
-  waitFor: ".content",
-});
+import { Thordata } from "thordata-js-sdk";
+
+// Create a targeted proxy config
+const proxy = Thordata.Proxy.residentialFromEnv()
+  .country("gb")
+  .city("london")
+  .sticky(10); // 10 minutes session
+
+const client = new Thordata();
+
+// Request uses the proxy automatically
+const response = await client.request("https://ipinfo.io/json", { proxy });
+console.log(response);
 ```
 
-### Web Scraper API (Async)
+---
+
+## ⚙️ Advanced Usage
+
+### Task Management (Async)
 
 ```typescript
-// Create Task
+// Create a scraping task
 const taskId = await client.createScraperTask({
-  fileName: "task1",
+  fileName: "task_001",
   spiderId: "universal",
   spiderName: "universal",
-  parameters: { url: "https://example.com" },
+  parameters: { url: "https://example.com" }
 });
 
-// Video Task (New)
-const vidId = await client.createVideoTask({
-  fileName: "video1",
-  spiderId: "youtube_video_by-url",
-  spiderName: "youtube.com",
-  parameters: { url: "..." },
-  commonSettings: { resolution: "1080p" },
-});
+console.log(`Task ${taskId} created. Waiting...`);
 
-// Wait & Result
+// Poll for completion
 const status = await client.waitForTask(taskId);
+
 if (status === "ready") {
-  const url = await client.getTaskResult(taskId);
-  console.log(url);
+  const downloadUrl = await client.getTaskResult(taskId);
+  console.log("Result:", downloadUrl);
 }
 ```
 
-### Account Management
-
-```typescript
-// Usage Stats
-const stats = await client.getUsageStatistics("2024-01-01", "2024-01-31");
-console.log("Balance:", stats.traffic_balance);
-
-// Proxy Users
-const users = await client.listProxyUsers("residential");
-
-// Whitelist
-await client.addWhitelistIp("1.2.3.4");
-```
-
-### Proxy Configuration
-
-```typescript
-// Residential Proxy
-const proxy = Thordata.Proxy.residentialFromEnv().country("us");
-await client.request("https://httpbin.org/ip", { proxy });
-```
-
 ---
 
 ## 📄 License
 
-MIT License
+MIT License.

package/dist/examples/basic_scraper_task.d.ts

@@ -1 +1,2 @@
 import "dotenv/config";
+//# sourceMappingURL=basic_scraper_task.d.ts.map

package/dist/examples/basic_scraper_task.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"basic_scraper_task.d.ts","sourceRoot":"","sources":["../../examples/basic_scraper_task.ts"],"names":[],"mappings":"AAEA,OAAO,eAAe,CAAC"}

package/dist/examples/internal/example.d.ts

@@ -3,3 +3,4 @@ export declare function env(name: string): string;
 export declare function skipIfMissing(...required: string[]): boolean;
 export declare function printJSON(v: unknown): void;
 export declare function truncate(s: string, n: number): string;
+//# sourceMappingURL=example.d.ts.map

package/dist/examples/internal/example.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"example.d.ts","sourceRoot":"","sources":["../../../examples/internal/example.ts"],"names":[],"mappings":"AAGA,wBAAgB,OAAO,SAEtB;AAED,wBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAExC;AAED,wBAAgB,aAAa,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAO5D;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,QAEnC;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,UAG5C"}

package/dist/examples/location_api.d.ts

@@ -1 +1,2 @@
 import "dotenv/config";
+//# sourceMappingURL=location_api.d.ts.map

package/dist/examples/location_api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"location_api.d.ts","sourceRoot":"","sources":["../../examples/location_api.ts"],"names":[],"mappings":"AAEA,OAAO,eAAe,CAAC"}

package/dist/examples/locations_basic.d.ts

@@ -1 +1,2 @@
 export {};
+//# sourceMappingURL=locations_basic.d.ts.map

package/dist/examples/locations_basic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locations_basic.d.ts","sourceRoot":"","sources":["../../examples/locations_basic.ts"],"names":[],"mappings":""}

package/dist/examples/proxy_datacenter.d.ts

@@ -1 +1,2 @@
 import "dotenv/config";
+//# sourceMappingURL=proxy_datacenter.d.ts.map

package/dist/examples/proxy_datacenter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy_datacenter.d.ts","sourceRoot":"","sources":["../../examples/proxy_datacenter.ts"],"names":[],"mappings":"AAEA,OAAO,eAAe,CAAC"}

package/dist/examples/proxy_isp.d.ts

@@ -1 +1,2 @@
 import "dotenv/config";
+//# sourceMappingURL=proxy_isp.d.ts.map

package/dist/examples/proxy_isp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy_isp.d.ts","sourceRoot":"","sources":["../../examples/proxy_isp.ts"],"names":[],"mappings":"AAEA,OAAO,eAAe,CAAC"}

package/dist/examples/proxy_mobile.d.ts

@@ -1 +1,2 @@
 import "dotenv/config";
+//# sourceMappingURL=proxy_mobile.d.ts.map

package/dist/examples/proxy_mobile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy_mobile.d.ts","sourceRoot":"","sources":["../../examples/proxy_mobile.ts"],"names":[],"mappings":"AAEA,OAAO,eAAe,CAAC"}

package/dist/examples/proxy_residential.d.ts

@@ -1 +1,2 @@
 import "dotenv/config";
+//# sourceMappingURL=proxy_residential.d.ts.map

package/dist/examples/proxy_residential.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy_residential.d.ts","sourceRoot":"","sources":["../../examples/proxy_residential.ts"],"names":[],"mappings":"AAEA,OAAO,eAAe,CAAC"}

package/dist/examples/serp_basic.d.ts

@@ -1 +1,2 @@
 export {};
+//# sourceMappingURL=serp_basic.d.ts.map

package/dist/examples/serp_basic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serp_basic.d.ts","sourceRoot":"","sources":["../../examples/serp_basic.ts"],"names":[],"mappings":""}

package/dist/examples/serp_google_news.d.ts

@@ -1 +1,2 @@
 import "dotenv/config";
+//# sourceMappingURL=serp_google_news.d.ts.map

package/dist/examples/serp_google_news.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serp_google_news.d.ts","sourceRoot":"","sources":["../../examples/serp_google_news.ts"],"names":[],"mappings":"AAEA,OAAO,eAAe,CAAC"}

package/dist/examples/smoke_proxy_protocols.d.ts

@@ -0,0 +1,2 @@
+import "dotenv/config";
+//# sourceMappingURL=smoke_proxy_protocols.d.ts.map

package/dist/examples/smoke_proxy_protocols.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"smoke_proxy_protocols.d.ts","sourceRoot":"","sources":["../../examples/smoke_proxy_protocols.ts"],"names":[],"mappings":"AAAA,OAAO,eAAe,CAAC"}

package/dist/examples/smoke_proxy_protocols.js

@@ -0,0 +1,29 @@
+import "dotenv/config";
+import { Thordata } from "../src/thordata.js";
+function printProxyEndpoint(proxyUrl) {
+    const u = new URL(proxyUrl);
+    console.log("proxy_endpoint:", `${u.protocol}//${u.hostname}:${u.port}`);
+    console.log("proxy_user_prefix:", decodeURIComponent(u.username).slice(0, 50));
+}
+async function runOne(protocol) {
+    // IMPORTANT: set BOTH global and product-specific protocol to avoid .env overriding
+    process.env.THORDATA_PROXY_PROTOCOL = protocol;
+    process.env.THORDATA_RESIDENTIAL_PROXY_PROTOCOL = protocol;
+    const client = new Thordata();
+    const proxy = Thordata.Proxy.residentialFromEnv().country("us");
+    const proxyUrl = proxy.toProxyUrl();
+    console.log("====", protocol, "====");
+    printProxyEndpoint(proxyUrl);
+    const out = await client.request("https://ipinfo.thordata.com", { proxy });
+    console.log(out);
+}
+async function main() {
+    for (const p of ["https", "socks5h"]) {
+        await runOne(p);
+    }
+}
+main().catch((e) => {
+    console.error(e);
+    process.exit(1);
+});
+//# sourceMappingURL=smoke_proxy_protocols.js.map

package/dist/examples/smoke_proxy_protocols.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"smoke_proxy_protocols.js","sourceRoot":"","sources":["../../examples/smoke_proxy_protocols.ts"],"names":[],"mappings":"AAAA,OAAO,eAAe,CAAC;AACvB,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C,SAAS,kBAAkB,CAAC,QAAgB;IAC1C,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC5B,OAAO,CAAC,GAAG,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACzE,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,kBAAkB,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;AACjF,CAAC;AAED,KAAK,UAAU,MAAM,CAAC,QAAgB;IACpC,oFAAoF;IACpF,OAAO,CAAC,GAAG,CAAC,uBAAuB,GAAG,QAAQ,CAAC;IAC/C,OAAO,CAAC,GAAG,CAAC,mCAAmC,GAAG,QAAQ,CAAC;IAE3D,MAAM,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;IAC9B,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,kBAAkB,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhE,MAAM,QAAQ,GAAG,KAAK,CAAC,UAAU,EAAE,CAAC;IACpC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IACtC,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IAE7B,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,6BAA6B,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3E,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACnB,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,KAAK,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,CAAC;QACrC,MAAM,MAAM,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE;IACjB,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACjB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/examples/universal_basic.d.ts

@@ -1 +1,2 @@
 export {};
+//# sourceMappingURL=universal_basic.d.ts.map

package/dist/examples/universal_basic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"universal_basic.d.ts","sourceRoot":"","sources":["../../examples/universal_basic.ts"],"names":[],"mappings":""}

package/dist/examples/verify_new_features.d.ts

@@ -1 +1,2 @@
 import "dotenv/config";
+//# sourceMappingURL=verify_new_features.d.ts.map

package/dist/examples/verify_new_features.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify_new_features.d.ts","sourceRoot":"","sources":["../../examples/verify_new_features.ts"],"names":[],"mappings":"AAEA,OAAO,eAAe,CAAC"}

package/dist/examples/verify_structured_serp.d.ts

@@ -0,0 +1,2 @@
+import "dotenv/config";
+//# sourceMappingURL=verify_structured_serp.d.ts.map

package/dist/examples/verify_structured_serp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify_structured_serp.d.ts","sourceRoot":"","sources":["../../examples/verify_structured_serp.ts"],"names":[],"mappings":"AACA,OAAO,eAAe,CAAC"}

package/dist/examples/verify_structured_serp.js

@@ -0,0 +1,38 @@
+// examples/verify_structured_serp.ts
+import "dotenv/config";
+import { ThordataClient } from "../src/index.js";
+async function main() {
+    const token = process.env.THORDATA_SCRAPER_TOKEN;
+    if (!token) {
+        console.error("❌ THORDATA_SCRAPER_TOKEN required");
+        process.exit(1);
+    }
+    // Init client
+    const client = new ThordataClient({ scraperToken: token });
+    console.log("--- 1. Testing Structured Google Maps (JS) ---");
+    try {
+        // New Syntax: client.serp.google.maps(...)
+        const res = await client.serp.google.maps("coffee", "@40.745,-74.008,14z");
+        // We expect an error if account is expired, but the structure is valid if we get here (or get a specific API error)
+        console.log("✅ Maps request structure valid. API Response:", JSON.stringify(res).slice(0, 100) + "...");
+    }
+    catch (e) {
+        // Catching the API error proves the SDK built the request correctly
+        console.log(`✅ SDK Structure Works! (API returned: ${e.message})`);
+    }
+    console.log("\n--- 2. Testing Structured Google Flights (JS) ---");
+    try {
+        // New Syntax: client.serp.google.flights(...)
+        await client.serp.google.flights({
+            departureId: "JFK",
+            arrivalId: "LHR",
+            outboundDate: "2025-12-25",
+        });
+        console.log("✅ Flights request structure valid.");
+    }
+    catch (e) {
+        console.log(`✅ SDK Structure Works! (API returned: ${e.message})`);
+    }
+}
+main();
+//# sourceMappingURL=verify_structured_serp.js.map

package/dist/examples/verify_structured_serp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify_structured_serp.js","sourceRoot":"","sources":["../../examples/verify_structured_serp.ts"],"names":[],"mappings":"AAAA,qCAAqC;AACrC,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,mCAAmC,CAAC,CAAC;QACnD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,cAAc;IACd,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC,CAAC;IAE3D,OAAO,CAAC,GAAG,CAAC,gDAAgD,CAAC,CAAC;IAC9D,IAAI,CAAC;QACH,2CAA2C;QAC3C,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,qBAAqB,CAAC,CAAC;QAE3E,oHAAoH;QACpH,OAAO,CAAC,GAAG,CACT,+CAA+C,EAC/C,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,KAAK,CAC1C,CAAC;IACJ,CAAC;IAAC,OAAO,CAAM,EAAE,CAAC;QAChB,oEAAoE;QACpE,OAAO,CAAC,GAAG,CAAC,yCAAyC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC;IACrE,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,qDAAqD,CAAC,CAAC;IACnE,IAAI,CAAC;QACH,8CAA8C;QAC9C,MAAM,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC;YAC/B,WAAW,EAAE,KAAK;YAClB,SAAS,EAAE,KAAK;YAChB,YAAY,EAAE,YAAY;SAC3B,CAAC,CAAC;QACH,OAAO,CAAC,GAAG,CAAC,oCAAoC,CAAC,CAAC;IACpD,CAAC;IAAC,OAAO,CAAM,EAAE,CAAC;QAChB,OAAO,CAAC,GAAG,CAAC,yCAAyC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC;IACrE,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC"}

package/dist/src/auth.d.ts

@@ -20,3 +20,4 @@ export declare function buildPublicHeaders(creds: Credentials): Headers;
  * Interface docs require `token` + `key` (My Account) AND `Authorization: Bearer ...` (scraper token).
  */
 export declare function buildBuilderHeaders(creds: Credentials): Headers;
+//# sourceMappingURL=auth.d.ts.map

package/dist/src/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/auth.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE7C,MAAM,WAAW,WAAW;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAS/D;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAS9D;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAK/D"}

package/dist/src/client.d.ts

@@ -1,3 +1,4 @@
+import { SerpNamespace } from "./serp_engines.js";
 import { SerpOptions, UniversalOptions, ScraperTaskOptions, WaitForTaskOptions, ProxyTypeParam, CountryInfo, StateInfo, CityInfo, AsnInfo, VideoTaskOptions, UsageStatistics, ProxyUserList, ProxyServer } from "./models.js";
 import { type ThordataBaseUrls } from "./endpoints.js";
 import { Proxy } from "./proxy.js";
@@ -5,8 +6,8 @@ import { Proxy } from "./proxy.js";
  * Configuration options for ThordataClient.
  */
 export interface ThordataClientConfig {
-    /** API token for SERP and Universal APIs */
-    scraperToken: string;
+    /** API token for SERP and Universal APIs (Optional) */
+    scraperToken?: string;
     /** Public token for Web Scraper API and Location API */
     publicToken?: string;
     /** Public key for Web Scraper API and Location API */
@@ -46,6 +47,7 @@ export declare class ThordataClient {
     private proxyListUrl;
     private proxyExpirationUrl;
     private taskListUrl;
+    serp: SerpNamespace;
     constructor(config: ThordataClientConfig);
     /**
      * Execute request with retry logic.
@@ -53,80 +55,29 @@ export declare class ThordataClient {
     private execute;
     /**
      * Perform a search using the SERP API.
-     *
-     * Supported engines: google, bing, yandex, duckduckgo
-     * Plus Google specialized engines: google_news, google_shopping, etc.
-     *
-     * @example
-     * ```typescript
-     * // Basic Google search
-     * const results = await client.serpSearch({
-     *   query: "pizza",
-     *   engine: Engine.GOOGLE,
-     *   country: "us",
-     * });
-     *
-     * // Google News (recommended: use dedicated engine)
-     * const news = await client.serpSearch({
-     *   query: "AI regulation",
-     *   engine: Engine.GOOGLE_NEWS,
-     * });
-     * ```
      */
     serpSearch(options: SerpOptions): Promise<Record<string, unknown>>;
     /**
      * Scrape a URL using the Universal/Web Unlocker API.
-     *
-     * @example
-     * ```typescript
-     * // Basic HTML scraping
-     * const html = await client.universalScrape({
-     *   url: "https://example.com",
-     *   jsRender: false,
-     * });
-     *
-     * // With JS rendering and wait for element
-     * const html = await client.universalScrape({
-     *   url: "https://example.com/spa",
-     *   jsRender: true,
-     *   waitFor: ".main-content",
-     * });
-     *
-     * // Screenshot
-     * const png = await client.universalScrape({
-     *   url: "https://example.com",
-     *   jsRender: true,
-     *   outputFormat: "png",
-     * });
-     * ```
      */
     universalScrape(options: UniversalOptions): Promise<string | Buffer | Record<string, unknown>>;
-    /**
-     * Create a new Web Scraper task.
-     */
     createScraperTask(options: ScraperTaskOptions): Promise<string>;
-    /**
-     * Verify that public credentials are available.
-     */
     private requirePublicCreds;
-    /**
-     * Get the status of a Web Scraper task.
-     */
     getTaskStatus(taskId: string): Promise<string>;
-    /**
-     * Get the download URL for a completed task's results.
-     */
     getTaskResult(taskId: string, fileType?: "json" | "csv" | "xlsx"): Promise<string>;
-    /**
-     * Create a YouTube video/audio download task.
-     */
     createVideoTask(options: VideoTaskOptions): Promise<string>;
-    /**
-     * Wait for a task to complete.
-     */
     waitForTask(taskId: string, options?: WaitForTaskOptions): Promise<string>;
     /**
      * Make an HTTP request through a proxy.
+     *
+     * Supported proxy protocols:
+     * - https:// (recommended, required by most accounts)
+     * - socks5:// or socks5h:// (SOCKS5 with remote DNS)
+     * - http:// (legacy, not supported by most Thordata accounts)
+     *
+     * For users in mainland China or behind corporate firewalls:
+     * Set THORDATA_UPSTREAM_PROXY environment variable to route through local proxy.
+     * Example: THORDATA_UPSTREAM_PROXY=socks5://127.0.0.1:7897
      */
     request(url: string, config?: {
         proxy?: Proxy;
@@ -142,24 +93,11 @@ export declare class ThordataClient {
     createProxyUser(username: string, pass: string, trafficLimit?: number, status?: boolean, proxyType?: ProxyTypeParam): Promise<any>;
     addWhitelistIp(ip: string, status?: boolean, proxyType?: ProxyTypeParam): Promise<any>;
     listProxyServers(proxyType: 1 | 2): Promise<ProxyServer[]>;
-    /**
-     * Internal method to call locations API.
-     */
+    getProxyExpiration(ips: string | string[], proxyType: 1 | 2): Promise<Record<string, unknown>>;
     private getLocations;
-    /**
-     * List all supported countries for a proxy type.
-     */
     listCountries(proxyType?: ProxyTypeParam): Promise<CountryInfo[]>;
-    /**
-     * List states/regions for a country.
-     */
     listStates(countryCode: string, proxyType?: ProxyTypeParam): Promise<StateInfo[]>;
-    /**
-     * List cities for a country (and optionally state).
-     */
     listCities(countryCode: string, stateCode?: string, proxyType?: ProxyTypeParam): Promise<CityInfo[]>;
-    /**
-     * List ASNs for a country.
-     */
     listAsns(countryCode: string, proxyType?: ProxyTypeParam): Promise<AsnInfo[]>;
 }
+//# sourceMappingURL=client.d.ts.map

package/dist/src/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}