mobiscroll-connect-sdk 1.0.1__tar.gz

mobiscroll_connect_sdk-1.0.1/.gitignore

@@ -0,0 +1,20 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+.venv/
+venv/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Environment — copy .env.example to .env and fill in your credentials
+examples/.env
+.env
+
+# IDE
+.DS_Store
+.vscode/
+.idea/

mobiscroll_connect_sdk-1.0.1/CLAUDE.md

@@ -0,0 +1,161 @@
+# CLAUDE.md — Mobiscroll Connect Python SDK
+
+## AI Assistant Guidelines
+
+Communication:
+
+- Be extremely concise. Skip introductory and concluding fluff. Get straight to the answer.
+- If a question is about code, provide the code block first, then explain briefly afterward.
+- Never hallucinate. If you don't know something or a library version is too new, say so immediately.
+- Focus on architectural patterns, edge cases, and optimization. Do not explain basic programming concepts.
+
+Coding Standards:
+
+- Default to Python 3.9+ compatible code with type annotations throughout.
+- Favor modular, reusable code. Include proper error handling and edge cases; do not just provide the "happy path."
+- Keep logic decoupled from transport concerns where possible.
+
+Formatting:
+
+- When modifying existing code, provide the entire function or class for easy copy-pasting. Never truncate code with comments like `# ... rest of code` unless the file is excessively long.
+- Type annotations are required on all public methods and module-level functions.
+
+## Project Overview
+
+Python 3.9+ client library for the Mobiscroll Connect API. Enables calendar and event management across Google Calendar, Microsoft Outlook, Apple Calendar, and CalDAV through a single SDK.
+
+- **PyPI**: `mobiscroll-connect-sdk`
+- **Package**: `mobiscroll_connect`
+- **HTTP client**: httpx (sync + async, same API surface)
+- **Test framework**: pytest + pytest-asyncio + respx
+- **Static analysis**: mypy (strict), ruff
+
+---
+
+## Architecture
+
+```
+MobiscrollConnectClient        — public sync entry point; constructs and wires all internals
+  └── ApiClient                — sync HTTP layer (httpx); auth headers; token refresh; error mapping
+        ├── resources/Auth     — generate_auth_url, get_token, set_credentials, get_connection_status, disconnect
+        ├── resources/Calendars — list()
+        └── resources/Events   — list(), iter_all(), create(), update(), delete()
+
+mobiscroll_connect.aio:
+AsyncMobiscrollConnectClient   — async counterpart; identical public API, all methods are coroutines
+  └── AsyncApiClient           — async HTTP layer (httpx.AsyncClient); asyncio.Lock for refresh dedup
+        ├── aio/resources/AsyncAuth, AsyncCalendars, AsyncEvents
+
+Config                         — frozen dataclass: client_id, client_secret, redirect_uri, base_url, timeout
+TokenResponse                  — frozen dataclass: access_token, token_type, expires_in, refresh_token
+CalendarEvent                  — frozen dataclass for API event responses
+EventsListResponse             — frozen dataclass wrapping list[CalendarEvent] + pagination; iterable
+Calendar                       — frozen dataclass for calendar list entries
+ConnectionStatusResponse       — frozen dataclass for /oauth/connection-status
+DisconnectResponse             — frozen dataclass for /oauth/disconnect
+
+Exceptions:
+  MobiscrollConnectError       — base; .message and .code
+  AuthenticationError          — 401/403
+  ValidationError              — 400/422; .details
+  NotFoundError                — 404
+  RateLimitError               — 429; .retry_after
+  ServerError                  — 5xx; .status_code
+  NetworkError                 — transport failures
+
+_internal/errors.py            — map_response_error, map_transport_error (pure functions, shared by sync+async)
+_internal/payloads.py          — build_list_events_query, build_event_payload, build_delete_query (pure, shared)
+```
+
+### Token refresh
+
+`ApiClient` catches a 401 on every `get/post/put/delete` call. If a refresh token is stored, it acquires a `threading.Lock` (sync) or `asyncio.Lock` (async), POSTs to `oauth/token` with Basic auth (`base64(client_id:client_secret)`), merges the new tokens (preserving the old refresh token if the server does not issue a new one), invokes the `on_tokens_refreshed` callback, then retries the original request once. `post_form` is excluded from retry — it is the token exchange path itself.
+
+### Path normalisation
+
+All request paths are `lstrip`-ed to strip leading slashes. httpx `base_url` is `https://connect.mobiscroll.com/api` with paths resolved relatively.
+
+### Route fallbacks in Auth
+
+`get_connection_status` and `disconnect` attempt `/oauth/*` first, catch `MobiscrollConnectError`, then fall back to the legacy path without the `/oauth` prefix. This matches PHP SDK behavior and handles older server deployments.
+
+---
+
+## Essential Commands
+
+```bash
+# Install in editable mode with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Single test file
+pytest tests/test_auth.py -v
+
+# Type checking
+mypy mobiscroll_connect
+
+# Linting
+ruff check mobiscroll_connect tests
+
+# Run the minimal Flask test app
+cd minimal-app
+pip install -r requirements.txt
+python app.py
+# Open http://localhost:8000/?action=ui
+```
+
+---
+
+## File Map
+
+| File                                       | Purpose                                                            |
+| ------------------------------------------ | ------------------------------------------------------------------ |
+| `mobiscroll_connect/client.py`             | Public sync API surface; constructs ApiClient + resources          |
+| `mobiscroll_connect/api_client.py`         | Sync HTTP methods, token refresh, error mapping                    |
+| `mobiscroll_connect/async_api_client.py`   | Async HTTP layer; identical surface, asyncio.Lock                  |
+| `mobiscroll_connect/aio/client.py`         | AsyncMobiscrollConnectClient                                       |
+| `mobiscroll_connect/aio/resources.py`      | AsyncAuth, AsyncCalendars, AsyncEvents                             |
+| `mobiscroll_connect/config.py`             | Immutable client config dataclass                                  |
+| `mobiscroll_connect/models.py`             | All response DTOs (frozen dataclasses with `from_dict` classmethods)|
+| `mobiscroll_connect/exceptions.py`         | Exception hierarchy                                                |
+| `mobiscroll_connect/resources/auth.py`     | OAuth flow methods                                                 |
+| `mobiscroll_connect/resources/calendars.py`| Calendar listing                                                   |
+| `mobiscroll_connect/resources/events.py`   | Event CRUD + iter_all pagination helper                            |
+| `mobiscroll_connect/_internal/errors.py`   | HTTP status → exception mapping (shared)                           |
+| `mobiscroll_connect/_internal/payloads.py` | Query/payload builders (shared, pure functions)                    |
+| `tests/`                                   | pytest tests (auth, calendars, events, models, payloads, async)    |
+| `minimal-app/app.py`                       | Reference Flask implementation (action-dispatch pattern)           |
+| `minimal-app/templates/`                   | Dark-theme UI pages (ui, calendars, events, event_edit)            |
+
+---
+
+## Coding Standards
+
+- All models are `@dataclass(frozen=True)` — no Pydantic, zero extra runtime dependencies.
+- Wire format is camelCase; all Python-facing properties are snake_case. `from_dict` classmethods handle the mapping.
+- Resources are attributes on the client (`client.events.list()`), not callable getters.
+- Use `from __future__ import annotations` on every file for forward-reference compatibility with Python 3.9.
+- No inline comments except where logic is genuinely non-obvious.
+
+---
+
+## Testing Patterns
+
+- HTTP is mocked with `respx` — each test function is decorated with `@respx.mock` (do not use it as a class decorator; it silently skips test methods in pytest).
+- Async tests use `pytest-asyncio` with `asyncio_mode = "auto"` in `pyproject.toml` — no `@pytest.mark.asyncio` needed.
+- `tests/conftest.py` provides a `make_client()` fixture with dummy credentials.
+- Do not mock model parsing with hardcoded strings; prefer calling `from_dict` directly in unit tests.
+
+---
+
+## Key Invariants
+
+- `post_form` never retries on 401 — it is the token exchange path itself.
+- Token merge on refresh: `refresh_token = new_tokens.refresh_token or current.refresh_token`.
+- `build_list_events_query` caps `page_size` at 1000 and serialises `single_events` as `"true"`/`"false"` strings (not booleans) — it goes into a URL query string.
+- `CalendarEvent.from_dict` raises `ValueError` for missing required fields (`provider`, `id`, `calendarId`).
+- All HTTP verbs set `Authorization: Bearer {token}` headers — never embed tokens in query strings or bodies.
+- `on_tokens_refreshed` callback exceptions are swallowed — persistence failures must not break the refresh path.
+- The async `on_tokens_refreshed` callback can be sync or async; `AsyncApiClient` detects coroutines via `asyncio.iscoroutine` and awaits them.

mobiscroll_connect_sdk-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mobiscroll
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mobiscroll_connect_sdk-1.0.1/PKG-INFO

@@ -0,0 +1,339 @@
+Metadata-Version: 2.4
+Name: mobiscroll-connect-sdk
+Version: 1.0.1
+Summary: Python client for the Mobiscroll Connect API — calendar and event management across Google, Microsoft, Apple, and CalDAV.
+Project-URL: Homepage, https://mobiscroll.com/connect
+Project-URL: Documentation, https://mobiscroll.com/docs/connect/python-sdk
+Project-URL: Source, https://github.com/acidb/mobiscroll-connect-sdks
+Author: Mobiscroll
+License: MIT
+License-File: LICENSE
+Keywords: caldav,calendar,google-calendar,mobiscroll,oauth2,outlook
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Scheduling
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1.0,>=0.24
+Requires-Dist: typing-extensions>=4.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: python-dotenv>=1.0; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Mobiscroll Connect Python SDK
+
+Python client for the Mobiscroll Connect API — calendar and event management across Google Calendar, Microsoft Outlook, Apple Calendar, and CalDAV through a single SDK.
+
+📖 **[Full documentation](https://mobiscroll.com/docs/connect/python-sdk)**
+
+## Features
+
+- **Multi-provider**: Google, Microsoft, Apple, CalDAV
+- **OAuth2**: full authorization-code flow
+- **Automatic token refresh** with persistence callback
+- **Sync and async** clients (`MobiscrollConnectClient` / `mobiscroll_connect.aio.AsyncMobiscrollConnectClient`)
+- **Typed responses** via frozen dataclasses
+- **Typed exception hierarchy** for HTTP errors
+- **Pagination** helpers (`iter_all` traverses every page)
+- **Type-checked** (`py.typed` shipped)
+
+## Installation
+
+```bash
+pip install mobiscroll-connect-sdk
+```
+
+Requires Python 3.9+.
+
+## Quick start
+
+```python
+from mobiscroll_connect import MobiscrollConnectClient
+
+with MobiscrollConnectClient(
+    client_id="YOUR_CLIENT_ID",
+    client_secret="YOUR_CLIENT_SECRET",
+    redirect_uri="https://yourapp.example/oauth/callback",
+) as client:
+    # 1. Build the auth URL and redirect the user
+    auth_url = client.auth.generate_auth_url(user_id="user-123")
+
+    # 2. After callback: exchange the code for tokens
+    tokens = client.auth.get_token(code="...")
+
+    # 3. Use the API
+    for calendar in client.calendars.list():
+        print(calendar.provider, calendar.title)
+```
+
+## OAuth2 flow
+
+```python
+# Step 1 — generate auth URL (server-side)
+auth_url = client.auth.generate_auth_url(
+    user_id="user-123",
+    scope="calendar",       # optional
+    state="csrf-value",     # optional
+    providers="google,microsoft",  # optional
+)
+
+# Step 2 — exchange the code (in your callback handler)
+tokens = client.auth.get_token(code=request.query_params["code"])
+
+# Persist tokens.access_token, tokens.refresh_token, tokens.expires_in
+
+# Step 3 — restore credentials on subsequent requests
+from mobiscroll_connect import TokenResponse
+
+client.auth.set_credentials(TokenResponse(
+    access_token=session["access_token"],
+    refresh_token=session["refresh_token"],
+    expires_in=session["expires_in"],
+))
+```
+
+## Automatic token refresh
+
+When a request returns `401 Unauthorized` and a refresh token is present, the SDK transparently refreshes and retries. Register a callback to persist the new tokens:
+
+```python
+def persist_tokens(tokens):
+    db.update_tokens(user_id, tokens.to_dict())
+
+client.on_tokens_refreshed(persist_tokens)
+```
+
+If the refresh itself fails (revoked, expired), `AuthenticationError` is raised — re-authorize the user.
+
+## Calendars
+
+```python
+calendars = client.calendars.list()
+for cal in calendars:
+    print(f"{cal.provider}: {cal.title} ({cal.id})")
+```
+
+## Events
+
+### List events
+
+```python
+from datetime import datetime
+
+response = client.events.list(
+    start=datetime(2024, 1, 1),
+    end=datetime(2024, 1, 31),
+    calendar_ids={"google": ["primary"]},
+    page_size=50,
+)
+
+for event in response:           # EventsListResponse is iterable
+    print(event.title, event.start, event.end)
+
+if response.has_more:
+    next_page = client.events.list(
+        next_page_token=response.next_page_token,
+        page_size=50,
+    )
+```
+
+### Iterate all pages
+
+```python
+for event in client.events.iter_all(
+    start=datetime(2024, 1, 1),
+    end=datetime(2024, 12, 31),
+    page_size=250,
+):
+    process(event)
+```
+
+### Create
+
+```python
+event = client.events.create({
+    "provider": "google",
+    "calendar_id": "primary",
+    "title": "Team Meeting",
+    "start": "2024-06-15T10:00:00Z",
+    "end": "2024-06-15T11:00:00Z",
+    "description": "Quarterly review",
+    "location": "Conference Room A",
+})
+print("Created:", event.id)
+```
+
+### Update
+
+```python
+client.events.update({
+    "provider": "google",
+    "calendar_id": "primary",
+    "event_id": "evt-123",
+    "title": "Team Meeting (Rescheduled)",
+    "start": "2024-06-15T14:00:00Z",
+    "end": "2024-06-15T15:00:00Z",
+})
+```
+
+### Delete
+
+```python
+client.events.delete({
+    "provider": "google",
+    "calendar_id": "primary",
+    "event_id": "evt-123",
+})
+```
+
+### Recurring events
+
+```python
+# Update only this instance
+client.events.update({
+    "provider": "google",
+    "calendar_id": "primary",
+    "event_id": "instance-id",
+    "recurring_event_id": "series-id",
+    "update_mode": "this",
+    "title": "One-off change",
+})
+
+# Delete this and all following instances
+client.events.delete({
+    "provider": "google",
+    "calendar_id": "primary",
+    "event_id": "instance-id",
+    "recurring_event_id": "series-id",
+    "delete_mode": "following",
+})
+```
+
+## Connection management
+
+```python
+status = client.auth.get_connection_status()
+for provider, accounts in status.connections.items():
+    print(f"{provider}: {len(accounts)} account(s)")
+
+if status.limit_reached:
+    print(f"Connection limit of {status.limit} reached")
+
+# Disconnect a single account
+client.auth.disconnect("google", account="user@gmail.com")
+
+# Or all accounts of a provider
+client.auth.disconnect("microsoft")
+```
+
+## Async usage
+
+```python
+import asyncio
+from mobiscroll_connect.aio import AsyncMobiscrollConnectClient
+
+async def main():
+    async with AsyncMobiscrollConnectClient(
+        client_id="...",
+        client_secret="...",
+        redirect_uri="...",
+    ) as client:
+        await client.auth.get_token(code="...")
+        async for event in client.events.iter_all(start="2024-01-01", end="2024-01-31"):
+            print(event.title)
+
+asyncio.run(main())
+```
+
+## Error handling
+
+| Exception             | HTTP status   | Extra          |
+| --------------------- | ------------- | -------------- |
+| `AuthenticationError` | 401, 403      | —              |
+| `ValidationError`     | 400, 422      | `.details`     |
+| `NotFoundError`       | 404           | —              |
+| `RateLimitError`      | 429           | `.retry_after` |
+| `ServerError`         | 5xx           | `.status_code` |
+| `NetworkError`        | — (transport) | —              |
+
+All errors inherit from `MobiscrollConnectError`.
+
+```python
+from mobiscroll_connect import (
+    AuthenticationError, ValidationError, NotFoundError,
+    RateLimitError, ServerError, NetworkError, MobiscrollConnectError,
+)
+
+try:
+    client.events.list()
+except AuthenticationError:
+    # Refresh failed — re-authorize the user
+    ...
+except ValidationError as e:
+    print(e.details)
+except RateLimitError as e:
+    print(f"Retry after {e.retry_after}s")
+except ServerError as e:
+    print(f"Server returned {e.status_code}")
+except NetworkError:
+    # Connection / DNS / timeout
+    ...
+except MobiscrollConnectError:
+    # Catch-all
+    ...
+```
+
+## Architecture
+
+```
+mobiscroll_connect/
+├── __init__.py                — public re-exports
+├── client.py                  — MobiscrollConnectClient (sync entry point)
+├── api_client.py              — sync HTTP layer + token refresh
+├── async_api_client.py        — async HTTP layer + token refresh
+├── config.py                  — frozen Config dataclass
+├── exceptions.py              — exception hierarchy
+├── models.py                  — frozen dataclass response models
+├── _internal/
+│   ├── errors.py              — HTTP → exception mapper (shared)
+│   └── payloads.py            — query/payload builders (shared)
+├── resources/
+│   ├── auth.py                — Auth (sync)
+│   ├── calendars.py           — Calendars (sync)
+│   └── events.py              — Events (sync)
+└── aio/
+    ├── client.py              — AsyncMobiscrollConnectClient
+    └── resources.py           — AsyncAuth / AsyncCalendars / AsyncEvents
+```
+
+### Why these choices
+
+- **Frozen dataclasses, not Pydantic.** No third-party runtime dependency for models — matches the "stdlib-only DTOs" approach of the PHP and Node SDKs and keeps install size small. Validation is done where it matters (response parsing, query builders).
+- **`httpx` for both sync and async.** Single dependency, identical request API. `requests` would force a separate sync transport.
+- **`asyncio.Lock` and `threading.Lock` for refresh dedup.** Concurrent 401s wait on the same in-flight refresh instead of racing — same invariant as the Node SDK's `refreshTokenPromise`.
+- **Resources as attributes (`client.auth`, not `client.auth()`).** Idiomatic Python; the parens-method style in the PHP SDK exists only because PHP can't expose readonly properties cleanly.
+- **Pagination helper (`iter_all`).** PHP/Node make callers manage `next_page_token` by hand; Python iterators are the natural shape and remove the bookkeeping.
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT