firecrawl-py 3.3.1__py3-none-any.whl → 3.3.2__py3-none-any.whl

build/lib/firecrawl/v2/client.py

@@ -1,805 +0,0 @@
-"""
-Main Firecrawl v2 API client.
-
-This module provides the main client class that orchestrates all v2 functionality.
-"""
-
-import os
-from typing import Optional, List, Dict, Any, Callable, Union, Literal
-from .types import (
-    ClientConfig,
-    ScrapeOptions,
-    Document,
-    SearchRequest,
-    SearchData,
-    SourceOption,
-    CategoryOption,
-    CrawlRequest,
-    CrawlResponse,
-    CrawlJob,
-    CrawlParamsRequest,
-    CrawlParamsData,
-    WebhookConfig,
-    CrawlErrorsResponse,
-    ActiveCrawlsResponse,
-    MapOptions,
-    MapData,
-    FormatOption,
-    WaitAction,
-    ScreenshotAction,
-    ClickAction,
-    WriteAction,
-    PressAction,
-    ScrollAction,
-    ScrapeAction,
-    ExecuteJavascriptAction,
-    PDFAction,
-    Location,
-)
-from .utils.http_client import HttpClient
-from .utils.error_handler import FirecrawlError
-from .methods import scrape as scrape_module
-from .methods import crawl as crawl_module  
-from .methods import batch as batch_module
-from .methods import search as search_module
-from .methods import map as map_module
-from .methods import batch as batch_methods
-from .methods import usage as usage_methods
-from .methods import extract as extract_module
-from .watcher import Watcher
-
-class FirecrawlClient:
-    """
-    Main Firecrawl v2 API client.
-    
-    This client provides a clean, modular interface to all Firecrawl functionality.
-    """
-    
-    def __init__(
-        self,
-        api_key: Optional[str] = None,
-        api_url: str = "https://api.firecrawl.dev",
-        timeout: Optional[float] = None,
-        max_retries: int = 3,
-        backoff_factor: float = 0.5
-    ):
-        """
-        Initialize the Firecrawl client.
-        
-        Args:
-            api_key: Firecrawl API key (or set FIRECRAWL_API_KEY env var)
-            api_url: Base URL for the Firecrawl API
-            timeout: Request timeout in seconds
-            max_retries: Maximum number of retries for failed requests
-            backoff_factor: Exponential backoff factor for retries (e.g. 0.5 means wait 0.5s, then 1s, then 2s between retries)
-        """
-        if api_key is None:
-            api_key = os.getenv("FIRECRAWL_API_KEY")
-        
-        if not api_key:
-            raise ValueError(
-                "API key is required. Set FIRECRAWL_API_KEY environment variable "
-                "or pass api_key parameter."
-            )
-        
-        self.config = ClientConfig(
-            api_key=api_key,
-            api_url=api_url,
-            timeout=timeout,
-            max_retries=max_retries,
-            backoff_factor=backoff_factor
-        )
-        
-        self.http_client = HttpClient(api_key, api_url)
-    
-    def scrape(
-        self,
-        url: str,
-        *,
-        formats: Optional[List['FormatOption']] = None,
-        headers: Optional[Dict[str, str]] = None,
-        include_tags: Optional[List[str]] = None,
-        exclude_tags: Optional[List[str]] = None,
-        only_main_content: Optional[bool] = None,
-        timeout: Optional[int] = None,
-        wait_for: Optional[int] = None,
-        mobile: Optional[bool] = None,
-        parsers: Optional[List[str]] = None,
-        actions: Optional[List[Union['WaitAction', 'ScreenshotAction', 'ClickAction', 'WriteAction', 'PressAction', 'ScrollAction', 'ScrapeAction', 'ExecuteJavascriptAction', 'PDFAction']]] = None,
-        location: Optional['Location'] = None,
-        skip_tls_verification: Optional[bool] = None,
-        remove_base64_images: Optional[bool] = None,
-        fast_mode: Optional[bool] = None,
-        use_mock: Optional[str] = None,
-        block_ads: Optional[bool] = None,
-        proxy: Optional[str] = None,
-        max_age: Optional[int] = None,
-        store_in_cache: Optional[bool] = None,
-    ) -> Document:
-        """
-        Scrape a single URL and return the document.
-        Args:
-            url: URL to scrape
-            formats: List of formats to scrape
-            headers: Dictionary of headers to use
-            include_tags: List of tags to include
-            exclude_tags: List of tags to exclude
-            only_main_content: Whether to only scrape the main content
-            timeout: Timeout in seconds
-            wait_for: Wait for a specific element to be present
-            mobile: Whether to use mobile mode
-            parsers: List of parsers to use
-            actions: List of actions to perform
-            location: Location to scrape
-            skip_tls_verification: Whether to skip TLS verification
-            remove_base64_images: Whether to remove base64 images
-            fast_mode: Whether to use fast mode
-            use_mock: Whether to use mock mode
-            block_ads: Whether to block ads
-            proxy: Proxy to use
-            max_age: Maximum age of the cache
-            store_in_cache: Whether to store the result in the cache
-        Returns:
-            Document
-        """
-        options = ScrapeOptions(
-            **{k: v for k, v in dict(
-                formats=formats,
-                headers=headers,
-                include_tags=include_tags,
-                exclude_tags=exclude_tags,
-                only_main_content=only_main_content,
-                timeout=timeout,
-                wait_for=wait_for,
-                mobile=mobile,
-                parsers=parsers,
-                actions=actions,
-                location=location,
-                skip_tls_verification=skip_tls_verification,
-                remove_base64_images=remove_base64_images,
-                fast_mode=fast_mode,
-                use_mock=use_mock,
-                block_ads=block_ads,
-                proxy=proxy,
-                max_age=max_age,
-                store_in_cache=store_in_cache,
-            ).items() if v is not None}
-        ) if any(v is not None for v in [formats, headers, include_tags, exclude_tags, only_main_content, timeout, wait_for, mobile, parsers, actions, location, skip_tls_verification, remove_base64_images, fast_mode, use_mock, block_ads, proxy, max_age, store_in_cache]) else None
-        return scrape_module.scrape(self.http_client, url, options)
-
-    def search(
-        self,
-        query: str,
-        *,
-        sources: Optional[List[SourceOption]] = None,
-        categories: Optional[List[CategoryOption]] = None,
-        limit: Optional[int] = None,
-        tbs: Optional[str] = None,
-        location: Optional[str] = None,
-        ignore_invalid_urls: Optional[bool] = None,
-        timeout: Optional[int] = None,
-        scrape_options: Optional[ScrapeOptions] = None,
-    ) -> SearchData:
-        """
-        Search for documents.
-        
-        Args:
-            query: Search query string
-            limit: Maximum number of results to return (default: 5)
-            tbs: Time-based search filter
-            location: Location string for search
-            timeout: Request timeout in milliseconds (default: 60000)
-            page_options: Options for scraping individual pages
-            
-        Returns:
-            SearchData containing the search results
-        """
-        request = SearchRequest(
-            query=query,
-            sources=sources,
-            categories=categories,
-            limit=limit,
-            tbs=tbs,
-            location=location,
-            ignore_invalid_urls=ignore_invalid_urls,
-            timeout=timeout,
-            scrape_options=scrape_options,
-        )
-
-        return search_module.search(self.http_client, request)
-    
-    def crawl(
-        self,
-        url: str,
-        *,
-        prompt: Optional[str] = None,
-        exclude_paths: Optional[List[str]] = None,
-        include_paths: Optional[List[str]] = None,
-        max_discovery_depth: Optional[int] = None,
-        ignore_sitemap: bool = False,
-        ignore_query_parameters: bool = False,
-        limit: Optional[int] = None,
-        crawl_entire_domain: bool = False,
-        allow_external_links: bool = False,
-        allow_subdomains: bool = False,
-        delay: Optional[int] = None,
-        max_concurrency: Optional[int] = None,
-        webhook: Optional[Union[str, WebhookConfig]] = None,
-        scrape_options: Optional[ScrapeOptions] = None,
-        zero_data_retention: bool = False,
-        poll_interval: int = 2,
-        timeout: Optional[int] = None
-    ) -> CrawlJob:
-        """
-        Start a crawl job and wait for it to complete.
-        
-        Args:
-            url: Target URL to start crawling from
-            prompt: Optional prompt to guide the crawl
-            exclude_paths: Patterns of URLs to exclude
-            include_paths: Patterns of URLs to include
-            max_discovery_depth: Maximum depth for finding new URLs
-            ignore_sitemap: Skip sitemap.xml processing
-            ignore_query_parameters: Ignore URL parameters
-            limit: Maximum pages to crawl
-            crawl_entire_domain: Follow parent directory links
-            allow_external_links: Follow external domain links
-            allow_subdomains: Follow subdomains
-            delay: Delay in seconds between scrapes
-            max_concurrency: Maximum number of concurrent scrapes
-            webhook: Webhook configuration for notifications
-            scrape_options: Page scraping configuration
-            zero_data_retention: Whether to delete data after 24 hours
-            poll_interval: Seconds between status checks
-            timeout: Maximum seconds to wait (None for no timeout)
-            
-        Returns:
-            CrawlJob when job completes
-            
-        Raises:
-            ValueError: If request is invalid
-            Exception: If the crawl fails to start or complete
-            TimeoutError: If timeout is reached
-        """
-        request = CrawlRequest(
-            url=url,
-            prompt=prompt,
-            exclude_paths=exclude_paths,
-            include_paths=include_paths,
-            max_discovery_depth=max_discovery_depth,
-            ignore_sitemap=ignore_sitemap,
-            ignore_query_parameters=ignore_query_parameters,
-            limit=limit,
-            crawl_entire_domain=crawl_entire_domain,
-            allow_external_links=allow_external_links,
-            allow_subdomains=allow_subdomains,
-            delay=delay,
-            max_concurrency=max_concurrency,
-            webhook=webhook,
-            scrape_options=scrape_options,
-            zero_data_retention=zero_data_retention
-        )
-        
-        return crawl_module.crawl(
-            self.http_client, 
-            request, 
-            poll_interval=poll_interval, 
-            timeout=timeout
-        )
-    
-    def start_crawl(
-        self,
-        url: str,
-        *,
-        prompt: Optional[str] = None,
-        exclude_paths: Optional[List[str]] = None,
-        include_paths: Optional[List[str]] = None,
-        max_discovery_depth: Optional[int] = None,
-        ignore_sitemap: bool = False,
-        ignore_query_parameters: bool = False,
-        limit: Optional[int] = None,
-        crawl_entire_domain: bool = False,
-        allow_external_links: bool = False,
-        allow_subdomains: bool = False,
-        delay: Optional[int] = None,
-        max_concurrency: Optional[int] = None,
-        webhook: Optional[Union[str, WebhookConfig]] = None,
-        scrape_options: Optional[ScrapeOptions] = None,
-        zero_data_retention: bool = False
-    ) -> CrawlResponse:
-        """
-        Start an asynchronous crawl job.
-        
-        Args:
-            url: Target URL to start crawling from
-            prompt: Optional prompt to guide the crawl
-            exclude_paths: Patterns of URLs to exclude
-            include_paths: Patterns of URLs to include
-            max_discovery_depth: Maximum depth for finding new URLs
-            ignore_sitemap: Skip sitemap.xml processing
-            ignore_query_parameters: Ignore URL parameters
-            limit: Maximum pages to crawl
-            crawl_entire_domain: Follow parent directory links
-            allow_external_links: Follow external domain links
-            allow_subdomains: Follow subdomains
-            delay: Delay in seconds between scrapes
-            max_concurrency: Maximum number of concurrent scrapes
-            webhook: Webhook configuration for notifications
-            scrape_options: Page scraping configuration
-            zero_data_retention: Whether to delete data after 24 hours
-            
-        Returns:
-            CrawlResponse with job information
-            
-        Raises:
-            ValueError: If request is invalid
-            Exception: If the crawl operation fails to start
-        """
-        request = CrawlRequest(
-            url=url,
-            prompt=prompt,
-            exclude_paths=exclude_paths,
-            include_paths=include_paths,
-            max_discovery_depth=max_discovery_depth,
-            ignore_sitemap=ignore_sitemap,
-            ignore_query_parameters=ignore_query_parameters,
-            limit=limit,
-            crawl_entire_domain=crawl_entire_domain,
-            allow_external_links=allow_external_links,
-            allow_subdomains=allow_subdomains,
-            delay=delay,
-            max_concurrency=max_concurrency,
-            webhook=webhook,
-            scrape_options=scrape_options,
-            zero_data_retention=zero_data_retention
-        )
-        
-        return crawl_module.start_crawl(self.http_client, request)
-    
-    def get_crawl_status(self, job_id: str) -> CrawlJob:
-        """
-        Get the status of a crawl job.
-        
-        Args:
-            job_id: ID of the crawl job
-            
-        Returns:
-            CrawlJob with current status and data
-            
-        Raises:
-            Exception: If the status check fails
-        """
-        return crawl_module.get_crawl_status(self.http_client, job_id)
-    
-    def get_crawl_errors(self, crawl_id: str) -> CrawlErrorsResponse:
-        """
-        Retrieve error details and robots.txt blocks for a given crawl job.
-        
-        Args:
-            crawl_id: The ID of the crawl job
-        
-        Returns:
-            CrawlErrorsResponse containing per-URL errors and robots-blocked URLs
-        """
-        return crawl_module.get_crawl_errors(self.http_client, crawl_id)
-    
-    def get_active_crawls(self) -> ActiveCrawlsResponse:
-        """
-        Get a list of currently active crawl jobs.
-        
-        Returns:
-            ActiveCrawlsResponse containing a list of active crawl jobs.
-        """
-        return crawl_module.get_active_crawls(self.http_client)
-    
-    def active_crawls(self) -> ActiveCrawlsResponse:
-        """
-        List currently active crawl jobs for the authenticated team.
-        
-        Returns:
-            ActiveCrawlsResponse containing the list of active crawl jobs
-        """
-        return self.get_active_crawls()
-
-    def map(
-        self,
-        url: str,
-        *,
-        search: Optional[str] = None,
-        include_subdomains: Optional[bool] = None,
-        limit: Optional[int] = None,
-        sitemap: Optional[Literal["only", "include", "skip"]] = None,
-        timeout: Optional[int] = None,
-    ) -> MapData:
-        """Map a URL and return discovered links.
-
-        Args:
-            url: Root URL to explore
-            search: Optional substring filter for discovered links
-            include_subdomains: Whether to include subdomains
-            limit: Maximum number of links to return
-            sitemap: Sitemap usage mode ("only" | "include" | "skip")
-            timeout: Request timeout in milliseconds
-
-        Returns:
-            MapData containing the discovered links
-        """
-        options = MapOptions(
-            search=search,
-            include_subdomains=include_subdomains,
-            limit=limit,
-            sitemap=sitemap if sitemap is not None else "include",
-            timeout=timeout,
-        ) if any(v is not None for v in [search, include_subdomains, limit, sitemap, timeout]) else None
-
-        return map_module.map(self.http_client, url, options)
-    
-    def cancel_crawl(self, crawl_id: str) -> bool:
-        """
-        Cancel a crawl job.
-        
-        Args:
-            crawl_id: The ID of the crawl job to cancel
-            
-        Returns:
-            bool: True if the crawl was cancelled, False otherwise
-        """
-        return crawl_module.cancel_crawl(self.http_client, crawl_id)
-
-    def crawl_params_preview(self, url: str, prompt: str) -> CrawlParamsData:
-        """Derive crawl parameters from natural-language prompt.
-
-        Args:
-            url: Root URL
-            prompt: Instruction describing how to crawl
-
-        Returns:
-            CrawlParamsData with normalized crawl configuration
-        """
-        request = CrawlParamsRequest(url=url, prompt=prompt)
-        return crawl_module.crawl_params_preview(self.http_client, request)
-
-    def start_extract(
-        self,
-        urls: Optional[List[str]] = None,
-        *,
-        prompt: Optional[str] = None,
-        schema: Optional[Dict[str, Any]] = None,
-        system_prompt: Optional[str] = None,
-        allow_external_links: Optional[bool] = None,
-        enable_web_search: Optional[bool] = None,
-        show_sources: Optional[bool] = None,
-        scrape_options: Optional['ScrapeOptions'] = None,
-        ignore_invalid_urls: Optional[bool] = None,
-    ):
-        """Start an extract job (non-blocking).
-
-        Args:
-            urls: URLs to extract from (optional)
-            prompt: Natural-language instruction for extraction
-            schema: Target JSON schema for the output
-            system_prompt: Optional system instruction
-            allow_external_links: Allow hyperlinks in output
-            enable_web_search: Whether to augment with web search
-            show_sources: Include per-field/source mapping when available
-            scrape_options: Scrape options applied prior to extraction
-            ignore_invalid_urls: Skip invalid URLs instead of failing
-
-        Returns:
-            Response payload with job id/status (poll with get_extract_status)
-        """
-        return extract_module.start_extract(
-            self.http_client,
-            urls,
-            prompt=prompt,
-            schema=schema,
-            system_prompt=system_prompt,
-            allow_external_links=allow_external_links,
-            enable_web_search=enable_web_search,
-            show_sources=show_sources,
-            scrape_options=scrape_options,
-            ignore_invalid_urls=ignore_invalid_urls,
-        )
-
-    def extract(
-        self,
-        urls: Optional[List[str]] = None,
-        *,
-        prompt: Optional[str] = None,
-        schema: Optional[Dict[str, Any]] = None,
-        system_prompt: Optional[str] = None,
-        allow_external_links: Optional[bool] = None,
-        enable_web_search: Optional[bool] = None,
-        show_sources: Optional[bool] = None,
-        scrape_options: Optional['ScrapeOptions'] = None,
-        ignore_invalid_urls: Optional[bool] = None,
-        poll_interval: int = 2,
-        timeout: Optional[int] = None,
-    ):
-        """Extract structured data and wait until completion.
-
-        Args:
-            urls: URLs to extract from (optional)
-            prompt: Natural-language instruction for extraction
-            schema: Target JSON schema for the output
-            system_prompt: Optional system instruction
-            allow_external_links: Allow hyperlinks in output
-            enable_web_search: Whether to augment with web search
-            show_sources: Include per-field/source mapping when available
-            scrape_options: Scrape options applied prior to extraction
-            ignore_invalid_urls: Skip invalid URLs instead of failing
-            poll_interval: Seconds between status checks
-            timeout: Maximum seconds to wait (None for no timeout)
-
-        Returns:
-            Final extract response when completed
-        """
-        return extract_module.extract(
-            self.http_client,
-            urls,
-            prompt=prompt,
-            schema=schema,
-            system_prompt=system_prompt,
-            allow_external_links=allow_external_links,
-            enable_web_search=enable_web_search,
-            show_sources=show_sources,
-            scrape_options=scrape_options,
-            ignore_invalid_urls=ignore_invalid_urls,
-            poll_interval=poll_interval,
-            timeout=timeout,
-        )
-
-    def start_batch_scrape(
-        self,
-        urls: List[str],
-        *,
-        formats: Optional[List['FormatOption']] = None,
-        headers: Optional[Dict[str, str]] = None,
-        include_tags: Optional[List[str]] = None,
-        exclude_tags: Optional[List[str]] = None,
-        only_main_content: Optional[bool] = None,
-        timeout: Optional[int] = None,
-        wait_for: Optional[int] = None,
-        mobile: Optional[bool] = None,
-        parsers: Optional[List[str]] = None,
-        actions: Optional[List[Union['WaitAction', 'ScreenshotAction', 'ClickAction', 'WriteAction', 'PressAction', 'ScrollAction', 'ScrapeAction', 'ExecuteJavascriptAction', 'PDFAction']]] = None,
-        location: Optional['Location'] = None,
-        skip_tls_verification: Optional[bool] = None,
-        remove_base64_images: Optional[bool] = None,
-        fast_mode: Optional[bool] = None,
-        use_mock: Optional[str] = None,
-        block_ads: Optional[bool] = None,
-        proxy: Optional[str] = None,
-        max_age: Optional[int] = None,
-        store_in_cache: Optional[bool] = None,
-        webhook: Optional[Union[str, WebhookConfig]] = None,
-        append_to_id: Optional[str] = None,
-        ignore_invalid_urls: Optional[bool] = None,
-        max_concurrency: Optional[int] = None,
-        zero_data_retention: Optional[bool] = None,
-        integration: Optional[str] = None,
-        idempotency_key: Optional[str] = None,
-    ):
-        """Start a batch scrape job over multiple URLs (non-blocking).
-
-        Args:
-            urls: List of URLs to scrape
-            formats: Output formats to collect per URL
-            headers: HTTP headers
-            include_tags: HTML tags to include
-            exclude_tags: HTML tags to exclude
-            only_main_content: Restrict scraping to main content
-            timeout: Per-request timeout in milliseconds
-            wait_for: Wait condition in milliseconds
-            mobile: Emulate mobile viewport
-            parsers: Parser list (e.g., ["pdf"]) 
-            actions: Browser actions to perform
-            location: Location settings
-            skip_tls_verification: Skip TLS verification
-            remove_base64_images: Remove base64 images from output
-            fast_mode: Prefer faster scraping modes
-            use_mock: Use a mock data source (internal/testing)
-            block_ads: Block ads during scraping
-            proxy: Proxy setting
-            max_age: Cache max age
-            store_in_cache: Whether to store results in cache
-            webhook: Webhook configuration
-            append_to_id: Append to an existing batch job
-            ignore_invalid_urls: Skip invalid URLs without failing
-            max_concurrency: Max concurrent scrapes
-            zero_data_retention: Delete data after 24 hours
-            integration: Integration tag/name
-            idempotency_key: Header used to deduplicate starts
-
-        Returns:
-            Response payload with job id (poll with get_batch_scrape_status)
-        """
-        options = ScrapeOptions(
-            **{k: v for k, v in dict(
-                formats=formats,
-                headers=headers,
-                include_tags=include_tags,
-                exclude_tags=exclude_tags,
-                only_main_content=only_main_content,
-                timeout=timeout,
-                wait_for=wait_for,
-                mobile=mobile,
-                parsers=parsers,
-                actions=actions,
-                location=location,
-                skip_tls_verification=skip_tls_verification,
-                remove_base64_images=remove_base64_images,
-                fast_mode=fast_mode,
-                use_mock=use_mock,
-                block_ads=block_ads,
-                proxy=proxy,
-                max_age=max_age,
-                store_in_cache=store_in_cache,
-            ).items() if v is not None}
-        ) if any(v is not None for v in [formats, headers, include_tags, exclude_tags, only_main_content, timeout, wait_for, mobile, parsers, actions, location, skip_tls_verification, remove_base64_images, fast_mode, use_mock, block_ads, proxy, max_age, store_in_cache]) else None
-
-        return batch_module.start_batch_scrape(
-            self.http_client,
-            urls,
-            options=options,
-            webhook=webhook,
-            append_to_id=append_to_id,
-            ignore_invalid_urls=ignore_invalid_urls,
-            max_concurrency=max_concurrency,
-            zero_data_retention=zero_data_retention,
-            integration=integration,
-            idempotency_key=idempotency_key,
-        )
-
-    def get_batch_scrape_status(self, job_id: str):
-        """Get current status and any scraped data for a batch job.
-
-        Args:
-            job_id: Batch job ID
-
-        Returns:
-            Status payload including counts and partial data
-        """
-        return batch_module.get_batch_scrape_status(self.http_client, job_id)
-
-    def cancel_batch_scrape(self, job_id: str) -> bool:
-        """Cancel a running batch scrape job.
-
-        Args:
-            job_id: Batch job ID
-
-        Returns:
-            True if the job was cancelled
-        """
-        return batch_module.cancel_batch_scrape(self.http_client, job_id)
-
-    def get_batch_scrape_errors(self, job_id: str):
-        """Retrieve error details for a batch scrape job.
-
-        Args:
-            job_id: Batch job ID
-
-        Returns:
-            Errors and robots-blocked URLs for the job
-        """
-        return batch_methods.get_batch_scrape_errors(self.http_client, job_id)
-
-    def get_extract_status(self, job_id: str):
-        """Get the current status (and data if completed) of an extract job.
-
-        Args:
-            job_id: Extract job ID
-
-        Returns:
-            Extract response payload with status and optional data
-        """
-        return extract_module.get_extract_status(self.http_client, job_id)
-
-    def get_concurrency(self):
-        """Get current concurrency and maximum allowed for this team/key (v2)."""
-        return usage_methods.get_concurrency(self.http_client)
-
-    def get_credit_usage(self):
-        """Get remaining credits for this team/key (v2)."""
-        return usage_methods.get_credit_usage(self.http_client)
-
-    def get_token_usage(self):
-        """Get recent token usage metrics (v2)."""
-        return usage_methods.get_token_usage(self.http_client)
-
-    def watcher(
-        self,
-        job_id: str,
-        *,
-        kind: Literal["crawl", "batch"] = "crawl",
-        poll_interval: int = 2,
-        timeout: Optional[int] = None,
-    ) -> Watcher:
-        """Create a watcher for crawl or batch jobs.
-
-        Args:
-            job_id: Job ID to watch
-            kind: Job kind ("crawl" or "batch")
-            poll_interval: Seconds between status checks
-            timeout: Maximum seconds to watch (None for no timeout)
-
-        Returns:
-            Watcher instance
-        """
-        return Watcher(self, job_id, kind=kind, poll_interval=poll_interval, timeout=timeout)
-
-    def batch_scrape(
-        self,
-        urls: List[str],
-        *,
-        formats: Optional[List['FormatOption']] = None,
-        headers: Optional[Dict[str, str]] = None,
-        include_tags: Optional[List[str]] = None,
-        exclude_tags: Optional[List[str]] = None,
-        only_main_content: Optional[bool] = None,
-        timeout: Optional[int] = None,
-        wait_for: Optional[int] = None,
-        mobile: Optional[bool] = None,
-        parsers: Optional[List[str]] = None,
-        actions: Optional[List[Union['WaitAction', 'ScreenshotAction', 'ClickAction', 'WriteAction', 'PressAction', 'ScrollAction', 'ScrapeAction', 'ExecuteJavascriptAction', 'PDFAction']]] = None,
-        location: Optional['Location'] = None,
-        skip_tls_verification: Optional[bool] = None,
-        remove_base64_images: Optional[bool] = None,
-        fast_mode: Optional[bool] = None,
-        use_mock: Optional[str] = None,
-        block_ads: Optional[bool] = None,
-        proxy: Optional[str] = None,
-        max_age: Optional[int] = None,
-        store_in_cache: Optional[bool] = None,
-        webhook: Optional[Union[str, WebhookConfig]] = None,
-        append_to_id: Optional[str] = None,
-        ignore_invalid_urls: Optional[bool] = None,
-        max_concurrency: Optional[int] = None,
-        zero_data_retention: Optional[bool] = None,
-        integration: Optional[str] = None,
-        idempotency_key: Optional[str] = None,
-        poll_interval: int = 2,
-        wait_timeout: Optional[int] = None,
-    ):
-        """
-        Start a batch scrape job and wait until completion.
-        """
-        options = ScrapeOptions(
-            **{k: v for k, v in dict(
-                formats=formats,
-                headers=headers,
-                include_tags=include_tags,
-                exclude_tags=exclude_tags,
-                only_main_content=only_main_content,
-                timeout=timeout,
-                wait_for=wait_for,
-                mobile=mobile,
-                parsers=parsers,
-                actions=actions,
-                location=location,
-                skip_tls_verification=skip_tls_verification,
-                remove_base64_images=remove_base64_images,
-                fast_mode=fast_mode,
-                use_mock=use_mock,
-                block_ads=block_ads,
-                proxy=proxy,
-                max_age=max_age,
-                store_in_cache=store_in_cache,
-            ).items() if v is not None}
-        ) if any(v is not None for v in [formats, headers, include_tags, exclude_tags, only_main_content, timeout, wait_for, mobile, parsers, actions, location, skip_tls_verification, remove_base64_images, fast_mode, use_mock, block_ads, proxy, max_age, store_in_cache]) else None
-
-        return batch_module.batch_scrape(
-            self.http_client,
-            urls,
-            options=options,
-            webhook=webhook,
-            append_to_id=append_to_id,
-            ignore_invalid_urls=ignore_invalid_urls,
-            max_concurrency=max_concurrency,
-            zero_data_retention=zero_data_retention,
-            integration=integration,
-            idempotency_key=idempotency_key,
-            poll_interval=poll_interval,
-            timeout=wait_timeout,
-        )
-