omnidapter 0.3.2__py3-none-any.whl

omnidapter/__init__.py

@@ -0,0 +1,118 @@
+"""
+Omnidapter — provider-agnostic async integration library.
+
+Quick start:
+    from omnidapter import Omnidapter
+    from omnidapter.transport.retry import RetryPolicy
+
+    omni = Omnidapter(
+        credential_store=my_store,
+        oauth_state_store=my_state_store,
+    )
+    conn = await omni.connection("conn_123")
+    calendar = conn.calendar()
+
+    async for event in calendar.list_events(calendar_id="primary"):
+        print(event.summary)
+"""
+
+from omnidapter.auth.models import (
+    ApiKeyCredentials,
+    BaseCredentials,
+    BasicCredentials,
+    OAuth2Credentials,
+)
+from omnidapter.core.errors import (
+    AuthError,
+    ConnectionNotFoundError,
+    InvalidCredentialFormatError,
+    OAuthStateError,
+    OmnidapterError,
+    ProviderAPIError,
+    ProviderNotConfiguredError,
+    RateLimitError,
+    ScopeInsufficientError,
+    TokenRefreshError,
+    TransportError,
+    UnsupportedCapabilityError,
+)
+from omnidapter.core.metadata import AuthKind, ProviderMetadata, ServiceKind
+from omnidapter.core.omnidapter import Omnidapter
+from omnidapter.core.registry import ProviderRegistry
+from omnidapter.services.calendar.capabilities import CalendarCapability
+from omnidapter.services.calendar.models import (
+    Attendee,
+    AvailabilityResponse,
+    Calendar,
+    CalendarEvent,
+    ConferenceData,
+    EventStatus,
+    Organizer,
+    Recurrence,
+)
+from omnidapter.services.calendar.requests import (
+    CreateCalendarRequest,
+    CreateEventRequest,
+    GetAvailabilityRequest,
+    UpdateCalendarRequest,
+    UpdateEventRequest,
+)
+from omnidapter.stores.credentials import CredentialStore, StoredCredential
+from omnidapter.stores.memory import InMemoryCredentialStore, InMemoryOAuthStateStore
+from omnidapter.stores.oauth_state import OAuthStateStore
+from omnidapter.transport.retry import RetryPolicy
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Omnidapter",
+    # Errors
+    "OmnidapterError",
+    "AuthError",
+    "OAuthStateError",
+    "ProviderNotConfiguredError",
+    "TokenRefreshError",
+    "UnsupportedCapabilityError",
+    "ConnectionNotFoundError",
+    "InvalidCredentialFormatError",
+    "ScopeInsufficientError",
+    "TransportError",
+    "ProviderAPIError",
+    "RateLimitError",
+    # Auth
+    "BaseCredentials",
+    "OAuth2Credentials",
+    "ApiKeyCredentials",
+    "BasicCredentials",
+    # Stores
+    "StoredCredential",
+    "CredentialStore",
+    "OAuthStateStore",
+    "InMemoryCredentialStore",
+    "InMemoryOAuthStateStore",
+    # Transport
+    "RetryPolicy",
+    # Registry
+    "ProviderRegistry",
+    # Metadata
+    "AuthKind",
+    "ServiceKind",
+    "ProviderMetadata",
+    # Calendar
+    "CalendarCapability",
+    "CalendarEvent",
+    "EventStatus",
+    "Calendar",
+    "AvailabilityResponse",
+    "Attendee",
+    "Organizer",
+    "Recurrence",
+    "ConferenceData",
+    "CreateCalendarRequest",
+    "CreateEventRequest",
+    "UpdateCalendarRequest",
+    "UpdateEventRequest",
+    "GetAvailabilityRequest",
+    # Version
+    "__version__",
+]

omnidapter/auth/__init__.py

@@ -0,0 +1,13 @@
+from omnidapter.auth.models import (
+    ApiKeyCredentials,
+    BaseCredentials,
+    BasicCredentials,
+    OAuth2Credentials,
+)
+
+__all__ = [
+    "BaseCredentials",
+    "OAuth2Credentials",
+    "ApiKeyCredentials",
+    "BasicCredentials",
+]

omnidapter/auth/kinds.py

@@ -0,0 +1,5 @@
+"""Auth kind enumeration (re-exported from core.metadata for convenience)."""
+
+from omnidapter.core.metadata import AuthKind
+
+__all__ = ["AuthKind"]

omnidapter/auth/models.py

