ghostcrawl 2.2.3__tar.gz → 2.3.0__tar.gz

ghostcrawl-2.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GhostCrawl, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{ghostcrawl-2.2.3/ghostcrawl.egg-info → ghostcrawl-2.3.0}/PKG-INFO

@@ -1,14 +1,14 @@
 Metadata-Version: 2.4
 Name: ghostcrawl
-Version: 2.2.3
+Version: 2.3.0
 Summary: Official Python SDK for the Ghostcrawl local orchestration API.
 Author: Ghostcrawl
-License: Proprietary — see LICENSE
+License: MIT
 Project-URL: Homepage, https://github.com/ghostcrawl/ghostcrawl
 Keywords: ghostcrawl,scraping,browser,automation,agent
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
-Classifier: License :: Other/Proprietary License
+Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
@@ -45,26 +45,42 @@ pip install ghostcrawl
 
 Requires Python 3.10+. Runtime dependencies: `httpx>=0.28.1`.
 
+> The client is **async** — every request method is a coroutine. Call them with
+> `await` inside an `async` function and drive it with `asyncio.run(...)`.
+
 ## Quickstart
 
 ```python
+import asyncio
 from ghostcrawl import GhostcrawlClient
 
-# Reads GHOSTCRAWL_API_KEY from environment, or pass token= explicitly
-client = GhostcrawlClient(token="gck_live_YOUR_KEY")
-
-# Scrape a URL
-result = client.scrape(url="https://example.com", format="markdown")
-print(result["content"])
-
-# Start a crawl
-run = client.crawl_runs.start(url="https://example.com", max_depth=2, max_pages=50)
-print(run["run_id"])
-
-# Web search
-results = client.search(query="latest AI research", engine="google", limit=10)
-for r in results["results"]:
-    print(r["title"], r["url"])
+async def main():
+    # Reads GHOSTCRAWL_API_KEY from environment, or pass token= explicitly
+    async with GhostcrawlClient(token="gck_live_YOUR_KEY") as client:
+        # Scrape a URL
+        result = await client.scrape(url="https://example.com", format="markdown")
+        print(result["content"])
+
+        # Start a crawl and wait for it to finish — EVENT-DRIVEN: the server
+        # blocks until the run is terminal (completed/failed/cancelled) or the
+        # timeout elapses, then returns the run. No client-side poll loop.
+        run = await client.crawl_runs.start(
+            url="https://example.com", max_depth=2, max_pages=50,
+            wait=True, wait_timeout=300,
+        )
+        print(run["run_id"], run["status"])
+
+        # Already have a run_id? Long-poll it to completion the same way:
+        #   run = await client.crawl_runs.wait(run_id, timeout=300)
+        # Or skip waiting entirely and get notified via a webhook (see Webhooks)
+        # by omitting wait= and registering a delivery URL with client.webhooks.
+
+        # Web search
+        results = await client.search(query="latest AI research", engine="google", limit=10)
+        for r in results["results"]:
+            print(r["title"], r["url"])
+
+asyncio.run(main())
 ```
 
 ## Authentication
