thordata-sdk 1.3.0__py3-none-any.whl → 1.4.0__py3-none-any.whl

thordata/async_client.py

@@ -23,10 +23,12 @@ Example:
 from __future__ import annotations
 
 import asyncio
+import json
 import logging
 import os
 from datetime import date
 from typing import Any
+from urllib.parse import quote
 
 import aiohttp
 
@@ -40,6 +42,7 @@ from ._utils import (
     extract_error_message,
     parse_json_response,
 )
+from .async_unlimited import AsyncUnlimitedNamespace
 from .enums import Engine, ProxyType
 from .exceptions import (
     ThordataConfigError,
@@ -65,9 +68,13 @@ from .serp_engines import AsyncSerpNamespace
 logger = logging.getLogger(__name__)
 
 
+# =========================================================================
+# Main Client Class
+# =========================================================================
+
+
 class AsyncThordataClient:
-    """
-    The official asynchronous Python client for Thordata.
+    """The official asynchronous Python client for Thordata.
 
     Designed for high-concurrency AI agents and data pipelines.
 
@@ -78,7 +85,13 @@ class AsyncThordataClient:
         proxy_host: Custom proxy gateway host.
         proxy_port: Custom proxy gateway port.
         timeout: Default request timeout in seconds.
+        api_timeout: Default API request timeout in seconds.
         retry_config: Configuration for automatic retries.
+        auth_mode: Authentication mode for scraping APIs ("bearer" or "header_token").
+        scraperapi_base_url: Override base URL for SERP API.
+        universalapi_base_url: Override base URL for Universal Scraping API.
+        web_scraper_api_base_url: Override base URL for Web Scraper API.
+        locations_base_url: Override base URL for Locations API.
 
     Example:
         >>> async with AsyncThordataClient(
@@ -86,10 +99,7 @@ class AsyncThordataClient:
         ...     public_token="pub_token",
         ...     public_key="pub_key"
         ... ) as client:
-        ...     # Old style
         ...     results = await client.serp_search("python")
-        ...     # New style (Namespaced)
-        ...     maps_results = await client.serp.google.maps("coffee", "@40.7,-74.0,14z")
     """
 
     # API Endpoints (same as sync client)
@@ -100,7 +110,7 @@ class AsyncThordataClient:
 
     def __init__(
         self,
-        scraper_token: str | None = None,  # Change: Optional
+        scraper_token: str | None = None,
         public_token: str | None = None,
         public_key: str | None = None,
         proxy_host: str = "pr.thordata.net",
@@ -114,8 +124,23 @@ class AsyncThordataClient:
         web_scraper_api_base_url: str | None = None,
         locations_base_url: str | None = None,
     ) -> None:
-        """Initialize the Async Thordata Client."""
+        """Initialize the Async Thordata Client.
 
+        Args:
+            scraper_token: Token for SERP/Universal scraping APIs.
+            public_token: Public API token for account/management operations.
+            public_key: Public API key for account/management operations.
+            proxy_host: Default proxy host for residential proxies.
+            proxy_port: Default proxy port for residential proxies.
+            timeout: Default timeout for proxy requests.
+            api_timeout: Default timeout for API requests.
+            retry_config: Configuration for retry behavior.
+            auth_mode: Authentication mode for scraper_token ("bearer" or "header_token").
+            scraperapi_base_url: Override base URL for SERP API.
+            universalapi_base_url: Override base URL for Universal Scraping API.
+            web_scraper_api_base_url: Override base URL for Web Scraper API.
+            locations_base_url: Override base URL for Locations API.
+        """
         self.scraper_token = scraper_token
         self.public_token = public_token
         self.public_key = public_key
@@ -207,6 +232,11 @@ class AsyncThordataClient:
 
         # Namespaced Access (e.g. client.serp.google.maps(...))
         self.serp = AsyncSerpNamespace(self)
+        self.unlimited = AsyncUnlimitedNamespace(self)
+
+    # =========================================================================
+    # Context Manager
+    # =========================================================================
 
     async def __aenter__(self) -> AsyncThordataClient:
         """Async context manager entry."""
@@ -248,8 +278,7 @@ class AsyncThordataClient:
         proxy_config: ProxyConfig | None = None,
         **kwargs: Any,
     ) -> aiohttp.ClientResponse:
-        """
-        Send an async GET request through the Proxy Network.
+        """Send an async GET request through the Proxy Network.
 
         Args:
             url: The target URL.
@@ -258,6 +287,10 @@ class AsyncThordataClient:
 
         Returns:
             The aiohttp response object.
+
+        Note:
+            aiohttp has limited support for HTTPS proxies (TLS to proxy / TLS-in-TLS).
+            For HTTPS proxy endpoints, please use ThordataClient.get/post (sync client).
         """
         session = self._get_session()
 
@@ -270,16 +303,13 @@ class AsyncThordataClient:
             raise ThordataConfigError(
                 "Proxy credentials are missing. "
                 "Pass proxy_config=ProxyConfig(username=..., password=..., product=...) "
-                "or set THORDATA_RESIDENTIAL_USERNAME/THORDATA_RESIDENTIAL_PASSWORD (or DATACENTER/MOBILE)."
+                "or set THORDATA_RESIDENTIAL_USERNAME/THORDATA_RESIDENTIAL_PASSWORD."
             )
 
-        # aiohttp has limited support for "https://" proxies (TLS to proxy / TLS-in-TLS).
-        # Your account's proxy endpoint requires HTTPS proxy, so we explicitly block here
-        # to avoid confusing "it always fails" behavior.
         if getattr(proxy_config, "protocol", "http").lower() == "https":
             raise ThordataConfigError(
-                "Proxy Network requires an HTTPS proxy endpoint (TLS to proxy) for your account. "
-                "aiohttp support for 'https://' proxies is limited and may fail. "
+                "Proxy Network requires an HTTPS proxy endpoint. "
+                "aiohttp support for 'https://' proxies is limited. "
                 "Please use ThordataClient.get/post (sync client) for Proxy Network requests."
             )
         proxy_url, proxy_auth = proxy_config.to_aiohttp_config()
@@ -304,8 +334,7 @@ class AsyncThordataClient:
         proxy_config: ProxyConfig | None = None,
         **kwargs: Any,
     ) -> aiohttp.ClientResponse:
-        """
-        Send an async POST request through the Proxy Network.
+        """Send an async POST request through the Proxy Network.
 
         Args:
             url: The target URL.
@@ -326,16 +355,13 @@ class AsyncThordataClient:
             raise ThordataConfigError(
                 "Proxy credentials are missing. "
                 "Pass proxy_config=ProxyConfig(username=..., password=..., product=...) "
-                "or set THORDATA_RESIDENTIAL_USERNAME/THORDATA_RESIDENTIAL_PASSWORD (or DATACENTER/MOBILE)."
+                "or set THORDATA_RESIDENTIAL_USERNAME/THORDATA_RESIDENTIAL_PASSWORD."
             )
 
-        # aiohttp has limited support for "https://" proxies (TLS to proxy / TLS-in-TLS).
-        # Your account's proxy endpoint requires HTTPS proxy, so we explicitly block here
-        # to avoid confusing "it always fails" behavior.
         if getattr(proxy_config, "protocol", "http").lower() == "https":
             raise ThordataConfigError(
-                "Proxy Network requires an HTTPS proxy endpoint (TLS to proxy) for your account. "
-                "aiohttp support for 'https://' proxies is limited and may fail. "
+                "Proxy Network requires an HTTPS proxy endpoint. "
+                "aiohttp support for 'https://' proxies is limited. "
                 "Please use ThordataClient.get/post (sync client) for Proxy Network requests."
             )
         proxy_url, proxy_auth = proxy_config.to_aiohttp_config()
@@ -372,18 +398,17 @@ class AsyncThordataClient:
         output_format: str = "json",
         **kwargs: Any,
     ) -> dict[str, Any]:
-        """
-        Execute an async SERP search.
+        """Execute an async SERP search.
 
         Args:
             query: Search keywords.
-            engine: Search engine.
+            engine: Search engine (GOOGLE, BING, etc.).
             num: Number of results.
             country: Country code for localization.
             language: Language code.
-            search_type: Type of search.
+            search_type: Type of search (images, news, video, etc.).
             device: Device type ('desktop', 'mobile', 'tablet').
-            render_js: Enable JavaScript rendering in SERP.
+            render_js: Enable JavaScript rendering.
             no_cache: Disable internal caching.
             output_format: 'json' or 'html'.
             **kwargs: Additional parameters.
@@ -456,8 +481,13 @@ class AsyncThordataClient:
             ) from e
 
     async def serp_search_advanced(self, request: SerpRequest) -> dict[str, Any]:
-        """
-        Execute an async SERP search using a SerpRequest object.
+        """Execute an async SERP search using a SerpRequest object.
+
+        Args:
+            request: SerpRequest object with search parameters.
+
+        Returns:
+            Parsed search results.
         """
         session = self._get_session()
         if not self.scraper_token:
@@ -521,17 +551,16 @@ class AsyncThordataClient:
         wait_for: str | None = None,
         **kwargs: Any,
     ) -> str | bytes:
-        """
-        Async scrape using Universal API (Web Unlocker).
+        """Async scrape using Universal API (Web Unlocker).
 
         Args:
             url: Target URL.
             js_render: Enable JavaScript rendering.
             output_format: "html" or "png".
             country: Geo-targeting country.
-            block_resources: Resources to block.
-            wait: Wait time in ms.
-            wait_for: CSS selector to wait for.
+            block_resources: Resources to block (e.g., "script,css").
+            wait: Wait time in milliseconds before fetching.
+            wait_for: CSS selector to wait for before fetching.
 
         Returns:
             HTML string or PNG bytes.
@@ -552,8 +581,13 @@ class AsyncThordataClient:
     async def universal_scrape_advanced(
         self, request: UniversalScrapeRequest
     ) -> str | bytes:
-        """
-        Async scrape using a UniversalScrapeRequest object.
+        """Async scrape using a UniversalScrapeRequest object.
+
+        Args:
+            request: UniversalScrapeRequest object with scrape parameters.
+
+        Returns:
+            HTML string or PNG bytes.
         """
         session = self._get_session()
         if not self.scraper_token:
@@ -604,7 +638,7 @@ class AsyncThordataClient:
             ) from e
 
     # =========================================================================
-    # Web Scraper API Methods
+    # Web Scraper API - Task Management
     # =========================================================================
 
     async def create_scraper_task(
@@ -615,8 +649,17 @@ class AsyncThordataClient:
         parameters: dict[str, Any],
         universal_params: dict[str, Any] | None = None,
     ) -> str:
-        """
-        Create an async Web Scraper task.
+        """Create an async Web Scraper task.
+
+        Args:
+            file_name: Name for the output file (supports {{TasksID}} template).
+            spider_id: Spider identifier from Dashboard.
+            spider_name: Spider name (target domain, e.g., "amazon.com").
+            parameters: Spider-specific parameters.
+            universal_params: Global spider settings.
+
+        Returns:
+            Task ID.
         """
         config = ScraperTaskConfig(
             file_name=file_name,
@@ -629,8 +672,13 @@ class AsyncThordataClient:
         return await self.create_scraper_task_advanced(config)
 
     async def create_scraper_task_advanced(self, config: ScraperTaskConfig) -> str:
-        """
-        Create a task using ScraperTaskConfig.
+        """Create a task using ScraperTaskConfig.
+
+        Args:
+            config: ScraperTaskConfig object with task configuration.
+
+        Returns:
+            Task ID.
         """
         self._require_public_credentials()
         session = self._get_session()
@@ -676,10 +724,18 @@ class AsyncThordataClient:
         parameters: dict[str, Any],
         common_settings: CommonSettings,
     ) -> str:
-        """
-        Create a YouTube video/audio download task.
-        """
+        """Create a YouTube video/audio download task.
 
+        Args:
+            file_name: Name for the output file.
+            spider_id: Spider identifier (e.g., "youtube_video_by-url").
+            spider_name: Target site (e.g., "youtube.com").
+            parameters: Spider-specific parameters (URLs, etc.).
+            common_settings: Video/audio settings (resolution, subtitles, etc.).
+
+        Returns:
+            Task ID.
+        """
         config = VideoTaskConfig(
             file_name=file_name,
             spider_id=spider_id,
@@ -691,10 +747,14 @@ class AsyncThordataClient:
         return await self.create_video_task_advanced(config)
 
     async def create_video_task_advanced(self, config: VideoTaskConfig) -> str:
-        """
-        Create a video task using VideoTaskConfig object.
-        """
+        """Create a video task using VideoTaskConfig object.
+
+        Args:
+            config: VideoTaskConfig object with task configuration.
 
+        Returns:
+            Task ID.
+        """
         self._require_public_credentials()
         session = self._get_session()
         if not self.scraper_token:
@@ -742,12 +802,17 @@ class AsyncThordataClient:
             ) from e
 
     async def get_task_status(self, task_id: str) -> str:
-        """
-        Check async task status.
+        """Check async task status.
+
+        Args:
+            task_id: Task identifier.
+
+        Returns:
+            Status string (running, success, failed, etc.).
 
         Raises:
             ThordataConfigError: If public credentials are missing.
-            ThordataAPIError: If API returns a non-200 code in JSON payload.
+            ThordataAPIError: If API returns a non-200 code.
             ThordataNetworkError: If network/HTTP request fails.
         """
         self._require_public_credentials()
@@ -797,8 +862,7 @@ class AsyncThordataClient:
             ) from e
 
     async def safe_get_task_status(self, task_id: str) -> str:
-        """
-        Backward-compatible status check.
+        """Backward-compatible status check.
 
         Returns:
             Status string, or "error" on any exception.
@@ -809,8 +873,14 @@ class AsyncThordataClient:
             return "error"
 
     async def get_task_result(self, task_id: str, file_type: str = "json") -> str:
-        """
-        Get download URL for completed task.
+        """Get download URL for completed task.
+
+        Args:
+            task_id: Task identifier.
+            file_type: File type to download (json, csv, video, audio, subtitle).
+
+        Returns:
+            Download URL.
         """
         self._require_public_credentials()
         session = self._get_session()
@@ -847,8 +917,7 @@ class AsyncThordataClient:
         page: int = 1,
         size: int = 20,
     ) -> dict[str, Any]:
-        """
-        List all Web Scraper tasks.
+        """List all Web Scraper tasks.
 
         Args:
             page: Page number (starts from 1).
@@ -904,10 +973,16 @@ class AsyncThordataClient:
         poll_interval: float = 5.0,
         max_wait: float = 600.0,
     ) -> str:
-        """
-        Wait for a task to complete.
-        """
+        """Wait for a task to complete.
 
+        Args:
+            task_id: Task identifier.
+            poll_interval: Polling interval in seconds.
+            max_wait: Maximum time to wait in seconds.
+
+        Returns:
+            Final status of the task.
+        """
         import time
 
         start = time.monotonic()
@@ -945,25 +1020,51 @@ class AsyncThordataClient:
         initial_poll_interval: float = 2.0,
         max_poll_interval: float = 10.0,
         include_errors: bool = True,
+        task_type: str = "web",
+        common_settings: CommonSettings | None = None,
     ) -> str:
-        """
-        Async high-level wrapper to Run a Web Scraper task and wait for result.
+        """Async high-level wrapper to run a task and wait for result.
 
         Lifecycle: Create -> Poll (Backoff) -> Get Download URL.
 
+        Args:
+            file_name: Name for the output file.
+            spider_id: Spider identifier from Dashboard.
+            spider_name: Spider name (target domain).
+            parameters: Spider-specific parameters.
+            universal_params: Global spider settings.
+            max_wait: Maximum seconds to wait for completion.
+            initial_poll_interval: Starting poll interval in seconds.
+            max_poll_interval: Maximum poll interval cap.
+            include_errors: Whether to include error logs.
+
         Returns:
