zappyquote 0.2.0__tar.gz

zappyquote-0.2.0/LICENSE

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

zappyquote-0.2.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.1
+Name: zappyquote
+Version: 0.2.0
+Summary: Official Zappy API client for Python - a thin wrapper over the documented Zappy API v1.
+Author: Zappy
+License: MIT
+Project-URL: Homepage, https://zappyquote.com/developers/
+Project-URL: Documentation, https://zappyquote.com/developers/
+Project-URL: Issues, https://zappyquote.com/contact.html
+Keywords: zappy,zappyquote,ai,image-generation,api,sdk
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# zappyquote
+
+The official Python client for the Zappy API v1 - a thin wrapper over the documented HTTP API
+(https://zappyquote.com/developers/). The server stays authoritative for pricing, caps, idempotency and ownership.
+
+Version 0.2.0 · contract `openapi-1.0.0@9dff9fdfbcd8c1bd` · Python 3.9+ · standard library only · MIT
+
+```bash
+# official download (always available):
+curl -O https://zappyquote.com/dl/zappyquote.py      # then: import zappyquote
+# PyPI, ONLY once https://zappyquote.com/developers/ lists zappyquote as published by Zappy:
+#   pip install zappyquote
+```
+
+```python
+from zappyquote import Zappy, ZappyError, new_idempotency_key
+
+zappy = Zappy()                                    # reads ZAPPY_API_KEY; or Zappy(api_key=...)
+caps = zappy.capabilities()["capabilities"]        # free
+quote = zappy.quote("zappy-image-pro")             # free, reserves nothing
+
+# BILLABLE. max_credits is a hard ceiling; the idempotency key makes a replay return the same job, never a second charge.
+key = new_idempotency_key("order-123")
+r = zappy.create_image("a lighthouse at dusk", max_credits=quote["credits_quoted"], idempotency_key=key)
+job = r if r["status"] == "succeeded" else zappy.wait_for_job(r["job_id"])   # 202 => poll (free)
+asset = zappy.get_asset(job["assets"][0]["asset_id"])                        # short-lived signed URL on Zappy's host
+```
+
+Every response is a `dict` with `.meta` (`request_id`, `rate_limit`, `retry_after`, `status`). Failures raise a
+`ZappyError` subclass with `code`, `status`, `request_id`, `retry_after`: `ZappyAuthError`, `ZappyRateLimitError`,
+`ZappySpendError`, `ZappyNotFoundError`, `ZappyUnavailableError`, `ZappyTransportError`. Messages never contain a credential.
+
+```python
+from zappyquote import verify_webhook_signature
+ok = verify_webhook_signature(secret, request.headers["Zappy-Signature"], request.get_data())   # exact raw bytes
+```
+
+`pkce_pair()` / `authorize_url(...)` build the OAuth authorization request for an app you registered in Zappy; consent
+and token exchange stay on Zappy's authorization server. Paid calls are never retried by this package.
+
+## Name
+
+The distribution and the import are both `zappyquote` (`import zappyquote`). The shorter name `zappy` is used on PyPI by an unrelated project whose distribution also installs a top-level `zappy` package; sharing that name would let either install silently replace the other. Version 0.2.0 is the first version under this name (0.1.0 was only ever a direct download, `/dl/zappy.py`, and is retired).
+
+### Migrating from the retired `/dl/zappy.py`
+
+1. Download `https://zappyquote.com/dl/zappyquote.py` next to your code.
+2. Change `import zappy` / `from zappy import ...` to `import zappyquote` / `from zappyquote import ...` (the API is unchanged).
+3. Delete your project-local `zappy.py` once you have confirmed it is the Zappy SDK (its docstring starts with
+   "zappy - the official Python client for the Zappy API v1"). Left in place, it would shadow any other `zappy` package.
+
+Registry packages are official only if https://zappyquote.com/developers/ lists them as published; until then use the download, and never install a look-alike name.

zappyquote-0.2.0/README.md

@@ -0,0 +1,52 @@
+# zappyquote
+
+The official Python client for the Zappy API v1 - a thin wrapper over the documented HTTP API
+(https://zappyquote.com/developers/). The server stays authoritative for pricing, caps, idempotency and ownership.
+
+Version 0.2.0 · contract `openapi-1.0.0@9dff9fdfbcd8c1bd` · Python 3.9+ · standard library only · MIT
+
+```bash
+# official download (always available):
+curl -O https://zappyquote.com/dl/zappyquote.py      # then: import zappyquote
+# PyPI, ONLY once https://zappyquote.com/developers/ lists zappyquote as published by Zappy:
+#   pip install zappyquote
+```
+
+```python
+from zappyquote import Zappy, ZappyError, new_idempotency_key
+
+zappy = Zappy()                                    # reads ZAPPY_API_KEY; or Zappy(api_key=...)
+caps = zappy.capabilities()["capabilities"]        # free
+quote = zappy.quote("zappy-image-pro")             # free, reserves nothing
+
+# BILLABLE. max_credits is a hard ceiling; the idempotency key makes a replay return the same job, never a second charge.
+key = new_idempotency_key("order-123")
+r = zappy.create_image("a lighthouse at dusk", max_credits=quote["credits_quoted"], idempotency_key=key)
+job = r if r["status"] == "succeeded" else zappy.wait_for_job(r["job_id"])   # 202 => poll (free)
+asset = zappy.get_asset(job["assets"][0]["asset_id"])                        # short-lived signed URL on Zappy's host
+```
+
+Every response is a `dict` with `.meta` (`request_id`, `rate_limit`, `retry_after`, `status`). Failures raise a
+`ZappyError` subclass with `code`, `status`, `request_id`, `retry_after`: `ZappyAuthError`, `ZappyRateLimitError`,
+`ZappySpendError`, `ZappyNotFoundError`, `ZappyUnavailableError`, `ZappyTransportError`. Messages never contain a credential.
+
+```python
+from zappyquote import verify_webhook_signature
+ok = verify_webhook_signature(secret, request.headers["Zappy-Signature"], request.get_data())   # exact raw bytes
+```
+
+`pkce_pair()` / `authorize_url(...)` build the OAuth authorization request for an app you registered in Zappy; consent
+and token exchange stay on Zappy's authorization server. Paid calls are never retried by this package.
+
+## Name
+
+The distribution and the import are both `zappyquote` (`import zappyquote`). The shorter name `zappy` is used on PyPI by an unrelated project whose distribution also installs a top-level `zappy` package; sharing that name would let either install silently replace the other. Version 0.2.0 is the first version under this name (0.1.0 was only ever a direct download, `/dl/zappy.py`, and is retired).
+
+### Migrating from the retired `/dl/zappy.py`
+
+1. Download `https://zappyquote.com/dl/zappyquote.py` next to your code.
+2. Change `import zappy` / `from zappy import ...` to `import zappyquote` / `from zappyquote import ...` (the API is unchanged).
+3. Delete your project-local `zappy.py` once you have confirmed it is the Zappy SDK (its docstring starts with
+   "zappy - the official Python client for the Zappy API v1"). Left in place, it would shadow any other `zappy` package.
+
+Registry packages are official only if https://zappyquote.com/developers/ lists them as published; until then use the download, and never install a look-alike name.

zappyquote-0.2.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zappyquote"
+version = "0.2.0"
+description = "Official Zappy API client for Python - a thin wrapper over the documented Zappy API v1."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Zappy" }]
+requires-python = ">=3.9"
+dependencies = []
+keywords = ["zappy", "zappyquote", "ai", "image-generation", "api", "sdk"]
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://zappyquote.com/developers/"
+Documentation = "https://zappyquote.com/developers/"
+Issues = "https://zappyquote.com/contact.html"
+
+[tool.setuptools]
+packages = ["zappyquote"]
+include-package-data = false

zappyquote-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

zappyquote-0.2.0/zappyquote/__init__.py

@@ -0,0 +1,339 @@
+"""zappyquote - the official Python client for the Zappy API v1 (distribution `zappyquote`, import `zappyquote`).
+
+Named after the zappyquote.com domain and the npm @zappyquote scope. Not `zappy`: that top-level name belongs to an unrelated
+PyPI project (lasersonlab/zappy), and two distributions shipping the same top-level package overwrite each other on install.
+
+A THIN WRAPPER over the documented HTTP API (https://zappyquote.com/developers/). It holds no business rule:
+pricing, quotas, ceilings, idempotency and ownership are decided by the server; this module only carries the
+request there and maps the public error envelope into typed exceptions. Standard library only (urllib), Python >= 3.9.
+
+Safety properties:
+  - the credential comes from the constructor or ZAPPY_API_KEY, is never logged, and is redacted from every error;
+  - paid calls (create_image, edit_image) are NEVER retried on their own; replay with the same idempotency_key
+    returns the same job, never a second charge;
+  - every mutating call sends an Idempotency-Key (yours, or one this client generates and returns to you);
+  - rate-limit metadata (RateLimit-*, Retry-After) and X-Request-Id are exposed on every result and error.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import os
+import re
+import secrets
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, Optional
+
+__version__ = "0.2.0"
+SDK_VERSION = __version__
+#: sha256 prefix of the public_html/api/openapi.json this client was written against (see DEVELOPER_DISTRIBUTION.md)
+CONTRACT = "openapi-1.0.0@9dff9fdfbcd8c1bd"
+DEFAULT_BASE_URL = "https://zappyquote.com/api/v1"
+
+_KEY_RE = re.compile(r"(zp_live_|zat_|zrt_|zcs_)[A-Za-z0-9_-]+")   # no leading boundary: an embedded credential is still a credential
+
+
+def redact(s: Any) -> str:
+    """Replace any Zappy credential shape in a string with a redacted marker."""
+    return _KEY_RE.sub(lambda m: m.group(1) + "…redacted", str(s))
+
+
+def new_idempotency_key(prefix: str = "zq") -> str:
+    """A stable idempotency key for ONE intended operation. Keep it with the operation; reuse it to replay safely."""
+    p = re.sub(r"[^A-Za-z0-9._:-]", "", prefix)[:20] or "zq"
+    return f"{p}-{int(time.time() * 1000):x}-{secrets.token_urlsafe(9)}"
+
+
+@dataclass
+class RateLimit:
+    limit: Optional[int]
+    remaining: Optional[int]
+    reset: Optional[int]
+
+
+@dataclass
+class ResponseMeta:
+    request_id: Optional[str]
+    rate_limit: Optional[RateLimit]
+    retry_after: Optional[int]
+    status: int = 0
+
+
+class ZappyError(Exception):
+    """Base error. `code` is the public error code, `status` the HTTP status, `meta` the response metadata."""
+
+    def __init__(self, message: str, code: str = "error", status: int = 0, meta: Optional[ResponseMeta] = None, body: Any = None):
+        super().__init__(redact(message))
+        self.code = code
+        self.status = status
+        self.meta = meta
+        self.body = body
+        self.idempotency_key: Optional[str] = None
+
+    @property
+    def request_id(self) -> Optional[str]:
+        return self.meta.request_id if self.meta else None
+
+    @property
+    def retry_after(self) -> Optional[int]:
+        return self.meta.retry_after if self.meta else None
+
+
+class ZappyAuthError(ZappyError): ...
+class ZappyRateLimitError(ZappyError): ...
+class ZappySpendError(ZappyError): ...
+class ZappyNotFoundError(ZappyError): ...
+class ZappyUnavailableError(ZappyError): ...
+class ZappyTransportError(ZappyError): ...
+
+
+_SPEND_CODES = {"insufficient_credits", "daily_cap_reached", "request_exceeds_key_ceiling", "request_exceeds_ceiling", "spend_check_unavailable", "idempotency_key_required", "idempotency_conflict"}
+
+
+def _error_for(status: int, body: Any, meta: ResponseMeta) -> ZappyError:
+    err = body.get("error") if isinstance(body, dict) else None
+    if not isinstance(err, dict):
+        err = {}
+    code = str(err.get("code") or {429: "rate_limited", 401: "unauthorized", 404: "not_found"}.get(status, "error"))
+    message = str(err.get("message") or f"Zappy API answered HTTP {status}")
+    kw = dict(code=code, status=status, meta=meta, body=body)
+    if status == 401 or code == "unauthorized" or (status == 403 and code == "insufficient_scope"):
+        return ZappyAuthError(message, **kw)
+    if status == 429 and code == "rate_limited":
+        return ZappyRateLimitError(message, **kw)
+    if code in _SPEND_CODES:
+        return ZappySpendError(message, **kw)
+    if status == 404:
+        return ZappyNotFoundError(message, **kw)
+    if status in (502, 503) or code in ("not_available", "pilot_closed"):
+        return ZappyUnavailableError(message, **kw)
+    return ZappyError(message, **kw)
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    """F5-SEC-001: a redirect is NEVER followed, so the credential can only ever reach the configured base URL."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):  # noqa: D401
+        return None
+
+
+_OPENER = urllib.request.build_opener(_NoRedirect())
+
+
+class Response(dict):
+    """The decoded JSON body, plus `.meta` (request id, rate limit, retry-after, status)."""
+    meta: ResponseMeta
+
+
+class Zappy:
+    def __init__(self, api_key: Optional[str] = None, *, access_token: Optional[str] = None, base_url: Optional[str] = None,
+                 client_name: str = "zappy-sdk-python", client_type: str = "sdk", client_version: Optional[str] = None,
+                 timeout: float = 60.0, opener: Optional[Callable[..., Any]] = None):
+        token = access_token or api_key or os.environ.get("ZAPPY_API_KEY", "")
+        if not token:
+            raise ZappyAuthError("No credential: pass api_key= or set ZAPPY_API_KEY. Create a key in Zappy under Account -> Developer.", code="not_configured")
+        self.__token = token
+        self.base_url = (base_url or os.environ.get("ZAPPY_API_BASE") or DEFAULT_BASE_URL).rstrip("/")
+        self.client_type = "cli" if client_type == "cli" else "sdk"
+        self.client_name = re.sub(r"[^a-z0-9._-]", "", client_name.lower())[:64] or "zappy-sdk-python"
+        self.client_version = client_version if client_version and re.fullmatch(r"[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}", client_version) else SDK_VERSION
+        self.timeout = timeout
+        self._open = opener or _OPENER.open
+        self.last_meta: Optional[ResponseMeta] = None
+
+    def __repr__(self) -> str:  # never the credential
+        return f"Zappy(base_url={self.base_url!r}, credential='redacted')"
+
+    # ---- transport ----
+    def _request(self, method: str, path: str, *, body: Optional[dict] = None, idempotency_key: Optional[str] = None, query: Optional[dict] = None) -> Response:
+        url = self.base_url + "/" + path.lstrip("/")
+        if query:
+            q = {k: str(v) for k, v in query.items() if v is not None}
+            if q:
+                url += "?" + urllib.parse.urlencode(q)
+        headers = {"Authorization": "Bearer " + self.__token, "Accept": "application/json",
+                   "X-Zappy-Client-Type": self.client_type, "X-Zappy-Client-Name": self.client_name, "X-Zappy-Client-Version": self.client_version}
+        data = None
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            data = json.dumps(body).encode("utf-8")
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        req = urllib.request.Request(url, data=data, method=method, headers=headers)
+        try:
+            resp = self._open(req, timeout=self.timeout)
+            status = resp.status
+            raw = resp.read()
+            hdrs = resp.headers
+        except urllib.error.HTTPError as e:
+            status = e.code
+            hdrs = e.headers
+            try:
+                raw = e.read()
+            except Exception as rx:  # an interrupted error body is a transport failure, typed like any other
+                raise ZappyTransportError("Could not read the Zappy API response: " + rx.__class__.__name__, code="unreachable", status=status, meta=self._meta(hdrs, status)) from None
+            if 300 <= status < 400:
+                raise ZappyTransportError(f"Zappy API answered with a redirect (HTTP {status}), which this client never follows", code="bad_response", status=status, meta=self._meta(hdrs, status)) from None
+        except Exception as e:  # network, timeout, DNS
+            raise ZappyTransportError("Could not reach the Zappy API: " + (e.__class__.__name__ + ": " + str(e)), code="unreachable") from None
+        try:
+            meta = self._meta(hdrs, status)
+        except Exception:
+            meta = ResponseMeta(request_id=None, rate_limit=None, retry_after=None, status=status)
+        self.last_meta = meta
+        try:
+            parsed = json.loads(raw.decode("utf-8")) if raw else None
+        except Exception:
+            parsed = None
+        if status >= 400 or not isinstance(parsed, dict) or parsed.get("ok") is False:
+            if not isinstance(parsed, dict):
+                raise ZappyTransportError(f"Zappy returned an unreadable response (HTTP {status})", code="bad_response", status=status, meta=meta)
+            raise _error_for(status, parsed, meta)
+        out = Response(parsed)
+        out.meta = meta
+        return out
+
+    @staticmethod
+    def _meta(h: Any, status: int) -> ResponseMeta:
+        def n(k: str) -> Optional[int]:
+            v = h.get(k) if h is not None else None
+            try:
+                return int(v) if v not in (None, "") else None
+            except ValueError:
+                return None
+        limit, remaining, reset = n("RateLimit-Limit"), n("RateLimit-Remaining"), n("RateLimit-Reset")
+        rl = None if limit is None and remaining is None else RateLimit(limit, remaining, reset)
+        return ResponseMeta(request_id=h.get("X-Request-Id") if h is not None else None, rate_limit=rl, retry_after=n("Retry-After"), status=status)
+
+    # ---- read (free) ----
+    def capabilities(self) -> Response:
+        return self._request("GET", "capabilities")
+
+    def balance(self) -> Response:
+        return self._request("GET", "balance")
+
+    def usage(self) -> Response:
+        return self._request("GET", "usage")
+
+    def quote(self, capability: str, duration: Optional[int] = None) -> Response:
+        body: Dict[str, Any] = {"capability": capability}
+        if duration:
+            body["duration"] = int(duration)
+        return self._request("POST", "quote", body=body)
+
+    def get_job(self, job_id: str) -> Response:
+        return self._request("GET", "jobs/" + urllib.parse.quote(str(job_id), safe=""))
+
+    def get_asset(self, asset_id: str) -> Response:
+        return self._request("GET", "assets/" + urllib.parse.quote(str(asset_id), safe=""))
+
+    def list_creations(self, limit: Optional[int] = None, cursor: Optional[str] = None) -> Response:
+        return self._request("GET", "creations", query={"limit": limit, "cursor": cursor})
+
+    def wait_for_job(self, job_id: str, *, interval: float = 3.0, timeout: float = 600.0, on_poll: Optional[Callable[[dict], None]] = None) -> Response:
+        """Poll (free) until the job is terminal. Honours Retry-After. Returns the final job record."""
+        start = time.time()
+        while True:
+            j = self.get_job(job_id)
+            if on_poll:
+                on_poll(j)
+            st = str(j.get("status") or "")
+            if st in ("succeeded", "failed"):
+                return j
+            if time.time() - start > timeout:
+                raise ZappyError(f"Timed out waiting for job {job_id} (still {st or 'processing'}; keep polling get_job)", code="wait_timeout")
+            ra = j.meta.retry_after if j.meta else None
+            time.sleep(ra if ra else interval)
+
+    # ---- write (SPENDS CREDITS; never auto-retried) ----
+    def create_image(self, prompt: str, *, max_credits: int, aspect_ratio: Optional[str] = None, idempotency_key: Optional[str] = None,
+                     on_key: Optional[Callable[[str], None]] = None) -> Response:
+        """SPENDS CREDITS. Returns the API response with `.idempotency_key` set to the key used. `on_key` receives the key BEFORE
+        dispatch (persist it); any exception raised carries `.idempotency_key` too, so a lost response can be replayed safely."""
+        if not prompt:
+            raise ZappyError("prompt is required", code="prompt_required")
+        if not (isinstance(max_credits, int) and max_credits > 0):
+            raise ZappyError("max_credits is required: a paid call needs a hard credit ceiling", code="max_credits_required")
+        key = idempotency_key or new_idempotency_key("img")
+        body: Dict[str, Any] = {"prompt": prompt, "max_credits": int(max_credits)}
+        if aspect_ratio:
+            body["aspect_ratio"] = aspect_ratio
+        return self._paid("images", body, key, on_key)
+
+    def edit_image(self, source_asset_id: str, prompt: str, *, max_credits: int, aspect_ratio: Optional[str] = None, idempotency_key: Optional[str] = None,
+                   on_key: Optional[Callable[[str], None]] = None) -> Response:
+        """SPENDS CREDITS."""
+        if not source_asset_id or not prompt:
+            raise ZappyError("source_asset_id and prompt are required", code="source_required")
+        if not (isinstance(max_credits, int) and max_credits > 0):
+            raise ZappyError("max_credits is required: a paid call needs a hard credit ceiling", code="max_credits_required")
+        key = idempotency_key or new_idempotency_key("edit")
+        body: Dict[str, Any] = {"source_asset_id": source_asset_id, "prompt": prompt, "max_credits": int(max_credits)}
+        if aspect_ratio:
+            body["aspect_ratio"] = aspect_ratio
+        return self._paid("images/edit", body, key, on_key)
+
+    def _paid(self, path: str, body: dict, key: str, on_key: Optional[Callable[[str], None]]) -> Response:
+        """F5-BILL-001: the key is handed out BEFORE dispatch and attached to every outcome, including the exception."""
+        if on_key:
+            on_key(key)
+        try:
+            r = self._request("POST", path, body=body, idempotency_key=key)
+        except ZappyError as e:
+            e.idempotency_key = key
+            raise
+        except Exception as ex:  # anything else escaping the dispatch boundary still carries the key
+            err = ZappyTransportError("Paid request failed before a response could be read: " + ex.__class__.__name__ + ": " + str(ex), code="unreachable")
+            err.idempotency_key = key
+            raise err from None
+        r.idempotency_key = key  # type: ignore[attr-defined]
+        return r
+
+
+# ---- webhooks (zq.webhook.v1) ----
+def verify_webhook_signature(secret: str, header: str, raw_body: bytes, *, now: Optional[int] = None, window_seconds: int = 300) -> bool:
+    """Verify a Zappy webhook delivery (Zappy-Signature: t=..,v1=..) over the exact raw body. Constant-time compare."""
+    if not isinstance(secret, str) or not secret or not isinstance(header, str):
+        return False
+    t = None
+    sigs = []
+    for part in header.split(","):
+        if "=" not in part:
+            continue
+        k, v = part.split("=", 1)
+        k, v = k.strip(), v.strip()
+        if k == "t" and v.isdigit():
+            t = int(v)
+        if k == "v1" and re.fullmatch(r"[a-f0-9]{64}", v):
+            sigs.append(v)
+    if t is None or not sigs or abs((now if now is not None else int(time.time())) - t) > window_seconds:
+        return False
+    if isinstance(raw_body, str):
+        raw_body = raw_body.encode("utf-8")
+    want = hmac.new(secret.encode("utf-8"), str(t).encode("ascii") + b"." + raw_body, hashlib.sha256).hexdigest()
+    return any(hmac.compare_digest(want, s) for s in sigs)
+
+
+# ---- OAuth 2.1 PKCE helpers (pure functions; Zappy's authorization server stays the one auth implementation) ----
+def pkce_pair() -> dict:
+    verifier = base64.urlsafe_b64encode(secrets.token_bytes(48)).rstrip(b"=").decode("ascii")
+    challenge = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode("ascii")).digest()).rstrip(b"=").decode("ascii")
+    return {"verifier": verifier, "challenge": challenge, "method": "S256"}
+
+
+def authorize_url(*, client_id: str, redirect_uri: str, scope: str, state: str, challenge: str,
+                  resource: str = "https://zappyquote.com/api/v1", issuer: str = "https://zappyquote.com") -> str:
+    q = urllib.parse.urlencode({"client_id": client_id, "redirect_uri": redirect_uri, "response_type": "code", "scope": scope, "state": state,
+                                "code_challenge": challenge, "code_challenge_method": "S256", "resource": resource})
+    return issuer.rstrip("/") + "/oauth/authorize?" + q
+
+
+__all__ = ["Zappy", "ZappyError", "ZappyAuthError", "ZappyRateLimitError", "ZappySpendError", "ZappyNotFoundError", "ZappyUnavailableError",
+           "ZappyTransportError", "Response", "ResponseMeta", "RateLimit", "redact", "new_idempotency_key", "verify_webhook_signature",
+           "pkce_pair", "authorize_url", "SDK_VERSION", "CONTRACT", "DEFAULT_BASE_URL"]

