sendrelay 1.7.0__py3-none-any.whl

sendrelay/__init__.py

@@ -0,0 +1,24 @@
+"""Official Relay server SDK for Python.
+
+Quote and create deliveries, read them back with the rider's live ETA, manage webhooks and mint
+tracking tokens for your apps. Use ``Relay`` in regular code and ``AsyncRelay`` with asyncio.
+"""
+
+from ._client import AsyncRelay, Relay
+from ._errors import ApiError, NetworkError, RelayError, ValidationError
+from ._http import RetryConfig
+from ._version import __version__
+from ._webhooks import WebhookSignatureVerification, verify_webhook_signature
+
+__all__ = [
+    "ApiError",
+    "AsyncRelay",
+    "NetworkError",
+    "Relay",
+    "RelayError",
+    "RetryConfig",
+    "ValidationError",
+    "WebhookSignatureVerification",
+    "__version__",
+    "verify_webhook_signature",
+]

sendrelay/_client.py

@@ -0,0 +1,333 @@
+from __future__ import annotations
+
+from typing import Any, AsyncIterator, Dict, Iterator, Mapping, Optional, cast
+
+import httpx
+
+from . import _operations as ops
+from ._errors import ValidationError
+from ._http import DEFAULT_API_VERSION, DEFAULT_BASE_URL, Config, Request, RetryConfig, send, send_async
+from ._webhooks import WebhookSignatureVerification, verify_webhook_signature
+from .types import (
+    CancelTaskResponse,
+    CreateTaskResponse,
+    CreateWebhookResponse,
+    GetTaskResponse,
+    ListTasksResponse,
+    ListWebhooksResponse,
+    PresenceResponse,
+    TaskListItem,
+    TaskQuoteResponse,
+    Webhook,
+    WebSocketToken,
+)
+
+Body = Mapping[str, Any]
+
+
+def _config(
+    api_key: str,
+    base_url: Optional[str],
+    api_version: Optional[str],
+    timeout: float,
+    max_retries: Optional[int],
+    retry: Optional[RetryConfig],
+    auto_idempotency: bool,
+    headers: Optional[Dict[str, str]],
+) -> Config:
+    if not api_key:
+        raise ValidationError("API key is required", "api_key")
+    if not (api_key.startswith("sk_live_") or api_key.startswith("sk_test_")):
+        raise ValidationError("Invalid API key format. Must start with sk_live_ or sk_test_", "api_key")
+    retry = retry or RetryConfig()
+    if max_retries is not None:
+        retry.max_retries = max_retries
+    return Config(
+        api_key=api_key,
+        base_url=base_url or DEFAULT_BASE_URL,
+        api_version=api_version or DEFAULT_API_VERSION,
+        timeout=timeout,
+        retry=retry,
+        auto_idempotency=auto_idempotency,
+        headers=dict(headers or {}),
+    )
+
+
+class _Base:
+    _config: Config
+
+    @property
+    def environment(self) -> str:
+        """``"live"`` for a live key, ``"test"`` for a test key."""
+        return "live" if self._config.api_key.startswith("sk_live_") else "test"
+
+
+# ─── Sync ────────────────────────────────────────────────────────────────────
+
+
+class Tasks:
+    def __init__(self, run: Any) -> None:
+        self._run = run
+
+    def quote(self, body: Body) -> TaskQuoteResponse:
+        """Price a delivery without creating it. Pass the ``quoteId`` to ``create`` to lock the price."""
+        return cast(TaskQuoteResponse, self._run(ops.tasks_quote(body)))
+
+    def create(self, body: Body, *, idempotency_key: Optional[str] = None) -> CreateTaskResponse:
+        """Create a delivery. Pass your own ``idempotency_key`` (for example your order ID) so retries
+        never create a second delivery; otherwise one is generated per call."""
+        return cast(CreateTaskResponse, self._run(ops.tasks_create(body, idempotency_key)))
+
+    def list(self, **query: Any) -> ListTasksResponse:
+        """One page of tasks, newest first by default. Filters: ``limit``, ``order``, ``cursor``."""
+        return cast(ListTasksResponse, self._run(ops.tasks_list(query)))
+
+    def list_all(self, **query: Any) -> Iterator[TaskListItem]:
+        """Every task, following the cursor page by page."""
+        cursor: Optional[str] = None
+        while True:
+            page = self.list(**{**query, **({"cursor": cursor} if cursor else {})})
+            yield from page["data"]
+            cursor = page.get("cursor") if page.get("hasMore") else None
+            if not cursor:
+                return
+
+    def get(self, task_id: str) -> GetTaskResponse:
+        """A task, with your ``rating`` of it and the rider's ``liveEta`` while they are on the way."""
+        return cast(GetTaskResponse, self._run(ops.tasks_get(task_id)))
+
+    def cancel(self, task_id: str, body: Optional[Body] = None) -> CancelTaskResponse:
+        return cast(CancelTaskResponse, self._run(ops.tasks_cancel(task_id, body)))
+
+    def assign(self, task_id: str, body: Body) -> Dict[str, Any]:
+        """Offer a manual (``autoAssign: false``) live task to riders from ``available_riders``."""
+        return cast(Dict[str, Any], self._run(ops.tasks_assign(task_id, body)))
+
+    def available_riders(self, task_id: str, **query: Any) -> Dict[str, Any]:
+        return cast(Dict[str, Any], self._run(ops.tasks_available_riders(task_id, query)))
+
+    def rate(self, task_id: str, body: Body) -> Dict[str, Any]:
+        """Rate the rider of a completed task, once. Check ``get(...)["rating"]`` first."""
+        return cast(Dict[str, Any], self._run(ops.tasks_rate(task_id, body)))
+
+    def dispute(self, task_id: str, body: Body) -> Dict[str, Any]:
+        return cast(Dict[str, Any], self._run(ops.tasks_dispute(task_id, body)))
+
+
+class Webhooks:
+    def __init__(self, run: Any) -> None:
+        self._run = run
+
+    def create(self, body: Body) -> CreateWebhookResponse:
+        """Register an endpoint. Store the returned ``secret``: it is shown only once."""
+        return cast(CreateWebhookResponse, self._run(ops.webhooks_create(body)))
+
+    def list(self) -> ListWebhooksResponse:
+        return cast(ListWebhooksResponse, self._run(ops.webhooks_list()))
+
+    def get(self, webhook_id: str) -> Webhook:
+        return cast(Webhook, self._run(ops.webhooks_get(webhook_id)))
+
+    def update(self, webhook_id: str, body: Body) -> Webhook:
+        return cast(Webhook, self._run(ops.webhooks_update(webhook_id, body)))
+
+    def delete(self, webhook_id: str) -> Webhook:
+        return cast(Webhook, self._run(ops.webhooks_delete(webhook_id)))
+
+    @staticmethod
+    def verify_signature(
+        payload: str | bytes, signature_header: str, secret: str, tolerance: int = 300
+    ) -> WebhookSignatureVerification:
+        """Check a delivery's ``X-Relay-Signature`` header against the raw body."""
+        return verify_webhook_signature(payload, signature_header, secret, tolerance)
+
+
+class Auth:
+    def __init__(self, run: Any) -> None:
+        self._run = run
+
+    def create_websocket_token(self, body: Body) -> WebSocketToken:
+        """A short-lived token for an app to track tasks live. ``scope``: ``["task:<id>", ...]``."""
+        return cast(WebSocketToken, self._run(ops.auth_create_websocket_token(body)))
+
+
+class Presence:
+    def __init__(self, run: Any) -> None:
+        self._run = run
+
+    def get(self, **query: Any) -> PresenceResponse:
+        """Anonymous rider availability around a point: ``latitude``, ``longitude``, ``resolution``."""
+        return cast(PresenceResponse, self._run(ops.presence_get(query)))
+
+
+class Relay(_Base):
+    """The Relay server SDK. Keep your API key on your server.
+
+    Example::
+
+        from sendrelay import Relay
+
+        relay = Relay(api_key=os.environ["RELAY_API_KEY"])
+        quote = relay.tasks.quote({"taskType": "PACKAGE_DELIVERY", "stages": [...]})
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: Optional[str] = None,
+        api_version: Optional[str] = None,
+        timeout: float = 30.0,
+        max_retries: Optional[int] = None,
+        retry: Optional[RetryConfig] = None,
+        auto_idempotency: bool = True,
+        headers: Optional[Dict[str, str]] = None,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        self._config = _config(api_key, base_url, api_version, timeout, max_retries, retry, auto_idempotency, headers)
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.Client(timeout=timeout)
+        self.tasks = Tasks(self._request)
+        self.webhooks = Webhooks(self._request)
+        self.auth = Auth(self._request)
+        self.presence = Presence(self._request)
+
+    def _request(self, request: Request) -> Any:
+        return send(self._config, self._http, request)
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._http.close()
+
+    def __enter__(self) -> Relay:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+
+# ─── Async ───────────────────────────────────────────────────────────────────
+
+
+class AsyncTasks:
+    def __init__(self, run: Any) -> None:
+        self._run = run
+
+    async def quote(self, body: Body) -> TaskQuoteResponse:
+        return cast(TaskQuoteResponse, await self._run(ops.tasks_quote(body)))
+
+    async def create(self, body: Body, *, idempotency_key: Optional[str] = None) -> CreateTaskResponse:
+        return cast(CreateTaskResponse, await self._run(ops.tasks_create(body, idempotency_key)))
+
+    async def list(self, **query: Any) -> ListTasksResponse:
+        return cast(ListTasksResponse, await self._run(ops.tasks_list(query)))
+
+    async def list_all(self, **query: Any) -> AsyncIterator[TaskListItem]:
+        cursor: Optional[str] = None
+        while True:
+            page = await self.list(**{**query, **({"cursor": cursor} if cursor else {})})
+            for item in page["data"]:
+                yield item
+            cursor = page.get("cursor") if page.get("hasMore") else None
+            if not cursor:
+                return
+
+    async def get(self, task_id: str) -> GetTaskResponse:
+        return cast(GetTaskResponse, await self._run(ops.tasks_get(task_id)))
+
+    async def cancel(self, task_id: str, body: Optional[Body] = None) -> CancelTaskResponse:
+        return cast(CancelTaskResponse, await self._run(ops.tasks_cancel(task_id, body)))
+
+    async def assign(self, task_id: str, body: Body) -> Dict[str, Any]:
+        return cast(Dict[str, Any], await self._run(ops.tasks_assign(task_id, body)))
+
+    async def available_riders(self, task_id: str, **query: Any) -> Dict[str, Any]:
+        return cast(Dict[str, Any], await self._run(ops.tasks_available_riders(task_id, query)))
+
+    async def rate(self, task_id: str, body: Body) -> Dict[str, Any]:
+        return cast(Dict[str, Any], await self._run(ops.tasks_rate(task_id, body)))
+
+    async def dispute(self, task_id: str, body: Body) -> Dict[str, Any]:
+        return cast(Dict[str, Any], await self._run(ops.tasks_dispute(task_id, body)))
+
+
+class AsyncWebhooks:
+    def __init__(self, run: Any) -> None:
+        self._run = run
+
+    async def create(self, body: Body) -> CreateWebhookResponse:
+        return cast(CreateWebhookResponse, await self._run(ops.webhooks_create(body)))
+
+    async def list(self) -> ListWebhooksResponse:
+        return cast(ListWebhooksResponse, await self._run(ops.webhooks_list()))
+
+    async def get(self, webhook_id: str) -> Webhook:
+        return cast(Webhook, await self._run(ops.webhooks_get(webhook_id)))
+
+    async def update(self, webhook_id: str, body: Body) -> Webhook:
+        return cast(Webhook, await self._run(ops.webhooks_update(webhook_id, body)))
+
+    async def delete(self, webhook_id: str) -> Webhook:
+        return cast(Webhook, await self._run(ops.webhooks_delete(webhook_id)))
+
+    verify_signature = staticmethod(Webhooks.verify_signature)
+
+
+class AsyncAuth:
+    def __init__(self, run: Any) -> None:
+        self._run = run
+
+    async def create_websocket_token(self, body: Body) -> WebSocketToken:
+        return cast(WebSocketToken, await self._run(ops.auth_create_websocket_token(body)))
+
+
+class AsyncPresence:
+    def __init__(self, run: Any) -> None:
+        self._run = run
+
+    async def get(self, **query: Any) -> PresenceResponse:
+        return cast(PresenceResponse, await self._run(ops.presence_get(query)))
+
+
+class AsyncRelay(_Base):
+    """The Relay server SDK for asyncio. Same methods as ``Relay``, awaited.
+
+    Example::
+
+        async with AsyncRelay(api_key=os.environ["RELAY_API_KEY"]) as relay:
+            task = await relay.tasks.get(task_id)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: Optional[str] = None,
+        api_version: Optional[str] = None,
+        timeout: float = 30.0,
+        max_retries: Optional[int] = None,
+        retry: Optional[RetryConfig] = None,
+        auto_idempotency: bool = True,
+        headers: Optional[Dict[str, str]] = None,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        self._config = _config(api_key, base_url, api_version, timeout, max_retries, retry, auto_idempotency, headers)
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.AsyncClient(timeout=timeout)
+        self.tasks = AsyncTasks(self._request)
+        self.webhooks = AsyncWebhooks(self._request)
+        self.auth = AsyncAuth(self._request)
+        self.presence = AsyncPresence(self._request)
+
+    async def _request(self, request: Request) -> Any:
+        return await send_async(self._config, self._http, request)
+
+    async def close(self) -> None:
+        if self._owns_client:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncRelay:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.close()

