thordata-js-sdk 0.2.0 → 0.4.0

package/LICENSE

@@ -1,21 +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
+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

@@ -1,18 +1,17 @@
 # Thordata JS SDK (Node.js / TypeScript)
 
-Official JavaScript/TypeScript SDK for <!--citation:1-->.
+Official JavaScript/TypeScript SDK for Thordata APIs.
 
-This SDK supports:
+[![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)
 
-- **SERP API** (Google / Bing / Yandex / DuckDuckGo / Baidu)
-- **Web Unlocker / Universal API**
-- **Web Scraper API** (task-based scraping)
+Supports:
 
-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)
+- **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)
 
 ---
 
@@ -22,403 +21,110 @@ It is designed to be:
 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_SCRAPER_TOKEN=your_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,
-});
-```
+import { Thordata } from "thordata-js-sdk";
 
-#### Alternative: Google generic engine + tbm (via searchType):
+const client = new Thordata(); // Reads from env vars
 
-```typescript
-const data = await client.serpSearch({
-  query: "iPhone 15",
+// SERP Search
+const results = await client.serpSearch({
+  query: "Thordata SDK",
   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
-
----
-
-## 🌐 Proxy Network
-
-Each proxy product requires separate credentials from Thordata Dashboard.
-
-### Environment Variables
-
-```env
-# Residential Proxy (port 9999)
-THORDATA_RESIDENTIAL_USERNAME=your_residential_username
-THORDATA_RESIDENTIAL_PASSWORD=your_residential_password
-
-# Datacenter Proxy (port 7777)
-THORDATA_DATACENTER_USERNAME=your_datacenter_username
-THORDATA_DATACENTER_PASSWORD=your_datacenter_password
-
-# Mobile Proxy (port 5555)
-THORDATA_MOBILE_USERNAME=your_mobile_username
-THORDATA_MOBILE_PASSWORD=your_mobile_password
-
-# Static ISP Proxy (port 6666, direct IP connection)
-THORDATA_ISP_HOST=your_static_ip_address
-THORDATA_ISP_USERNAME=your_isp_username
-THORDATA_ISP_PASSWORD=your_isp_password
-```
-
-### Residential Proxy
-
-```typescript
-import { Thordata } from "thordata-js-sdk";
-
-const client = new Thordata();
-
-// Basic US residential
-const proxy = Thordata.Proxy.residentialFromEnv().country("us");
-const result = await client.request("http://httpbin.org/ip", { proxy });
-console.log("IP:", result.origin);
-
-// Sticky session (same IP for 30 minutes)
-const stickyProxy = Thordata.Proxy.residentialFromEnv()
-  .country("jp")
-  .city("tokyo")
-  .session("my_session")
-  .sticky(30);
-const result2 = await client.request("http://httpbin.org/ip", { proxy: stickyProxy });
-```
-
-### Datacenter Proxy
-
-```typescript
-const proxy = Thordata.Proxy.datacenterFromEnv();
-const result = await client.request("http://httpbin.org/ip", { proxy });
-console.log("Datacenter IP:", result.origin);
-```
-
-### Mobile Proxy
-
-```typescript
-const proxy = Thordata.Proxy.mobileFromEnv().country("gb");
-const result = await client.request("http://httpbin.org/ip", { proxy });
-console.log("UK Mobile IP:", result.origin);
-```
-
-### Static ISP Proxy
-
-```typescript
-const proxy = Thordata.Proxy.ispFromEnv();
-const result = await client.request("http://httpbin.org/ip", { proxy });
-console.log("Static ISP IP:", result.origin);
-// Returns your purchased static IP address
-```
-
-### Proxy Examples
-
-```bash
-node dist/examples/proxy_residential.js
-node dist/examples/proxy_datacenter.js
-node dist/examples/proxy_mobile.js
-node dist/examples/proxy_isp.js
+console.log(results.organic?.[0]?.link);
 ```
 
 ---
 
-## 🔓 Web Unlocker / Universal API
+## 📖 Features
 
-### Basic HTML scraping
+### SERP API
 
 ```typescript
-const html = await client.universalScrape({
-  url: "https://httpbin.org/html",
-  jsRender: false,
-  outputFormat: "html",
+const news = await client.serpSearch({
+  query: "AI News",
+  engine: "google_news",
+  num: 10,
 });
-
-console.log(String(html).slice(0, 300));
 ```
 
-### JS rendering + wait for selector
+### Web Unlocker (Universal)
 
 ```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",
+  waitFor: ".content",
 });
-
-writeFileSync("screenshot.png", pngBytes as Buffer);
 ```
 
----
-
-## 🕷️ Web Scraper API (Task-based)
-
-Requires `THORDATA_PUBLIC_TOKEN` and `THORDATA_PUBLIC_KEY`.
+### Web Scraper API (Async)
 
 ```typescript
-const client = new ThordataClient({
-  scraperToken: process.env.THORDATA_SCRAPER_TOKEN!,
-  publicToken: process.env.THORDATA_PUBLIC_TOKEN,
-  publicKey: process.env.THORDATA_PUBLIC_KEY,
-});
-
+// Create Task
 const taskId = await client.createScraperTask({
-  fileName: "demo_task",
-  spiderId: "example-spider-id",
-  spiderName: "example.com",
+  fileName: "task1",
+  spiderId: "universal",
+  spiderName: "universal",
   parameters: { url: "https://example.com" },
 });
 
-console.log("Task created:", taskId);
-
-const status = await client.waitForTask(taskId, {
-  pollIntervalMs: 5000,
-  maxWaitMs: 60000,
+// 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("Final status:", status);
-
-if (["ready", "success", "finished"].includes(status.toLowerCase())) {
-  const downloadUrl = await client.getTaskResult(taskId, "json");
-  console.log("Download URL:", downloadUrl);
+// Wait & Result
+const status = await client.waitForTask(taskId);
+if (status === "ready") {
+  const url = await client.getTaskResult(taskId);
+  console.log(url);
 }
 ```
 
----
-
-## 🔧 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:
+### Account Management
 
 ```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);
-  }
-}
-```
+// Usage Stats
+const stats = await client.getUsageStatistics("2024-01-01", "2024-01-31");
+console.log("Balance:", stats.traffic_balance);
 
----
-
-## 🌍 Base URL Overrides (for offline tests / custom routing)
+// Proxy Users
+const users = await client.listProxyUsers("residential");
 
-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
+// Whitelist
+await client.addWhitelistIp("1.2.3.4");
 ```
 
-Or via client config:
+### Proxy Configuration
 
 ```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
+// Residential Proxy
+const proxy = Thordata.Proxy.residentialFromEnv().country("us");
+await client.request("https://httpbin.org/ip", { proxy });
 ```
 
 ---
 
-## 🔮 Roadmap
+## 📄 License
 
-- 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)
-
----
+MIT License

package/dist/examples/basic_scraper_task.js

@@ -5,42 +5,55 @@ async function main() {
     const scraperToken = process.env.THORDATA_SCRAPER_TOKEN;
     const publicToken = process.env.THORDATA_PUBLIC_TOKEN;
     const publicKey = process.env.THORDATA_PUBLIC_KEY;
+    // These are NOT universal constants; users should copy them from Dashboard -> Web Scraper Store -> API Builder.
+    const spiderName = process.env.THORDATA_TASK_SPIDER_NAME;
+    const spiderId = process.env.THORDATA_TASK_SPIDER_ID;
+    const fileName = process.env.THORDATA_TASK_FILE_NAME || "{{TasksID}}";
+    const parametersJson = process.env.THORDATA_TASK_PARAMETERS_JSON || "{}";
     if (!scraperToken || !publicToken || !publicKey) {
         console.error("Please set THORDATA_SCRAPER_TOKEN, THORDATA_PUBLIC_TOKEN, THORDATA_PUBLIC_KEY in .env");
         process.exit(1);
     }
+    // If task-specific env vars are missing, skip the example to keep CI/offline e2e stable.
+    if (!spiderName || !spiderId) {
+        console.log("Skipping tasks example. Set THORDATA_TASK_SPIDER_NAME and THORDATA_TASK_SPIDER_ID to run it (copy from Dashboard -> Web Scraper Store -> API Builder).");
+        return;
+    }
+    let parameters;
+    try {
+        parameters = JSON.parse(parametersJson);
+    }
+    catch {
+        console.error("THORDATA_TASK_PARAMETERS_JSON must be valid JSON");
+        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);
+    console.log("🕷️  Creating Web Scraper task (live example)...");
+    const taskId = await client.createScraperTask({
+        // Recommended by docs: let the server substitute the actual task id.
+        fileName,
+        spiderId,
+        spiderName,
+        parameters,
+    });
+    console.log("Task created:", taskId);
+    console.log("⏱️  Waiting for task completion...");
+    const status = await client.waitForTask(taskId, {
+        pollIntervalMs: 5000,
+        maxWaitMs: 120_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);
     }
 }
 main().catch((err) => {
     console.error("Fatal error:", err);
+    process.exit(1);
 });
 //# sourceMappingURL=basic_scraper_task.js.map

package/dist/examples/basic_scraper_task.js.map

@@ -1 +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"}
+{"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,gHAAgH;IAChH,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC;IACzD,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC;IACrD,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,uBAAuB,IAAI,aAAa,CAAC;IACtE,MAAM,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC,6BAA6B,IAAI,IAAI,CAAC;IAEzE,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,yFAAyF;IACzF,IAAI,CAAC,UAAU,IAAI,CAAC,QAAQ,EAAE,CAAC;QAC7B,OAAO,CAAC,GAAG,CACT,wJAAwJ,CACzJ,CAAC;QACF,OAAO;IACT,CAAC;IAED,IAAI,UAAe,CAAC;IACpB,IAAI,CAAC;QACH,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;IAC1C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,KAAK,CAAC,kDAAkD,CAAC,CAAC;QAClE,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,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC;QAC5C,qEAAqE;QACrE,QAAQ;QACR,QAAQ;QACR,UAAU;QACV,UAAU;KACX,CAAC,CAAC;IAEH,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;IAErC,OAAO,CAAC,GAAG,CAAC,oCAAoC,CAAC,CAAC;IAClD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,MAAM,EAAE;QAC9C,cAAc,EAAE,IAAI;QACpB,SAAS,EAAE,OAAO;KACnB,CAAC,CAAC;IAEH,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;IAErC,IAAI,MAAM,CAAC,WAAW,EAAE,KAAK,OAAO,IAAI,MAAM,CAAC,WAAW,EAAE,KAAK,SAAS,EAAE,CAAC;QAC3E,MAAM,WAAW,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/D,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,WAAW,CAAC,CAAC;IAC5C,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;IACnC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/examples/basic_serp.js

@@ -14,10 +14,10 @@ async function main() {
         engine: Engine.GOOGLE,
         num: 5,
     });
-    // 调试用：看真实返回结构
+    // Debug: show actual response structure
     console.dir(results, { depth: 4 });
-    // 优先找 'organic'，其次才是 'organic_results'
-    const organic = results?.organic ?? results?.organic_results ?? [];
+    // Type-safe access with fallback
+    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);

package/dist/examples/basic_serp.js.map

@@ -1 +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"}
+{"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,wCAAwC;IACxC,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;IAEnC,iCAAiC;IACjC,MAAM,OAAO,GAAG,CAAC,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,eAAe,IAAI,EAAE,CAGjE,CAAC;IACH,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"}