driftstack-sdk 0.1.0__py3-none-any.whl

driftstack/resources/sessions.py

@@ -0,0 +1,156 @@
+"""Sessions resource.
+
+Wraps every ``/v1/sessions[/...]`` route. Both sync and async variants
+share the URL/parameter shapes; the only difference is which HTTP
+client they call.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+from pydantic import BaseModel
+
+from driftstack._generated.models import (
+    CaptureRequest,
+    CaptureResponse,
+    CreateSessionRequest,
+    CreateSessionResponse,
+    InteractRequest,
+    InteractResponse,
+    NavigateRequest,
+    NavigateResponse,
+    PaginationQuery,
+    Session,
+    SessionState,
+    WaitRequest,
+    WaitResponse,
+)
+from driftstack.http import AsyncHttpClient, HttpClient
+from driftstack.resources._common import coerce_body, coerce_query
+
+
+class SessionsListPage(BaseModel):
+    """Paginated list of sessions returned by ``GET /v1/sessions``."""
+
+    data: list[Session]
+    has_more: bool
+    next_cursor: str | None
+
+
+def _session_path(session_id: str, suffix: str = "") -> str:
+    return f"/v1/sessions/{quote(session_id, safe='')}{suffix}"
+
+
+class SessionsResource:
+    """Synchronous sessions resource."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def create(
+        self, body: CreateSessionRequest | dict[str, Any] | None = None
+    ) -> CreateSessionResponse:
+        """Create a new session. Returns the new ``Session`` row."""
+        data = self._http.request("POST", "/v1/sessions", json_body=coerce_body(body) or {})
+        return CreateSessionResponse.model_validate(data)
+
+    def list(self, query: PaginationQuery | dict[str, Any] | None = None) -> SessionsListPage:
+        """List sessions for the current account, newest first."""
+        data = self._http.request("GET", "/v1/sessions", params=coerce_query(query))
+        return SessionsListPage.model_validate(data)
+
+    def get(self, session_id: str) -> Session:
+        data = self._http.request("GET", _session_path(session_id))
+        return Session.model_validate(data)
+
+    def navigate(self, session_id: str, body: NavigateRequest | dict[str, Any]) -> NavigateResponse:
+        data = self._http.request(
+            "POST", _session_path(session_id, "/navigate"), json_body=coerce_body(body)
+        )
+        return NavigateResponse.model_validate(data)
+
+    def interact(self, session_id: str, body: InteractRequest | dict[str, Any]) -> InteractResponse:
+        data = self._http.request(
+            "POST", _session_path(session_id, "/interact"), json_body=coerce_body(body)
+        )
+        return InteractResponse.model_validate(data)
+
+    def wait(self, session_id: str, body: WaitRequest | dict[str, Any]) -> WaitResponse:
+        data = self._http.request(
+            "POST", _session_path(session_id, "/wait"), json_body=coerce_body(body)
+        )
+        return WaitResponse.model_validate(data)
+
+    def get_state(self, session_id: str) -> SessionState:
+        data = self._http.request("GET", _session_path(session_id, "/state"))
+        return SessionState.model_validate(data)
+
+    def capture(self, session_id: str, body: CaptureRequest | dict[str, Any]) -> CaptureResponse:
+        data = self._http.request(
+            "POST", _session_path(session_id, "/capture"), json_body=coerce_body(body)
+        )
+        return CaptureResponse.model_validate(data)
+
+    def destroy(self, session_id: str) -> None:
+        """Destroy the session. Idempotent (safe to call twice)."""
+        self._http.request("DELETE", _session_path(session_id))
+
+
+class AsyncSessionsResource:
+    """Async sessions resource. Mirrors :class:`SessionsResource`."""
+
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def create(
+        self, body: CreateSessionRequest | dict[str, Any] | None = None
+    ) -> CreateSessionResponse:
+        data = await self._http.request("POST", "/v1/sessions", json_body=coerce_body(body) or {})
+        return CreateSessionResponse.model_validate(data)
+
+    async def list(self, query: PaginationQuery | dict[str, Any] | None = None) -> SessionsListPage:
+        data = await self._http.request("GET", "/v1/sessions", params=coerce_query(query))
+        return SessionsListPage.model_validate(data)
+
+    async def get(self, session_id: str) -> Session:
+        data = await self._http.request("GET", _session_path(session_id))
+        return Session.model_validate(data)
+
+    async def navigate(
+        self, session_id: str, body: NavigateRequest | dict[str, Any]
+    ) -> NavigateResponse:
+        data = await self._http.request(
+            "POST", _session_path(session_id, "/navigate"), json_body=coerce_body(body)
+        )
+        return NavigateResponse.model_validate(data)
+
+    async def interact(
+        self, session_id: str, body: InteractRequest | dict[str, Any]
+    ) -> InteractResponse:
+        data = await self._http.request(
+            "POST", _session_path(session_id, "/interact"), json_body=coerce_body(body)
+        )
+        return InteractResponse.model_validate(data)
+
+    async def wait(self, session_id: str, body: WaitRequest | dict[str, Any]) -> WaitResponse:
+        data = await self._http.request(
+            "POST", _session_path(session_id, "/wait"), json_body=coerce_body(body)
+        )
+        return WaitResponse.model_validate(data)
+
+    async def get_state(self, session_id: str) -> SessionState:
+        data = await self._http.request("GET", _session_path(session_id, "/state"))
+        return SessionState.model_validate(data)
+
+    async def capture(
+        self, session_id: str, body: CaptureRequest | dict[str, Any]
+    ) -> CaptureResponse:
+        data = await self._http.request(
+            "POST", _session_path(session_id, "/capture"), json_body=coerce_body(body)
+        )
+        return CaptureResponse.model_validate(data)
+
+    async def destroy(self, session_id: str) -> None:
+        await self._http.request("DELETE", _session_path(session_id))

