sesame-sdk 0.1.0__tar.gz

sesame_sdk-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+dist/
+build/

sesame_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sesame
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sesame_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: sesame-sdk
+Version: 0.1.0
+Summary: Python SDK for the Sesame human-in-the-loop approval API
+Project-URL: Homepage, https://github.com/lavanpuri1999/sesame
+Project-URL: Repository, https://github.com/lavanpuri1999/sesame
+Project-URL: Issues, https://github.com/lavanpuri1999/sesame/issues
+Author: Sesame
+License: MIT
+License-File: LICENSE
+Keywords: agents,approval,authorization,human-in-the-loop,sesame,webhook
+Classifier: Development Status :: 4 - Beta
+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.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.6
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# sesame-sdk
+
+Python SDK for the [Sesame](https://getsesame.dev) human-in-the-loop approval API.
+
+Drop an approval gate in front of any sensitive operation in your backend. Sesame
+triggers a request that a human approves (via Telegram + push), and your code blocks
+until the decision lands — or reacts asynchronously via a webhook.
+
+```bash
+pip install sesame-sdk
+```
+
+Requires Python 3.12+. Runtime deps: `httpx`, `pydantic`.
+
+## Configuration
+
+The client reads credentials from the environment, or you can pass them explicitly:
+
+| Env var             | Default                  | Purpose                          |
+| ------------------- | ------------------------ | -------------------------------- |
+| `SESAME_API_KEY`    | _(required)_             | `sk_live_...` API key            |
+| `SESAME_BROKER_URL` | `http://localhost:8000`  | Broker base URL                  |
+
+```python
+from sesame_sdk import Sesame
+
+client = Sesame()                                  # from env
+client = Sesame(api_key="sk_live_...", base_url="https://broker.example.com")
+```
+
+## Gate a function with `@require_approval`
+
+The wrapped function only runs if a human approves. Denied/expired raises
+`ApprovalDenied`; no decision before `timeout` raises `ApprovalTimeout`.
+
+```python
+from sesame_sdk import require_approval, ApprovalDenied
+
+@require_approval(
+    "payments.refund",
+    summary=lambda amount, **_: f"Refund ${amount/100:.2f} to customer",
+    timeout=300,
+)
+def issue_refund(amount: int, customer_id: str) -> None:
+    stripe.Refund.create(amount=amount, customer=customer_id)
+
+try:
+    issue_refund(4200, customer_id="cus_123")
+except ApprovalDenied:
+    log.warning("refund rejected by operator")
+```
+
+`summary` may be a static string or a callable receiving the wrapped function's
+arguments. Omit it for a sensible default built from the action and function name.
+Pass `client=Sesame(...)` to use a specific client; otherwise a module-level default
+is built lazily from the environment.
+
+## Trigger and wait explicitly
+
+```python
+from sesame_sdk import Sesame
+
+client = Sesame()
+approval = client.approvals.trigger(
+    action="db.delete",
+    summary="Delete 1,204 rows from prod.orders",
+    reason="GDPR erasure request #882",
+    context={"table": "orders", "rows": 1204},
+)
+
+approval.wait(timeout=300)   # blocks on the broker's long-poll until decided
+if approval.approved:
+    run_deletion()
+else:
+    print("decision:", approval.status)  # "denied" or "expired"
+```
+
+## Receive decisions via webhook
+
+When you pass a `callback_url`, the broker POSTs to it on every terminal decision.
+Verify the signature before trusting the body — `verify_webhook` recomputes the
+HMAC-SHA256 over the *raw* request body and rejects stale timestamps.
+
+### Flask
+
+```python
+from flask import Flask, request, abort
+from sesame_sdk import verify_webhook, WebhookVerificationError
+
+app = Flask(__name__)
+WEBHOOK_SECRET = os.environ["SESAME_WEBHOOK_SECRET"]
+
+@app.post("/sesame/webhook")
+def sesame_webhook():
+    try:
+        payload = verify_webhook(request.headers, request.get_data(), WEBHOOK_SECRET)
+    except WebhookVerificationError:
+        abort(400)
+    # payload: {"approval_id", "action", "status", "decided_at", "requester_label", "dedup_key"?}
+    handle_decision(payload["approval_id"], payload["status"])
+    return "", 204
+```
+
+### FastAPI
+
+```python
+from fastapi import FastAPI, Request, Response, HTTPException
+from sesame_sdk import verify_webhook, WebhookVerificationError
+
+app = FastAPI()
+
+@app.post("/sesame/webhook")
+async def sesame_webhook(request: Request):
+    raw = await request.body()  # must be the exact bytes the broker signed
+    try:
+        payload = verify_webhook(request.headers, raw, WEBHOOK_SECRET)
+    except WebhookVerificationError:
+        raise HTTPException(status_code=400, detail="bad signature")
+    handle_decision(payload["approval_id"], payload["status"])
+    return Response(status_code=204)
+```
+
+## Exceptions
+
+All inherit from `ApprovalError`:
+
+- `ApprovalDenied` — terminal `denied`/`expired` (carries `.approval_id`, `.status`)
+- `ApprovalTimeout` — no decision before the caller's timeout
+- `SesameAuthError` — broker rejected the API key (HTTP 401)
+- `NotFoundError` — unknown approval id (HTTP 404)
+- `WebhookVerificationError` — bad/missing signature, stale timestamp, or bad JSON
+
+## Notes
+
+This SDK is synchronous for v1. An async client may be added later; until then, run
+`approval.wait()` in a worker thread if you need to avoid blocking an event loop.

sesame_sdk-0.1.0/PUBLISHING.md

@@ -0,0 +1,63 @@
+# Publishing `sesame-sdk` to PyPI
+
+> These steps are documented but **not run automatically**. Publishing requires a
+> PyPI API token and explicit sign-off from a maintainer.
+
+## Prerequisites
+
+- [ ] **A license has been chosen.** No `LICENSE` file currently exists in the repo.
+      A license is a product/legal decision and must be made before the first public
+      release. Once chosen: add the `LICENSE` file to this package, restore the
+      `license` field in `pyproject.toml`, and add the matching `License ::` trove
+      classifier.
+- [ ] `version` in `pyproject.toml` bumped (PyPI rejects re-uploading an existing version).
+- [ ] A PyPI account with an API token (`pypi-...`). Store it securely; never commit it.
+
+## 1. Build the artifacts
+
+```bash
+uv build
+```
+
+This produces both distributions in `dist/`:
+
+- `dist/sesame_sdk-<version>-py3-none-any.whl`
+- `dist/sesame_sdk-<version>.tar.gz`
+
+## 2. (Recommended) Verify the build
+
+```bash
+uvx twine check dist/*
+```
+
+## 3. Publish
+
+Using uv (preferred):
+
+```bash
+# Requires PyPI token — pass via env or --token. Do NOT commit the token.
+UV_PUBLISH_TOKEN="pypi-..." uv publish
+```
+
+Or with twine:
+
+```bash
+twine upload dist/*    # prompts for username (__token__) + password (the pypi-... token)
+```
+
+Optionally test against TestPyPI first:
+
+```bash
+UV_PUBLISH_TOKEN="pypi-..." uv publish --publish-url https://test.pypi.org/legacy/
+```
+
+## 4. Verify the published package
+
+```bash
+pip install sesame-sdk
+python -c "import sesame_sdk; print(sesame_sdk.__version__)"
+```
+
+---
+
+**Do not run the publish command without explicit maintainer sign-off and a chosen license.**

sesame_sdk-0.1.0/README.md

@@ -0,0 +1,136 @@
+# sesame-sdk
+
+Python SDK for the [Sesame](https://getsesame.dev) human-in-the-loop approval API.
+
+Drop an approval gate in front of any sensitive operation in your backend. Sesame
+triggers a request that a human approves (via Telegram + push), and your code blocks
+until the decision lands — or reacts asynchronously via a webhook.
+
+```bash
+pip install sesame-sdk
+```
+
+Requires Python 3.12+. Runtime deps: `httpx`, `pydantic`.
+
+## Configuration
+
+The client reads credentials from the environment, or you can pass them explicitly:
+
+| Env var             | Default                  | Purpose                          |
+| ------------------- | ------------------------ | -------------------------------- |
+| `SESAME_API_KEY`    | _(required)_             | `sk_live_...` API key            |
+| `SESAME_BROKER_URL` | `http://localhost:8000`  | Broker base URL                  |
+
+```python
+from sesame_sdk import Sesame
+
+client = Sesame()                                  # from env
+client = Sesame(api_key="sk_live_...", base_url="https://broker.example.com")
+```
+
+## Gate a function with `@require_approval`
+
+The wrapped function only runs if a human approves. Denied/expired raises
+`ApprovalDenied`; no decision before `timeout` raises `ApprovalTimeout`.
+
+```python
+from sesame_sdk import require_approval, ApprovalDenied
+
+@require_approval(
+    "payments.refund",
+    summary=lambda amount, **_: f"Refund ${amount/100:.2f} to customer",
+    timeout=300,
+)
+def issue_refund(amount: int, customer_id: str) -> None:
+    stripe.Refund.create(amount=amount, customer=customer_id)
+
+try:
+    issue_refund(4200, customer_id="cus_123")
+except ApprovalDenied:
+    log.warning("refund rejected by operator")
+```
+
+`summary` may be a static string or a callable receiving the wrapped function's
+arguments. Omit it for a sensible default built from the action and function name.
+Pass `client=Sesame(...)` to use a specific client; otherwise a module-level default
+is built lazily from the environment.
+
+## Trigger and wait explicitly
+
+```python
+from sesame_sdk import Sesame
+
+client = Sesame()
+approval = client.approvals.trigger(
+    action="db.delete",
+    summary="Delete 1,204 rows from prod.orders",
+    reason="GDPR erasure request #882",
+    context={"table": "orders", "rows": 1204},
+)
+
+approval.wait(timeout=300)   # blocks on the broker's long-poll until decided
+if approval.approved:
+    run_deletion()
+else:
+    print("decision:", approval.status)  # "denied" or "expired"
+```
+
+## Receive decisions via webhook
+
+When you pass a `callback_url`, the broker POSTs to it on every terminal decision.
+Verify the signature before trusting the body — `verify_webhook` recomputes the
+HMAC-SHA256 over the *raw* request body and rejects stale timestamps.
+
+### Flask
+
+```python
+from flask import Flask, request, abort
+from sesame_sdk import verify_webhook, WebhookVerificationError
+
+app = Flask(__name__)
+WEBHOOK_SECRET = os.environ["SESAME_WEBHOOK_SECRET"]
+
+@app.post("/sesame/webhook")
+def sesame_webhook():
+    try:
+        payload = verify_webhook(request.headers, request.get_data(), WEBHOOK_SECRET)
+    except WebhookVerificationError:
+        abort(400)
+    # payload: {"approval_id", "action", "status", "decided_at", "requester_label", "dedup_key"?}
+    handle_decision(payload["approval_id"], payload["status"])
+    return "", 204
+```
+
+### FastAPI
+
+```python
+from fastapi import FastAPI, Request, Response, HTTPException
+from sesame_sdk import verify_webhook, WebhookVerificationError
+
+app = FastAPI()
+
+@app.post("/sesame/webhook")
+async def sesame_webhook(request: Request):
+    raw = await request.body()  # must be the exact bytes the broker signed
+    try:
+        payload = verify_webhook(request.headers, raw, WEBHOOK_SECRET)
+    except WebhookVerificationError:
+        raise HTTPException(status_code=400, detail="bad signature")
+    handle_decision(payload["approval_id"], payload["status"])
+    return Response(status_code=204)
+```
+
+## Exceptions
+
+All inherit from `ApprovalError`:
+
+- `ApprovalDenied` — terminal `denied`/`expired` (carries `.approval_id`, `.status`)
+- `ApprovalTimeout` — no decision before the caller's timeout
+- `SesameAuthError` — broker rejected the API key (HTTP 401)
+- `NotFoundError` — unknown approval id (HTTP 404)
+- `WebhookVerificationError` — bad/missing signature, stale timestamp, or bad JSON
+
+## Notes
+
+This SDK is synchronous for v1. An async client may be added later; until then, run
+`approval.wait()` in a worker thread if you need to avoid blocking an event loop.

sesame_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[project]
+name = "sesame-sdk"
+version = "0.1.0"
+description = "Python SDK for the Sesame human-in-the-loop approval API"
+readme = "README.md"
+requires-python = ">=3.12"
+authors = [{ name = "Sesame" }]
+keywords = [
+    "sesame",
+    "approval",
+    "human-in-the-loop",
+    "webhook",
+    "authorization",
+    "agents",
+]
+license = { text = "MIT" }
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: MIT License",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Security",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.6",
+]
+
+[project.urls]
+Homepage = "https://github.com/lavanpuri1999/sesame"
+Repository = "https://github.com/lavanpuri1999/sesame"
+Issues = "https://github.com/lavanpuri1999/sesame/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "respx>=0.21",
+    "ruff>=0.4",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sesame_sdk"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/sesame_sdk",
+    "README.md",
+    "PUBLISHING.md",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

sesame_sdk-0.1.0/src/sesame_sdk/__init__.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from .approval import Approval
+from .client import Sesame
+from .decorator import require_approval
+from .exceptions import (
+    ApprovalDenied,
+    ApprovalError,
+    ApprovalTimeout,
+    NotFoundError,
+    SesameAuthError,
+    WebhookVerificationError,
+)
+from .models import ApprovalState, TriggerResponse, WebhookPayload
+from .webhook import verify_webhook
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Sesame",
+    "Approval",
+    "require_approval",
+    "verify_webhook",
+    "ApprovalError",
+    "ApprovalDenied",
+    "ApprovalTimeout",
+    "WebhookVerificationError",
+    "SesameAuthError",
+    "NotFoundError",
+    "ApprovalState",
+    "TriggerResponse",
+    "WebhookPayload",
+    "__version__",
+]

