axivoy 1.0.0__tar.gz

axivoy-1.0.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+dist/
+__pycache__/
+*.egg-info/
+axivoy/generated.py

axivoy-1.0.0/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.5
+Name: axivoy
+Version: 1.0.0
+Summary: Typed client for the Axivoy API: operations, webhooks and errors.
+Project-URL: Documentation, https://app.axivoy.ai/developers
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# axivoy
+
+Typed client for the [Axivoy API](https://app.axivoy.ai/developers): every published operation, refusals as exceptions and webhook signature checks. Generated from the public OpenAPI reference; standard library only, Python 3.11+.
+
+```python
+import os
+from axivoy import AxivoyClient, client_credentials
+
+client = AxivoyClient(token=client_credentials(os.environ["AXIVOY_CLIENT_ID"], os.environ["AXIVOY_CLIENT_SECRET"]))
+page = client.call("loads.list", {"limit": 25})
+```
+
+Guide: [Client libraries](https://app.axivoy.ai/developers/guides/client-libraries).
+
+## Maintainers
+
+Source lives in the Axivoy TMS repository under `clients/python` and is released by the `client-libraries` workflow when the reference changes. `py scripts/generate.py` rebuilds `axivoy/generated.py` from `docs/api/openapi-public.json`; `py -m unittest discover tests`; `py scripts/smoke.py` runs against a live install.

axivoy-1.0.0/README.md

@@ -0,0 +1,17 @@
+# axivoy
+
+Typed client for the [Axivoy API](https://app.axivoy.ai/developers): every published operation, refusals as exceptions and webhook signature checks. Generated from the public OpenAPI reference; standard library only, Python 3.11+.
+
+```python
+import os
+from axivoy import AxivoyClient, client_credentials
+
+client = AxivoyClient(token=client_credentials(os.environ["AXIVOY_CLIENT_ID"], os.environ["AXIVOY_CLIENT_SECRET"]))
+page = client.call("loads.list", {"limit": 25})
+```
+
+Guide: [Client libraries](https://app.axivoy.ai/developers/guides/client-libraries).
+
+## Maintainers
+
+Source lives in the Axivoy TMS repository under `clients/python` and is released by the `client-libraries` workflow when the reference changes. `py scripts/generate.py` rebuilds `axivoy/generated.py` from `docs/api/openapi-public.json`; `py -m unittest discover tests`; `py scripts/smoke.py` runs against a live install.

axivoy-1.0.0/axivoy/__init__.py

@@ -0,0 +1,33 @@
+"""Axivoy API client: operations, webhooks and errors. Docs: https://app.axivoy.ai/developers"""
+
+from .client import (
+    DEFAULT_BASE_URL,
+    DEFAULT_TOKEN_URL,
+    AxivoyClient,
+    Response,
+    Transport,
+    client_credentials,
+    urllib_transport,
+)
+from .errors import AxivoyError, AxivoyProposal, AxivoyWebhookError
+from .generated import API_VERSION, EventType, OperationKey
+from .webhooks import verify_webhook
+
+__version__ = API_VERSION
+
+__all__ = [
+    "API_VERSION",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_TOKEN_URL",
+    "AxivoyClient",
+    "AxivoyError",
+    "AxivoyProposal",
+    "AxivoyWebhookError",
+    "EventType",
+    "OperationKey",
+    "Response",
+    "Transport",
+    "client_credentials",
+    "urllib_transport",
+    "verify_webhook",
+]

axivoy-1.0.0/axivoy/client.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+import json
+import random
+import ssl
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, Mapping, Optional, Union
+
+from .errors import AxivoyError, AxivoyProposal
+
+DEFAULT_BASE_URL = "https://api.axivoy.ai/v1"
+DEFAULT_TOKEN_URL = "https://app.axivoy.ai/oauth/token"
+DRY_RUN_HEADER = "Axivoy-Dry-Run"
+
+TokenSource = Union[str, Callable[[], str]]
+
+
+@dataclass
+class Response:
+    status: int
+    headers: Mapping[str, str]
+    body: bytes
+
+
+Transport = Callable[[str, bytes, Dict[str, str], float], Response]
+
+
+def urllib_transport(ssl_context: Optional[ssl.SSLContext] = None) -> Transport:
+    """The default transport (standard library only)."""
+
+    def send(url: str, data: bytes, headers: Dict[str, str], timeout: float) -> Response:
+        request = urllib.request.Request(url, data=data, headers=headers, method="POST")
+        try:
+            with urllib.request.urlopen(request, timeout=timeout, context=ssl_context) as reply:
+                return Response(reply.status, dict(reply.headers.items()), reply.read())
+        except urllib.error.HTTPError as error:
+            return Response(error.code, dict(error.headers.items()), error.read())
+
+    return send
+
+
+def client_credentials(
+    client_id: str,
+    client_secret: str,
+    token_url: str = DEFAULT_TOKEN_URL,
+    transport: Optional[Transport] = None,
+    timeout: float = 30.0,
+) -> Callable[[], str]:
+    """A token source for an API key: reuses the token until a minute before it expires."""
+    send = transport or urllib_transport()
+    cached: Dict[str, Any] = {}
+
+    def token() -> str:
+        if cached and time.monotonic() < cached["expires_at"]:
+            return str(cached["token"])
+        data = urllib.parse.urlencode(
+            {"grant_type": "client_credentials", "client_id": client_id, "client_secret": client_secret}
+        ).encode()
+        reply = send(token_url, data, {"Accept": "application/json", "Content-Type": "application/x-www-form-urlencoded"}, timeout)
+        body = _json(reply.body)
+        if reply.status != 200 or not isinstance(body.get("access_token"), str):
+            raise AxivoyError(
+                reply.status,
+                {
+                    "code": body.get("error", "token_failed"),
+                    "message": body.get("error_description", f"Token request failed with HTTP {reply.status}."),
+                },
+            )
+        lifetime = body.get("expires_in") if isinstance(body.get("expires_in"), int) else 3600
+        cached.update(token=body["access_token"], expires_at=time.monotonic() + max(0, lifetime - 60))
+        return str(body["access_token"])
+
+    return token
+
+
+@dataclass
+class AxivoyClient:
+    """Runs Axivoy operations: ``client.call("loads.list", {"limit": 25})``.
+
+    ``token`` is an access token or a function returning a fresh one
+    (see ``client_credentials``). Network errors, 429, 409 ``in_flight`` and
+    5xx are retried up to ``max_retries`` times with the same idempotency key.
+    """
+
+    token: TokenSource
+    base_url: str = DEFAULT_BASE_URL
+    max_retries: int = 3
+    timeout: float = 30.0
+    transport: Transport = field(default_factory=urllib_transport)
+
+    def call(self, key: str, input: Optional[Mapping[str, Any]] = None, *, idempotency_key: Optional[str] = None) -> Any:
+        """Runs one operation and returns its ``result``.
+
+        Raises ``AxivoyError`` when refused and ``AxivoyProposal`` when the
+        write was sent for approval.
+        """
+        return self._post(key, input, idempotency_key, dry_run=False)["result"]
+
+    def dry_run(self, key: str, input: Optional[Mapping[str, Any]] = None, *, idempotency_key: Optional[str] = None) -> Dict[str, Any]:
+        """Validates and authorizes without running anything: ``{"outcome", "input", "simulation"?}``."""
+        return self._post(key, input, idempotency_key, dry_run=True)["dry_run"]
+
+    def _post(self, key: str, input: Optional[Mapping[str, Any]], idempotency_key: Optional[str], dry_run: bool) -> Dict[str, Any]:
+        url = f"{self.base_url.rstrip('/')}/ops/{urllib.parse.quote(key, safe='.')}"
+        data = json.dumps(dict(input or {})).encode()
+        idempotency = idempotency_key or str(uuid.uuid4())
+        attempt = 0
+        while True:
+            headers = {
+                "Authorization": f"Bearer {self._token()}",
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+                "Idempotency-Key": idempotency,
+            }
+            if dry_run:
+                headers[DRY_RUN_HEADER] = "true"
+            try:
+                reply = self.transport(url, data, headers, self.timeout)
+            except (urllib.error.URLError, OSError):
+                if attempt >= self.max_retries:
+                    raise
+                time.sleep(_backoff(attempt))
+                attempt += 1
+                continue
+
+            body = _json(reply.body)
+            if reply.status == 200:
+                return body
+            if reply.status == 202 and isinstance(body.get("proposal"), dict):
+                raise AxivoyProposal(body["proposal"])
+            error = body.get("error") if isinstance(body.get("error"), dict) else {"code": "unexpected", "message": f"HTTP {reply.status}"}
+            retryable = reply.status in (429, 500, 502, 503, 504) or (reply.status == 409 and error.get("reason") == "in_flight")
+            if not retryable or attempt >= self.max_retries:
+                raise AxivoyError(reply.status, error)
+            time.sleep(_retry_after(reply.headers) or _backoff(attempt))
+            attempt += 1
+
+    def _token(self) -> str:
+        return self.token() if callable(self.token) else self.token
+
+
+def _json(raw: bytes) -> Dict[str, Any]:
+    try:
+        decoded = json.loads(raw.decode() or "{}")
+    except ValueError:
+        return {}
+    return decoded if isinstance(decoded, dict) else {}
+
+
+def _backoff(attempt: int) -> float:
+    return min(8.0, 0.5 * 2**attempt) + random.random() / 4
+
+
+def _retry_after(headers: Mapping[str, str]) -> Optional[float]:
+    for name, value in headers.items():
+        if name.lower() == "retry-after":
+            try:
+                return min(60.0, float(value))
+            except ValueError:
+                return None
+    return None

axivoy-1.0.0/axivoy/errors.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Mapping, Optional
+
+
+class AxivoyError(Exception):
+    """A refused call: ``status`` is the HTTP status, ``code`` the stable refusal code."""
+
+    def __init__(self, status: int, body: Mapping[str, Any]) -> None:
+        super().__init__(str(body.get("message", f"HTTP {status}")))
+        self.status = status
+        self.code: str = str(body.get("code", "unexpected"))
+        self.reason: Optional[str] = body.get("reason")
+        self.fields: Dict[str, List[str]] = dict(body.get("fields") or {})
+
+
+class AxivoyProposal(Exception):
+    """A write sent for approval (HTTP 202). Check it later with ``approvals.list``."""
+
+    def __init__(self, body: Mapping[str, Any]) -> None:
+        super().__init__(str(body.get("message", "")))
+        self.id: str = str(body.get("id", ""))
+        self.approval_url: Optional[str] = body.get("approval_url")
+
+
+class AxivoyWebhookError(Exception):
+    """The ``Axivoy-Signature`` header is missing, stale or does not match."""

axivoy-1.0.0/axivoy/webhooks.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from typing import Any, Dict, List, Optional, Union
+
+from .errors import AxivoyWebhookError
+
+
+def verify_webhook(
+    raw_body: Union[bytes, str],
+    signature_header: Optional[str],
+    secret: str,
+    *,
+    tolerance_seconds: int = 300,
+    now: Optional[int] = None,
+) -> Dict[str, Any]:
+    """Checks ``Axivoy-Signature`` (``t=<unix>,v1=<hex>``: HMAC-SHA256 of
+    ``{t}.{raw body}``) and returns the parsed event.
+
+    Pass the raw body exactly as received. Raises ``AxivoyWebhookError``
+    when the header is missing, older than ``tolerance_seconds`` or does
+    not match.
+    """
+    body = raw_body.encode() if isinstance(raw_body, str) else raw_body
+    timestamp: Optional[int] = None
+    signatures: List[str] = []
+    for piece in (signature_header or "").split(","):
+        name, _, value = piece.strip().partition("=")
+        if name == "t" and value.isdigit() and timestamp is None:
+            timestamp = int(value)
+        elif name == "v1" and value:
+            signatures.append(value)
+    if timestamp is None or not signatures:
+        raise AxivoyWebhookError("Missing or malformed Axivoy-Signature header.")
+
+    current = int(time.time()) if now is None else now
+    if abs(current - timestamp) > tolerance_seconds:
+        raise AxivoyWebhookError("Signature timestamp is outside the tolerance.")
+
+    expected = hmac.new(secret.encode(), str(timestamp).encode() + b"." + body, hashlib.sha256).hexdigest()
+    if not any(hmac.compare_digest(expected, signature) for signature in signatures):
+        raise AxivoyWebhookError("Signature does not match.")
+
+    event = json.loads(body.decode())
+    if not isinstance(event, dict):
+        raise AxivoyWebhookError("Body is not an event.")
+    return event

axivoy-1.0.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "axivoy"
+dynamic = ["version"]
+description = "Typed client for the Axivoy API: operations, webhooks and errors."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+dependencies = []
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Documentation = "https://app.axivoy.ai/developers"
+
+[tool.hatch.version]
+path = "axivoy/generated.py"
+pattern = "API_VERSION = \"(?P<version>[^\"]+)\""
+
+[tool.hatch.build.targets.wheel]
+packages = ["axivoy"]
+
+[tool.hatch.build.targets.sdist]
+include = ["axivoy", "README.md"]