driftstack/resources/usage.py

@@ -0,0 +1,29 @@
+"""Usage resource — /v1/usage."""
+
+from __future__ import annotations
+
+from driftstack._generated.models import UsagePeriodSummary
+from driftstack.http import AsyncHttpClient, HttpClient
+
+
+class UsageResource:
+    """Synchronous usage resource."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def current_period(self) -> UsagePeriodSummary:
+        """Current calendar-month UTC totals + tier quotas."""
+        data = self._http.request("GET", "/v1/usage")
+        return UsagePeriodSummary.model_validate(data)
+
+
+class AsyncUsageResource:
+    """Async usage resource."""
+
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def current_period(self) -> UsagePeriodSummary:
+        data = await self._http.request("GET", "/v1/usage")
+        return UsagePeriodSummary.model_validate(data)

driftstack/resources/webhooks.py

@@ -0,0 +1,110 @@
+"""Webhooks resource — /v1/webhooks."""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+from pydantic import BaseModel
+
+from driftstack._generated.models import (
+    CreateWebhookRequest,
+    CreateWebhookResponse,
+    ListDeliveriesQuery,
+    WebhookDelivery,
+    WebhookEndpoint,
+)
+from driftstack.http import AsyncHttpClient, HttpClient
+from driftstack.resources._common import coerce_body, coerce_query
+
+
+class WebhookEndpointList(BaseModel):
+    """Response shape for ``GET /v1/webhooks``."""
+
+    data: list[WebhookEndpoint]
+
+
+class WebhookDeliveryListPage(BaseModel):
+    """Response shape for ``GET /v1/webhooks/{id}/deliveries``."""
+
+    data: list[WebhookDelivery]
+    has_more: bool
+    next_cursor: str | None
+
+
+def _webhook_path(webhook_id: str, suffix: str = "") -> str:
+    return f"/v1/webhooks/{quote(webhook_id, safe='')}{suffix}"
+
+
+class WebhooksResource:
+    """Synchronous webhooks resource."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def create(self, body: CreateWebhookRequest | dict[str, Any]) -> CreateWebhookResponse:
+        """Create a webhook subscription.
+
+        Plaintext signing secret is returned ONCE; store it now — it
+        cannot be retrieved later. Requires the ``admin`` scope.
+        """
+        data = self._http.request("POST", "/v1/webhooks", json_body=coerce_body(body))
+        return CreateWebhookResponse.model_validate(data)
+
+    def list(self) -> WebhookEndpointList:
+        data = self._http.request("GET", "/v1/webhooks")
+        return WebhookEndpointList.model_validate(data)
+
+    def get(self, webhook_id: str) -> WebhookEndpoint:
+        data = self._http.request("GET", _webhook_path(webhook_id))
+        return WebhookEndpoint.model_validate(data)
+
+    def delete(self, webhook_id: str) -> None:
+        """Soft-delete (disable) the endpoint. Idempotent."""
+        self._http.request("DELETE", _webhook_path(webhook_id))
+
+    def list_deliveries(
+        self,
+        webhook_id: str,
+        query: ListDeliveriesQuery | dict[str, Any] | None = None,
+    ) -> WebhookDeliveryListPage:
+        data = self._http.request(
+            "GET",
+            _webhook_path(webhook_id, "/deliveries"),
+            params=coerce_query(query),
+        )
+        return WebhookDeliveryListPage.model_validate(data)
+
+
+class AsyncWebhooksResource:
+    """Async webhooks resource."""
+
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def create(self, body: CreateWebhookRequest | dict[str, Any]) -> CreateWebhookResponse:
+        data = await self._http.request("POST", "/v1/webhooks", json_body=coerce_body(body))
+        return CreateWebhookResponse.model_validate(data)
+
+    async def list(self) -> WebhookEndpointList:
+        data = await self._http.request("GET", "/v1/webhooks")
+        return WebhookEndpointList.model_validate(data)
+
+    async def get(self, webhook_id: str) -> WebhookEndpoint:
+        data = await self._http.request("GET", _webhook_path(webhook_id))
+        return WebhookEndpoint.model_validate(data)
+
+    async def delete(self, webhook_id: str) -> None:
+        await self._http.request("DELETE", _webhook_path(webhook_id))
+
+    async def list_deliveries(
+        self,
+        webhook_id: str,
+        query: ListDeliveriesQuery | dict[str, Any] | None = None,
+    ) -> WebhookDeliveryListPage:
+        data = await self._http.request(
+            "GET",
+            _webhook_path(webhook_id, "/deliveries"),
+            params=coerce_query(query),
+        )
+        return WebhookDeliveryListPage.model_validate(data)

