driftstack-sdk 0.1.0__py3-none-any.whl

driftstack/__init__.py

@@ -0,0 +1,60 @@
+"""Driftstack Python SDK.
+
+Customer-facing entry points re-exported here so callers can write::
+
+    from driftstack import Driftstack, AsyncDriftstack, DriftstackError
+
+Resource accessors live on the client instance::
+
+    client = Driftstack(api_key="ds_live_...")
+    session = client.sessions.create()
+    client.sessions.navigate(session.id, url="https://example.com")
+    client.sessions.destroy(session.id)
+"""
+
+from __future__ import annotations
+
+from driftstack._version import __version__
+from driftstack.client import AsyncDriftstack, Driftstack
+from driftstack.errors import (
+    AuthError,
+    ConcurrencyLimitError,
+    ConflictError,
+    DriftstackError,
+    DriverError,
+    ExpiredKeyError,
+    ForbiddenError,
+    InvalidKeyError,
+    NotFoundError,
+    QuotaExceededError,
+    RateLimitError,
+    RevokedKeyError,
+    SessionDestroyedError,
+    SessionNotFoundError,
+    TransportError,
+    ValidationError,
+)
+from driftstack.webhook_signature import verify_webhook_signature
+
+__all__ = [
+    "__version__",
+    "Driftstack",
+    "AsyncDriftstack",
+    "DriftstackError",
+    "AuthError",
+    "ForbiddenError",
+    "InvalidKeyError",
+    "ExpiredKeyError",
+    "RevokedKeyError",
+    "ConflictError",
+    "NotFoundError",
+    "RateLimitError",
+    "QuotaExceededError",
+    "ConcurrencyLimitError",
+    "SessionNotFoundError",
+    "SessionDestroyedError",
+    "DriverError",
+    "ValidationError",
+    "TransportError",
+    "verify_webhook_signature",
+]

driftstack/_generated/__init__.py

@@ -0,0 +1,6 @@
+"""Codegen output. Regenerated by ``scripts/generate.sh``.
+
+Hand-edit nothing in this package — it gets clobbered every regeneration.
+Customer-facing types are re-exported from :mod:`driftstack` (the package
+root); to add a wrapping layer, edit there.
+"""

driftstack/_generated/models.py

