driftstack-sdk 0.1.0__py3-none-any.whl

driftstack/errors.py

@@ -0,0 +1,194 @@
+"""Error class hierarchy for the Driftstack Python SDK.
+
+Mirrors the server's RFC 7807 problem-types (apps/server/src/lib/errors.ts).
+The HTTP layer maps `application/problem+json` responses to the right
+subclass; non-HTTP failures (timeouts, parse errors, network) raise
+``TransportError``.
+
+Callers can catch with the granularity they need::
+
+    try:
+        client.sessions.create()
+    except RateLimitError as e:
+        time.sleep(e.retry_after_seconds or 1)
+    except DriftstackError as e:
+        # any other typed problem
+        log.error("driftstack call failed: %s", e)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class DriftstackError(Exception):
+    """Base for every error raised by the Driftstack SDK.
+
+    All HTTP-derived errors carry the parsed problem document so callers
+    can read additional fields (``e.problem.get("retry_after_seconds")``,
+    ``e.problem.get("current_sessions")``, etc.) without knowing the
+    specific subclass shape.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int | None = None,
+        problem_type: str | None = None,
+        problem: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.problem_type = problem_type
+        self.problem: dict[str, Any] = problem or {}
+
+    def __repr__(self) -> str:  # pragma: no cover - cosmetic
+        return f"{type(self).__name__}({self.message!r}, status={self.status})"
+
+
+# ── Auth (401, 403) ───────────────────────────────────────────────────────
+
+
+class AuthError(DriftstackError):
+    """Base for authentication / authorisation failures."""
+
+
+class InvalidKeyError(AuthError):
+    """The provided API key was not recognised (malformed or unknown)."""
+
+
+class ExpiredKeyError(AuthError):
+    """The API key passed its ``expires_at`` deadline."""
+
+
+class RevokedKeyError(AuthError):
+    """The API key was revoked (DELETE /v1/api-keys/:id)."""
+
+
+class ForbiddenError(AuthError):
+    """The caller is authenticated but lacks the required scope."""
+
+
+# ── Validation / domain (400, 404, 409, 410) ──────────────────────────────
+
+
+class ValidationError(DriftstackError):
+    """Request body or query parameters failed schema validation."""
+
+
+class NotFoundError(DriftstackError):
+    """The targeted resource doesn't exist."""
+
+
+class ConflictError(DriftstackError):
+    """The request would violate an invariant (duplicate, capacity, etc.)."""
+
+
+class SessionNotFoundError(NotFoundError):
+    """Specifically: the addressed session id has no row in our store."""
+
+
+class SessionDestroyedError(DriftstackError):
+    """The session was destroyed; further operations on it are rejected (410)."""
+
+
+# ── Rate / quota (429) ────────────────────────────────────────────────────
+
+
+class RateLimitError(DriftstackError):
+    """Token-bucket rate limit hit. ``retry_after_seconds`` is the hint."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        retry_after_seconds: int | None = None,
+        status: int | None = 429,
+        problem_type: str | None = None,
+        problem: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message, status=status, problem_type=problem_type, problem=problem)
+        self.retry_after_seconds = retry_after_seconds
+
+
+class QuotaExceededError(DriftstackError):
+    """Per-period usage quota exhausted."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        current: int | None = None,
+        limit: int | None = None,
+        record_type: str | None = None,
+        status: int | None = 429,
+        problem_type: str | None = None,
+        problem: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message, status=status, problem_type=problem_type, problem=problem)
+        self.current = current
+        self.limit = limit
+        self.record_type = record_type
+
+
+class ConcurrencyLimitError(DriftstackError):
+    """Active-session count would exceed the tier's concurrent limit."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        current_sessions: int | None = None,
+        limit: int | None = None,
+        status: int | None = 429,
+        problem_type: str | None = None,
+        problem: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message, status=status, problem_type=problem_type, problem=problem)
+        self.current_sessions = current_sessions
+        self.limit = limit
+
+
+# ── Driver / upstream (502) ───────────────────────────────────────────────
+
+
+class DriverError(DriftstackError):
+    """The driver returned an unrecoverable error during the operation."""
+
+
+# ── Transport (network, timeout, parse) ───────────────────────────────────
+
+
+class TransportError(DriftstackError):
+    """A network-level or response-parsing failure that didn't reach the server.
+
+    Distinguished from server-returned errors so retry logic can decide
+    whether the request was idempotent enough to retry without surprises.
+    """
+
+
+# ── Mapping problem-type URI → subclass ──────────────────────────────────
+
+# Keep the mapping in one place for ease of audit + extension. The HTTP
+# layer in `driftstack.http` consults this; the keys match the server
+# constants in apps/server/src/lib/problem-types.ts.
+
+PROBLEM_TYPE_TO_ERROR: dict[str, type[DriftstackError]] = {
+    "https://errors.driftstack.dev/bad-request": ValidationError,
+    "https://errors.driftstack.dev/unauthorized": AuthError,
+    "https://errors.driftstack.dev/forbidden": ForbiddenError,
+    "https://errors.driftstack.dev/not-found": NotFoundError,
+    "https://errors.driftstack.dev/conflict": ConflictError,
+    "https://errors.driftstack.dev/rate-limited": RateLimitError,
+    "https://errors.driftstack.dev/concurrency-limit": ConcurrencyLimitError,
+    "https://errors.driftstack.dev/tier-limit": QuotaExceededError,
+    "https://errors.driftstack.dev/revoked-key": RevokedKeyError,
+    "https://errors.driftstack.dev/expired-key": ExpiredKeyError,
+    "https://errors.driftstack.dev/invalid-key": InvalidKeyError,
+    "https://errors.driftstack.dev/session-destroyed": SessionDestroyedError,
+    "https://errors.driftstack.dev/driver-error": DriverError,
+    "https://errors.driftstack.dev/driver-not-integrated": DriverError,
+    "https://errors.driftstack.dev/validation-failed": ValidationError,
+}

driftstack/http.py

@@ -0,0 +1,291 @@
+"""HTTP client wrapper.
+
+Customers don't construct this directly — they get a :class:`Driftstack`
+or :class:`AsyncDriftstack`, which wraps an :class:`HttpClient`
+internally. The wrapper handles:
+
+* Bearer auth header injection
+* RFC 7807 problem-json → typed error mapping (``error_from_response``)
+* Per-request timeout
+* Retry policy delegation (see :mod:`driftstack.retry`)
+
+Both sync and async variants share the same problem-mapping logic in
+:func:`_error_from_response_data`, so a future shape change to the
+server's error envelope updates both paths in one place.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import httpx
+
+from driftstack._version import __version__
+from driftstack.errors import (
+    PROBLEM_TYPE_TO_ERROR,
+    ConcurrencyLimitError,
+    DriftstackError,
+    QuotaExceededError,
+    RateLimitError,
+    TransportError,
+)
+from driftstack.retry import RetryConfig, with_retry, with_retry_async
+
+DEFAULT_TIMEOUT_S = 30.0
+USER_AGENT = f"driftstack-sdk-python/{__version__}"
+
+
+def _build_headers(api_key: str, has_body: bool) -> dict[str, str]:
+    headers = {
+        "authorization": f"Bearer {api_key}",
+        "user-agent": USER_AGENT,
+        "accept": "application/json",
+    }
+    if has_body:
+        headers["content-type"] = "application/json"
+    return headers
+
+
+def _problem_from_text(text: str, status: int) -> dict[str, Any] | None:
+    """Parse a response body as RFC 7807 problem+json. Return None on parse fail."""
+    if not text:
+        return None
+    try:
+        parsed = json.loads(text)
+    except (json.JSONDecodeError, ValueError):
+        return None
+    if not isinstance(parsed, dict):
+        return None
+    if "type" not in parsed or "title" not in parsed or "status" not in parsed:
+        return None
+    return parsed
+
+
+def _error_from_response_data(
+    status: int,
+    text: str,
+    retry_after_header: str | None,
+) -> DriftstackError:
+    """Map a non-2xx response to the right :class:`DriftstackError` subclass.
+
+    Falls back to :class:`TransportError` when the body isn't a proper
+    problem document — that surfaces as a server contract violation,
+    which is the right diagnostic for "we got a 500 with HTML in it."
+    """
+    problem = _problem_from_text(text, status)
+    if problem is None:
+        return TransportError(
+            f"non-2xx response ({status}) with non-problem body",
+            status=status,
+        )
+
+    problem_type = str(problem.get("type", ""))
+    title = str(problem.get("title", ""))
+    detail = str(problem.get("detail") or title)
+
+    # Retry-After can come from either the header or from a problem field.
+    retry_after_seconds: int | None = None
+    if retry_after_header is not None:
+        try:
+            retry_after_seconds = int(retry_after_header)
+        except ValueError:
+            retry_after_seconds = None
+    if retry_after_seconds is None and "retry_after_seconds" in problem:
+        try:
+            retry_after_seconds = int(problem["retry_after_seconds"])
+        except (TypeError, ValueError):
+            retry_after_seconds = None
+
+    error_cls = PROBLEM_TYPE_TO_ERROR.get(problem_type, DriftstackError)
+
+    if error_cls is RateLimitError:
+        return RateLimitError(
+            detail,
+            retry_after_seconds=retry_after_seconds,
+            status=status,
+            problem_type=problem_type,
+            problem=problem,
+        )
+    if error_cls is QuotaExceededError:
+        return QuotaExceededError(
+            detail,
+            current=_int_or_none(problem.get("current")),
+            limit=_int_or_none(problem.get("limit")),
+            record_type=str(problem["record_type"]) if problem.get("record_type") else None,
+            status=status,
+            problem_type=problem_type,
+            problem=problem,
+        )
+    if error_cls is ConcurrencyLimitError:
+        return ConcurrencyLimitError(
+            detail,
+            current_sessions=_int_or_none(problem.get("current_sessions")),
+            limit=_int_or_none(problem.get("limit")),
+            status=status,
+            problem_type=problem_type,
+            problem=problem,
+        )
+    return error_cls(detail, status=status, problem_type=problem_type, problem=problem)
+
+
+def _int_or_none(value: Any) -> int | None:
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# Sync HTTP client (httpx.Client)
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class HttpClient:
+    """Thin wrapper around ``httpx.Client`` for the sync :class:`Driftstack`."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str,
+        timeout_s: float = DEFAULT_TIMEOUT_S,
+        retry: RetryConfig | None = None,
+        client: httpx.Client | None = None,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._retry = retry
+        self._client = client or httpx.Client(timeout=timeout_s)
+        self._owns_client = client is None
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> HttpClient:
+        return self
+
+    def __exit__(self, *_excinfo: Any) -> None:
+        self.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json_body: Any | None = None,
+        retry: RetryConfig | None = None,
+    ) -> Any:
+        url = self._base_url + path
+        headers = _build_headers(self._api_key, has_body=json_body is not None)
+
+        def _do() -> Any:
+            try:
+                response = self._client.request(
+                    method,
+                    url,
+                    params=params,
+                    json=json_body,
+                    headers=headers,
+                )
+            except httpx.TimeoutException as err:
+                raise TransportError("request timed out", status=0) from err
+            except httpx.HTTPError as err:
+                raise TransportError(str(err), status=0) from err
+
+            return _decode_or_raise(response)
+
+        return with_retry(_do, retry or self._retry)
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# Async HTTP client (httpx.AsyncClient)
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class AsyncHttpClient:
+    """Async analogue of :class:`HttpClient`."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str,
+        timeout_s: float = DEFAULT_TIMEOUT_S,
+        retry: RetryConfig | None = None,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._retry = retry
+        self._client = client or httpx.AsyncClient(timeout=timeout_s)
+        self._owns_client = client is None
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncHttpClient:
+        return self
+
+    async def __aexit__(self, *_excinfo: Any) -> None:
+        await self.aclose()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json_body: Any | None = None,
+        retry: RetryConfig | None = None,
+    ) -> Any:
+        url = self._base_url + path
+        headers = _build_headers(self._api_key, has_body=json_body is not None)
+
+        async def _do() -> Any:
+            try:
+                response = await self._client.request(
+                    method,
+                    url,
+                    params=params,
+                    json=json_body,
+                    headers=headers,
+                )
+            except httpx.TimeoutException as err:
+                raise TransportError("request timed out", status=0) from err
+            except httpx.HTTPError as err:
+                raise TransportError(str(err), status=0) from err
+
+            return _decode_or_raise(response)
+
+        return await with_retry_async(_do, retry or self._retry)
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# Shared response handling
+# ──────────────────────────────────────────────────────────────────────────
+
+
+def _decode_or_raise(response: httpx.Response) -> Any:
+    """2xx → parsed JSON (or None on 204). Anything else → raise typed error."""
+    if 200 <= response.status_code < 300:
+        if response.status_code == 204 or not response.content:
+            return None
+        try:
+            return response.json()
+        except (json.JSONDecodeError, ValueError) as err:
+            raise TransportError(
+                "failed to parse JSON response body",
+                status=response.status_code,
+            ) from err
+
+    raise _error_from_response_data(
+        status=response.status_code,
+        text=response.text,
+        retry_after_header=response.headers.get("retry-after"),
+    )

