driftstack-sdk 0.1.0__tar.gz

driftstack_sdk-0.1.0/.gitignore

@@ -0,0 +1,45 @@
+node_modules/
+dist/
+build/
+coverage/
+.tsbuildinfo
+*.tsbuildinfo
+
+# Env
+.env
+.env.*
+!.env.example
+
+# Editor
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# Logs
+*.log
+npm-debug.log*
+
+# Test artifacts
+test-results/
+playwright-report/
+playwright/.cache/
+
+# Drizzle
+drizzle/.migrations-applied
+
+# Python SDK
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+packages/sdk-python/dist/
+.npmrc
+
+# GUI client (Tauri)
+apps/gui-client/dist/
+apps/gui-client/src-tauri/target/
+apps/gui-client/src-tauri/gen/
+# Cargo.lock SHOULD be committed for binaries (Tauri app is a binary).

driftstack_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: driftstack-sdk
+Version: 0.1.0
+Summary: Driftstack Python SDK — stealth iPhone Safari automation. Import as `driftstack`.
+Project-URL: Homepage, https://driftstack.dev
+Project-URL: Repository, https://github.com/driftstackdev/driftstack-api
+Project-URL: Issues, https://github.com/driftstackdev/driftstack-api/issues
+Author: Driftstack
+License: MIT
+Keywords: browser-automation,driftstack,ios,safari,stealth
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: pydantic[email]<3.0,>=2.5
+Provides-Extra: dev
+Requires-Dist: datamodel-code-generator[http]>=0.25; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Driftstack Python SDK
+
+Stealth iPhone Safari automation, called from Python. Sync (`Driftstack`) and async (`AsyncDriftstack`) clients in one package, sharing the same typed resources, error hierarchy, and retry policy.
+
+> **Status:** alpha. The SDK is built, tested, and wheel-buildable, but **not yet published to PyPI** — gated on entity setup. Until then, install from a local checkout or a tagged commit.
+
+## Install
+
+```bash
+pip install driftstack-sdk
+```
+
+The dist name on PyPI is `driftstack-sdk`; the import name is `driftstack`.
+
+Requires Python 3.10+.
+
+## Quickstart (sync)
+
+```python
+from driftstack import Driftstack
+
+with Driftstack(api_key="ds_live_…") as client:
+    session = client.sessions.create({"label": "ci-run"})
+    client.sessions.navigate(str(session.id), {"url": "https://example.com/"})
+    state = client.sessions.get_state(str(session.id))
+    print(state.url, state.title)
+    client.sessions.destroy(str(session.id))
+```
+
+## Quickstart (async)
+
+```python
+import asyncio
+from driftstack import AsyncDriftstack
+
+async def main():
+    async with AsyncDriftstack(api_key="ds_live_…") as client:
+        s = await client.sessions.create()
+        await client.sessions.navigate(str(s.id), {"url": "https://example.com/"})
+        await client.sessions.destroy(str(s.id))
+
+asyncio.run(main())
+```
+
+## Resources
+
+Every public API endpoint is a typed method on a resource accessor:
+
+| Accessor          | Methods                                                                                    |
+| ----------------- | ------------------------------------------------------------------------------------------ |
+| `client.sessions` | `create`, `list`, `get`, `navigate`, `interact`, `wait`, `get_state`, `capture`, `destroy` |
+| `client.api_keys` | `create`, `list`, `revoke`                                                                 |
+| `client.usage`    | `current_period`                                                                           |
+| `client.webhooks` | `create`, `list`, `get`, `delete`, `list_deliveries`                                       |
+
+Inputs accept either a Pydantic model OR a plain `dict` (both serialize identically on the wire). Outputs are typed Pydantic models — IDEs autocomplete every field.
+
+```python
+# Either of these works:
+from driftstack._generated.models import CreateSessionRequest
+client.sessions.create(CreateSessionRequest(label="ci"))
+client.sessions.create({"label": "ci"})
+```
+
+## Error handling
+
+Every server `application/problem+json` response is mapped to a typed exception. The base class is `DriftstackError`; subclasses cover the documented problem types.
+
+```python
+from driftstack import (
+    AuthError,
+    ConcurrencyLimitError,
+    DriftstackError,
+    QuotaExceededError,
+    RateLimitError,
+    ValidationError,
+)
+
+try:
+    session = client.sessions.create()
+except AuthError:
+    ...                                    # invalid / expired / revoked key
+except ConcurrencyLimitError as e:
+    ...                                    # e.current_sessions / e.limit
+except QuotaExceededError as e:
+    ...                                    # e.current / e.limit / e.record_type
+except RateLimitError as e:
+    time.sleep(e.retry_after_seconds or 1)
+except ValidationError as e:
+    ...                                    # e.message has the server's detail
+except DriftstackError as e:
+    ...                                    # catch-all for anything else
+```
+
+The full hierarchy lives in `driftstack/errors.py`; the URI → exception mapping is in `PROBLEM_TYPE_TO_ERROR`.
+
+## Retry
+
+Default policy: 3 retries with exponential backoff and full jitter. Honours `Retry-After` from rate-limit responses. Customize via `RetryConfig`:
+
+```python
+from driftstack import Driftstack
+from driftstack.retry import RetryConfig
+
+client = Driftstack(
+    api_key="ds_live_…",
+    retry=RetryConfig(max_retries=5, initial_delay_ms=500, max_delay_ms=10_000),
+)
+
+# Disable entirely for predictable testing:
+client = Driftstack(api_key="…", retry=RetryConfig(enabled=False))
+```
+
+Retryable errors by default: `TransportError` (network / timeout / parse) + `RateLimitError`. Other typed errors (auth, validation, quota, concurrency) propagate immediately.
+
+## Webhook signature verification
+
+Stripe-style HMAC-SHA256 over `<unix_seconds>.<raw_body>`. Constant-time comparison via `hmac.compare_digest`. 5-minute default tolerance.
+
+```python
+from driftstack import verify_webhook_signature
+
+@app.post("/driftstack-webhook")
+def receive():
+    raw = request.get_data()                   # framework-specific raw body
+    ok = verify_webhook_signature(
+        body=raw,
+        header=request.headers.get("x-driftstack-signature"),
+        secret=os.environ["DRIFTSTACK_WEBHOOK_SECRET"],
+    )
+    if not ok:
+        return ("", 401)
+    # ... process event ...
+    return ("", 204)
+```
+
+A complete stdlib-only receiver lives in [`examples/webhook_receiver.py`](examples/webhook_receiver.py).
+
+## Examples
+
+- [`quickstart.py`](examples/quickstart.py) — minimal create/navigate/capture/destroy.
+- [`error_handling.py`](examples/error_handling.py) — granular catch + custom retry loop.
+- [`webhook_receiver.py`](examples/webhook_receiver.py) — stdlib HTTP receiver with signature verify + dispatch.
+- [`langchain_tool.py`](examples/langchain_tool.py) — LangChain `Tool` adapter for AI-agent QA pipelines.
+- [`pytest_fixture.py`](examples/pytest_fixture.py) — drop-in `mock_driftstack` fixture for customer test suites.
+
+## Configuration
+
+```python
+client = Driftstack(
+    api_key="ds_live_…",          # required
+    base_url="https://api.driftstack.dev",   # default; override for self-host or test
+    timeout_s=30.0,               # per-request timeout
+    retry=RetryConfig(...),       # see above
+    http_client=httpx.Client(...) # advanced: BYO httpx.Client
+)
+```
+
+The async client takes the same arguments; pass `httpx.AsyncClient(...)` instead of `httpx.Client(...)`.
+
+## Development
+
+```bash
+# from packages/sdk-python/
+python3.10 -m venv .venv
+source .venv/bin/activate
+pip install -e '.[dev]'
+pytest
+ruff check . && ruff format --check .
+mypy src
+```
+
+Re-generate Pydantic models from a fresh OpenAPI spec:
+
+```bash
+# from the repo root
+npm run sdk:python:dump-spec     # writes packages/sdk-python/openapi.json
+npm run sdk:python:generate      # runs datamodel-codegen
+```
+
+Build the wheel:
+
+```bash
+# from packages/sdk-python/
+python -m pip install build
+python -m build       # → dist/driftstack-X.Y.Z-py3-none-any.whl + sdist
+```
+
+## License
+
+MIT.

driftstack_sdk-0.1.0/README.md

@@ -0,0 +1,191 @@
+# Driftstack Python SDK
+
+Stealth iPhone Safari automation, called from Python. Sync (`Driftstack`) and async (`AsyncDriftstack`) clients in one package, sharing the same typed resources, error hierarchy, and retry policy.
+
+> **Status:** alpha. The SDK is built, tested, and wheel-buildable, but **not yet published to PyPI** — gated on entity setup. Until then, install from a local checkout or a tagged commit.
+
+## Install
+
+```bash
+pip install driftstack-sdk
+```
+
+The dist name on PyPI is `driftstack-sdk`; the import name is `driftstack`.
+
+Requires Python 3.10+.
+
+## Quickstart (sync)
+
+```python
+from driftstack import Driftstack
+
+with Driftstack(api_key="ds_live_…") as client:
+    session = client.sessions.create({"label": "ci-run"})
+    client.sessions.navigate(str(session.id), {"url": "https://example.com/"})
+    state = client.sessions.get_state(str(session.id))
+    print(state.url, state.title)
+    client.sessions.destroy(str(session.id))
+```
+
+## Quickstart (async)
+
+```python
+import asyncio
+from driftstack import AsyncDriftstack
+
+async def main():
+    async with AsyncDriftstack(api_key="ds_live_…") as client:
+        s = await client.sessions.create()
+        await client.sessions.navigate(str(s.id), {"url": "https://example.com/"})
+        await client.sessions.destroy(str(s.id))
+
+asyncio.run(main())
+```
+
+## Resources
+
+Every public API endpoint is a typed method on a resource accessor:
+
+| Accessor          | Methods                                                                                    |
+| ----------------- | ------------------------------------------------------------------------------------------ |
+| `client.sessions` | `create`, `list`, `get`, `navigate`, `interact`, `wait`, `get_state`, `capture`, `destroy` |
+| `client.api_keys` | `create`, `list`, `revoke`                                                                 |
+| `client.usage`    | `current_period`                                                                           |
+| `client.webhooks` | `create`, `list`, `get`, `delete`, `list_deliveries`                                       |
+
+Inputs accept either a Pydantic model OR a plain `dict` (both serialize identically on the wire). Outputs are typed Pydantic models — IDEs autocomplete every field.
+
+```python
+# Either of these works:
+from driftstack._generated.models import CreateSessionRequest
+client.sessions.create(CreateSessionRequest(label="ci"))
+client.sessions.create({"label": "ci"})
+```
+
+## Error handling
+
+Every server `application/problem+json` response is mapped to a typed exception. The base class is `DriftstackError`; subclasses cover the documented problem types.
+
+```python
+from driftstack import (
+    AuthError,
+    ConcurrencyLimitError,
+    DriftstackError,
+    QuotaExceededError,
+    RateLimitError,
+    ValidationError,
+)
+
+try:
+    session = client.sessions.create()
+except AuthError:
+    ...                                    # invalid / expired / revoked key
+except ConcurrencyLimitError as e:
+    ...                                    # e.current_sessions / e.limit
+except QuotaExceededError as e:
+    ...                                    # e.current / e.limit / e.record_type
+except RateLimitError as e:
+    time.sleep(e.retry_after_seconds or 1)
+except ValidationError as e:
+    ...                                    # e.message has the server's detail
+except DriftstackError as e:
+    ...                                    # catch-all for anything else
+```
+
+The full hierarchy lives in `driftstack/errors.py`; the URI → exception mapping is in `PROBLEM_TYPE_TO_ERROR`.
+
+## Retry
+
+Default policy: 3 retries with exponential backoff and full jitter. Honours `Retry-After` from rate-limit responses. Customize via `RetryConfig`:
+
+```python
+from driftstack import Driftstack
+from driftstack.retry import RetryConfig
+
+client = Driftstack(
+    api_key="ds_live_…",
+    retry=RetryConfig(max_retries=5, initial_delay_ms=500, max_delay_ms=10_000),
+)
+
+# Disable entirely for predictable testing:
+client = Driftstack(api_key="…", retry=RetryConfig(enabled=False))
+```
+
+Retryable errors by default: `TransportError` (network / timeout / parse) + `RateLimitError`. Other typed errors (auth, validation, quota, concurrency) propagate immediately.
+
+## Webhook signature verification
+
+Stripe-style HMAC-SHA256 over `<unix_seconds>.<raw_body>`. Constant-time comparison via `hmac.compare_digest`. 5-minute default tolerance.
+
+```python
+from driftstack import verify_webhook_signature
+
+@app.post("/driftstack-webhook")
+def receive():
+    raw = request.get_data()                   # framework-specific raw body
+    ok = verify_webhook_signature(
+        body=raw,
+        header=request.headers.get("x-driftstack-signature"),
+        secret=os.environ["DRIFTSTACK_WEBHOOK_SECRET"],
+    )
+    if not ok:
+        return ("", 401)
+    # ... process event ...
+    return ("", 204)
+```
+
+A complete stdlib-only receiver lives in [`examples/webhook_receiver.py`](examples/webhook_receiver.py).
+
+## Examples
+
+- [`quickstart.py`](examples/quickstart.py) — minimal create/navigate/capture/destroy.
+- [`error_handling.py`](examples/error_handling.py) — granular catch + custom retry loop.
+- [`webhook_receiver.py`](examples/webhook_receiver.py) — stdlib HTTP receiver with signature verify + dispatch.
+- [`langchain_tool.py`](examples/langchain_tool.py) — LangChain `Tool` adapter for AI-agent QA pipelines.
+- [`pytest_fixture.py`](examples/pytest_fixture.py) — drop-in `mock_driftstack` fixture for customer test suites.
+
+## Configuration
+
+```python
+client = Driftstack(
+    api_key="ds_live_…",          # required
+    base_url="https://api.driftstack.dev",   # default; override for self-host or test
+    timeout_s=30.0,               # per-request timeout
+    retry=RetryConfig(...),       # see above
+    http_client=httpx.Client(...) # advanced: BYO httpx.Client
+)
+```
+
+The async client takes the same arguments; pass `httpx.AsyncClient(...)` instead of `httpx.Client(...)`.
+
+## Development
+
+```bash
+# from packages/sdk-python/
+python3.10 -m venv .venv
+source .venv/bin/activate
+pip install -e '.[dev]'
+pytest
+ruff check . && ruff format --check .
+mypy src
+```
+
+Re-generate Pydantic models from a fresh OpenAPI spec:
+
+```bash
+# from the repo root
+npm run sdk:python:dump-spec     # writes packages/sdk-python/openapi.json
+npm run sdk:python:generate      # runs datamodel-codegen
+```
+
+Build the wheel:
+
+```bash
+# from packages/sdk-python/
+python -m pip install build
+python -m build       # → dist/driftstack-X.Y.Z-py3-none-any.whl + sdist
+```
+
+## License
+
+MIT.