sendrelay/_errors.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class RelayError(Exception):
+    """Base class for every error this SDK raises."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.message = message
+
+
+class ApiError(RelayError):
+    """The API answered with an error status.
+
+    ``code`` is the API's error code (for example ``NOT_FOUND`` or ``CONFLICT``) and ``details``
+    carries anything extra the API sent, such as validation problems.
+    """
+
+    def __init__(self, status_code: int, code: str, message: str, details: Any = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code
+        self.details = details
+
+    def __repr__(self) -> str:
+        return f"ApiError(status_code={self.status_code}, code={self.code!r}, message={self.message!r})"
+
+
+class NetworkError(RelayError):
+    """The request never got an answer: the connection failed or timed out."""
+
+    def __init__(self, message: str, cause: Optional[BaseException] = None) -> None:
+        super().__init__(message)
+        self.__cause__ = cause
+
+
+class ValidationError(RelayError):
+    """The SDK rejected the input before sending anything."""
+
+    def __init__(self, message: str, field: Optional[str] = None) -> None:
+        super().__init__(message)
+        self.field = field

sendrelay/_http.py

@@ -0,0 +1,153 @@
+"""HTTP plumbing shared by the sync and async clients: request building, retries and error mapping."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import random
+import secrets
+import time
+from dataclasses import dataclass, field
+from typing import Any, Dict, Mapping, Optional, Tuple
+
+import httpx
+
+from ._errors import ApiError, NetworkError
+from ._version import __version__
+
+DEFAULT_BASE_URL = "https://api.sendrelay.com.ng"
+DEFAULT_API_VERSION = "v1"
+RETRYABLE_STATUS_CODES: Tuple[int, ...] = (408, 429, 500, 502, 503, 504)
+# Test-mode quota 429s last minutes to hours; retrying can't succeed, so surface them at once.
+NON_RETRYABLE_ERROR_CODES = frozenset({"TEST_QUOTA_EXCEEDED", "TEST_CONCURRENCY_EXCEEDED"})
+
+
+@dataclass
+class RetryConfig:
+    """How failed requests are retried. Delays are in seconds."""
+
+    enabled: bool = True
+    max_retries: int = 3
+    initial_delay: float = 0.5
+    max_delay: float = 10.0
+    backoff_multiplier: float = 2.0
+    retryable_status_codes: Tuple[int, ...] = RETRYABLE_STATUS_CODES
+
+    def delay(self, attempt: int) -> float:
+        base = min(self.initial_delay * self.backoff_multiplier**attempt, self.max_delay)
+        # ±25% jitter so many clients don't retry in lockstep.
+        return max(0.0, base + base * 0.25 * (random.random() * 2 - 1))
+
+
+@dataclass
+class Request:
+    method: str
+    path: str
+    body: Any = None
+    query: Optional[Mapping[str, Any]] = None
+    headers: Dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class Config:
+    api_key: str
+    base_url: str = DEFAULT_BASE_URL
+    api_version: str = DEFAULT_API_VERSION
+    timeout: float = 30.0
+    retry: RetryConfig = field(default_factory=RetryConfig)
+    auto_idempotency: bool = True
+    headers: Dict[str, str] = field(default_factory=dict)
+
+
+def _query_value(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)
+
+
+def build(config: Config, request: Request) -> httpx.Request:
+    url = f"{config.base_url.rstrip('/')}/{config.api_version}{request.path}"
+    params = {k: _query_value(v) for k, v in (request.query or {}).items() if v is not None}
+    headers = {
+        "Content-Type": "application/json",
+        "X-Relay-Key": config.api_key,
+        "User-Agent": f"sendrelay-python/{__version__}",
+        **config.headers,
+        **request.headers,
+    }
+    if request.method == "POST" and config.auto_idempotency and "Idempotency-Key" not in headers:
+        headers["Idempotency-Key"] = f"sdk-{int(time.time() * 1000)}-{secrets.token_hex(16)}"
+    content = json.dumps(request.body).encode() if request.body is not None else None
+    return httpx.Request(request.method, url, params=params, headers=headers, content=content)
+
+
+def api_error(response: httpx.Response) -> ApiError:
+    try:
+        body = response.json()
+    except ValueError:
+        body = {}
+    error = body.get("error") if isinstance(body, dict) else None
+    error = error if isinstance(error, dict) else {}
+    return ApiError(
+        response.status_code,
+        error.get("code") or "UNKNOWN_ERROR",
+        error.get("message") or response.reason_phrase or "Request failed",
+        error.get("details"),
+    )
+
+
+def retryable(config: Config, error: ApiError, attempt: int) -> bool:
+    return (
+        config.retry.enabled
+        and attempt < config.retry.max_retries
+        and error.code not in NON_RETRYABLE_ERROR_CODES
+        and error.status_code in config.retry.retryable_status_codes
+    )
+
+
+def network_error(config: Config, cause: httpx.TransportError) -> NetworkError:
+    if isinstance(cause, httpx.TimeoutException):
+        return NetworkError(f"Request timeout after {config.timeout}s", cause)
+    return NetworkError("Network error - connection failed", cause)
+
+
+def send(config: Config, client: httpx.Client, request: Request) -> Any:
+    attempt = 0
+    while True:
+        try:
+            response = client.send(build(config, request))
+        except httpx.TransportError as exc:
+            if config.retry.enabled and attempt < config.retry.max_retries:
+                time.sleep(config.retry.delay(attempt))
+                attempt += 1
+                continue
+            raise network_error(config, exc) from exc
+        if response.is_success:
+            return response.json()
+        error = api_error(response)
+        if retryable(config, error, attempt):
+            time.sleep(config.retry.delay(attempt))
+            attempt += 1
+            continue
+        raise error
+
+
+async def send_async(config: Config, client: httpx.AsyncClient, request: Request) -> Any:
+    attempt = 0
+    while True:
+        try:
+            response = await client.send(build(config, request))
+        except httpx.TransportError as exc:
+            if config.retry.enabled and attempt < config.retry.max_retries:
+                await asyncio.sleep(config.retry.delay(attempt))
+                attempt += 1
+                continue
+            raise network_error(config, exc) from exc
+        if response.is_success:
+            return response.json()
+        error = api_error(response)
+        if retryable(config, error, attempt):
+            await asyncio.sleep(config.retry.delay(attempt))
+            attempt += 1
+            continue
+        raise error

