sapancal 0.2.0__tar.gz

sapancal-0.2.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+dist/

sapancal-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sapan Labs Pty Ltd
+
+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.

sapancal-0.2.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.5
+Name: sapancal
+Version: 0.2.0
+Summary: The SapanCal API client for Python: connect Google and Microsoft calendars, find availability, write events, verify webhooks.
+Project-URL: Homepage, https://sapancal.com
+License-Expression: MIT
+License-File: LICENSE
+Keywords: availability,calendar,free busy,google calendar,microsoft outlook,sapancal,scheduling
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.27
+Description-Content-Type: text/markdown
+
+# SapanCal for Python
+
+The official client for the [SapanCal](https://sapancal.com) API: connect your users' Google and Microsoft calendars, find when they're free, and write events, from one API.
+
+- Sync and asyncio clients
+- Fully typed: responses are `TypedDict`s generated from the API's OpenAPI document
+- Retries rate limits and provider hiccups for you
+- Webhook signature verification built in
+- One dependency (`httpx`), Python 3.11+
+
+```sh
+pip install sapancal
+```
+
+## Quickstart
+
+```python
+from sapancal import SapanCal
+
+client = SapanCal()  # reads SAPANCAL_API_KEY
+```
+
+Your API key is in the console under **Application → API keys**. It already says which region your application lives in, so there's nothing else to configure.
+
+### 1. Connect a calendar
+
+Create a connect session for one of your users and send them to its `url`:
+
+```python
+session = client.connect_sessions.create(
+    user_id="user_123",  # your own id for the user
+    redirect_uri="https://app.example.com/calendar/connected",
+)
+return redirect(session["url"])
+```
+
+They sign in to Google or Microsoft and come back to your `redirect_uri` with `connect_session_id` and `status` in the query string:
+
+```python
+# GET /calendar/connected?connect_session_id=cs_...&status=success
+session = client.connect_sessions.get(request.args["connect_session_id"])
+if session["status"] == "completed":
+    print("Connected", session["connection"]["email"])
+```
+
+### 2. Find a time
+
+```python
+from datetime import datetime
+from zoneinfo import ZoneInfo
+
+sydney = ZoneInfo("Australia/Sydney")
+result = client.availability.query(
+    participants=[{"user_id": "user_123"}, {"user_id": "user_456"}],
+    periods=[{"start": datetime(2026, 11, 2, 9, tzinfo=sydney), "end": datetime(2026, 11, 2, 17, tzinfo=sydney)}],
+    slot_duration_minutes=30,
+)
+for slot in result["slots"]:
+    print(slot["start"], slot["user_ids"])
+```
+
+`start` and `end` take a timezone-aware `datetime` or an ISO 8601 string. For raw busy blocks instead of slots, use `client.free_busy.query(user_ids=[...], start=..., end=...)`.
+
+### 3. Book it
+
+Events are keyed by your own id, so the same call creates and later updates the event, and a retry never makes a duplicate:
+
+```python
+slot = result["slots"][0]
+client.events.upsert("user_123", "booking_789", summary="Intro call", start=slot["start"], end=slot["end"], time_zone="Australia/Sydney")
+
+client.events.delete("user_123", "booking_789")
+```
+
+### 4. Handle webhooks
+
+SapanCal tells you when a connection is created, needs relinking or is revoked, and when a calendar changes. Verify the signature against the **raw** request body:
+
+```python
+from sapancal import WebhookVerificationError
+
+# Flask
+@app.post("/webhooks/sapancal")
+def sapancal_webhook():
+    try:
+        event = client.webhooks.verify(request.get_data(), request.headers)  # secret from SAPANCAL_WEBHOOK_SECRET
+    except WebhookVerificationError:
+        return "", 400
+
+    if event["type"] == "connection.relink_required":
+        ask_user_to_reconnect(event["data"]["user_id"], event["data"]["connection_id"])
+    elif event["type"] == "calendar.changed":
+        resync(event["data"]["user_id"], event["data"]["calendar_id"])
+    return "", 204
+```
+
+In Django pass `request.body` and `request.headers`; in FastAPI, `await request.body()` and `request.headers`. Verification fails if the signature is missing, wrong or older than five minutes. Deliveries are retried, so use `event["id"]` to skip ones you've already handled. During a signing-secret rotation both the old and new secret are accepted.
+
+To test your handler, sign your own payload with `sapancal.sign_webhook(body, "whsec_test")` and send it as the `SapanCal-Signature` header.
+
+## Async
+
+```python
+from sapancal import AsyncSapanCal
+
+async with AsyncSapanCal() as client:
+    user = await client.users.get("user_123")
+```
+
+Every method is the same, awaited.
+
+## All methods
+
+| Method | API |
+|---|---|
+| `connect_sessions.create(user_id=, redirect_uri=, provider=, connection_id=)` | `POST /connect_sessions` |
+| `connect_sessions.get(id)` | `GET /connect_sessions/{id}` |
+| `users.get(user_id)` | `GET /users/{user_id}` |
+| `users.update(user_id, default_connection_id=)` | `PATCH /users/{user_id}` |
+| `users.delete(user_id)` | `DELETE /users/{user_id}` |
+| `connections.get(id)` | `GET /connections/{id}` |
+| `connections.delete(id)` | `DELETE /connections/{id}` |
+| `connections.list_calendars(id)` | `GET /connections/{id}/calendars` |
+| `free_busy.query(user_ids=, start=, end=, calendar_ids=)` | `POST /free_busy` |
+| `availability.query(participants=, periods=, slot_duration_minutes=, ...)` | `POST /availability` |
+| `events.upsert(user_id, event_id, summary=, start=, end=, ...)` | `PUT /users/{user_id}/events/{event_id}` |
+| `events.delete(user_id, event_id)` | `DELETE /users/{user_id}/events/{event_id}` |
+| `webhooks.verify(payload, headers, secret=)` | checks a webhook locally |
+
+Arguments and response keys use the API's names, so the [API reference](https://api.sapancal.com/openapi.json) applies as written.
+
+## Errors
+
+API errors raise `SapanCalApiError`. Branch on `code`, which is stable; the message is for people.
+
+```python
+from sapancal import SapanCalApiError
+
+try:
+    client.events.upsert(user_id, booking_id, summary="Intro call", start=start, end=end)
+except SapanCalApiError as err:
+    if err.code == "relink_required":
+        # The user revoked access or changed their password: send them through a new connect
+        # session with connection_id to relink.
+        ...
+    raise
+```
+
+`SapanCalApiError` has `status`, `code`, `message`, `request_id` (quote it to support), `details` (validation issues) and `retry_after`. Network failures and timeouts raise `SapanCalConnectionError`. Both extend `SapanCalError`.
+
+## Retries and timeouts
+
+Network errors, `429` and `502`–`504` are retried twice with exponential backoff, waiting as long as the API's `Retry-After` asks (up to 60 seconds; longer waits raise instead). Each attempt times out after 30 seconds.
+
+```python
+client = SapanCal(max_retries=4, timeout=10)
+```
+
+## Configuration
+
+| Argument | Environment variable | Default |
+|---|---|---|
+| `api_key` | `SAPANCAL_API_KEY` | required |
+| `webhook_secret` | `SAPANCAL_WEBHOOK_SECRET` | none |
+| `base_url` | `SAPANCAL_BASE_URL` | `https://api.sapancal.com/{region}/v1`, region from the key |
+| `timeout` | | `30` seconds |
+| `max_retries` | | `2` |
+| `http_client` | | a new `httpx.Client` / `httpx.AsyncClient` |
+
+## License
+
+MIT

sapancal-0.2.0/README.md

@@ -0,0 +1,172 @@
+# SapanCal for Python
+
+The official client for the [SapanCal](https://sapancal.com) API: connect your users' Google and Microsoft calendars, find when they're free, and write events, from one API.
+
+- Sync and asyncio clients
+- Fully typed: responses are `TypedDict`s generated from the API's OpenAPI document
+- Retries rate limits and provider hiccups for you
+- Webhook signature verification built in
+- One dependency (`httpx`), Python 3.11+
+
+```sh
+pip install sapancal
+```
+
+## Quickstart
+
+```python
+from sapancal import SapanCal
+
+client = SapanCal()  # reads SAPANCAL_API_KEY
+```
+
+Your API key is in the console under **Application → API keys**. It already says which region your application lives in, so there's nothing else to configure.
+
+### 1. Connect a calendar
+
+Create a connect session for one of your users and send them to its `url`:
+
+```python
+session = client.connect_sessions.create(
+    user_id="user_123",  # your own id for the user
+    redirect_uri="https://app.example.com/calendar/connected",
+)
+return redirect(session["url"])
+```
+
+They sign in to Google or Microsoft and come back to your `redirect_uri` with `connect_session_id` and `status` in the query string:
+
+```python
+# GET /calendar/connected?connect_session_id=cs_...&status=success
+session = client.connect_sessions.get(request.args["connect_session_id"])
+if session["status"] == "completed":
+    print("Connected", session["connection"]["email"])
+```
+
+### 2. Find a time
+
+```python
+from datetime import datetime
+from zoneinfo import ZoneInfo
+
+sydney = ZoneInfo("Australia/Sydney")
+result = client.availability.query(
+    participants=[{"user_id": "user_123"}, {"user_id": "user_456"}],
+    periods=[{"start": datetime(2026, 11, 2, 9, tzinfo=sydney), "end": datetime(2026, 11, 2, 17, tzinfo=sydney)}],
+    slot_duration_minutes=30,
+)
+for slot in result["slots"]:
+    print(slot["start"], slot["user_ids"])
+```
+
+`start` and `end` take a timezone-aware `datetime` or an ISO 8601 string. For raw busy blocks instead of slots, use `client.free_busy.query(user_ids=[...], start=..., end=...)`.
+
+### 3. Book it
+
+Events are keyed by your own id, so the same call creates and later updates the event, and a retry never makes a duplicate:
+
+```python
+slot = result["slots"][0]
+client.events.upsert("user_123", "booking_789", summary="Intro call", start=slot["start"], end=slot["end"], time_zone="Australia/Sydney")
+
+client.events.delete("user_123", "booking_789")
+```
+
+### 4. Handle webhooks
+
+SapanCal tells you when a connection is created, needs relinking or is revoked, and when a calendar changes. Verify the signature against the **raw** request body:
+
+```python
+from sapancal import WebhookVerificationError
+
+# Flask
+@app.post("/webhooks/sapancal")
+def sapancal_webhook():
+    try:
+        event = client.webhooks.verify(request.get_data(), request.headers)  # secret from SAPANCAL_WEBHOOK_SECRET
+    except WebhookVerificationError:
+        return "", 400
+
+    if event["type"] == "connection.relink_required":
+        ask_user_to_reconnect(event["data"]["user_id"], event["data"]["connection_id"])
+    elif event["type"] == "calendar.changed":
+        resync(event["data"]["user_id"], event["data"]["calendar_id"])
+    return "", 204
+```
+
+In Django pass `request.body` and `request.headers`; in FastAPI, `await request.body()` and `request.headers`. Verification fails if the signature is missing, wrong or older than five minutes. Deliveries are retried, so use `event["id"]` to skip ones you've already handled. During a signing-secret rotation both the old and new secret are accepted.
+
+To test your handler, sign your own payload with `sapancal.sign_webhook(body, "whsec_test")` and send it as the `SapanCal-Signature` header.
+
+## Async
+
+```python
+from sapancal import AsyncSapanCal
+
+async with AsyncSapanCal() as client:
+    user = await client.users.get("user_123")
+```
+
+Every method is the same, awaited.
+
+## All methods
+
+| Method | API |
+|---|---|
+| `connect_sessions.create(user_id=, redirect_uri=, provider=, connection_id=)` | `POST /connect_sessions` |
+| `connect_sessions.get(id)` | `GET /connect_sessions/{id}` |
+| `users.get(user_id)` | `GET /users/{user_id}` |
+| `users.update(user_id, default_connection_id=)` | `PATCH /users/{user_id}` |
+| `users.delete(user_id)` | `DELETE /users/{user_id}` |
+| `connections.get(id)` | `GET /connections/{id}` |
+| `connections.delete(id)` | `DELETE /connections/{id}` |
+| `connections.list_calendars(id)` | `GET /connections/{id}/calendars` |
+| `free_busy.query(user_ids=, start=, end=, calendar_ids=)` | `POST /free_busy` |
+| `availability.query(participants=, periods=, slot_duration_minutes=, ...)` | `POST /availability` |
+| `events.upsert(user_id, event_id, summary=, start=, end=, ...)` | `PUT /users/{user_id}/events/{event_id}` |
+| `events.delete(user_id, event_id)` | `DELETE /users/{user_id}/events/{event_id}` |
+| `webhooks.verify(payload, headers, secret=)` | checks a webhook locally |
+
+Arguments and response keys use the API's names, so the [API reference](https://api.sapancal.com/openapi.json) applies as written.
+
+## Errors
+
+API errors raise `SapanCalApiError`. Branch on `code`, which is stable; the message is for people.
+
+```python
+from sapancal import SapanCalApiError
+
+try:
+    client.events.upsert(user_id, booking_id, summary="Intro call", start=start, end=end)
+except SapanCalApiError as err:
+    if err.code == "relink_required":
+        # The user revoked access or changed their password: send them through a new connect
+        # session with connection_id to relink.
+        ...
+    raise
+```
+
+`SapanCalApiError` has `status`, `code`, `message`, `request_id` (quote it to support), `details` (validation issues) and `retry_after`. Network failures and timeouts raise `SapanCalConnectionError`. Both extend `SapanCalError`.
+
+## Retries and timeouts
+
+Network errors, `429` and `502`–`504` are retried twice with exponential backoff, waiting as long as the API's `Retry-After` asks (up to 60 seconds; longer waits raise instead). Each attempt times out after 30 seconds.
+
+```python
+client = SapanCal(max_retries=4, timeout=10)
+```
+
+## Configuration
+
+| Argument | Environment variable | Default |
+|---|---|---|
+| `api_key` | `SAPANCAL_API_KEY` | required |
+| `webhook_secret` | `SAPANCAL_WEBHOOK_SECRET` | none |
+| `base_url` | `SAPANCAL_BASE_URL` | `https://api.sapancal.com/{region}/v1`, region from the key |
+| `timeout` | | `30` seconds |
+| `max_retries` | | `2` |
+| `http_client` | | a new `httpx.Client` / `httpx.AsyncClient` |
+
+## License
+
+MIT

sapancal-0.2.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "sapancal"
+version = "0.2.0"
+description = "The SapanCal API client for Python: connect Google and Microsoft calendars, find availability, write events, verify webhooks."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+dependencies = ["httpx>=0.27,<1"]
+keywords = ["sapancal", "calendar", "google calendar", "microsoft outlook", "availability", "scheduling", "free busy"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Typing :: Typed",
+  "Framework :: AsyncIO",
+]
+
+[project.urls]
+Homepage = "https://sapancal.com"
+
+[dependency-groups]
+dev = ["pytest>=8", "mypy>=1.13"]
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sapancal"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+strict = true
+files = ["src"]

sapancal-0.2.0/src/sapancal/__init__.py

@@ -0,0 +1,66 @@
+"""The SapanCal API client: connect Google and Microsoft calendars, find availability, write events, verify webhooks."""
+
+from ._client import AsyncSapanCal, SapanCal, DateTimeInput
+from ._errors import SapanCalApiError, SapanCalConnectionError, SapanCalError, WebhookVerificationError
+from ._types import (
+    AvailabilityResponse,
+    AvailabilitySlot,
+    Calendar,
+    CalendarChangedEvent,
+    CalendarChangedWebhookData,
+    Connection,
+    ConnectionCreatedEvent,
+    ConnectionRelinkedEvent,
+    ConnectionRelinkRequiredEvent,
+    ConnectionRevokedEvent,
+    ConnectionWebhookData,
+    ConnectSession,
+    Event,
+    FreeBusyResponse,
+    ParticipantError,
+    TimeInterval,
+    User,
+)
+from ._version import __version__
+from ._webhooks import (
+    DEFAULT_WEBHOOK_TOLERANCE,
+    WEBHOOK_EVENT_ID_HEADER,
+    WEBHOOK_SIGNATURE_HEADER,
+    WebhookEvent,
+    sign_webhook,
+    verify_webhook,
+)
+
+__all__ = [
+    "AsyncSapanCal",
+    "AvailabilityResponse",
+    "AvailabilitySlot",
+    "SapanCal",
+    "SapanCalApiError",
+    "SapanCalConnectionError",
+    "SapanCalError",
+    "Calendar",
+    "CalendarChangedEvent",
+    "CalendarChangedWebhookData",
+    "Connection",
+    "ConnectionCreatedEvent",
+    "ConnectionRelinkedEvent",
+    "ConnectionRelinkRequiredEvent",
+    "ConnectionRevokedEvent",
+    "ConnectionWebhookData",
+    "ConnectSession",
+    "DEFAULT_WEBHOOK_TOLERANCE",
+    "DateTimeInput",
+    "Event",
+    "FreeBusyResponse",
+    "ParticipantError",
+    "TimeInterval",
+    "User",
+    "WEBHOOK_EVENT_ID_HEADER",
+    "WEBHOOK_SIGNATURE_HEADER",
+    "WebhookEvent",
+    "WebhookVerificationError",
+    "__version__",
+    "sign_webhook",
+    "verify_webhook",
+]