storeshot 0.1.0__py3-none-any.whl

storeshot/__init__.py

@@ -0,0 +1,41 @@
+"""The official Python SDK for the Storeshot API (SS-026). See README.md."""
+
+from __future__ import annotations
+
+from ._client import DEFAULT_BASE_URL, Storeshot
+from ._errors import (
+    SDK_ERROR_CODES,
+    StoreshotConnectionError,
+    StoreshotError,
+    StoreshotTimeoutError,
+    StoreshotWebhookError,
+)
+from ._generated.operations import CONTRACT_VERSION, ERROR_CODES, WEBHOOK_EVENT_TYPES
+from ._version import __version__
+from .webhooks import (
+    DEFAULT_WEBHOOK_TOLERANCE_SECONDS,
+    WEBHOOK_SIGNATURE_HEADER,
+    construct_webhook_event,
+    verify_webhook_signature,
+)
+
+SDK_VERSION = __version__
+
+__all__ = [
+    "CONTRACT_VERSION",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_WEBHOOK_TOLERANCE_SECONDS",
+    "ERROR_CODES",
+    "SDK_ERROR_CODES",
+    "SDK_VERSION",
+    "WEBHOOK_EVENT_TYPES",
+    "WEBHOOK_SIGNATURE_HEADER",
+    "Storeshot",
+    "StoreshotConnectionError",
+    "StoreshotError",
+    "StoreshotTimeoutError",
+    "StoreshotWebhookError",
+    "__version__",
+    "construct_webhook_event",
+    "verify_webhook_signature",
+]

storeshot/_client.py

@@ -0,0 +1,240 @@
+"""The Storeshot client (SS-026 §4.1, §7.2, §7.3)."""
+
+from __future__ import annotations
+
+import math
+import os
+import re
+import sys
+from collections.abc import Callable, Mapping
+from typing import Final, Literal, cast
+from urllib.parse import urlsplit, urlunsplit
+
+import httpx
+
+from ._compat import Unpack
+from ._core.headers import assert_credential, client_header, invalid, user_headers
+from ._core.options import ClientIdentity, RequestOptions
+from ._core.redact import mask_key
+from ._core.request import Requester, RequesterConfig, ResponseMeta
+from ._errors import StoreshotError
+from ._generated.schemas import Generation, HealthReport, Me, ScreenshotSet, StatusReport
+from ._helpers.wait import (
+    DEFAULT_POLL_INTERVAL,
+    DEFAULT_WAIT_TIMEOUT,
+    wait_for_generation,
+    wait_for_screenshot_set,
+)
+from ._resources.activity import Activity
+from ._resources.api_keys import ApiKeys
+from ._resources.auth import Auth
+from ._resources.billing import Billing
+from ._resources.catalog import Devices, Stores
+from ._resources.generations import Generations
+from ._resources.palettes import Palettes
+from ._resources.projects import Projects
+from ._resources.screenshot_sets import ScreenshotSets
+from ._resources.uploads import Uploads
+from ._resources.usage import Credits, Usage
+from ._resources.webhooks import Webhooks
+from ._version import __version__
+
+DEFAULT_BASE_URL: Final = "https://api.storeshot.art/v1"
+DEFAULT_TIMEOUT: Final = 60.0
+DEFAULT_MAX_RETRIES: Final = 2
+DEFAULT_MAX_RETRY_AFTER: Final = 60.0
+_LOOPBACK = re.compile(r"localhost|127(?:\.[0-9]{1,3}){3}|::1", re.ASCII)
+
+
+class _FromEnv:
+    def __repr__(self) -> str:
+        return "FROM_ENV"
+
+
+#: The default of `api_key`: read STORESHOT_API_KEY.
+FROM_ENV: Final = _FromEnv()
+
+
+def _env(name: str) -> str | None:
+    return os.environ.get(name) or None
+
+
+def normalise_base_url(value: str) -> str:
+    """https:, or http: on loopback only; no credentials, query or fragment (the CLI/TS rule)."""
+    try:
+        parts = urlsplit(value)
+        _ = parts.port
+    except ValueError:
+        raise invalid(f'base_url must be an absolute URL (got "{value}").') from None
+    if not parts.scheme or not parts.netloc:
+        raise invalid(f'base_url must be an absolute URL (got "{value}").')
+    host = (parts.hostname or "").lower()
+    plain_local = parts.scheme == "http" and _LOOPBACK.fullmatch(host) is not None
+    if parts.scheme != "https" and not plain_local:
+        raise invalid("base_url must use https: (http: only for localhost / 127.0.0.1 / [::1]).")
+    if parts.username is not None or parts.password is not None or parts.query or parts.fragment:
+        raise invalid("base_url may not contain credentials, a query or a fragment.")
+    return urlunsplit((parts.scheme, parts.netloc.lower(), parts.path, "", "")).rstrip("/")
+
+
+def _number(name: str, value: float, maximum: float = math.inf) -> float:
+    if (
+        isinstance(value, bool)
+        or not isinstance(value, (int, float))
+        or not math.isfinite(value)
+        or not 0 <= value <= maximum
+    ):
+        raise invalid(f"{name} must be a number between 0 and {maximum:g}.")
+    return float(value)
+
+
+class Storeshot:
+    """The Storeshot API client. One instance per API key; it holds no per-request state.
+
+    `api_key` defaults to STORESHOT_API_KEY; `Storeshot(None)` is a key-less client for
+    `client.auth.*` only (device authorization).
+    """
+
+    def __init__(
+        self,
+        api_key: str | None | _FromEnv = FROM_ENV,
+        *,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        max_retry_after: float = DEFAULT_MAX_RETRY_AFTER,
+        http_client: httpx.Client | None = None,
+        client_identity: ClientIdentity | None = None,
+        default_headers: Mapping[str, str] | None = None,
+        on_response: Callable[[ResponseMeta], None] | None = None,
+        environment: Literal["test", "live"] | None = None,
+        dangerously_allow_browser: bool = False,
+    ) -> None:
+        key = _env("STORESHOT_API_KEY") if isinstance(api_key, _FromEnv) else api_key
+        if key == "" or (key is None and isinstance(api_key, _FromEnv)):
+            raise StoreshotError(
+                "MISSING_API_KEY",
+                "No API key: set STORESHOT_API_KEY (or pass api_key). Create a free test key "
+                "(ss_test_…) at https://console.storeshot.art/. Never paste a key into a chat, a "
+                "log or a commit.",
+            )
+        if key is not None:
+            assert_credential(key)
+        if environment is not None:
+            if environment not in ("test", "live"):
+                raise invalid('environment must be "test" or "live".')
+            if key is None or not key.startswith(f"ss_{environment}_"):
+                held = mask_key(key) if key else "no key"
+                raise invalid(
+                    f'environment="{environment}" needs an ss_{environment}_ key; this client '
+                    f"has {held}."
+                )
+        if sys.platform == "emscripten" and not dangerously_allow_browser:
+            raise StoreshotError(
+                "BROWSER_NOT_ALLOWED",
+                "Storeshot API keys are secrets: call the API from your server, not from a web "
+                "page (Pyodide). Pass dangerously_allow_browser=True only if you accept that every "
+                "visitor can read the key.",
+            )
+        self.base_url = normalise_base_url(
+            base_url or _env("STORESHOT_BASE_URL") or DEFAULT_BASE_URL
+        )
+        self._api_key = key
+        settings = RequesterConfig(
+            api_key=key,
+            base_url=self.base_url,
+            http=http_client if http_client is not None else httpx.Client(),
+            timeout=_number("timeout", timeout),
+            max_retries=math.floor(_number("max_retries", max_retries, 10)),
+            max_retry_after=_number("max_retry_after", max_retry_after),
+            client_header=client_header(client_identity),
+            user_agent=f"storeshot-sdk-python/{__version__}",
+            default_headers=user_headers(default_headers),
+            on_response=on_response,
+        )
+        self._owns_http = http_client is None
+        self._http = settings.http
+        self._requester = r = Requester(settings)
+        self.devices = Devices(r)
+        self.stores = Stores(r)
+        self.api_keys = ApiKeys(r)
+        self.credits = Credits(r)
+        self.usage = Usage(r)
+        self.uploads = Uploads(r)
+        self.generations = Generations(r)
+        self.screenshot_sets = ScreenshotSets(r)
+        self.projects = Projects(r)
+        self.palettes = Palettes(r)
+        self.webhooks = Webhooks(r)
+        self.activity = Activity(r)
+        self.billing = Billing(r)
+        #: Device authorization (RFC 8628): get an API key with your human's approval.
+        self.auth = Auth(r)
+
+    @property
+    def environment(self) -> Literal["test", "live"] | None:
+        """The key environment from the key prefix (None for a JWT or a key-less client)."""
+        match = re.match(r"ss_(test|live)_", self._api_key or "")
+        return cast(Literal["test", "live"], match.group(1)) if match else None
+
+    def me(self, **options: Unpack[RequestOptions]) -> Me:
+        """`GET /me`: the account and the credential (environment, scopes)."""
+        return cast(Me, self._requester.call("getMe", options=options))
+
+    def health(self, **options: Unpack[RequestOptions]) -> HealthReport:
+        """`GET /health` (public)."""
+        return cast(HealthReport, self._requester.call("getHealth", options=options))
+
+    def status(self, **options: Unpack[RequestOptions]) -> StatusReport:
+        """`GET /status` (public)."""
+        return cast(StatusReport, self._requester.call("getStatus", options=options))
+
+    def wait_for_generation(
+        self,
+        target: str | Generation,
+        /,
+        *,
+        timeout: float = DEFAULT_WAIT_TIMEOUT,
+        poll_interval: float = DEFAULT_POLL_INTERVAL,
+    ) -> Generation:
+        """Returns the generation once it is succeeded, failed or canceled (long-polls with
+        Prefer: wait). Raises StoreshotTimeoutError WAIT_TIMEOUT after `timeout` seconds."""
+        return wait_for_generation(
+            lambda id, wait: self.generations.get(id, wait=wait),
+            target,
+            timeout=timeout,
+            poll_interval=poll_interval,
+        )
+
+    def wait_for_screenshot_set(
+        self,
+        target: str | ScreenshotSet,
+        /,
+        *,
+        timeout: float = DEFAULT_WAIT_TIMEOUT,
+        poll_interval: float = DEFAULT_POLL_INTERVAL,
+    ) -> ScreenshotSet:
+        """Returns the set once it is succeeded, partially_failed, failed or canceled."""
+        return wait_for_screenshot_set(
+            lambda id: self.screenshot_sets.get(id),
+            target,
+            timeout=timeout,
+            poll_interval=poll_interval,
+        )
+
+    def close(self) -> None:
+        """Closes the HTTP client the SDK created (never one you passed)."""
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> Storeshot:
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        shown = "none" if self._api_key is None else mask_key(self._api_key)
+        return f"Storeshot(base_url={self.base_url}, api_key={shown})"
+
+    __str__ = __repr__

