Added Zone Creation Endpoint and Tests

Author: vzucher

README.md

@@ -426,6 +426,57 @@ print(f"Zones: {info['zone_count']}")
 print(f"Active zones: {[z['name'] for z in info['zones']]}")
 ```
 
+### Zone Management
+
+The SDK can automatically create required zones if they don't exist, or you can manage zones manually.
+
+#### Automatic Zone Creation
+
+Enable automatic zone creation when initializing the client:
+
+```python
+client = BrightDataClient(
+    token="your_token",
+    auto_create_zones=True  # Automatically create zones if missing
+)
+
+# Zones are created on first API call
+async with client:
+    # sdk_unlocker, sdk_serp, and sdk_browser zones created automatically if needed
+    result = await client.scrape.amazon.products(url="...")
+```
+
+#### Manual Zone Management
+
+List and manage zones programmatically:
+
+```python
+# List all zones
+zones = await client.list_zones()
+zones = client.list_zones_sync()  # Synchronous version
+
+for zone in zones:
+    print(f"Zone: {zone['name']} (Type: {zone.get('type', 'unknown')})")
+
+# Advanced: Use ZoneManager directly
+from brightdata import ZoneManager
+
+async with client.engine:
+    zone_manager = ZoneManager(client.engine)
+
+    # Ensure specific zones exist
+    await zone_manager.ensure_required_zones(
+        web_unlocker_zone="my_custom_zone",
+        serp_zone="my_serp_zone"
+    )
+```
+
+**Zone Creation API:**
+- Endpoint: `POST https://api.brightdata.com/zone`
+- Zones are created via the Bright Data API
+- Supported zone types: `unblocker`, `serp`, `browser`
+- Automatically handles duplicate zones gracefully
+
 ### Result Objects
 
 All operations return rich result objects with timing and metadata:

examples/zone_management_demo.py

@@ -0,0 +1,163 @@
+"""
+Zone Management Demo - Demonstrates zone creation and management features.
+
+This example shows how to:
+1. List existing zones
+2. Enable automatic zone creation
+3. Use ZoneManager for advanced zone management
+"""
+
+import asyncio
+import os
+from brightdata import BrightDataClient, ZoneManager
+
+
+async def demo_list_zones():
+    """List all zones in the account."""
+    print("\n" + "=" * 60)
+    print("DEMO 1: List Zones")
+    print("=" * 60)
+
+    client = BrightDataClient()
+
+    # List all zones
+    zones = await client.list_zones()
+
+    print(f"\nFound {len(zones)} zones in your account:")
+    for zone in zones:
+        zone_name = zone.get('name', 'Unknown')
+        zone_type = zone.get('type', 'unknown')
+        zone_status = zone.get('status', 'unknown')
+        print(f"  - {zone_name}")
+        print(f"    Type: {zone_type}")
+        print(f"    Status: {zone_status}")
+        print()
+
+
+async def demo_auto_create_zones():
+    """Demonstrate automatic zone creation."""
+    print("\n" + "=" * 60)
+    print("DEMO 2: Automatic Zone Creation")
+    print("=" * 60)
+
+    # Create client with auto zone creation enabled
+    client = BrightDataClient(auto_create_zones=True)
+
+    print("\nClient configured with auto_create_zones=True")
+    print("Required zones will be created automatically on first API call:")
+    print("  - sdk_unlocker (Web Unlocker)")
+    print("  - sdk_serp (SERP API)")
+    print("  - sdk_browser (Browser API)")
+
+    # Zones will be created when entering context manager
+    async with client:
+        print("\n✓ Zones ensured (created if missing)")
+
+        # List zones to confirm
+        zones = await client.list_zones()
+        zone_names = [z.get('name') for z in zones]
+
+        print(f"\nZones now in account ({len(zones)} total):")
+        for name in zone_names:
+            print(f"  - {name}")
+
+
+async def demo_zone_manager_advanced():
+    """Demonstrate advanced zone management with ZoneManager."""
+    print("\n" + "=" * 60)
+    print("DEMO 3: Advanced Zone Management")
+    print("=" * 60)
+
+    client = BrightDataClient()
+
+    async with client.engine:
+        zone_manager = ZoneManager(client.engine)
+
+        print("\nUsing ZoneManager for fine-grained control...")
+
+        # List zones
+        zones = await zone_manager.list_zones()
+        print(f"\nCurrent zones: {len(zones)}")
+
+        # Ensure specific zones exist
+        print("\nEnsuring custom zones exist...")
+        print("  - my_web_unlocker (unblocker)")
+        print("  - my_serp_api (serp)")
+
+        try:
+            await zone_manager.ensure_required_zones(
+                web_unlocker_zone="my_web_unlocker",
+                serp_zone="my_serp_api"
+            )
+            print("\n✓ Zones ensured successfully")
+        except Exception as e:
+            print(f"\n✗ Zone creation failed: {e}")
+
+        # List zones again
+        zones = await zone_manager.list_zones()
+        print(f"\nZones after creation: {len(zones)}")
+        for zone in zones:
+            print(f"  - {zone.get('name')}")
+
+
+async def demo_sync_methods():
+    """Demonstrate synchronous zone listing."""
+    print("\n" + "=" * 60)
+    print("DEMO 4: Synchronous Zone Listing")
+    print("=" * 60)
+
+    client = BrightDataClient()
+
+    print("\nUsing synchronous method for convenience...")
+
+    # Synchronous version (blocks until complete)
+    zones = client.list_zones_sync()
+
+    print(f"\nFound {len(zones)} zones (synchronous call):")
+    for zone in zones[:5]:  # Show first 5
+        print(f"  - {zone.get('name')}: {zone.get('type', 'unknown')}")
+
+    if len(zones) > 5:
+        print(f"  ... and {len(zones) - 5} more")
+
+
+async def main():
+    """Run all zone management demos."""
+    print("\n" + "=" * 60)
+    print("BRIGHT DATA SDK - ZONE MANAGEMENT DEMOS")
+    print("=" * 60)
+
+    # Check for API token
+    if not os.getenv("BRIGHTDATA_API_TOKEN"):
+        print("\n⚠️  Warning: BRIGHTDATA_API_TOKEN not set")
+        print("Please set your API token as an environment variable:")
+        print("  export BRIGHTDATA_API_TOKEN='your_token_here'")
+        return
+
+    try:
+        # Demo 1: List zones
+        await demo_list_zones()
+
+        # Demo 2: Auto-create zones
+        # Note: Uncomment to test zone creation
+        # await demo_auto_create_zones()
+
+        # Demo 3: Advanced zone management
+        # Note: Uncomment to test custom zone creation
+        # await demo_zone_manager_advanced()
+
+        # Demo 4: Sync methods
+        await demo_sync_methods()
+
+        print("\n" + "=" * 60)
+        print("DEMOS COMPLETE")
+        print("=" * 60)
+
+    except Exception as e:
+        print(f"\n❌ Error running demos: {e}")
+        import traceback
+        traceback.print_exc()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

