synoppy 1.0.0__tar.gz

synoppy-1.0.0/.gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+*.tsbuildinfo
+__pycache__/
+*.egg-info/

synoppy-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Saanora
+
+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.

synoppy-1.0.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: synoppy
+Version: 1.0.0
+Summary: Official Python SDK for the Synoppy web-data API — scrape, screenshot, crawl, map, extract, classify, enrich, and images.
+Project-URL: Homepage, https://synoppy.com
+Project-URL: Documentation, https://synoppy.com/docs/sdks
+Project-URL: Repository, https://github.com/Synoppy/synoppy-python
+Project-URL: Issues, https://github.com/Synoppy/synoppy-python/issues
+Author-email: Saanora <support@synoppy.com>
+License: MIT
+License-File: LICENSE
+Keywords: agents,crawler,llm,markdown,rag,scraping,synoppy,web-data
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Requires-Dist: requests>=2.25
+Description-Content-Type: text/markdown
+
+# synoppy (Python)
+
+[![PyPI](https://img.shields.io/pypi/v/synoppy.svg)](https://pypi.org/project/synoppy/) [![Python](https://img.shields.io/pypi/pyversions/synoppy.svg)](https://pypi.org/project/synoppy/)
+
+**Give your AI agents the whole web.** Synoppy is the web-data layer for AI agents — one key to **read, crawl, map, extract, classify & enrich** any site, plus screenshots and image scraping. Clean, structured, LLM-ready data, with no scraping stack to run.
+
+[**Get a free key →**](https://synoppy.com/dashboard) · [Docs](https://synoppy.com/docs) · [synoppy.com](https://synoppy.com)
+
+```bash
+pip install synoppy
+```
+
+## Quickstart
+
+```python
+import os
+from synoppy import Synoppy
+
+client = Synoppy(api_key=os.environ["SYNOPPY_API_KEY"])
+
+# Read any URL → clean markdown (force JS rendering + settle delay)
+page = client.read(
+    "https://stripe.com/blog",
+    formats=["markdown"],
+    render="auto",
+    wait_ms=500,
+)
+print(page["markdown"])
+print(page["metadata"]["rendered"], page["metadata"]["bytesIn"])
+
+# Screenshot a URL → PNG data URL
+shot = client.screenshot("https://stripe.com", full_page=True)
+print(shot["screenshot"][:40], shot["statusCode"])
+
+# Crawl a site
+site = client.crawl("https://example.com", limit=25)
+print(site["count"], "of", site["discovered"], "pages")
+
+# AI structured extraction (prompt, a.k.a. instruction)
+result = client.extract("https://news.ycombinator.com", prompt="Return { title, summary, topics }")
+print(result["data"], result["usage"])
+
+# Brand intelligence — from a url, a domain, or a work email
+brand = client.enrich(domain="linear.app")
+print(brand["colors"], brand["fonts"], brand["socials"])
+```
+
+## Credits
+
+Every successful response includes `creditsUsed` (number) and
+`creditsRemaining` (number or `None`) so you can track metered usage:
+
+```python
+page = client.read("https://stripe.com")
+print("used", page["creditsUsed"], "remaining", page["creditsRemaining"])
+```
+
+## Methods
+
+| Method | Endpoint | Notes |
+| --- | --- | --- |
+| `read(url, formats=, only_main_content=, timeout_ms=, render=, wait_ms=)` / `scrape(...)` | `POST /api/scrape` | `render` is `True`/`False`/`"auto"` |
+| `screenshot(url, full_page=, wait_ms=, timeout_ms=)` | `POST /api/screenshot` | returns a PNG data URL; can 503 `RENDER_UNAVAILABLE` |
+| `crawl(url, limit=)` | `POST /api/crawl` | `limit` 1–25 · requires a key |
+| `map(url)` / `sitemap(url)` | `POST /api/map` | |
+| `extract(url, prompt=, instruction=)` | `POST /api/extract` | `instruction` aliases `prompt` · AI · requires a key |
+| `classify(url, labels=)` | `POST /api/classify` | NAICS/SIC by default, or your own `labels` · AI · requires a key |
+| `enrich(url=, domain=, email=)` / `brand(...)` | `POST /api/brand` | pass one of url / domain / work email |
+| `images(url)` | `POST /api/images` | |
+
+Every response also carries `creditsUsed` and `creditsRemaining`.
+
+`act()` is **coming soon** — `/api/act` is not live yet, and calling this
+method raises `NotImplementedError`.
+
+## Errors
+
+```python
+from synoppy import SynoppyError
+
+try:
+    client.crawl("https://example.com")
+except SynoppyError as err:
+    print(err.code, err.status, err)
+```
+
+MIT licensed.

synoppy-1.0.0/README.md

@@ -0,0 +1,87 @@
+# synoppy (Python)
+
+[![PyPI](https://img.shields.io/pypi/v/synoppy.svg)](https://pypi.org/project/synoppy/) [![Python](https://img.shields.io/pypi/pyversions/synoppy.svg)](https://pypi.org/project/synoppy/)
+
+**Give your AI agents the whole web.** Synoppy is the web-data layer for AI agents — one key to **read, crawl, map, extract, classify & enrich** any site, plus screenshots and image scraping. Clean, structured, LLM-ready data, with no scraping stack to run.
+
+[**Get a free key →**](https://synoppy.com/dashboard) · [Docs](https://synoppy.com/docs) · [synoppy.com](https://synoppy.com)
+
+```bash
+pip install synoppy
+```
+
+## Quickstart
+
+```python
+import os
+from synoppy import Synoppy
+
+client = Synoppy(api_key=os.environ["SYNOPPY_API_KEY"])
+
+# Read any URL → clean markdown (force JS rendering + settle delay)
+page = client.read(
+    "https://stripe.com/blog",
+    formats=["markdown"],
+    render="auto",
+    wait_ms=500,
+)
+print(page["markdown"])
+print(page["metadata"]["rendered"], page["metadata"]["bytesIn"])
+
+# Screenshot a URL → PNG data URL
+shot = client.screenshot("https://stripe.com", full_page=True)
+print(shot["screenshot"][:40], shot["statusCode"])
+
+# Crawl a site
+site = client.crawl("https://example.com", limit=25)
+print(site["count"], "of", site["discovered"], "pages")
+
+# AI structured extraction (prompt, a.k.a. instruction)
+result = client.extract("https://news.ycombinator.com", prompt="Return { title, summary, topics }")
+print(result["data"], result["usage"])
+
+# Brand intelligence — from a url, a domain, or a work email
+brand = client.enrich(domain="linear.app")
+print(brand["colors"], brand["fonts"], brand["socials"])
+```
+
+## Credits
+
+Every successful response includes `creditsUsed` (number) and
+`creditsRemaining` (number or `None`) so you can track metered usage:
+
+```python
+page = client.read("https://stripe.com")
+print("used", page["creditsUsed"], "remaining", page["creditsRemaining"])
+```
+
+## Methods
+
+| Method | Endpoint | Notes |
+| --- | --- | --- |
+| `read(url, formats=, only_main_content=, timeout_ms=, render=, wait_ms=)` / `scrape(...)` | `POST /api/scrape` | `render` is `True`/`False`/`"auto"` |
+| `screenshot(url, full_page=, wait_ms=, timeout_ms=)` | `POST /api/screenshot` | returns a PNG data URL; can 503 `RENDER_UNAVAILABLE` |
+| `crawl(url, limit=)` | `POST /api/crawl` | `limit` 1–25 · requires a key |
+| `map(url)` / `sitemap(url)` | `POST /api/map` | |
+| `extract(url, prompt=, instruction=)` | `POST /api/extract` | `instruction` aliases `prompt` · AI · requires a key |
+| `classify(url, labels=)` | `POST /api/classify` | NAICS/SIC by default, or your own `labels` · AI · requires a key |
+| `enrich(url=, domain=, email=)` / `brand(...)` | `POST /api/brand` | pass one of url / domain / work email |
+| `images(url)` | `POST /api/images` | |
+
+Every response also carries `creditsUsed` and `creditsRemaining`.
+
+`act()` is **coming soon** — `/api/act` is not live yet, and calling this
+method raises `NotImplementedError`.
+
+## Errors
+
+```python
+from synoppy import SynoppyError
+
+try:
+    client.crawl("https://example.com")
+except SynoppyError as err:
+    print(err.code, err.status, err)
+```
+
+MIT licensed.

synoppy-1.0.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "synoppy"
+version = "1.0.0"
+description = "Official Python SDK for the Synoppy web-data API — scrape, screenshot, crawl, map, extract, classify, enrich, and images."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Saanora", email = "support@synoppy.com" }]
+dependencies = ["requests>=2.25"]
+keywords = ["synoppy", "scraping", "crawler", "web-data", "markdown", "llm", "agents", "rag"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+]
+
+[project.urls]
+Homepage = "https://synoppy.com"
+Documentation = "https://synoppy.com/docs/sdks"
+Repository = "https://github.com/Synoppy/synoppy-python"
+Issues = "https://github.com/Synoppy/synoppy-python/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build]
+exclude = ["**/__pycache__", "*.pyc"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["synoppy"]

synoppy-1.0.0/synoppy/__init__.py

@@ -0,0 +1,233 @@
+"""Official Python SDK for the Synoppy web-data API.
+
+One key for scrape, screenshot, crawl, map, extract, classify, enrich,
+and images. Every successful response includes ``creditsUsed`` and
+``creditsRemaining`` so you can track metered usage.
+"""
+from __future__ import annotations
+
+import json as _json
+from typing import Any, Dict, List, Optional, Union
+
+import requests
+
+__version__ = "1.0.0"
+DEFAULT_BASE_URL = "https://synoppy.com"
+
+
+class SynoppyError(Exception):
+    """Raised when the API returns an error response."""
+
+    def __init__(self, message: str, code: str, status: int) -> None:
+        super().__init__(message)
+        self.code = code
+        self.status = status
+
+
+class Synoppy:
+    """Synoppy API client.
+
+    Example:
+        >>> from synoppy import Synoppy
+        >>> client = Synoppy(api_key="syn_live_...")
+        >>> page = client.read("https://stripe.com/blog", formats=["markdown"])
+        >>> print(page["markdown"])
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 60.0,
+    ) -> None:
+        if not api_key:
+            raise ValueError("Synoppy: api_key is required")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._session = requests.Session()
+        self._session.headers.update(
+            {
+                "Authorization": "Bearer " + api_key,
+                "Content-Type": "application/json",
+                "User-Agent": "synoppy-python/" + __version__,
+            }
+        )
+
+    def _request(self, path: str, body: Dict[str, Any]) -> Dict[str, Any]:
+        resp = self._session.post(
+            self.base_url + path, data=_json.dumps(body), timeout=self.timeout
+        )
+        try:
+            data = resp.json()
+        except ValueError:
+            data = {}
+        if not resp.ok or data.get("success") is False:
+            raise SynoppyError(
+                data.get("error", "HTTP %s" % resp.status_code),
+                data.get("code", "ERROR"),
+                resp.status_code,
+            )
+        return data
+
+    # --- Endpoints -----------------------------------------------------------
+
+    def read(
+        self,
+        url: str,
+        formats: Optional[List[str]] = None,
+        only_main_content: Optional[bool] = None,
+        timeout_ms: Optional[int] = None,
+        render: Optional[Union[bool, str]] = None,
+        wait_ms: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """Read a URL → clean markdown / HTML / text.
+
+        ``render`` may be ``True``/``False`` or ``"auto"`` to control JS
+        rendering; ``wait_ms`` adds a settle delay before capture. The
+        response includes ``metadata`` (title, description, language,
+        siteName, author, ogImage, sourceUrl, statusCode, wordCount,
+        fetchedAt, rendered, bytesIn), the requested ``markdown``/``html``/
+        ``text``, ``renderMs``, ``latencyMs``, ``creditsUsed``, and
+        ``creditsRemaining``.
+        """
+        body: Dict[str, Any] = {"url": url}
+        if formats is not None:
+            body["formats"] = formats
+        if only_main_content is not None:
+            body["onlyMainContent"] = only_main_content
+        if timeout_ms is not None:
+            body["timeoutMs"] = timeout_ms
+        if render is not None:
+            body["render"] = render
+        if wait_ms is not None:
+            body["waitMs"] = wait_ms
+        return self._request("/api/scrape", body)
+
+    scrape = read
+
+    def screenshot(
+        self,
+        url: str,
+        full_page: Optional[bool] = None,
+        wait_ms: Optional[int] = None,
+        timeout_ms: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """Capture a PNG screenshot of a URL.
+
+        Returns ``screenshot`` (a PNG data URL) alongside ``sourceUrl``,
+        ``statusCode``, ``fullPage``, ``latencyMs``, ``creditsUsed``, and
+        ``creditsRemaining``. Raises :class:`SynoppyError` with code
+        ``RENDER_UNAVAILABLE`` (status 503) if rendering is unavailable.
+        """
+        body: Dict[str, Any] = {"url": url}
+        if full_page is not None:
+            body["fullPage"] = full_page
+        if wait_ms is not None:
+            body["waitMs"] = wait_ms
+        if timeout_ms is not None:
+            body["timeoutMs"] = timeout_ms
+        return self._request("/api/screenshot", body)
+
+    def crawl(self, url: str, limit: Optional[int] = None) -> Dict[str, Any]:
+        """Crawl a site → one clean page per URL discovered (requires a key)."""
+        body: Dict[str, Any] = {"url": url}
+        if limit is not None:
+            body["limit"] = limit
+        return self._request("/api/crawl", body)
+
+    def map(self, url: str) -> Dict[str, Any]:
+        """Discover every URL on a domain."""
+        return self._request("/api/map", {"url": url})
+
+    sitemap = map
+
+    def extract(
+        self,
+        url: str,
+        prompt: Optional[str] = None,
+        instruction: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """AI-structured JSON extraction (requires a key).
+
+        ``instruction`` is an alias for ``prompt``. The response includes
+        ``data``, ``model``, ``metadata``, ``truncated``,
+        ``usage`` (``inputTokens``/``outputTokens``), ``latencyMs``,
+        ``creditsUsed``, and ``creditsRemaining``.
+        """
+        body: Dict[str, Any] = {"url": url}
+        if prompt is None:
+            prompt = instruction
+        if prompt is not None:
+            body["prompt"] = prompt
+        return self._request("/api/extract", body)
+
+    def classify(self, url: str, labels: Optional[List[str]] = None) -> Dict[str, Any]:
+        """Classify a company by industry, or your own labels (requires a key).
+
+        Without ``labels``, ``data`` holds the NAICS/SIC industry profile
+        (``industry``, ``naics_code``, ``naics_title``, ``naics_sector``,
+        ``naics_sector_title``, ``naics_valid``, ``sic_code``,
+        ``sic_title``, ``sic_division``, ``sic_division_title``,
+        ``sic_valid``, ``categories``, ``confidence``). With ``labels``,
+        ``data`` holds ``label``, ``matched``, ``confidence``, and
+        ``reasoning``. Both modes include ``creditsUsed`` and
+        ``creditsRemaining``.
+        """
+        body: Dict[str, Any] = {"url": url}
+        if labels is not None:
+            body["labels"] = labels
+        return self._request("/api/classify", body)
+
+    def enrich(
+        self,
+        url: Optional[str] = None,
+        *,
+        domain: Optional[str] = None,
+        email: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Resolve a brand profile from a URL, domain, or work email.
+
+        Pass exactly one of ``url``, ``domain``, or ``email`` (a work email
+        is mapped to its domain server-side). The response includes
+        ``name``, ``description``, ``logo``, ``colors``, ``fonts``,
+        ``address``, ``socials`` (``label``/``url``), ``bytesIn``,
+        ``latencyMs``, ``creditsUsed``, and ``creditsRemaining``.
+        """
+        body: Dict[str, Any] = {}
+        if url is not None:
+            body["url"] = url
+        if domain is not None:
+            body["domain"] = domain
+        if email is not None:
+            body["email"] = email
+        if not body:
+            raise ValueError(
+                "Synoppy.enrich: one of url, domain, or email is required"
+            )
+        return self._request("/api/brand", body)
+
+    brand = enrich
+
+    def images(self, url: str) -> Dict[str, Any]:
+        """Pull every image off a page.
+
+        Returns ``url``, ``count``, ``images`` (each with ``src``, ``alt``,
+        ``width``, ``height``), ``bytesIn``, ``latencyMs``, ``creditsUsed``,
+        and ``creditsRemaining``.
+        """
+        return self._request("/api/images", {"url": url})
+
+    # --- Coming soon ---------------------------------------------------------
+    # /api/act is not live yet. It is intentionally not implemented; calling
+    # it raises a clear error rather than hitting an endpoint that does not
+    # exist.
+
+    def act(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
+        """Agentic browser actions — coming soon (not yet live)."""
+        raise NotImplementedError(
+            "Synoppy.act is coming soon; /api/act is not live yet."
+        )
+
+
+__all__ = ["Synoppy", "SynoppyError", "__version__"]