@@ -86,71 +102,86 @@ Every request sends `Authorization: Bearer <token>`. This is the only auth schem
 ## Extract structured data
 
 ```python
+import asyncio
 from ghostcrawl import GhostcrawlClient
 
-client = GhostcrawlClient(token="gck_live_YOUR_KEY")
-
-# Define a schema and extract matching data
-data = client.extract(
-    url="https://example.com/product",
-    schema={
-        "type": "object",
-        "properties": {
-            "name": {"type": "string"},
-            "price": {"type": "number"},
-            "description": {"type": "string"},
-        },
-    },
-)
-print(data["name"], data["price"])
+async def main():
+    async with GhostcrawlClient(token="gck_live_YOUR_KEY") as client:
+        # Define a schema and extract matching data
+        data = await client.extract(
+            url="https://example.com/product",
+            schema={
+                "type": "object",
+                "properties": {
+                    "name": {"type": "string"},
+                    "price": {"type": "number"},
+                    "description": {"type": "string"},
+                },
+            },
+        )
+        print(data["name"], data["price"])
+
+asyncio.run(main())
 ```
 
 ## Browser sessions
 
 ```python
+import asyncio
 from ghostcrawl import GhostcrawlClient
 
-client = GhostcrawlClient(token="gck_live_YOUR_KEY")
+async def main():
+    async with GhostcrawlClient(token="gck_live_YOUR_KEY") as client:
+        # Create a session
+        session = await client.sessions.create(profile_name="my-profile")
+        session_id = session["session_id"]
 
-# Create a session
-session = client.sessions.create(profile_name="my-profile")
-session_id = session["session_id"]
+        # Extend and release
+        await client.sessions.extend(session_id, duration_seconds=600)
+        await client.sessions.release(session_id)
 
-# Extend and release
-client.sessions.extend(session_id, duration_seconds=600)
-client.sessions.release(session_id)
+asyncio.run(main())
 ```
 
 ## Error handling
 
 ```python
+import asyncio
 from ghostcrawl import GhostcrawlClient, AuthenticationError, RateLimitError, APIError
 
-client = GhostcrawlClient(token="gck_live_YOUR_KEY")
-
-try:
-    result = client.scrape(url="https://example.com")
-except AuthenticationError:
-    print("Invalid API key — check your token")
-except RateLimitError:
-    print("Rate limit reached — retry after a short delay")
-except APIError as e:
-    print(f"Server error: {e.status_code}")
+async def main():
+    async with GhostcrawlClient(token="gck_live_YOUR_KEY") as client:
+        try:
+            result = await client.scrape(url="https://example.com")
+        except AuthenticationError:
+            print("Invalid API key — check your token")
+        except RateLimitError:
+            print("Rate limit reached — retry after a short delay")
+        except APIError as e:
+            print(f"Server error: {e.status_code}")
+
+asyncio.run(main())
 ```
 
 ## Context manager
 
 ```python
+import asyncio
 from ghostcrawl import GhostcrawlClient
 
-with GhostcrawlClient(token="gck_live_YOUR_KEY") as client:
-    result = client.scrape(url="https://example.com")
-    print(result)
-# HTTP connection is closed automatically
+async def main():
+    async with GhostcrawlClient(token="gck_live_YOUR_KEY") as client:
+        result = await client.scrape(url="https://example.com")
+        print(result)
+    # HTTP connection is closed automatically
+
+asyncio.run(main())
 ```
 
 ## All resources
 
+Every operation below is a coroutine — prefix each call with `await` inside an `async` function.
+
 | Resource | Client attribute | Key operations |
 |----------|-----------------|----------------|
 | Scraping | `client.scrape(url=…)` | Render and return page content |
@@ -158,7 +189,7 @@ with GhostcrawlClient(token="gck_live_YOUR_KEY") as client:
 | Data extraction | `client.extract(url=…, schema=…)` | Structured JSON from any page |
 | Deep crawl | `client.crawl(url=…)` | Crawl a site depth-first |
 | URL map | `client.map(url=…)` | Discover all reachable URLs |
-| Crawl runs | `client.crawl_runs` | start, list, get, cancel |
+| Crawl runs | `client.crawl_runs` | start (`wait=True`), wait, list, get, cancel |
 | Sessions | `client.sessions` | create, extend, release |
 | Profiles | `client.profiles` | list, get, create, update, delete |
 | Webhooks | `client.webhooks` | list, get, create, delete, rotate-secret |

ghostcrawl-2.3.0/README.md