sendrelay/_operations.py

@@ -0,0 +1,101 @@
+"""Every API operation, defined once as a request. Sync and async resources both use these."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional
+from urllib.parse import quote
+
+from ._errors import ValidationError
+from ._http import Request
+
+
+def _id(value: str, name: str) -> str:
+    if not value:
+        raise ValidationError(f"{name} is required", name)
+    return quote(value, safe="")
+
+
+def tasks_quote(body: Mapping[str, Any]) -> Request:
+    return Request("POST", "/sdk/tasks/quote", body=dict(body))
+
+
+def tasks_create(body: Mapping[str, Any], idempotency_key: Optional[str]) -> Request:
+    headers = {"Idempotency-Key": idempotency_key} if idempotency_key else {}
+    return Request("POST", "/sdk/tasks", body=dict(body), headers=headers)
+
+
+def tasks_list(query: Optional[Mapping[str, Any]]) -> Request:
+    return Request("GET", "/sdk/tasks", query=query)
+
+
+def tasks_get(task_id: str) -> Request:
+    return Request("GET", f"/sdk/tasks/{_id(task_id, 'task_id')}")
+
+
+def tasks_cancel(task_id: str, body: Optional[Mapping[str, Any]]) -> Request:
+    return Request("DELETE", f"/sdk/tasks/{_id(task_id, 'task_id')}/cancel", body=dict(body) if body else None)
+
+
+def tasks_assign(task_id: str, body: Mapping[str, Any]) -> Request:
+    return Request("POST", f"/sdk/tasks/{_id(task_id, 'task_id')}/assign", body=dict(body))
+
+
+def tasks_available_riders(task_id: str, query: Optional[Mapping[str, Any]]) -> Request:
+    return Request("GET", f"/sdk/tasks/{_id(task_id, 'task_id')}/available-riders", query=query)
+
+
+def tasks_rate(task_id: str, body: Mapping[str, Any]) -> Request:
+    return Request("POST", f"/sdk/tasks/{_id(task_id, 'task_id')}/ratings", body=dict(body))
+
+
+def tasks_dispute(task_id: str, body: Mapping[str, Any]) -> Request:
+    return Request("POST", f"/sdk/tasks/{_id(task_id, 'task_id')}/dispute", body=dict(body))
+
+
+def webhooks_create(body: Mapping[str, Any]) -> Request:
+    return Request("POST", "/sdk/webhooks", body=dict(body))
+
+
+def webhooks_list() -> Request:
+    return Request("GET", "/sdk/webhooks")
+
+
+def webhooks_get(webhook_id: str) -> Request:
+    return Request("GET", f"/sdk/webhooks/{_id(webhook_id, 'webhook_id')}")
+
+
+def webhooks_update(webhook_id: str, body: Mapping[str, Any]) -> Request:
+    return Request("PUT", f"/sdk/webhooks/{_id(webhook_id, 'webhook_id')}", body=dict(body))
+
+
+def webhooks_delete(webhook_id: str) -> Request:
+    return Request("DELETE", f"/sdk/webhooks/{_id(webhook_id, 'webhook_id')}")
+
+
+def auth_create_websocket_token(body: Mapping[str, Any]) -> Request:
+    scope = list(body.get("scope") or [])
+    if not scope:
+        raise ValidationError("scope must contain at least one resource", "scope")
+    for resource in scope:
+        parts = str(resource).split(":")
+        if len(parts) != 2:
+            raise ValidationError(
+                f'Invalid scope format: "{resource}". Expected "type:id" (e.g., "task:abc123")', "scope"
+            )
+        kind, ident = parts
+        if not kind or not ident:
+            raise ValidationError(f'Invalid scope format: "{resource}". Both type and id must be non-empty', "scope")
+        if kind == "task" and len(ident.split(",")) > 5:
+            raise ValidationError(f'Scoped tasks cannot exceed 5 per scope entry: "{resource}"', "scope")
+    expires_in = body.get("expiresIn")
+    if expires_in is not None and not 60 <= expires_in <= 7200:
+        raise ValidationError("expiresIn must be between 60 and 7200 seconds", "expiresIn")
+    return Request(
+        "POST",
+        "/auth/websocket-token",
+        body={"scope": scope, "expiresIn": expires_in if expires_in is not None else 1800},
+    )
+
+
+def presence_get(query: Mapping[str, Any]) -> Request:
+    return Request("GET", "/sdk/presence", query=query)

sendrelay/_version.py

@@ -0,0 +1,2 @@
+#: The published package version. Kept in sync with pyproject.toml by scripts/check-sdk-versions.mjs.
+__version__ = "1.7.0"

sendrelay/_webhooks.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import base64
+import binascii
+import hashlib
+import hmac
+import time
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class WebhookSignatureVerification:
+    valid: bool
+    error: Optional[str] = None
+
+    def __bool__(self) -> bool:
+        return self.valid
+
+
+def verify_webhook_signature(
+    payload: str | bytes,
+    signature_header: str,
+    secret: str,
+    tolerance: int = 300,
+) -> WebhookSignatureVerification:
+    """Check that a webhook came from Relay and wasn't changed on the way.
+
+    Pass the raw request body (exactly as received), the ``X-Relay-Signature`` header and the
+    ``whsec_...`` secret you got when you created the webhook. ``tolerance`` is how old, in seconds,
+    a delivery may be.
+    """
+    try:
+        parts = signature_header.split(",")
+        timestamp_part = next((p for p in parts if p.startswith("t=")), None)
+        signature_part = next((p for p in parts if p.startswith("v1=")), None)
+        if timestamp_part is None or signature_part is None:
+            return WebhookSignatureVerification(False, "Invalid signature format")
+
+        timestamp = int(timestamp_part.split("=", 1)[1])
+        signature = signature_part.split("=", 1)[1]
+        if abs(int(time.time()) - timestamp) > tolerance:
+            return WebhookSignatureVerification(False, "Timestamp outside tolerance window")
+
+        # The key is everything after `whsec_` (mode prefix included), base64url-decoded.
+        key_text = secret.replace("whsec_", "", 1)
+        key = base64.urlsafe_b64decode(key_text + "=" * (-len(key_text) % 4))
+        body = payload if isinstance(payload, str) else payload.decode("utf-8")
+        expected = hmac.new(key, f"{timestamp}.{body}".encode(), hashlib.sha256).hexdigest()
+        if not hmac.compare_digest(signature.encode(), expected.encode()):
+            return WebhookSignatureVerification(False, "Signature verification failed")
+        return WebhookSignatureVerification(True)
+    except (ValueError, binascii.Error, UnicodeDecodeError) as exc:
+        return WebhookSignatureVerification(False, str(exc))

sendrelay/types.py

@@ -0,0 +1,203 @@
+"""Request and response shapes. Responses are plain dicts with the API's camelCase keys; these
+TypedDicts describe them for editors and type checkers."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Literal, Optional
+
+from typing_extensions import NotRequired, TypedDict
+
+TaskType = Literal["PASSENGER_RIDE", "FOOD_DELIVERY", "PACKAGE_DELIVERY", "BULK_DELIVERY", "ERRAND"]
+TaskStatus = Literal[
+    "PENDING", "OFFERED", "ASSIGNED", "IN_PROGRESS", "COMPLETED", "CANCELLED", "FAILED", "PAYMENT_FAILED"
+]
+Priority = Literal["STANDARD", "URGENT"]
+StageType = Literal["PICKUP", "DROPOFF"]
+Weight = Literal["LIGHT", "STANDARD", "HEAVY", "FREIGHT"]
+Size = Literal["ENVELOPE", "BOX", "LARGE_BOX", "FREIGHT"]
+VehicleType = Literal["BICYCLE", "BIKE", "MOTORCYCLE", "TRICYCLE", "CAR", "VAN", "TRUCK"]
+WebhookMode = Literal["test", "live"]
+PresenceResolution = Literal["BLOCK", "NEIGHBOURHOOD", "DISTRICT"]
+
+
+class Location(TypedDict):
+    latitude: float
+    longitude: float
+    address: str
+
+
+class Item(TypedDict):
+    name: str
+    estimatedValue: int
+    estimatedWeight: Weight
+    estimatedSize: Size
+    description: NotRequired[str]
+    specialInstructions: NotRequired[str]
+
+
+class Passenger(TypedDict):
+    name: str
+    contactInfo: NotRequired[str]
+    specialNeeds: NotRequired[str]
+    luggageCount: NotRequired[int]
+
+
+class Stage(TypedDict):
+    type: StageType
+    location: Location
+    instructions: NotRequired[str]
+    items: NotRequired[List[Item]]
+    passengers: NotRequired[List[Passenger]]
+    status: NotRequired[str]
+    completedAt: NotRequired[Optional[str]]
+
+
+class Preferences(TypedDict, total=False):
+    minRating: float
+    hasBox: bool
+    hasRefrigeration: bool
+    hasAirConditioning: bool
+    vehicleType: List[VehicleType]
+    allowedOrganisations: List[str]
+    blockedOrganisations: List[str]
+    allowIndependentRiders: bool
+
+
+class TaskQuoteRequest(TypedDict):
+    taskType: TaskType
+    stages: List[Stage]
+    priority: NotRequired[Priority]
+    preferences: NotRequired[Preferences]
+
+
+class CreateTaskRequest(TaskQuoteRequest):
+    autoAssign: NotRequired[bool]
+    paymentMethod: NotRequired[Literal["WALLET", "CARD"]]
+    notes: NotRequired[str]
+    externalId: NotRequired[str]
+    quoteId: NotRequired[str]
+    completionCode: NotRequired[Dict[str, Any]]
+    simulationOutcome: NotRequired[str]
+
+
+class TaskLiveEta(TypedDict):
+    """How far the rider is from the stop they are heading to, from their navigation route."""
+
+    stageIndex: int
+    seconds: int
+    meters: int
+    arrivesAt: str
+    updatedAt: str
+
+
+class TaskRating(TypedDict):
+    rating: int
+    comment: Optional[str]
+    createdAt: str
+
+
+class Task(TypedDict):
+    id: str
+    developerId: str
+    riderId: Optional[str]
+    externalId: Optional[str]
+    status: TaskStatus
+    taskType: TaskType
+    priority: Priority
+    autoAssign: bool
+    currentStageIndex: Optional[int]
+    stages: List[Stage]
+    deliveryFee: int
+    totalFee: int
+    paymentMethod: str
+    paymentStatus: Optional[str]
+    createdAt: str
+    updatedAt: str
+    completionCodeRequired: bool
+    completionCodeLength: Optional[int]
+    rider: NotRequired[Dict[str, Any]]
+    completionCode: NotRequired[Optional[Dict[str, Any]]]
+
+
+class GetTaskResponse(TypedDict):
+    task: Task
+    rating: Optional[TaskRating]
+    liveEta: Optional[TaskLiveEta]
+
+
+class TaskListItem(TypedDict):
+    id: str
+    status: TaskStatus
+    taskType: TaskType
+    totalFee: int
+    createdAt: str
+
+
+class ListTasksResponse(TypedDict):
+    data: List[TaskListItem]
+    hasMore: bool
+    cursor: Optional[str]
+
+
+class CreateTaskResponse(TypedDict):
+    message: str
+    task: Task
+    pricing: Dict[str, Any]
+    idempotency: Dict[str, Any]
+
+
+class TaskQuoteResponse(TypedDict):
+    total: int
+    subtotal: int
+    tax: int
+    platformFee: int
+    quoteId: str
+    expiresAt: str
+    quoteTtlSeconds: int
+
+
+class CancelTaskResponse(TypedDict):
+    message: str
+    taskId: str
+    status: Literal["CANCELLED"]
+
+
+class Webhook(TypedDict):
+    id: str
+    url: str
+    mode: WebhookMode
+    events: List[str]
+    createdAt: str
+    usage: Dict[str, Any]
+    description: NotRequired[str]
+
+
+class CreateWebhookResponse(TypedDict):
+    id: str
+    url: str
+    mode: WebhookMode
+    events: List[str]
+    secret: str
+
+
+class ListWebhooksResponse(TypedDict):
+    data: List[Webhook]
+    hasMore: bool
+    cursor: Optional[str]
+
+
+class WebSocketToken(TypedDict):
+    token: str
+    expiresIn: int
+    expiresAt: str
+    scope: List[str]
+
+
+class PresenceResponse(TypedDict):
+    mode: WebhookMode
+    simulated: bool
+    resolution: PresenceResolution
+    cells: List[Dict[str, Any]]
+    totals: Dict[str, Any]
+    generatedAt: str
+    refreshAfterSeconds: int