src/brightdata/__init__.py

@@ -26,8 +26,9 @@
     SSLError,
 )
 
-# Export WebUnlockerService for advanced usage
+# Export services for advanced usage
 from .api.web_unlocker import WebUnlockerService
+from .core.zone_manager import ZoneManager
 
 __all__ = [
     "__version__",
@@ -51,4 +52,5 @@
     "SSLError",
     # Services
     "WebUnlockerService",
+    "ZoneManager",
 ]

src/brightdata/client.py

@@ -20,6 +20,7 @@
     pass
 
 from .core.engine import AsyncEngine
+from .core.zone_manager import ZoneManager
 from .api.web_unlocker import WebUnlockerService
 from .api.scrape_service import ScrapeService, GenericScraper
 from .api.search_service import SearchService
@@ -134,9 +135,11 @@ def __init__(
         self._search_service: Optional[SearchService] = None
         self._crawler_service: Optional[CrawlerService] = None
         self._web_unlocker_service: Optional[WebUnlockerService] = None
+        self._zone_manager: Optional[ZoneManager] = None
         self._is_connected = False
         self._account_info: Optional[Dict[str, Any]] = None
-        
+        self._zones_ensured = False
+
         if validate_token:
             self._validate_token_sync()
 
@@ -198,8 +201,32 @@ def _validate_token_sync(self) -> None:
                 f"Failed to validate token: {str(e)}\n"
                 f"Check your token at: https://brightdata.com/cp/api_keys"
             )
-    
-    
+
+    async def _ensure_zones(self) -> None:
+        """
+        Ensure required zones exist if auto_create_zones is enabled.
+
+        This is called automatically before the first API request.
+        Only runs once per client instance.
+
+        Raises:
+            ZoneError: If zone creation fails
+            AuthenticationError: If API token lacks permissions
+        """
+        if self._zones_ensured or not self.auto_create_zones:
+            return
+
+        if self._zone_manager is None:
+            self._zone_manager = ZoneManager(self.engine)
+
+        await self._zone_manager.ensure_required_zones(
+            web_unlocker_zone=self.web_unlocker_zone,
+            serp_zone=self.serp_zone,
+            browser_zone=self.browser_zone
+        )
+        self._zones_ensured = True
+
+
     @property
     def scrape(self) -> ScrapeService:
         """
@@ -380,8 +407,34 @@ def test_connection_sync(self) -> bool:
             return asyncio.run(self.test_connection())
         except Exception:
             return False
-    
-    
+
+    async def list_zones(self) -> List[Dict[str, Any]]:
+        """
+        List all active zones in your Bright Data account.
+
+        Returns:
+            List of zone dictionaries with their configurations
+
+        Raises:
+            ZoneError: If zone listing fails
+            AuthenticationError: If authentication fails
+
+        Example:
+            >>> zones = await client.list_zones()
+            >>> print(f"Found {len(zones)} zones")
+            >>> for zone in zones:
+            ...     print(f"  - {zone['name']}: {zone.get('type', 'unknown')}")
+        """
+        async with self.engine:
+            if self._zone_manager is None:
+                self._zone_manager = ZoneManager(self.engine)
+            return await self._zone_manager.list_zones()
+
+    def list_zones_sync(self) -> List[Dict[str, Any]]:
+        """Synchronous version of list_zones()."""
+        return asyncio.run(self.list_zones())
+
+
     async def scrape_url_async(
         self,
         url: Union[str, List[str]],
@@ -419,6 +472,7 @@ def scrape_url(self, *args, **kwargs) -> Union[ScrapeResult, List[ScrapeResult]]
     async def __aenter__(self):
         """Async context manager entry."""
         await self.engine.__aenter__()
+        await self._ensure_zones()
         return self
 
     async def __aexit__(self, exc_type, exc_val, exc_tb):