authpi-admin 0.3.0__py3-none-any.whl

authpi_admin/generated/scopes/issuer_scope.py

@@ -0,0 +1,160 @@
+"""Generated scope class for IssuerScope — DO NOT EDIT."""
+
+from __future__ import annotations
+
+from functools import cached_property
+from typing import Any, TYPE_CHECKING
+
+from authpi_admin.http_client import validate_path_segment as _validate_path_segment
+
+if TYPE_CHECKING:
+    from authpi_admin.http_client import HttpClient
+from authpi_admin.generated.resources.agents import AgentsResource
+from authpi_admin.generated.resources.approvals import ApprovalsResource
+from authpi_admin.generated.resources.auth_methods import AuthMethodsResource
+from authpi_admin.generated.resources.clients import ClientsResource
+from authpi_admin.generated.resources.organizations import OrganizationsResource
+from authpi_admin.generated.resources.api_keys import ApiKeysResource
+from authpi_admin.generated.resources.groups import GroupsResource
+from authpi_admin.generated.resources.invitations import InvitationsResource
+from authpi_admin.generated.resources.members import MembersResource
+from authpi_admin.generated.resources.domains import DomainsResource
+from authpi_admin.generated.resources.sessions import SessionsResource
+from authpi_admin.generated.resources.users import UsersResource
+from authpi_admin.generated.scopes.agent_scope import AgentScope
+from authpi_admin.generated.scopes.user_scope import UserScope
+
+
+class IssuerScope:
+    """Scope for operations under a specific issuer."""
+
+    def __init__(self, client: HttpClient, base_path: str, issuer_id: str) -> None:
+        _validate_path_segment(issuer_id, "issuer_id")
+        self._client = client
+        self._base_path = base_path
+        self._issuer_id = issuer_id
+        self._path = f"{base_path}/{issuer_id}"
+
+    @cached_property
+    def agents(self) -> AgentsResource:
+        """Access agents under this issuer."""
+        return AgentsResource(self._client, f"{self._path}/agents")
+
+    @cached_property
+    def approvals(self) -> ApprovalsResource:
+        """Access approvals under this issuer."""
+        return ApprovalsResource(self._client, f"{self._path}/approvals")
+
+    @cached_property
+    def auth_methods(self) -> AuthMethodsResource:
+        """Access auth_methods under this issuer."""
+        return AuthMethodsResource(self._client, f"{self._path}/auth-methods")
+
+    @cached_property
+    def clients(self) -> ClientsResource:
+        """Access clients under this issuer."""
+        return ClientsResource(self._client, f"{self._path}/clients")
+
+    @cached_property
+    def organizations(self) -> OrganizationsResource:
+        """Access organizations under this issuer."""
+        return OrganizationsResource(self._client, f"{self._path}/organizations")
+
+    @cached_property
+    def api_keys(self) -> ApiKeysResource:
+        """Access api_keys under this issuer."""
+        return ApiKeysResource(self._client, f"{self._path}/api-keys")
+
+    @cached_property
+    def groups(self) -> GroupsResource:
+        """Access groups under this issuer."""
+        return GroupsResource(self._client, f"{self._path}/groups")
+
+    @cached_property
+    def invitations(self) -> InvitationsResource:
+        """Access invitations under this issuer."""
+        return InvitationsResource(self._client, f"{self._path}/invitations")
+
+    @cached_property
+    def members(self) -> MembersResource:
+        """Access members under this issuer."""
+        return MembersResource(self._client, f"{self._path}/members")
+
+    @cached_property
+    def domains(self) -> DomainsResource:
+        """Access domains under this issuer."""
+        return DomainsResource(self._client, f"{self._path}/domains")
+
+    @cached_property
+    def sessions(self) -> SessionsResource:
+        """Access sessions under this issuer."""
+        return SessionsResource(self._client, f"{self._path}/sessions")
+
+    @cached_property
+    def users(self) -> UsersResource:
+        """Access users under this issuer."""
+        return UsersResource(self._client, f"{self._path}/users")
+
+    def agent(self, agent_id: str) -> AgentScope:
+        """Scope into a specific agent."""
+        return AgentScope(self._client, f"{self._path}/agents", agent_id)
+
+    def user(self, user_id: str) -> UserScope:
+        """Scope into a specific user."""
+        return UserScope(self._client, f"{self._path}/users", user_id)
+
+    async def get(
+        self,
+        *,
+        timeout: float | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> Any:
+        """Get Issuer"""
+        resp = await self._client.request("GET", self._path, timeout=timeout, headers=headers)
+        return resp.data
+
+    async def update(
+        self,
+        body: dict[str, Any],
+        *,
+        if_match: str | None = None,
+        idempotency_key: str | None = None,
+        timeout: float | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> Any:
+        """Update Issuer"""
+        req_headers: dict[str, str] = {}
+        if headers:
+            req_headers.update(headers)
+        if if_match:
+            req_headers["if-match"] = if_match
+        if idempotency_key:
+            req_headers["idempotency-key"] = idempotency_key
+        resp = await self._client.request(
+            "PATCH",
+            self._path,
+            body=body,
+            timeout=timeout,
+            headers=req_headers or None,
+        )
+        return resp.data
+
+    async def delete(
+        self,
+        *,
+        if_match: str | None = None,
+        timeout: float | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        """Delete Issuer"""
+        req_headers: dict[str, str] = {}
+        if headers:
+            req_headers.update(headers)
+        if if_match:
+            req_headers["if-match"] = if_match
+        await self._client.request(
+            "DELETE",
+            self._path,
+            timeout=timeout,
+            headers=req_headers or None,
+        )

authpi_admin/generated/scopes/user_scope.py

@@ -0,0 +1,102 @@
+"""Generated scope class for UserScope — DO NOT EDIT."""
+
+from __future__ import annotations
+
+from functools import cached_property
+from typing import Any, TYPE_CHECKING
+
+from authpi_admin.http_client import validate_path_segment as _validate_path_segment
+
+if TYPE_CHECKING:
+    from authpi_admin.http_client import HttpClient
+from authpi_admin.generated.resources.sessions import SessionsResource
+from authpi_admin.generated.resources.tokens import TokensResource
+from authpi_admin.generated.resources.trusted_devices import TrustedDevicesResource
+from authpi_admin.generated.resources.verifiers import VerifiersResource
+
+
+class UserScope:
+    """Scope for operations under a specific user."""
+
+    def __init__(self, client: HttpClient, base_path: str, user_id: str) -> None:
+        _validate_path_segment(user_id, "user_id")
+        self._client = client
+        self._base_path = base_path
+        self._user_id = user_id
+        self._path = f"{base_path}/{user_id}"
+
+    @cached_property
+    def sessions(self) -> SessionsResource:
+        """Access sessions under this user."""
+        return SessionsResource(self._client, f"{self._path}/sessions")
+
+    @cached_property
+    def tokens(self) -> TokensResource:
+        """Access tokens under this user."""
+        return TokensResource(self._client, f"{self._path}/tokens")
+
+    @cached_property
+    def trusted_devices(self) -> TrustedDevicesResource:
+        """Access trusted_devices under this user."""
+        return TrustedDevicesResource(self._client, f"{self._path}/trusted-devices")
+
+    @cached_property
+    def verifiers(self) -> VerifiersResource:
+        """Access verifiers under this user."""
+        return VerifiersResource(self._client, f"{self._path}/verifiers")
+
+    async def get(
+        self,
+        *,
+        timeout: float | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> Any:
+        """Get User"""
+        resp = await self._client.request("GET", self._path, timeout=timeout, headers=headers)
+        return resp.data
+
+    async def update(
+        self,
+        body: dict[str, Any],
+        *,
+        if_match: str | None = None,
+        idempotency_key: str | None = None,
+        timeout: float | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> Any:
+        """Update User"""
+        req_headers: dict[str, str] = {}
+        if headers:
+            req_headers.update(headers)
+        if if_match:
+            req_headers["if-match"] = if_match
+        if idempotency_key:
+            req_headers["idempotency-key"] = idempotency_key
+        resp = await self._client.request(
+            "PATCH",
+            self._path,
+            body=body,
+            timeout=timeout,
+            headers=req_headers or None,
+        )
+        return resp.data
+
+    async def delete(
+        self,
+        *,
+        if_match: str | None = None,
+        timeout: float | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        """Delete User"""
+        req_headers: dict[str, str] = {}
+        if headers:
+            req_headers.update(headers)
+        if if_match:
+            req_headers["if-match"] = if_match
+        await self._client.request(
+            "DELETE",
+            self._path,
+            timeout=timeout,
+            headers=req_headers or None,
+        )

authpi_admin/generated/scopes/webhook_scope.py

@@ -0,0 +1,84 @@
+"""Generated scope class for WebhookScope — DO NOT EDIT."""
+
+from __future__ import annotations
+
+from functools import cached_property
+from typing import Any, TYPE_CHECKING
+
+from authpi_admin.http_client import validate_path_segment as _validate_path_segment
+
+if TYPE_CHECKING:
+    from authpi_admin.http_client import HttpClient
+from authpi_admin.generated.resources.deliveries import DeliveriesResource
+
+
+class WebhookScope:
+    """Scope for operations under a specific webhook."""
+
+    def __init__(self, client: HttpClient, base_path: str, webhook_id: str) -> None:
+        _validate_path_segment(webhook_id, "webhook_id")
+        self._client = client
+        self._base_path = base_path
+        self._webhook_id = webhook_id
+        self._path = f"{base_path}/{webhook_id}"
+
+    @cached_property
+    def deliveries(self) -> DeliveriesResource:
+        """Access deliveries under this webhook."""
+        return DeliveriesResource(self._client, f"{self._path}/deliveries")
+
+    async def get(
+        self,
+        *,
+        timeout: float | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> Any:
+        """Get Webhook"""
+        resp = await self._client.request("GET", self._path, timeout=timeout, headers=headers)
+        return resp.data
+
+    async def update(
+        self,
+        body: dict[str, Any],
+        *,
+        if_match: str | None = None,
+        idempotency_key: str | None = None,
+        timeout: float | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> Any:
+        """Update Webhook"""
+        req_headers: dict[str, str] = {}
+        if headers:
+            req_headers.update(headers)
+        if if_match:
+            req_headers["if-match"] = if_match
+        if idempotency_key:
+            req_headers["idempotency-key"] = idempotency_key
+        resp = await self._client.request(
+            "PATCH",
+            self._path,
+            body=body,
+            timeout=timeout,
+            headers=req_headers or None,
+        )
+        return resp.data
+
+    async def delete(
+        self,
+        *,
+        if_match: str | None = None,
+        timeout: float | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        """Delete Webhook"""
+        req_headers: dict[str, str] = {}
+        if headers:
+            req_headers.update(headers)
+        if if_match:
+            req_headers["if-match"] = if_match
+        await self._client.request(
+            "DELETE",
+            self._path,
+            timeout=timeout,
+            headers=req_headers or None,
+        )

authpi_admin/http_client.py

@@ -0,0 +1,305 @@
+"""Internal HTTP client — not exported. Used by all resource classes."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable
+
+import httpx
+
+from authpi_admin.errors import (
+    AuthenticationError,
+    ClosedClientError,
+    ConfigurationError,
+    error_from_response,
+)
+from authpi_admin._version import SDK_VERSION
+from authpi_admin.user_agent import build_user_agent
+
+_USER_AGENT = build_user_agent(SDK_VERSION)
+
+# Maximum raw body size to store on errors (4KB)
+_MAX_RAW_BODY = 4096
+
+_UNSAFE_PATH_CHARS = frozenset("/\\?#")
+
+# Headers that must not be overridden by user-provided values.
+_PROTECTED_HEADERS = frozenset({"authorization", "host", "user-agent"})
+
+_RETRYABLE_STATUSES = frozenset({429, 502, 503, 504})
+_RETRYABLE_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
+
+
+def validate_path_segment(value: str, name: str = "id") -> str:
+    """Validate that a value is safe to interpolate into a URL path segment."""
+    if not value or any(c in value for c in _UNSAFE_PATH_CHARS) or value in (".", ".."):
+        raise ValueError(f"Invalid {name}: must not be empty or contain path separators")
+    return value
+
+
+def _strip_underscore_keys(obj: Any) -> Any:
+    """Recursively remove keys starting with ``_`` from dicts (e.g. ``_etag``)."""
+    if obj is None or not isinstance(obj, (dict, list)):
+        return obj
+    if isinstance(obj, list):
+        return [_strip_underscore_keys(item) for item in obj]
+    return {k: _strip_underscore_keys(v) for k, v in obj.items() if not k.startswith("_")}
+
+
+def _parse_retry_after(header: str | None) -> float | None:
+    """Parse Retry-After header value into seconds."""
+    if not header:
+        return None
+    try:
+        return float(header)
+    except ValueError:
+        return None
+
+
+@dataclass
+class RetryConfig:
+    """Retry configuration."""
+
+    limit: int = 3
+    delay: float = 1.0
+    backoff: str = "exponential"  # "exponential" or "linear"
+
+
+@dataclass
+class ApiResponse:
+    """Response wrapper carrying parsed data and optional ETag."""
+
+    data: Any
+    etag: str | None = None
+
+
+class HttpClient:
+    """Low-level HTTP client that handles auth, serialization, retries, and error mapping."""
+
+    __slots__ = (
+        "_base_url",
+        "_HttpClient__credential",
+        "_owns_client",
+        "_closed",
+        "_client",
+        "_default_headers",
+        "_retry_config",
+        "_on_token_expired",
+        "_refresh_lock",
+    )
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        api_key: str | None = None,
+        access_token: str | None = None,
+        on_token_expired: Callable[[], Awaitable[dict[str, str]]] | None = None,
+        http_client: httpx.AsyncClient | None = None,
+        timeout: float = 30.0,
+        default_headers: dict[str, str] | None = None,
+        retries: bool | dict[str, Any] | None = None,
+    ) -> None:
+        has_api_key = api_key is not None
+        has_access_token = access_token is not None
+
+        if not has_api_key and not has_access_token:
+            raise ConfigurationError("Either api_key or access_token is required")
+        if has_api_key and has_access_token:
+            raise ConfigurationError("Provide either api_key or access_token, not both")
+
+        self._base_url = base_url.rstrip("/")
+        self.__credential = api_key or access_token  # name-mangled
+        self._default_headers = default_headers or {}
+        self._on_token_expired = on_token_expired
+        self._refresh_lock = asyncio.Lock()
+        self._owns_client = http_client is None
+        self._closed = False
+
+        if retries is False:
+            self._retry_config: RetryConfig | None = None
+        else:
+            r = retries if isinstance(retries, dict) else {}
+            self._retry_config = RetryConfig(
+                limit=r.get("limit", 3),
+                delay=r.get("delay", 1.0),
+                backoff=r.get("backoff", "exponential"),
+            )
+
+        if http_client is not None:
+            self._client = http_client
+        else:
+            self._client = httpx.AsyncClient(timeout=timeout)
+
+    def _update_credential(self, token: str) -> None:
+        """Update the bearer credential after a token refresh."""
+        self.__credential = token
+
+    def __repr__(self) -> str:
+        return f"HttpClient(base_url={self._base_url!r})"
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Any = None,
+        query: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        timeout: float | None = None,
+    ) -> ApiResponse:
+        """Send an HTTP request and return the parsed response."""
+        return await self._request(method, path, body=body, query=query, headers=headers, timeout=timeout, is_refresh_retry=False)
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Any = None,
+        query: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        timeout: float | None = None,
+        is_refresh_retry: bool = False,
+    ) -> ApiResponse:
+        if self._closed:
+            raise ClosedClientError()
+
+        url = f"{self._base_url}{path}"
+
+        filtered_query: dict[str, Any] | None = None
+        if query:
+            filtered_query = {k: v for k, v in query.items() if v is not None}
+
+        content = json.dumps(_strip_underscore_keys(body)).encode() if body is not None else None
+
+        can_retry = self._retry_config is not None and method.upper() in _RETRYABLE_METHODS
+        max_attempts = (self._retry_config.limit + 1) if can_retry and self._retry_config else 1
+
+        for attempt in range(max_attempts):
+            req_headers = self._build_headers(body is not None, headers)
+
+            kwargs: dict[str, Any] = {
+                "method": method,
+                "url": url,
+                "headers": req_headers,
+            }
+            if content is not None:
+                kwargs["content"] = content
+            if filtered_query:
+                kwargs["params"] = filtered_query
+            if timeout is not None:
+                kwargs["timeout"] = timeout
+
+            try:
+                response = await self._client.request(**kwargs)
+            except httpx.CloseError as err:
+                raise ClosedClientError() from err
+            except RuntimeError as err:
+                if "closed" in str(err).lower():
+                    raise ClosedClientError() from err
+                raise
+
+            # Handle 401 with token refresh
+            if response.status_code == 401 and self._on_token_expired and not is_refresh_retry:
+                await self._singleflight_refresh(self.__credential)
+                return await self._request(
+                    method, path, body=body, query=query, headers=headers,
+                    timeout=timeout, is_refresh_retry=True,
+                )
+
+            if response.is_success:
+                return self._handle_success(response)
+
+            # Check if we should retry
+            if can_retry and response.status_code in _RETRYABLE_STATUSES and attempt < max_attempts - 1:
+                retry_after = _parse_retry_after(response.headers.get("retry-after"))
+                if retry_after is not None:
+                    delay = retry_after
+                elif self._retry_config and self._retry_config.backoff == "exponential":
+                    delay = self._retry_config.delay * (2 ** attempt)
+                elif self._retry_config:
+                    delay = self._retry_config.delay * (attempt + 1)
+                else:
+                    delay = 1.0
+                await asyncio.sleep(delay)
+                continue
+
+            # Not retryable or last attempt
+            self._handle_error(response)
+
+        # Unreachable
+        raise RuntimeError("unreachable")
+
+    async def _singleflight_refresh(self, stale_credential: str) -> str:
+        """Deduplicate concurrent token refresh calls.
+
+        Uses the lock + credential comparison pattern: if the credential has
+        already been updated by the time we acquire the lock, skip the refresh.
+        This prevents rotating refresh tokens from being consumed multiple
+        times under concurrency.
+        """
+        async with self._refresh_lock:
+            # If credential changed while we waited, another coroutine already refreshed
+            if self.__credential != stale_credential:
+                return self.__credential  # type: ignore[return-value]
+
+            assert self._on_token_expired is not None
+            result = await self._on_token_expired()
+            self._update_credential(result["access_token"])
+            return result["access_token"]
+
+    def _build_headers(self, has_body: bool, extra: dict[str, str] | None) -> dict[str, str]:
+        req_headers: dict[str, str] = {
+            "authorization": f"Bearer {self.__credential}",
+            "accept": "application/json",
+            "user-agent": _USER_AGENT,
+        }
+        if has_body:
+            req_headers["content-type"] = "application/json"
+
+        for key, value in self._default_headers.items():
+            if key.lower() not in _PROTECTED_HEADERS:
+                req_headers[key] = value
+
+        if extra:
+            for key, value in extra.items():
+                if key.lower() not in _PROTECTED_HEADERS:
+                    req_headers[key] = value
+
+        return req_headers
+
+    @staticmethod
+    def _handle_success(response: httpx.Response) -> ApiResponse:
+        if response.status_code == 204 or not response.content:
+            return ApiResponse(data=None)
+        data = response.json()
+        etag = response.headers.get("etag")
+        return ApiResponse(data=data, etag=etag)
+
+    @staticmethod
+    def _handle_error(response: httpx.Response) -> None:
+        raw_body: str | None = None
+        parsed_body: dict[str, Any] | None = None
+
+        try:
+            parsed_body = response.json()
+        except Exception:
+            raw_text = response.text
+            raw_body = raw_text[:_MAX_RAW_BODY] if raw_text else None
+
+        resp_headers = dict(response.headers)
+        raise error_from_response(
+            status_code=response.status_code,
+            body=parsed_body,
+            headers=resp_headers,
+            raw_body=raw_body,
+        )
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client (only if owned by this instance)."""
+        if self._owns_client:
+            await self._client.aclose()
+        self._closed = self._owns_client

authpi_admin/pagination.py

@@ -0,0 +1,41 @@
+"""Cursor-based pagination helpers."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Awaitable, Callable
+from dataclasses import dataclass
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class Page(Generic[T]):
+    """A single page of results from a paginated endpoint."""
+
+    data: list[T]
+    has_more: bool
+    next_cursor: str | None = None
+
+
+async def auto_paginate(
+    fetcher: Callable[[str | None], Awaitable[Page[T]]],
+) -> AsyncIterator[T]:
+    """Automatically paginate through all results.
+
+    Args:
+        fetcher: An async function that takes an optional cursor and returns a Page.
+
+    Yields:
+        Individual items from each page.
+    """
+    cursor: str | None = None
+    while True:
+        page = await fetcher(cursor)
+        for item in page.data:
+            yield item
+        if not page.has_more:
+            break
+        cursor = page.next_cursor
+        if cursor is None:
+            break