done

Author: vzucher

README.md

@@ -106,12 +106,15 @@ from brightdata import BrightDataClient
 # Initialize client (auto-loads token from environment)
 client = BrightDataClient()
 
-# Scrape any website
+# Scrape any website (sync wrapper)
 result = client.scrape.generic.url("https://example.com")
 
-print(f"Success: {result.success}")
-print(f"Data: {result.data[:200]}...")
-print(f"Time: {result.elapsed_ms():.2f}ms")
+if result.success:
+    print(f"Success: {result.success}")
+    print(f"Data: {result.data[:200]}...")
+    print(f"Time: {result.elapsed_ms():.2f}ms")
+else:
+    print(f"Error: {result.error}")
 ```
 
 ### Using Dataclass Payloads (Type-Safe ✨)
@@ -180,7 +183,6 @@ df.to_csv('products.csv', index=False)
 # Scrape specific product URLs
 result = client.scrape.amazon.products(
     url="https://amazon.com/dp/B0CRMZHDG8",
-    sync=True,
     timeout=65
 )
 
@@ -203,8 +205,7 @@ result = client.scrape.amazon.sellers(
 ```python
 # URL-based extraction
 result = client.scrape.linkedin.profiles(
-    url="https://linkedin.com/in/johndoe",
-    sync=True
+    url="https://linkedin.com/in/johndoe"
 )
 
 result = client.scrape.linkedin.jobs(
@@ -242,18 +243,17 @@ result = client.search.linkedin.posts(
 #### ChatGPT Interactions
 
 ```python
-# Send prompts to ChatGPT
-result = client.search.chatGPT(
+# Send single prompt to ChatGPT
+result = client.scrape.chatgpt.prompt(
     prompt="Explain Python async programming",
     country="us",
-    webSearch=True,
-    sync=True
+    web_search=True
 )
 
 # Batch prompts
-result = client.search.chatGPT(
-    prompt=["What is Python?", "What is JavaScript?", "Compare them"],
-    webSearch=[False, False, True]
+result = client.scrape.chatgpt.prompts(
+    prompts=["What is Python?", "What is JavaScript?", "Compare them"],
+    web_searches=[False, False, True]
 )
 ```
 
@@ -377,11 +377,14 @@ result = client.search.yandex(
 
 ### Async Usage
 
+For better performance with multiple operations, use async:
+
 ```python
 import asyncio
 from brightdata import BrightDataClient
 
 async def scrape_multiple():
+    # Use async context manager for engine lifecycle
     async with BrightDataClient() as client:
         # Scrape multiple URLs concurrently
         results = await client.scrape.generic.url_async([
@@ -391,11 +394,13 @@ async def scrape_multiple():
         ])
 
         for result in results:
-            print(f"{result.url}: {result.success}")
+            print(f"Success: {result.success}")
 
 asyncio.run(scrape_multiple())
 ```
 
+**Important:** When using `*_async` methods, always use the async context manager (`async with BrightDataClient() as client`). Sync wrappers (methods without `_async`) handle this automatically.
+
 ---
 
 ## 🆕 What's New in v26.11.24
@@ -454,7 +459,7 @@ client.scrape.generic.url(url="...")
 client.search.linkedin.jobs(keyword="...", location="...")
 client.search.instagram.posts(url="...", num_of_posts=10)
 client.search.google(query="...")
-client.search.chatGPT(prompt="...")
+client.scrape.chatgpt.prompt(prompt="...")
 
 # Direct service access (advanced)
 client.web_unlocker.fetch(url="...")
@@ -600,9 +605,9 @@ The SDK includes a powerful CLI tool:
 # Help
 brightdata --help
 
-# Scrape Amazon product
+# Scrape Amazon product (URL is positional argument)
 brightdata scrape amazon products \
-  --url "https://amazon.com/dp/B0CRMZHDG8" \
+  "https://amazon.com/dp/B0CRMZHDG8" \
   --output-format json
 
 # Search LinkedIn jobs
@@ -612,14 +617,14 @@ brightdata search linkedin jobs \
   --remote \
   --output-file jobs.json
 
-# Search Google
+# Search Google (query is positional argument)
 brightdata search google \
-  --query "python tutorial" \
+  "python tutorial" \
   --location "United States"
 
-# Generic web scraping
+# Generic web scraping (URL is positional argument)
 brightdata scrape generic \
-  --url "https://example.com" \
+  "https://example.com" \
   --output-format pretty
 ```
 
@@ -799,8 +804,7 @@ result = client.scrape.amazon.reviews(
     url="https://amazon.com/dp/B123",
     pastDays=7,              # Last 7 days only
     keyWord="quality",       # Filter by keyword
-    numOfReviews=50,         # Limit to 50 reviews
-    sync=True
+    numOfReviews=50          # Limit to 50 reviews
 )
 
 # LinkedIn jobs with extensive filters
@@ -816,24 +820,31 @@ result = client.search.linkedin.jobs(
 )
 ```
 
-### Sync vs Async Modes
+### Sync vs Async Methods
 
 ```python
-# Sync mode (default) - immediate response
+# Sync wrapper - for simple scripts (blocks until complete)
 result = client.scrape.linkedin.profiles(
     url="https://linkedin.com/in/johndoe",
-    sync=True,      # Immediate response (faster but limited timeout)
-    timeout=65      # Max 65 seconds
+    timeout=300      # Max wait time in seconds
 )
 
-# Async mode - polling for long operations
-result = client.scrape.linkedin.profiles(
-    url="https://linkedin.com/in/johndoe",
-    sync=False,     # Trigger + poll (can wait longer)
-    timeout=300     # Max 5 minutes
-)
+# Async method - for concurrent operations (requires async context)
+import asyncio
+
+async def scrape_profiles():
+    async with BrightDataClient() as client:
+        result = await client.scrape.linkedin.profiles_async(
+            url="https://linkedin.com/in/johndoe",
+            timeout=300
+        )
+        return result
+
+result = asyncio.run(scrape_profiles())
 ```
 
+**Note:** Sync wrappers (e.g., `profiles()`) internally use `asyncio.run()` and cannot be called from within an existing async context. Use `*_async` methods when you're already in an async function.
+
 ### SSL Certificate Error Handling
 
 The SDK includes comprehensive SSL error handling with platform-specific guidance:
@@ -1100,11 +1111,10 @@ if client.test_connection_sync():
     )
 
     if product.success:
-        print(f"Product: {product.data['title']}")
-        print(f"Price: {product.data['price']}")
-        print(f"Rating: {product.data['rating']}")
+        print(f"Product: {product.data[0]['title']}")
+        print(f"Price: {product.data[0]['final_price']}")
+        print(f"Rating: {product.data[0]['rating']}")
         print(f"Cost: ${product.cost:.4f}")
-        print(f"Method: {product.method}")  # "web_scraper", "web_unlocker", etc.
 
     # Search LinkedIn jobs
     jobs = client.search.linkedin.jobs(
@@ -1113,25 +1123,28 @@ if client.test_connection_sync():
         remote=True
     )
 
-    print(f"Found {jobs.row_count} jobs")
+    if jobs.success:
+        print(f"Found {len(jobs.data)} jobs")
 
     # Scrape Facebook posts
     fb_posts = client.scrape.facebook.posts_by_profile(
-        url="https://facebook.com/profile",
+        url="https://facebook.com/zuck",
         num_of_posts=10,
         timeout=240
     )
 
-    print(f"Scraped {len(fb_posts.data)} Facebook posts")
+    if fb_posts.success:
+        print(f"Scraped {len(fb_posts.data)} Facebook posts")
 
     # Scrape Instagram profile
     ig_profile = client.scrape.instagram.profiles(
-        url="https://instagram.com/username",
+        url="https://instagram.com/instagram",
         timeout=240
     )
 
-    print(f"Profile: {ig_profile.data['username']}")
-    print(f"Followers: {ig_profile.data['followers']}")
+    if ig_profile.success:
+        print(f"Profile: {ig_profile.data[0]['username']}")
+        print(f"Followers: {ig_profile.data[0]['followers_count']}")
 
     # Search Google
     search_results = client.search.google(
@@ -1140,8 +1153,9 @@ if client.test_connection_sync():
         num_results=10
     )
 
-    for i, item in enumerate(search_results.data, 1):
-        print(f"{i}. {item['title']}")
+    if search_results.success:
+        for i, item in enumerate(search_results.data[:5], 1):
+            print(f"{i}. {item.get('title', 'N/A')}")
 ```
 
 ### Interactive CLI Demo

src/brightdata/scrapers/chatgpt/scraper.py

@@ -157,13 +157,11 @@ async def prompt_trigger_async(
             dataset_id=self.DATASET_ID
         )
 
-        sdk_function = get_caller_function_name()
-        
         return ScrapeJob(
             snapshot_id=snapshot_id,
-            scraper=self,
-            dataset_id=self.DATASET_ID,
-            sdk_function=sdk_function or "prompt_trigger"
+            api_client=self.api_client,
+            platform_name=self.PLATFORM_NAME,
+            cost_per_record=self.COST_PER_RECORD,
         )
 
     def prompt_trigger(
@@ -307,13 +305,11 @@ async def prompts_trigger_async(
             dataset_id=self.DATASET_ID
         )
 
-        sdk_function = get_caller_function_name()
-        
         return ScrapeJob(
             snapshot_id=snapshot_id,
-            scraper=self,
-            dataset_id=self.DATASET_ID,
-            sdk_function=sdk_function or "prompts_trigger"
+            api_client=self.api_client,
+            platform_name=self.PLATFORM_NAME,
+            cost_per_record=self.COST_PER_RECORD,
         )
 
     def prompts_trigger(

src/brightdata/scrapers/facebook/scraper.py

@@ -165,9 +165,9 @@ async def posts_by_profile_trigger_async(
 
         return ScrapeJob(
             snapshot_id=snapshot_id,
-            scraper=self,
-            dataset_id=self.DATASET_ID_POSTS_PROFILE,
-            sdk_function=sdk_function or "posts_by_profile_trigger"
+            api_client=self.api_client,
+            platform_name=self.PLATFORM_NAME,
+            cost_per_record=self.COST_PER_RECORD,
         )
 
     def posts_by_profile_trigger(self, url: Union[str, List[str]], **kwargs) -> "ScrapeJob":
@@ -266,7 +266,12 @@ async def posts_by_group_trigger_async(self, url: Union[str, List[str]], **kwarg
         url_list = [url] if isinstance(url, str) else url
         payload = [{"url": u, **{k: v for k, v in kwargs.items() if v is not None}} for u in url_list]
         snapshot_id = await self.api_client.trigger(payload=payload, dataset_id=self.DATASET_ID_POSTS_GROUP)
-        return ScrapeJob(snapshot_id=snapshot_id, scraper=self, dataset_id=self.DATASET_ID_POSTS_GROUP, sdk_function=sdk_function or "posts_by_group_trigger")
+        return ScrapeJob(
+            snapshot_id=snapshot_id,
+            api_client=self.api_client,
+            platform_name=self.PLATFORM_NAME,
+            cost_per_record=self.COST_PER_RECORD,
+        )
 
     def posts_by_group_trigger(self, url: Union[str, List[str]], **kwargs) -> "ScrapeJob":
         """Trigger Facebook posts by group scrape (sync wrapper)."""
@@ -442,7 +447,12 @@ async def comments_trigger_async(self, url: Union[str, List[str]], **kwargs) ->
         url_list = [url] if isinstance(url, str) else url
         payload = [{"url": u, **{k: v for k, v in kwargs.items() if v is not None}} for u in url_list]
         snapshot_id = await self.api_client.trigger(payload=payload, dataset_id=self.DATASET_ID_COMMENTS)
-        return ScrapeJob(snapshot_id=snapshot_id, scraper=self, dataset_id=self.DATASET_ID_COMMENTS, sdk_function=sdk_function or "comments_trigger")
+        return ScrapeJob(
+            snapshot_id=snapshot_id,
+            api_client=self.api_client,
+            platform_name=self.PLATFORM_NAME,
+            cost_per_record=self.COST_PER_RECORD,
+        )
 
     def comments_trigger(self, url: Union[str, List[str]], **kwargs) -> "ScrapeJob":
         """Trigger Facebook comments scrape (sync wrapper)."""
@@ -540,7 +550,12 @@ async def reels_trigger_async(self, url: Union[str, List[str]], **kwargs) -> "Sc
         url_list = [url] if isinstance(url, str) else url
         payload = [{"url": u, **{k: v for k, v in kwargs.items() if v is not None}} for u in url_list]
         snapshot_id = await self.api_client.trigger(payload=payload, dataset_id=self.DATASET_ID_REELS)
-        return ScrapeJob(snapshot_id=snapshot_id, scraper=self, dataset_id=self.DATASET_ID_REELS, sdk_function=sdk_function or "reels_trigger")
+        return ScrapeJob(
+            snapshot_id=snapshot_id,
+            api_client=self.api_client,
+            platform_name=self.PLATFORM_NAME,
+            cost_per_record=self.COST_PER_RECORD,
+        )
 
     def reels_trigger(self, url: Union[str, List[str]], **kwargs) -> "ScrapeJob":
         """Trigger Facebook reels scrape (sync wrapper)."""