mobiscroll-connect-sdk 1.0.1__py3-none-any.whl

mobiscroll_connect/__init__.py

@@ -0,0 +1,68 @@
+"""Mobiscroll Connect SDK for Python.
+
+Calendar and event management across Google Calendar, Microsoft Outlook,
+Apple Calendar, and CalDAV through a single client.
+
+Quick start::
+
+    from mobiscroll_connect import MobiscrollConnectClient
+
+    with MobiscrollConnectClient("client-id", "client-secret", "https://app/callback") as client:
+        url = client.auth.generate_auth_url(user_id="user-123")
+        # ...exchange code, set credentials...
+        for event in client.events.iter_all(start="2024-01-01", end="2024-01-31"):
+            print(event.title)
+
+For asyncio, use :mod:`mobiscroll_connect.aio`::
+
+    from mobiscroll_connect.aio import AsyncMobiscrollConnectClient
+"""
+
+from .client import MobiscrollConnectClient
+from .config import Config
+from .exceptions import (
+    AuthenticationError,
+    MobiscrollConnectError,
+    NetworkError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from .models import (
+    Calendar,
+    CalendarEvent,
+    ConnectedAccount,
+    ConnectionStatusResponse,
+    DisconnectResponse,
+    EventAttendee,
+    EventsListResponse,
+    Provider,
+    TokenResponse,
+)
+
+__version__ = "1.0.1"
+
+__all__ = [
+    "AuthenticationError",
+    "Calendar",
+    "CalendarEvent",
+    "Config",
+    "ConnectedAccount",
+    "ConnectionStatusResponse",
+    "DisconnectResponse",
+    "EventAttendee",
+    "EventsListResponse",
+    "MobiscrollConnectClient",
+    # Exceptions
+    "MobiscrollConnectError",
+    "NetworkError",
+    "NotFoundError",
+    # Models
+    "Provider",
+    "RateLimitError",
+    "ServerError",
+    "TokenResponse",
+    "ValidationError",
+    "__version__",
+]

mobiscroll_connect/_internal/errors.py

@@ -0,0 +1,58 @@
+"""Maps HTTP responses to typed SDK exceptions. Shared by sync and async clients."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+
+from ..exceptions import (
+    AuthenticationError,
+    MobiscrollConnectError,
+    NetworkError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+
+
+def _safe_json(response: httpx.Response) -> Mapping[str, Any]:
+    try:
+        data = response.json()
+        return data if isinstance(data, Mapping) else {}
+    except Exception:
+        return {}
+
+
+def map_response_error(response: httpx.Response) -> MobiscrollConnectError:
+    """Map an HTTP response to a typed SDK exception."""
+    status = response.status_code
+    data = _safe_json(response)
+    message = str(data.get("message") or response.reason_phrase or f"HTTP {status}")
+
+    if status in (401, 403):
+        return AuthenticationError(message)
+    if status == 404:
+        return NotFoundError(message)
+    if status in (400, 422):
+        details = data.get("details") if isinstance(data, Mapping) else None
+        return ValidationError(message, details if isinstance(details, Mapping) else None)
+    if status == 429:
+        retry_after_raw = response.headers.get("retry-after")
+        retry_after: int | None = None
+        if retry_after_raw is not None:
+            try:
+                retry_after = int(retry_after_raw)
+            except (TypeError, ValueError):
+                retry_after = None
+        return RateLimitError(message, retry_after)
+    if status in (500, 502, 503, 504):
+        return ServerError(message, status)
+
+    return MobiscrollConnectError(message, code=str(data.get("code") or "UNKNOWN_ERROR"))
+
+
+def map_transport_error(exc: httpx.HTTPError) -> NetworkError:
+    return NetworkError(str(exc) or exc.__class__.__name__)

mobiscroll_connect/_internal/payloads.py

@@ -0,0 +1,100 @@
+"""Pure functions that build request payloads / queries from caller input.
+
+Kept separate from the API client so they can be unit-tested in isolation and
+reused by both the sync and async resources.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable, Mapping
+from datetime import datetime, timezone
+from typing import Any, Union
+
+DateLike = Union[datetime, str]
+
+_LIST_QUERY_KEYS_PASSTHROUGH = ("provider", "calendarId", "eventId", "recurringEventId", "deleteMode")
+
+
+def format_datetime(value: DateLike) -> str:
+    """Convert to ISO 8601 with a ``Z`` suffix when UTC. String input is passed through."""
+    if isinstance(value, datetime):
+        if value.tzinfo is None:
+            value = value.replace(tzinfo=timezone.utc)
+        iso = value.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+        return iso
+    return str(value)
+
+
+def build_list_events_query(
+    *,
+    start: DateLike | None = None,
+    end: DateLike | None = None,
+    calendar_ids: Mapping[str, Iterable[str]] | None = None,
+    page_size: int | None = None,
+    next_page_token: str | None = None,
+    single_events: bool | None = None,
+) -> dict[str, str]:
+    """Build the query string for ``GET /events``. All values are stringified."""
+    query: dict[str, str] = {}
+
+    if start is not None:
+        query["start"] = format_datetime(start)
+    if end is not None:
+        query["end"] = format_datetime(end)
+    if calendar_ids is not None:
+        # Convert iterables to lists so json.dumps emits arrays.
+        normalized = {k: list(v) for k, v in calendar_ids.items()}
+        query["calendarIds"] = json.dumps(normalized, separators=(",", ":"))
+    if page_size is not None:
+        query["pageSize"] = str(min(int(page_size), 1000))
+    if next_page_token is not None:
+        query["nextPageToken"] = str(next_page_token)
+    if single_events is not None:
+        # API expects string booleans in query string.
+        query["singleEvents"] = "true" if single_events else "false"
+
+    return query
+
+
+def build_event_payload(event: Mapping[str, Any]) -> dict[str, Any]:
+    """Normalize a snake_case-friendly event dict into the API's camelCase shape.
+
+    Accepts both wire-format keys (``calendarId``, ``allDay``) and Pythonic ones
+    (``calendar_id``, ``all_day``). Datetime fields are formatted to ISO 8601.
+    """
+    snake_to_camel = {
+        "calendar_id": "calendarId",
+        "event_id": "eventId",
+        "recurring_event_id": "recurringEventId",
+        "update_mode": "updateMode",
+        "delete_mode": "deleteMode",
+        "all_day": "allDay",
+    }
+
+    payload: dict[str, Any] = {}
+    for key, value in event.items():
+        out_key = snake_to_camel.get(key, key)
+        if out_key in ("start", "end") and value is not None:
+            payload[out_key] = format_datetime(value)
+        else:
+            payload[out_key] = value
+
+    return payload
+
+
+def build_delete_query(params: Mapping[str, Any]) -> dict[str, str]:
+    """Build the query string for ``DELETE /event``. Validates required keys."""
+    payload = build_event_payload(params)
+    query: dict[str, str] = {}
+    for key in _LIST_QUERY_KEYS_PASSTHROUGH:
+        value = payload.get(key)
+        if value is not None and value != "":
+            query[key] = str(value)
+
+    snake_for_error = {"provider": "provider", "calendarId": "calendar_id", "eventId": "event_id"}
+    for required in ("provider", "calendarId", "eventId"):
+        if required not in query:
+            raise ValueError(f"{snake_for_error[required]} is required for event deletion")
+
+    return query

mobiscroll_connect/aio/__init__.py

@@ -0,0 +1,11 @@
+"""Async API. Mirrors the sync surface — every method is a coroutine."""
+
+from .client import AsyncMobiscrollConnectClient
+from .resources import AsyncAuth, AsyncCalendars, AsyncEvents
+
+__all__ = [
+    "AsyncAuth",
+    "AsyncCalendars",
+    "AsyncEvents",
+    "AsyncMobiscrollConnectClient",
+]

mobiscroll_connect/aio/client.py

@@ -0,0 +1,69 @@
+"""Public async client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from ..async_api_client import AsyncApiClient, AsyncTokensRefreshedCallback
+from ..config import Config
+from ..models import TokenResponse
+from .resources import AsyncAuth, AsyncCalendars, AsyncEvents
+
+
+class AsyncMobiscrollConnectClient:
+    """Async variant of :class:`mobiscroll_connect.MobiscrollConnectClient`.
+
+    Use as an async context manager to release the connection pool::
+
+        async with AsyncMobiscrollConnectClient(...) as client:
+            calendars = await client.calendars.list()
+    """
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str,
+        redirect_uri: str,
+        *,
+        base_url: str | None = None,
+        timeout: float | None = None,
+        http_client: httpx.AsyncClient | None = None,
+        on_tokens_refreshed: AsyncTokensRefreshedCallback | None = None,
+    ) -> None:
+        config_kwargs: dict[str, Any] = {"client_id": client_id, "client_secret": client_secret, "redirect_uri": redirect_uri}
+        if base_url is not None:
+            config_kwargs["base_url"] = base_url
+        if timeout is not None:
+            config_kwargs["timeout"] = timeout
+
+        self._config = Config(**config_kwargs)
+        self._api = AsyncApiClient(
+            self._config,
+            http_client=http_client,
+            on_tokens_refreshed=on_tokens_refreshed,
+        )
+        self.auth = AsyncAuth(self._api)
+        self.calendars = AsyncCalendars(self._api)
+        self.events = AsyncEvents(self._api)
+
+    @property
+    def config(self) -> Config:
+        return self._config
+
+    def set_credentials(self, tokens: TokenResponse) -> None:
+        """Shortcut for ``client.auth.set_credentials(tokens)``."""
+        self.auth.set_credentials(tokens)
+
+    def on_tokens_refreshed(self, callback: AsyncTokensRefreshedCallback) -> None:
+        self._api.on_tokens_refreshed(callback)
+
+    async def aclose(self) -> None:
+        await self._api.aclose()
+
+    async def __aenter__(self) -> AsyncMobiscrollConnectClient:
+        return self
+
+    async def __aexit__(self, *exc_info: Any) -> None:
+        await self.aclose()

mobiscroll_connect/aio/resources.py

@@ -0,0 +1,185 @@
+from __future__ import annotations
+
+import base64
+from collections.abc import AsyncIterator, Iterable, Mapping
+from typing import Any, Union
+from urllib.parse import urlencode
+
+from .._internal.payloads import (
+    DateLike,
+    build_delete_query,
+    build_event_payload,
+    build_list_events_query,
+)
+from ..async_api_client import AsyncApiClient
+from ..exceptions import MobiscrollConnectError, ServerError
+from ..models import (
+    Calendar,
+    CalendarEvent,
+    ConnectionStatusResponse,
+    DisconnectResponse,
+    EventsListResponse,
+    Provider,
+    TokenResponse,
+)
+
+ProviderLike = Union[str, Provider]
+
+
+class AsyncAuth:
+    def __init__(self, api_client: AsyncApiClient) -> None:
+        self._api = api_client
+
+    def generate_auth_url(
+        self,
+        user_id: str,
+        *,
+        scope: str = "calendar",
+        state: str | None = None,
+        providers: str | None = None,
+    ) -> str:
+        cfg = self._api.config
+        params = {
+            "client_id": cfg.client_id,
+            "response_type": "code",
+            "user_id": user_id,
+            "redirect_uri": cfg.redirect_uri,
+            "scope": scope,
+        }
+        if state is not None:
+            params["state"] = state
+        if providers is not None:
+            params["providers"] = providers
+        return f"{self._api.base_url}/oauth/authorize?{urlencode(params)}"
+
+    async def get_token(self, code: str) -> TokenResponse:
+        cfg = self._api.config
+        credentials = base64.b64encode(
+            f"{cfg.client_id}:{cfg.client_secret}".encode()
+        ).decode()
+
+        data = await self._api.post_form(
+            "oauth/token",
+            form={
+                "grant_type": "authorization_code",
+                "code": code,
+                "redirect_uri": cfg.redirect_uri,
+            },
+            headers={
+                "Authorization": f"Basic {credentials}",
+                "CLIENT_ID": cfg.client_id,
+            },
+        )
+        tokens = TokenResponse.from_dict(data or {})
+        self._api.set_credentials(tokens)
+        return tokens
+
+    def set_credentials(self, tokens: TokenResponse) -> None:
+        self._api.set_credentials(tokens)
+
+    async def get_connection_status(self) -> ConnectionStatusResponse:
+        try:
+            data = await self._api.get("oauth/connection-status")
+        except MobiscrollConnectError:
+            data = await self._api.get("connection-status")
+        return ConnectionStatusResponse.from_dict(data or {})
+
+    async def disconnect(
+        self,
+        provider: ProviderLike,
+        *,
+        account: str | None = None,
+    ) -> DisconnectResponse:
+        params = {"provider": str(provider.value if isinstance(provider, Provider) else provider)}
+        if account:
+            params["account"] = account
+        try:
+            data = await self._api.post("oauth/disconnect", json={}, params=params)
+        except MobiscrollConnectError:
+            data = await self._api.post("disconnect", json={}, params=params)
+        return DisconnectResponse.from_dict(data or {})
+
+
+class AsyncCalendars:
+    def __init__(self, api_client: AsyncApiClient) -> None:
+        self._api = api_client
+
+    async def list(self) -> list[Calendar]:
+        data = await self._api.get("calendars")
+        if not isinstance(data, list):
+            return []
+        return [Calendar.from_dict(c) for c in data if isinstance(c, Mapping)]
+
+
+class AsyncEvents:
+    def __init__(self, api_client: AsyncApiClient) -> None:
+        self._api = api_client
+
+    async def list(
+        self,
+        *,
+        start: DateLike | None = None,
+        end: DateLike | None = None,
+        calendar_ids: Mapping[str, Iterable[str]] | None = None,
+        page_size: int | None = None,
+        next_page_token: str | None = None,
+        single_events: bool | None = None,
+    ) -> EventsListResponse:
+        query = build_list_events_query(
+            start=start,
+            end=end,
+            calendar_ids=calendar_ids,
+            page_size=page_size,
+            next_page_token=next_page_token,
+            single_events=single_events,
+        )
+        data = await self._api.get("events", params=query or None)
+        return EventsListResponse.from_dict(data if isinstance(data, Mapping) else {})
+
+    async def iter_all(
+        self,
+        *,
+        start: DateLike | None = None,
+        end: DateLike | None = None,
+        calendar_ids: Mapping[str, Iterable[str]] | None = None,
+        page_size: int | None = None,
+        single_events: bool | None = None,
+    ) -> AsyncIterator[CalendarEvent]:
+        token: str | None = None
+        while True:
+            page = await self.list(
+                start=start,
+                end=end,
+                calendar_ids=calendar_ids,
+                page_size=page_size,
+                next_page_token=token,
+                single_events=single_events,
+            )
+            for event in page.events:
+                yield event
+            if not page.next_page_token:
+                return
+            token = page.next_page_token
+
+    async def create(self, event: Mapping[str, Any]) -> CalendarEvent:
+        payload = build_event_payload(event)
+        response = await self._api.post("event", json=payload)
+        return self._extract_event(response, "create")
+
+    async def update(self, event: Mapping[str, Any]) -> CalendarEvent:
+        payload = build_event_payload(event)
+        response = await self._api.put("event", json=payload)
+        return self._extract_event(response, "update")
+
+    async def delete(self, params: Mapping[str, Any]) -> None:
+        query = build_delete_query(params)
+        response = await self._api.delete("event", params=query)
+        if isinstance(response, Mapping) and response.get("success") is False:
+            raise ServerError(str(response.get("message") or "Failed to delete event"), 400)
+
+    @staticmethod
+    def _extract_event(response: Any, operation: str) -> CalendarEvent:
+        if isinstance(response, Mapping) and isinstance(response.get("event"), Mapping):
+            return CalendarEvent.from_dict(response["event"])
+        msg = response.get("message") if isinstance(response, Mapping) else None
+        raise ServerError(msg if isinstance(msg, str) else f"Failed to {operation} event", 400)