authpi-admin 0.3.0__py3-none-any.whl

authpi_admin/__init__.py

@@ -0,0 +1,55 @@
+"""AuthPI Admin SDK — Official Python client for the AuthPI Core API."""
+
+from __future__ import annotations
+
+__version__ = "0.3.0"
+
+from authpi_admin.client import AuthPIAdmin
+from authpi_admin.errors import (
+    ApiError,
+    AuthenticationError,
+    BadGatewayError,
+    ClosedClientError,
+    ConfigurationError,
+    ConflictError,
+    ForbiddenError,
+    GatewayTimeoutError,
+    InternalServerError,
+    NotFoundError,
+    PreconditionFailedError,
+    RateLimitError,
+    ServerError,
+    ServiceUnavailableError,
+    UnexpectedError,
+    ValidationError,
+)
+from authpi_admin.generated.scopes.issuer_scope import IssuerScope
+from authpi_admin.generated.scopes.user_scope import UserScope
+from authpi_admin.generated.scopes.agent_scope import AgentScope
+from authpi_admin.generated.scopes.webhook_scope import WebhookScope
+from authpi_admin.pagination import Page
+
+__all__ = [
+    "AgentScope",
+    "ApiError",
+    "AuthPIAdmin",
+    "AuthenticationError",
+    "BadGatewayError",
+    "ClosedClientError",
+    "ConfigurationError",
+    "ConflictError",
+    "ForbiddenError",
+    "GatewayTimeoutError",
+    "InternalServerError",
+    "IssuerScope",
+    "NotFoundError",
+    "Page",
+    "PreconditionFailedError",
+    "RateLimitError",
+    "ServerError",
+    "ServiceUnavailableError",
+    "UnexpectedError",
+    "UserScope",
+    "ValidationError",
+    "WebhookScope",
+]

authpi_admin/_version.py

@@ -0,0 +1,5 @@
+"""SDK version — kept in sync with pyproject.toml via release-please."""
+
+# x-release-please-start-version
+SDK_VERSION = "0.3.0"
+# x-release-please-end

authpi_admin/client.py

@@ -0,0 +1,155 @@
+"""AuthPIAdmin — entry-point client for the AuthPI Admin SDK."""
+
+from __future__ import annotations
+
+from functools import cached_property
+from typing import TYPE_CHECKING, Any, Awaitable, Callable
+
+import httpx
+
+from authpi_admin.errors import ConfigurationError
+from authpi_admin.http_client import HttpClient
+from authpi_admin.generated.resources.accounts import AccountsResource
+from authpi_admin.generated.resources.api_keys import ApiKeysResource
+from authpi_admin.generated.resources.domains import DomainsResource
+from authpi_admin.generated.resources.events import EventsResource
+from authpi_admin.generated.resources.issuers import IssuersResource
+from authpi_admin.generated.resources.notes import NotesResource
+from authpi_admin.generated.resources.tokens import TokensResource
+from authpi_admin.generated.resources.webhooks import WebhooksResource
+from authpi_admin.generated.scopes.issuer_scope import IssuerScope
+from authpi_admin.generated.scopes.webhook_scope import WebhookScope
+
+if TYPE_CHECKING:
+    from types import TracebackType
+
+
+class AuthPIAdmin:
+    """Entry-point client for the AuthPI Core API.
+
+    Usage with API key:
+        async with AuthPIAdmin(api_key="key_xxx") as admin:
+            users = await admin.issuer("iss_xxx").users.list()
+
+    Usage with bearer token:
+        async with AuthPIAdmin(
+            access_token="tok_xxx",
+            account_id="acc_xxx",
+        ) as admin:
+            users = await admin.issuer("iss_xxx").users.list()
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        access_token: str | None = None,
+        on_token_expired: Callable[[], Awaitable[dict[str, str]]] | None = None,
+        account_id: str | None = None,
+        base_url: str = "https://api.authpi.dev",
+        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:
+        if not api_key and not access_token:
+            raise ConfigurationError("Either api_key or access_token is required")
+        if api_key and access_token:
+            raise ConfigurationError("Provide either api_key or access_token, not both")
+        if access_token and not account_id:
+            raise ConfigurationError("account_id is required when using access_token")
+
+        resolved_account_id = account_id or "me"
+        self._http = HttpClient(
+            base_url=base_url,
+            api_key=api_key,
+            access_token=access_token,
+            on_token_expired=on_token_expired,
+            http_client=http_client,
+            timeout=timeout,
+            default_headers=default_headers,
+            retries=retries,
+        )
+        self._base_path = f"/v1/accounts/{resolved_account_id}"
+
+    @property
+    def http(self) -> HttpClient:
+        """The underlying HTTP client (for advanced use)."""
+        return self._http
+
+    # --- Account-level resource accessors ---
+
+    @cached_property
+    def accounts(self) -> AccountsResource:
+        """Operations on the account itself."""
+        return AccountsResource(self._http, "/v1/accounts")
+
+    @cached_property
+    def api_keys(self) -> ApiKeysResource:
+        """Manage account-level API keys."""
+        return ApiKeysResource(self._http, f"{self._base_path}/api-keys")
+
+    @cached_property
+    def domains(self) -> DomainsResource:
+        """Manage account-level domains."""
+        return DomainsResource(self._http, f"{self._base_path}/domains")
+
+    @cached_property
+    def events(self) -> EventsResource:
+        """Query events."""
+        return EventsResource(self._http, f"{self._base_path}/events")
+
+    @cached_property
+    def issuers(self) -> IssuersResource:
+        """Manage issuers."""
+        return IssuersResource(self._http, f"{self._base_path}/issuers")
+
+    @cached_property
+    def notes(self) -> NotesResource:
+        """Manage notes."""
+        return NotesResource(self._http, f"{self._base_path}/notes")
+
+    @cached_property
+    def tokens(self) -> TokensResource:
+        """Manage account-level tokens."""
+        return TokensResource(self._http, f"{self._base_path}/tokens")
+
+    @cached_property
+    def webhooks(self) -> WebhooksResource:
+        """Manage webhooks."""
+        return WebhooksResource(self._http, f"{self._base_path}/webhooks")
+
+    # --- Scope accessors ---
+
+    def issuer(self, issuer_id: str) -> IssuerScope:
+        """Scope operations to a specific issuer."""
+        return IssuerScope(
+            client=self._http,
+            base_path=f"{self._base_path}/issuers",
+            issuer_id=issuer_id,
+        )
+
+    def webhook(self, webhook_id: str) -> WebhookScope:
+        """Scope operations to a specific webhook."""
+        return WebhookScope(
+            client=self._http,
+            base_path=f"{self._base_path}/webhooks",
+            webhook_id=webhook_id,
+        )
+
+    # --- Lifecycle ---
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        await self._http.close()
+
+    async def __aenter__(self) -> AuthPIAdmin:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        await self.close()

authpi_admin/errors.py

@@ -0,0 +1,218 @@
+"""Error hierarchy for the AuthPI Admin SDK."""
+
+from __future__ import annotations
+
+import contextlib
+from typing import Any
+
+# Retryable status codes (when not overridden by response body)
+_RETRYABLE_STATUSES = {408, 429, 502, 503, 504}
+
+
+class ConfigurationError(Exception):
+    """Raised when the client is configured incorrectly."""
+
+
+class ApiError(Exception):
+    """Base error for all API errors."""
+
+    def __init__(
+        self,
+        *,
+        error: str,
+        error_description: str,
+        status_code: int,
+        retryable: bool = False,
+        reference: str | None = None,
+        raw_body: str | None = None,
+    ) -> None:
+        super().__init__(error_description)
+        self.error = error
+        self.error_description = error_description
+        self.status_code = status_code
+        self.retryable = retryable
+        self.reference = reference
+        self.raw_body = raw_body
+
+
+class ValidationError(ApiError):
+    """Raised for 400 and 422 responses with field-level validation errors."""
+
+    def __init__(self, *, fields: list[dict[str, Any]] | None = None, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self.fields = fields or []
+
+
+class AuthenticationError(ApiError):
+    """Raised for 401 responses."""
+
+
+class ForbiddenError(ApiError):
+    """Raised for 403 responses."""
+
+
+class NotFoundError(ApiError):
+    """Raised for 404 responses."""
+
+
+class ConflictError(ApiError):
+    """Raised for 409 responses."""
+
+
+class PreconditionFailedError(ApiError):
+    """Raised for 412 responses (ETag mismatch)."""
+
+    def __init__(self, *, current_etag: str | None = None, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self.current_etag = current_etag
+
+
+class RateLimitError(ApiError):
+    """Raised for 429 responses."""
+
+    def __init__(self, *, retry_after: int | None = None, **kwargs: Any) -> None:
+        kwargs.setdefault("retryable", True)
+        super().__init__(**kwargs)
+        self.retry_after = retry_after
+
+
+class ServerError(ApiError):
+    """Base class for 5xx server errors."""
+
+
+class InternalServerError(ServerError):
+    """Raised for 500 responses."""
+
+
+class BadGatewayError(ServerError):
+    """Raised for 502 responses."""
+
+    def __init__(self, **kwargs: Any) -> None:
+        kwargs.setdefault("retryable", True)
+        super().__init__(**kwargs)
+
+
+class ServiceUnavailableError(ServerError):
+    """Raised for 503 responses."""
+
+    def __init__(self, **kwargs: Any) -> None:
+        kwargs.setdefault("retryable", True)
+        super().__init__(**kwargs)
+
+
+class GatewayTimeoutError(ServerError):
+    """Raised for 504 responses."""
+
+    def __init__(self, **kwargs: Any) -> None:
+        kwargs.setdefault("retryable", True)
+        super().__init__(**kwargs)
+
+
+class UnexpectedError(ApiError):
+    """Raised for any status code not explicitly mapped."""
+
+
+class ClosedClientError(ApiError):
+    """Raised when attempting to use a closed client."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            error="closed_client",
+            error_description="Cannot make requests after the client has been closed",
+            status_code=0,
+            retryable=False,
+        )
+
+
+# HTTP status text fallbacks
+_STATUS_TEXT: dict[int, str] = {
+    400: "Bad Request",
+    401: "Unauthorized",
+    403: "Forbidden",
+    404: "Not Found",
+    408: "Request Timeout",
+    409: "Conflict",
+    412: "Precondition Failed",
+    422: "Unprocessable Entity",
+    429: "Too Many Requests",
+    500: "Internal Server Error",
+    502: "Bad Gateway",
+    503: "Service Unavailable",
+    504: "Gateway Timeout",
+}
+
+# Status code -> error class mapping
+_STATUS_MAP: dict[int, type[ApiError]] = {
+    400: ValidationError,
+    401: AuthenticationError,
+    403: ForbiddenError,
+    404: NotFoundError,
+    409: ConflictError,
+    412: PreconditionFailedError,
+    422: ValidationError,
+    429: RateLimitError,
+    500: InternalServerError,
+    502: BadGatewayError,
+    503: ServiceUnavailableError,
+    504: GatewayTimeoutError,
+}
+
+
+def error_from_response(
+    *,
+    status_code: int,
+    body: dict[str, Any] | None,
+    headers: dict[str, str],
+    raw_body: str | None = None,
+) -> ApiError:
+    """Create the appropriate error from an HTTP response.
+
+    Args:
+        status_code: HTTP status code.
+        body: Parsed JSON body, or None if parsing failed.
+        headers: Response headers (lowercase keys).
+        raw_body: Raw body string for non-JSON responses.
+    """
+    body = body or {}
+    error = body.get("error", "unknown")
+    error_description = body.get("error_description", _STATUS_TEXT.get(status_code, "Unknown Error"))
+    reference = body.get("reference")
+    retryable = body.get("retryable", status_code in _RETRYABLE_STATUSES)
+
+    base_kwargs: dict[str, Any] = {
+        "error": error,
+        "error_description": error_description,
+        "status_code": status_code,
+        "retryable": retryable,
+        "reference": reference,
+        "raw_body": raw_body,
+    }
+
+    error_class = _STATUS_MAP.get(status_code)
+
+    if error_class is None:
+        # 408 gets base ApiError with retryable=True
+        if status_code == 408:
+            return ApiError(**base_kwargs)
+        # Unmapped 5xx codes get the base ServerError
+        if 500 <= status_code < 600:
+            return ServerError(**base_kwargs)
+        return UnexpectedError(**base_kwargs)
+
+    # Build extra kwargs for specific error classes
+    if error_class is ValidationError:
+        return ValidationError(fields=body.get("fields"), **base_kwargs)
+
+    if error_class is PreconditionFailedError:
+        return PreconditionFailedError(current_etag=body.get("current_etag"), **base_kwargs)
+
+    if error_class is RateLimitError:
+        retry_after = body.get("retry_after")
+        if retry_after is None:
+            header_val = headers.get("retry-after")
+            if header_val is not None:
+                with contextlib.suppress(ValueError):
+                    retry_after = int(header_val)
+        return RateLimitError(retry_after=retry_after, **base_kwargs)
+
+    return error_class(**base_kwargs)

authpi_admin/generated/__init__.py

@@ -0,0 +1,28 @@
+"""Generated exports — DO NOT EDIT."""
+
+from .models import *  # noqa: F401,F403
+from .resources.accounts import AccountsResource  # noqa: F401
+from .resources.api_keys import ApiKeysResource  # noqa: F401
+from .resources.domains import DomainsResource  # noqa: F401
+from .resources.events import EventsResource  # noqa: F401
+from .resources.issuers import IssuersResource  # noqa: F401
+from .resources.agents import AgentsResource  # noqa: F401
+from .resources.verifiers import VerifiersResource  # noqa: F401
+from .resources.approvals import ApprovalsResource  # noqa: F401
+from .resources.auth_methods import AuthMethodsResource  # noqa: F401
+from .resources.clients import ClientsResource  # noqa: F401
+from .resources.organizations import OrganizationsResource  # noqa: F401
+from .resources.groups import GroupsResource  # noqa: F401
+from .resources.invitations import InvitationsResource  # noqa: F401
+from .resources.members import MembersResource  # noqa: F401
+from .resources.sessions import SessionsResource  # noqa: F401
+from .resources.users import UsersResource  # noqa: F401
+from .resources.tokens import TokensResource  # noqa: F401
+from .resources.trusted_devices import TrustedDevicesResource  # noqa: F401
+from .resources.notes import NotesResource  # noqa: F401
+from .resources.webhooks import WebhooksResource  # noqa: F401
+from .resources.deliveries import DeliveriesResource  # noqa: F401
+from .scopes.issuer_scope import IssuerScope  # noqa: F401
+from .scopes.agent_scope import AgentScope  # noqa: F401
+from .scopes.user_scope import UserScope  # noqa: F401
+from .scopes.webhook_scope import WebhookScope  # noqa: F401