zoplio 0.2.0__tar.gz

zoplio-0.2.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: zoplio
+Version: 0.2.0
+Summary: Official Zoplio Python SDK for the Zoplio API v1
+Author-email: Zoplio <hello@zoplio.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Zoplio/zoplio-sdk
+Project-URL: Repository, https://github.com/Zoplio/zoplio-sdk
+Project-URL: Issues, https://github.com/Zoplio/zoplio-sdk/issues
+Keywords: zoplio,scheduling,ai-agent,meetings,mcp
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+
+# zoplio (Python SDK)
+
+Official Zoplio Python SDK for the [Zoplio API v1](../../docs/quickstart.md). MIT licensed.
+
+Zoplio schedules meetings for you: you say who and roughly when, Zoplio negotiates with every participant over WhatsApp/email and confirms a slot.
+
+Requires Python >= 3.10. Depends on `httpx`.
+
+## Install
+
+Not yet published to PyPI — install from this monorepo:
+
+```bash
+pip install -e packages/sdk-python
+```
+
+## Usage
+
+```python
+from zoplio import ZoplioClient, ZoplioError
+
+zoplio = ZoplioClient(api_key="zpl_...")  # base_url defaults to https://api.zoplio.com
+
+# Create a meeting — Zoplio reaches out to participants and negotiates.
+created = zoplio.schedule_meeting(
+    participants=[
+        {"email": "petr@example.com", "name": "Petr"},
+        {"phone": "+420777123456", "name": "Jana"},
+    ],
+    title="Intro call",
+    duration_minutes=30,
+    preferred_date="2026-06-15",
+    preferred_time="14:00",
+    timezone="Europe/Prague",
+    idempotency_key="order-42-intro-call",  # optional, safe retries
+)
+print(created["meetingId"], created["status"], created["proposedSlots"])
+
+# Poll status (or use webhooks instead).
+meeting = zoplio.get_meeting(created["meetingId"])
+
+# List / reschedule / cancel.
+zoplio.list_meetings(status="confirmed", limit=10)
+zoplio.reschedule_meeting(
+    created["meetingId"],
+    preferred_date="2026-06-16",
+    preferred_time="10:00",
+    timezone="Europe/Prague",
+)
+zoplio.cancel_meeting(created["meetingId"])
+```
+
+## Errors
+
+Every non-2xx response raises `ZoplioError` with the contract envelope:
+
+```python
+try:
+    zoplio.get_meeting("nope")
+except ZoplioError as err:
+    err.status_code  # 404
+    err.code         # 'not_found' | 'unauthorized' | 'rate_limited' | 'validation_failed' | 'conflict' | 'upstream_error'
+    str(err)         # human-readable message
+    err.details      # [{"field", "message"}] on validation_failed
+```
+
+## Webhooks
+
+```python
+# Subscribe — the secret is returned exactly once.
+hook = zoplio.create_webhook(
+    url="https://example.com/zoplio-hook",
+    events=["meeting.confirmed", "meeting.cancelled"],
+)
+save_secret(hook["secret"])  # whsec_...
+
+zoplio.list_webhooks()
+zoplio.delete_webhook(hook["id"])
+```
+
+Verify deliveries with the static helper — pass the RAW request body:
+
+```python
+# e.g. Flask
+@app.post("/zoplio-hook")
+def zoplio_hook():
+    ok = ZoplioClient.verify_webhook_signature(
+        request.get_data(),                          # raw bytes
+        request.headers.get("X-Zoplio-Signature", ""),
+        os.environ["ZOPLIO_WEBHOOK_SECRET"],         # whsec_...
+    )
+    if not ok:
+        return "", 401
+    delivery = request.get_json()  # {"event", "payload", "timestamp"}
+    return "", 200
+```

zoplio-0.2.0/README.md

