thordata-js-sdk 0.2.0 → 0.3.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,20 @@
 # Thordata JS SDK (Node.js / TypeScript)
 
-Official JavaScript/TypeScript SDK for <!--citation:1-->.
+Official JavaScript/TypeScript SDK for Thordata APIs.
 
 This SDK supports:
 
-- **SERP API** (Google / Bing / Yandex / DuckDuckGo / Baidu)
+- **SERP API** (Google / Bing / Yandex / DuckDuckGo)
 - **Web Unlocker / Universal API**
 - **Web Scraper API** (task-based scraping)
+- **Proxy Network** (Residential / Datacenter / Mobile / ISP)
+- **Location API** (Geo-targeting options)
 
 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)
+- **TypeScript-first** with full type definitions
+- **ESM-ready** with CommonJS fallback
+- **Offline-test friendly** (base URLs can be overridden)
 
 ---
 
@@ -22,7 +24,7 @@ It is designed to be:
 npm install thordata-js-sdk
 ```
 
-If you are developing locally:
+For local development:
 
 ```bash
 git clone https://github.com/Thordata/thordata-js-sdk.git
@@ -38,15 +40,15 @@ npm run build
 Set environment variables:
 
 ```bash
-export THORDATA_SCRAPER_TOKEN=your_scraper_token
+export THORDATA_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):
+Or create a `.env` file:
 
 ```env
-THORDATA_SCRAPER_TOKEN=your_scraper_token
+THORDATA_TOKEN=your_scraper_token
 THORDATA_PUBLIC_TOKEN=your_public_token
 THORDATA_PUBLIC_KEY=your_public_key
 ```
@@ -55,95 +57,193 @@ THORDATA_PUBLIC_KEY=your_public_key
 
 ## 🚀 Quick Start
 
-### Create a client
+Create a client:
 
 ```typescript
 import { ThordataClient } from "thordata-js-sdk";
 
 const client = new ThordataClient({
-  scraperToken: process.env.THORDATA_SCRAPER_TOKEN!,
+  scraperToken: process.env.THORDATA_TOKEN!,
   publicToken: process.env.THORDATA_PUBLIC_TOKEN,
   publicKey: process.env.THORDATA_PUBLIC_KEY,
 });
 ```
 
+Or use the convenience wrapper:
+
+```typescript
+import { Thordata } from "thordata-js-sdk";
+
+// Automatically reads from environment variables
+const client = new Thordata();
+```
+
 ---
 
 ## 🔍 SERP API
 
-### Basic Google Search
+### Supported Engines
+
+| Engine     | Identifier | Notes                  |
+| ---------- | ---------- | ---------------------- |
+| Google     | google     | Base web search        |
+| Bing       | bing       | Base web search        |
+| Yandex     | yandex     | Uses text instead of q |
+| DuckDuckGo | duckduckgo | Base web search        |
+
+### Google Specialized Engines
+
+For Google verticals, use dedicated engines for best results:
+
+| Engine          | Identifier      |
+| --------------- | --------------- |
+| Google News     | google_news     |
+| Google Shopping | google_shopping |
+| Google Images   | google_images   |
+| Google Videos   | google_videos   |
+| Google Maps     | google_maps     |
+| Google Scholar  | google_scholar  |
+| Google Patents  | google_patents  |
+| Google Jobs     | google_jobs     |
+| Google Flights  | google_flights  |
+| Google Finance  | google_finance  |
+| Google Product  | google_product  |
+
+### Basic Search
 
 ```typescript
 import { ThordataClient, Engine } from "thordata-js-sdk";
 
-const client = new ThordataClient({ scraperToken: process.env.THORDATA_SCRAPER_TOKEN! });
+const client = new ThordataClient({ scraperToken: process.env.THORDATA_TOKEN! });
 
 const data = await client.serpSearch({
   query: "Thordata proxy network",
   engine: Engine.GOOGLE,
-  num: 5,
+  country: "us",
+  language: "en",
+  num: 10,
 });
 
 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):
+### Google News (Recommended: Dedicated Engine)
 
 ```typescript
-const data = await client.serpSearch({
+const news = await client.serpSearch({
   query: "AI regulation",
-  engine: "google_news",
+  engine: Engine.GOOGLE_NEWS,
   country: "us",
   language: "en",
   num: 10,
-  so: 1, // 0=relevance, 1=date (Google News)
 });
 ```
 
-#### Google Shopping (recommended):
+### Google Shopping
 
 ```typescript
-const data = await client.serpSearch({
+const shopping = await client.serpSearch({
   query: "iPhone 15",
-  engine: "google_shopping",
+  engine: Engine.GOOGLE_SHOPPING,
   country: "us",
   language: "en",
   num: 10,
-  min_price: 500,
-  max_price: 1500,
 });
 ```
 
-#### Alternative: Google generic engine + tbm (via searchType):
+### Alternative: Using tbm Parameter
+
+For some Google engines, you can also use the searchType (tbm) parameter:
 
 ```typescript
-const data = await client.serpSearch({
-  query: "iPhone 15",
-  engine: "google",
-  searchType: "shopping", // maps to tbm=shop
-  country: "us",
-  language: "en",
-  num: 10,
+import { GoogleTbm } from "thordata-js-sdk";
+
+const images = await client.serpSearch({
+  query: "cats",
+  engine: Engine.GOOGLE,
+  searchType: GoogleTbm.IMAGES, // or just "isch"
+});
+```
+
+> **Note:** Using dedicated engines (e.g., `Engine.GOOGLE_NEWS`) is recommended over `Engine.GOOGLE + searchType` for clearer parameter contracts.
+
+---
+
+## 🌐 Web Unlocker / Universal API
+
+### Supported Output Formats
+
+| Format | Description            |
+| ------ | ---------------------- |
+| html   | HTML content (default) |
+| png    | PNG screenshot         |
+
+### 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", // Wait for element to appear
+});
+```
+
+### Block Resources for Performance
+
+```typescript
+const html = await client.universalScrape({
+  url: "https://example.com",
+  jsRender: true,
+  blockResources: "image,media", // Block images and media
+  cleanContent: "js,css", // Remove JS and CSS from output
 });
 ```
 
-Official and up-to-date parameters are documented at: https://doc.thordata.com
+### 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);
+```
+
+### Custom Headers and Cookies
+
+```typescript
+const html = await client.universalScrape({
+  url: "https://example.com/account",
+  jsRender: true,
+  headers: [
+    { name: "User-Agent", value: "Mozilla/5.0 (ThordataBot)" },
+    { name: "Accept-Language", value: "en-US,en;q=0.9" },
+  ],
+  cookies: [{ name: "sessionid", value: "abc123" }],
+});
+```
 
 ---
 
-## 🌐 Proxy Network
+## 🌍 Proxy Network
 
 Each proxy product requires separate credentials from Thordata Dashboard.
 
@@ -162,7 +262,7 @@ THORDATA_DATACENTER_PASSWORD=your_datacenter_password
 THORDATA_MOBILE_USERNAME=your_mobile_username
 THORDATA_MOBILE_PASSWORD=your_mobile_password
 
-# Static ISP Proxy (port 6666, direct IP connection)
+# Static ISP Proxy (port 6666)
 THORDATA_ISP_HOST=your_static_ip_address
 THORDATA_ISP_USERNAME=your_isp_username
 THORDATA_ISP_PASSWORD=your_isp_password
@@ -186,7 +286,6 @@ const stickyProxy = Thordata.Proxy.residentialFromEnv()
   .city("tokyo")
   .session("my_session")
   .sticky(30);
-const result2 = await client.request("http://httpbin.org/ip", { proxy: stickyProxy });
 ```
 
 ### Datacenter Proxy
@@ -194,7 +293,6 @@ const result2 = await client.request("http://httpbin.org/ip", { proxy: stickyPro
 ```typescript
 const proxy = Thordata.Proxy.datacenterFromEnv();
 const result = await client.request("http://httpbin.org/ip", { proxy });
-console.log("Datacenter IP:", result.origin);
 ```
 
 ### Mobile Proxy
@@ -202,7 +300,6 @@ console.log("Datacenter IP:", result.origin);
 ```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
@@ -210,58 +307,49 @@ console.log("UK Mobile IP:", result.origin);
 ```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
 ```
 
 ---
 