driftstack_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,112 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "driftstack-sdk"
+version = "0.1.0"
+description = "Driftstack Python SDK — stealth iPhone Safari automation. Import as `driftstack`."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+  { name = "Driftstack" }
+]
+keywords = ["driftstack", "browser-automation", "ios", "safari", "stealth"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.27,<1.0",
+  "pydantic[email]>=2.5,<3.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+  "respx>=0.21",
+  "ruff>=0.5",
+  "mypy>=1.10",
+  "datamodel-code-generator[http]>=0.25",
+]
+
+[project.urls]
+Homepage = "https://driftstack.dev"
+Repository = "https://github.com/driftstackdev/driftstack-api"
+Issues = "https://github.com/driftstackdev/driftstack-api/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/driftstack"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/src/driftstack",
+  "/README.md",
+  "/pyproject.toml",
+]
+
+# ──────────────────────────────────────────────────────────────────
+# pytest
+# ──────────────────────────────────────────────────────────────────
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+filterwarnings = [
+  "error",
+  # Pydantic emits deprecation warnings for some patterns we generate
+  # via datamodel-code-generator; tolerate them so tests don't fail on
+  # codegen output we don't fully control.
+  "default::DeprecationWarning:pydantic",
+  "default::DeprecationWarning:driftstack._generated",
+]
+
+# ──────────────────────────────────────────────────────────────────
+# ruff
+# ──────────────────────────────────────────────────────────────────
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+extend-exclude = ["src/driftstack/_generated"]
+
+[tool.ruff.lint]
+# Conservative starter set; tighten in follow-up commits.
+select = ["E", "F", "I", "B", "UP", "PT"]
+ignore = []
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["B", "PT011"]
+
+# ──────────────────────────────────────────────────────────────────
+# mypy — strict on hand-written code; permissive on _generated
+# ──────────────────────────────────────────────────────────────────
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_unused_configs = true
+exclude = ["build/", "dist/"]
+
+[[tool.mypy.overrides]]
+module = "driftstack._generated.*"
+# Codegen output isn't always strict-clean — `conint(...)` /
+# `constr(...)` factory calls aren't valid type annotations to mypy
+# even though Pydantic v2 accepts them at runtime. Skip type-checking
+# for the codegen module entirely; the wrapper layer that customers
+# actually touch stays strict, and the generated models are runtime-
+# tested via tests/test_generated_models.py.
+ignore_errors = true

driftstack_sdk-0.1.0/src/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_sdk-0.1.0/src/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.
+"""