permitly 0.1.0__tar.gz

permitly-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+*.log
+.superpowers/
+.DS_Store
+.env
+.env.backup
+.env.production
+.phpactor.json
+.phpunit.result.cache
+/.cursor/
+/.idea
+/.nova
+/.phpunit.cache
+/.vscode
+/.zed
+/auth.json
+/node_modules
+# /public/build
+/public/hot
+/public/storage
+/storage/*.key
+/storage/pail
+/vendor
+_ide_helper.php
+Homestead.json
+Homestead.yaml
+Thumbs.db
+.gstack/
+/.worktrees

permitly-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: permitly
+Version: 0.1.0
+Summary: Python SDK for Permitly — consent and delegation for AI agents
+License-Expression: MIT
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21.0; extra == 'dev'

permitly-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "permitly"
+version = "0.1.0"
+description = "Python SDK for Permitly — consent and delegation for AI agents"
+license = "MIT"
+requires-python = ">=3.9"
+dependencies = ["httpx>=0.27.0"]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "respx>=0.21.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/permitly"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

permitly-0.1.0/src/permitly/__init__.py

@@ -0,0 +1,18 @@
+from .client import PermitlyClient
+from .exceptions import AuthError, PermitlyError, UsageLimitError, ValidationError
+from .models import AuditEvent, ConsentRequest, PageResult
+from .scope_templates import ScopeTemplates
+from .webhook import verify_signature
+
+__all__ = [
+    "PermitlyClient",
+    "PermitlyError",
+    "AuthError",
+    "ValidationError",
+    "UsageLimitError",
+    "ScopeTemplates",
+    "verify_signature",
+    "AuditEvent",
+    "ConsentRequest",
+    "PageResult",
+]

permitly-0.1.0/src/permitly/client.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import types
+from typing import Optional, Type
+
+import httpx
+
+from .exceptions import AuthError, PermitlyError, UsageLimitError, ValidationError
+
+
+class PermitlyClient:
+    """Synchronous HTTP client for the Permitly API."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://permitly.dev",
+        timeout: int = 30,
+    ) -> None:
+        from .resources.consent import ConsentResource
+        from .resources.audit import AuditResource
+
+        self._http = httpx.Client(
+            base_url=base_url,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            },
+            timeout=timeout,
+        )
+        self.consent = ConsentResource(self)
+        self.audit = AuditResource(self)
+
+    def _request(self, method: str, path: str, **kwargs) -> dict:
+        """Execute an HTTP request and return the parsed JSON body.
+
+        Raises a typed exception for any non-2xx response.
+        """
+        response = self._http.request(method, path, **kwargs)
+        self._raise_for_status(response)
+        return response.json()
+
+    def _raise_for_status(self, response: httpx.Response) -> None:
+        """Translate HTTP error responses into typed SDK exceptions."""
+        if response.is_success:
+            return
+
+        try:
+            body = response.json()
+            error = body.get("error", {})
+            code = error.get("code", "unknown_error")
+            message = error.get("message", response.text)
+            errors = error.get("errors")
+        except Exception:
+            code = "unknown_error"
+            message = response.text
+            errors = None
+
+        if response.status_code == 401:
+            raise AuthError(message, code=code, status_code=401)
+        elif response.status_code == 422:
+            raise ValidationError(message, code=code, status_code=422, errors=errors)
+        elif response.status_code == 429:
+            raise UsageLimitError(message, code=code, status_code=429)
+        else:
+            raise PermitlyError(message, code=code, status_code=response.status_code)
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        self._http.close()
+
+    def __enter__(self) -> PermitlyClient:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc_val: Optional[BaseException],
+        exc_tb: Optional[types.TracebackType],
+    ) -> None:
+        self.close()

permitly-0.1.0/src/permitly/exceptions.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from typing import Optional
+
+
+class PermitlyError(Exception):
+    def __init__(self, message: str, *, code: str = "unknown_error", status_code: int = 0):
+        super().__init__(message)
+        self.code = code
+        self.status_code = status_code
+
+
+class AuthError(PermitlyError):
+    """Raised on 401 — invalid or missing API key."""
+
+
+class ValidationError(PermitlyError):
+    """Raised on 422 — request payload failed server-side validation."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str = "validation_error",
+        status_code: int = 422,
+        errors: Optional[dict] = None,
+    ):
+        super().__init__(message, code=code, status_code=status_code)
+        self.errors = errors or {}
+
+
+class UsageLimitError(PermitlyError):
+    """Raised on 429 — monthly consent request limit reached."""

permitly-0.1.0/src/permitly/models.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class ConsentRequest:
+    id: str
+    status: str
+    consent_url: Optional[str] = None
+    end_user_ref: Optional[str] = None
+    scopes: Optional[list] = None
+    created_at: Optional[str] = None
+    decided_at: Optional[str] = None
+    expires_at: Optional[str] = None
+
+
+@dataclass
+class AuditEvent:
+    id: str
+    event_type: str
+    actor: Optional[str] = None
+    consent_id: Optional[str] = None
+    created_at: Optional[str] = None
+
+
+@dataclass
+class PageResult:
+    data: list
+    cursor: Optional[str]
+    has_more: bool
+
+
+def _parse_consent(data: dict) -> ConsentRequest:
+    return ConsentRequest(
+        id=data["id"],
+        status=data["status"],
+        consent_url=data.get("consent_url"),
+        end_user_ref=data.get("end_user_ref"),
+        scopes=data.get("scopes"),
+        created_at=data.get("created_at"),
+        decided_at=data.get("decided_at"),
+        expires_at=data.get("expires_at"),
+    )
+
+
+def _parse_audit_event(data: dict) -> AuditEvent:
+    return AuditEvent(
+        id=data["id"],
+        event_type=data["event_type"],
+        actor=data.get("actor"),
+        consent_id=data.get("consent_id"),
+        created_at=data.get("created_at"),
+    )

permitly-0.1.0/src/permitly/resources/audit.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Optional
+
+from ..models import AuditEvent, PageResult, _parse_audit_event
+
+if TYPE_CHECKING:
+    from ..client import PermitlyClient
+
+
+class AuditResource:
+    """Provides access to audit log operations."""
+
+    def __init__(self, client: "PermitlyClient") -> None:
+        self._client = client
+
+    def list(
+        self,
+        *,
+        consent_id: Optional[str] = None,
+        event_type: Optional[str] = None,
+        limit: int = 20,
+        cursor: Optional[str] = None,
+    ) -> PageResult:
+        """List audit events with optional filtering and pagination.
+
+        Args:
+            consent_id: Filter to events for a specific consent request.
+            event_type: Filter by event type (e.g., 'approved', 'declined', 'revoked').
+            limit: Maximum number of results to return (default 20).
+            cursor: Pagination cursor from a previous response.
+
+        Returns:
+            A PageResult containing a list of AuditEvents plus pagination info.
+        """
+        params: dict = {"limit": limit}
+        if consent_id is not None:
+            params["consent_id"] = consent_id
+        if event_type is not None:
+            params["event_type"] = event_type
+        if cursor is not None:
+            params["cursor"] = cursor
+
+        body = self._client._request("GET", "/v1/audit", params=params)
+        return PageResult(
+            data=[_parse_audit_event(item) for item in body["data"]],
+            cursor=body["meta"]["cursor"],
+            has_more=body["meta"]["has_more"],
+        )

permitly-0.1.0/src/permitly/resources/consent.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Optional
+
+from ..models import ConsentRequest, PageResult, _parse_consent
+
+if TYPE_CHECKING:
+    from ..client import PermitlyClient
+
+
+class ConsentResource:
+    """Provides access to consent-request lifecycle operations."""
+
+    def __init__(self, client: PermitlyClient) -> None:
+        self._client = client
+
+    def request(
+        self,
+        end_user_ref: str,
+        scopes: list[dict],
+        redirect_url: str,
+        *,
+        end_user_email: Optional[str] = None,
+        expires_in: Optional[int] = None,
+        metadata: Optional[dict[str, Any]] = None,
+    ) -> ConsentRequest:
+        """Create a new consent request and return the hosted consent URL.
+
+        Args:
+            end_user_ref: Stable identifier for the end user in the builder's system.
+            scopes: List of scope dicts to request approval for.
+            redirect_url: URL the consent page redirects to after a decision.
+            end_user_email: Optional email shown on the consent page.
+            expires_in: Optional TTL in seconds before the request auto-expires.
+            metadata: Optional freeform dict stored alongside the request.
+
+        Returns:
+            A ConsentRequest with id, status, consent_url, and expires_at populated.
+        """
+        payload: dict = {
+            "end_user_ref": end_user_ref,
+            "scopes": scopes,
+            "redirect_url": redirect_url,
+        }
+        if end_user_email is not None:
+            payload["end_user_email"] = end_user_email
+        if expires_in is not None:
+            payload["expires_in"] = expires_in
+        if metadata is not None:
+            payload["metadata"] = metadata
+
+        body = self._client._request("POST", "/v1/consent/request", json=payload)
+        return _parse_consent(body["data"])
+
+    def get(self, id: str) -> ConsentRequest:
+        """Retrieve a consent request by ID.
+
+        Args:
+            id: The consent request UUID.
+
+        Returns:
+            The full ConsentRequest including scopes and decision timestamps.
+        """
+        body = self._client._request("GET", f"/v1/consent/{id}")
+        return _parse_consent(body["data"])
+
+    def verify(self, token: str) -> dict[str, Any]:
+        """Verify a consent JWT and return its decoded claims.
+
+        Args:
+            token: The signed JWT returned to the agent after consent was approved.
+
+        Returns:
+            Dict of JWT claims: sub, agt, cid, scopes, iat, exp, jti.
+        """
+        body = self._client._request("POST", "/v1/consent/verify", json={"token": token})
+        return body["data"]
+
+    def revoke(self, id: str) -> ConsentRequest:
+        """Revoke an existing consent request.
+
+        Args:
+            id: The consent request UUID to revoke.
+
+        Returns:
+            The updated ConsentRequest with status set to 'revoked'.
+        """
+        body = self._client._request("DELETE", f"/v1/consent/{id}")
+        return _parse_consent(body["data"])
+
+    def list(
+        self,
+        *,
+        status: Optional[str] = None,
+        end_user_ref: Optional[str] = None,
+        limit: int = 20,
+        cursor: Optional[str] = None,
+    ) -> PageResult:
+        """List consent requests with optional filtering and pagination.
+
+        Args:
+            status: Filter by status ('pending', 'approved', 'declined', 'revoked', 'expired').
+            end_user_ref: Filter to requests for a specific end user.
+            limit: Maximum number of results to return (default 20).
+            cursor: Pagination cursor from a previous response.
+
+        Returns:
+            A PageResult containing a list of ConsentRequests plus pagination info.
+        """
+        params: dict = {"limit": limit}
+        if status is not None:
+            params["status"] = status
+        if end_user_ref is not None:
+            params["end_user_ref"] = end_user_ref
+        if cursor is not None:
+            params["cursor"] = cursor
+
+        body = self._client._request("GET", "/v1/consent", params=params)
+        return PageResult(
+            data=[_parse_consent(item) for item in body["data"]],
+            cursor=body["meta"]["cursor"],
+            has_more=body["meta"]["has_more"],
+        )
+
+    def manage_url(self, end_user_ref: str) -> str:
+        """Get a signed URL for the end-user's self-service consent management page.
+
+        Args:
+            end_user_ref: The end user's stable identifier.
+
+        Returns:
+            A signed, time-limited URL the builder can redirect the end user to.
+        """
+        body = self._client._request(
+            "GET", "/v1/consent/manage-url", params={"end_user_ref": end_user_ref}
+        )
+        return body["data"]["url"]

permitly-0.1.0/src/permitly/scope_templates.py

@@ -0,0 +1,73 @@
+class ScopeTemplates:
+    """Pre-built scope templates for common permissions."""
+
+    SEND_EMAIL = {
+        "key": "send_email",
+        "label": "Send Emails",
+        "description": "Send emails on your behalf",
+        "reversible": True,
+        "risk_level": "medium",
+    }
+    READ_EMAIL = {
+        "key": "read_email",
+        "label": "Read Emails",
+        "description": "Read your email inbox and messages",
+        "reversible": True,
+        "risk_level": "medium",
+    }
+    READ_CALENDAR = {
+        "key": "read_calendar",
+        "label": "Read Calendar",
+        "description": "View your calendar events and availability",
+        "reversible": True,
+        "risk_level": "low",
+    }
+    WRITE_CALENDAR = {
+        "key": "write_calendar",
+        "label": "Modify Calendar",
+        "description": "Create and modify calendar events",
+        "reversible": True,
+        "risk_level": "medium",
+    }
+    BOOK_APPOINTMENT = {
+        "key": "book_appointment",
+        "label": "Book Appointments",
+        "description": "Schedule appointments and meetings on your behalf",
+        "reversible": True,
+        "risk_level": "medium",
+    }
+    SEND_MESSAGE = {
+        "key": "send_message",
+        "label": "Send Messages",
+        "description": "Send messages and chat communications on your behalf",
+        "reversible": True,
+        "risk_level": "medium",
+    }
+    READ_FILES = {
+        "key": "read_files",
+        "label": "Read Files",
+        "description": "Read and access your files and documents",
+        "reversible": True,
+        "risk_level": "low",
+    }
+    WRITE_FILES = {
+        "key": "write_files",
+        "label": "Modify Files",
+        "description": "Create, edit, and delete your files and documents",
+        "reversible": False,
+        "risk_level": "high",
+    }
+    MAKE_PURCHASE = {
+        "key": "make_purchase",
+        "label": "Make Purchases",
+        "description": "Make purchases and payments using your saved payment methods",
+        "reversible": False,
+        "risk_level": "high",
+    }
+    SUBMIT_FORM = {
+        "key": "submit_form",
+        "label": "Submit Forms",
+        "description": "Submit forms, applications, and official documents on your behalf",
+        "reversible": False,
+        "risk_level": "high",
+    }

permitly-0.1.0/src/permitly/webhook.py

@@ -0,0 +1,27 @@
+import hashlib
+import hmac
+
+
+def verify_signature(payload: str, signature: str, secret: str) -> bool:
+    """Verify a Permitly webhook signature.
+
+    The signature header value is: sha256=<hmac_sha256_hex_of_payload>
+    Returns True if valid, False otherwise. Uses constant-time comparison.
+
+    Args:
+        payload: The raw request body as a string.
+        signature: The X-Permitly-Signature header value.
+        secret: The webhook secret for this agent.
+
+    Returns:
+        True if the signature is valid, False otherwise.
+    """
+    if not signature.startswith("sha256="):
+        return False
+    expected_digest = hmac.new(
+        secret.encode("utf-8"),
+        payload.encode("utf-8"),
+        hashlib.sha256,
+    ).hexdigest()
+    received_digest = signature[len("sha256=") :]
+    return hmac.compare_digest(expected_digest, received_digest)

permitly-0.1.0/tests/conftest.py

@@ -0,0 +1,11 @@
+import pytest
+import respx
+from permitly import PermitlyClient
+
+BASE_URL = "https://permitly.dev"
+API_KEY = "sk_live_testkey1234567890123456789012"
+
+
+@pytest.fixture
+def client():
+    return PermitlyClient(API_KEY, base_url=BASE_URL)

permitly-0.1.0/tests/test_audit.py

@@ -0,0 +1,75 @@
+import httpx
+import pytest
+import respx
+
+from permitly import PermitlyClient
+from permitly.models import AuditEvent, PageResult
+
+BASE_URL = "https://permitly.dev"
+
+EVENT = {
+    "id": "evt-uuid-001",
+    "event_type": "approved",
+    "actor": "user",
+    "consent_id": "cr-uuid-001",
+    "created_at": "2026-05-25T10:01:00+00:00",
+}
+
+
+@pytest.fixture
+def client():
+    return PermitlyClient("sk_live_testkey", base_url=BASE_URL)
+
+
+@respx.mock(base_url=BASE_URL)
+def test_audit_list_returns_page_result(respx_mock, client):
+    respx_mock.get("/v1/audit").mock(
+        return_value=httpx.Response(200, json={
+            "data": [EVENT],
+            "meta": {"cursor": None, "has_more": False},
+        })
+    )
+    result = client.audit.list()
+    assert isinstance(result, PageResult)
+    assert len(result.data) == 1
+    assert isinstance(result.data[0], AuditEvent)
+    assert result.data[0].event_type == "approved"
+    assert result.data[0].consent_id == "cr-uuid-001"
+    assert not result.has_more
+
+
+@respx.mock(base_url=BASE_URL)
+def test_audit_list_sends_filters(respx_mock, client):
+    route = respx_mock.get("/v1/audit").mock(
+        return_value=httpx.Response(200, json={"data": [], "meta": {"cursor": None, "has_more": False}})
+    )
+    client.audit.list(consent_id="cr-uuid-001", event_type="approved", limit=5)
+    params = dict(route.calls[0].request.url.params)
+    assert params["consent_id"] == "cr-uuid-001"
+    assert params["event_type"] == "approved"
+    assert params["limit"] == "5"
+
+
+@respx.mock(base_url=BASE_URL)
+def test_audit_list_passes_cursor(respx_mock, client):
+    route = respx_mock.get("/v1/audit").mock(
+        return_value=httpx.Response(200, json={
+            "data": [],
+            "meta": {"cursor": "bmV4dA==", "has_more": True},
+        })
+    )
+    result = client.audit.list(cursor="dGVzdA==")
+    params = dict(route.calls[0].request.url.params)
+    assert params["cursor"] == "dGVzdA=="
+    assert result.cursor == "bmV4dA=="
+    assert result.has_more
+
+
+@respx.mock(base_url=BASE_URL)
+def test_audit_list_returns_empty_page(respx_mock, client):
+    respx_mock.get("/v1/audit").mock(
+        return_value=httpx.Response(200, json={"data": [], "meta": {"cursor": None, "has_more": False}})
+    )
+    result = client.audit.list()
+    assert result.data == []
+    assert result.cursor is None

permitly-0.1.0/tests/test_client.py

@@ -0,0 +1,81 @@
+import httpx
+import pytest
+import respx
+
+from permitly import PermitlyClient
+from permitly.exceptions import AuthError, PermitlyError, UsageLimitError, ValidationError
+
+BASE_URL = "https://permitly.dev"
+
+
+@pytest.fixture
+def client():
+    return PermitlyClient("sk_live_testkey", base_url=BASE_URL)
+
+
+def test_client_sets_auth_header(client):
+    assert client._http.headers["authorization"] == "Bearer sk_live_testkey"
+
+
+def test_client_default_base_url():
+    c = PermitlyClient("sk_live_testkey")
+    assert str(c._http.base_url) == "https://permitly.dev"
+
+
+def test_client_exposes_consent_and_audit_resources(client):
+    from permitly.resources.consent import ConsentResource
+    from permitly.resources.audit import AuditResource
+    assert isinstance(client.consent, ConsentResource)
+    assert isinstance(client.audit, AuditResource)
+
+
+@respx.mock(base_url=BASE_URL)
+def test_raises_auth_error_on_401(respx_mock, client):
+    respx_mock.get("/v1/consent/fake-id").mock(
+        return_value=httpx.Response(401, json={"error": {"code": "invalid_api_key", "message": "Unauthorized."}})
+    )
+    with pytest.raises(AuthError) as exc_info:
+        client._request("GET", "/v1/consent/fake-id")
+    assert exc_info.value.status_code == 401
+    assert exc_info.value.code == "invalid_api_key"
+
+
+@respx.mock(base_url=BASE_URL)
+def test_raises_validation_error_on_422(respx_mock, client):
+    respx_mock.post("/v1/consent/request").mock(
+        return_value=httpx.Response(422, json={
+            "error": {
+                "code": "validation_error",
+                "message": "The given data was invalid.",
+                "errors": {"end_user_ref": ["The end user ref field is required."]}
+            }
+        })
+    )
+    with pytest.raises(ValidationError) as exc_info:
+        client._request("POST", "/v1/consent/request", json={})
+    assert exc_info.value.status_code == 422
+    assert "end_user_ref" in exc_info.value.errors
+
+
+@respx.mock(base_url=BASE_URL)
+def test_raises_usage_limit_error_on_429(respx_mock, client):
+    respx_mock.post("/v1/consent/request").mock(
+        return_value=httpx.Response(429, json={"error": {"code": "usage_limit_exceeded", "message": "Limit reached."}})
+    )
+    with pytest.raises(UsageLimitError) as exc_info:
+        client._request("POST", "/v1/consent/request", json={})
+    assert exc_info.value.status_code == 429
+
+
+@respx.mock(base_url=BASE_URL)
+def test_raises_generic_permitly_error_on_500(respx_mock, client):
+    respx_mock.get("/v1/consent/x").mock(return_value=httpx.Response(500, text="Server Error"))
+    with pytest.raises(PermitlyError) as exc_info:
+        client._request("GET", "/v1/consent/x")
+    assert exc_info.value.status_code == 500
+
+
+def test_client_context_manager():
+    with PermitlyClient("sk_live_testkey", base_url=BASE_URL) as c:
+        assert c._http is not None
+    assert c._http.is_closed

permitly-0.1.0/tests/test_consent.py

@@ -0,0 +1,223 @@
+import json
+
+import httpx
+import pytest
+import respx
+
+from permitly import PermitlyClient
+from permitly.exceptions import AuthError, ValidationError
+from permitly.models import ConsentRequest, PageResult
+
+BASE_URL = "https://permitly.dev"
+API_KEY = "sk_live_testkey"
+
+SCOPE = {
+    "key": "send_email",
+    "label": "Send Emails",
+    "description": "Send emails on your behalf",
+    "reversible": True,
+    "risk_level": "medium",
+}
+
+CONSENT_CREATED = {
+    "id": "cr-uuid-001",
+    "consent_url": "https://permitly.dev/c/cr-uuid-001",
+    "status": "pending",
+    "expires_at": "2026-05-26T10:00:00+00:00",
+}
+
+CONSENT_FULL = {
+    "id": "cr-uuid-001",
+    "end_user_ref": "user-42",
+    "status": "approved",
+    "scopes": [SCOPE],
+    "created_at": "2026-05-25T10:00:00+00:00",
+    "decided_at": "2026-05-25T10:01:00+00:00",
+    "expires_at": "2026-05-26T10:00:00+00:00",
+}
+
+
+@pytest.fixture
+def client():
+    return PermitlyClient(API_KEY, base_url=BASE_URL)
+
+
+# --- request() ---
+
+@respx.mock(base_url=BASE_URL)
+def test_consent_request_returns_consent_request(respx_mock, client):
+    respx_mock.post("/v1/consent/request").mock(
+        return_value=httpx.Response(201, json={"data": CONSENT_CREATED})
+    )
+    result = client.consent.request(
+        end_user_ref="user-42",
+        scopes=[SCOPE],
+        redirect_url="https://app.example.com/callback",
+    )
+    assert isinstance(result, ConsentRequest)
+    assert result.id == "cr-uuid-001"
+    assert result.status == "pending"
+    assert result.consent_url == "https://permitly.dev/c/cr-uuid-001"
+
+
+@respx.mock(base_url=BASE_URL)
+def test_consent_request_sends_correct_payload(respx_mock, client):
+    route = respx_mock.post("/v1/consent/request").mock(
+        return_value=httpx.Response(201, json={"data": CONSENT_CREATED})
+    )
+    client.consent.request(
+        end_user_ref="user-42",
+        scopes=[SCOPE],
+        redirect_url="https://app.example.com/callback",
+        expires_in=3600,
+    )
+    body = json.loads(route.calls[0].request.content)
+    assert body["end_user_ref"] == "user-42"
+    assert body["expires_in"] == 3600
+    assert body["scopes"] == [SCOPE]
+
+
+@respx.mock(base_url=BASE_URL)
+def test_consent_request_raises_validation_error(respx_mock, client):
+    respx_mock.post("/v1/consent/request").mock(
+        return_value=httpx.Response(422, json={
+            "error": {
+                "code": "validation_error",
+                "message": "The given data was invalid.",
+                "errors": {"scopes": ["The scopes field is required."]}
+            }
+        })
+    )
+    with pytest.raises(ValidationError) as exc_info:
+        client.consent.request(end_user_ref="u", scopes=[], redirect_url="https://x.com/cb")
+    assert "scopes" in exc_info.value.errors
+
+
+@respx.mock(base_url=BASE_URL)
+def test_consent_request_raises_auth_error(respx_mock, client):
+    respx_mock.post("/v1/consent/request").mock(
+        return_value=httpx.Response(401, json={"error": {"code": "invalid_api_key", "message": "Unauthorized."}})
+    )
+    with pytest.raises(AuthError):
+        client.consent.request(end_user_ref="u", scopes=[SCOPE], redirect_url="https://x.com/cb")
+
+
+# --- get() ---
+
+@respx.mock(base_url=BASE_URL)
+def test_consent_get_returns_full_consent_request(respx_mock, client):
+    respx_mock.get("/v1/consent/cr-uuid-001").mock(
+        return_value=httpx.Response(200, json={"data": CONSENT_FULL})
+    )
+    result = client.consent.get("cr-uuid-001")
+    assert isinstance(result, ConsentRequest)
+    assert result.end_user_ref == "user-42"
+    assert result.status == "approved"
+    assert len(result.scopes) == 1
+
+
+# --- verify() ---
+
+@respx.mock(base_url=BASE_URL)
+def test_consent_verify_returns_claims(respx_mock, client):
+    claims = {
+        "sub": "user-42",
+        "agt": "agent-uuid",
+        "cid": "cr-uuid-001",
+        "scopes": ["send_email"],
+        "iat": 1716631200,
+        "exp": 1716717600,
+        "jti": "jti-uuid",
+    }
+    respx_mock.post("/v1/consent/verify").mock(
+        return_value=httpx.Response(200, json={"data": claims})
+    )
+    result = client.consent.verify("eyJhbGciOiJFUzI1NiJ9.test.sig")
+    assert result["sub"] == "user-42"
+    assert result["cid"] == "cr-uuid-001"
+
+
+@respx.mock(base_url=BASE_URL)
+def test_consent_verify_sends_token_in_body(respx_mock, client):
+    route = respx_mock.post("/v1/consent/verify").mock(
+        return_value=httpx.Response(200, json={"data": {"sub": "u"}})
+    )
+    token = "eyJhbGciOiJFUzI1NiJ9.test.sig"
+    client.consent.verify(token)
+    body = json.loads(route.calls[0].request.content)
+    assert body["token"] == token
+
+
+# --- revoke() ---
+
+@respx.mock(base_url=BASE_URL)
+def test_consent_revoke_returns_consent_request(respx_mock, client):
+    respx_mock.delete("/v1/consent/cr-uuid-001").mock(
+        return_value=httpx.Response(200, json={"data": {"id": "cr-uuid-001", "status": "revoked"}})
+    )
+    result = client.consent.revoke("cr-uuid-001")
+    assert isinstance(result, ConsentRequest)
+    assert result.status == "revoked"
+
+
+# --- list() ---
+
+@respx.mock(base_url=BASE_URL)
+def test_consent_list_returns_page_result(respx_mock, client):
+    respx_mock.get("/v1/consent").mock(
+        return_value=httpx.Response(200, json={
+            "data": [{"id": "cr-1", "status": "pending", "end_user_ref": "u1", "created_at": "2026-05-25T10:00:00+00:00"}],
+            "meta": {"cursor": None, "has_more": False},
+        })
+    )
+    result = client.consent.list()
+    assert isinstance(result, PageResult)
+    assert len(result.data) == 1
+    assert isinstance(result.data[0], ConsentRequest)
+    assert not result.has_more
+    assert result.cursor is None
+
+
+@respx.mock(base_url=BASE_URL)
+def test_consent_list_sends_filters(respx_mock, client):
+    route = respx_mock.get("/v1/consent").mock(
+        return_value=httpx.Response(200, json={"data": [], "meta": {"cursor": None, "has_more": False}})
+    )
+    client.consent.list(status="approved", end_user_ref="user-42", limit=10)
+    params = dict(route.calls[0].request.url.params)
+    assert params["status"] == "approved"
+    assert params["end_user_ref"] == "user-42"
+    assert params["limit"] == "10"
+
+
+@respx.mock(base_url=BASE_URL)
+def test_consent_list_passes_cursor(respx_mock, client):
+    route = respx_mock.get("/v1/consent").mock(
+        return_value=httpx.Response(200, json={"data": [], "meta": {"cursor": "bmV4dA==", "has_more": True}})
+    )
+    result = client.consent.list(cursor="dGVzdA==")
+    params = dict(route.calls[0].request.url.params)
+    assert params["cursor"] == "dGVzdA=="
+    assert result.cursor == "bmV4dA=="
+    assert result.has_more
+
+
+# --- manage_url() ---
+
+@respx.mock(base_url=BASE_URL)
+def test_consent_manage_url_returns_url(respx_mock, client):
+    respx_mock.get("/v1/consent/manage-url").mock(
+        return_value=httpx.Response(200, json={"data": {"url": "https://permitly.dev/manage/signed-token"}})
+    )
+    url = client.consent.manage_url("user-42")
+    assert url == "https://permitly.dev/manage/signed-token"
+
+
+@respx.mock(base_url=BASE_URL)
+def test_consent_manage_url_sends_end_user_ref(respx_mock, client):
+    route = respx_mock.get("/v1/consent/manage-url").mock(
+        return_value=httpx.Response(200, json={"data": {"url": "https://permitly.dev/manage/x"}})
+    )
+    client.consent.manage_url("user-42")
+    params = dict(route.calls[0].request.url.params)
+    assert params["end_user_ref"] == "user-42"

permitly-0.1.0/tests/test_models.py

@@ -0,0 +1,47 @@
+from permitly.models import ConsentRequest, AuditEvent, PageResult
+
+
+def test_consent_request_required_fields():
+    cr = ConsentRequest(id="abc-123", status="pending")
+    assert cr.id == "abc-123"
+    assert cr.status == "pending"
+    assert cr.consent_url is None
+    assert cr.end_user_ref is None
+    assert cr.scopes is None
+    assert cr.created_at is None
+    assert cr.decided_at is None
+    assert cr.expires_at is None
+
+
+def test_consent_request_full_fields():
+    cr = ConsentRequest(
+        id="abc-123",
+        status="approved",
+        consent_url="https://permitly.dev/c/abc-123",
+        end_user_ref="user-42",
+        scopes=[{"key": "send_email", "label": "Send Emails"}],
+        created_at="2026-05-25T10:00:00+00:00",
+        decided_at="2026-05-25T10:01:00+00:00",
+        expires_at="2026-05-26T10:00:00+00:00",
+    )
+    assert cr.end_user_ref == "user-42"
+    assert len(cr.scopes) == 1
+
+
+def test_audit_event_fields():
+    event = AuditEvent(
+        id="evt-1",
+        event_type="approved",
+        actor="user",
+        consent_id="cr-1",
+        created_at="2026-05-25T10:00:00+00:00",
+    )
+    assert event.event_type == "approved"
+    assert event.consent_id == "cr-1"
+
+
+def test_page_result_fields():
+    result = PageResult(data=[], cursor=None, has_more=False)
+    assert result.data == []
+    assert result.cursor is None
+    assert not result.has_more

permitly-0.1.0/tests/test_scope_templates.py

@@ -0,0 +1,63 @@
+from permitly.scope_templates import ScopeTemplates
+
+REQUIRED_KEYS = {"key", "label", "description", "reversible", "risk_level"}
+VALID_RISK_LEVELS = {"low", "medium", "high"}
+
+ALL_TEMPLATES = [
+    ScopeTemplates.SEND_EMAIL,
+    ScopeTemplates.READ_EMAIL,
+    ScopeTemplates.READ_CALENDAR,
+    ScopeTemplates.WRITE_CALENDAR,
+    ScopeTemplates.BOOK_APPOINTMENT,
+    ScopeTemplates.SEND_MESSAGE,
+    ScopeTemplates.READ_FILES,
+    ScopeTemplates.WRITE_FILES,
+    ScopeTemplates.MAKE_PURCHASE,
+    ScopeTemplates.SUBMIT_FORM,
+]
+
+
+def test_all_ten_templates_exist():
+    assert len(ALL_TEMPLATES) == 10
+
+
+def test_each_template_has_required_keys():
+    for template in ALL_TEMPLATES:
+        assert REQUIRED_KEYS == set(template.keys()), f"Missing keys in {template}"
+
+
+def test_each_template_has_valid_risk_level():
+    for template in ALL_TEMPLATES:
+        assert template["risk_level"] in VALID_RISK_LEVELS
+
+
+def test_reversible_is_boolean():
+    for template in ALL_TEMPLATES:
+        assert isinstance(template["reversible"], bool)
+
+
+def test_keys_are_snake_case():
+    for template in ALL_TEMPLATES:
+        key = template["key"]
+        assert key == key.lower()
+        assert " " not in key
+
+
+def test_high_risk_templates_are_not_reversible():
+    for template in ALL_TEMPLATES:
+        if template["risk_level"] == "high":
+            assert template["reversible"] is False, f"{template['key']} is high-risk but reversible=True"
+
+
+def test_send_email_shape():
+    t = ScopeTemplates.SEND_EMAIL
+    assert t["key"] == "send_email"
+    assert t["risk_level"] == "medium"
+    assert t["reversible"] is True
+
+
+def test_make_purchase_shape():
+    t = ScopeTemplates.MAKE_PURCHASE
+    assert t["key"] == "make_purchase"
+    assert t["risk_level"] == "high"
+    assert t["reversible"] is False

permitly-0.1.0/tests/test_webhook.py

@@ -0,0 +1,38 @@
+import hashlib
+import hmac
+
+from permitly.webhook import verify_signature
+
+
+SECRET = "whsec_test_secret_key_32byteslong"
+PAYLOAD = '{"event":"consent.approved","data":{"id":"cr-123"}}'
+
+
+def _make_sig(payload: str, secret: str) -> str:
+    digest = hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest()
+    return f"sha256={digest}"
+
+
+def test_valid_signature_returns_true():
+    sig = _make_sig(PAYLOAD, SECRET)
+    assert verify_signature(PAYLOAD, sig, SECRET) is True
+
+
+def test_invalid_signature_returns_false():
+    assert verify_signature(PAYLOAD, "sha256=deadbeef", SECRET) is False
+
+
+def test_wrong_secret_returns_false():
+    sig = _make_sig(PAYLOAD, "wrong_secret")
+    assert verify_signature(PAYLOAD, sig, SECRET) is False
+
+
+def test_tampered_payload_returns_false():
+    sig = _make_sig(PAYLOAD, SECRET)
+    tampered = PAYLOAD.replace("approved", "revoked")
+    assert verify_signature(tampered, sig, SECRET) is False
+
+
+def test_missing_sha256_prefix_returns_false():
+    raw_digest = hmac.new(SECRET.encode(), PAYLOAD.encode(), hashlib.sha256).hexdigest()
+    assert verify_signature(PAYLOAD, raw_digest, SECRET) is False