driftstack/resources/__init__.py

@@ -0,0 +1,29 @@
+"""Resource accessors mounted on the top-level Driftstack clients.
+
+Each module exposes two classes — a sync resource and an async one —
+that share the same method signatures but back onto :class:`HttpClient`
+or :class:`AsyncHttpClient` respectively.
+
+Customers don't import these directly; they reach them through the
+client::
+
+    client = Driftstack(api_key="…")
+    client.sessions.create()       # sync
+    await async_client.sessions.create()   # async (separate client)
+"""
+
+from driftstack.resources.api_keys import ApiKeysResource, AsyncApiKeysResource
+from driftstack.resources.sessions import AsyncSessionsResource, SessionsResource
+from driftstack.resources.usage import AsyncUsageResource, UsageResource
+from driftstack.resources.webhooks import AsyncWebhooksResource, WebhooksResource
+
+__all__ = [
+    "ApiKeysResource",
+    "AsyncApiKeysResource",
+    "SessionsResource",
+    "AsyncSessionsResource",
+    "UsageResource",
+    "AsyncUsageResource",
+    "WebhooksResource",
+    "AsyncWebhooksResource",
+]

driftstack/resources/_common.py

@@ -0,0 +1,38 @@
+"""Shared helpers for the resource layer.
+
+Customers can pass either a Pydantic model OR a dict to mutating
+methods. Both serialise to the same JSON shape on the wire — the
+helper here normalises before hand-off to httpx.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel
+
+
+def coerce_body(body: BaseModel | dict[str, Any] | None) -> dict[str, Any] | None:
+    """Convert a Pydantic model or dict to the dict that httpx will JSON-encode.
+
+    ``None`` round-trips as ``None`` so a route with no body works
+    without callers having to pass an empty dict.
+
+    Pydantic models go through ``model_dump(mode="json", exclude_none=True)``
+    so optional unset fields don't pollute the wire payload (e.g.
+    ``CreateSessionRequest()`` shouldn't emit ``{"label": null}``).
+    """
+    if body is None:
+        return None
+    if isinstance(body, BaseModel):
+        return body.model_dump(mode="json", exclude_none=True)
+    return body
+
+
+def coerce_query(query: BaseModel | dict[str, Any] | None) -> dict[str, Any] | None:
+    """Same as :func:`coerce_body` but for query-string params."""
+    if query is None:
+        return None
+    if isinstance(query, BaseModel):
+        return query.model_dump(mode="json", exclude_none=True)
+    return {k: v for k, v in query.items() if v is not None}

driftstack/resources/api_keys.py

@@ -0,0 +1,61 @@
+"""API keys resource — /v1/api-keys."""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+from pydantic import BaseModel
+
+from driftstack._generated.models import ApiKey, CreateApiKeyRequest, CreateApiKeyResponse
+from driftstack.http import AsyncHttpClient, HttpClient
+from driftstack.resources._common import coerce_body
+
+
+class ApiKeyList(BaseModel):
+    """Response shape for ``GET /v1/api-keys``."""
+
+    data: list[ApiKey]
+
+
+class ApiKeysResource:
+    """Synchronous API keys resource."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def create(self, body: CreateApiKeyRequest | dict[str, Any]) -> CreateApiKeyResponse:
+        """Create an API key.
+
+        Plaintext is in the response — store it now, it cannot be
+        retrieved later. Requires the ``admin`` scope on the calling key.
+        """
+        data = self._http.request("POST", "/v1/api-keys", json_body=coerce_body(body))
+        return CreateApiKeyResponse.model_validate(data)
+
+    def list(self) -> ApiKeyList:
+        """List API keys for the current account. Plaintext never included."""
+        data = self._http.request("GET", "/v1/api-keys")
+        return ApiKeyList.model_validate(data)
+
+    def revoke(self, key_id: str) -> None:
+        """Revoke an API key. Idempotent — revoking an already-revoked key is a no-op."""
+        self._http.request("DELETE", f"/v1/api-keys/{quote(key_id, safe='')}")
+
+
+class AsyncApiKeysResource:
+    """Async API keys resource."""
+
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def create(self, body: CreateApiKeyRequest | dict[str, Any]) -> CreateApiKeyResponse:
+        data = await self._http.request("POST", "/v1/api-keys", json_body=coerce_body(body))
+        return CreateApiKeyResponse.model_validate(data)
+
+    async def list(self) -> ApiKeyList:
+        data = await self._http.request("GET", "/v1/api-keys")
+        return ApiKeyList.model_validate(data)
+
+    async def revoke(self, key_id: str) -> None:
+        await self._http.request("DELETE", f"/v1/api-keys/{quote(key_id, safe='')}")