@@ -0,0 +1,191 @@
+# ghostcrawl — Python SDK
+
+The official Python client for the [GhostCrawl](https://ghostcrawl.io) API. Collect web data at scale — scrape, crawl, search, extract structured data, manage browser sessions, and automate the full data-collection pipeline.
+
+## Install
+
+```bash
+pip install ghostcrawl
+```
+
+Requires Python 3.10+. Runtime dependencies: `httpx>=0.28.1`.
+
+> The client is **async** — every request method is a coroutine. Call them with
+> `await` inside an `async` function and drive it with `asyncio.run(...)`.
+
+## Quickstart
+
+```python
+import asyncio
+from ghostcrawl import GhostcrawlClient
+
+async def main():
+    # Reads GHOSTCRAWL_API_KEY from environment, or pass token= explicitly
+    async with GhostcrawlClient(token="gck_live_YOUR_KEY") as client:
+        # Scrape a URL
+        result = await client.scrape(url="https://example.com", format="markdown")
+        print(result["content"])
+
+        # Start a crawl and wait for it to finish — EVENT-DRIVEN: the server
+        # blocks until the run is terminal (completed/failed/cancelled) or the
+        # timeout elapses, then returns the run. No client-side poll loop.
+        run = await client.crawl_runs.start(
+            url="https://example.com", max_depth=2, max_pages=50,
+            wait=True, wait_timeout=300,
+        )
+        print(run["run_id"], run["status"])
+
+        # Already have a run_id? Long-poll it to completion the same way:
+        #   run = await client.crawl_runs.wait(run_id, timeout=300)
+        # Or skip waiting entirely and get notified via a webhook (see Webhooks)
+        # by omitting wait= and registering a delivery URL with client.webhooks.
+
+        # Web search
+        results = await client.search(query="latest AI research", engine="google", limit=10)
+        for r in results["results"]:
+            print(r["title"], r["url"])
+
+asyncio.run(main())
+```
+
+## Authentication
+
+```python
+import os
+from ghostcrawl import GhostcrawlClient
+
+# Option 1: pass token directly
+client = GhostcrawlClient(token="gck_live_YOUR_KEY")
+
+# Option 2: set environment variable (recommended for production)
+os.environ["GHOSTCRAWL_API_KEY"] = "gck_live_YOUR_KEY"
+client = GhostcrawlClient()
+```
+
+Every request sends `Authorization: Bearer <token>`. This is the only auth scheme the API accepts.
+
+## Extract structured data
+
+```python
+import asyncio
+from ghostcrawl import GhostcrawlClient
+
+async def main():
+    async with GhostcrawlClient(token="gck_live_YOUR_KEY") as client:
+        # Define a schema and extract matching data
+        data = await client.extract(
+            url="https://example.com/product",
+            schema={
+                "type": "object",
+                "properties": {
+                    "name": {"type": "string"},
+                    "price": {"type": "number"},
+                    "description": {"type": "string"},
+                },
+            },
+        )
+        print(data["name"], data["price"])
+
+asyncio.run(main())
+```
+
+## Browser sessions
+
+```python
+import asyncio
+from ghostcrawl import GhostcrawlClient
+
+async def main():
+    async with GhostcrawlClient(token="gck_live_YOUR_KEY") as client:
+        # Create a session
+        session = await client.sessions.create(profile_name="my-profile")
+        session_id = session["session_id"]
+
+        # Extend and release
+        await client.sessions.extend(session_id, duration_seconds=600)
+        await client.sessions.release(session_id)
+
+asyncio.run(main())
+```
+
+## Error handling
+
+```python
+import asyncio
+from ghostcrawl import GhostcrawlClient, AuthenticationError, RateLimitError, APIError
+
+async def main():
+    async with GhostcrawlClient(token="gck_live_YOUR_KEY") as client:
+        try:
+            result = await client.scrape(url="https://example.com")
+        except AuthenticationError:
+            print("Invalid API key — check your token")
+        except RateLimitError:
+            print("Rate limit reached — retry after a short delay")
+        except APIError as e:
+            print(f"Server error: {e.status_code}")
+
+asyncio.run(main())
+```
+
+## Context manager
+
+```python
+import asyncio
+from ghostcrawl import GhostcrawlClient
+
+async def main():
+    async with GhostcrawlClient(token="gck_live_YOUR_KEY") as client:
+        result = await client.scrape(url="https://example.com")
+        print(result)
+    # HTTP connection is closed automatically
+
+asyncio.run(main())
+```
+
+## All resources
+
+Every operation below is a coroutine — prefix each call with `await` inside an `async` function.
+
+| Resource | Client attribute | Key operations |
+|----------|-----------------|----------------|
+| Scraping | `client.scrape(url=…)` | Render and return page content |
+| Web search | `client.search(query=…)` | Search Google, Bing, DuckDuckGo |
+| Data extraction | `client.extract(url=…, schema=…)` | Structured JSON from any page |
+| Deep crawl | `client.crawl(url=…)` | Crawl a site depth-first |
+| URL map | `client.map(url=…)` | Discover all reachable URLs |
+| Crawl runs | `client.crawl_runs` | start (`wait=True`), wait, list, get, cancel |
+| Sessions | `client.sessions` | create, extend, release |
+| Profiles | `client.profiles` | list, get, create, update, delete |
+| Webhooks | `client.webhooks` | list, get, create, delete, rotate-secret |
+| Schedules | `client.schedules` | list, get, create, delete |
+| Datasets | `client.datasets` | list, get, create, delete, append rows |
+| Recordings | `client.recordings` | list, get, delete |
+| Key-Value Store | `client.kv` | get, set, delete |
+| Account | `client.me()` | Get account info and usage |
+
+## LangChain integration
+
+```bash
+pip install ghostcrawl-langchain
+```
+
+```python
+from ghostcrawl_langchain import GhostcrawlScrape, GhostcrawlSearch
+
+scrape_tool = GhostcrawlScrape()
+search_tool = GhostcrawlSearch()
+```
+
+## Self-hosted
+
+```python
+client = GhostcrawlClient(
+    token="gck_live_YOUR_KEY",
+    base_url="http://localhost:8080",  # your self-hosted instance
+)
+```
+
+## License
+
+Proprietary — GhostCrawl Software License. See [LICENSE](LICENSE).

{ghostcrawl-2.2.3 → ghostcrawl-2.3.0}/_generated/v1/v1_request_builder.py

@@ -8,7 +8,6 @@ from typing import Any, Optional, TYPE_CHECKING, Union
 if TYPE_CHECKING:
     from .audit.audit_request_builder import AuditRequestBuilder
     from .billing.billing_request_builder import BillingRequestBuilder
-    from .binary.binary_request_builder import BinaryRequestBuilder
     from .budgets.budgets_request_builder import BudgetsRequestBuilder
     from .cdp.cdp_request_builder import CdpRequestBuilder
     from .contact.contact_request_builder import ContactRequestBuilder
@@ -69,15 +68,6 @@ class V1RequestBuilder(BaseRequestBuilder):
 
         return BillingRequestBuilder(self.request_adapter, self.path_parameters)
     
-    @property
-    def binary(self) -> BinaryRequestBuilder:
-        """
-        The binary property
-        """
-        from .binary.binary_request_builder import BinaryRequestBuilder
-
-        return BinaryRequestBuilder(self.request_adapter, self.path_parameters)
-    
     @property
     def budgets(self) -> BudgetsRequestBuilder:
         """

{ghostcrawl-2.2.3 → ghostcrawl-2.3.0}/ghostcrawl/__init__.py

@@ -81,7 +81,20 @@ from .params import (
 )
 from .retry_policy import RetryPolicy, with_retries
 
+# ---------------------------------------------------------------------------
+# Package version — sourced from installed distribution metadata (single source
+# of truth = pyproject.toml), so ``ghostcrawl.__version__`` never drifts from
+# the published version. Falls back to "0.0.0" only for an uninstalled tree.
+# ---------------------------------------------------------------------------
+from importlib.metadata import version as _pkg_version, PackageNotFoundError
+
+try:
+    __version__ = _pkg_version("ghostcrawl")
+except PackageNotFoundError:  # source tree not pip-installed
+    __version__ = "0.0.0"
+
 __all__ = [
+    "__version__",
     # Canonical client + aliases
     "GhostcrawlClient",
     "Ghostcrawl",

{ghostcrawl-2.2.3 → ghostcrawl-2.3.0}/ghostcrawl/cli/main.py

@@ -58,7 +58,7 @@ def _run(value: Any) -> Any:
 # Top-level app
 # ---------------------------------------------------------------------------
 
-__version__ = "2.2.3"  # keep in sync with sdks/python/pyproject.toml (test_version_matches_pyproject guards drift)
+__version__ = "2.3.0"  # keep in sync with sdks/python/pyproject.toml (test_version_matches_pyproject guards drift)
 
 
 def _version_callback(value: bool) -> None: