thordata-sdk 0.7.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

thordata/client.py

@@ -25,13 +25,18 @@ from __future__ import annotations
 
 import logging
 import os
+import ssl
+from datetime import date
 from typing import Any, Dict, List, Optional, Union
+from urllib.parse import urlencode
 
 import requests
+import urllib3
 
 from . import __version__ as _sdk_version
 from ._utils import (
     build_auth_headers,
+    build_builder_headers,
     build_public_api_headers,
     build_user_agent,
     decode_base64_image,
@@ -46,11 +51,17 @@ from .exceptions import (
     raise_for_code,
 )
 from .models import (
+    CommonSettings,
     ProxyConfig,
     ProxyProduct,
+    ProxyServer,
+    ProxyUserList,
     ScraperTaskConfig,
     SerpRequest,
     UniversalScrapeRequest,
+    UsageStatistics,
+    VideoTaskConfig,
+    WhitelistProxyConfig,
 )
 from .retry import RetryConfig, with_retry
 
@@ -87,8 +98,8 @@ class ThordataClient:
     # API Endpoints
     BASE_URL = "https://scraperapi.thordata.com"
     UNIVERSAL_URL = "https://universalapi.thordata.com"
-    API_URL = "https://api.thordata.com/api/web-scraper-api"
-    LOCATIONS_URL = "https://api.thordata.com/api/locations"
+    API_URL = "https://openapi.thordata.com/api/web-scraper-api"
+    LOCATIONS_URL = "https://openapi.thordata.com/api/locations"
 
     def __init__(
         self,
@@ -98,7 +109,9 @@ class ThordataClient:
         proxy_host: str = "pr.thordata.net",
         proxy_port: int = 9999,
         timeout: int = 30,
+        api_timeout: int = 60,
         retry_config: Optional[RetryConfig] = None,
+        auth_mode: str = "bearer",
         scraperapi_base_url: Optional[str] = None,
         universalapi_base_url: Optional[str] = None,
         web_scraper_api_base_url: Optional[str] = None,
@@ -108,6 +121,7 @@ class ThordataClient:
         if not scraper_token:
             raise ThordataConfigError("scraper_token is required")
 
+        # Core credentials
         self.scraper_token = scraper_token
         self.public_token = public_token
         self.public_key = public_key
@@ -115,17 +129,22 @@ class ThordataClient:
         # Proxy configuration
         self._proxy_host = proxy_host
         self._proxy_port = proxy_port
+
+        # Timeout configuration
         self._default_timeout = timeout
+        self._api_timeout = api_timeout
 
         # Retry configuration
         self._retry_config = retry_config or RetryConfig()
 
-        # Build default proxy URL (for basic usage)
-        self._default_proxy_url = (
-            f"http://td-customer-{self.scraper_token}:@{proxy_host}:{proxy_port}"
-        )
+        # Authentication mode (for scraping APIs)
+        self._auth_mode = auth_mode.lower()
+        if self._auth_mode not in ("bearer", "header_token"):
+            raise ThordataConfigError(
+                f"Invalid auth_mode: {auth_mode}. Must be 'bearer' or 'header_token'."
+            )
 
-        # Sessions:
+        # NOTE:
         # - _proxy_session: used for proxy network traffic to target sites
         # - _api_session: used for Thordata APIs (SERP/Universal/Tasks/Locations)
         #
@@ -133,14 +152,9 @@ class ThordataClient:
         # so developers can rely on system proxy settings (e.g., Clash) via env vars.
         self._proxy_session = requests.Session()
         self._proxy_session.trust_env = False
-        self._proxy_session.proxies = {
-            "http": self._default_proxy_url,
-            "https": self._default_proxy_url,
-        }
 
         self._api_session = requests.Session()
         self._api_session.trust_env = True
-
         self._api_session.headers.update(
             {"User-Agent": build_user_agent(_sdk_version, "requests")}
         )
@@ -170,17 +184,49 @@ class ThordataClient:
             or self.LOCATIONS_URL
         ).rstrip("/")
 
+        # These URLs exist in your codebase; keep them for now (even if your org later migrates fully to openapi)
+        gateway_base = os.getenv(
+            "THORDATA_GATEWAY_BASE_URL", "https://api.thordata.com/api/gateway"
+        )
+        child_base = os.getenv(
+            "THORDATA_CHILD_BASE_URL", "https://api.thordata.com/api/child"
+        )
+        self._gateway_base_url = gateway_base
+        self._child_base_url = child_base
+
         self._serp_url = f"{scraperapi_base}/request"
         self._builder_url = f"{scraperapi_base}/builder"
+        self._video_builder_url = f"{scraperapi_base}/video_builder"
         self._universal_url = f"{universalapi_base}/request"
+
         self._status_url = f"{web_scraper_api_base}/tasks-status"
         self._download_url = f"{web_scraper_api_base}/tasks-download"
+        self._list_url = f"{web_scraper_api_base}/tasks-list"
+
         self._locations_base_url = locations_base
 
+        # These 2 lines keep your existing behavior (derive account endpoints from locations_base)
+        self._usage_stats_url = (
+            f"{locations_base.replace('/locations', '')}/account/usage-statistics"
+        )
+        self._proxy_users_url = (
+            f"{locations_base.replace('/locations', '')}/proxy-users"
+        )
+
+        whitelist_base = os.getenv(
+            "THORDATA_WHITELIST_BASE_URL", "https://api.thordata.com/api"
+        )
+        self._whitelist_url = f"{whitelist_base}/whitelisted-ips"
+
+        proxy_api_base = os.getenv(
+            "THORDATA_PROXY_API_BASE_URL", "https://api.thordata.com/api"
+        )
+        self._proxy_list_url = f"{proxy_api_base}/proxy/proxy-list"
+        self._proxy_expiration_url = f"{proxy_api_base}/proxy/expiration-time"
+
     # =========================================================================
-    # Proxy Network Methods
+    # Proxy Network Methods (Pure proxy network request functions)
     # =========================================================================
-
     def get(
         self,
         url: str,
@@ -219,11 +265,37 @@ class ThordataClient:
 
         timeout = timeout or self._default_timeout
 
-        if proxy_config:
-            proxies = proxy_config.to_proxies_dict()
-            kwargs["proxies"] = proxies
+        if proxy_config is None:
+            proxy_config = self._get_default_proxy_config_from_env()
+
+        if proxy_config is None:
+            raise ThordataConfigError(
+                "Proxy credentials are missing. "
+                "Pass proxy_config=ProxyConfig(username=..., password=..., product=...) "
+                "or set THORDATA_RESIDENTIAL_USERNAME/THORDATA_RESIDENTIAL_PASSWORD (or DATACENTER/MOBILE)."
+            )
+
+        kwargs["proxies"] = proxy_config.to_proxies_dict()
+
+        @with_retry(self._retry_config)
+        def _do() -> requests.Response:
+            return self._proxy_request_with_proxy_manager(
+                "GET",
+                url,
+                proxy_config=proxy_config,
+                timeout=timeout,
+                headers=kwargs.pop("headers", None),
+                params=kwargs.pop("params", None),
+            )
 
-        return self._request_with_retry("GET", url, timeout=timeout, **kwargs)
+        try:
+            return _do()
+        except requests.Timeout as e:
+            raise ThordataTimeoutError(
+                f"Request timed out: {e}", original_error=e
+            ) from e
+        except Exception as e:
+            raise ThordataNetworkError(f"Request failed: {e}", original_error=e) from e
 
     def post(
         self,
@@ -249,14 +321,43 @@ class ThordataClient:
 
         timeout = timeout or self._default_timeout
 
-        if proxy_config:
-            proxies = proxy_config.to_proxies_dict()
-            kwargs["proxies"] = proxies
+        if proxy_config is None:
+            proxy_config = self._get_default_proxy_config_from_env()
+
+        if proxy_config is None:
+            raise ThordataConfigError(
+                "Proxy credentials are missing. "
+                "Pass proxy_config=ProxyConfig(username=..., password=..., product=...) "
+                "or set THORDATA_RESIDENTIAL_USERNAME/THORDATA_RESIDENTIAL_PASSWORD (or DATACENTER/MOBILE)."
+            )
 
-        return self._request_with_retry("POST", url, timeout=timeout, **kwargs)
+        kwargs["proxies"] = proxy_config.to_proxies_dict()
+
+        @with_retry(self._retry_config)
+        def _do() -> requests.Response:
+            return self._proxy_request_with_proxy_manager(
+                "POST",
+                url,
+                proxy_config=proxy_config,
+                timeout=timeout,
+                headers=kwargs.pop("headers", None),
+                params=kwargs.pop("params", None),
+                data=kwargs.pop("data", None),
+            )
+
+        try:
+            return _do()
+        except requests.Timeout as e:
+            raise ThordataTimeoutError(
+                f"Request timed out: {e}", original_error=e
+            ) from e
+        except Exception as e:
+            raise ThordataNetworkError(f"Request failed: {e}", original_error=e) from e
 
     def build_proxy_url(
         self,
+        username: str,  # Required
+        password: str,  # Required
         *,
         country: Optional[str] = None,
         state: Optional[str] = None,
@@ -288,8 +389,8 @@ class ThordataClient:
             >>> requests.get("https://example.com", proxies=proxies)
         """
         config = ProxyConfig(
-            username=self.scraper_token,
-            password="",
+            username=username,
+            password=password,
             host=self._proxy_host,
             port=self._proxy_port,
             product=product,
@@ -302,9 +403,44 @@ class ThordataClient:
         return config.build_proxy_url()
 
     # =========================================================================
-    # SERP API Methods
+    # Internal API Request Retry Helper (For all API calls)
     # =========================================================================
+    def _api_request_with_retry(
+        self,
+        method: str,
+        url: str,
+        *,
+        data: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> requests.Response:
+        """Make an API request with automatic retry on transient failures."""
+
+        @with_retry(self._retry_config)
+        def _do_request() -> requests.Response:
+            return self._api_session.request(
+                method,
+                url,
+                data=data,
+                headers=headers,
+                params=params,
+                timeout=self._api_timeout,
+            )
+
+        try:
+            return _do_request()
+        except requests.Timeout as e:
+            raise ThordataTimeoutError(
+                f"API request timed out: {e}", original_error=e
+            ) from e
+        except requests.RequestException as e:
+            raise ThordataNetworkError(
+                f"API request failed: {e}", original_error=e
+            ) from e
 
+    # =========================================================================
+    # SERP API Methods (Search Engine Results Page functions)
+    # =========================================================================
     def serp_search(
         self,
         query: str,
@@ -375,16 +511,18 @@ class ThordataClient:
         )
 
         payload = request.to_payload()
-        headers = build_auth_headers(self.scraper_token)
+        headers = build_auth_headers(self.scraper_token, mode=self._auth_mode)
 
-        logger.info(f"SERP Search: {engine_str} - {query}")
+        logger.info(
+            f"SERP Search: {engine_str} - {query[:50]}{'...' if len(query) > 50 else ''}"
+        )
 
         try:
-            response = self._api_session.post(
+            response = self._api_request_with_retry(
+                "POST",
                 self._serp_url,
                 data=payload,
                 headers=headers,
-                timeout=60,
             )
             response.raise_for_status()
 
@@ -445,16 +583,18 @@ class ThordataClient:
             >>> results = client.serp_search_advanced(request)
         """
         payload = request.to_payload()
-        headers = build_auth_headers(self.scraper_token)
+        headers = build_auth_headers(self.scraper_token, mode=self._auth_mode)
 
-        logger.info(f"SERP Advanced Search: {request.engine} - {request.query}")
+        logger.info(
+            f"SERP Advanced Search: {request.engine} - {request.query[:50]}{'...' if len(request.query) > 50 else ''}"
+        )
 
         try:
-            response = self._api_session.post(
+            response = self._api_request_with_retry(
+                "POST",
                 self._serp_url,
                 data=payload,
                 headers=headers,
-                timeout=60,
             )
             response.raise_for_status()
 
@@ -487,9 +627,8 @@ class ThordataClient:
             ) from e
 
     # =========================================================================
-    # Universal Scraping API (Web Unlocker) Methods
+    # Universal Scraping API Methods (Web Unlocker functions)
     # =========================================================================
-
     def universal_scrape(
         self,
         url: str,
@@ -559,18 +698,18 @@ class ThordataClient:
             HTML string or PNG bytes.
         """
         payload = request.to_payload()
-        headers = build_auth_headers(self.scraper_token)
+        headers = build_auth_headers(self.scraper_token, mode=self._auth_mode)
 
         logger.info(
             f"Universal Scrape: {request.url} (format: {request.output_format})"
         )
 
         try:
-            response = self._api_session.post(
+            response = self._api_request_with_retry(
+                "POST",
                 self._universal_url,
                 data=payload,
                 headers=headers,
-                timeout=60,
             )
             response.raise_for_status()
 
@@ -619,9 +758,8 @@ class ThordataClient:
         return str(resp_json)
 
     # =========================================================================
-    # Web Scraper API (Task-based) Methods
+    # Web Scraper API Methods (Only async task management functions)
     # =========================================================================
-
     def create_scraper_task(
         self,
         file_name: str,
@@ -673,17 +811,25 @@ class ThordataClient:
         Returns:
             The created task_id.
         """
+        self._require_public_credentials()
+
         payload = config.to_payload()
-        headers = build_auth_headers(self.scraper_token)
+
+        # Builder needs 3 headers: token, key, Authorization Bearer
+        headers = build_builder_headers(
+            self.scraper_token,
+            self.public_token or "",
+            self.public_key or "",
+        )
 
         logger.info(f"Creating Scraper Task: {config.spider_name}")
 
         try:
-            response = self._api_session.post(
+            response = self._api_request_with_retry(
+                "POST",
                 self._builder_url,
                 data=payload,
                 headers=headers,
-                timeout=30,
             )
             response.raise_for_status()
 
@@ -701,6 +847,94 @@ class ThordataClient:
                 f"Task creation failed: {e}", original_error=e
             ) from e
 
+    def create_video_task(
+        self,
+        file_name: str,
+        spider_id: str,
+        spider_name: str,
+        parameters: Dict[str, Any],
+        common_settings: "CommonSettings",
+    ) -> str:
+        """
+        Create a YouTube video/audio download task.
+
+        Uses the /video_builder endpoint.
+
+        Args:
+            file_name: Output file name. Supports {{TasksID}}, {{VideoID}}.
+            spider_id: Spider identifier (e.g., "youtube_video_by-url").
+            spider_name: Spider name (typically "youtube.com").
+            parameters: Spider parameters (e.g., {"url": "..."}).
+            common_settings: Video/audio settings.
+
+        Returns:
+            The created task_id.
+
+        Example:
+            >>> from thordata import CommonSettings
+            >>> task_id = client.create_video_task(
+            ...     file_name="{{VideoID}}",
+            ...     spider_id="youtube_video_by-url",
+            ...     spider_name="youtube.com",
+            ...     parameters={"url": "https://youtube.com/watch?v=xxx"},
+            ...     common_settings=CommonSettings(
+            ...         resolution="1080p",
+            ...         is_subtitles="true"
+            ...     )
+            ... )
+        """
+
+        config = VideoTaskConfig(
+            file_name=file_name,
+            spider_id=spider_id,
+            spider_name=spider_name,
+            parameters=parameters,
+            common_settings=common_settings,
+        )
+
+        return self.create_video_task_advanced(config)
+
+    def create_video_task_advanced(self, config: VideoTaskConfig) -> str:
+        """
+        Create a video task using VideoTaskConfig object.
+
+        Args:
+            config: Video task configuration.
+
+        Returns:
+            The created task_id.
+        """
+
+        self._require_public_credentials()
+
+        payload = config.to_payload()
+        headers = build_builder_headers(
+            self.scraper_token,
+            self.public_token or "",
+            self.public_key or "",
+        )
+
+        logger.info(f"Creating Video Task: {config.spider_name} - {config.spider_id}")
+
+        response = self._api_request_with_retry(
+            "POST",
+            self._video_builder_url,
+            data=payload,
+            headers=headers,
+        )
+        response.raise_for_status()
+
+        data = response.json()
+        code = data.get("code")
+
+        if code != 200:
+            msg = extract_error_message(data)
+            raise_for_code(
+                f"Video task creation failed: {msg}", code=code, payload=data
+            )
+
+        return data["data"]["task_id"]
+
     def get_task_status(self, task_id: str) -> str:
         """
         Check the status of an asynchronous scraping task.
@@ -721,11 +955,11 @@ class ThordataClient:
         payload = {"tasks_ids": task_id}
 
         try:
-            response = self._api_session.post(
+            response = self._api_request_with_retry(
+                "POST",
                 self._status_url,
                 data=payload,
                 headers=headers,
-                timeout=30,
             )
             response.raise_for_status()
             data = response.json()
@@ -788,11 +1022,11 @@ class ThordataClient:
         logger.info(f"Getting result URL for Task: {task_id}")
 
         try:
-            response = self._api_session.post(
+            response = self._api_request_with_retry(
+                "POST",
                 self._download_url,
                 data=payload,
                 headers=headers,
-                timeout=30,
             )
             response.raise_for_status()
 
@@ -812,6 +1046,57 @@ class ThordataClient:
                 f"Get result failed: {e}", original_error=e
             ) from e
 
+    def list_tasks(
+        self,
+        page: int = 1,
+        size: int = 20,
+    ) -> Dict[str, Any]:
+        """
+        List all Web Scraper tasks.
+
+        Args:
+            page: Page number (starts from 1).
+            size: Number of tasks per page.
+
+        Returns:
+            Dict containing 'count' and 'list' of tasks.
+
+        Example:
+            >>> result = client.list_tasks(page=1, size=10)
+            >>> print(f"Total tasks: {result['count']}")
+            >>> for task in result['list']:
+            ...     print(f"Task {task['task_id']}: {task['status']}")
+        """
+        self._require_public_credentials()
+
+        headers = build_public_api_headers(
+            self.public_token or "", self.public_key or ""
+        )
+        payload: Dict[str, Any] = {}
+        if page:
+            payload["page"] = str(page)
+        if size:
+            payload["size"] = str(size)
+
+        logger.info(f"Listing tasks: page={page}, size={size}")
+
+        response = self._api_request_with_retry(
+            "POST",
+            self._list_url,
+            data=payload,
+            headers=headers,
+        )
+        response.raise_for_status()
+
+        data = response.json()
+        code = data.get("code")
+
+        if code != 200:
+            msg = extract_error_message(data)
+            raise_for_code(f"List tasks failed: {msg}", code=code, payload=data)
+
+        return data.get("data", {"count": 0, "list": []})
+
     def wait_for_task(
         self,
         task_id: str,
@@ -865,9 +1150,514 @@ class ThordataClient:
         raise TimeoutError(f"Task {task_id} did not complete within {max_wait} seconds")
 
     # =========================================================================
-    # Location API Methods
+    # Proxy Account Management Methods (Proxy balance, user, whitelist functions)
     # =========================================================================
+    def get_usage_statistics(
+        self,
+        from_date: Union[str, date],
+        to_date: Union[str, date],
+    ) -> UsageStatistics:
+        """
+        Get account usage statistics for a date range.
+
+        Args:
+            from_date: Start date (YYYY-MM-DD string or date object).
+            to_date: End date (YYYY-MM-DD string or date object).
+
+        Returns:
+            UsageStatistics object with traffic data.
+
+        Raises:
+            ValueError: If date range exceeds 180 days.
+
+        Example:
+            >>> from datetime import date, timedelta
+            >>> today = date.today()
+            >>> week_ago = today - timedelta(days=7)
+            >>> stats = client.get_usage_statistics(week_ago, today)
+            >>> print(f"Used: {stats.range_usage_gb():.2f} GB")
+            >>> print(f"Balance: {stats.balance_gb():.2f} GB")
+        """
+
+        self._require_public_credentials()
+
+        # Convert dates to strings
+        if isinstance(from_date, date):
+            from_date = from_date.strftime("%Y-%m-%d")
+        if isinstance(to_date, date):
+            to_date = to_date.strftime("%Y-%m-%d")
+
+        params = {
+            "token": self.public_token,
+            "key": self.public_key,
+            "from_date": from_date,
+            "to_date": to_date,
+        }
+
+        logger.info(f"Getting usage statistics: {from_date} to {to_date}")
+
+        response = self._api_request_with_retry(
+            "GET",
+            self._usage_stats_url,
+            params=params,
+        )
+        response.raise_for_status()
+
+        data = response.json()
+
+        if isinstance(data, dict):
+            code = data.get("code")
+            if code is not None and code != 200:
+                msg = extract_error_message(data)
+                raise_for_code(
+                    f"Usage statistics error: {msg}",
+                    code=code,
+                    payload=data,
+                )
+
+            # Extract data field
+            usage_data = data.get("data", data)
+            return UsageStatistics.from_dict(usage_data)
+
+        raise ThordataNetworkError(
+            f"Unexpected usage statistics response: {type(data).__name__}",
+            original_error=None,
+        )
+
+    def get_residential_balance(self) -> Dict[str, Any]:
+        """
+        Get residential proxy balance.
+
+        Uses public_token/public_key (Dashboard -> My account -> API).
+        """
+        headers = self._build_gateway_headers()
+
+        logger.info("Getting residential proxy balance")
+
+        response = self._api_request_with_retry(
+            "POST",
+            f"{self._gateway_base_url}/getFlowBalance",
+            headers=headers,
+            data={},
+        )
+        response.raise_for_status()
+
+        data = response.json()
+        code = data.get("code")
+
+        if code != 200:
+            msg = extract_error_message(data)
+            raise_for_code(f"Get balance failed: {msg}", code=code, payload=data)
+
+        return data.get("data", {})
+
+    def get_residential_usage(
+        self,
+        start_time: Union[str, int],
+        end_time: Union[str, int],
+    ) -> Dict[str, Any]:
+        """
+        Get residential proxy usage records.
+
+        Uses public_token/public_key (Dashboard -> My account -> API).
+        """
+        headers = self._build_gateway_headers()
+        payload = {"start_time": str(start_time), "end_time": str(end_time)}
+
+        logger.info(f"Getting residential usage: {start_time} to {end_time}")
+
+        response = self._api_request_with_retry(
+            "POST",
+            f"{self._gateway_base_url}/usageRecord",
+            headers=headers,
+            data=payload,
+        )
+        response.raise_for_status()
+
+        data = response.json()
+        code = data.get("code")
 
+        if code != 200:
+            msg = extract_error_message(data)
+            raise_for_code(f"Get usage failed: {msg}", code=code, payload=data)
+
+        return data.get("data", {})
+
+    def list_proxy_users(
+        self, proxy_type: Union[ProxyType, int] = ProxyType.RESIDENTIAL
+    ) -> ProxyUserList:
+        """
+        List all proxy users (sub-accounts).
+
+        Args:
+            proxy_type: Proxy type (1=Residential, 2=Unlimited).
+
+        Returns:
+            ProxyUserList with user details.
+
+        Example:
+            >>> users = client.list_proxy_users(proxy_type=ProxyType.RESIDENTIAL)
+            >>> print(f"Total users: {users.user_count}")
+            >>> for user in users.users:
+            ...     print(f"{user.username}: {user.usage_gb():.2f} GB used")
+        """
+
+        self._require_public_credentials()
+
+        params = {
+            "token": self.public_token,
+            "key": self.public_key,
+            "proxy_type": str(
+                int(proxy_type) if isinstance(proxy_type, ProxyType) else proxy_type
+            ),
+        }
+
+        logger.info(f"Listing proxy users: type={params['proxy_type']}")
+
+        response = self._api_request_with_retry(
+            "GET",
+            f"{self._proxy_users_url}/user-list",
+            params=params,
+        )
+        response.raise_for_status()
+
+        data = response.json()
+
+        if isinstance(data, dict):
+            code = data.get("code")
+            if code is not None and code != 200:
+                msg = extract_error_message(data)
+                raise_for_code(
+                    f"List proxy users error: {msg}", code=code, payload=data
+                )
+
+            user_data = data.get("data", data)
+            return ProxyUserList.from_dict(user_data)
+
+        raise ThordataNetworkError(
+            f"Unexpected proxy users response: {type(data).__name__}",
+            original_error=None,
+        )
+
+    def create_proxy_user(
+        self,
+        username: str,
+        password: str,
+        proxy_type: Union[ProxyType, int] = ProxyType.RESIDENTIAL,
+        traffic_limit: int = 0,
+        status: bool = True,
+    ) -> Dict[str, Any]:
+        """
+        Create a new proxy user (sub-account).
+
+        Args:
+            username: Username for the new user.
+            password: Password for the new user.
+            proxy_type: Proxy type (1=Residential, 2=Unlimited).
+            traffic_limit: Traffic limit in MB (0 = unlimited, min 100).
+            status: Enable/disable user (True/False).
+
+        Returns:
+            API response data.
+
+        Example:
+            >>> result = client.create_proxy_user(
+            ...     username="subuser1",
+            ...     password="securepass",
+            ...     traffic_limit=5120,  # 5GB
+            ...     status=True
+            ... )
+        """
+        self._require_public_credentials()
+
+        headers = build_public_api_headers(
+            self.public_token or "", self.public_key or ""
+        )
+
+        payload = {
+            "proxy_type": str(
+                int(proxy_type) if isinstance(proxy_type, ProxyType) else proxy_type
+            ),
+            "username": username,
+            "password": password,
+            "traffic_limit": str(traffic_limit),
+            "status": "true" if status else "false",
+        }
+
+        logger.info(f"Creating proxy user: {username}")
+
+        response = self._api_request_with_retry(
+            "POST",
+            f"{self._proxy_users_url}/create-user",
+            data=payload,
+            headers=headers,
+        )
+        response.raise_for_status()
+
+        data = response.json()
+        code = data.get("code")
+
+        if code != 200:
+            msg = extract_error_message(data)
+            raise_for_code(f"Create proxy user failed: {msg}", code=code, payload=data)
+
+        return data.get("data", {})
+
+    def add_whitelist_ip(
+        self,
+        ip: str,
+        proxy_type: Union[ProxyType, int] = ProxyType.RESIDENTIAL,
+        status: bool = True,
+    ) -> Dict[str, Any]:
+        """
+        Add an IP to the whitelist for IP authentication.
+
+        Args:
+            ip: IP address to whitelist.
+            proxy_type: Proxy type (1=Residential, 2=Unlimited, 9=Mobile).
+            status: Enable/disable the IP (True/False).
+
+        Returns:
+            API response data.
+
+        Example:
+            >>> result = client.add_whitelist_ip(
+            ...     ip="123.45.67.89",
+            ...     proxy_type=ProxyType.RESIDENTIAL,
+            ...     status=True
+            ... )
+        """
+        self._require_public_credentials()
+
+        headers = build_public_api_headers(
+            self.public_token or "", self.public_key or ""
+        )
+
+        # Convert ProxyType to int
+        proxy_type_int = (
+            int(proxy_type) if isinstance(proxy_type, ProxyType) else proxy_type
+        )
+
+        payload = {
+            "proxy_type": str(proxy_type_int),
+            "ip": ip,
+            "status": "true" if status else "false",
+        }
+
+        logger.info(f"Adding whitelist IP: {ip}")
+
+        response = self._api_request_with_retry(
+            "POST",
+            f"{self._whitelist_url}/add-ip",
+            data=payload,
+            headers=headers,
+        )
+        response.raise_for_status()
+
+        data = response.json()
+        code = data.get("code")
+
+        if code != 200:
+            msg = extract_error_message(data)
+            raise_for_code(f"Add whitelist IP failed: {msg}", code=code, payload=data)
+
+        return data.get("data", {})
+
+    def list_proxy_servers(
+        self,
+        proxy_type: int,
+    ) -> List[ProxyServer]:
+        """
+        List ISP or Datacenter proxy servers.
+
+        Args:
+            proxy_type: Proxy type (1=ISP, 2=Datacenter).
+
+        Returns:
+            List of ProxyServer objects.
+
+        Example:
+            >>> servers = client.list_proxy_servers(proxy_type=1)  # ISP proxies
+            >>> for server in servers:
+            ...     print(f"{server.ip}:{server.port} - expires: {server.expiration_time}")
+        """
+
+        self._require_public_credentials()
+
+        params = {
+            "token": self.public_token,
+            "key": self.public_key,
+            "proxy_type": str(proxy_type),
+        }
+
+        logger.info(f"Listing proxy servers: type={proxy_type}")
+
+        response = self._api_request_with_retry(
+            "GET",
+            self._proxy_list_url,
+            params=params,
+        )
+        response.raise_for_status()
+
+        data = response.json()
+
+        if isinstance(data, dict):
+            code = data.get("code")
+            if code is not None and code != 200:
+                msg = extract_error_message(data)
+                raise_for_code(
+                    f"List proxy servers error: {msg}", code=code, payload=data
+                )
+
+            # Extract list from data field
+            server_list = data.get("data", data.get("list", []))
+        elif isinstance(data, list):
+            server_list = data
+        else:
+            raise ThordataNetworkError(
+                f"Unexpected proxy list response: {type(data).__name__}",
+                original_error=None,
+            )
+
+        return [ProxyServer.from_dict(s) for s in server_list]
+
+    def get_isp_regions(self) -> List[Dict[str, Any]]:
+        """
+        Get available ISP proxy regions.
+
+        Uses public_token/public_key (Dashboard -> My account -> API).
+        """
+        headers = self._build_gateway_headers()
+
+        logger.info("Getting ISP regions")
+
+        response = self._api_request_with_retry(
+            "POST",
+            f"{self._gateway_base_url}/getRegionIsp",
+            headers=headers,
+            data={},
+        )
+        response.raise_for_status()
+
+        data = response.json()
+        code = data.get("code")
+
+        if code != 200:
+            msg = extract_error_message(data)
+            raise_for_code(f"Get ISP regions failed: {msg}", code=code, payload=data)
+
+        return data.get("data", [])
+
+    def list_isp_proxies(self) -> List[Dict[str, Any]]:
+        """
+        List ISP proxies.
+
+        Uses public_token/public_key (Dashboard -> My account -> API).
+        """
+        headers = self._build_gateway_headers()
+
+        logger.info("Listing ISP proxies")
+
+        response = self._api_request_with_retry(
+            "POST",
+            f"{self._gateway_base_url}/queryListIsp",
+            headers=headers,
+            data={},
+        )
+        response.raise_for_status()
+
+        data = response.json()
+        code = data.get("code")
+
+        if code != 200:
+            msg = extract_error_message(data)
+            raise_for_code(f"List ISP proxies failed: {msg}", code=code, payload=data)
+
+        return data.get("data", [])
+
+    def get_wallet_balance(self) -> Dict[str, Any]:
+        """
+        Get wallet balance for ISP proxies.
+
+        Uses public_token/public_key (Dashboard -> My account -> API).
+        """
+        headers = self._build_gateway_headers()
+
+        logger.info("Getting wallet balance")
+
+        response = self._api_request_with_retry(
+            "POST",
+            f"{self._gateway_base_url}/getBalance",
+            headers=headers,
+            data={},
+        )
+        response.raise_for_status()
+
+        data = response.json()
+        code = data.get("code")
+
+        if code != 200:
+            msg = extract_error_message(data)
+            raise_for_code(f"Get wallet balance failed: {msg}", code=code, payload=data)
+
+        return data.get("data", {})
+
+    def get_proxy_expiration(
+        self,
+        ips: Union[str, List[str]],
+        proxy_type: int,
+    ) -> Dict[str, Any]:
+        """
+        Get expiration time for specific proxy IPs.
+
+        Args:
+            ips: Single IP or list of IPs to check.
+            proxy_type: Proxy type (1=ISP, 2=Datacenter).
+
+        Returns:
+            Dict with expiration information.
+
+        Example:
+            >>> result = client.get_proxy_expiration("123.45.67.89", proxy_type=1)
+            >>> print(result)
+        """
+        self._require_public_credentials()
+
+        # Convert list to comma-separated string
+        if isinstance(ips, list):
+            ips = ",".join(ips)
+
+        params = {
+            "token": self.public_token,
+            "key": self.public_key,
+            "proxy_type": str(proxy_type),
+            "ips": ips,
+        }
+
+        logger.info(f"Getting proxy expiration: {ips}")
+
+        response = self._api_request_with_retry(
+            "GET",
+            self._proxy_expiration_url,
+            params=params,
+        )
+        response.raise_for_status()
+
+        data = response.json()
+
+        if isinstance(data, dict):
+            code = data.get("code")
+            if code is not None and code != 200:
+                msg = extract_error_message(data)
+                raise_for_code(f"Get expiration error: {msg}", code=code, payload=data)
+
+            return data.get("data", data)
+
+        return data
+
+    # =========================================================================
+    # Location API Methods (Country/State/City/ASN functions)
+    # =========================================================================
     def list_countries(
         self, proxy_type: Union[ProxyType, int] = ProxyType.RESIDENTIAL
     ) -> List[Dict[str, Any]]:
@@ -978,7 +1768,11 @@ class ThordataClient:
         logger.debug(f"Locations API request: {url}")
 
         # Use requests.get directly (no proxy needed for this API)
-        response = self._api_session.get(url, params=params, timeout=30)
+        response = self._api_request_with_retry(
+            "GET",
+            url,
+            params=params,
+        )
         response.raise_for_status()
 
         data = response.json()
@@ -998,9 +1792,8 @@ class ThordataClient:
         return []
 
     # =========================================================================
-    # Helper Methods
+    # Helper Methods (Internal utility functions)
     # =========================================================================
-
     def _require_public_credentials(self) -> None:
         """Ensure public API credentials are available."""
         if not self.public_token or not self.public_key:
@@ -1009,6 +1802,185 @@ class ThordataClient:
                 "Please provide them when initializing ThordataClient."
             )
 
+    def _get_proxy_endpoint_overrides(
+        self, product: ProxyProduct
+    ) -> tuple[Optional[str], Optional[int], str]:
+        """
+        Read proxy endpoint overrides from env.
+
+        Priority:
+        1) THORDATA_<PRODUCT>_PROXY_HOST/PORT/PROTOCOL
+        2) THORDATA_PROXY_HOST/PORT/PROTOCOL
+        3) defaults (host/port None => ProxyConfig will use its product defaults)
+        """
+        prefix = product.value.upper()  # RESIDENTIAL / DATACENTER / MOBILE / ISP
+
+        host = os.getenv(f"THORDATA_{prefix}_PROXY_HOST") or os.getenv(
+            "THORDATA_PROXY_HOST"
+        )
+        port_raw = os.getenv(f"THORDATA_{prefix}_PROXY_PORT") or os.getenv(
+            "THORDATA_PROXY_PORT"
+        )
+        protocol = (
+            os.getenv(f"THORDATA_{prefix}_PROXY_PROTOCOL")
+            or os.getenv("THORDATA_PROXY_PROTOCOL")
+            or "http"
+        )
+
+        port: Optional[int] = None
+        if port_raw:
+            try:
+                port = int(port_raw)
+            except ValueError:
+                port = None
+
+        return host or None, port, protocol
+
+    def _get_default_proxy_config_from_env(self) -> Optional[ProxyConfig]:
+        """
+        Try to build a default ProxyConfig from env vars.
+
+        Priority order:
+        1) Residential
+        2) Datacenter
+        3) Mobile
+        """
+        # Residential
+        u = os.getenv("THORDATA_RESIDENTIAL_USERNAME")
+        p = os.getenv("THORDATA_RESIDENTIAL_PASSWORD")
+        if u and p:
+            host, port, protocol = self._get_proxy_endpoint_overrides(
+                ProxyProduct.RESIDENTIAL
+            )
+            return ProxyConfig(
+                username=u,
+                password=p,
+                product=ProxyProduct.RESIDENTIAL,
+                host=host,
+                port=port,
+                protocol=protocol,
+            )
+
+        # Datacenter
+        u = os.getenv("THORDATA_DATACENTER_USERNAME")
+        p = os.getenv("THORDATA_DATACENTER_PASSWORD")
+        if u and p:
+            host, port, protocol = self._get_proxy_endpoint_overrides(
+                ProxyProduct.DATACENTER
+            )
+            return ProxyConfig(
+                username=u,
+                password=p,
+                product=ProxyProduct.DATACENTER,
+                host=host,
+                port=port,
+                protocol=protocol,
+            )
+
+        # Mobile
+        u = os.getenv("THORDATA_MOBILE_USERNAME")
+        p = os.getenv("THORDATA_MOBILE_PASSWORD")
+        if u and p:
+            host, port, protocol = self._get_proxy_endpoint_overrides(
+                ProxyProduct.MOBILE
+            )
+            return ProxyConfig(
+                username=u,
+                password=p,
+                product=ProxyProduct.MOBILE,
+                host=host,
+                port=port,
+                protocol=protocol,
+            )
+
+        return None
+
+    def _build_gateway_headers(self) -> Dict[str, str]:
+        """
+        Build headers for legacy gateway-style endpoints.
+
+        IMPORTANT:
+        - SDK does NOT expose "sign/apiKey" as a separate credential model.
+        - Values ALWAYS come from public_token/public_key.
+        - Some backend endpoints may still expect header field names "sign" and "apiKey".
+        """
+        self._require_public_credentials()
+        return {
+            "sign": self.public_token or "",
+            "apiKey": self.public_key or "",
+            "Content-Type": "application/x-www-form-urlencoded",
+        }
+
+    def _proxy_request_with_proxy_manager(
+        self,
+        method: str,
+        url: str,
+        *,
+        proxy_config: ProxyConfig,
+        timeout: int,
+        headers: Optional[Dict[str, str]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        data: Any = None,
+    ) -> requests.Response:
+        """
+        Proxy Network request implemented via urllib3.ProxyManager.
+
+        This is required to reliably support HTTPS proxy endpoints like:
+        https://<endpoint>.pr.thordata.net:9999
+        """
+        # Build final URL (include query params)
+        req = requests.Request(method=method.upper(), url=url, params=params)
+        prepped = self._proxy_session.prepare_request(req)
+        final_url = prepped.url or url
+
+        proxy_url = proxy_config.build_proxy_endpoint()
+        proxy_headers = urllib3.make_headers(
+            proxy_basic_auth=proxy_config.build_proxy_basic_auth()
+        )
+
+        pm = urllib3.ProxyManager(
+            proxy_url,
+            proxy_headers=proxy_headers,
+            proxy_ssl_context=(
+                ssl.create_default_context()
+                if proxy_url.startswith("https://")
+                else None
+            ),
+        )
+
+        # Encode form data if dict
+        body = None
+        req_headers = dict(headers or {})
+        if data is not None:
+            if isinstance(data, dict):
+                # form-urlencoded
+                body = urlencode({k: str(v) for k, v in data.items()})
+                req_headers.setdefault(
+                    "Content-Type", "application/x-www-form-urlencoded"
+                )
+            else:
+                body = data
+
+        http_resp = pm.request(
+            method.upper(),
+            final_url,
+            body=body,
+            headers=req_headers or None,
+            timeout=urllib3.Timeout(connect=timeout, read=timeout),
+            retries=False,
+            preload_content=True,
+        )
+
+        # Convert urllib3 response -> requests.Response (keep your API stable)
+        r = requests.Response()
+        r.status_code = int(getattr(http_resp, "status", 0) or 0)
+        r._content = http_resp.data or b""
+        r.url = final_url
+        r.headers = requests.structures.CaseInsensitiveDict(
+            dict(http_resp.headers or {})
+        )
+        return r
+
     def _request_with_retry(
         self, method: str, url: str, **kwargs: Any
     ) -> requests.Response: