permitly 0.1.0__py3-none-any.whl

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

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

@@ -0,0 +1,12 @@
+permitly/__init__.py,sha256=6p0DnW5yWBTDOZOTAuj3hi9kI7TrtxgNEZtK_1ZDdyg,484
+permitly/client.py,sha256=ZbKwgUr2TqdTYjxmfzf4rhQ5gBAEjUz6hzitGuL8efo,2624
+permitly/exceptions.py,sha256=qZMo-G2BZ2uuG7md565oyak8YIrSHTe_0QT_wkzx6bo,889
+permitly/models.py,sha256=fVqnkQjbSHiM9MM5uBjsb36JKOYyKUrzWTyi7VJNUWM,1300
+permitly/scope_templates.py,sha256=-3XowWRUNgaIVcuxA0j7P0Xnxr6sYlr5OjRGSEeaHbs,2312
+permitly/webhook.py,sha256=HlBKl5tuwhLv59VIY1j8R5S4mlQ8PYBFQHb65Tbnzok,862
+permitly/resources/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+permitly/resources/audit.py,sha256=xxuLywp3SX7Op_hHK-wr251GzlE768-dWcMIi4jdIWw,1603
+permitly/resources/consent.py,sha256=dadfA2lZozwwljy-FpYriS3L1CAMVYjWZEuVaM-IptQ,4769
+permitly-0.1.0.dist-info/METADATA,sha256=Rqt4gAGI_Af_c4_HyYt5X6KJo51Nx-XtAylFGdUeAks,310
+permitly-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+permitly-0.1.0.dist-info/RECORD,,

permitly-0.1.0.dist-info/WHEEL

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