sendrelay-1.7.0.dist-info/METADATA

@@ -0,0 +1,112 @@
+Metadata-Version: 2.5
+Name: sendrelay
+Version: 1.7.0
+Summary: Official Relay server SDK for Python: quotes, deliveries, webhooks and tracking tokens
+Project-URL: Homepage, https://sendrelay.com.ng
+Project-URL: Documentation, https://docs.sendrelay.com.ng/sdks/python-sdk
+Project-URL: Source, https://github.com/SendRelay/relay-sdk-python
+Author: SendRelay
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,delivery,dispatch,logistics,relay,sdk
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.25
+Requires-Dist: typing-extensions>=4.7
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Relay Python SDK
+
+The official server SDK for [Relay](https://sendrelay.com.ng), the delivery API. Quote and create deliveries, read them back with the rider's live ETA, manage webhooks, and mint tracking tokens for your apps.
+
+```bash
+pip install sendrelay
+```
+
+Python 3.9 or newer. Use `Relay` in regular code and `AsyncRelay` with asyncio. Both have the same methods.
+
+## Quick start
+
+```python
+import os
+from sendrelay import Relay
+
+relay = Relay(api_key=os.environ["RELAY_API_KEY"])  # sk_test_... or sk_live_..., server only
+
+stages = [
+    {
+        "type": "PICKUP",
+        "location": {"latitude": 6.5244, "longitude": 3.3792, "address": "12 Marina Road, Lagos"},
+        "items": [{"name": "Phone case", "estimatedValue": 500000, "estimatedWeight": "LIGHT", "estimatedSize": "BOX"}],
+    },
+    {"type": "DROPOFF", "location": {"latitude": 6.4474, "longitude": 3.4723, "address": "22 Admiralty Way, Lekki"}},
+]
+
+quote = relay.tasks.quote({"taskType": "PACKAGE_DELIVERY", "stages": stages})
+print(quote["total"])  # kobo
+
+created = relay.tasks.create(
+    {"taskType": "PACKAGE_DELIVERY", "stages": stages, "quoteId": quote["quoteId"]},
+    idempotency_key="order-1042",  # retries with the same key never create a second delivery
+)
+
+read = relay.tasks.get(created["task"]["id"])
+if read["liveEta"]:
+    print(f"Arriving at stop {read['liveEta']['stageIndex'] + 1} at {read['liveEta']['arrivesAt']}")
+```
+
+Responses are plain dicts with the API's field names (`liveEta`, `totalFee`, ...). `sendrelay.types` has TypedDicts for them.
+
+## Asyncio
+
+```python
+from sendrelay import AsyncRelay
+
+async with AsyncRelay(api_key=os.environ["RELAY_API_KEY"]) as relay:
+    async for task in relay.tasks.list_all(limit=50):
+        print(task["id"], task["status"])
+```
+
+## Webhooks
+
+```python
+from sendrelay import verify_webhook_signature
+
+result = verify_webhook_signature(raw_body, request.headers["X-Relay-Signature"], os.environ["RELAY_WEBHOOK_SECRET"])
+if not result.valid:
+    return 400
+```
+
+Pass the raw request body exactly as received, not re-serialized JSON.
+
+## Errors and retries
+
+- `ApiError` has `status_code`, `code` and `details` from the API.
+- `NetworkError` means the request never got an answer.
+- `ValidationError` means the SDK rejected the input before sending.
+
+Timeouts, 408, 429 and 5xx responses are retried up to 3 times with exponential backoff. Test-mode quota errors are not retried. Change this with `max_retries=` or `retry=RetryConfig(...)`.
+
+## Tracking in your app
+
+Mint a short-lived token on your server and hand it to your app:
+
+```python
+token = relay.auth.create_websocket_token({"scope": [f"task:{task_id}"]})["token"]
+```
+
+Your app then tracks the task live with one of the UI SDKs.
+
+[Full documentation](https://docs.sendrelay.com.ng/sdks/python-sdk)

sendrelay-1.7.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+sendrelay/__init__.py,sha256=S4zu9CoQxrZdYuEMa1OmHW_Q3ho6cgb9Bj8-ZJSF6Vo,721
+sendrelay/_client.py,sha256=UZnhzdfPQPzu_I46JNslPs290RlwGbGFR92IH_uAKrk,12856
+sendrelay/_errors.py,sha256=qB4QicE84LEwi5jNXBqmywZ1hkMuA7sJcm8mE3nlaII,1381
+sendrelay/_http.py,sha256=ItWgECH8CiOEi10YGwMxmIoywZexKizCbIgZXj3x_qg,5300
+sendrelay/_operations.py,sha256=OJLf2EpKehQ0C_e63m8rng4gvkF9FzbRSiBnScV3Gwo,3777
+sendrelay/_version.py,sha256=MUtFtY_uMM8ayUww-tcJpB-VoFH1XLxZ-mXE73QznxE,124
+sendrelay/_webhooks.py,sha256=ZaURo8EcbdcWHosHM4G9lCVuuY6HblJrUs1I1T37Zsk,2151
+sendrelay/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sendrelay/types.py,sha256=c-jr4V1znX2QEadx3Ak0joZzCEo9dD1qo0E_4HWA7Fo,4749
+sendrelay-1.7.0.dist-info/METADATA,sha256=rCIV8lv7CZMI23D68zqSUF4XU0bONUyVtrB7SinYTTw,3927
+sendrelay-1.7.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+sendrelay-1.7.0.dist-info/licenses/LICENSE,sha256=1iFLFtAqcG9V0jaJGO6BN1Yc0M9qeyJPpj36q27V0Hw,1071
+sendrelay-1.7.0.dist-info/RECORD,,

sendrelay-1.7.0.dist-info/WHEEL

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

sendrelay-1.7.0.dist-info/licenses/LICENSE

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