vatly-api-python 0.1.0a2__py3-none-any.whl

vatly/webhooks.py

@@ -0,0 +1,146 @@
+"""Raw-body HMAC verification and typed, forward-compatible webhook deliveries."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import math
+import re
+import time
+from collections.abc import Sequence
+from datetime import datetime
+from typing import Any, Literal, get_args
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+from .errors import VatlyInvalidSignatureError
+from .models import WebhookDelivery
+
+VATLY_SIGNATURE_HEADER = "Vatly-Signature"
+VATLY_EVENT_ID_HEADER = "Vatly-Event-Id"
+WEBHOOK_EVENT_NAMES: tuple[str, ...] = get_args(
+    WebhookDelivery.model_fields["event_name"].annotation
+)
+
+
+class KnownWebhookEvent(WebhookDelivery):
+    known: Literal[True] = True
+
+
+class UnsupportedWebhookEvent(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+    known: Literal[False] = False
+    id: str
+    resource: Literal["webhook_event"]
+    event_name: str = Field(alias="eventName")
+    reason: str | None
+    entity_type: str = Field(alias="entityType")
+    entity_id: str = Field(alias="entityId")
+    object: Any
+    created_at: datetime = Field(alias="createdAt")
+    testmode: bool
+
+
+VatlyWebhookEvent = KnownWebhookEvent | UnsupportedWebhookEvent
+
+
+def compute_signature_v1(raw_body: bytes | str, secret: str, timestamp: int) -> str:
+    if isinstance(timestamp, bool) or not isinstance(timestamp, int) or timestamp < 0:
+        raise ValueError("timestamp must be a non-negative integer")
+    body = raw_body.encode("utf-8") if isinstance(raw_body, str) else raw_body
+    return hmac.new(
+        secret.encode("utf-8"), str(timestamp).encode() + b"." + body, hashlib.sha256
+    ).hexdigest()
+
+
+def verify_webhook_signature(
+    raw_body: bytes | str,
+    signature_header: str | None,
+    secret: str | Sequence[str],
+    *,
+    tolerance: float = 300,
+    now: float | None = None,
+) -> None:
+    """Verify exact bytes. Zero tolerance disables freshness, not deduplication."""
+    if not math.isfinite(tolerance) or tolerance < 0:
+        raise ValueError("tolerance must be finite and non-negative")
+    secrets = [secret] if isinstance(secret, str) else list(secret)
+    if not secrets or any(not s for s in secrets):
+        raise VatlyInvalidSignatureError("At least one non-empty webhook secret is required")
+    if not signature_header:
+        raise VatlyInvalidSignatureError("Missing webhook signature")
+    parts = {}
+    for piece in signature_header.split(","):
+        key, sep, value = piece.strip().partition("=")
+        if sep:
+            parts[key.strip()] = value.strip()
+    stamp = parts.get("t", "")
+    signature = parts.get("v1", "")
+    if not re.fullmatch(r"[0-9]{1,15}", stamp) or not re.fullmatch(r"[0-9a-fA-F]{64}", signature):
+        raise VatlyInvalidSignatureError("Malformed timestamp or v1 signature")
+    timestamp = int(stamp)
+    current = time.time() if now is None else now
+    if not math.isfinite(current):
+        raise ValueError("now must be finite")
+    if tolerance and abs(current - timestamp) > tolerance:
+        raise VatlyInvalidSignatureError("Webhook timestamp outside tolerance")
+    valid = False
+    for candidate in secrets:
+        valid |= hmac.compare_digest(
+            compute_signature_v1(raw_body, candidate, timestamp), signature.lower()
+        )
+    if not valid:
+        raise VatlyInvalidSignatureError("Invalid webhook signature")
+
+
+def is_valid_webhook_signature(
+    raw_body: bytes | str,
+    signature_header: str | None,
+    secret: str | Sequence[str],
+    *,
+    tolerance: float = 300,
+    now: float | None = None,
+) -> bool:
+    try:
+        verify_webhook_signature(raw_body, signature_header, secret, tolerance=tolerance, now=now)
+        return True
+    except VatlyInvalidSignatureError:
+        return False
+
+
+def construct_event(
+    raw_body: bytes | str,
+    signature_header: str | None,
+    secret: str | Sequence[str],
+    *,
+    tolerance: float = 300,
+    now: float | None = None,
+) -> WebhookDelivery:
+    verify_webhook_signature(raw_body, signature_header, secret, tolerance=tolerance, now=now)
+    try:
+        return WebhookDelivery.model_validate_json(raw_body)
+    except ValidationError as exc:
+        raise VatlyInvalidSignatureError("Invalid webhook JSON or envelope") from exc
+
+
+def construct_webhook_event(
+    raw_body: bytes | str,
+    signature_header: str | None,
+    secret: str | Sequence[str],
+    *,
+    tolerance: float = 300,
+    now: float | None = None,
+) -> VatlyWebhookEvent:
+    verify_webhook_signature(raw_body, signature_header, secret, tolerance=tolerance, now=now)
+    try:
+        payload = json.loads(raw_body)
+        if not isinstance(payload, dict):
+            raise ValueError("Envelope must be an object")
+        # `known` is SDK-owned; never trust a supplied discriminator.
+        payload.pop("known", None)
+        if payload.get("eventName") in WEBHOOK_EVENT_NAMES:
+            return KnownWebhookEvent.model_validate(payload)
+        return UnsupportedWebhookEvent.model_validate(payload)
+    except (ValueError, UnicodeDecodeError) as exc:
+        raise VatlyInvalidSignatureError("Invalid webhook JSON or envelope") from exc

vatly_api_python-0.1.0a2.dist-info/METADATA

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: vatly-api-python
+Version: 0.1.0a2
+Summary: Python SDK for Vatly, the merchant of record for AI, software and digital products
+Project-URL: Homepage, https://github.com/vatly/vatly-api-python
+Project-URL: Documentation, https://docs.vatly.com
+Project-URL: Issues, https://github.com/vatly/vatly-api-python/issues
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.11
+Requires-Dist: typing-extensions<5,>=4.12
+Description-Content-Type: text/markdown
+
+# Vatly Python SDK
+
+> **Alpha — under active development. Every alpha release may include breaking changes. Pin exact versions during alpha.**
+
+Python SDK for Vatly, the merchant of record for AI, software and digital products.
+Python 3.10+, Pydantic v2 models, and pooled httpx sync/async clients. All 50 production
+OpenAPI operations are covered. No package has been published yet.
+
+## Installation
+
+Once published:
+
+```bash
+pip install vatly-api-python==0.1.0a2
+```
+
+For local development: `uv sync --locked`.
+
+## Quick start
+
+Get a test or live API key from [the dashboard](https://my.vatly.com), under Settings > API.
+Keep keys server-side. The client reads `VATLY_API_KEY` by default.
+
+```python
+from vatly import VatlyClient
+from vatly.models import CreateCheckoutRequest
+
+with VatlyClient() as vatly:
+    checkout = vatly.checkouts.create(
+        CreateCheckoutRequest(
+            redirect_url_success="https://example.com/success",
+            redirect_url_canceled="https://example.com/canceled",
+            products=[{"id": "subscription_plan_abc123", "quantity": 1}],
+        )
+    )
+    print(checkout.links.checkout_url.href)
+```
+
+```python
+from vatly import AsyncVatlyClient
+
+
+async def read_orders():
+    async with AsyncVatlyClient() as vatly:
+        async for order in vatly.orders.list_all({"limit": 100}):
+            print(order.id, order.total)
+```
+
+Pydantic models use snake_case attributes and accept Vatly's camelCase aliases.
+Dictionary inputs use **wire-format camelCase keys**. Model requests serialize with
+aliases and omit unset fields; explicitly supplied `None` is sent as JSON null.
+Money values remain decimal **strings**, never floats.
+
+## Configuration and reliability
+
+```python
+from vatly import VatlyClient, RequestOptions
+
+with VatlyClient(timeout=30, max_retries=2) as vatly:
+    page = vatly.customers.list({"limit": 25}, options=RequestOptions(timeout=10))
+```
+
+Timeouts are **seconds per httpx network phase per attempt**, not a total request deadline;
+zero disables timeouts. Default base URL: `https://api.vatly.com/v1`.
+`base_url`, `default_headers`, and `transport` (an httpx transport) can be overridden.
+`mode` exposes `test` or `live`. Test helpers reject live keys before sending.
+
+POST/PATCH/PUT/DELETE receive a UUID idempotency key, reused across retries.
+Set `RequestOptions(idempotency_key="your-operation-id")` to reuse a business-operation key
+across separate SDK calls. Set `idempotency_key_generator=None` to disable auto-keys.
+GETs and keyed mutations retry 429, 5xx, timeouts and connection errors with exponential
+backoff (250ms to 8s plus jitter), honoring numeric or HTTP-date `Retry-After`.
+Keyed 409 retries **only** `details.idempotency_outcome == "in_progress"`.
+Never blindly retry an `unknown` idempotency outcome: read/reconcile the resource first.
+Unkeyed mutations do not retry. Redirects are not followed.
+
+`Vatly-Client-Info` identifies SDK/runtime/OS/architecture. Pass
+`client_info={"app": "MyApp/1.0", "framework": "Django/5"}` to add sanitized identifiers,
+or `client_info=False` to suppress the SDK-generated header.
+
+## Errors
+
+All API/transport errors extend `VatlyError`, with `status`, `body`, `url`, `method`,
+`details`, `errors` and `retry_after`. Network errors retain the httpx exception as `__cause__`.
+
+| Status | Error |
+| --- | --- |
+| 401 | `VatlyAuthError` |
+| 403 | `VatlyForbiddenError` |
+| 404 | `VatlyNotFoundError` |
+| 409 | `VatlyConflictError` |
+| 422 | `VatlyValidationError` |
+| 429 | `VatlyRateLimitError` |
+| Other / invalid response | `VatlyApiError` |
+| Network / timeout | `VatlyConnectionError` / `VatlyTimeoutError` |
+
+```python
+from vatly import VatlyValidationError
+
+try:
+    # Your API call here
+    pass
+except VatlyValidationError as error:
+    print(error.errors)
+```
+
+See [getting started and resource guides](docs/README.md), the generated
+[method inventory](docs/API.md), [webhook guide](docs/Webhooks.md), and
+[production API reference](https://docs.vatly.com/api-reference).
+
+## Development
+
+Run `.agents/setup` in a fresh orb. It installs uv if missing, provisions Python 3.12,
+syncs locked dependencies and runs an import sanity check. Warm runs reuse uv's caches.
+
+```bash
+uv run python scripts/generate.py --check
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+uv run pytest
+uv build
+uv run twine check dist/*
+```
+
+See [maintainer notes](docs/Development.md) for spec regeneration, docs sync, and trusted publishing.

vatly_api_python-0.1.0a2.dist-info/RECORD

@@ -0,0 +1,15 @@
+vatly/__init__.py,sha256=9TDFCpOAM591UZ2dxrrOVkRDwRUo0eKiOzc7qRZEtBA,1003
+vatly/_model.py,sha256=JBRyh3t064-3zgYd_MWqWkzt8tT50AYz6aI0MFU939s,424
+vatly/_transport.py,sha256=DQeNGu3ygN6Y-PF0Gz_w0fsfPlthswQiztd9B1tf6RM,10743
+vatly/_version.py,sha256=MVC3xG9U8KXXTiZ2FMZ9ARASAJV2A-Qu7UcliE-N_hI,24
+vatly/client.py,sha256=eIc25KLNh5o2l98JcXgnbKKoMtgxbrHp3kka0HEWGaU,2947
+vatly/errors.py,sha256=5jt0xjLYjfpGN6IbSSWgZfRVf7aKuiwjrlrYx4C6XT4,1881
+vatly/models.py,sha256=Nou8Ome0kMXbFb2hniHXs_5qZuT9V77GDgO9jjtUcxw,118964
+vatly/pagination.py,sha256=QNzrFd9a3umT6xx1Rcc7YoGIwF9VOP5n0vLZYbbu1CM,853
+vatly/py.typed,sha256=-lBwBtQZPKsgcrt4OLCCZA8mJQAMAnBGxQhahf5SL88,58
+vatly/resources.py,sha256=w9cQXnmESU6it1JJjIQKcDJSewAOGsJbBN9tq8lZ_gg,64541
+vatly/webhooks.py,sha256=C082LOgJ-Dc_Bd5ZRNRhwjJNkHFFbI-sXZpUeaNbaCI,5165
+vatly_api_python-0.1.0a2.dist-info/METADATA,sha256=G0uAhhURWadTZ7PTZ4ae63vdWk7Hd-YwLmFN0XLQPRg,5140
+vatly_api_python-0.1.0a2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+vatly_api_python-0.1.0a2.dist-info/licenses/LICENSE,sha256=CkjDnWn3u8SlJD-QfG6Bd_2O7ZtuzM0nzfpy9E-AQsw,1062
+vatly_api_python-0.1.0a2.dist-info/RECORD,,

vatly_api_python-0.1.0a2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

vatly_api_python-0.1.0a2.dist-info/licenses/LICENSE

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