-## 🔓 Web Unlocker / Universal API
+## 📍 Location API
 
-### Basic HTML scraping
+Query available geo-targeting options. Requires `THORDATA_PUBLIC_TOKEN` and `THORDATA_PUBLIC_KEY`.
+
+### List Countries
 
 ```typescript
-const html = await client.universalScrape({
-  url: "https://httpbin.org/html",
-  jsRender: false,
-  outputFormat: "html",
-});
+// Using string parameter (recommended)
+const countries = await client.listCountries("residential");
 
-console.log(String(html).slice(0, 300));
+// Or numeric parameter (1 = residential, 2 = unlimited)
+const countries2 = await client.listCountries(1);
+
+console.log(`Found ${countries.length} countries`);
+// [{ country_code: "US", country_name: "United States" }, ...]
 ```
 
-### JS rendering + wait for selector
+### List States
 
 ```typescript
-const html = await client.universalScrape({
-  url: "https://example.com/spa",
-  jsRender: true,
-  outputFormat: "html",
-  waitFor: ".main-content",
-});
+const states = await client.listStates("US", "residential");
+console.log(`Found ${states.length} states`);
+// [{ state_code: "california", state_name: "California" }, ...]
 ```
 
-### Screenshot (PNG)
+### List Cities
 
 ```typescript
-import { writeFileSync } from "node:fs";
+const cities = await client.listCities("US", "california", "residential");
+console.log(`Found ${cities.length} cities`);
+// [{ city_name: "Los Angeles" }, { city_name: "San Francisco" }, ...]
+```
 
-const pngBytes = await client.universalScrape({
-  url: "https://example.com",
-  jsRender: true,
-  outputFormat: "png",
-});
+### List ASNs
 
-writeFileSync("screenshot.png", pngBytes as Buffer);
+```typescript
+const asns = await client.listAsns("US", "residential");
+console.log(`Found ${asns.length} ASNs`);
+// [{ asn_code: "AS7922", asn_name: "Comcast" }, ...]
 ```
 
 ---
@@ -272,11 +360,12 @@ Requires `THORDATA_PUBLIC_TOKEN` and `THORDATA_PUBLIC_KEY`.
 
 ```typescript
 const client = new ThordataClient({
-  scraperToken: process.env.THORDATA_SCRAPER_TOKEN!,
+  scraperToken: process.env.THORDATA_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",
@@ -286,6 +375,7 @@ const taskId = await client.createScraperTask({
 
 console.log("Task created:", taskId);
 
+// Wait for completion
 const status = await client.waitForTask(taskId, {
   pollIntervalMs: 5000,
   maxWaitMs: 60000,
@@ -293,6 +383,7 @@ const status = await client.waitForTask(taskId, {
 
 console.log("Final status:", status);
 
+// Download results
 if (["ready", "success", "finished"].includes(status.toLowerCase())) {
   const downloadUrl = await client.getTaskResult(taskId, "json");
   console.log("Download URL:", downloadUrl);
@@ -301,20 +392,22 @@ if (["ready", "success", "finished"].includes(status.toLowerCase())) {
 
 ---
 
-## 🔧 Errors & Response Codes
+## 🔧 Error Handling
+
+The SDK throws typed errors based on API response codes:
 
-The SDK throws typed errors when the API returns a non-success code (or non-2xx HTTP status).
+| Code    | Meaning       | Error Class               |
+| ------- | ------------- | ------------------------- |
+| 200     | Success       | -                         |
+| 300     | Not collected | ThordataNotCollectedError |
+| 400     | Bad request   | ThordataValidationError   |
+| 401/403 | Auth error    | ThordataAuthError         |
+| 402/429 | Rate limit    | ThordataRateLimitError    |
+| 5xx     | Server error  | ThordataServerError       |
 
-| 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` |
+> **Billing Note:** Only requests with code == 200 are billed.
 
