snapapi-python 1.3.0__py3-none-any.whl

snapapi.py

@@ -0,0 +1,269 @@
+"""
+SnapAPI Python SDK — capture any website as an image.
+
+Usage:
+    from snapapi import SnapAPI
+
+    snap = SnapAPI("snap_your_key_here")
+    image = snap.screenshot("example.com")
+"""
+
+import requests
+
+
+class SnapAPIError(Exception):
+    """Raised when the SnapAPI returns a non-2xx response."""
+
+    def __init__(self, status, message, body=None):
+        self.status = status
+        self.message = message
+        self.body = body
+        super().__init__(f"SnapAPI Error {status}: {message}")
+
+
+class SnapAPI:
+    """Client for the SnapAPI screenshot service."""
+
+    def __init__(self, api_key, base_url="https://snapapi.tech"):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self._session = requests.Session()
+        self._session.headers.update({"X-Api-Key": self.api_key})
+
+    def _request(self, method, path, params=None, json=None):
+        """Send a request and return the response, raising on errors."""
+        url = f"{self.base_url}{path}"
+        resp = self._session.request(method, url, params=params, json=json)
+
+        if not resp.ok:
+            try:
+                body = resp.json()
+                message = body.get("error", body.get("message", resp.reason))
+            except ValueError:
+                body = None
+                message = resp.reason or resp.text
+            raise SnapAPIError(resp.status_code, message, body)
+
+        return resp
+
+    @staticmethod
+    def _bool_param(value):
+        """Convert a Python bool to a query-string friendly string."""
+        return "true" if value else "false"
+
+    def screenshot(self, url, width=1280, height=800, format="png", quality=80,
+                   full_page=False, delay=0, dark_mode=False, block_ads=False,
+                   cache=True, selector=None, meta=False, device=None):
+        """Capture a screenshot of the given URL.
+
+        Returns bytes (raw image data) by default.
+        When meta=True, returns a dict with page metadata instead.
+        """
+        params = {
+            "url": url,
+            "width": width,
+            "height": height,
+            "format": format,
+            "quality": quality,
+            "full_page": self._bool_param(full_page),
+            "delay": delay,
+            "dark_mode": self._bool_param(dark_mode),
+            "block_ads": self._bool_param(block_ads),
+            "cache": self._bool_param(cache),
+            "meta": self._bool_param(meta),
+        }
+
+        if selector is not None:
+            params["selector"] = selector
+        if device is not None:
+            params["device"] = device
+
+        resp = self._request("GET", "/v1/screenshot", params=params)
+
+        content_type = resp.headers.get("Content-Type", "")
+        if "application/json" in content_type:
+            return resp.json()
+
+        return resp.content
+
+    def metadata(self, url):
+        """Extract metadata from a URL without taking a screenshot.
+
+        Returns title, description, OG tags, favicon, headings, links, and more.
+        Available on all plans.
+
+        Args:
+            url: The webpage URL to extract metadata from.
+
+        Returns:
+            dict with metadata fields.
+        """
+        resp = self._request("GET", "/v1/metadata", params={"url": url})
+        return resp.json()
+
+    def render(self, html, width=1200, height=630, format="png", quality=90):
+        """Render raw HTML to an image (PNG, JPEG, or WebP).
+
+        Perfect for OG cards, email previews, and dashboard exports.
+        Requires Starter tier or above.
+
+        Args:
+            html: Full HTML string to render (max 2MB).
+            width: Viewport width in pixels (default 1200).
+            height: Viewport height in pixels (default 630).
+            format: Output format — 'png', 'jpeg', or 'webp' (default 'png').
+            quality: Image quality 1-100 for jpeg/webp (default 90).
+
+        Returns:
+            bytes (raw image data).
+        """
+        resp = self._request("POST", "/v1/render", json={
+            "html": html,
+            "width": width,
+            "height": height,
+            "format": format,
+            "quality": quality,
+        })
+        return resp.content
+
+    def usage(self):
+        """Return current usage statistics (tier, usage count, limits)."""
+        resp = self._request("GET", "/v1/usage")
+        return resp.json()
+
+    def account(self):
+        """Return full account information."""
+        resp = self._request("GET", "/v1/account")
+        return resp.json()
+
+    def update_settings(self, name=None, allowed_domains=None):
+        """Update account settings.
+
+        Args:
+            name: Display name to set.
+            allowed_domains: List of allowed domains for the API key.
+
+        Returns:
+            dict with updated settings.
+        """
+        payload = {}
+        if name is not None:
+            payload["name"] = name
+        if allowed_domains is not None:
+            payload["allowed_domains"] = allowed_domains
+
+        resp = self._request("POST", "/v1/account/settings", json=payload)
+        return resp.json()
+
+    # ─── Monitors (Scheduled Screenshots) ───
+
+    def create_monitor(self, url, interval_minutes, name=None, params=None, webhook_url=None):
+        """Create a new scheduled monitor.
+
+        Args:
+            url: URL to monitor.
+            interval_minutes: Capture interval in minutes.
+            name: Optional display name.
+            params: Optional screenshot options dict (width, height, format, etc.).
+            webhook_url: Optional webhook URL for notifications.
+
+        Returns:
+            dict with monitor details.
+        """
+        payload = {"url": url, "interval_minutes": interval_minutes}
+        if name is not None:
+            payload["name"] = name
+        if params is not None:
+            payload["params"] = params
+        if webhook_url is not None:
+            payload["webhook_url"] = webhook_url
+
+        resp = self._request("POST", "/v1/monitors", json=payload)
+        return resp.json()
+
+    def list_monitors(self):
+        """List all monitors for this API key.
+
+        Returns:
+            list of monitor dicts.
+        """
+        resp = self._request("GET", "/v1/monitors")
+        return resp.json()
+
+    def get_monitor(self, monitor_id):
+        """Get a single monitor by ID.
+
+        Returns:
+            dict with monitor details.
+        """
+        resp = self._request("GET", f"/v1/monitors/{monitor_id}")
+        return resp.json()
+
+    def update_monitor(self, monitor_id, **kwargs):
+        """Update a monitor.
+
+        Keyword Args:
+            name: New display name.
+            interval_minutes: New interval.
+            status: 'active' or 'paused'.
+            params: New screenshot options dict.
+            webhook_url: New webhook URL.
+
+        Returns:
+            dict with updated monitor.
+        """
+        resp = self._request("PATCH", f"/v1/monitors/{monitor_id}", json=kwargs)
+        return resp.json()
+
+    def delete_monitor(self, monitor_id):
+        """Delete a monitor and all its snapshots."""
+        self._request("DELETE", f"/v1/monitors/{monitor_id}")
+
+    def list_snapshots(self, monitor_id, limit=50, offset=0):
+        """List snapshots for a monitor.
+
+        Args:
+            monitor_id: Monitor ID.
+            limit: Max results (default 50).
+            offset: Pagination offset.
+
+        Returns:
+            dict with snapshots list, total, limit, offset.
+        """
+        resp = self._request("GET", f"/v1/monitors/{monitor_id}/snapshots",
+                             params={"limit": limit, "offset": offset})
+        return resp.json()
+
+    def get_snapshot(self, monitor_id, snapshot_id):
+        """Download a specific snapshot image.
+
+        Returns:
+            bytes (raw image data).
+        """
+        resp = self._request("GET", f"/v1/monitors/{monitor_id}/snapshots/{snapshot_id}")
+        return resp.content
+
+    @staticmethod
+    def signup(email, base_url="https://snapapi.tech"):
+        """Create a new SnapAPI account. No API key required.
+
+        Args:
+            email: Email address for the new account.
+            base_url: API base URL.
+
+        Returns:
+            dict with key, tier, and limit.
+        """
+        url = f"{base_url.rstrip('/')}/v1/signup"
+        resp = requests.post(url, json={"email": email})
+
+        if not resp.ok:
+            try:
+                body = resp.json()
+                message = body.get("error", body.get("message", resp.reason))
+            except ValueError:
+                body = None
+                message = resp.reason or resp.text
+            raise SnapAPIError(resp.status_code, message, body)
+
+        return resp.json()

snapapi_python-1.3.0.dist-info/METADATA

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: snapapi-python
+Version: 1.3.0
+Summary: Official Python SDK for SnapAPI — screenshot, metadata extraction, and HTML rendering
+License: MIT
+Keywords: screenshot,api,webpage-capture,snapapi
+Requires-Python: >=3.7
+Requires-Dist: requests>=2.20.0
+Dynamic: keywords
+Dynamic: license
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

snapapi_python-1.3.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+snapapi.py,sha256=sNkVGGihSbQln8n3kYfeShworXs32B5vf8p5i9Eq0Ug,8726
+snapapi_python-1.3.0.dist-info/METADATA,sha256=PY-9BZ9ybpFJcjDx31o8w5_IWALRCafbKg-6RrmmY3w,385
+snapapi_python-1.3.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+snapapi_python-1.3.0.dist-info/top_level.txt,sha256=ixqJtWjxOFIoE_Mirko8xyRTH-3pKC_AYNRLLUuESoA,8
+snapapi_python-1.3.0.dist-info/RECORD,,

snapapi_python-1.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

snapapi_python-1.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+snapapi