creno 0.1.0__py3-none-any.whl

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/_version.py

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

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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+creno/__init__.py,sha256=IyUprdtsDTVMoway1FpcHUq031MdHpOaxxPVdeAa2oM,720
+creno/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+creno/client.py,sha256=QyXhcKob93mEJQhFUvvYYojSqqk4r32gNBmZPdl8fgg,7498
+creno/exceptions.py,sha256=j8xREO7K0tjvXtjnpGrm6z1ZISEN_j4tMj7v222gpjk,2026
+creno/models.py,sha256=QjxLlsUcia05SsIcbgH9dXYF2rOsebmv8vFXZye-qEg,3283
+creno/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+creno-0.1.0.dist-info/METADATA,sha256=_wUymZ32i7YfWsN_zm-1A-cpW5pPM5eCttDGb9hlp5w,4640
+creno-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+creno-0.1.0.dist-info/licenses/LICENSE,sha256=r5WLPHVmSujFz8jqRckdGBi6VvSvAzZ_xv-N-hxvd6g,1073
+creno-0.1.0.dist-info/RECORD,,

creno-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

creno-0.1.0.dist-info/licenses/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.