driftstack/retry.py

@@ -0,0 +1,105 @@
+"""Exponential-backoff retry policy with full jitter.
+
+Mirrors `packages/sdk-typescript/src/retry.ts`. Honours `Retry-After`
+when the server set one (the SDK's HTTP layer maps it onto the
+RateLimitError before retry decides). Idempotent or read-shaped
+methods are retried; mutating methods that lack server-side idempotency
+keys are NOT retried by default — callers can opt in via the
+``retry`` argument on the HTTP client.
+"""
+
+from __future__ import annotations
+
+import random
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import TypeVar
+
+from driftstack.errors import (
+    DriftstackError,
+    RateLimitError,
+    TransportError,
+)
+
+T = TypeVar("T")
+
+
+@dataclass
+class RetryConfig:
+    """Tuning knobs for the retry loop. Defaults match the TypeScript SDK."""
+
+    max_retries: int = 3
+    initial_delay_ms: int = 200
+    max_delay_ms: int = 10_000
+    backoff_multiplier: float = 2.0
+    """If True, retry on TransportError + RateLimitError. If False, never retry."""
+    enabled: bool = True
+    """Errors that ARE retryable when retries are enabled."""
+    retryable_errors: tuple[type[BaseException], ...] = field(
+        default_factory=lambda: (TransportError, RateLimitError)
+    )
+
+
+def _backoff_delay_ms(attempt: int, cfg: RetryConfig, retry_after_seconds: int | None) -> int:
+    """Compute the next sleep with full jitter; cap at ``max_delay_ms``.
+
+    If the server set a ``Retry-After`` (rate-limit case), it wins —
+    we never retry sooner than the server asks. Otherwise it's
+    exponential-backoff with full jitter (random uniform between 0
+    and the next exponential value).
+    """
+    if retry_after_seconds is not None:
+        return min(retry_after_seconds * 1000, cfg.max_delay_ms)
+    capped = min(cfg.initial_delay_ms * (cfg.backoff_multiplier**attempt), cfg.max_delay_ms)
+    return int(random.uniform(0, capped))
+
+
+def with_retry(fn: Callable[[], T], cfg: RetryConfig | None = None) -> T:
+    """Run ``fn`` with retries per ``cfg``. Synchronous variant."""
+    config = cfg or RetryConfig()
+    if not config.enabled:
+        return fn()
+
+    attempt = 0
+    while True:
+        try:
+            return fn()
+        except config.retryable_errors as err:
+            if attempt >= config.max_retries:
+                raise
+            retry_after = err.retry_after_seconds if isinstance(err, RateLimitError) else None
+            time.sleep(_backoff_delay_ms(attempt, config, retry_after) / 1000)
+            attempt += 1
+        except DriftstackError:
+            # Non-retryable typed error — propagate immediately.
+            raise
+
+
+async def with_retry_async(
+    fn: Callable[[], _Awaitable[T]],
+    cfg: RetryConfig | None = None,
+) -> T:
+    """Run an async ``fn`` with retries. Mirrors :func:`with_retry`."""
+    import asyncio
+
+    config = cfg or RetryConfig()
+    if not config.enabled:
+        return await fn()
+
+    attempt = 0
+    while True:
+        try:
+            return await fn()
+        except config.retryable_errors as err:
+            if attempt >= config.max_retries:
+                raise
+            retry_after = err.retry_after_seconds if isinstance(err, RateLimitError) else None
+            await asyncio.sleep(_backoff_delay_ms(attempt, config, retry_after) / 1000)
+            attempt += 1
+        except DriftstackError:
+            raise
+
+
+# Forward-declare for the async type hint above.
+from collections.abc import Awaitable as _Awaitable  # noqa: E402