@@ -0,0 +1,63 @@
+"""
+Typed credential payload models.
+
+These are the auth-kind-specific payloads stored inside a ``StoredCredential``.
+Every concrete credential type must inherit from :class:`BaseCredentials` so that
+calling code can use ``isinstance(creds, BaseCredentials)`` to distinguish a
+credential envelope's payload from arbitrary dicts.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class BaseCredentials(BaseModel):
+    """Base class for all credential payload types.
+
+    ``OAuth2Credentials``, ``ApiKeyCredentials``, and ``BasicCredentials`` all
+    inherit from this class.  It is the common base for ``isinstance`` checks
+    and an extension point for shared behaviour in future auth kinds.
+
+    Consuming apps that implement custom credential types for non-standard
+    auth schemes should also inherit from ``BaseCredentials`` so that
+    ``StoredCredential.credentials`` remains uniformly typed.
+    """
+
+
+class OAuth2Credentials(BaseCredentials):
+    """OAuth2 token payload."""
+
+    access_token: str
+    refresh_token: str | None = None
+    token_type: str = "Bearer"
+    expires_at: datetime | None = None  # UTC
+    id_token: str | None = None
+    raw: dict[str, Any] = Field(default_factory=dict)
+
+    def is_expired(self, buffer_seconds: float = 60.0) -> bool:
+        """Return True if the access token is expired (or within *buffer_seconds* of expiry)."""
+        if self.expires_at is None:
+            return False
+        return datetime.now(tz=timezone.utc) >= self.expires_at - timedelta(seconds=buffer_seconds)
+
+    def is_refreshable(self) -> bool:
+        """Return True if a refresh_token is available."""
+        return self.refresh_token is not None
+
+
+class ApiKeyCredentials(BaseCredentials):
+    """API key auth payload."""
+
+    api_key: str
+    header_name: str = "X-API-Key"
+
+
+class BasicCredentials(BaseCredentials):
+    """HTTP Basic auth payload."""
+
+    username: str
+    password: str

omnidapter/auth/oauth.py

@@ -0,0 +1,215 @@
+"""
+OAuth 2.0 flow helpers — begin and complete flows.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import secrets
+import urllib.parse
+from datetime import datetime, timedelta, timezone
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel
+
+from omnidapter.core.logging import auth_logger
+
+if TYPE_CHECKING:
+    import httpx
+
+    from omnidapter.core.registry import ProviderRegistry
+    from omnidapter.stores.credentials import CredentialStore
+    from omnidapter.stores.oauth_state import OAuthStateStore
+    from omnidapter.transport.hooks import TransportHooks
+    from omnidapter.transport.retry import RetryPolicy
+
+
+class OAuthBeginResult(BaseModel):
+    """Result of beginning an OAuth flow."""
+
+    authorization_url: str
+    state: str
+    connection_id: str
+    provider: str
+
+
+class OAuthPendingState(BaseModel):
+    """Payload stored in the OAuthStateStore during a pending OAuth flow."""
+
+    connection_id: str
+    provider: str
+    redirect_uri: str
+    code_verifier: str | None = None
+    expires_at: datetime  # UTC
+
+
+def _generate_pkce_pair() -> tuple[str, str]:
+    """Generate a PKCE code_verifier and code_challenge pair (S256 method)."""
+    import base64
+
+    verifier = secrets.token_urlsafe(64)
+    challenge = (
+        base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).rstrip(b"=").decode()
+    )
+    return verifier, challenge
+
+
+class OAuthHelper:
+    """Manages OAuth begin/complete flows with automatic credential persistence."""
+
+    def __init__(
+        self,
+        registry: ProviderRegistry,
+        credential_store: CredentialStore,
+        oauth_state_store: OAuthStateStore,
+        retry_policy: RetryPolicy | None = None,
+        hooks: TransportHooks | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._registry = registry
+        self._credential_store = credential_store
+        self._oauth_state_store = oauth_state_store
+        self._retry_policy = retry_policy
+        self._hooks = hooks
+        self._http_client = http_client
+
+    def _configure_provider_transport(self, provider_impl: Any) -> None:
+        configure = getattr(provider_impl, "configure_oauth_transport", None)
+        if callable(configure):
+            configure(
+                retry_policy=self._retry_policy,
+                hooks=self._hooks,
+                http_client=self._http_client,
+            )
+
+    async def begin(
+        self,
+        provider: str,
+        connection_id: str,
+        redirect_uri: str,
+        scopes: list[str] | None = None,
+        extra_params: dict[str, str] | None = None,
+    ) -> OAuthBeginResult:
+        """Begin an OAuth flow.
+
+        Generates authorization URL, persists temporary state, returns the redirect URL.
+        """
+        provider_impl = self._registry.get(provider)
+        oauth_config = provider_impl.get_oauth_config()
+        if oauth_config is None:
+            raise ValueError(f"Provider {provider!r} does not support OAuth2")
+
+        state_id = secrets.token_urlsafe(32)
+        code_verifier: str | None = None
+
+        params: dict[str, str] = {
+            "response_type": "code",
+            "client_id": oauth_config.client_id,
+            "redirect_uri": redirect_uri,
+            "state": state_id,
+        }
+
+        # Scopes
+        effective_scopes = scopes or oauth_config.default_scopes
+        if effective_scopes:
+            params["scope"] = oauth_config.scope_separator.join(effective_scopes)
+
+        # Provider-defined extra params (e.g. access_type=offline for Google)
+        if oauth_config.extra_auth_params:
+            params.update(oauth_config.extra_auth_params)
+
+        # PKCE
+        if oauth_config.supports_pkce:
+            code_verifier, code_challenge = _generate_pkce_pair()
+            params["code_challenge"] = code_challenge
+            params["code_challenge_method"] = "S256"
+
+        # Caller overrides last so they can always override provider defaults
+        if extra_params:
+            params.update(extra_params)
+
+        authorization_url = (
+            oauth_config.authorization_endpoint + "?" + urllib.parse.urlencode(params)
+        )
+
+        pending = OAuthPendingState(
+            connection_id=connection_id,
+            provider=provider,
+            redirect_uri=redirect_uri,
+            code_verifier=code_verifier,
+            expires_at=datetime.now(tz=timezone.utc) + timedelta(minutes=15),
+        )
+
+        await self._oauth_state_store.save_state(
+            state_id=state_id,
+            payload=pending.model_dump(mode="json"),
+            expires_at=pending.expires_at,
+        )
+
+        auth_logger.info(
+            "OAuth begin: provider=%r connection_id=%r",
+            provider,
+            connection_id,
+        )
+
+        return OAuthBeginResult(
+            authorization_url=authorization_url,
+            state=state_id,
+            connection_id=connection_id,
+            provider=provider,
+        )
+
+    async def complete(
+        self,
+        provider: str,
+        connection_id: str,
+        code: str,
+        state: str,
+        redirect_uri: str,
+    ) -> Any:
+        """Complete an OAuth flow.
+
+        Validates state, exchanges code for tokens, persists credentials.
+
+        Returns:
+            The StoredCredential (for inspection only — already persisted).
+        """
+        from omnidapter.core.errors import OAuthStateError
+
+        # Load and validate state
+        state_payload = await self._oauth_state_store.load_state(state)
+        if state_payload is None:
+            raise OAuthStateError("OAuth state not found or expired")
+
+        pending = OAuthPendingState.model_validate(state_payload)
+
+        if pending.connection_id != connection_id:
+            raise OAuthStateError("OAuth state connection_id mismatch")
+        if pending.provider != provider:
+            raise OAuthStateError("OAuth state provider mismatch")
+        if pending.redirect_uri != redirect_uri:
+            raise OAuthStateError("OAuth state redirect_uri mismatch")
+
+        # Exchange code for tokens
+        provider_impl = self._registry.get(provider)
+        self._configure_provider_transport(provider_impl)
+        stored_credential = await provider_impl.exchange_code_for_tokens(
+            connection_id=connection_id,
+            code=code,
+            redirect_uri=redirect_uri,
+            code_verifier=pending.code_verifier,
+        )
+
+        # Persist credentials
+        await self._credential_store.save_credentials(connection_id, stored_credential)
+
+        # Clean up state
+        await self._oauth_state_store.delete_state(state)
+
+        auth_logger.info(
+            "OAuth complete: provider=%r connection_id=%r",
+            provider,
+            connection_id,
+        )
+
+        return stored_credential

omnidapter/auth/refresh.py

@@ -0,0 +1,94 @@
+"""
+Automatic token refresh logic.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from omnidapter.core.logging import auth_logger
+
+if TYPE_CHECKING:
+    import httpx
+
+    from omnidapter.core.registry import ProviderRegistry
+    from omnidapter.stores.credentials import CredentialStore, StoredCredential
+    from omnidapter.transport.hooks import TransportHooks
+    from omnidapter.transport.retry import RetryPolicy
+
+
+class TokenRefreshManager:
+    """Manages automatic token refresh for OAuth2 credentials."""
+
+    def __init__(
+        self,
+        registry: ProviderRegistry,
+        credential_store: CredentialStore,
+        retry_policy: RetryPolicy | None = None,
+        hooks: TransportHooks | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._registry = registry
+        self._credential_store = credential_store
+        self._retry_policy = retry_policy
+        self._hooks = hooks
+        self._http_client = http_client
+
+    def _configure_provider_transport(self, provider_impl: object) -> None:
+        configure = getattr(provider_impl, "configure_oauth_transport", None)
+        if callable(configure):
+            configure(
+                retry_policy=self._retry_policy,
+                hooks=self._hooks,
+                http_client=self._http_client,
+            )
+
+    async def ensure_fresh(self, connection_id: str) -> StoredCredential:
+        """Ensure credentials are fresh, refreshing if necessary.
+
+        Returns:
+            Fresh StoredCredential.
+        """
+        from omnidapter.auth.models import OAuth2Credentials
+        from omnidapter.core.metadata import AuthKind
+
+        stored = await self._credential_store.get_credentials(connection_id)
+        if stored is None:
+            from omnidapter.core.errors import ConnectionNotFoundError
+
+            raise ConnectionNotFoundError(connection_id)
+
+        # Only refresh OAuth2 credentials
+        if stored.auth_kind != AuthKind.OAUTH2:
+            return stored
+
+        creds = stored.credentials
+        if not isinstance(creds, OAuth2Credentials):
+            return stored
+
+        if not creds.is_expired():
+            return stored
+
+        if not creds.is_refreshable():
+            auth_logger.warning(
+                "Token expired but no refresh_token available: connection_id=%r",
+                connection_id,
+            )
+            return stored
+
+        auth_logger.info("Refreshing token: connection_id=%r", connection_id)
+
+        provider_impl = self._registry.get(stored.provider_key)
+        self._configure_provider_transport(provider_impl)
+        updated = await provider_impl.refresh_token(stored)
+
+        # Persist updated credentials
+        await self._credential_store.save_credentials(connection_id, updated)
+
+        auth_logger.info(
+            "Token refreshed successfully: connection_id=%r provider=%r",
+            connection_id,
+            stored.provider_key,
+        )
+
+        return updated

omnidapter/core/connection.py

@@ -0,0 +1,106 @@
+"""
+Connection represents authorization to a provider account.
+
+Services are accessed from a connection.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import TYPE_CHECKING, Any
+
+from omnidapter.core.metadata import ServiceKind
+
+if TYPE_CHECKING:
+    import httpx
+
+    from omnidapter.core.registry import ProviderRegistry
+    from omnidapter.services.calendar.interface import CalendarService
+    from omnidapter.stores.credentials import StoredCredential
+    from omnidapter.transport.hooks import TransportHooks
+    from omnidapter.transport.retry import RetryPolicy
+
+
+class Connection:
+    """Represents an authorized connection to a provider account.
+
+    Services are accessed through a connection:
+
+        conn = await omni.connection("conn_123")
+        calendar = conn.calendar()
+        await calendar.list_calendars()
+    """
+
+    def __init__(
+        self,
+        connection_id: str,
+        stored_credential: StoredCredential,
+        registry: ProviderRegistry,
+        retry_policy: RetryPolicy | None = None,
+        hooks: TransportHooks | None = None,
+        credential_resolver: Callable[[str], Awaitable[StoredCredential]] | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._connection_id = connection_id
+        self._stored = stored_credential
+        self._registry = registry
+        self._retry_policy = retry_policy
+        self._hooks = hooks
+        self._credential_resolver = credential_resolver
+        self._http_client = http_client
+
+    @property
+    def connection_id(self) -> str:
+        return self._connection_id
+
+    @property
+    def provider_key(self) -> str:
+        return self._stored.provider_key
+
+    @property
+    def stored_credential(self) -> StoredCredential:
+        return self._stored
+
+    def supports(self, service: ServiceKind) -> bool:
+        """Return True if the provider for this connection supports the given service."""
+        provider = self._registry.get(self._stored.provider_key)
+        return service in provider.metadata.services
+
+    def _configure_service_runtime(self, service: CalendarService) -> CalendarService:
+        service_runtime: Any = service
+
+        if self._credential_resolver is not None:
+            service_runtime._credential_resolver = self._credential_resolver
+
+        if self._http_client is not None:
+            transport = getattr(service_runtime, "_http", None)
+            set_shared_client = getattr(transport, "set_shared_client", None)
+            if callable(set_shared_client):
+                set_shared_client(self._http_client)
+
+        return service
+
+    def calendar(self) -> CalendarService:
+        """Return the calendar service for this connection.
+
+        Raises:
+            UnsupportedCapabilityError: If the provider does not support calendars.
+            Use ``conn.supports(ServiceKind.CALENDAR)`` to check first.
+        """
+        if not self.supports(ServiceKind.CALENDAR):
+            from omnidapter.core.errors import UnsupportedCapabilityError
+
+            raise UnsupportedCapabilityError(
+                f"Provider {self._stored.provider_key!r} does not support calendars. "
+                "Check conn.supports(ServiceKind.CALENDAR) before calling conn.calendar().",
+                provider_key=self._stored.provider_key,
+                capability=ServiceKind.CALENDAR,
+            )
+        provider = self._registry.get(self._stored.provider_key)
+        service = provider.get_calendar_service(
+            connection_id=self._connection_id,
+            stored_credential=self._stored,
+            retry_policy=self._retry_policy,
+            hooks=self._hooks,
+        )
+        return self._configure_service_runtime(service)