sesame_sdk-0.1.0/src/sesame_sdk/approval.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import time
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from .exceptions import ApprovalTimeout
+from .models import TERMINAL_STATUSES, ApprovalState, TriggerResponse
+
+if TYPE_CHECKING:
+    from .approvals import Approvals
+
+
+class Approval:
+    """A single approval request, with helpers to block until it is decided."""
+
+    def __init__(
+        self,
+        approval_id: str,
+        status: str,
+        approvals: Approvals,
+        expires_at: datetime | None = None,
+    ) -> None:
+        self.approval_id = approval_id
+        self.status = status
+        self.expires_at = expires_at
+        self._approvals = approvals
+
+    @classmethod
+    def _from_trigger(cls, data: TriggerResponse, approvals: Approvals) -> Approval:
+        return cls(data.approval_id, data.status, approvals)
+
+    def _apply(self, state: ApprovalState) -> None:
+        self.status = state.status
+        self.expires_at = state.expires_at
+
+    @property
+    def approved(self) -> bool:
+        return self.status == "approved"
+
+    @property
+    def is_terminal(self) -> bool:
+        return self.status in TERMINAL_STATUSES
+
+    def refresh(self, *, wait: bool = False) -> Approval:
+        """Fetch current state from the broker. `wait=True` long-polls server-side."""
+        self._apply(self._approvals._get(self.approval_id, wait=wait))
+        return self
+
+    def wait(self, timeout: float = 300.0, poll_interval: float = 2.0) -> Approval:
+        """Block until the approval reaches a terminal state or `timeout` seconds elapse.
+
+        The broker's `?wait=true` already long-polls (~25-30s), so each iteration mostly
+        re-issues that long-poll; `poll_interval` is only a floor between cheap returns
+        (e.g. an immediate "still pending") to avoid hammering the broker.
+        """
+        deadline = time.monotonic() + timeout
+        while True:
+            if self.is_terminal:
+                return self
+            if time.monotonic() >= deadline:
+                raise ApprovalTimeout(
+                    f"Approval {self.approval_id} not decided within {timeout}s (status={self.status})",
+                    approval_id=self.approval_id,
+                )
+            started = time.monotonic()
+            self.refresh(wait=True)
+            if self.is_terminal:
+                return self
+            # Floor the loop only if the long-poll returned faster than poll_interval.
+            elapsed = time.monotonic() - started
+            remaining = min(poll_interval - elapsed, deadline - time.monotonic())
+            if remaining > 0:
+                time.sleep(remaining)
+
+    def __repr__(self) -> str:
+        return f"Approval(approval_id={self.approval_id!r}, status={self.status!r})"