@@ -0,0 +1,96 @@
+# zoplio (Python SDK)
+
+Official Zoplio Python SDK for the [Zoplio API v1](../../docs/quickstart.md). MIT licensed.
+
+Zoplio schedules meetings for you: you say who and roughly when, Zoplio negotiates with every participant over WhatsApp/email and confirms a slot.
+
+Requires Python >= 3.10. Depends on `httpx`.
+
+## Install
+
+Not yet published to PyPI — install from this monorepo:
+
+```bash
+pip install -e packages/sdk-python
+```
+
+## Usage
+
+```python
+from zoplio import ZoplioClient, ZoplioError
+
+zoplio = ZoplioClient(api_key="zpl_...")  # base_url defaults to https://api.zoplio.com
+
+# Create a meeting — Zoplio reaches out to participants and negotiates.
+created = zoplio.schedule_meeting(
+    participants=[
+        {"email": "petr@example.com", "name": "Petr"},
+        {"phone": "+420777123456", "name": "Jana"},
+    ],
+    title="Intro call",
+    duration_minutes=30,
+    preferred_date="2026-06-15",
+    preferred_time="14:00",
+    timezone="Europe/Prague",
+    idempotency_key="order-42-intro-call",  # optional, safe retries
+)
+print(created["meetingId"], created["status"], created["proposedSlots"])
+
+# Poll status (or use webhooks instead).
+meeting = zoplio.get_meeting(created["meetingId"])
+
+# List / reschedule / cancel.
+zoplio.list_meetings(status="confirmed", limit=10)
+zoplio.reschedule_meeting(
+    created["meetingId"],
+    preferred_date="2026-06-16",
+    preferred_time="10:00",
+    timezone="Europe/Prague",
+)
+zoplio.cancel_meeting(created["meetingId"])
+```
+
+## Errors
+
+Every non-2xx response raises `ZoplioError` with the contract envelope:
+
+```python
+try:
+    zoplio.get_meeting("nope")
+except ZoplioError as err:
+    err.status_code  # 404
+    err.code         # 'not_found' | 'unauthorized' | 'rate_limited' | 'validation_failed' | 'conflict' | 'upstream_error'
+    str(err)         # human-readable message
+    err.details      # [{"field", "message"}] on validation_failed
+```
+
+## Webhooks
+
+```python
+# Subscribe — the secret is returned exactly once.
+hook = zoplio.create_webhook(
+    url="https://example.com/zoplio-hook",
+    events=["meeting.confirmed", "meeting.cancelled"],
+)
+save_secret(hook["secret"])  # whsec_...
+
+zoplio.list_webhooks()
+zoplio.delete_webhook(hook["id"])
+```
+
+Verify deliveries with the static helper — pass the RAW request body:
+
+```python
+# e.g. Flask
+@app.post("/zoplio-hook")
+def zoplio_hook():
+    ok = ZoplioClient.verify_webhook_signature(
+        request.get_data(),                          # raw bytes
+        request.headers.get("X-Zoplio-Signature", ""),
+        os.environ["ZOPLIO_WEBHOOK_SECRET"],         # whsec_...
+    )
+    if not ok:
+        return "", 401
+    delivery = request.get_json()  # {"event", "payload", "timestamp"}
+    return "", 200
+```

