firecrawl 4.3.7__tar.gz → 4.5.0__tar.gz

{firecrawl-4.3.7 → firecrawl-4.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: firecrawl
-Version: 4.3.7
+Version: 4.5.0
 Summary: Python SDK for Firecrawl API
 Home-page: https://github.com/firecrawl/firecrawl
 Author: Mendable.ai

{firecrawl-4.3.7 → firecrawl-4.5.0}/firecrawl/__init__.py

@@ -17,7 +17,7 @@ from .v1 import (
     V1ChangeTrackingOptions,
 )
 
-__version__ = "4.3.7"
+__version__ = "4.5.0"
 
 # Define the logger for the Firecrawl project
 logger: logging.Logger = logging.getLogger("firecrawl")

{firecrawl-4.3.7 → firecrawl-4.5.0}/firecrawl/__tests__/unit/v2/methods/test_pagination.py

@@ -89,6 +89,40 @@ class TestCrawlPagination:
         assert result.next == "https://api.firecrawl.dev/v2/crawl/test-crawl-123?page=2"
         assert len(result.data) == 1
         assert isinstance(result.data[0], Document)
+
+    def test_get_crawl_status_propagates_request_timeout(self):
+        """Ensure request_timeout is forwarded to the HTTP client."""
+        mock_response = Mock()
+        mock_response.ok = True
+        mock_response.json.return_value = {
+            "success": True,
+            "status": "completed",
+            "completed": 1,
+            "total": 1,
+            "creditsUsed": 1,
+            "expiresAt": "2024-01-01T00:00:00Z",
+            "next": None,
+            "data": [self.sample_doc],
+        }
+
+        self.mock_client.get.return_value = mock_response
+
+        timeout_seconds = 5.5
+        import firecrawl.v2.methods.crawl as crawl_module
+
+        assert crawl_module.__file__.endswith("firecrawl/v2/methods/crawl.py")
+        assert crawl_module.get_crawl_status.__kwdefaults__ is not None
+        assert "request_timeout" in crawl_module.get_crawl_status.__kwdefaults__
+        result = get_crawl_status(
+            self.mock_client,
+            self.job_id,
+            request_timeout=timeout_seconds,
+        )
+
+        assert result.status == "completed"
+        self.mock_client.get.assert_called_with(
+            f"/v2/crawl/{self.job_id}", timeout=timeout_seconds
+        )
     
     def test_get_crawl_status_with_pagination(self):
         """Test get_crawl_status with auto_paginate=True."""
@@ -423,7 +457,42 @@ class TestAsyncPagination:
         assert result.next is None
         assert len(result.data) == 2
         assert self.mock_client.get.call_count == 2
-    
+
+    @pytest.mark.asyncio
+    async def test_get_crawl_status_async_propagates_request_timeout(self):
+        """Ensure async request_timeout is forwarded to the HTTP client."""
+        mock_response = Mock()
+        mock_response.status_code = 200
+        mock_response.json.return_value = {
+            "success": True,
+            "status": "completed",
+            "completed": 1,
+            "total": 1,
+            "creditsUsed": 1,
+            "expiresAt": "2024-01-01T00:00:00Z",
+            "next": None,
+            "data": [self.sample_doc],
+        }
+
+        self.mock_client.get.return_value = mock_response
+
+        timeout_seconds = 3.3
+        import firecrawl.v2.methods.aio.crawl as crawl_module_async
+
+        assert crawl_module_async.__file__.endswith("firecrawl/v2/methods/aio/crawl.py")
+        assert crawl_module_async.get_crawl_status.__kwdefaults__ is not None
+        assert "request_timeout" in crawl_module_async.get_crawl_status.__kwdefaults__
+        result = await get_crawl_status_async(
+            self.mock_client,
+            self.job_id,
+            request_timeout=timeout_seconds,
+        )
+
+        assert result.status == "completed"
+        self.mock_client.get.assert_awaited_with(
+            f"/v2/crawl/{self.job_id}", timeout=timeout_seconds
+        )
+
     @pytest.mark.asyncio
     async def test_get_batch_scrape_status_async_with_pagination(self):
         """Test async get_batch_scrape_status with pagination."""

{firecrawl-4.3.7 → firecrawl-4.5.0}/firecrawl/v2/client.py

@@ -54,10 +54,14 @@ from .watcher import Watcher
 class FirecrawlClient:
     """
     Main Firecrawl v2 API client.
-    
+
     This client provides a clean, modular interface to all Firecrawl functionality.
     """
-    
+
+    @staticmethod
+    def _is_cloud_service(url: str) -> bool:
+        return "api.firecrawl.dev" in url.lower()
+
     def __init__(
         self,
         api_key: Optional[str] = None,
@@ -68,7 +72,7 @@ class FirecrawlClient:
     ):
         """
         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
@@ -78,13 +82,13 @@ class FirecrawlClient:
         """
         if api_key is None:
             api_key = os.getenv("FIRECRAWL_API_KEY")
-        
-        if not api_key:
+
+        if self._is_cloud_service(api_url) and not api_key:
             raise ValueError(
-                "API key is required. Set FIRECRAWL_API_KEY environment variable "
+                "API key is required for the cloud API. Set FIRECRAWL_API_KEY environment variable "
                 "or pass api_key parameter."
             )
-        
+
         self.config = ClientConfig(
             api_key=api_key,
             api_url=api_url,
@@ -92,7 +96,7 @@ class FirecrawlClient:
             max_retries=max_retries,
             backoff_factor=backoff_factor
         )
-        
+
         self.http_client = HttpClient(api_key, api_url)
     
     def scrape(
@@ -236,6 +240,7 @@ class FirecrawlClient:
         zero_data_retention: bool = False,
         poll_interval: int = 2,
         timeout: Optional[int] = None,
+        request_timeout: Optional[float] = None,
         integration: Optional[str] = None,
     ) -> CrawlJob:
         """
@@ -259,7 +264,8 @@ class FirecrawlClient:
             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)
+            timeout: Maximum seconds to wait for the entire crawl job to complete (None for no timeout)
+            request_timeout: Timeout (in seconds) for each individual HTTP request, including pagination requests when fetching results. If there are multiple pages, each page request gets this timeout
             
         Returns:
             CrawlJob when job completes
@@ -290,10 +296,11 @@ class FirecrawlClient:
         )
         
         return crawl_module.crawl(
-            self.http_client, 
-            request, 
-            poll_interval=poll_interval, 
-            timeout=timeout
+            self.http_client,
+            request,
+            poll_interval=poll_interval,
+            timeout=timeout,
+            request_timeout=request_timeout,
         )
     
     def start_crawl(
@@ -368,9 +375,11 @@ class FirecrawlClient:
         return crawl_module.start_crawl(self.http_client, request)
     
     def get_crawl_status(
-        self, 
+        self,
         job_id: str,
-        pagination_config: Optional[PaginationConfig] = None
+        pagination_config: Optional[PaginationConfig] = None,
+        *,
+        request_timeout: Optional[float] = None,
     ) -> CrawlJob:
         """
         Get the status of a crawl job.
@@ -378,6 +387,9 @@ class FirecrawlClient:
         Args:
             job_id: ID of the crawl job
             pagination_config: Optional configuration for pagination behavior
+            request_timeout: Timeout (in seconds) for each individual HTTP request. When auto-pagination 
+                is enabled (default) and there are multiple pages of results, this timeout applies to 
+                each page request separately, not to the entire operation
             
         Returns:
             CrawlJob with current status and data
@@ -386,9 +398,10 @@ class FirecrawlClient:
             Exception: If the status check fails
         """
         return crawl_module.get_crawl_status(
-            self.http_client, 
+            self.http_client,
             job_id,
-            pagination_config=pagination_config
+            pagination_config=pagination_config,
+            request_timeout=request_timeout,
         )
     
     def get_crawl_errors(self, crawl_id: str) -> CrawlErrorsResponse:

{firecrawl-4.3.7 → firecrawl-4.5.0}/firecrawl/v2/client_async.py

@@ -4,6 +4,7 @@ Async v2 client mirroring the regular client surface using true async HTTP trans
 
 import os
 import asyncio
+import time
 from typing import Optional, List, Dict, Any, Union, Callable, Literal
 from .types import (
     ScrapeOptions,
@@ -47,11 +48,15 @@ from .methods.aio import extract as async_extract  # type: ignore[attr-defined]
 from .watcher_async import AsyncWatcher
 
 class AsyncFirecrawlClient:
+    @staticmethod
+    def _is_cloud_service(url: str) -> bool:
+        return "api.firecrawl.dev" in url.lower()
+
     def __init__(self, api_key: Optional[str] = None, api_url: str = "https://api.firecrawl.dev"):
         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 or pass api_key.")
+        if self._is_cloud_service(api_url) and not api_key:
+            raise ValueError("API key is required for the cloud API. Set FIRECRAWL_API_KEY or pass api_key.")
         self.http_client = HttpClient(api_key, api_url)
         self.async_http_client = AsyncHttpClient(api_key, api_url)
 
@@ -77,33 +82,91 @@ class AsyncFirecrawlClient:
         request = CrawlRequest(url=url, **kwargs)
         return await async_crawl.start_crawl(self.async_http_client, request)
 
-    async def wait_crawl(self, job_id: str, poll_interval: int = 2, timeout: Optional[int] = None) -> CrawlJob:
-        # simple polling loop using blocking get (ok for test-level async)
-        start = asyncio.get_event_loop().time()
+    async def wait_crawl(
+        self,
+        job_id: str,
+        poll_interval: int = 2,
+        timeout: Optional[int] = None,
+        *,
+        request_timeout: Optional[float] = None,
+    ) -> CrawlJob:
+        """
+        Polls the status of a crawl job until it reaches a terminal state.
+
+        Args:
+            job_id (str): The ID of the crawl job to poll.
+            poll_interval (int, optional): Number of seconds to wait between polling attempts. Defaults to 2.
+            timeout (Optional[int], optional): Maximum number of seconds to wait for the entire crawl job to complete before timing out. If None, waits indefinitely. Defaults to None.
+            request_timeout (Optional[float], optional): Timeout (in seconds) for each individual HTTP request, including pagination requests when fetching results. If there are multiple pages, each page request gets this timeout. If None, no per-request timeout is set. Defaults to None.
+
+        Returns:
+            CrawlJob: The final status of the crawl job when it reaches a terminal state.
+
+        Raises:
+            TimeoutError: If the crawl does not reach a terminal state within the specified timeout.
+
+        Terminal states:
+            - "completed": The crawl finished successfully.
+            - "failed": The crawl finished with an error.
+            - "cancelled": The crawl was cancelled.
+        """
+        start = time.monotonic()
         while True:
-            status = await async_crawl.get_crawl_status(self.async_http_client, job_id)
-            if status.status in ["completed", "failed"]:
+            status = await async_crawl.get_crawl_status(
+                self.async_http_client,
+                job_id,
+                request_timeout=request_timeout,
+            )
+            if status.status in ["completed", "failed", "cancelled"]:
                 return status
-            if timeout and (asyncio.get_event_loop().time() - start) > timeout:
+            if timeout and (time.monotonic() - start) > timeout:
                 raise TimeoutError("Crawl wait timed out")
             await asyncio.sleep(poll_interval)
 
     async def crawl(self, **kwargs) -> CrawlJob:
         # wrapper combining start and wait
-        resp = await self.start_crawl(**{k: v for k, v in kwargs.items() if k not in ("poll_interval", "timeout")})
+        resp = await self.start_crawl(
+            **{k: v for k, v in kwargs.items() if k not in ("poll_interval", "timeout", "request_timeout")}
+        )
         poll_interval = kwargs.get("poll_interval", 2)
         timeout = kwargs.get("timeout")
-        return await self.wait_crawl(resp.id, poll_interval=poll_interval, timeout=timeout)
+        request_timeout = kwargs.get("request_timeout")
+        effective_request_timeout = request_timeout if request_timeout is not None else timeout
+        return await self.wait_crawl(
+            resp.id,
+            poll_interval=poll_interval,
+            timeout=timeout,
+            request_timeout=effective_request_timeout,
+        )
 
     async def get_crawl_status(
-        self, 
+        self,
         job_id: str,
-        pagination_config: Optional[PaginationConfig] = None
+        pagination_config: Optional[PaginationConfig] = None,
+        *,
+        request_timeout: Optional[float] = None,
     ) -> CrawlJob:
+        """
+        Get the status of a crawl job.
+        
+        Args:
+            job_id: ID of the crawl job
+            pagination_config: Optional configuration for pagination behavior
+            request_timeout: Timeout (in seconds) for each individual HTTP request. When auto-pagination 
+                is enabled (default) and there are multiple pages of results, this timeout applies to 
+                each page request separately, not to the entire operation
+            
+        Returns:
+            CrawlJob with current status and data
+            
+        Raises:
+            Exception: If the status check fails
+        """
         return await async_crawl.get_crawl_status(
-            self.async_http_client, 
+            self.async_http_client,
             job_id,
-            pagination_config=pagination_config
+            pagination_config=pagination_config,
+            request_timeout=request_timeout,
         )
 
     async def cancel_crawl(self, job_id: str) -> bool:

{firecrawl-4.3.7 → firecrawl-4.5.0}/firecrawl/v2/methods/aio/crawl.py

@@ -87,9 +87,11 @@ async def start_crawl(client: AsyncHttpClient, request: CrawlRequest) -> CrawlRe
 
 
 async def get_crawl_status(
-    client: AsyncHttpClient, 
+    client: AsyncHttpClient,
     job_id: str,
-    pagination_config: Optional[PaginationConfig] = None
+    pagination_config: Optional[PaginationConfig] = None,
+    *,
+    request_timeout: Optional[float] = None,
 ) -> CrawlJob:
     """
     Get the status of a crawl job.
@@ -98,6 +100,9 @@ async def get_crawl_status(
         client: Async HTTP client instance
         job_id: ID of the crawl job
         pagination_config: Optional configuration for pagination limits
+        request_timeout: Timeout (in seconds) for each individual HTTP request. When auto-pagination 
+            is enabled (default) and there are multiple pages of results, this timeout applies to 
+            each page request separately, not to the entire operation
         
     Returns:
         CrawlJob with job information
@@ -105,7 +110,7 @@ async def get_crawl_status(
     Raises:
         Exception: If the status check fails
     """
-    response = await client.get(f"/v2/crawl/{job_id}")
+    response = await client.get(f"/v2/crawl/{job_id}", timeout=request_timeout)
     if response.status_code >= 400:
         handle_response_error(response, "get crawl status")
     body = response.json()
@@ -120,10 +125,11 @@ async def get_crawl_status(
         auto_paginate = pagination_config.auto_paginate if pagination_config else True
         if auto_paginate and body.get("next"):
             documents = await _fetch_all_pages_async(
-                client, 
-                body.get("next"), 
-                documents, 
-                pagination_config
+                client,
+                body.get("next"),
+                documents,
+                pagination_config,
+                request_timeout=request_timeout,
             )
         
         return CrawlJob(
@@ -142,7 +148,9 @@ async def _fetch_all_pages_async(
     client: AsyncHttpClient,
     next_url: str,
     initial_documents: List[Document],
-    pagination_config: Optional[PaginationConfig] = None
+    pagination_config: Optional[PaginationConfig] = None,
+    *,
+    request_timeout: Optional[float] = None,
 ) -> List[Document]:
     """
     Fetch all pages of crawl results asynchronously.
@@ -152,6 +160,7 @@ async def _fetch_all_pages_async(
         next_url: URL for the next page
         initial_documents: Documents from the first page
         pagination_config: Optional configuration for pagination limits
+        request_timeout: Optional timeout (in seconds) for the underlying HTTP request
         
     Returns:
         List of all documents from all pages
@@ -176,7 +185,7 @@ async def _fetch_all_pages_async(
             break
         
         # Fetch next page
-        response = await client.get(current_url)
+        response = await client.get(current_url, timeout=request_timeout)
         
         if response.status_code >= 400:
             # Log error but continue with what we have

{firecrawl-4.3.7 → firecrawl-4.5.0}/firecrawl/v2/methods/crawl.py

@@ -142,37 +142,42 @@ def start_crawl(client: HttpClient, request: CrawlRequest) -> CrawlResponse:
 
 
 def get_crawl_status(
-    client: HttpClient, 
+    client: HttpClient,
     job_id: str,
-    pagination_config: Optional[PaginationConfig] = None
+    pagination_config: Optional[PaginationConfig] = None,
+    *,
+    request_timeout: Optional[float] = None,
 ) -> CrawlJob:
     """
     Get the status of a crawl job.
-    
+
     Args:
         client: HTTP client instance
         job_id: ID of the crawl job
         pagination_config: Optional configuration for pagination behavior
-        
+        request_timeout: Timeout (in seconds) for each individual HTTP request. When auto-pagination 
+            is enabled (default) and there are multiple pages of results, this timeout applies to 
+            each page request separately, not to the entire operation
+
     Returns:
         CrawlJob with current status and data
-        
+
     Raises:
         Exception: If the status check fails
     """
     # Make the API request
-    response = client.get(f"/v2/crawl/{job_id}")
-    
+    response = client.get(f"/v2/crawl/{job_id}", timeout=request_timeout)
+
     # Handle errors
     if not response.ok:
         handle_response_error(response, "get crawl status")
-    
+
     # Parse response
     response_data = response.json()
-    
+
     if response_data.get("success"):
         # The API returns status fields at the top level, not in a data field
-        
+
         # Convert documents
         documents = []
         data_list = response_data.get("data", [])
@@ -183,17 +188,22 @@ def get_crawl_status(
                 continue
             else:
                 documents.append(Document(**normalize_document_input(doc_data)))
-        
+
         # Handle pagination if requested
         auto_paginate = pagination_config.auto_paginate if pagination_config else True
-        if auto_paginate and response_data.get("next") and not (pagination_config and pagination_config.max_results is not None and len(documents) >= pagination_config.max_results):
+        if auto_paginate and response_data.get("next") and not (
+            pagination_config
+            and pagination_config.max_results is not None
+            and len(documents) >= pagination_config.max_results
+        ):
             documents = _fetch_all_pages(
-                client, 
-                response_data.get("next"), 
-                documents, 
-                pagination_config
+                client,
+                response_data.get("next"),
+                documents,
+                pagination_config,
+                request_timeout=request_timeout,
             )
-        
+
         # Create CrawlJob with current status and data
         return CrawlJob(
             status=response_data.get("status"),
@@ -212,31 +222,34 @@ def _fetch_all_pages(
     client: HttpClient,
     next_url: str,
     initial_documents: List[Document],
-    pagination_config: Optional[PaginationConfig] = None
+    pagination_config: Optional[PaginationConfig] = None,
+    *,
+    request_timeout: Optional[float] = None,
 ) -> List[Document]:
     """
     Fetch all pages of crawl results.
-    
+
     Args:
         client: HTTP client instance
         next_url: URL for the next page
         initial_documents: Documents from the first page
         pagination_config: Optional configuration for pagination limits
-        
+        request_timeout: Optional timeout (in seconds) for the underlying HTTP request
+
     Returns:
         List of all documents from all pages
     """
     documents = initial_documents.copy()
     current_url = next_url
     page_count = 0
-    
+
     # Apply pagination limits
     max_pages = pagination_config.max_pages if pagination_config else None
     max_results = pagination_config.max_results if pagination_config else None
     max_wait_time = pagination_config.max_wait_time if pagination_config else None
-    
+
     start_time = time.monotonic()
-    
+
     while current_url:
         # Check pagination limits (treat 0 as a valid limit)
         if (max_pages is not None) and page_count >= max_pages:
@@ -244,22 +257,22 @@ def _fetch_all_pages(
 
         if (max_wait_time is not None) and (time.monotonic() - start_time) > max_wait_time:
             break
-        
+
         # Fetch next page
-        response = client.get(current_url)
-        
+        response = client.get(current_url, timeout=request_timeout)
+
         if not response.ok:
             # Log error but continue with what we have
             import logging
             logger = logging.getLogger("firecrawl")
             logger.warning("Failed to fetch next page", extra={"status_code": response.status_code})
             break
-        
+
         page_data = response.json()
-        
+
         if not page_data.get("success"):
             break
-        
+
         # Add documents from this page
         data_list = page_data.get("data", [])
         for doc_data in data_list:
@@ -270,15 +283,15 @@ def _fetch_all_pages(
                 if max_results is not None and len(documents) >= max_results:
                     break
                 documents.append(Document(**normalize_document_input(doc_data)))
-        
+
         # Check if we hit max_results limit
         if max_results is not None and len(documents) >= max_results:
             break
-        
+
         # Get next URL
         current_url = page_data.get("next")
         page_count += 1
-    
+
     return documents
 
 
@@ -309,7 +322,9 @@ def wait_for_crawl_completion(
     client: HttpClient,
     job_id: str,
     poll_interval: int = 2,
-    timeout: Optional[int] = None
+    timeout: Optional[int] = None,
+    *,
+    request_timeout: Optional[float] = None,
 ) -> CrawlJob:
     """
     Wait for a crawl job to complete, polling for status updates.
@@ -319,6 +334,7 @@ def wait_for_crawl_completion(
         job_id: ID of the crawl job
         poll_interval: Seconds between status checks
         timeout: Maximum seconds to wait (None for no timeout)
+        request_timeout: Optional timeout (in seconds) for each status request
         
     Returns:
         CrawlJob when job completes
@@ -330,7 +346,11 @@ def wait_for_crawl_completion(
     start_time = time.monotonic()
     
     while True:
-        crawl_job = get_crawl_status(client, job_id)
+        crawl_job = get_crawl_status(
+            client,
+            job_id,
+            request_timeout=request_timeout,
+        )
         
         # Check if job is complete
         if crawl_job.status in ["completed", "failed", "cancelled"]:
@@ -348,7 +368,9 @@ def crawl(
     client: HttpClient,
     request: CrawlRequest,
     poll_interval: int = 2,
-    timeout: Optional[int] = None
+    timeout: Optional[int] = None,
+    *,
+    request_timeout: Optional[float] = None,
 ) -> CrawlJob:
     """
     Start a crawl job and wait for it to complete.
@@ -357,7 +379,9 @@ def crawl(
         client: HTTP client instance
         request: CrawlRequest containing URL and options
         poll_interval: Seconds between status checks
-        timeout: Maximum seconds to wait (None for no timeout)
+        timeout: Maximum seconds to wait for the entire crawl job to complete (None for no timeout)
+        request_timeout: Timeout (in seconds) for each individual HTTP request, including pagination 
+            requests when fetching results. If there are multiple pages, each page request gets this timeout
         
     Returns:
         CrawlJob when job completes
@@ -371,9 +395,16 @@ def crawl(
     crawl_job = start_crawl(client, request)
     job_id = crawl_job.id
     
+    # Determine the per-request timeout. If not provided, reuse the overall timeout value.
+    effective_request_timeout = request_timeout if request_timeout is not None else timeout
+
     # Wait for completion
     return wait_for_crawl_completion(
-        client, job_id, poll_interval, timeout
+        client,
+        job_id,
+        poll_interval,
+        timeout,
+        request_timeout=effective_request_timeout,
     )
 
 

{firecrawl-4.3.7 → firecrawl-4.5.0}/firecrawl/v2/methods/search.py

@@ -123,7 +123,7 @@ def _validate_search_request(request: SearchRequest) -> SearchRequest:
     
     # Validate categories (if provided)
     if request.categories is not None:
-        valid_categories = {"github", "research"}
+        valid_categories = {"github", "research", "pdf"}
         for category in request.categories:
             if isinstance(category, str):
                 if category not in valid_categories:

{firecrawl-4.3.7 → firecrawl-4.5.0}/firecrawl/v2/types.py

@@ -186,7 +186,13 @@ class Source(BaseModel):
 SourceOption = Union[str, Source]
 
 class Category(BaseModel):
-    """Configuration for a search category."""
+    """Configuration for a search category.
+    
+    Supported categories:
+    - "github": Filter results to GitHub repositories
+    - "research": Filter results to research papers and academic sites
+    - "pdf": Filter results to PDF files (adds filetype:pdf to search)
+    """
     type: str
 
 CategoryOption = Union[str, Category]
@@ -762,7 +768,7 @@ class ActiveCrawlsRequest(BaseModel):
 # Configuration types
 class ClientConfig(BaseModel):
     """Configuration for the Firecrawl client."""
-    api_key: str
+    api_key: Optional[str] = None
     api_url: str = "https://api.firecrawl.dev"
     timeout: Optional[float] = None
     max_retries: int = 3

{firecrawl-4.3.7 → firecrawl-4.5.0}/firecrawl/v2/utils/http_client.py

@@ -12,8 +12,8 @@ version = get_version()
 
 class HttpClient:
     """HTTP client with retry logic and error handling."""
-    
-    def __init__(self, api_key: str, api_url: str):
+
+    def __init__(self, api_key: Optional[str], api_url: str):
         self.api_key = api_key
         self.api_url = api_url
 
@@ -43,8 +43,10 @@ class HttpClient:
         """Prepare headers for API requests."""
         headers = {
             'Content-Type': 'application/json',
-            'Authorization': f'Bearer {self.api_key}',
         }
+
+        if self.api_key:
+            headers['Authorization'] = f'Bearer {self.api_key}'
         
         if idempotency_key:
             headers['x-idempotency-key'] = idempotency_key

{firecrawl-4.3.7 → firecrawl-4.5.0}/firecrawl/v2/utils/http_client_async.py

@@ -6,15 +6,19 @@ version = get_version()
 
 
 class AsyncHttpClient:
-    def __init__(self, api_key: str, api_url: str):
+    def __init__(self, api_key: Optional[str], api_url: str):
         self.api_key = api_key
         self.api_url = api_url
+        headers = {
+            "Content-Type": "application/json",
+        }
+
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+
         self._client = httpx.AsyncClient(
             base_url=api_url,
-            headers={
-                "Authorization": f"Bearer {api_key}",
-                "Content-Type": "application/json",
-            },
+            headers=headers,
             limits=httpx.Limits(max_keepalive_connections=0),
         )
 

{firecrawl-4.3.7 → firecrawl-4.5.0}/firecrawl.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: firecrawl
-Version: 4.3.7
+Version: 4.5.0
 Summary: Python SDK for Firecrawl API
 Home-page: https://github.com/firecrawl/firecrawl
 Author: Mendable.ai

{firecrawl-4.3.7 → firecrawl-4.5.0}/firecrawl.egg-info/SOURCES.txt

@@ -80,5 +80,6 @@ firecrawl/v2/utils/http_client.py
 firecrawl/v2/utils/http_client_async.py
 firecrawl/v2/utils/normalize.py
 firecrawl/v2/utils/validation.py
+tests/test_api_key_handling.py
 tests/test_change_tracking.py
 tests/test_timeout_conversion.py

firecrawl-4.5.0/tests/test_api_key_handling.py

@@ -0,0 +1,44 @@
+import sys
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from firecrawl.v2.client import FirecrawlClient
+from firecrawl.v2.client_async import AsyncFirecrawlClient
+
+
+@pytest.fixture(autouse=True)
+def clear_firecrawl_api_key_env(monkeypatch):
+    monkeypatch.delenv("FIRECRAWL_API_KEY", raising=False)
+    yield
+
+
+def test_cloud_requires_api_key():
+    with pytest.raises(ValueError):
+        FirecrawlClient(api_url="https://api.firecrawl.dev")
+
+
+def test_self_host_allows_missing_api_key():
+    client = FirecrawlClient(api_url="http://localhost:3000")
+    assert client.http_client.api_key is None
+
+
+def test_async_cloud_requires_api_key():
+    with pytest.raises(ValueError):
+        AsyncFirecrawlClient(api_url="https://api.firecrawl.dev")
+
+
+@pytest.mark.asyncio
+async def test_async_self_host_allows_missing_api_key():
+    client = AsyncFirecrawlClient(api_url="http://localhost:3000")
+    try:
+        assert client.http_client.api_key is None
+        await client.async_http_client.close()
+    finally:
+        # Ensure the underlying HTTPX client is closed even if assertions fail
+        if not client.async_http_client._client.is_closed:
+            await client.async_http_client.close()