driftstack/webhook_signature.py

@@ -0,0 +1,106 @@
+"""Webhook signature verification helper.
+
+Header format (Stripe-style): ``t=<unix-seconds>,v1=<hex hmac>``.
+HMAC = HMAC-SHA256(``<unix-seconds>.<raw body>``, ``<secret>``).
+
+Mirrors :func:`verifyWebhookSignature` from the TypeScript SDK so a
+multi-language receiver fleet works against the same wire format.
+
+Example::
+
+    from driftstack import verify_webhook_signature
+
+    @app.post("/driftstack-webhook")
+    def receive():
+        sig = request.headers["x-driftstack-signature"]
+        ok = verify_webhook_signature(
+            body=request.body,                      # bytes or str
+            header=sig,
+            secret=os.environ["DRIFTSTACK_WEBHOOK_SECRET"],
+        )
+        if not ok:
+            return Response(status=401)
+        # ... process event ...
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import time
+from dataclasses import dataclass
+
+DEFAULT_TOLERANCE_SEC = 300
+
+
+@dataclass
+class _ParsedSignature:
+    timestamp_seconds: int
+    signature_hex: str
+
+
+def _parse_signature_header(header: str) -> _ParsedSignature | None:
+    """Parse ``t=...,v1=...`` (order-independent). Return None on shape failure."""
+    timestamp: int | None = None
+    signature: str | None = None
+    for part in header.split(","):
+        eq_idx = part.find("=")
+        if eq_idx < 0:
+            continue
+        key = part[:eq_idx].strip()
+        value = part[eq_idx + 1 :].strip()
+        if key == "t":
+            try:
+                timestamp = int(value)
+            except ValueError:
+                continue
+        elif key == "v1":
+            signature = value
+    if timestamp is None or signature is None:
+        return None
+    return _ParsedSignature(timestamp_seconds=timestamp, signature_hex=signature)
+
+
+def verify_webhook_signature(
+    *,
+    body: bytes | str,
+    header: str | None,
+    secret: str,
+    tolerance_sec: int = DEFAULT_TOLERANCE_SEC,
+    now_seconds: float | None = None,
+) -> bool:
+    """Verify an inbound webhook signature header.
+
+    Returns ``True`` iff the header is well-formed, the timestamp is
+    within ``tolerance_sec`` of now, and the HMAC matches in
+    constant time. Returns ``False`` on any failure mode — never
+    raises.
+
+    ``body`` must be the EXACT raw bytes the server signed. If your
+    framework re-encodes JSON before passing it to your handler,
+    you'll need to use a raw-body access path (Flask:
+    ``request.get_data()``; FastAPI: ``await request.body()``;
+    Django: ``request.body``).
+    """
+    if not header or not isinstance(header, str):
+        return False
+
+    parsed = _parse_signature_header(header)
+    if parsed is None:
+        return False
+
+    now = now_seconds if now_seconds is not None else time.time()
+    if abs(now - parsed.timestamp_seconds) > tolerance_sec:
+        return False
+
+    body_bytes = body.encode("utf-8") if isinstance(body, str) else bytes(body)
+    payload = f"{parsed.timestamp_seconds}.".encode() + body_bytes
+
+    expected = hmac.new(
+        secret.encode("utf-8"),
+        payload,
+        hashlib.sha256,
+    ).hexdigest()
+
+    # ``compare_digest`` is constant-time on equal-length strings.
+    return hmac.compare_digest(expected, parsed.signature_hex)