@@ -0,0 +1,494 @@
+# generated by datamodel-codegen:
+#   filename:  openapi.json
+#   timestamp: 2026-05-02T16:11:24+00:00
+
+from __future__ import annotations
+
+from typing import Any, Literal
+from uuid import UUID
+
+from pydantic import AnyUrl, AwareDatetime, BaseModel, EmailStr, Field, conint, constr
+
+
+class Account(BaseModel):
+    id: constr(
+        pattern=r"^acc_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+    )
+    email: EmailStr
+    name: str | None
+    tier: Literal["free", "starter", "solo", "builder", "scale", "enterprise"]
+    status: Literal["active", "suspended", "deleted"]
+    created_at: AwareDatetime
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """
+    updated_at: AwareDatetime
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """
+
+
+class ApiKey(BaseModel):
+    id: constr(
+        pattern=r"^key_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+    )
+    name: str
+    key_prefix: str
+    scopes: list[Literal["read", "write", "admin"]]
+    last_used_at: AwareDatetime | None
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """
+    revoked_at: AwareDatetime | None
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """
+    expires_at: AwareDatetime | None
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """
+    created_at: AwareDatetime
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """
+
+
+class Session(BaseModel):
+    id: constr(
+        pattern=r"^ses_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+    )
+    account_id: constr(
+        pattern=r"^acc_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+    )
+    api_key_id: constr(
+        pattern=r"^key_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+    )
+    status: Literal["creating", "ready", "busy", "destroyed", "errored"]
+    archetype: constr(pattern=r"^[a-z0-9_]+$", min_length=3, max_length=60)
+    label: str | None
+    metadata: dict[str, Any] | None
+    created_at: AwareDatetime
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """
+    updated_at: AwareDatetime
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """
+    last_state_at: AwareDatetime | None
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """
+    destroyed_at: AwareDatetime | None
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """
+
+
+class SessionState(BaseModel):
+    url: AnyUrl | None
+    title: str | None
+    cookies: list[dict[str, Any]]
+    local_storage: dict[str, str]
+    captured_at: AwareDatetime
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """
+
+
+class Problem(BaseModel):
+    """
+    RFC 7807 problem details
+    """
+
+    type: AnyUrl
+    """
+    Stable URI identifying the problem class. Clients switch on this.
+    """
+    title: str
+    status: conint(ge=100, le=599)
+    detail: str | None = None
+    instance: str | None = None
+
+
+class Totals(BaseModel):
+    session_minute: conint(ge=0) | None = None
+    navigate: conint(ge=0) | None = None
+    interact: conint(ge=0) | None = None
+    wait: conint(ge=0) | None = None
+    state_capture: conint(ge=0) | None = None
+    screenshot_capture: conint(ge=0) | None = None
+
+
+class Quotas(BaseModel):
+    session_minute: conint(ge=0) | None = None
+    navigate: conint(ge=0) | None = None
+    interact: conint(ge=0) | None = None
+    wait: conint(ge=0) | None = None
+    state_capture: conint(ge=0) | None = None
+    screenshot_capture: conint(ge=0) | None = None
+
+
+class UsagePeriodSummary(BaseModel):
+    period_start: AwareDatetime
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """
+    period_end: AwareDatetime
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """
+    tier: Literal["free", "starter", "solo", "builder", "scale", "enterprise"]
+    totals: Totals
+    quotas: Quotas
+
+
+class PaginationQuery(BaseModel):
+    limit: conint(ge=1, le=100) | None = 50
+    cursor: str | None = None
+
+
+class CreateSessionRequest(BaseModel):
+    archetype: constr(pattern=r"^[a-z0-9_]+$", min_length=3, max_length=60) | None = (
+        None
+    )
+    label: constr(max_length=120) | None = None
+    metadata: dict[str, Any] | None = None
+
+
+class CreateSessionResponse(BaseModel):
+    id: constr(
+        pattern=r"^ses_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+    )
+    account_id: constr(
+        pattern=r"^acc_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+    )
+    api_key_id: constr(
+        pattern=r"^key_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+    )
+    status: Literal["creating", "ready", "busy", "destroyed", "errored"]
+    archetype: constr(pattern=r"^[a-z0-9_]+$", min_length=3, max_length=60)
+    label: str | None
+    metadata: dict[str, Any] | None
+    created_at: AwareDatetime
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """
+    updated_at: AwareDatetime
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """
+    last_state_at: AwareDatetime | None
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """
+    destroyed_at: AwareDatetime | None
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """
+
+
+class NavigateRequest(BaseModel):
+    url: AnyUrl
+    timeout_ms: conint(ge=1000, le=120000) | None = None
+    wait_until: Literal["load", "domcontentloaded", "networkidle"] | None = "load"
+
+
+class NavigateResponse(BaseModel):
+    url: AnyUrl
+    status: conint(ge=100, le=599)
+    final_url: AnyUrl
+    duration_ms: conint(ge=0)
+
+
+class Offset(BaseModel):
+    x: int
+    y: int
+
+
+class Action(BaseModel):
+    kind: Literal["tap"]
+    selector: constr(min_length=1)
+    offset: Offset | None = None
+
+
+class Action1(BaseModel):
+    kind: Literal["type"]
+    selector: constr(min_length=1)
+    text: constr(max_length=10000)
+    delay_ms: conint(ge=0, le=500) | None = None
+
+
+class Action2(BaseModel):
+    kind: Literal["scroll"]
+    selector: constr(min_length=1) | None = None
+    delta_x: int | None = 0
+    delta_y: int | None = 0
+
+
+class Action3(BaseModel):
+    kind: Literal["press"]
+    key: constr(min_length=1, max_length=20)
+
+
+class InteractRequest(BaseModel):
+    action: Action | Action1 | Action2 | Action3
+    timeout_ms: conint(ge=100, le=60000) | None = None
+
+
+class InteractResponse(BaseModel):
+    ok: Literal[True]
+    duration_ms: conint(ge=0)
+
+
+class Condition(BaseModel):
+    kind: Literal["selector"]
+    selector: constr(min_length=1)
+
+
+class Condition1(BaseModel):
+    kind: Literal["selector_hidden"]
+    selector: constr(min_length=1)
+
+
+class Condition2(BaseModel):
+    kind: Literal["url_matches"]
+    pattern: constr(min_length=1)
+
+
+class Condition3(BaseModel):
+    kind: Literal["time"]
+    ms: conint(ge=0, le=60000)
+
+
+class WaitRequest(BaseModel):
+    condition: Condition | Condition1 | Condition2 | Condition3
+    timeout_ms: conint(ge=100, le=120000) | None = None
+
+
+class WaitResponse(BaseModel):
+    satisfied: bool
+    duration_ms: conint(ge=0)
+
+
+class CaptureRequest(BaseModel):
+    kind: Literal["screenshot", "dom_snapshot", "pdf"]
+    full_page: bool | None = False
+
+
+class CaptureResponse(BaseModel):
+    kind: Literal["screenshot", "dom_snapshot", "pdf"]
+    data: str
+    encoding: Literal["base64", "utf8"]
+    byte_size: conint(ge=0)
+    duration_ms: conint(ge=0)
+
+
+class CreateApiKeyRequest(BaseModel):
+    name: constr(min_length=1, max_length=120)
+    scopes: list[Literal["read", "write", "admin"]] = Field(..., min_length=1)
+    expires_at: AwareDatetime | None = None
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """
+
+
+class CreateApiKeyResponse(BaseModel):
+    id: constr(
+        pattern=r"^key_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+    )
+    name: str
+    key_prefix: str
+    scopes: list[Literal["read", "write", "admin"]]
+    last_used_at: AwareDatetime | None
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """
+    revoked_at: AwareDatetime | None
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """
+    expires_at: AwareDatetime | None
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """
+    created_at: AwareDatetime
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """
+    plaintext: str
+    """
+    The plaintext key. Shown once at creation; not retrievable later.
+    """
+
+
+class WebhookEndpoint(BaseModel):
+    id: constr(
+        pattern=r"^whk_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+    )
+    url: AnyUrl
+    secret_prefix: str
+    events: list[
+        Literal[
+            "session.completed",
+            "session.failed",
+            "quota.warning_80pct",
+            "quota.exceeded",
+            "api_key.revoked",
+        ]
+    ]
+    description: str | None
+    active: bool
+    consecutive_failures: conint(ge=0)
+    last_success_at: AwareDatetime | None
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """
+    last_failure_at: AwareDatetime | None
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """
+    disabled_at: AwareDatetime | None
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """
+    created_at: AwareDatetime
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """
+
+
+class CreateWebhookRequest(BaseModel):
+    url: AnyUrl
+    events: list[
+        Literal[
+            "session.completed",
+            "session.failed",
+            "quota.warning_80pct",
+            "quota.exceeded",
+            "api_key.revoked",
+        ]
+    ] = Field(..., max_length=10, min_length=1)
+    description: constr(max_length=200) | None = None
+
+
+class CreateWebhookResponse(BaseModel):
+    id: constr(
+        pattern=r"^whk_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+    )
+    url: AnyUrl
+    secret_prefix: str
+    events: list[
+        Literal[
+            "session.completed",
+            "session.failed",
+            "quota.warning_80pct",
+            "quota.exceeded",
+            "api_key.revoked",
+        ]
+    ]
+    description: str | None
+    active: bool
+    consecutive_failures: conint(ge=0)
+    last_success_at: AwareDatetime | None
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """
+    last_failure_at: AwareDatetime | None
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """
+    disabled_at: AwareDatetime | None
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """
+    created_at: AwareDatetime
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """
+    secret: str
+    """
+    Plaintext signing secret. Returned ONCE; not retrievable later.
+    """
+
+
+class WebhookDelivery(BaseModel):
+    id: constr(
+        pattern=r"^wdl_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+    )
+    webhook_id: constr(
+        pattern=r"^whk_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+    )
+    event_id: UUID
+    event_type: Literal[
+        "session.completed",
+        "session.failed",
+        "quota.warning_80pct",
+        "quota.exceeded",
+        "api_key.revoked",
+    ]
+    status: Literal["pending", "in_flight", "delivered", "failed", "dlq"]
+    attempts: conint(ge=0)
+    next_attempt_at: AwareDatetime
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """
+    last_response_status: int | None
+    last_response_excerpt: str | None
+    last_error: str | None
+    delivered_at: AwareDatetime | None
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """
+    created_at: AwareDatetime
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """
+
+
+class ListDeliveriesQuery(BaseModel):
+    limit: conint(ge=1, le=100) | None = 50
+    cursor: str | None = None
+    status: Literal["pending", "in_flight", "delivered", "failed", "dlq"] | None = None
+
+
+class AdminAccount(BaseModel):
+    id: constr(
+        pattern=r"^acc_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+    )
+    email: EmailStr
+    name: str | None
+    tier: Literal["free", "starter", "solo", "builder", "scale", "enterprise"]
+    status: Literal["active", "suspended", "deleted"]
+    created_at: AwareDatetime
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """
+    updated_at: AwareDatetime
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """
+
+
+class AdminAuditLogEntry(BaseModel):
+    id: UUID
+    admin_account_id: str
+    admin_key_id: str
+    action: Literal[
+        "account.tier_changed",
+        "account.suspended",
+        "account.unsuspended",
+        "webhook_delivery.replayed",
+        "webhook_delivery.requeued",
+        "rate_limit_override.set",
+        "rate_limit_override.cleared",
+    ]
+    target_account_id: str | None
+    target_resource_id: str | None
+    input_payload: dict[str, Any] | None
+    result: str
+    ip_address: str | None
+    timestamp: AwareDatetime
+    """
+    ISO 8601 timestamp with timezone offset, e.g. 2026-05-02T09:15:00Z
+    """

driftstack/_version.py

@@ -0,0 +1,10 @@
+"""Single source of truth for the SDK's package version.
+
+Kept in a tiny module so `__init__.py` can import it without pulling
+in the full dependency graph (httpx, pydantic) before the version is
+needed — useful for tools that scrape the version without installing.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"

driftstack/client.py

@@ -0,0 +1,120 @@
+"""Top-level Driftstack client.
+
+Two parallel classes — :class:`Driftstack` (sync, ``httpx.Client``)
+and :class:`AsyncDriftstack` (async, ``httpx.AsyncClient``). Mirrors
+the pattern used by Stripe-Python, OpenAI-Python, Anthropic-Python.
+
+Resource accessors are placeholders in this commit — full
+implementations land in PY2. The constructor + auth + transport
+plumbing is covered by the smoke tests in this commit.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from driftstack.http import AsyncHttpClient, HttpClient
+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
+from driftstack.retry import RetryConfig
+
+DEFAULT_BASE_URL = "https://api.driftstack.dev"
+
+
+def _validate_api_key(api_key: str) -> None:
+    if not api_key or not isinstance(api_key, str):
+        raise TypeError("Driftstack: api_key is required and must be a string")
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# Sync
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class Driftstack:
+    """Synchronous Driftstack API client.
+
+    Example::
+
+        from driftstack import Driftstack
+
+        client = Driftstack(api_key="ds_live_…")
+        session = client.sessions.create()
+        client.sessions.navigate(session.id, {"url": "https://example.com"})
+        client.sessions.destroy(session.id)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout_s: float = 30.0,
+        retry: RetryConfig | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        _validate_api_key(api_key)
+        self._http = HttpClient(
+            api_key,
+            base_url=base_url,
+            timeout_s=timeout_s,
+            retry=retry,
+            client=http_client,
+        )
+        self.sessions = SessionsResource(self._http)
+        self.api_keys = ApiKeysResource(self._http)
+        self.usage = UsageResource(self._http)
+        self.webhooks = WebhooksResource(self._http)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> Driftstack:
+        return self
+
+    def __exit__(self, *_excinfo: Any) -> None:
+        self.close()
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# Async
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class AsyncDriftstack:
+    """Async Driftstack API client. asyncio-compatible."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout_s: float = 30.0,
+        retry: RetryConfig | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        _validate_api_key(api_key)
+        self._http = AsyncHttpClient(
+            api_key,
+            base_url=base_url,
+            timeout_s=timeout_s,
+            retry=retry,
+            client=http_client,
+        )
+        self.sessions = AsyncSessionsResource(self._http)
+        self.api_keys = AsyncApiKeysResource(self._http)
+        self.usage = AsyncUsageResource(self._http)
+        self.webhooks = AsyncWebhooksResource(self._http)
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncDriftstack:
+        return self
+
+    async def __aexit__(self, *_excinfo: Any) -> None:
+        await self.aclose()