zappyquote-0.2.0/zappyquote.egg-info/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.1
+Name: zappyquote
+Version: 0.2.0
+Summary: Official Zappy API client for Python - a thin wrapper over the documented Zappy API v1.
+Author: Zappy
+License: MIT
+Project-URL: Homepage, https://zappyquote.com/developers/
+Project-URL: Documentation, https://zappyquote.com/developers/
+Project-URL: Issues, https://zappyquote.com/contact.html
+Keywords: zappy,zappyquote,ai,image-generation,api,sdk
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# zappyquote
+
+The official Python client for the Zappy API v1 - a thin wrapper over the documented HTTP API
+(https://zappyquote.com/developers/). The server stays authoritative for pricing, caps, idempotency and ownership.
+
+Version 0.2.0 · contract `openapi-1.0.0@9dff9fdfbcd8c1bd` · Python 3.9+ · standard library only · MIT
+
+```bash
+# official download (always available):
+curl -O https://zappyquote.com/dl/zappyquote.py      # then: import zappyquote
+# PyPI, ONLY once https://zappyquote.com/developers/ lists zappyquote as published by Zappy:
+#   pip install zappyquote
+```
+
+```python
+from zappyquote import Zappy, ZappyError, new_idempotency_key
+
+zappy = Zappy()                                    # reads ZAPPY_API_KEY; or Zappy(api_key=...)
+caps = zappy.capabilities()["capabilities"]        # free
+quote = zappy.quote("zappy-image-pro")             # free, reserves nothing
+
+# BILLABLE. max_credits is a hard ceiling; the idempotency key makes a replay return the same job, never a second charge.
+key = new_idempotency_key("order-123")
+r = zappy.create_image("a lighthouse at dusk", max_credits=quote["credits_quoted"], idempotency_key=key)
+job = r if r["status"] == "succeeded" else zappy.wait_for_job(r["job_id"])   # 202 => poll (free)
+asset = zappy.get_asset(job["assets"][0]["asset_id"])                        # short-lived signed URL on Zappy's host
+```
+
+Every response is a `dict` with `.meta` (`request_id`, `rate_limit`, `retry_after`, `status`). Failures raise a
+`ZappyError` subclass with `code`, `status`, `request_id`, `retry_after`: `ZappyAuthError`, `ZappyRateLimitError`,
+`ZappySpendError`, `ZappyNotFoundError`, `ZappyUnavailableError`, `ZappyTransportError`. Messages never contain a credential.
+
+```python
+from zappyquote import verify_webhook_signature
+ok = verify_webhook_signature(secret, request.headers["Zappy-Signature"], request.get_data())   # exact raw bytes
+```
+
+`pkce_pair()` / `authorize_url(...)` build the OAuth authorization request for an app you registered in Zappy; consent
+and token exchange stay on Zappy's authorization server. Paid calls are never retried by this package.
+
+## Name
+
+The distribution and the import are both `zappyquote` (`import zappyquote`). The shorter name `zappy` is used on PyPI by an unrelated project whose distribution also installs a top-level `zappy` package; sharing that name would let either install silently replace the other. Version 0.2.0 is the first version under this name (0.1.0 was only ever a direct download, `/dl/zappy.py`, and is retired).
+
+### Migrating from the retired `/dl/zappy.py`
+
+1. Download `https://zappyquote.com/dl/zappyquote.py` next to your code.
+2. Change `import zappy` / `from zappy import ...` to `import zappyquote` / `from zappyquote import ...` (the API is unchanged).
+3. Delete your project-local `zappy.py` once you have confirmed it is the Zappy SDK (its docstring starts with
+   "zappy - the official Python client for the Zappy API v1"). Left in place, it would shadow any other `zappy` package.
+
+Registry packages are official only if https://zappyquote.com/developers/ lists them as published; until then use the download, and never install a look-alike name.

zappyquote-0.2.0/zappyquote.egg-info/SOURCES.txt

@@ -0,0 +1,8 @@
+LICENSE
+README.md
+pyproject.toml
+zappyquote/__init__.py
+zappyquote.egg-info/PKG-INFO
+zappyquote.egg-info/SOURCES.txt
+zappyquote.egg-info/dependency_links.txt
+zappyquote.egg-info/top_level.txt

zappyquote-0.2.0/zappyquote.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

zappyquote-0.2.0/zappyquote.egg-info/top_level.txt

@@ -0,0 +1 @@
+zappyquote