sesame_sdk-0.1.0/src/sesame_sdk/approvals.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .approval import Approval
+from .models import ApprovalState, TriggerResponse
+from .transport import Transport
+
+
+class Approvals:
+    """Resource handle for the /v1/approvals endpoints."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._transport = transport
+
+    def trigger(
+        self,
+        action: str,
+        summary: str,
+        *,
+        reason: str | None = None,
+        dedup_key: str | None = None,
+        callback_url: str | None = None,
+        severity: str | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> Approval:
+        """Request a human approval. Returns immediately with a pending Approval."""
+        body: dict[str, Any] = {"action": action, "summary": summary}
+        optional = {
+            "reason": reason,
+            "dedup_key": dedup_key,
+            "callback_url": callback_url,
+            "severity": severity,
+            "context": context,
+        }
+        body.update({k: v for k, v in optional.items() if v is not None})
+
+        data = self._transport.request("POST", "/v1/approvals", json=body)
+        return Approval._from_trigger(TriggerResponse.model_validate(data), self)
+
+    def get(self, approval_id: str, *, wait: bool = False) -> Approval:
+        """Fetch the current state of an approval as an Approval object."""
+        state = self._get(approval_id, wait=wait)
+        return Approval(
+            state.approval_id, state.status, self, expires_at=state.expires_at
+        )
+
+    def _get(self, approval_id: str, *, wait: bool) -> ApprovalState:
+        params = {"wait": "true"} if wait else None
+        data = self._transport.request(
+            "GET", f"/v1/approvals/{approval_id}", params=params
+        )
+        return ApprovalState.model_validate(data)

sesame_sdk-0.1.0/src/sesame_sdk/client.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import os
+
+from .approvals import Approvals
+from .transport import Transport
+
+DEFAULT_BASE_URL = "http://localhost:8000"
+
+
+class Sesame:
+    """Client for the Sesame human-in-the-loop approval API.
+
+    api_key falls back to $SESAME_API_KEY, base_url to $SESAME_BROKER_URL (then localhost).
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        api_key = api_key or os.environ.get("SESAME_API_KEY")
+        if not api_key:
+            raise ValueError(
+                "No Sesame API key provided. Pass api_key=... or set the SESAME_API_KEY environment variable."
+            )
+        base_url = base_url or os.environ.get("SESAME_BROKER_URL") or DEFAULT_BASE_URL
+
+        self._transport = Transport(base_url=base_url, api_key=api_key, timeout=timeout)
+        self.approvals = Approvals(self._transport)
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> Sesame:
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()

sesame_sdk-0.1.0/src/sesame_sdk/decorator.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import functools
+from typing import Any, Callable, TypeVar
+
+from .client import Sesame
+from .exceptions import ApprovalDenied
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+# Lazily-built module-level client, shared by decorators that don't pass their own.
+_default_client: Sesame | None = None
+
+
+def _get_default_client() -> Sesame:
+    global _default_client
+    if _default_client is None:
+        _default_client = Sesame()
+    return _default_client
+
+
+def require_approval(
+    action: str,
+    *,
+    summary: str | Callable[..., str] | None = None,
+    reason: str | None = None,
+    timeout: float = 300.0,
+    client: Sesame | None = None,
+) -> Callable[[F], F]:
+    """Gate a sync function behind a human approval.
+
+    Before each call the wrapped function triggers an approval and blocks until decided.
+    Denied/expired -> ApprovalDenied; no decision in time -> ApprovalTimeout (from wait()).
+    `summary` may be a static string or a callable receiving the same (*args, **kwargs).
+    """
+
+    def decorator(func: F) -> F:
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            active = client or _get_default_client()
+
+            if callable(summary):
+                resolved_summary = summary(*args, **kwargs)
+            elif summary is not None:
+                resolved_summary = summary
+            else:
+                resolved_summary = (
+                    f"Approval required for {action} (via {func.__name__})"
+                )
+
+            approval = active.approvals.trigger(
+                action,
+                resolved_summary,
+                reason=reason,
+            )
+            approval.wait(timeout=timeout)
+            if not approval.approved:
+                raise ApprovalDenied(
+                    f"Approval for {action!r} was {approval.status}",
+                    approval_id=approval.approval_id,
+                    status=approval.status,
+                )
+            return func(*args, **kwargs)
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator

sesame_sdk-0.1.0/src/sesame_sdk/exceptions.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+
+class ApprovalError(Exception):
+    """Base class for all Sesame SDK errors."""
+
+
+class SesameAuthError(ApprovalError):
+    """Raised when the broker rejects the API key (HTTP 401)."""
+
+
+class NotFoundError(ApprovalError):
+    """Raised when an approval id is unknown to the broker (HTTP 404)."""
+
+
+class ApprovalDenied(ApprovalError):
+    """Raised when an approval reached a terminal non-approved state (denied/expired)."""
+
+    def __init__(
+        self, message: str, *, approval_id: str | None = None, status: str | None = None
+    ) -> None:
+        super().__init__(message)
+        self.approval_id = approval_id
+        self.status = status
+
+
+class ApprovalTimeout(ApprovalError):
+    """Raised when waiting for a decision exceeded the caller's timeout."""
+
+    def __init__(self, message: str, *, approval_id: str | None = None) -> None:
+        super().__init__(message)
+        self.approval_id = approval_id
+
+
+class WebhookVerificationError(ApprovalError):
+    """Raised when a webhook signature/timestamp fails verification."""

sesame_sdk-0.1.0/src/sesame_sdk/models.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict
+
+# Terminal states: no further decision can change them.
+TERMINAL_STATUSES = frozenset({"approved", "denied", "expired"})
+
+
+class TriggerResponse(BaseModel):
+    """Response body from POST /v1/approvals (202)."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    approval_id: str
+    status: str
+
+
+class ApprovalState(BaseModel):
+    """Response body from GET /v1/approvals/{id} (200)."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    approval_id: str
+    status: str
+    expires_at: datetime | None = None
+
+
+class WebhookPayload(BaseModel):
+    """Body the broker POSTs to a caller's callback_url on a terminal decision."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    approval_id: str
+    action: str
+    status: str
+    decided_at: datetime
+    requester_label: str | None = None
+    dedup_key: str | None = None

sesame_sdk-0.1.0/src/sesame_sdk/transport.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from .exceptions import ApprovalError, NotFoundError, SesameAuthError
+
+
+def _detail(response: httpx.Response) -> str:
+    """Pull the broker's `{"detail": ...}` message, falling back to raw text."""
+    try:
+        body = response.json()
+    except ValueError:
+        return response.text or response.reason_phrase
+    if isinstance(body, dict) and "detail" in body:
+        return str(body["detail"])
+    return response.text or response.reason_phrase
+
+
+class Transport:
+    """Thin httpx.Client wrapper that sets auth once and maps errors to SDK exceptions."""
+
+    def __init__(self, base_url: str, api_key: str, timeout: float) -> None:
+        self._client = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=timeout,
+        )
+
+    def request(self, method: str, path: str, **kwargs: Any) -> dict[str, Any]:
+        response = self._client.request(method, path, **kwargs)
+        return self._handle(response)
+
+    def _handle(self, response: httpx.Response) -> dict[str, Any]:
+        if response.is_success:
+            return response.json()
+        if response.status_code == 401:
+            raise SesameAuthError(_detail(response))
+        if response.status_code == 404:
+            raise NotFoundError(_detail(response))
+        raise ApprovalError(
+            f"Sesame request failed ({response.status_code}): {_detail(response)}"
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> Transport:
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()

sesame_sdk-0.1.0/src/sesame_sdk/webhook.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from typing import Any, Mapping
+
+from .exceptions import WebhookVerificationError
+
+SIGNATURE_HEADER = "X-Sesame-Signature"
+TIMESTAMP_HEADER = "X-Sesame-Timestamp"
+
+
+def _get_header(headers: Mapping[str, str], name: str) -> str | None:
+    # HTTP header lookups are case-insensitive; callers may hand us a plain dict.
+    target = name.lower()
+    for key, value in headers.items():
+        if key.lower() == target:
+            return value
+    return None
+
+
+def verify_webhook(
+    headers: Mapping[str, str],
+    body: bytes | str,
+    secret: str,
+    *,
+    tolerance: int = 300,
+) -> dict[str, Any]:
+    """Verify a Sesame webhook and return its parsed JSON payload.
+
+    Recomputes HMAC-SHA256 over the *exact* raw body and constant-time compares it to
+    X-Sesame-Signature; rejects bodies whose X-Sesame-Timestamp is older than `tolerance`
+    seconds. Raises WebhookVerificationError on any failure.
+    """
+    raw = body.encode("utf-8") if isinstance(body, str) else body
+
+    signature = _get_header(headers, SIGNATURE_HEADER)
+    if not signature:
+        raise WebhookVerificationError(f"Missing {SIGNATURE_HEADER} header")
+
+    timestamp = _get_header(headers, TIMESTAMP_HEADER)
+    if not timestamp:
+        raise WebhookVerificationError(f"Missing {TIMESTAMP_HEADER} header")
+    try:
+        ts = int(timestamp)
+    except ValueError as exc:
+        raise WebhookVerificationError(f"Invalid {TIMESTAMP_HEADER} header") from exc
+    if abs(time.time() - ts) > tolerance:
+        raise WebhookVerificationError("Webhook timestamp outside tolerance window")
+
+    expected = hmac.new(secret.encode("utf-8"), raw, hashlib.sha256).hexdigest()
+    if not hmac.compare_digest(expected, signature):
+        raise WebhookVerificationError("Webhook signature mismatch")
+
+    try:
+        return json.loads(raw)
+    except ValueError as exc:
+        raise WebhookVerificationError("Webhook body is not valid JSON") from exc