storeshot/_compat.py

@@ -0,0 +1,19 @@
+"""Typing names that moved into `typing` in Python 3.11 (SS-026 §3.2)."""
+
+from __future__ import annotations
+
+import sys
+
+if sys.version_info >= (3, 11):
+    from typing import NotRequired, Required, TypedDict, Unpack, get_type_hints, is_typeddict
+else:  # pragma: no cover - exercised by the Python 3.10 CI leg
+    from typing_extensions import (
+        NotRequired,
+        Required,
+        TypedDict,
+        Unpack,
+        get_type_hints,
+        is_typeddict,
+    )
+
+__all__ = ["NotRequired", "Required", "TypedDict", "Unpack", "get_type_hints", "is_typeddict"]

storeshot/_core/__init__.py

@@ -0,0 +1 @@
+"""The SDK core (SS-026 §6): pure helpers plus the one synchronous I/O loop."""

storeshot/_core/clock.py

@@ -0,0 +1,26 @@
+"""Time and randomness seams (SS-026 §6.2): tests replace these module attributes.
+
+Callers import the module (`from . import clock`) and call `clock.sleep(...)`, so that
+monkeypatching works.
+"""
+
+from __future__ import annotations
+
+import random as _random
+import time as _time
+
+
+def sleep(seconds: float) -> None:
+    _time.sleep(seconds)
+
+
+def monotonic() -> float:
+    return _time.monotonic()
+
+
+def time() -> float:
+    return _time.time()
+
+
+def random() -> float:
+    return _random.random()

storeshot/_core/headers.py