zoplio-0.2.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zoplio"
+version = "0.2.0"
+description = "Official Zoplio Python SDK for the Zoplio API v1"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "Zoplio", email = "hello@zoplio.com" }]
+keywords = ["zoplio", "scheduling", "ai-agent", "meetings", "mcp"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "mypy>=1.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+zoplio = ["py.typed"]
+
+[project.urls]
+Homepage = "https://github.com/Zoplio/zoplio-sdk"
+Repository = "https://github.com/Zoplio/zoplio-sdk"
+Issues = "https://github.com/Zoplio/zoplio-sdk/issues"

zoplio-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

zoplio-0.2.0/src/zoplio/__init__.py

@@ -0,0 +1,30 @@
+from .client import ZoplioClient, ZoplioError
+from .types import (
+    MEETING_STATUSES,
+    WEBHOOK_EVENTS,
+    MeetingDetail,
+    MeetingParticipant,
+    MeetingSummary,
+    ParticipantInput,
+    Slot,
+    WebhookCreated,
+    WebhookDelivery,
+    WebhookSummary,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "ZoplioClient",
+    "ZoplioError",
+    "MEETING_STATUSES",
+    "WEBHOOK_EVENTS",
+    "MeetingDetail",
+    "MeetingParticipant",
+    "MeetingSummary",
+    "ParticipantInput",
+    "Slot",
+    "WebhookCreated",
+    "WebhookDelivery",
+    "WebhookSummary",
+]

zoplio-0.2.0/src/zoplio/client.py

@@ -0,0 +1,261 @@
+"""Client for the Zoplio public API v1 (api-gateway /v1)."""
+
+import hashlib
+import hmac
+from typing import Any, Optional, Union
+from urllib.parse import quote
+
+import httpx
+
+
+class ZoplioError(Exception):
+    """Error raised for every non-2xx API response.
+
+    Carries the contract error envelope ``{"error": {"code", "message",
+    "details"?}}``:
+
+    - ``code``: one of ``unauthorized``, ``rate_limited``, ``validation_failed``,
+      ``not_found``, ``conflict``, ``quota_exceeded``, ``upstream_error``
+    - ``status_code``: HTTP status of the response
+    - ``details``: list of ``{"field", "message"}`` on ``validation_failed``
+    """
+
+    def __init__(
+        self,
+        message: str,
+        code: str = "upstream_error",
+        status_code: int = 0,
+        details: Optional[list] = None,
+    ):
+        super().__init__(message)
+        self.code = code
+        self.status_code = status_code
+        self.details = details or []
+
+
+class ZoplioClient:
+    """Official Zoplio Python SDK client.
+
+    Usage::
+
+        from zoplio import ZoplioClient
+
+        zoplio = ZoplioClient(api_key="zpl_...")
+        created = zoplio.schedule_meeting(
+            participants=[{"email": "petr@example.com", "name": "Petr"}],
+            title="Intro call",
+        )
+        print(created["meetingId"], created["status"])
+    """
+
+    def __init__(self, api_key: str, base_url: str = "https://api.zoplio.com"):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+            },
+            timeout=30.0,
+        )
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        json: Optional[dict] = None,
+        params: Optional[dict] = None,
+        headers: Optional[dict] = None,
+    ) -> Any:
+        response = self._client.request(
+            method, path, json=json, params=params, headers=headers
+        )
+        try:
+            data = response.json()
+        except ValueError:
+            data = None
+        if not response.is_success:
+            err = (data or {}).get("error") or {}
+            raise ZoplioError(
+                err.get("message", f"Zoplio API error: HTTP {response.status_code}"),
+                code=err.get("code", "upstream_error"),
+                status_code=response.status_code,
+                details=err.get("details"),
+            )
+        return data
+
+    # ── Meetings ────────────────────────────────────────
+
+    def schedule_meeting(
+        self,
+        participants: list[dict],
+        title: Optional[str] = None,
+        duration_minutes: Optional[int] = None,
+        preferred_date: Optional[str] = None,
+        preferred_time: Optional[str] = None,
+        timezone: Optional[str] = None,
+        earliest_date: Optional[str] = None,
+        latest_date: Optional[str] = None,
+        open_ask: Optional[bool] = None,
+        location: Optional[str] = None,
+        organizer_attending: Optional[bool] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> dict:
+        """Create a meeting and start negotiating with the participants.
+
+        ``POST /v1/meetings``
+
+        :param participants: 1-8 dicts, each with ``phone`` (E.164) or
+            ``email``, plus optional ``name``.
+        :param preferred_date: ``YYYY-MM-DD`` (required when
+            ``preferred_time`` is set).
+        :param preferred_time: ``HH:MM`` 24-hour.
+        :param timezone: IANA timezone the date/time are expressed in.
+        :param idempotency_key: sent as ``X-Idempotency-Key`` — replaying the
+            same key returns the originally created meeting.
+        :returns: ``{"meetingId", "negotiationId", "status", "proposedSlots"}``
+        """
+        body: dict[str, Any] = {"participants": participants}
+        if title is not None:
+            body["title"] = title
+        if duration_minutes is not None:
+            body["durationMinutes"] = duration_minutes
+        if preferred_date is not None:
+            body["preferredDate"] = preferred_date
+        if preferred_time is not None:
+            body["preferredTime"] = preferred_time
+        if timezone is not None:
+            body["timezone"] = timezone
+        if earliest_date is not None:
+            body["earliestDate"] = earliest_date
+        if latest_date is not None:
+            body["latestDate"] = latest_date
+        if open_ask is not None:
+            body["openAsk"] = open_ask
+        if location is not None:
+            body["location"] = location
+        if organizer_attending is not None:
+            body["organizerAttending"] = organizer_attending
+
+        headers = {"X-Idempotency-Key": idempotency_key} if idempotency_key else None
+        return self._request("POST", "/v1/meetings", json=body, headers=headers)
+
+    def get_meeting(self, meeting_id: str) -> dict:
+        """Fetch one meeting you organize, with per-participant status.
+
+        ``GET /v1/meetings/:id`` →
+        ``{"id", "title", "status", "confirmedSlot"?, "participants"}``
+        """
+        return self._request("GET", f"/v1/meetings/{quote(meeting_id, safe='')}")
+
+    def list_meetings(
+        self, status: Optional[str] = None, limit: Optional[int] = None
+    ) -> dict:
+        """List meetings you organize, newest first.
+
+        ``GET /v1/meetings?status=&limit=`` → ``{"meetings": [...]}``
+
+        :param status: one of ``draft``, ``negotiating``, ``confirmed``,
+            ``cancelled``, ``rescheduling``.
+        :param limit: 1-50, default 20.
+        """
+        params: dict[str, Any] = {}
+        if status is not None:
+            params["status"] = status
+        if limit is not None:
+            params["limit"] = limit
+        return self._request("GET", "/v1/meetings", params=params or None)
+
+    def cancel_meeting(self, meeting_id: str) -> dict:
+        """Cancel a meeting (idempotent).
+
+        ``POST /v1/meetings/:id/cancel`` → ``{"status": "cancelled"}``
+        """
+        return self._request(
+            "POST", f"/v1/meetings/{quote(meeting_id, safe='')}/cancel"
+        )
+
+    def reschedule_meeting(
+        self,
+        meeting_id: str,
+        preferred_date: str,
+        preferred_time: str,
+        timezone: Optional[str] = None,
+    ) -> dict:
+        """Propose a new exact date+time to all participants.
+
+        ``POST /v1/meetings/:id/reschedule`` →
+        ``{"meetingId", "status": "negotiating", "proposedSlots"}``
+
+        Raises :class:`ZoplioError` with code ``conflict`` when the requested
+        time collides with a participant's availability or the negotiation
+        state does not allow re-proposing.
+        """
+        body: dict[str, Any] = {
+            "preferredDate": preferred_date,
+            "preferredTime": preferred_time,
+        }
+        if timezone is not None:
+            body["timezone"] = timezone
+        return self._request(
+            "POST", f"/v1/meetings/{quote(meeting_id, safe='')}/reschedule", json=body
+        )
+
+    # ── Webhooks ────────────────────────────────────────
+
+    def create_webhook(self, url: str, events: Optional[list[str]] = None) -> dict:
+        """Subscribe a URL to meeting lifecycle events.
+
+        ``POST /v1/webhooks`` → ``{"id", "url", "events", "secret"}``
+
+        The ``whsec_`` secret is returned exactly once — store it to verify
+        deliveries. ``events`` defaults to all of ``meeting.created``,
+        ``meeting.confirmed``, ``meeting.cancelled``, ``negotiation.failed``.
+        """
+        body: dict[str, Any] = {"url": url}
+        if events is not None:
+            body["events"] = events
+        return self._request("POST", "/v1/webhooks", json=body)
+
+    def list_webhooks(self) -> dict:
+        """List your webhook subscriptions (without secrets).
+
+        ``GET /v1/webhooks`` → ``{"webhooks": [...]}``
+        """
+        return self._request("GET", "/v1/webhooks")
+
+    def delete_webhook(self, webhook_id: str) -> dict:
+        """Delete one of your webhook subscriptions.
+
+        ``DELETE /v1/webhooks/:id`` → ``{"deleted": true}``
+        """
+        return self._request(
+            "DELETE", f"/v1/webhooks/{quote(webhook_id, safe='')}"
+        )
+
+    @staticmethod
+    def verify_webhook_signature(
+        raw_body: Union[str, bytes], signature_header: str, secret: str
+    ) -> bool:
+        """Verify a webhook delivery signature.
+
+        Constant-time comparison of the ``X-Zoplio-Signature`` header against
+        ``HMAC-SHA256(secret, raw_body)`` hex-encoded — exactly how Zoplio
+        signs deliveries. Pass the RAW request body bytes (before JSON
+        parsing — re-serializing the parsed body may not be byte-identical).
+        """
+        if not signature_header or not secret:
+            return False
+        body = raw_body.encode("utf-8") if isinstance(raw_body, str) else raw_body
+        expected = hmac.new(secret.encode("utf-8"), body, hashlib.sha256).hexdigest()
+        return hmac.compare_digest(expected, signature_header.strip().lower())
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "ZoplioClient":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()

zoplio-0.2.0/src/zoplio/types.py

@@ -0,0 +1,106 @@
+"""Reference shapes for the Zoplio public API v1 wire format.
+
+:class:`~zoplio.client.ZoplioClient` returns plain dicts straight off the
+wire; these dataclasses document the shapes (mirroring the TypeScript SDK's
+types) for IDE help and type-checked application code.
+"""
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+MEETING_STATUSES = ("draft", "negotiating", "confirmed", "cancelled", "rescheduling")
+
+WEBHOOK_EVENTS = (
+    "meeting.created",
+    "meeting.confirmed",
+    "meeting.cancelled",
+    "meeting.rescheduled",
+    "negotiation.failed",
+)
+
+
+@dataclass
+class Slot:
+    """A concrete time slot. ISO 8601 datetimes (UTC)."""
+
+    start: str
+    end: str
+
+
+@dataclass
+class ParticipantInput:
+    """Meeting participant input — needs ``phone`` (E.164) or ``email``."""
+
+    phone: Optional[str] = None
+    email: Optional[str] = None
+    name: Optional[str] = None
+
+
+@dataclass
+class MeetingParticipant:
+    """Participant as returned by ``GET /v1/meetings/:id``."""
+
+    status: str  # pending, accepted, declined, counter-proposed, ...
+    attending: bool
+    name: Optional[str] = None
+    email: Optional[str] = None
+    phone: Optional[str] = None
+
+
+@dataclass
+class MeetingDetail:
+    """``GET /v1/meetings/:id`` response."""
+
+    id: str
+    title: str
+    status: str  # one of MEETING_STATUSES
+    participants: list[MeetingParticipant] = field(default_factory=list)
+    confirmed_slot: Optional[Slot] = None  # wire key: confirmedSlot
+
+
+@dataclass
+class MeetingSummary:
+    """Entry of ``GET /v1/meetings`` → ``{"meetings": [...]}``."""
+
+    id: str
+    title: str
+    status: str
+    confirmed_slot: Optional[Slot] = None  # wire key: confirmedSlot
+    created_at: Optional[str] = None  # wire key: createdAt
+
+
+@dataclass
+class WebhookCreated:
+    """``POST /v1/webhooks`` response. ``secret`` is returned exactly once."""
+
+    id: str
+    url: str
+    events: list[str]
+    secret: str  # whsec_...
+
+
+@dataclass
+class WebhookSummary:
+    """Entry of ``GET /v1/webhooks`` → ``{"webhooks": [...]}`` (no secret)."""
+
+    id: str
+    url: str
+    events: list[str]
+    active: bool
+    created_at: Optional[str] = None  # wire key: createdAt
+
+
+@dataclass
+class WebhookDelivery:
+    """Body POSTed to a subscribed URL.
+
+    Verify ``X-Zoplio-Signature`` over the raw body with
+    :meth:`zoplio.ZoplioClient.verify_webhook_signature` before trusting it.
+    ``payload`` carries ``meetingId``, ``organizerUserId``, ``title`` and — on
+    confirmed/cancelled/failed events — ``negotiationId``,
+    ``participantEmails`` and (when confirmed) ``confirmedSlot``.
+    """
+
+    event: str  # one of WEBHOOK_EVENTS, also in the X-Zoplio-Event header
+    payload: dict
+    timestamp: str  # ISO 8601

zoplio-0.2.0/src/zoplio.egg-info/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: zoplio
+Version: 0.2.0
+Summary: Official Zoplio Python SDK for the Zoplio API v1
+Author-email: Zoplio <hello@zoplio.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Zoplio/zoplio-sdk
+Project-URL: Repository, https://github.com/Zoplio/zoplio-sdk
+Project-URL: Issues, https://github.com/Zoplio/zoplio-sdk/issues
+Keywords: zoplio,scheduling,ai-agent,meetings,mcp
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+
+# zoplio (Python SDK)
+
+Official Zoplio Python SDK for the [Zoplio API v1](../../docs/quickstart.md). MIT licensed.
+
+Zoplio schedules meetings for you: you say who and roughly when, Zoplio negotiates with every participant over WhatsApp/email and confirms a slot.
+
+Requires Python >= 3.10. Depends on `httpx`.
+
+## Install
+
+Not yet published to PyPI — install from this monorepo:
+
+```bash
+pip install -e packages/sdk-python
+```
+
+## Usage
+
+```python
+from zoplio import ZoplioClient, ZoplioError
+
+zoplio = ZoplioClient(api_key="zpl_...")  # base_url defaults to https://api.zoplio.com
+
+# Create a meeting — Zoplio reaches out to participants and negotiates.
+created = zoplio.schedule_meeting(
+    participants=[
+        {"email": "petr@example.com", "name": "Petr"},
+        {"phone": "+420777123456", "name": "Jana"},
+    ],
+    title="Intro call",
+    duration_minutes=30,
+    preferred_date="2026-06-15",
+    preferred_time="14:00",
+    timezone="Europe/Prague",
+    idempotency_key="order-42-intro-call",  # optional, safe retries
+)
+print(created["meetingId"], created["status"], created["proposedSlots"])
+
+# Poll status (or use webhooks instead).
+meeting = zoplio.get_meeting(created["meetingId"])
+
+# List / reschedule / cancel.
+zoplio.list_meetings(status="confirmed", limit=10)
+zoplio.reschedule_meeting(
+    created["meetingId"],
+    preferred_date="2026-06-16",
+    preferred_time="10:00",
+    timezone="Europe/Prague",
+)
+zoplio.cancel_meeting(created["meetingId"])
+```
+
+## Errors
+
+Every non-2xx response raises `ZoplioError` with the contract envelope:
+
+```python
+try:
+    zoplio.get_meeting("nope")
+except ZoplioError as err:
+    err.status_code  # 404
+    err.code         # 'not_found' | 'unauthorized' | 'rate_limited' | 'validation_failed' | 'conflict' | 'upstream_error'
+    str(err)         # human-readable message
+    err.details      # [{"field", "message"}] on validation_failed
+```
+
+## Webhooks
+
+```python
+# Subscribe — the secret is returned exactly once.
+hook = zoplio.create_webhook(
+    url="https://example.com/zoplio-hook",
+    events=["meeting.confirmed", "meeting.cancelled"],
+)
+save_secret(hook["secret"])  # whsec_...
+
+zoplio.list_webhooks()
+zoplio.delete_webhook(hook["id"])
+```
+
+Verify deliveries with the static helper — pass the RAW request body:
+
+```python
+# e.g. Flask
+@app.post("/zoplio-hook")
+def zoplio_hook():
+    ok = ZoplioClient.verify_webhook_signature(
+        request.get_data(),                          # raw bytes
+        request.headers.get("X-Zoplio-Signature", ""),
+        os.environ["ZOPLIO_WEBHOOK_SECRET"],         # whsec_...
+    )
+    if not ok:
+        return "", 401
+    delivery = request.get_json()  # {"event", "payload", "timestamp"}
+    return "", 200
+```

zoplio-0.2.0/src/zoplio.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+src/zoplio/__init__.py
+src/zoplio/client.py
+src/zoplio/py.typed
+src/zoplio/types.py
+src/zoplio.egg-info/PKG-INFO
+src/zoplio.egg-info/SOURCES.txt
+src/zoplio.egg-info/dependency_links.txt
+src/zoplio.egg-info/requires.txt
+src/zoplio.egg-info/top_level.txt
+tests/test_webhook_signature.py

zoplio-0.2.0/src/zoplio.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

zoplio-0.2.0/src/zoplio.egg-info/requires.txt

@@ -0,0 +1,5 @@
+httpx>=0.27
+
+[dev]
+pytest>=8.0
+mypy>=1.0

zoplio-0.2.0/src/zoplio.egg-info/top_level.txt

@@ -0,0 +1 @@
+zoplio

zoplio-0.2.0/tests/test_webhook_signature.py

@@ -0,0 +1,35 @@
+"""Webhook HMAC verification — pinned against the SAME vector the JS SDK and
+the webhooks service use (packages/sdk-js/src/__tests__/client.test.ts and
+apps/webhooks/src/services/__tests__/webhookSignature.test.ts). A drift here
+silently breaks every Python consumer's signature check, so this must match
+byte-for-byte."""
+
+from zoplio.client import ZoplioClient
+
+SECRET = "whsec_0123456789abcdef0123456789abcdef0123456789abcdef"
+BODY = (
+    '{"event":"meeting.confirmed","payload":{"meetingId":"meet_1",'
+    '"title":"Standup"},"timestamp":"2026-06-11T08:00:00.000Z"}'
+)
+SIG = "700d795ed0445ce5a1fb659ef36f540684c5595b2818f96368e4d7062a1f9433"
+
+
+def test_accepts_known_good_vector_str():
+    assert ZoplioClient.verify_webhook_signature(BODY, SIG, SECRET) is True
+
+
+def test_accepts_known_good_vector_bytes():
+    assert ZoplioClient.verify_webhook_signature(BODY.encode("utf-8"), SIG, SECRET) is True
+
+
+def test_rejects_wrong_signature():
+    assert ZoplioClient.verify_webhook_signature(BODY, "0" * 64, SECRET) is False
+
+
+def test_rejects_tampered_body():
+    tampered = BODY.replace("Standup", "Tampered")
+    assert ZoplioClient.verify_webhook_signature(tampered, SIG, SECRET) is False
+
+
+def test_rejects_wrong_secret():
+    assert ZoplioClient.verify_webhook_signature(BODY, SIG, "whsec_wrong") is False