creno 0.1.0__tar.gz

creno-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+node_modules/
+dist/
+.env
+.env.*
+!.env.example
+!.env.production
+*.log
+.DS_Store
+.turbo/
+
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+build/
+.venv/
+packages/vue/demo/public/
+test-results/
+playwright-report/
+blob-report/
+playwright/.cache/

creno-0.1.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to the `creno` Python package are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+versioning follows [SemVer](https://semver.org/).
+
+## [0.1.0] - 2026-07-28
+
+### Added
+- `CrenoClient`: typed, synchronous client (`httpx`-based) covering
+  `fetch_service_types`, `fetch_availability`, and `create_booking`.
+- A typed exception per API error code, `CrenoConflictError` (409),
+  `CrenoPlanLimitError` (402), `CrenoRateLimitError` (429),
+  `CrenoValidationError`, `CrenoNotFoundError`, `CrenoForbiddenError`,
+  `CrenoAuthenticationError`, and a `CrenoAPIError` base for anything else, so callers can catch the specific failure they care about instead of
+  parsing status codes by hand.
+- Full type hints (`py.typed`), Python 3.9-3.13.
+- Every request identifies itself via `X-Client-Library: python` and a
+  `creno-python/{version}` User-Agent.
+
+### Changed
+- Relicensed to **MIT** (was file-based custom license metadata).

creno-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Solution Lancée
+
+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.

creno-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: creno
+Version: 0.1.0
+Summary: Official Python client for Creno's scheduling and booking API (https://crenoapp.com).
+Project-URL: Homepage, https://crenoapp.com
+Project-URL: Documentation, https://crenoapp.com/docs
+Project-URL: Repository, https://github.com/whythoughts/platform
+Author-email: Solution Lancee <contact@crenoapp.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-client,booking,creno,scheduling
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# creno
+
+Official Python client for [Creno](https://crenoapp.com)'s scheduling and booking API.
+
+```python
+from creno import CrenoClient
+
+with CrenoClient(api_key="pk_live_...") as client:
+    service_types = client.list_service_types()
+    availability = client.get_availability(from_="2026-08-01", to="2026-08-07")
+    booking = client.create_booking(
+        start_at=availability.slots[0].start_at,
+        customer_name="Jane Doe",
+        customer_email="jane@example.com",
+    )
+```
+
+## Install
+
+```
+pip install creno
+```
+
+Requires Python 3.9+. The only runtime dependency is [httpx](https://www.python-httpx.org/).
+
+## Security model
+
+The API key you pass to `CrenoClient` is the same "publishable" key used by Creno's browser widgets (`@creno/react`, `<creno-widget>`). In the browser, safety comes from Creno's per-tenant origin allowlist, not from keeping the key secret. This client makes server-to-server calls with no `Origin` header, so that allowlist check never applies here. Treat the key as sensitive in your own backend even though it's called "publishable" elsewhere.
+
+## Errors
+
+Every non-2xx response raises a subclass of `CrenoError` (`.message`, `.status_code`, `.response_body`):
+
+| Exception | Status | Meaning |
+|---|---|---|
+| `CrenoAuthenticationError` | 401 | Missing or invalid API key |
+| `CrenoForbiddenError` | 403 | Origin not on the tenant's allowlist (shouldn't occur for server-to-server calls) |
+| `CrenoNotFoundError` | 404 | No matching resource, or no scheduling resource configured for this tenant |
+| `CrenoValidationError` | 400 | Request failed validation (for example, a Turnstile challenge) |
+| `CrenoConflictError` | 409 | The requested time slot is no longer available |
+| `CrenoPlanLimitError` | 402 | The tenant's plan limit was reached, carries `.limit_type` and `.plan` |
+| `CrenoRateLimitError` | 429 | Too many requests, rate-limited per API key rather than per IP |
+| `CrenoAPIError` | any | Fallback for network errors or unexpected responses |
+
+`list_service_types` and `get_availability` retry automatically (up to 3 attempts with backoff) on network errors or 5xx responses, since they're read-only. `create_booking` never retries automatically: a lost response after a booking was actually created server-side, followed by a client-side retry, could still submit a second real booking attempt for a real customer, even though Creno's own database can never double-book the same slot. If `create_booking` raises `CrenoAPIError` with an unclear outcome, check the tenant's Creno dashboard before retrying by hand.
+
+## Dates and times
+
+`Slot` and `Booking` fields are real timezone-aware `datetime.datetime` objects, already parsed from the API's ISO-8601 strings. `create_booking`'s `start_at` accepts either a timezone-aware `datetime` or an ISO-8601 string; a naive `datetime` (no `tzinfo`) raises `ValueError` rather than silently guessing a timezone. `get_availability`'s `from_`/`to` accept either a `datetime.date` or a `"YYYY-MM-DD"` string.
+
+Optional fields you don't have, for example `resource_id` or `service_type_id`, should simply be omitted (their default is `None`). This client drops `None` values from the request body before sending, since Creno's API treats a field as "not provided" only when it's absent from the JSON body entirely, not when it's sent as `null`.
+
+## License
+
+[MIT](./LICENSE). See [CHANGELOG.md](./CHANGELOG.md) for release history and the repo root's [SECURITY.md](../../SECURITY.md) to report a vulnerability.
+
+---
+
+Made by [Solution Lancée](https://solutionlancee.com).

creno-0.1.0/README.md

@@ -0,0 +1,59 @@
+# creno
+
+Official Python client for [Creno](https://crenoapp.com)'s scheduling and booking API.
+
+```python
+from creno import CrenoClient
+
+with CrenoClient(api_key="pk_live_...") as client:
+    service_types = client.list_service_types()
+    availability = client.get_availability(from_="2026-08-01", to="2026-08-07")
+    booking = client.create_booking(
+        start_at=availability.slots[0].start_at,
+        customer_name="Jane Doe",
+        customer_email="jane@example.com",
+    )
+```
+
+## Install
+
+```
+pip install creno
+```
+
+Requires Python 3.9+. The only runtime dependency is [httpx](https://www.python-httpx.org/).
+
+## Security model
+
+The API key you pass to `CrenoClient` is the same "publishable" key used by Creno's browser widgets (`@creno/react`, `<creno-widget>`). In the browser, safety comes from Creno's per-tenant origin allowlist, not from keeping the key secret. This client makes server-to-server calls with no `Origin` header, so that allowlist check never applies here. Treat the key as sensitive in your own backend even though it's called "publishable" elsewhere.
+
+## Errors
+
+Every non-2xx response raises a subclass of `CrenoError` (`.message`, `.status_code`, `.response_body`):
+
+| Exception | Status | Meaning |
+|---|---|---|
+| `CrenoAuthenticationError` | 401 | Missing or invalid API key |
+| `CrenoForbiddenError` | 403 | Origin not on the tenant's allowlist (shouldn't occur for server-to-server calls) |
+| `CrenoNotFoundError` | 404 | No matching resource, or no scheduling resource configured for this tenant |
+| `CrenoValidationError` | 400 | Request failed validation (for example, a Turnstile challenge) |
+| `CrenoConflictError` | 409 | The requested time slot is no longer available |
+| `CrenoPlanLimitError` | 402 | The tenant's plan limit was reached, carries `.limit_type` and `.plan` |
+| `CrenoRateLimitError` | 429 | Too many requests, rate-limited per API key rather than per IP |
+| `CrenoAPIError` | any | Fallback for network errors or unexpected responses |
+
+`list_service_types` and `get_availability` retry automatically (up to 3 attempts with backoff) on network errors or 5xx responses, since they're read-only. `create_booking` never retries automatically: a lost response after a booking was actually created server-side, followed by a client-side retry, could still submit a second real booking attempt for a real customer, even though Creno's own database can never double-book the same slot. If `create_booking` raises `CrenoAPIError` with an unclear outcome, check the tenant's Creno dashboard before retrying by hand.
+
+## Dates and times
+
+`Slot` and `Booking` fields are real timezone-aware `datetime.datetime` objects, already parsed from the API's ISO-8601 strings. `create_booking`'s `start_at` accepts either a timezone-aware `datetime` or an ISO-8601 string; a naive `datetime` (no `tzinfo`) raises `ValueError` rather than silently guessing a timezone. `get_availability`'s `from_`/`to` accept either a `datetime.date` or a `"YYYY-MM-DD"` string.
+
+Optional fields you don't have, for example `resource_id` or `service_type_id`, should simply be omitted (their default is `None`). This client drops `None` values from the request body before sending, since Creno's API treats a field as "not provided" only when it's absent from the JSON body entirely, not when it's sent as `null`.
+
+## License
+
+[MIT](./LICENSE). See [CHANGELOG.md](./CHANGELOG.md) for release history and the repo root's [SECURITY.md](../../SECURITY.md) to report a vulnerability.
+
+---
+
+Made by [Solution Lancée](https://solutionlancee.com).

creno-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "creno"
+version = "0.1.0"
+description = "Official Python client for Creno's scheduling and booking API (https://crenoapp.com)."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "Solution Lancee", email = "contact@crenoapp.com" }]
+keywords = ["creno", "scheduling", "booking", "api-client"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Operating System :: OS Independent",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27,<1"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "mypy>=1.11", "ruff>=0.6"]
+
+[project.urls]
+Homepage = "https://crenoapp.com"
+Documentation = "https://crenoapp.com/docs"
+Repository = "https://github.com/whythoughts/platform"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/creno"]
+
+[tool.ruff]
+line-length = 110
+target-version = "py39"
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+
+[tool.pytest.ini_options]
+markers = ["integration: real HTTP tests against a running Creno API instance"]
+testpaths = ["tests"]

creno-0.1.0/scripts/verify_live.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+"""Runs real requests against a live Creno API instance and prints the results.
+
+This is the standalone, human-runnable proof that the SDK actually works end
+to end, separate from the mocked/gated test suites in tests/.
+
+Usage:
+    pnpm dev:api   # from the platform repo root, in one terminal
+
+    CRENO_API_URL=http://localhost:3000 \\
+    CRENO_API_KEY=<a real seeded tenant's publishable key> \\
+    python scripts/verify_live.py
+"""
+
+import os
+import sys
+import uuid
+from datetime import date, timedelta
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "src"))
+
+from creno import CrenoClient, CrenoError  # noqa: E402
+
+
+def main() -> int:
+    api_url = os.environ.get("CRENO_API_URL", "http://localhost:3000")
+    api_key = os.environ.get("CRENO_API_KEY")
+    if not api_key:
+        print("Set CRENO_API_KEY to a real tenant's publishable key before running this script.")
+        return 1
+
+    with CrenoClient(api_key=api_key, base_url=api_url) as client:
+        print(f"Connecting to {api_url} ...")
+
+        service_types = client.list_service_types()
+        print(f"Service types: {len(service_types)} found")
+        for service_type in service_types:
+            print(f"  - {service_type.name} (active={service_type.active})")
+
+        today = date.today()
+        availability = client.get_availability(from_=today, to=today + timedelta(days=14))
+        print(f"Availability ({availability.timezone}): {len(availability.slots)} open slots in the next 14 days")
+
+        if not availability.slots:
+            print("No open slots in the next 14 days, cannot verify booking creation. Seed more availability and re-run.")
+            return 0
+
+        slot = availability.slots[0]
+        print(f"Booking the first open slot: {slot.start_at.isoformat()}")
+        try:
+            booking = client.create_booking(
+                start_at=slot.start_at,
+                customer_name="Creno SDK Verification",
+                customer_email=f"sdk-verify-{uuid.uuid4().hex[:8]}@example.com",
+                notes="Created by scripts/verify_live.py, safe to delete.",
+            )
+        except CrenoError as exc:
+            print(f"Booking failed: {exc.message} (status {exc.status_code})")
+            return 1
+
+        print(f"Booking created: id={booking.id} status={booking.status}")
+        return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

creno-0.1.0/src/creno/__init__.py

@@ -0,0 +1,32 @@
+from ._version import __version__
+from .client import CrenoClient
+from .exceptions import (
+    CrenoAPIError,
+    CrenoAuthenticationError,
+    CrenoConflictError,
+    CrenoError,
+    CrenoForbiddenError,
+    CrenoNotFoundError,
+    CrenoPlanLimitError,
+    CrenoRateLimitError,
+    CrenoValidationError,
+)
+from .models import Availability, Booking, ServiceType, Slot
+
+__all__ = [
+    "__version__",
+    "CrenoClient",
+    "CrenoError",
+    "CrenoAuthenticationError",
+    "CrenoForbiddenError",
+    "CrenoNotFoundError",
+    "CrenoValidationError",
+    "CrenoConflictError",
+    "CrenoPlanLimitError",
+    "CrenoRateLimitError",
+    "CrenoAPIError",
+    "ServiceType",
+    "Slot",
+    "Availability",
+    "Booking",
+]

creno-0.1.0/src/creno/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

creno-0.1.0/src/creno/client.py

@@ -0,0 +1,201 @@
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from ._version import __version__
+from .exceptions import (
+    CrenoAPIError,
+    CrenoAuthenticationError,
+    CrenoConflictError,
+    CrenoError,
+    CrenoForbiddenError,
+    CrenoNotFoundError,
+    CrenoPlanLimitError,
+    CrenoRateLimitError,
+    CrenoValidationError,
+)
+from .models import Availability, Booking, DateLike, DatetimeLike, ServiceType, to_date_str, to_iso
+
+DEFAULT_BASE_URL = "https://api.crenoapp.com"
+DEFAULT_TIMEOUT = 10.0
+
+# Only applied to the two read-only GET endpoints, never to create_booking
+# (see its docstring for why).
+_MAX_RETRY_ATTEMPTS = 3
+_RETRY_BASE_DELAY_SECONDS = 0.2
+
+
+def _drop_none(values: Dict[str, Any]) -> Dict[str, Any]:
+    return {key: value for key, value in values.items() if value is not None}
+
+
+class CrenoClient:
+    """Synchronous client for Creno's public scheduling and booking API.
+
+    The API key you pass here is the same "publishable" key used by Creno's
+    browser widgets. In the browser, safety comes from Creno's origin
+    allowlist, not from keeping the key secret. This client makes
+    server-to-server calls with no Origin header, so that allowlist check
+    never applies here, treat the key as sensitive in your own backend.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        transport: Optional[httpx.BaseTransport] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self._client = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            timeout=timeout,
+            headers={
+                "X-API-Key": api_key,
+                "User-Agent": f"creno-python/{__version__}",
+                "X-Client-Library": "python",
+                "Content-Type": "application/json",
+            },
+            transport=transport,
+        )
+
+    def __enter__(self) -> "CrenoClient":
+        return self
+
+    def __exit__(self, *exc_info: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._client.close()
+
+    # -- endpoints -----------------------------------------------------------
+
+    def list_service_types(self, *, resource_id: Optional[str] = None) -> List[ServiceType]:
+        """GET /v1/public/service-types. Retries on network errors or 5xx."""
+        params = _drop_none({"resourceId": resource_id})
+        rows = self._request_idempotent("GET", "/v1/public/service-types", params=params)
+        return [ServiceType._from_api(row) for row in rows]
+
+    def get_availability(
+        self,
+        *,
+        from_: DateLike,
+        to: DateLike,
+        resource_id: Optional[str] = None,
+        service_type_id: Optional[str] = None,
+    ) -> Availability:
+        """GET /v1/public/availability. Retries on network errors or 5xx."""
+        params = _drop_none(
+            {
+                "from": to_date_str(from_),
+                "to": to_date_str(to),
+                "resourceId": resource_id,
+                "serviceTypeId": service_type_id,
+            }
+        )
+        data = self._request_idempotent("GET", "/v1/public/availability", params=params)
+        return Availability._from_api(data)
+
+    def create_booking(
+        self,
+        *,
+        start_at: DatetimeLike,
+        customer_name: str,
+        customer_email: str,
+        resource_id: Optional[str] = None,
+        service_type_id: Optional[str] = None,
+        customer_phone: Optional[str] = None,
+        notes: Optional[str] = None,
+        lang: Optional[str] = None,
+        turnstile_token: Optional[str] = None,
+    ) -> Booking:
+        """POST /v1/public/bookings.
+
+        Never retried automatically: a lost response after the booking was
+        actually created server-side, followed by a client-side retry, could
+        still submit a second real booking attempt to a real customer, even
+        though Creno's own database can never double-book the same slot.
+        """
+        body = _drop_none(
+            {
+                "resourceId": resource_id,
+                "serviceTypeId": service_type_id,
+                "startAt": to_iso(start_at),
+                "customerName": customer_name,
+                "customerEmail": customer_email,
+                "customerPhone": customer_phone,
+                "notes": notes,
+                "lang": lang,
+                "turnstileToken": turnstile_token,
+            }
+        )
+        data = self._request("POST", "/v1/public/bookings", json=body)
+        return Booking._from_api(data)
+
+    # -- internals -------------------------------------------------------------
+
+    def _request_idempotent(self, method: str, path: str, *, params: Dict[str, Any]) -> Any:
+        last_error: Optional[CrenoError] = None
+        for attempt in range(_MAX_RETRY_ATTEMPTS):
+            try:
+                return self._request(method, path, params=params)
+            except CrenoError as exc:
+                retryable = exc.status_code is None or exc.status_code >= 500
+                if not retryable or attempt == _MAX_RETRY_ATTEMPTS - 1:
+                    raise
+                last_error = exc
+                time.sleep(_RETRY_BASE_DELAY_SECONDS * (2**attempt))
+        assert last_error is not None  # pragma: no cover - loop always raises or returns
+        raise last_error
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        json: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        try:
+            response = self._client.request(method, path, params=params, json=json)
+        except httpx.TransportError as exc:
+            raise CrenoAPIError(f"Network error calling the Creno API: {exc}") from exc
+
+        if response.status_code // 100 == 2:
+            if response.status_code == 204 or not response.content:
+                return None
+            return response.json()
+
+        try:
+            body: Any = response.json()
+        except ValueError:
+            body = None
+        message = (body or {}).get("error") if isinstance(body, dict) else None
+        message = message or response.text or response.reason_phrase
+
+        if response.status_code == 401:
+            raise CrenoAuthenticationError(message, status_code=401, response_body=body)
+        if response.status_code == 403:
+            raise CrenoForbiddenError(message, status_code=403, response_body=body)
+        if response.status_code == 404:
+            raise CrenoNotFoundError(message, status_code=404, response_body=body)
+        if response.status_code == 400:
+            raise CrenoValidationError(message, status_code=400, response_body=body)
+        if response.status_code == 409:
+            raise CrenoConflictError(message, status_code=409, response_body=body)
+        if response.status_code == 402:
+            raise CrenoPlanLimitError(
+                message,
+                status_code=402,
+                response_body=body,
+                limit_type=(body or {}).get("limitType") if isinstance(body, dict) else None,
+                plan=(body or {}).get("plan") if isinstance(body, dict) else None,
+            )
+        if response.status_code == 429:
+            raise CrenoRateLimitError(message, status_code=429, response_body=body)
+        raise CrenoAPIError(message, status_code=response.status_code, response_body=body)

creno-0.1.0/src/creno/exceptions.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class CrenoError(Exception):
+    """Base class for every error this client raises.
+
+    `status_code` is None for errors that never got an HTTP response at all
+    (a network failure) rather than a non-2xx one.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        response_body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.response_body = response_body
+
+
+class CrenoAuthenticationError(CrenoError):
+    """401 - the X-API-Key header was missing or didn't match a real key."""
+
+
+class CrenoForbiddenError(CrenoError):
+    """403 - the request's Origin header isn't on the tenant's allowlist.
+
+    This client never sends an Origin header, so this shouldn't occur during
+    normal server-to-server use of this SDK.
+    """
+
+
+class CrenoNotFoundError(CrenoError):
+    """404 - no matching resource, or no scheduling resource configured for this tenant."""
+
+
+class CrenoValidationError(CrenoError):
+    """400 - the request body failed validation (for example, a Turnstile challenge)."""
+
+
+class CrenoConflictError(CrenoError):
+    """409 - the requested time slot is no longer available."""
+
+
+class CrenoPlanLimitError(CrenoError):
+    """402 - the tenant's plan limit has been reached."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        response_body: Any,
+        limit_type: Optional[str],
+        plan: Optional[str],
+    ) -> None:
+        super().__init__(message, status_code=status_code, response_body=response_body)
+        self.limit_type = limit_type
+        self.plan = plan
+
+
+class CrenoRateLimitError(CrenoError):
+    """429 - too many requests. Rate limits are keyed per API key, not per IP."""
+
+
+class CrenoAPIError(CrenoError):
+    """Fallback for network errors, 5xx responses, or any other unexpected response."""

creno-0.1.0/src/creno/models.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date, datetime, timezone
+from typing import Any, Dict, List, Optional, Union
+
+DateLike = Union[str, date]
+DatetimeLike = Union[str, datetime]
+
+
+def _parse_datetime(value: str) -> datetime:
+    # datetime.fromisoformat only accepts "+00:00", not the "Z" suffix Creno's
+    # API actually sends, on Python versions before 3.11.
+    return datetime.fromisoformat(value.replace("Z", "+00:00"))
+
+
+def _parse_optional_datetime(value: Optional[str]) -> Optional[datetime]:
+    return _parse_datetime(value) if value else None
+
+
+def to_iso(value: DatetimeLike) -> str:
+    if isinstance(value, datetime):
+        if value.tzinfo is None:
+            raise ValueError(
+                "datetime values passed to the Creno client must be timezone-aware "
+                "(attach a tzinfo, e.g. datetime.timezone.utc)"
+            )
+        return value.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
+    return value
+
+
+def to_date_str(value: DateLike) -> str:
+    if isinstance(value, date):
+        return value.isoformat()
+    return value
+
+
+@dataclass(frozen=True)
+class ServiceType:
+    id: str
+    resource_id: str
+    name: str
+    active: bool
+    sort_order: int
+
+    @classmethod
+    def _from_api(cls, data: Dict[str, Any]) -> "ServiceType":
+        return cls(
+            id=data["id"],
+            resource_id=data["resourceId"],
+            name=data["name"],
+            active=data["active"],
+            sort_order=data["sortOrder"],
+        )
+
+
+@dataclass(frozen=True)
+class Slot:
+    start_at: datetime
+    end_at: datetime
+
+    @classmethod
+    def _from_api(cls, data: Dict[str, Any]) -> "Slot":
+        return cls(start_at=_parse_datetime(data["startAt"]), end_at=_parse_datetime(data["endAt"]))
+
+
+@dataclass(frozen=True)
+class Availability:
+    resource_id: str
+    timezone: str
+    slots: List[Slot]
+
+    @classmethod
+    def _from_api(cls, data: Dict[str, Any]) -> "Availability":
+        return cls(
+            resource_id=data["resourceId"],
+            timezone=data["timezone"],
+            slots=[Slot._from_api(row) for row in data["slots"]],
+        )
+
+
+@dataclass(frozen=True)
+class Booking:
+    id: str
+    tenant_id: str
+    resource_id: str
+    service_type_id: Optional[str]
+    customer_name: str
+    customer_email: str
+    customer_phone: Optional[str]
+    start_at: datetime
+    end_at: datetime
+    status: str
+    hold_expires_at: Optional[datetime]
+    notes: Optional[str]
+    created_at: datetime
+
+    @classmethod
+    def _from_api(cls, data: Dict[str, Any]) -> "Booking":
+        return cls(
+            id=data["id"],
+            tenant_id=data["tenantId"],
+            resource_id=data["resourceId"],
+            service_type_id=data.get("serviceTypeId"),
+            customer_name=data["customerName"],
+            customer_email=data["customerEmail"],
+            customer_phone=data.get("customerPhone"),
+            start_at=_parse_datetime(data["startAt"]),
+            end_at=_parse_datetime(data["endAt"]),
+            status=data["status"],
+            hold_expires_at=_parse_optional_datetime(data.get("holdExpiresAt")),
+            notes=data.get("notes"),
+            created_at=_parse_datetime(data["createdAt"]),
+        )

creno-0.1.0/tests/conftest.py

@@ -0,0 +1,17 @@
+import httpx
+import pytest
+
+from creno import CrenoClient
+
+
+@pytest.fixture
+def client_with():
+    """Builds a CrenoClient whose transport is a caller-supplied handler function.
+
+    Usage: client_with(lambda request: httpx.Response(200, json=[]))
+    """
+
+    def make(handler) -> CrenoClient:
+        return CrenoClient(api_key="pk_test_123", transport=httpx.MockTransport(handler))
+
+    return make

creno-0.1.0/tests/test_client_integration.py

@@ -0,0 +1,66 @@
+"""Real HTTP integration tests against a running Creno API instance.
+
+Skipped unless CRENO_TEST_API_URL and CRENO_TEST_API_KEY are set, so a bare
+`pytest` run never silently "passes" without ever touching the network.
+
+    pnpm dev:api    # from the platform repo root, in one terminal
+    CRENO_TEST_API_URL=http://localhost:3000 \\
+    CRENO_TEST_API_KEY=<a real seeded tenant's publishable key> \\
+    pytest tests/test_client_integration.py -m integration
+"""
+
+import os
+import uuid
+from datetime import date, timedelta
+
+import pytest
+
+from creno import CrenoClient
+
+API_URL = os.environ.get("CRENO_TEST_API_URL")
+API_KEY = os.environ.get("CRENO_TEST_API_KEY")
+
+pytestmark = [
+    pytest.mark.integration,
+    pytest.mark.skipif(
+        not API_URL or not API_KEY,
+        reason=(
+            "Set CRENO_TEST_API_URL and CRENO_TEST_API_KEY to run these tests against "
+            "a real running Creno API instance."
+        ),
+    ),
+]
+
+
+@pytest.fixture
+def client():
+    with CrenoClient(api_key=API_KEY, base_url=API_URL) as c:
+        yield c
+
+
+def test_list_service_types_real(client: CrenoClient) -> None:
+    result = client.list_service_types()
+    assert isinstance(result, list)
+
+
+def test_get_availability_real(client: CrenoClient) -> None:
+    today = date.today()
+    availability = client.get_availability(from_=today, to=today + timedelta(days=7))
+    assert availability.timezone
+
+
+def test_create_booking_real(client: CrenoClient) -> None:
+    today = date.today()
+    availability = client.get_availability(from_=today, to=today + timedelta(days=14))
+    if not availability.slots:
+        pytest.skip("No available slots in the next 14 days for the test tenant; seed more availability.")
+
+    slot = availability.slots[0]
+    booking = client.create_booking(
+        start_at=slot.start_at,
+        customer_name="Creno SDK Integration Test",
+        customer_email=f"sdk-integration-test-{uuid.uuid4().hex[:8]}@example.com",
+        notes="Created by the creno Python SDK's integration test suite.",
+    )
+    assert booking.status in ("pending", "confirmed")
+    assert booking.start_at == slot.start_at

creno-0.1.0/tests/test_client_unit.py

@@ -0,0 +1,239 @@
+import json
+
+import httpx
+import pytest
+
+from creno import (
+    CrenoAuthenticationError,
+    CrenoConflictError,
+    CrenoForbiddenError,
+    CrenoNotFoundError,
+    CrenoPlanLimitError,
+    CrenoRateLimitError,
+    CrenoValidationError,
+)
+
+
+def test_sends_api_key_header(client_with):
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["api_key"] = request.headers["x-api-key"]
+        return httpx.Response(200, json=[])
+
+    client_with(handler).list_service_types()
+    assert seen["api_key"] == "pk_test_123"
+
+
+def test_list_service_types_parses_rows(client_with):
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            200,
+            json=[{"id": "st1", "resourceId": "r1", "name": "Haircut", "active": True, "sortOrder": 0}],
+        )
+
+    result = client_with(handler).list_service_types()
+    assert len(result) == 1
+    assert result[0].name == "Haircut"
+    assert result[0].sort_order == 0
+
+
+def test_get_availability_parses_slots(client_with):
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            200,
+            json={
+                "resourceId": "r1",
+                "timezone": "America/Toronto",
+                "slots": [{"startAt": "2026-08-01T13:00:00Z", "endAt": "2026-08-01T13:30:00Z"}],
+            },
+        )
+
+    availability = client_with(handler).get_availability(from_="2026-08-01", to="2026-08-07")
+    assert availability.timezone == "America/Toronto"
+    assert availability.slots[0].start_at.hour == 13
+
+
+def test_get_availability_accepts_date_objects(client_with):
+    from datetime import date
+
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["query"] = dict(request.url.params)
+        return httpx.Response(200, json={"resourceId": "r1", "timezone": "UTC", "slots": []})
+
+    client_with(handler).get_availability(from_=date(2026, 8, 1), to=date(2026, 8, 7))
+    assert seen["query"]["from"] == "2026-08-01"
+    assert seen["query"]["to"] == "2026-08-07"
+
+
+def test_create_booking_omits_none_fields_from_body(client_with):
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["body"] = json.loads(request.read())
+        return httpx.Response(
+            201,
+            json={
+                "id": "b1",
+                "tenantId": "t1",
+                "resourceId": "r1",
+                "serviceTypeId": None,
+                "customerName": "Jane Doe",
+                "customerEmail": "jane@example.com",
+                "customerPhone": None,
+                "startAt": "2026-08-01T13:00:00Z",
+                "endAt": "2026-08-01T13:30:00Z",
+                "status": "confirmed",
+                "holdExpiresAt": None,
+                "notes": None,
+                "createdAt": "2026-08-01T12:00:00Z",
+            },
+        )
+
+    booking = client_with(handler).create_booking(
+        start_at="2026-08-01T13:00:00Z",
+        customer_name="Jane Doe",
+        customer_email="jane@example.com",
+    )
+    assert "resourceId" not in seen["body"]
+    assert "serviceTypeId" not in seen["body"]
+    assert "customerPhone" not in seen["body"]
+    assert booking.status == "confirmed"
+    assert booking.service_type_id is None
+
+
+def test_create_booking_normalizes_aware_datetime_to_utc_iso(client_with):
+    from datetime import datetime, timedelta, timezone
+
+    seen = {}
+    eastern = timezone(timedelta(hours=-4))
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["body"] = json.loads(request.read())
+        return httpx.Response(
+            201,
+            json={
+                "id": "b1",
+                "tenantId": "t1",
+                "resourceId": "r1",
+                "serviceTypeId": None,
+                "customerName": "Jane Doe",
+                "customerEmail": "jane@example.com",
+                "customerPhone": None,
+                "startAt": "2026-08-01T17:00:00Z",
+                "endAt": "2026-08-01T17:30:00Z",
+                "status": "confirmed",
+                "holdExpiresAt": None,
+                "notes": None,
+                "createdAt": "2026-08-01T12:00:00Z",
+            },
+        )
+
+    client_with(handler).create_booking(
+        start_at=datetime(2026, 8, 1, 13, 0, 0, tzinfo=eastern),
+        customer_name="Jane Doe",
+        customer_email="jane@example.com",
+    )
+    assert seen["body"]["startAt"] == "2026-08-01T17:00:00Z"
+
+
+def test_create_booking_rejects_naive_datetime(client_with):
+    from datetime import datetime
+
+    def handler(request: httpx.Request) -> httpx.Response:  # pragma: no cover - should never be called
+        return httpx.Response(201, json={})
+
+    with pytest.raises(ValueError):
+        client_with(handler).create_booking(
+            start_at=datetime(2026, 8, 1, 13, 0, 0),
+            customer_name="Jane Doe",
+            customer_email="jane@example.com",
+        )
+
+
+@pytest.mark.parametrize(
+    "status_code,exc_class",
+    [
+        (401, CrenoAuthenticationError),
+        (403, CrenoForbiddenError),
+        (404, CrenoNotFoundError),
+        (400, CrenoValidationError),
+        (409, CrenoConflictError),
+        (429, CrenoRateLimitError),
+    ],
+)
+def test_error_status_codes_map_to_exceptions(client_with, status_code, exc_class):
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(status_code, json={"error": "boom"})
+
+    with pytest.raises(exc_class) as exc_info:
+        client_with(handler).list_service_types()
+    assert exc_info.value.status_code == status_code
+    assert exc_info.value.message == "boom"
+
+
+def test_plan_limit_error_carries_limit_type_and_plan(client_with):
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            402,
+            json={"error": "Plan limit reached", "limitType": "bookingsPerMonth", "plan": "starter"},
+        )
+
+    with pytest.raises(CrenoPlanLimitError) as exc_info:
+        client_with(handler).create_booking(
+            start_at="2026-08-01T13:00:00Z", customer_name="Jane", customer_email="jane@example.com"
+        )
+    assert exc_info.value.limit_type == "bookingsPerMonth"
+    assert exc_info.value.plan == "starter"
+
+
+def test_get_availability_retries_on_500_then_succeeds(client_with):
+    calls = {"count": 0}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls["count"] += 1
+        if calls["count"] < 2:
+            return httpx.Response(500, json={"error": "boom"})
+        return httpx.Response(200, json={"resourceId": "r1", "timezone": "UTC", "slots": []})
+
+    result = client_with(handler).get_availability(from_="2026-08-01", to="2026-08-07")
+    assert calls["count"] == 2
+    assert result.timezone == "UTC"
+
+
+def test_get_availability_does_not_retry_on_4xx(client_with):
+    calls = {"count": 0}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls["count"] += 1
+        return httpx.Response(404, json={"error": "Resource not found"})
+
+    with pytest.raises(CrenoNotFoundError):
+        client_with(handler).get_availability(from_="2026-08-01", to="2026-08-07")
+    assert calls["count"] == 1
+
+
+def test_create_booking_does_not_retry_on_500(client_with):
+    calls = {"count": 0}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls["count"] += 1
+        return httpx.Response(500, json={"error": "boom"})
+
+    with pytest.raises(Exception):
+        client_with(handler).create_booking(
+            start_at="2026-08-01T13:00:00Z", customer_name="Jane", customer_email="jane@example.com"
+        )
+    assert calls["count"] == 1
+
+
+def test_context_manager_closes_client(client_with):
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, json=[])
+
+    client = client_with(handler)
+    with client:
+        client.list_service_types()
+    assert client._client.is_closed