-### Example error handling:
+### Example
 
 ```typescript
 import {
@@ -344,18 +437,37 @@ try {
 
 ---
 
-## 🌍 Base URL Overrides (for offline tests / custom routing)
+## ⚙️ Advanced Configuration
 
-You can override API base URLs via environment variables:
+### SSL Verification
+
+```typescript
+const client = new ThordataClient({
+  scraperToken: process.env.THORDATA_TOKEN!,
+  verifySsl: false, // Only for testing with self-signed certs
+});
+```
+
+### Retry Configuration
+
+```typescript
+const client = new ThordataClient({
+  scraperToken: process.env.THORDATA_TOKEN!,
+  maxRetries: 3, // Retry up to 3 times on transient failures
+  timeoutMs: 60000, // 60 second timeout
+});
+```
+
+### Base URL Overrides
+
+For testing or custom routing:
 
 ```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:
+Or via config:
 
 ```typescript
 const client = new ThordataClient({
@@ -372,9 +484,11 @@ const client = new ThordataClient({
 npm install
 npm run build
 npm test
+npm run lint
+npm run format
 ```
 
-### Run examples (compiled):
+### Run Examples
 
 ```bash
 node dist/examples/basic_serp.js
@@ -388,37 +502,35 @@ node dist/examples/basic_universal.js
 ```
 thordata-js-sdk/
 ├── src/
-│   ├── index.ts
-│   ├── client.ts
-│   ├── models.ts
-│   ├── enums.ts
-│   ├── errors.ts
-│   ├── retry.ts
-│   ├── endpoints.ts
-│   └── utils.ts
+│   ├── index.ts        # Main exports
+│   ├── client.ts       # ThordataClient class
+│   ├── thordata.ts     # Convenience wrapper
+│   ├── proxy.ts        # Proxy configuration
+│   ├── models.ts       # TypeScript interfaces
+│   ├── enums.ts        # Enumerations
+│   ├── errors.ts       # Error classes
+│   ├── utils.ts        # Helper functions
+│   └── endpoints.ts    # API endpoints
 ├── 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
+## 📚 API Reference
+
+For detailed API documentation, visit:
 
-- 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)
+- [Google Search Parameters](#)
+- [Google News Parameters](#)
+- [Google Shopping Parameters](#)
+- [Yandex Parameters](#)
+- [Universal API Parameters](#)
 
 ---
+
+## 📄 License
+
+MIT License - see LICENSE for details.

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

package/dist/examples/location_api.js

@@ -0,0 +1,47 @@
+// examples/location_api.ts
+import "dotenv/config";
+import { Thordata } from "../src/thordata.js";
+async function main() {
+    if (!process.env.THORDATA_PUBLIC_TOKEN || !process.env.THORDATA_PUBLIC_KEY) {
+        console.log("Location API Demo - Skipped");
+        console.log("Set THORDATA_PUBLIC_TOKEN and THORDATA_PUBLIC_KEY in .env");
+        return;
+    }
+    const client = new Thordata();
+    console.log("Location API Demo\n");
+    // List countries (now using string parameter)
+    console.log("1. Listing countries...");
+    const countries = await client.listCountries("residential");
+    console.log(`   Found ${countries.length} countries`);
+    console.log(`   First 5: ${countries
+        .slice(0, 5)
+        .map((c) => c.country_code)
+        .join(", ")}`);
+    // List states for US
+    console.log("\n2. Listing US states...");
+    const states = await client.listStates("US", "residential");
+    console.log(`   Found ${states.length} states`);
+    console.log(`   First 5: ${states
+        .slice(0, 5)
+        .map((s) => s.state_name)
+        .join(", ")}`);
+    // List cities for California
+    console.log("\n3. Listing California cities...");
+    const cities = await client.listCities("US", "california", "residential");
+    console.log(`   Found ${cities.length} cities`);
+    console.log(`   First 5: ${cities
+        .slice(0, 5)
+        .map((c) => c.city_name)
+        .join(", ")}`);
+    // List ASNs for US
+    console.log("\n4. Listing US ASNs...");
+    const asns = await client.listAsns("US", "residential");
+    console.log(`   Found ${asns.length} ASNs`);
+    console.log(`   First 3: ${asns
+        .slice(0, 3)
+        .map((a) => `${a.asn_code}: ${a.asn_name}`)
+        .join(", ")}`);
+    console.log("\nLocation API demo completed.");
+}
+main().catch(console.error);
+//# sourceMappingURL=location_api.js.map