@@ -0,0 +1,67 @@
+"""Header and credential rules shared with the server and the TS SDK (SS-026 §6.1, §7.2)."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+
+from .._errors import StoreshotError
+from .._version import __version__
+from .options import ClientIdentity
+
+#: Same rule as the server (v1/attribution.ts); an invalid header would be ignored there.
+CLIENT_HEADER_PATTERN = re.compile(r"(?:api|web|mcp|cli)/[A-Za-z0-9._@+-]{1,100}", re.ASCII)
+#: Same rule as the server's request-id middleware.
+REQUEST_ID_PATTERN = re.compile(r"[A-Za-z0-9_\-=]{1,128}", re.ASCII)
+IDEMPOTENCY_KEY_PATTERN = re.compile(r"[\x20-\x7e]{1,255}")
+CREDENTIAL_PATTERN = re.compile(r"[\x21-\x7e]+")
+HEADER_VALUE_PATTERN = re.compile(r"[\t\x20-\x7e]*")
+#: Headers the SDK owns; default and per-call headers may not set them.
+RESERVED_HEADERS = ("authorization", "x-storeshot-client", "idempotency-key")
+
+
+def invalid(message: str) -> StoreshotError:
+    return StoreshotError("INVALID_CONFIGURATION", message)
+
+
+def default_client_name() -> str:
+    return f"storeshot-sdk-python@{__version__}"
+
+
+def client_header(identity: ClientIdentity | None) -> str:
+    """The X-Storeshot-Client value, validated so the server never silently drops it."""
+    identity = identity or {}
+    value = f"{identity.get('surface', 'api')}/{identity.get('name', default_client_name())}"
+    if not CLIENT_HEADER_PATTERN.fullmatch(value):
+        raise invalid(
+            f'Invalid client identity "{value}": surface api|web|mcp|cli, name of 1–100 '
+            "characters A-Z a-z 0-9 . _ @ + -."
+        )
+    return value
+
+
+def assert_credential(value: str) -> None:
+    """Credentials: printable ASCII without spaces (no header injection, no stray newline)."""
+    if not CREDENTIAL_PATTERN.fullmatch(value):
+        raise invalid("The API key contains whitespace or non-printable characters.")
+
+
+def assert_header_value(name: str, value: str) -> None:
+    if not HEADER_VALUE_PATTERN.fullmatch(value):
+        raise invalid(f"Header {name} has a line break or a non-ASCII character.")
+
+
+def assert_request_id(value: str) -> None:
+    if not REQUEST_ID_PATTERN.fullmatch(value):
+        raise invalid("request_id must be 1–128 characters of A-Z a-z 0-9 _ - =.")
+
+
+def user_headers(headers: Mapping[str, str] | None) -> dict[str, str]:
+    """Validates user-supplied headers and refuses the ones the SDK owns."""
+    out: dict[str, str] = {}
+    for name, value in (headers or {}).items():
+        if name.lower() in RESERVED_HEADERS:
+            raise invalid(f"Header {name} is set by the SDK; use the matching option instead.")
+        assert_header_value(name, value)
+        out[name] = value
+    return out

storeshot/_core/operation.py

@@ -0,0 +1,23 @@
+"""One API operation's method, path and request traits (SS-026 §5; generated in operations.py)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Operation:
+    method: str
+    path: str
+    tag: str | None
+    idempotency_key: bool
+    wait: bool
+    path_params: tuple[str, ...]
+    query_params: tuple[str, ...]
+    body: str
+    success_statuses: tuple[int, ...]
+    binary: bool
+    #: Component name of the JSON request body, if any.
+    request_schema: str | None
+    #: Component names a 2xx JSON answer may have (anyOf flattened), sorted.
+    response_schemas: tuple[str, ...]

storeshot/_core/options.py

@@ -0,0 +1,31 @@
+"""Per-call options and the client identity (SS-026 §4.1)."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import TYPE_CHECKING, Literal
+
+from .._compat import TypedDict
+
+if TYPE_CHECKING:
+    from .request import ResponseMeta
+
+
+class RequestOptions(TypedDict, total=False):
+    """Keyword options every method accepts."""
+
+    timeout: float
+    """Seconds per network operation of each attempt (overrides the client's)."""
+    max_retries: int
+    request_id: str
+    """Sent as X-Request-Id (1–128 of A-Z a-z 0-9 _ - =) to correlate with your logs."""
+    headers: Mapping[str, str]
+    on_response: Callable[[ResponseMeta], None]
+
+
+class ClientIdentity(TypedDict, total=False):
+    """X-Storeshot-Client: `api` by default; `cli`/`mcp` for such tools (usage labels)."""
+
+    surface: Literal["api", "web", "mcp", "cli"]
+    name: str
+    """1–100 of A-Z a-z 0-9 . _ @ + -, for example `my-tool@1.2.0`."""

storeshot/_core/redact.py

@@ -0,0 +1,38 @@
+"""Secrets never leave the SDK in a message (SS-026 §7.1): same rules as the TS SDK."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from typing import Any
+
+#: Storeshot API keys anywhere in a text (the secret part is at least 8 characters).
+KEY_PATTERN = re.compile(r"\bss_(live|test)_[A-Za-z0-9_-]{8,}", re.ASCII)
+MAX_DEPTH = 8
+
+
+def scrub(text: str, secrets: Sequence[str] = ()) -> str:
+    """Removes the given secrets and anything shaped like an API key from a text."""
+    for secret in secrets:
+        if secret:
+            text = text.replace(secret, "[redacted]")
+    return KEY_PATTERN.sub(lambda m: f"ss_{m.group(1)}_[redacted]", text)
+
+
+def scrub_value(value: Any, secrets: Sequence[str] = (), depth: int = 0) -> Any:
+    """`scrub` applied to every string of a JSON-like value (error details)."""
+    if isinstance(value, str):
+        return scrub(value, secrets)
+    if depth >= MAX_DEPTH:
+        return value
+    if isinstance(value, list):
+        return [scrub_value(item, secrets, depth + 1) for item in value]
+    if isinstance(value, dict):
+        return {key: scrub_value(item, secrets, depth + 1) for key, item in value.items()}
+    return value
+
+
+def mask_key(key: str) -> str:
+    """What may be shown of a credential: the key environment prefix only."""
+    match = re.match(r"ss_(live|test)_", key)
+    return f"{match.group(0)}…" if match else "…"