-            str: The download URL.
+            The download URL.
         """
-        # 1. Create Task
-        config = ScraperTaskConfig(
-            file_name=file_name,
-            spider_id=spider_id,
-            spider_name=spider_name,
-            parameters=parameters,
-            universal_params=universal_params,
-            include_errors=include_errors,
-        )
-        task_id = await self.create_scraper_task_advanced(config)
+        if task_type == "video":
+            if common_settings is None:
+                raise ValueError("common_settings is required for video tasks")
+
+            config_video = VideoTaskConfig(
+                file_name=file_name,
+                spider_id=spider_id,
+                spider_name=spider_name,
+                parameters=parameters,
+                common_settings=common_settings,
+                include_errors=include_errors,
+            )
+            task_id = await self.create_video_task_advanced(config_video)
+        else:
+            config = ScraperTaskConfig(
+                file_name=file_name,
+                spider_id=spider_id,
+                spider_name=spider_name,
+                parameters=parameters,
+                universal_params=universal_params,
+                include_errors=include_errors,
+            )
+            task_id = await self.create_scraper_task_advanced(config)
+
         logger.info(f"Async Task created: {task_id}. Polling...")
 
         # 2. Poll Status
@@ -978,7 +1079,6 @@ class AsyncThordataClient:
 
             if status_lower in {"ready", "success", "finished"}:
                 logger.info(f"Task {task_id} ready.")
-                # 3. Get Result
                 return await self.get_task_result(task_id)
 
             if status_lower in {"failed", "error", "cancelled"}:
@@ -992,7 +1092,7 @@ class AsyncThordataClient:
         raise ThordataTimeoutError(f"Async Task {task_id} timed out after {max_wait}s")
 
     # =========================================================================
-    # Proxy Account Management Methods
+    # Account & Usage Methods
     # =========================================================================
 
     async def get_usage_statistics(
@@ -1000,8 +1100,7 @@ class AsyncThordataClient:
         from_date: str | date,
         to_date: str | date,
     ) -> UsageStatistics:
-        """
-        Get account usage statistics for a date range.
+        """Get account usage statistics for a date range.
 
         Args:
             from_date: Start date (YYYY-MM-DD string or date object).
@@ -1010,7 +1109,6 @@ class AsyncThordataClient:
         Returns:
             UsageStatistics object with traffic data.
         """
-
         self._require_public_credentials()
         session = self._get_session()
 
@@ -1066,10 +1164,12 @@ class AsyncThordataClient:
             ) from e
 
     async def get_residential_balance(self) -> dict[str, Any]:
-        """
-        Get residential proxy balance.
+        """Get residential proxy balance.
 
-        Uses public_token/public_key.
+        Uses public_token/public_key via gateway API.
+
+        Returns:
+            Balance data dictionary.
         """
         session = self._get_session()
         headers = self._build_gateway_headers()
@@ -1109,10 +1209,16 @@ class AsyncThordataClient:
         start_time: str | int,
         end_time: str | int,
     ) -> dict[str, Any]:
-        """
-        Get residential proxy usage records.
+        """Get residential proxy usage records.
+
+        Uses public_token/public_key via gateway API.
 
-        Uses public_token/public_key.
+        Args:
+            start_time: Start timestamp or date string.
+            end_time: End timestamp or date string.
+
+        Returns:
+            Usage data dictionary.
         """
         session = self._get_session()
         headers = self._build_gateway_headers()
@@ -1146,11 +1252,186 @@ class AsyncThordataClient:
                 f"Get usage failed: {e}", original_error=e
             ) from e
 
+    async def get_traffic_balance(self) -> float:
+        """Get traffic balance in KB via Public API."""
+        self._require_public_credentials()
+        # FIX: Ensure params are strings and dict structure satisfies type checker
+        # _require_public_credentials ensures tokens are not None at runtime,
+        # but for type checking we cast or assert.
+        params = {
+            "token": str(self.public_token),
+            "key": str(self.public_key),
+        }
+        api_base = self._locations_base_url.replace("/locations", "")
+
+        try:
+            async with self._get_session().get(
+                f"{api_base}/account/traffic-balance", params=params
+            ) as resp:
+                data = await resp.json()
+                if data.get("code") != 200:
+                    raise_for_code(
+                        "Get traffic balance failed",
+                        code=data.get("code"),
+                        payload=data,
+                    )
+                return float(data.get("data", {}).get("traffic_balance", 0))
+        except aiohttp.ClientError as e:
+            raise ThordataNetworkError(f"Request failed: {e}", original_error=e) from e
+
+    async def get_proxy_user_usage(
+        self,
+        username: str,
+        start_date: str | date,
+        end_date: str | date,
+        proxy_type: ProxyType | int = ProxyType.RESIDENTIAL,
+    ) -> list[dict[str, Any]]:
+        """Get user usage statistics."""
+        self._require_public_credentials()
+        pt = int(proxy_type) if isinstance(proxy_type, ProxyType) else proxy_type
+
+        if isinstance(start_date, date):
+            start_date = start_date.strftime("%Y-%m-%d")
+        if isinstance(end_date, date):
+            end_date = end_date.strftime("%Y-%m-%d")
+
+        params = {
+            "token": self.public_token,
+            "key": self.public_key,
+            "proxy_type": str(pt),
+            "username": username,
+            "from_date": start_date,
+            "to_date": end_date,
+        }
+
+        try:
+            async with self._get_session().get(
+                f"{self._proxy_users_url}/usage-statistics", params=params
+            ) as resp:
+                data = await resp.json()
+                if data.get("code") != 200:
+                    raise_for_code(
+                        "Get user usage failed", code=data.get("code"), payload=data
+                    )
+                return data.get("data") or []
+        except aiohttp.ClientError as e:
+            raise ThordataNetworkError(f"Request failed: {e}", original_error=e) from e
+
+    async def extract_ip_list(
+        self,
+        num: int = 1,
+        country: str | None = None,
+        state: str | None = None,
+        city: str | None = None,
+        time_limit: int | None = None,
+        port: int | None = None,
+        return_type: str = "txt",
+        protocol: str = "http",
+        sep: str = "\r\n",
+        product: str = "residential",
+    ) -> list[str]:
+        """Async extract IPs."""
+        base_url = "https://get-ip.thordata.net"
+        endpoint = "/unlimited_api" if product == "unlimited" else "/api"
+
+        params: dict[str, Any] = {
+            "num": str(num),
+            "return_type": return_type,
+            "protocol": protocol,
+            "sep": sep,
+        }
+        if country:
+            params["country"] = country
+        if state:
+            params["state"] = state
+        if city:
+            params["city"] = city
+        if time_limit:
+            params["time"] = str(time_limit)
+        if port:
+            params["port"] = str(port)
+
+        username = os.getenv("THORDATA_RESIDENTIAL_USERNAME")
+        if username:
+            params["td-customer"] = username
+
+        try:
+            async with self._get_session().get(
+                f"{base_url}{endpoint}", params=params
+            ) as resp:
+                if return_type == "json":
+                    data = await resp.json()
+                    if isinstance(data, dict):
+                        if data.get("code") == 0 or data.get("code") == 200:
+                            raw_list = data.get("data") or []
+                            return [f"{item['ip']}:{item['port']}" for item in raw_list]
+                        else:
+                            raise_for_code(
+                                "Extract IPs failed",
+                                code=data.get("code"),
+                                payload=data,
+                            )
+                    return []
+                else:
+                    text = await resp.text()
+                    text = text.strip()
+                    if text.startswith("{") and "code" in text:
+                        try:
+                            err_data = json.loads(text)
+                            raise_for_code(
+                                "Extract IPs failed",
+                                code=err_data.get("code"),
+                                payload=err_data,
+                            )
+                        except json.JSONDecodeError:
+                            pass
+
+                    actual_sep = sep.replace("\\r", "\r").replace("\\n", "\n")
+                    return [
+                        line.strip() for line in text.split(actual_sep) if line.strip()
+                    ]
+
+        except aiohttp.ClientError as e:
+            raise ThordataNetworkError(f"Request failed: {e}", original_error=e) from e
+
+    async def get_wallet_balance(self) -> float:
+        """Get wallet balance via Public API."""
+        self._require_public_credentials()
+        # FIX: Ensure params are strings
+        params = {
+            "token": str(self.public_token),
+            "key": str(self.public_key),
+        }
+        api_base = self._locations_base_url.replace("/locations", "")
+
+        try:
+            async with self._get_session().get(
+                f"{api_base}/account/wallet-balance", params=params
+            ) as resp:
+                data = await resp.json()
+                if data.get("code") != 200:
+                    raise_for_code(
+                        "Get wallet balance failed", code=data.get("code"), payload=data
+                    )
+                return float(data.get("data", {}).get("balance", 0))
+        except aiohttp.ClientError as e:
+            raise ThordataNetworkError(f"Request failed: {e}", original_error=e) from e
+
+    # =========================================================================
+    # Proxy Users Management (Sub-accounts)
+    # =========================================================================
+
     async def list_proxy_users(
         self, proxy_type: ProxyType | int = ProxyType.RESIDENTIAL
     ) -> ProxyUserList:
-        """List all proxy users (sub-accounts)."""
+        """List all proxy users (sub-accounts).
+
+        Args:
+            proxy_type: Proxy product type.
 
+        Returns:
+            ProxyUserList with user information.
+        """
         self._require_public_credentials()
         session = self._get_session()
 
@@ -1206,7 +1487,18 @@ class AsyncThordataClient:
         traffic_limit: int = 0,
         status: bool = True,
     ) -> dict[str, Any]:
-        """Create a new proxy user (sub-account)."""
+        """Create a new proxy user (sub-account).
+
+        Args:
+            username: Sub-account username.
+            password: Sub-account password.
+            proxy_type: Proxy product type.
+            traffic_limit: Traffic limit in MB (0 = unlimited).
+            status: Enable or disable the account.
+
+        Returns:
+            API response data.
+        """
         self._require_public_credentials()
         session = self._get_session()
 
@@ -1254,14 +1546,132 @@ class AsyncThordataClient:
                 f"Create user failed: {e}", original_error=e
             ) from e
 
+    async def update_proxy_user(
+        self,
+        username: str,
+        password: str,  # Added password
+        traffic_limit: int | None = None,
+        status: bool | None = None,
+        proxy_type: ProxyType | int = ProxyType.RESIDENTIAL,
+    ) -> dict[str, Any]:
+        """Update a proxy user."""
+        self._require_public_credentials()
+        session = self._get_session()
+        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,  # Include password
+        }
+        if traffic_limit is not None:
+            payload["traffic_limit"] = str(traffic_limit)
+        if status is not None:
+            payload["status"] = "true" if status else "false"
+
+        try:
+            async with session.post(
+                f"{self._proxy_users_url}/update-user",
+                data=payload,
+                headers=headers,
+                timeout=self._api_timeout,
+            ) as response:
+                response.raise_for_status()
+                data = await response.json()
+
+                if data.get("code") != 200:
+                    raise_for_code(
+                        f"Update user failed: {data.get('msg')}",
+                        code=data.get("code"),
+                        payload=data,
+                    )
+
+                return data.get("data", {})
+
+        except aiohttp.ClientError as e:
+            raise ThordataNetworkError(
+                f"Update user failed: {e}", original_error=e
+            ) from e
+
+    async def delete_proxy_user(
+        self,
+        username: str,
+        proxy_type: ProxyType | int = ProxyType.RESIDENTIAL,
+    ) -> dict[str, Any]:
+        """Delete a proxy user.
+
+        Args:
+            username: The sub-account username.
+            proxy_type: Proxy product type.
+
+        Returns:
+            API response data.
+        """
+        self._require_public_credentials()
+        session = self._get_session()
+
+        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,
+        }
+
+        try:
+            async with session.post(
+                f"{self._proxy_users_url}/delete-user",
+                data=payload,
+                headers=headers,
+                timeout=self._api_timeout,
+            ) as response:
+                response.raise_for_status()
+                data = await response.json()
+
+                code = data.get("code")
+                if code != 200:
+                    msg = extract_error_message(data)
+                    raise_for_code(
+                        f"Delete user failed: {msg}", code=code, payload=data
+                    )
+
+                return data.get("data", {})
+
+        except asyncio.TimeoutError as e:
+            raise ThordataTimeoutError(
+                f"Delete user timed out: {e}", original_error=e
+            ) from e
+        except aiohttp.ClientError as e:
+            raise ThordataNetworkError(
+                f"Delete user failed: {e}", original_error=e
+            ) from e
+
+    # =========================================================================
+    # Whitelist IP Management
+    # =========================================================================
+
     async def add_whitelist_ip(
         self,
         ip: str,
         proxy_type: ProxyType | int = ProxyType.RESIDENTIAL,
         status: bool = True,
     ) -> dict[str, Any]:
-        """
-        Add an IP to the whitelist for IP authentication.
+        """Add an IP to the whitelist for IP authentication.
+
+        Args:
+            ip: IP address to whitelist.
+            proxy_type: Proxy product type.
+            status: Enable or disable the whitelist entry.
+
+        Returns:
+            API response data.
         """
         self._require_public_credentials()
         session = self._get_session()
@@ -1310,19 +1720,245 @@ class AsyncThordataClient:
                 f"Add whitelist failed: {e}", original_error=e
             ) from e
 
-    async def list_proxy_servers(
+    async def delete_whitelist_ip(
         self,
-        proxy_type: int,
-    ) -> list[ProxyServer]:
-        """
-        List ISP or Datacenter proxy servers.
-        """
+        ip: str,
+        proxy_type: ProxyType | int = ProxyType.RESIDENTIAL,
+    ) -> dict[str, Any]:
+        """Delete an IP from the whitelist.
+
+        Args:
+            ip: The IP address to remove.
+            proxy_type: Proxy product type.
 
+        Returns:
+            API response data.
+        """
         self._require_public_credentials()
         session = self._get_session()
 
-        params = {
-            "token": self.public_token,
+        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
+            ),
+            "ip": ip,
+        }
+
+        try:
+            async with session.post(
+                f"{self._whitelist_url}/delete-ip",
+                data=payload,
+                headers=headers,
+                timeout=self._api_timeout,
+            ) as response:
+                response.raise_for_status()
+                data = await response.json()
+
+                code = data.get("code")
+                if code != 200:
+                    msg = extract_error_message(data)
+                    raise_for_code(
+                        f"Delete whitelist IP failed: {msg}", code=code, payload=data
+                    )
+
+                return data.get("data", {})
+
+        except asyncio.TimeoutError as e:
+            raise ThordataTimeoutError(
+                f"Delete whitelist timed out: {e}", original_error=e
+            ) from e
+        except aiohttp.ClientError as e:
+            raise ThordataNetworkError(
+                f"Delete whitelist failed: {e}", original_error=e
+            ) from e
+
+    async def list_whitelist_ips(
+        self,
+        proxy_type: ProxyType | int = ProxyType.RESIDENTIAL,
+    ) -> list[str]:
+        """List all whitelisted IPs.
+
+        Args:
+            proxy_type: Proxy product type.
+
+        Returns:
+            List of IP address strings.
+        """
+        self._require_public_credentials()
+        session = self._get_session()
+
+        params = {
+            k: v
+            for k, v in {
+                "token": self.public_token,
+                "key": self.public_key,
+                "proxy_type": str(
+                    int(proxy_type) if isinstance(proxy_type, ProxyType) else proxy_type
+                ),
+            }.items()
+            if v is not None
+        }
+
+        try:
+            async with session.get(
+                f"{self._whitelist_url}/ip-list",
+                params=params,
+                timeout=self._api_timeout,
+            ) as response:
+                response.raise_for_status()
+                data = await 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 whitelist IPs error: {msg}", code=code, payload=data
+                        )
+
+                    items = data.get("data", [])
+                    result = []
+                    for item in items:
+                        if isinstance(item, str):
+                            result.append(item)
+                        elif isinstance(item, dict) and "ip" in item:
+                            result.append(str(item["ip"]))
+                        else:
+                            result.append(str(item))
+                    return result
+
+                raise ThordataNetworkError(
+                    f"Unexpected whitelist response: {type(data).__name__}",
+                    original_error=None,
+                )
+
+        except asyncio.TimeoutError as e:
+            raise ThordataTimeoutError(
+                f"List whitelist timed out: {e}", original_error=e
+            ) from e
+        except aiohttp.ClientError as e:
+            raise ThordataNetworkError(
+                f"List whitelist failed: {e}", original_error=e
+            ) from e
+
+    # =========================================================================
+    # Locations & ASN Methods
+    # =========================================================================
+
+    async def list_countries(
+        self, proxy_type: ProxyType | int = ProxyType.RESIDENTIAL
+    ) -> list[dict[str, Any]]:
+        """List supported countries for proxy locations.
+
+        Args:
+            proxy_type: Proxy product type.
+
+        Returns:
+            List of country dictionaries.
+        """
+        return await self._get_locations(
+            "countries",
+            proxy_type=(
+                int(proxy_type) if isinstance(proxy_type, ProxyType) else proxy_type
+            ),
+        )
+
+    async def list_states(
+        self,
+        country_code: str,
+        proxy_type: ProxyType | int = ProxyType.RESIDENTIAL,
+    ) -> list[dict[str, Any]]:
+        """List supported states/provinces for a country.
+
+        Args:
+            country_code: Country code (e.g., "US", "GB").
+            proxy_type: Proxy product type.
+
+        Returns:
+            List of state dictionaries.
+        """
+        return await self._get_locations(
+            "states",
+            proxy_type=(
+                int(proxy_type) if isinstance(proxy_type, ProxyType) else proxy_type
+            ),
+            country_code=country_code,
+        )
+
+    async def list_cities(
+        self,
+        country_code: str,
+        state_code: str | None = None,
+        proxy_type: ProxyType | int = ProxyType.RESIDENTIAL,
+    ) -> list[dict[str, Any]]:
+        """List supported cities for a country/state.
+
+        Args:
+            country_code: Country code.
+            state_code: State code (optional).
+            proxy_type: Proxy product type.
+
+        Returns:
+            List of city dictionaries.
+        """
+        kwargs = {
+            "proxy_type": (
+                int(proxy_type) if isinstance(proxy_type, ProxyType) else proxy_type
+            ),
+            "country_code": country_code,
+        }
+        if state_code:
+            kwargs["state_code"] = state_code
+
+        return await self._get_locations("cities", **kwargs)
+
+    async def list_asn(
+        self,
+        country_code: str,
+        proxy_type: ProxyType | int = ProxyType.RESIDENTIAL,
+    ) -> list[dict[str, Any]]:
+        """List supported ASNs for a country.
+
+        Args:
+            country_code: Country code.
+            proxy_type: Proxy product type.
+
+        Returns:
+            List of ASN dictionaries.
+        """
+        return await self._get_locations(
+            "asn",
+            proxy_type=(
+                int(proxy_type) if isinstance(proxy_type, ProxyType) else proxy_type
+            ),
+            country_code=country_code,
+        )
+
+    # =========================================================================
+    # ISP & Datacenter Proxy Management
+    # =========================================================================
+
+    async 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.
+        """
+        self._require_public_credentials()
+        session = self._get_session()
+
+        params = {
+            "token": self.public_token,
             "key": self.public_key,
             "proxy_type": str(proxy_type),
         }
