thrustlab 0.1.0__py3-none-any.whl

thrustlab/resources/submissions.py

@@ -0,0 +1,44 @@
+"""``client.submissions`` — community component submissions.
+
+Endpoints:
+    GET    /v1/submissions
+    POST   /v1/submissions
+    GET    /v1/submissions/{id}
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from thrustlab._pagination import CursorPager
+from thrustlab.resources._base import Resource
+
+
+class SubmissionsResource(Resource):
+    def list(self, *, limit: int = 20, starting_after: Optional[str] = None) -> CursorPager[dict[str, Any]]:
+        """List submissions (cursor-paginated).
+
+        Returns a :class:`CursorPager` that lazily fetches subsequent pages.
+        """
+        params: dict[str, Any] = {"limit": limit}
+        if starting_after:
+            params["starting_after"] = starting_after
+        return CursorPager(
+            fetch_page=lambda p: self._transport.request("GET", "/v1/submissions", params=p),
+            initial_params=params,
+        )
+
+    def create(
+        self,
+        *,
+        component_data: dict[str, Any],
+        idempotency_key: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """Submit a new component for review."""
+        return self._transport.request(
+            "POST", "/v1/submissions", json=component_data,
+            idempotency_key=idempotency_key,
+        )
+
+    def retrieve(self, submission_id: str) -> dict[str, Any]:
+        return self._transport.request("GET", f"/v1/submissions/{submission_id}")

thrustlab/resources/subscriptions.py

@@ -0,0 +1,42 @@
+"""``client.subscriptions`` — subscription info and billing portal.
+
+Endpoints:
+    GET    /v1/subscriptions/me
+    POST   /v1/subscriptions/billing_portal/sessions
+
+Note: billing_portal/sessions returns 503 ``billing_not_configured`` in Phase A
+(before Stripe account setup). The SDK propagates this as ``APIServerError``
+without special-casing.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from thrustlab.resources._base import Resource
+
+
+class SubscriptionsResource(Resource):
+    def me(self) -> dict[str, Any]:
+        """Return the authenticated user's subscription details."""
+        return self._transport.request("GET", "/v1/subscriptions/me")
+
+    def create_billing_portal_session(
+        self,
+        *,
+        return_url: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """Create a Stripe billing-portal session and return the redirect URL.
+
+        Raises ``APIServerError`` with code ``billing_not_configured`` when
+        Stripe is not yet configured (Phase A).
+        """
+        body: dict[str, Any] = {}
+        if return_url:
+            body["return_url"] = return_url
+        return self._transport.request(
+            "POST", "/v1/subscriptions/billing_portal/sessions",
+            json=body or None,
+            idempotency_key=idempotency_key,
+        )

thrustlab/resources/sweeps.py

@@ -0,0 +1,96 @@
+"""``client.sweeps`` — run and manage parameter sweeps.
+
+Endpoints:
+    GET    /v1/sweeps
+    POST   /v1/sweeps
+    GET    /v1/sweeps/{id}
+    POST   /v1/sweeps/{id}/cancel
+    GET    /v1/sweeps/{id}/points
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from thrustlab._async_polling import poll_until_terminal
+from thrustlab._pagination import CursorPager
+from thrustlab.resources._base import Resource
+
+
+class SweepsResource(Resource):
+    def list(
+        self,
+        *,
+        project_id: Optional[str] = None,
+        limit: int = 20,
+        starting_after: Optional[str] = None,
+    ) -> CursorPager[dict[str, Any]]:
+        """List sweeps (cursor-paginated).
+
+        Returns a :class:`CursorPager` that lazily fetches subsequent pages.
+        """
+        params: dict[str, Any] = {"limit": limit}
+        if project_id:
+            params["project_id"] = project_id
+        if starting_after:
+            params["starting_after"] = starting_after
+        return CursorPager(
+            fetch_page=lambda p: self._transport.request("GET", "/v1/sweeps", params=p),
+            initial_params=params,
+        )
+
+    def create(
+        self,
+        *,
+        project_id: str,
+        idempotency_key: Optional[str] = None,
+        **params: Any,
+    ) -> dict[str, Any]:
+        """Submit a sweep. Returns the resource in pending/running state."""
+        body = {"project_id": project_id, **params}
+        return self._transport.request(
+            "POST", "/v1/sweeps", json=body,
+            idempotency_key=idempotency_key,
+        )
+
+    def retrieve(self, sweep_id: str) -> dict[str, Any]:
+        return self._transport.request("GET", f"/v1/sweeps/{sweep_id}")
+
+    def cancel(self, sweep_id: str, *, idempotency_key: Optional[str] = None) -> dict[str, Any]:
+        return self._transport.request(
+            "POST", f"/v1/sweeps/{sweep_id}/cancel",
+            idempotency_key=idempotency_key,
+        )
+
+    def list_points(
+        self,
+        sweep_id: str,
+        *,
+        limit: int = 100,
+        starting_after: Optional[str] = None,
+    ) -> CursorPager[dict[str, Any]]:
+        """List computed sweep points (cursor-paginated).
+
+        Returns a :class:`CursorPager` that lazily fetches subsequent pages.
+        """
+        params: dict[str, Any] = {"limit": limit}
+        if starting_after:
+            params["starting_after"] = starting_after
+        return CursorPager(
+            fetch_page=lambda p: self._transport.request(
+                "GET", f"/v1/sweeps/{sweep_id}/points", params=p
+            ),
+            initial_params=params,
+        )
+
+    def wait(self, sweep_id: str, *, poll_interval: float = 2.0, timeout: float = 600.0) -> dict[str, Any]:
+        """Poll until the sweep reaches a terminal state.
+
+        Returns the final resource dict. If ``timeout`` is exceeded, the dict
+        has ``status="timed_out"`` (SDK-side sentinel, not a server state).
+        """
+        return poll_until_terminal(
+            fetch=lambda: self.retrieve(sweep_id),
+            timeout=timeout,
+            poll_interval=poll_interval,
+        )

thrustlab/resources/users.py

@@ -0,0 +1,13 @@
+"""``client.users`` — authenticated user profile."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from thrustlab.resources._base import Resource
+
+
+class UsersResource(Resource):
+    def me(self) -> dict[str, Any]:
+        """Return the authenticated user's profile."""
+        return self._transport.request("GET", "/v1/users/me")

thrustlab/resources/webhook_endpoints.py

@@ -0,0 +1,138 @@
+"""``client.webhook_endpoints`` — manage webhook endpoints, events, and deliveries.
+
+Endpoints:
+    GET    /v1/webhook_endpoints
+    POST   /v1/webhook_endpoints
+    GET    /v1/webhook_endpoints/{id}
+    PATCH  /v1/webhook_endpoints/{id}
+    DELETE /v1/webhook_endpoints/{id}
+    POST   /v1/webhook_endpoints/{id}/rotate_secret
+    POST   /v1/webhook_endpoints/{id}/test
+    GET    /v1/events
+    GET    /v1/webhook_endpoints/{id}/deliveries
+    POST   /v1/webhook_endpoints/{id}/deliveries/{did}/retry
+"""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+from thrustlab._pagination import CursorPager
+from thrustlab.resources._base import Resource
+
+
+class WebhookEndpointsResource(Resource):
+    def list(self, *, limit: int = 20, starting_after: Optional[str] = None) -> CursorPager[dict[str, Any]]:
+        """List webhook endpoints (cursor-paginated).
+
+        Returns a :class:`CursorPager` that lazily fetches subsequent pages.
+        """
+        params: dict[str, Any] = {"limit": limit}
+        if starting_after:
+            params["starting_after"] = starting_after
+        return CursorPager(
+            fetch_page=lambda p: self._transport.request("GET", "/v1/webhook_endpoints", params=p),
+            initial_params=params,
+        )
+
+    def create(
+        self,
+        *,
+        url: str,
+        events: List[str],
+        description: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {"url": url, "events": events}
+        if description is not None:
+            body["description"] = description
+        return self._transport.request(
+            "POST", "/v1/webhook_endpoints", json=body,
+            idempotency_key=idempotency_key,
+        )
+
+    def retrieve(self, endpoint_id: str) -> dict[str, Any]:
+        return self._transport.request("GET", f"/v1/webhook_endpoints/{endpoint_id}")
+
+    def update(
+        self,
+        endpoint_id: str,
+        *,
+        idempotency_key: Optional[str] = None,
+        **fields: Any,
+    ) -> dict[str, Any]:
+        return self._transport.request(
+            "PATCH", f"/v1/webhook_endpoints/{endpoint_id}", json=fields,
+            idempotency_key=idempotency_key,
+        )
+
+    def delete(self, endpoint_id: str, *, idempotency_key: Optional[str] = None) -> None:
+        self._transport.request(
+            "DELETE", f"/v1/webhook_endpoints/{endpoint_id}",
+            idempotency_key=idempotency_key,
+        )
+
+    def rotate_secret(self, endpoint_id: str, *, idempotency_key: Optional[str] = None) -> dict[str, Any]:
+        """Rotate the signing secret for this endpoint."""
+        return self._transport.request(
+            "POST", f"/v1/webhook_endpoints/{endpoint_id}/rotate_secret",
+            idempotency_key=idempotency_key,
+        )
+
+    def test(self, endpoint_id: str, *, idempotency_key: Optional[str] = None) -> dict[str, Any]:
+        """Send a test event to the endpoint."""
+        return self._transport.request(
+            "POST", f"/v1/webhook_endpoints/{endpoint_id}/test",
+            idempotency_key=idempotency_key,
+        )
+
+    def list_events(self, *, limit: int = 20, starting_after: Optional[str] = None) -> CursorPager[dict[str, Any]]:
+        """List all event types (cursor-paginated).
+
+        Returns a :class:`CursorPager` that lazily fetches subsequent pages.
+        """
+        params: dict[str, Any] = {"limit": limit}
+        if starting_after:
+            params["starting_after"] = starting_after
+        return CursorPager(
+            fetch_page=lambda p: self._transport.request("GET", "/v1/events", params=p),
+            initial_params=params,
+        )
+
+    def list_deliveries(
+        self,
+        endpoint_id: str,
+        *,
+        status: Optional[str] = None,
+        limit: int = 20,
+        starting_after: Optional[str] = None,
+    ) -> CursorPager[dict[str, Any]]:
+        """List delivery attempts for an endpoint (cursor-paginated).
+
+        Returns a :class:`CursorPager` that lazily fetches subsequent pages.
+        """
+        params: dict[str, Any] = {"limit": limit}
+        if status:
+            params["status"] = status
+        if starting_after:
+            params["starting_after"] = starting_after
+        return CursorPager(
+            fetch_page=lambda p: self._transport.request(
+                "GET", f"/v1/webhook_endpoints/{endpoint_id}/deliveries", params=p
+            ),
+            initial_params=params,
+        )
+
+    def retry_delivery(
+        self,
+        endpoint_id: str,
+        delivery_id: str,
+        *,
+        idempotency_key: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """Retry a failed delivery."""
+        return self._transport.request(
+            "POST",
+            f"/v1/webhook_endpoints/{endpoint_id}/deliveries/{delivery_id}/retry",
+            idempotency_key=idempotency_key,
+        )

thrustlab/webhooks.py

@@ -0,0 +1,121 @@
+"""Webhook signature verification + Event parsing.
+
+Mirrors the live webhook-delivery service's HMAC scheme. The server-side
+implementation is in ``backend/app/services/webhooks.py``.
+
+Signing scheme (as of 2026-04-25):
+  Header name:  ``Thrustlab-Signature``
+  Header value: ``t=<unix_ts>,v1=<hex>``
+  Signed blob:  ``f"{unix_ts}.{body_utf8}".encode("utf-8")``
+  Algorithm:    ``hmac.new(secret.encode("utf-8"), blob, hashlib.sha256).hexdigest()``
+  Tolerance:    300 seconds (5 minutes) by default
+
+Example::
+
+    from thrustlab import Webhook
+    from thrustlab.exceptions import SignatureVerificationError
+
+    try:
+        event = Webhook.verify(request.body, request.headers["Thrustlab-Signature"], secret)
+    except SignatureVerificationError as e:
+        return 400, str(e)
+    process(event)
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from dataclasses import dataclass
+from typing import Any
+
+from thrustlab.exceptions import SignatureVerificationError
+
+
+DEFAULT_TOLERANCE_SECONDS = 5 * 60  # 300 s
+
+
+@dataclass
+class Event:
+    """A parsed, verified webhook event."""
+
+    id: str
+    type: str
+    created: int
+    data: dict[str, Any]
+    raw: dict[str, Any]
+
+
+class Webhook:
+    @staticmethod
+    def verify(
+        payload: bytes | str,
+        signature_header: str,
+        secret: str,
+        *,
+        tolerance: int = DEFAULT_TOLERANCE_SECONDS,
+    ) -> Event:
+        """Verify the webhook signature and return the parsed Event.
+
+        Args:
+            payload: Raw request body (bytes or str).
+            signature_header: Value of the ``Thrustlab-Signature`` header.
+            secret: Signing secret starting with ``whsec_``.
+            tolerance: Maximum age of the timestamp in seconds (default 300).
+
+        Returns:
+            Parsed :class:`Event` if verification succeeds.
+
+        Raises:
+            :class:`~thrustlab.exceptions.SignatureVerificationError` on:
+              - Missing or malformed header (no ``t=`` or ``v1=`` parts)
+              - HMAC mismatch (wrong secret, tampered payload)
+              - Timestamp outside the tolerance window (replay protection)
+        """
+        if isinstance(payload, str):
+            payload_bytes = payload.encode("utf-8")
+        else:
+            payload_bytes = payload
+
+        timestamp, sig = _parse_signature_header(signature_header)
+
+        # Construct the signed blob exactly as the server does:
+        #   f"{unix_ts}.{body_utf8}".encode("utf-8")
+        signed = f"{timestamp}.{payload_bytes.decode('utf-8')}".encode("utf-8")
+        expected = hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).hexdigest()
+
+        if not hmac.compare_digest(expected, sig):
+            raise SignatureVerificationError("HMAC signature does not match")
+
+        # Check timestamp *after* HMAC so we don't leak timing info on bad sigs.
+        if abs(time.time() - timestamp) > tolerance:
+            raise SignatureVerificationError(
+                f"timestamp outside tolerance ({tolerance}s)"
+            )
+
+        body = json.loads(payload_bytes)
+        return Event(
+            id=body.get("id", ""),
+            type=body.get("type", ""),
+            created=body.get("created", 0),
+            data=body.get("data", {}),
+            raw=body,
+        )
+
+
+def _parse_signature_header(header: str) -> tuple[int, str]:
+    """Parse ``t=<unix>,v1=<hex>`` header into ``(timestamp, sig_hex)``."""
+    parts: dict[str, str] = {}
+    for chunk in header.split(","):
+        if "=" not in chunk:
+            raise SignatureVerificationError("malformed signature header")
+        k, v = chunk.split("=", 1)
+        parts[k.strip()] = v.strip()
+    if "t" not in parts or "v1" not in parts:
+        raise SignatureVerificationError("missing required signature parts (t or v1)")
+    try:
+        return int(parts["t"]), parts["v1"]
+    except ValueError as exc:
+        raise SignatureVerificationError("malformed timestamp") from exc

thrustlab-0.1.0.dist-info/METADATA

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: thrustlab
+Version: 0.1.0
+Summary: Official Python SDK for the ThrustLab API
+Project-URL: Homepage, https://thrustlab.com
+Project-URL: Documentation, https://thrustlab.com/docs
+Project-URL: Repository, https://github.com/<owner>/thrustlab
+Project-URL: Changelog, https://thrustlab.com/docs/changelog
+Author-email: ThrustLab <support@thrustlab.com>
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: attrs>=23.0
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: pydantic<3.0,>=2.7
+Requires-Dist: python-dateutil>=2.8
+Provides-Extra: dev
+Requires-Dist: openapi-python-client>=0.21; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# thrustlab — official Python SDK for the ThrustLab API
+
+[![PyPI](https://img.shields.io/pypi/v/thrustlab.svg)](https://pypi.org/project/thrustlab/)
+[![Python](https://img.shields.io/pypi/pyversions/thrustlab.svg)](https://pypi.org/project/thrustlab/)
+[![License](https://img.shields.io/pypi/l/thrustlab.svg)](https://github.com/kylebedrich/thrustlab/blob/master/backend/sdks/python/LICENSE)
+
+## Install
+
+```bash
+pip install thrustlab
+```
+
+Requires Python 3.10+.
+
+## Quickstart
+
+```python
+from thrustlab import Client
+
+client = Client(api_key="key_...")  # or set $THRUSTLAB_API_KEY
+
+# Create a project
+project = client.projects.create(name="my project")
+
+# Run a simulation and wait for the result
+sim = client.simulations.create(
+    project_id=project["id"],
+    motor="comp_motor_xxx",
+    propeller="comp_prop_xxx",
+    battery="comp_batt_xxx",
+    throttle=0.7,
+)
+result = client.simulations.wait(sim["id"], timeout=300)
+print(result)
+```
+
+## Configuration
+
+| Setting      | Constructor arg  | Env var               | Default                  |
+|--------------|------------------|-----------------------|--------------------------|
+| API key      | `api_key=`       | `THRUSTLAB_API_KEY`   | (required)               |
+| Base URL     | `base_url=`      | `THRUSTLAB_BASE_URL`  | `https://thrustlab.com`  |
+| Timeout      | `timeout=`       | —                     | `30` (seconds)           |
+| Max retries  | `max_retries=`   | —                     | `3`                      |
+
+## Resources
+
+Every `/v1/` route family is exposed as an attribute on the client:
+
+```python
+client.api_keys
+client.users
+client.projects
+client.simulations
+client.sweeps
+client.components
+client.submissions
+client.starred_components
+client.geometry
+client.credits
+client.subscriptions
+client.webhook_endpoints
+```
+
+## Error handling
+
+```python
+from thrustlab import Client
+from thrustlab.exceptions import (
+    AuthenticationError,
+    ValidationError,
+    RateLimitError,
+    NotFoundError,
+)
+
+client = Client()
+try:
+    client.simulations.create(project_id="proj_xxx", motor="comp_xxx", ...)
+except ValidationError as exc:
+    print(f"bad request: {exc.code} ({exc.param}): {exc.message}")
+except RateLimitError as exc:
+    print(f"rate limited; retry after {exc.retry_after}s")
+except NotFoundError as exc:
+    print(f"not found: {exc.message}")
+except AuthenticationError as exc:
+    print(f"auth failed: {exc.message}")
+```
+
+Every error carries `.code`, `.type`, `.request_id`, `.http_status`, and
+`.message`. `ValidationError` additionally exposes `.param`. See
+[thrustlab.com/docs/guides/errors](https://thrustlab.com/docs/guides/errors)
+for the full code reference.
+
+## Pagination
+
+List endpoints return a `CursorPager` — a lazy iterator that fetches the
+next page only when needed:
+
+```python
+# Iterate all pages automatically
+for project in client.projects.list():
+    print(project["id"])
+
+# Materialise the first page only
+first_page = list(client.projects.list(limit=20))
+```
+
+## Async polling
+
+`simulations.wait()` and `sweeps.wait()` block until the resource reaches a
+terminal state (`succeeded`, `failed`, or `cancelled`) or the timeout fires:
+
+```python
+sweep = client.sweeps.create(...)
+result = client.sweeps.wait(sweep["id"], timeout=600, poll_interval=2.0)
+if result["status"] == "succeeded":
+    print(result["outputs"])
+```
+
+## Webhooks
+
+```python
+from thrustlab import Webhook
+from thrustlab.exceptions import SignatureVerificationError
+
+WEBHOOK_SECRET = "whsec_..."
+
+@app.post("/webhooks/thrustlab")
+async def handle(request):
+    payload = await request.body()
+    sig    = request.headers["Thrustlab-Signature"]
+    try:
+        event = Webhook.verify(payload, sig, WEBHOOK_SECRET)
+    except SignatureVerificationError:
+        return Response(status_code=400)
+    if event.type == "simulation.succeeded":
+        print(event.data)
+```
+
+## Retries
+
+The client automatically retries on 429 (rate limit) and 5xx responses using
+exponential backoff with jitter. Set `max_retries=0` to disable:
+
+```python
+client = Client(max_retries=0)
+```
+
+## Links
+
+- Documentation: https://thrustlab.com/docs
+- API reference: https://thrustlab.com/docs/reference
+- SDK guide: https://thrustlab.com/docs/sdk/python
+- Changelog: https://thrustlab.com/docs/changelog
+- Issue tracker: https://github.com/kylebedrich/thrustlab/issues
+
+## License
+
+MIT