driftstack-sdk 0.1.0__py3-none-any.whl

driftstack_sdk-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,19 @@
+driftstack/__init__.py,sha256=LNJKiDuftp5bDH2j8UZU9QxVzu6x-fzAbG3Joo5u-zc,1474
+driftstack/_version.py,sha256=SSsD1--zWDGoDKKzXI8AKzNzGe6NPmM1VgsDlcDaIJY,331
+driftstack/client.py,sha256=fI_WcPfeN8rpgOpvbhq8S_Ku5bwdfhMJtw1FyDuup8w,4276
+driftstack/errors.py,sha256=caO__wvZ1TTTscsCiAmgltjISqtglnfrb24u4O_Shts,6938
+driftstack/http.py,sha256=qm6uFXnq6OtAzs0-IA1ofk3pTFtuHpK1XQOCX-jviko,10099
+driftstack/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+driftstack/retry.py,sha256=O3ONsIx11NUTLkumxo0wBJit5kVNMy5Vg0GBtaJkOxM,3491
+driftstack/webhook_signature.py,sha256=S__HBpImMcSHz4FvHWRCBtwANkK2JRQQwikY9ZDrJ7c,3214
+driftstack/_generated/__init__.py,sha256=RTXUjfOp7ZVibedHEGqtfr6CPB8h3XKLbz3-KYGcLPU,258
+driftstack/_generated/models.py,sha256=IzOtTzjdDKvn73GEuyDk5D2NnZoDnvvpz0XdX5WGvh0,13615
+driftstack/resources/__init__.py,sha256=PC44R4_TfnLkPAK7Ty9Wy7XfTQq5_GbN7bx3GQeDNXo,1024
+driftstack/resources/_common.py,sha256=DyBQPAQThPz3H3Z0Q6klgd_XgSYrwlH_r5izVS4MI_s,1339
+driftstack/resources/api_keys.py,sha256=7uGiKtq5gaXG2CGgRzfkTP-5R5FgtFTignNMgxLZWQ0,2148
+driftstack/resources/sessions.py,sha256=xsPoxNubJ299bG4wlz1ZRXcMv8va4GQXsZDLPy4WRIo,5913
+driftstack/resources/usage.py,sha256=oegqGhkpeosmcKUzqQPPzTJdyWnEPVjYQ-gPs8Sz8ks,868
+driftstack/resources/webhooks.py,sha256=APLdXHTYS47oXi-166E4KV8DEpIGnqvDk_Ek0mCG2Kk,3635
+driftstack_sdk-0.1.0.dist-info/METADATA,sha256=6UjEjmWygo7nMXWfPg6MpFFgtDI9vqaeyjm_49qNv4U,8104
+driftstack_sdk-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+driftstack_sdk-0.1.0.dist-info/RECORD,,

driftstack_sdk-0.1.0.dist-info/WHEEL

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