@@ -1366,11 +2002,72 @@ class AsyncThordataClient:
                 f"List servers failed: {e}", original_error=e
             ) from e
 
-    async def get_isp_regions(self) -> list[dict[str, Any]]:
+    async def get_proxy_expiration(
+        self,
+        ips: str | list[str],
+        proxy_type: int,
+    ) -> dict[str, Any]:
+        """Get expiration time for specific proxy IPs.
+
+        Args:
+            ips: Single IP or comma-separated list of IPs.
+            proxy_type: Proxy type (1=ISP, 2=Datacenter).
+
+        Returns:
+            Dictionary with IP expiration times.
         """
-        Get available ISP proxy regions.
+        self._require_public_credentials()
+        session = self._get_session()
+
+        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"Async getting proxy expiration: {ips}")
+
+        try:
+            async with session.get(
+                self._proxy_expiration_url,
+                params=params,
+                timeout=self._api_timeout,
+            ) as response:
+                response.raise_for_status()
+                data = await 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
+                        )
 
-        Uses public_token/public_key.
+                    return data.get("data", data)
+
+                return data
+
+        except asyncio.TimeoutError as e:
+            raise ThordataTimeoutError(
+                f"Get expiration timed out: {e}", original_error=e
+            ) from e
+        except aiohttp.ClientError as e:
+            raise ThordataNetworkError(
+                f"Get expiration failed: {e}", original_error=e
+            ) from e
+
+    async def get_isp_regions(self) -> list[dict[str, Any]]:
+        """Get available ISP proxy regions.
+
+        Uses public_token/public_key via gateway API.
+
+        Returns:
+            List of ISP region dictionaries.
         """
         session = self._get_session()
         headers = self._build_gateway_headers()
@@ -1406,10 +2103,12 @@ class AsyncThordataClient:
             ) from e
 
     async def list_isp_proxies(self) -> list[dict[str, Any]]:
-        """
-        List ISP proxies.
+        """List ISP proxies.
+
+        Uses public_token/public_key via gateway API.
 
-        Uses public_token/public_key.
+        Returns:
+            List of ISP proxy dictionaries.
         """
         session = self._get_session()
         headers = self._build_gateway_headers()
@@ -1444,11 +2143,13 @@ class AsyncThordataClient:
                 f"List ISP proxies failed: {e}", original_error=e
             ) from e
 
-    async def get_wallet_balance(self) -> dict[str, Any]:
-        """
-        Get wallet balance for ISP proxies.
+    async def get_isp_wallet_balance(self) -> dict[str, Any]:
+        """Get wallet balance for ISP proxies.
+
+        Uses public_token/public_key via gateway API.
 
-        Uses public_token/public_key.
+        Returns:
+            Wallet balance data dictionary.
         """
         session = self._get_session()
         headers = self._build_gateway_headers()
@@ -1483,124 +2184,35 @@ class AsyncThordataClient:
                 f"Get wallet balance failed: {e}", original_error=e
             ) from e
 
-    async def get_proxy_expiration(
-        self,
-        ips: str | list[str],
-        proxy_type: int,
-    ) -> dict[str, Any]:
-        """
-        Get expiration time for specific proxy IPs.
-        """
-        self._require_public_credentials()
-        session = self._get_session()
-
-        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"Async getting proxy expiration: {ips}")
-
-        try:
-            async with session.get(
-                self._proxy_expiration_url,
-                params=params,
-                timeout=self._api_timeout,
-            ) as response:
-                response.raise_for_status()
-                data = await 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
-
-        except asyncio.TimeoutError as e:
-            raise ThordataTimeoutError(
-                f"Get expiration timed out: {e}", original_error=e
-            ) from e
-        except aiohttp.ClientError as e:
-            raise ThordataNetworkError(
-                f"Get expiration failed: {e}", original_error=e
-            ) from e
-
     # =========================================================================
-    # Location API Methods
+    # Internal Helper Methods
     # =========================================================================
 
-    async def list_countries(
-        self, proxy_type: ProxyType | int = ProxyType.RESIDENTIAL
-    ) -> list[dict[str, Any]]:
-        """List supported countries."""
-        return await self._get_locations(
-            "countries",
-            proxy_type=(
-                int(proxy_type) if isinstance(proxy_type, ProxyType) else proxy_type
-            ),
-        )
-
-    async def list_states(
-        self,
-        country_code: str,
-        proxy_type: ProxyType | int = ProxyType.RESIDENTIAL,
-    ) -> list[dict[str, Any]]:
-        """List supported states for a country."""
-        return await self._get_locations(
-            "states",
-            proxy_type=(
-                int(proxy_type) if isinstance(proxy_type, ProxyType) else proxy_type
-            ),
-            country_code=country_code,
-        )
-
-    async def list_cities(
-        self,
-        country_code: str,
-        state_code: str | None = None,
-        proxy_type: ProxyType | int = ProxyType.RESIDENTIAL,
-    ) -> list[dict[str, Any]]:
-        """List supported cities."""
-        kwargs = {
-            "proxy_type": (
-                int(proxy_type) if isinstance(proxy_type, ProxyType) else proxy_type
-            ),
-            "country_code": country_code,
-        }
-        if state_code:
-            kwargs["state_code"] = state_code
-
-        return await self._get_locations("cities", **kwargs)
+    def _require_public_credentials(self) -> None:
+        """Ensure public API credentials are available."""
+        if not self.public_token or not self.public_key:
+            raise ThordataConfigError(
+                "public_token and public_key are required for this operation. "
+                "Please provide them when initializing AsyncThordataClient."
+            )
 
-    async def list_asn(
-        self,
-        country_code: str,
-        proxy_type: ProxyType | int = ProxyType.RESIDENTIAL,
-    ) -> list[dict[str, Any]]:
-        """List supported ASNs."""
-        return await self._get_locations(
-            "asn",
-            proxy_type=(
-                int(proxy_type) if isinstance(proxy_type, ProxyType) else proxy_type
-            ),
-            country_code=country_code,
-        )
+    def _build_gateway_headers(self) -> dict[str, str]:
+        """Headers for gateway-style endpoints."""
+        self._require_public_credentials()
+        return build_public_api_headers(self.public_token or "", self.public_key or "")
 
     async def _get_locations(
         self, endpoint: str, **kwargs: Any
     ) -> list[dict[str, Any]]:
-        """Internal async locations API call."""
+        """Internal async locations API call.
+
+        Args:
+            endpoint: Location endpoint (countries, states, cities, asn).
+            **kwargs: Query parameters.
+
+        Returns:
+            List of location dictionaries.
+        """
         self._require_public_credentials()
 
         params = {
@@ -1637,21 +2249,10 @@ class AsyncThordataClient:
 
             return []
 
-    # =========================================================================
-    # Helper Methods
-    # =========================================================================
-
-    def _require_public_credentials(self) -> None:
-        """Ensure public API credentials are available."""
-        if not self.public_token or not self.public_key:
-            raise ThordataConfigError(
-                "public_token and public_key are required for this operation. "
-                "Please provide them when initializing AsyncThordataClient."
-            )
-
     def _get_proxy_endpoint_overrides(
         self, product: ProxyProduct
     ) -> tuple[str | None, int | None, str]:
+        """Get proxy endpoint overrides from environment variables."""
         prefix = product.value.upper()
 
         host = os.getenv(f"THORDATA_{prefix}_PROXY_HOST") or os.getenv(
@@ -1676,6 +2277,8 @@ class AsyncThordataClient:
         return host or None, port, protocol
 
     def _get_default_proxy_config_from_env(self) -> ProxyConfig | None:
+        """Get proxy configuration from environment variables."""
+        # Check RESIDENTIAL
         u = os.getenv("THORDATA_RESIDENTIAL_USERNAME")
         p = os.getenv("THORDATA_RESIDENTIAL_PASSWORD")
         if u and p:
@@ -1691,6 +2294,7 @@ class AsyncThordataClient:
                 protocol=protocol,
             )
 
+        # Check DATACENTER
         u = os.getenv("THORDATA_DATACENTER_USERNAME")
         p = os.getenv("THORDATA_DATACENTER_PASSWORD")
         if u and p:
@@ -1706,6 +2310,7 @@ class AsyncThordataClient:
                 protocol=protocol,
             )
 
+        # Check MOBILE
         u = os.getenv("THORDATA_MOBILE_USERNAME")
         p = os.getenv("THORDATA_MOBILE_PASSWORD")
         if u and p:
@@ -1723,11 +2328,35 @@ class AsyncThordataClient:
 
         return None
 
-    def _build_gateway_headers(self) -> dict[str, str]:
+    def get_browser_connection_url(
+        self, username: str | None = None, password: str | None = None
+    ) -> str:
         """
-        Headers for gateway-style endpoints.
+        Generate the WebSocket URL for connecting to Scraping Browser.
 
-        Per our SDK rule: ONLY public_token/public_key exist.
+        Note: This method is synchronous as it only does string formatting.
         """
-        self._require_public_credentials()
-        return build_public_api_headers(self.public_token or "", self.public_key or "")
+        user = (
+            username
+            or os.getenv("THORDATA_BROWSER_USERNAME")
+            or os.getenv("THORDATA_RESIDENTIAL_USERNAME")
+        )
+        pwd = (
+            password
+            or os.getenv("THORDATA_BROWSER_PASSWORD")
+            or os.getenv("THORDATA_RESIDENTIAL_PASSWORD")
+        )
+
+        if not user or not pwd:
+            raise ThordataConfigError(
+                "Browser credentials missing. Set THORDATA_BROWSER_USERNAME/PASSWORD or pass arguments."
+            )
+
+        prefix = "td-customer-"
+        # Fixed SIM108 (ternary operator)
+        final_user = f"{prefix}{user}" if not user.startswith(prefix) else user
+
+        safe_user = quote(final_user, safe="")
+        safe_pass = quote(pwd, safe="")
+
+        return f"wss://{safe_user}:{safe_pass}@ws-browser.thordata.com"