bookingkoala-api-mcp 1.0.2__py3-none-any.whl

bookingkoala_api_mcp/__init__.py

@@ -0,0 +1,28 @@
+"""Self-hosted API and MCP server for one app (see app.py). Personal use only, see LICENSE.
+
+From Python, without a server:
+
+    from bookingkoala_api_mcp import call
+    bookings = call("list_bookings", status="upcoming")["bookings"]
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+__version__ = "1.0.2"
+
+
+def call(tool: str, args: dict[str, Any] | None = None, **kwargs: Any) -> Any:
+    """Run one tool with the saved session and return its answer. Raises ToolError on failure."""
+    from bookingkoala_api_mcp.runner import Runner
+
+    async def go() -> Any:
+        runner = Runner()
+        try:
+            return await runner.run(tool, {**(args or {}), **kwargs})
+        finally:
+            await runner.close()
+
+    return asyncio.run(go())

bookingkoala_api_mcp/api.py

@@ -0,0 +1,213 @@
+"""The REST API and the MCP endpoint on one port.
+
+- `GET|POST|PUT|PATCH|DELETE <app.API_PREFIX>/<route>`: each tool at its route, the same paths as the
+  hosted API at cotlet.dev. Path parts and the query string are arguments; a JSON body adds the rest.
+- `POST <app.API_PREFIX>/tools/{name}`: any tool by name, the JSON body is its arguments.
+- `GET <app.API_PREFIX>/tools`: every tool with its schema. OpenAPI at `/docs` and `/openapi.json`.
+- `/mcp`: the MCP server over streamable HTTP.
+
+With <ENV>_MCP_TOKEN set, every request needs `Authorization: Bearer <token>`.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import hmac
+import json
+import os
+import re
+from collections.abc import AsyncIterator, Awaitable, Callable
+from typing import Any
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
+
+from bookingkoala_api_mcp import __version__, app, mcp_server
+from bookingkoala_api_mcp.core.errors import HTTP_STATUS, ErrorCode, ToolError
+from bookingkoala_api_mcp.core.tools import ToolSpec
+from bookingkoala_api_mcp.runner import Runner, description, tools
+
+PREFIX = app.API_PREFIX
+ASGI = Callable[[dict[str, Any], Callable[[], Awaitable[Any]], Callable[[Any], Awaitable[None]]], Awaitable[None]]
+
+
+def _error(code: ErrorCode, message: str) -> JSONResponse:
+    return JSONResponse({"error": code.value, "message": message}, status_code=HTTP_STATUS.get(code, 500))
+
+
+def _typed(value: str, schema: dict[str, Any]) -> Any:
+    kind = schema.get("type")
+    try:
+        if kind == "integer":
+            return int(value)
+        if kind == "number":
+            return float(value)
+    except ValueError:
+        return value
+    if kind == "boolean":
+        return value.lower() in ("1", "true", "yes", "on")
+    if kind == "array":
+        return [_typed(v, schema.get("items") or {}) for v in value.split(",") if v]
+    if kind == "object":
+        with contextlib.suppress(ValueError):
+            return json.loads(value)
+    return value
+
+
+def _route_order(spec: ToolSpec) -> list[int]:
+    """Literal segments before {placeholders}, so /groups/discover wins over /groups/{group}."""
+    path = (spec.route or "").split(" ", 1)[1]
+    return [1 if part.startswith("{") else 0 for part in path.strip("/").split("/")]
+
+
+def _tag(path: str) -> str:
+    """OpenAPI group: the part after /groups/{group}/ (posts, members ...), else the first part."""
+    parts = path.strip("/").split("/")
+    return parts[2] if parts[:2] == ["groups", "{group}"] and len(parts) > 2 else parts[0]
+
+
+def _openapi(spec: ToolSpec, method: str, path: str) -> dict[str, Any]:
+    props: dict[str, Any] = spec.input_schema.get("properties") or {}
+    required = set(spec.input_schema.get("required") or [])
+    in_path = set(re.findall(r"\{(\w+)\}", path))
+    parameters = [
+        {"name": name, "in": "path", "required": True, "schema": props.get(name, {"type": "string"})}
+        for name in in_path
+    ]
+    rest = {k: v for k, v in props.items() if k not in in_path}
+    extra: dict[str, Any] = {}
+    if method == "GET":
+        parameters += [
+            {"name": name, "in": "query", "required": name in required, "schema": schema}
+            for name, schema in rest.items()
+        ]
+    elif rest:
+        body = {"type": "object", "properties": rest, "required": sorted(required - in_path)}
+        extra["requestBody"] = {"required": bool(body["required"]), "content": {"application/json": {"schema": body}}}
+    if spec.example_response:
+        extra["responses"] = {
+            "200": {"description": "OK", "content": {"application/json": {"example": spec.example_response}}}
+        }
+    return {"parameters": parameters, **extra}
+
+
+async def _arguments(request: Request, spec: ToolSpec) -> dict[str, Any]:
+    props: dict[str, Any] = spec.input_schema.get("properties") or {}
+    args: dict[str, Any] = {}
+    if request.method != "GET":
+        raw = await request.body()
+        if raw.strip():
+            try:
+                body = json.loads(raw)
+            except ValueError:
+                raise ToolError("The body must be a JSON object.", ErrorCode.INVALID_INPUT) from None
+            if not isinstance(body, dict):
+                raise ToolError("The body must be a JSON object.", ErrorCode.INVALID_INPUT)
+            args.update(body)
+    for name in request.query_params:
+        values = request.query_params.getlist(name)
+        schema = props.get(name) or {}
+        args[name] = (
+            [_typed(v, schema.get("items") or {}) for v in values]
+            if schema.get("type") == "array" and len(values) > 1
+            else _typed(values[-1], schema)
+        )
+    for name, value in request.path_params.items():
+        args[name] = _typed(value, props.get(name) or {})
+    return args
+
+
+def create_app(runner: Runner) -> ASGI:
+    manager = StreamableHTTPSessionManager(app=mcp_server.build(runner), json_response=True, stateless=True)
+    token = os.environ.get(f"{app.ENV}_MCP_TOKEN", "").strip()
+
+    @contextlib.asynccontextmanager
+    async def lifespan(_: FastAPI) -> AsyncIterator[None]:
+        async with manager.run():
+            yield
+        await runner.close()
+
+    api = FastAPI(
+        title=f"{app.NAME} API (self-hosted)",
+        version=__version__,
+        description=f"Your {app.NAME} account as a REST API, run on your machine with your Chrome's session.",
+        lifespan=lifespan,
+    )
+
+    async def call(spec: ToolSpec, args: dict[str, Any]) -> JSONResponse:
+        try:
+            result = await runner.run(spec.name, args)
+        except ToolError as exc:
+            return _error(exc.code, str(exc))
+        return JSONResponse(result)
+
+    def endpoint(spec: ToolSpec) -> Callable[[Request], Awaitable[JSONResponse]]:
+        async def handle(request: Request) -> JSONResponse:
+            try:
+                args = await _arguments(request, spec)
+            except ToolError as exc:
+                return _error(exc.code, str(exc))
+            return await call(spec, args)
+
+        return handle
+
+    @api.get(f"{PREFIX}/tools", summary="Every tool with its route and input schema")
+    async def list_tools() -> list[dict[str, Any]]:
+        return [
+            {
+                "name": spec.name,
+                "title": spec.title,
+                "access": spec.access,
+                "route": spec.route,
+                "description": description(spec),
+                "input_schema": spec.input_schema,
+                "example_response": spec.example_response,
+            }
+            for spec in tools(runner.read_only)
+        ]
+
+    @api.post(f"{PREFIX}/tools/{{name}}", summary="Call any tool by name; the JSON body is its arguments")
+    async def call_by_name(name: str, request: Request) -> JSONResponse:
+        raw = await request.body()
+        try:
+            args = json.loads(raw) if raw.strip() else {}
+        except ValueError:
+            return _error(ErrorCode.INVALID_INPUT, "The body must be a JSON object.")
+        if not isinstance(args, dict):
+            return _error(ErrorCode.INVALID_INPUT, "The body must be a JSON object.")
+        spec = next((s for s in tools() if s.name == name), None)
+        if spec is None:
+            return _error(ErrorCode.UNKNOWN_TOOL, f"No tool '{name}'. GET {PREFIX}/tools lists them.")
+        return await call(spec, args)
+
+    for spec in sorted(tools(runner.read_only), key=_route_order):
+        method, path = (spec.route or "").split(" ", 1)
+        api.add_api_route(
+            PREFIX + path,
+            endpoint(spec),
+            methods=[method],
+            name=spec.name,
+            operation_id=spec.name,
+            summary=spec.title,
+            description=description(spec),
+            tags=[_tag(path)],
+            openapi_extra=_openapi(spec, method, path),
+        )
+
+    async def asgi(
+        scope: dict[str, Any], receive: Callable[[], Awaitable[Any]], send: Callable[[Any], Awaitable[None]]
+    ) -> None:
+        if scope["type"] == "http" and token:
+            sent = dict(scope.get("headers") or []).get(b"authorization", b"").decode()
+            if not hmac.compare_digest(sent, f"Bearer {token}"):
+                await _error(ErrorCode.AUTH_REQUIRED, f"Send Authorization: Bearer <{app.ENV}_MCP_TOKEN>.")(
+                    scope, receive, send
+                )
+                return
+        if scope["type"] == "http" and (scope["path"] == "/mcp" or scope["path"].startswith("/mcp/")):
+            await manager.handle_request(scope, receive, send)
+            return
+        await api(scope, receive, send)
+
+    return asgi

bookingkoala_api_mcp/app.py

@@ -0,0 +1,42 @@
+"""Everything the server knows about BookingKoala outside `bookingkoala/`: names, domains and the session cookie.
+
+The rest of the package reads these values and never names the app itself.
+"""
+
+from __future__ import annotations
+
+NAME = "BookingKoala"
+SLUG = "bookingkoala"
+# The command and the prefix of every environment variable (BOOKINGKOALA_AUTH_TOKEN, BOOKINGKOALA_MCP_TOKEN ...).
+CLI = "bookingkoala-mcp"
+ENV = "BOOKINGKOALA"
+# Requests may reach only these hosts and their subdomains (every store is <store>.bookingkoala.com).
+# Their cookies are read from Chrome.
+DOMAINS = ("bookingkoala.com",)
+# Present only while signed in. The first is the cookie a pasted token sets. The app writes it on the store's
+# own host at sign-in and deletes it at sign-out.
+SESSION_COOKIES = ("IRON_GATEWAY_CTX",)
+# The host a pasted token's cookie belongs to. {store} is the store name, asked for with the token.
+COOKIE_DOMAIN = "{store}.bookingkoala.com"
+# localStorage keys of the app's pages that also hold the session, read at connect from open tabs of the app.
+LOCAL_STORAGE_KEYS = ("currentUser",)
+LOGIN_URL = "https://www.bookingkoala.com/login"
+# A final URL with one of these means the app signed the session out.
+LOGGED_OUT_MARKERS = ("/login",)
+# Paths the tools may only read: sign-in, sign-out, impersonation, password, the merchant's own billing.
+ACCOUNT_PATHS = (
+    r"^/api/v\d+/auth/",
+    r"^/api/v\d+/sessions/",
+    r"^/api/v\d+/merchant/",
+    r"^/api/v\d+/merchant-(setup-intent|coupon)",
+    r"^/api/v\d+/users/\d+/password",
+    r"^/bkaffiliates/v\d+/promoters/login-token",
+)
+# A 401 or 403 whose body has one of these asks for a fresh sign-in before the action. BookingKoala has none.
+RELOGIN_MARKERS: tuple[str, ...] = ()
+# REST routes live under this path, the same as on cotlet.dev.
+API_PREFIX = "/api/v1/bookingkoala"
+# Prepended to the MCP server's instructions: where an agent starts.
+AGENT_START = (
+    "Start with dashboard or list_bookings: their booking, customer and provider ids are what the other tools take."
+)

bookingkoala_api_mcp/bookingkoala/auth.py

@@ -0,0 +1,26 @@
+"""Who is signed in: the store owner's own user record (GET /api/v6/users/{id}), for "Signed in as ..."."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from bookingkoala_api_mcp.bookingkoala.client import api, session
+from bookingkoala_api_mcp.core.errors import AuthExpiredError
+
+if TYPE_CHECKING:
+    from bookingkoala_api_mcp.core.context import ToolContext
+
+
+async def whoami(ctx: ToolContext) -> str | None:
+    """None only when BookingKoala says signed out; any other failure raises (detection tries again later)."""
+    s = session(ctx)
+    if s is None:
+        return None
+    try:
+        me = await api(ctx, "GET", f"/api/v6/users/{s.user_id}", s=s) or {}
+    except AuthExpiredError:
+        return None
+    name = " ".join(p for p in (me.get("first_name"), me.get("last_name")) if p).strip()
+    email = me.get("email_id")
+    who = f"{name} ({email})" if name and email else name or email or None
+    return f"{who}, {s.store}" if who else None

bookingkoala_api_mcp/bookingkoala/client.py

@@ -0,0 +1,183 @@
+"""BookingKoala's admin API, recorded on the dev account (21.10.2026).
+
+Each business is its own host, `<store>.bookingkoala.com`, and the admin app (Angular, `cdn.bookingkoala.com/
+admin-build`) calls `/api/v3`, `/api/v6` and the other `/<service>/v<n>/` paths on that host. A call needs three
+things, else the app answers HTTP 200 with `api_status` 0 and "Unauthorized request":
+
+- `authorization: Bearer <token>`: the token from sign-in. The app keeps it in `localStorage.currentUser` and in
+  the cookie `IRON_GATEWAY_CTX` (URL-encoded JSON `{Ip, token, id, role}`, 30 days, set by the app's JS at
+  sign-in, deleted at sign-out). The other cookies do not authenticate.
+- `auth-session-v2`: base64 of `<csrf>__<store>__<nonce>`, where `<csrf>` is the `data` of
+  `GET /bkutility/v1/preload` (no auth; it also sets the httpOnly `iron_csrf_token` cookie the csrf is checked
+  against) and `<nonce>` is base64 of 32 random bytes, new for every request (a repeated one answers
+  "Request expired"). The app refreshes the csrf every 25 minutes.
+- the `iron_csrf_token` cookie from that preload.
+
+The `ip` header the app sends (the browser's address from `/getip/`) is not checked: any value passes, and the
+session is not bound to the exit IP. A bad or expired token answers `api_status` 10, "Session Expired", which is
+the only signed-out answer: the core cannot see it (HTTP 200), so `api` turns it into `auth_expired`.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import secrets
+import time
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+from urllib.parse import unquote, urlsplit
+
+from bookingkoala_api_mcp.core.errors import AuthExpiredError, ErrorCode, ToolError
+
+if TYPE_CHECKING:
+    from bookingkoala_api_mcp.core.context import ToolContext
+    from bookingkoala_api_mcp.core.profile import Cookie
+
+WWW = "https://www.bookingkoala.com"
+SESSION_COOKIE = "IRON_GATEWAY_CTX"
+CSRF_COOKIE = "iron_csrf_token"
+_SUFFIX = ".bookingkoala.com"
+# BookingKoala's own hosts, never a store.
+_NOT_STORES = {"www", "cdn", "help", "files", "api"}
+# api_status in the answer: 1 done, 10 signed out; 99 csrf refused (the app fetches a new one).
+_OK, _SIGNED_OUT, _CSRF_REFUSED = 1, 10, 99
+# "#101-13" (csrf cookie does not match) and "#101-16" (request expired) also mean a stale csrf.
+_STALE_CSRF = ("#101-13", "#101-16")
+# The app renews its csrf every 25 minutes; this one is renewed a little sooner.
+_CSRF_TTL_S = 20 * 60
+# (browser_id, origin) -> (csrf, fetched at epoch seconds). In this process's memory only, never in Redis.
+_csrf: dict[tuple[str, str], tuple[str, float]] = {}
+
+
+@dataclass(frozen=True)
+class Session:
+    origin: str
+    store: str
+    token: str
+    user_id: int
+    role: str
+    ip: str
+
+
+def store_of(host: str) -> str | None:
+    """`yourstore` for `yourstore.bookingkoala.com`; None for BookingKoala's own hosts."""
+    host = host.lstrip(".").lower()
+    if not host.endswith(_SUFFIX):
+        return None
+    store = host.removesuffix(_SUFFIX)
+    return store if store and "." not in store and store not in _NOT_STORES else None
+
+
+def _parse(raw: str | None) -> dict[str, Any] | None:
+    if not raw:
+        return None
+    try:
+        value = json.loads(raw)
+    except ValueError:
+        return None
+    return value if isinstance(value, dict) and value.get("token") and value.get("id") else None
+
+
+def session_from(cookies: Iterable[Cookie], local_storage: dict[str, dict[str, str]]) -> Session | None:
+    """The store and token in these cookies or this localStorage; None when they hold none."""
+    found: tuple[str, dict[str, Any]] | None = None
+    for cookie in cookies:
+        if cookie.name != SESSION_COOKIE or not (store := store_of(cookie.domain)):
+            continue
+        if user := _parse(unquote(cookie.value)):
+            found = (store, user)
+            break
+    if found is None:
+        for origin, values in local_storage.items():
+            if (store := store_of(urlsplit(origin).hostname or "")) and (user := _parse(values.get("currentUser"))):
+                found = (store, user)
+                break
+    if found is None:
+        return None
+    store, user = found
+    return Session(
+        origin=f"https://{store}{_SUFFIX}",
+        store=store,
+        token=str(user["token"]),
+        user_id=int(user["id"]),
+        role=str(user.get("role") or ""),
+        ip=str(user.get("Ip") or ""),
+    )
+
+
+def session(ctx: ToolContext) -> Session | None:
+    """The store and token the browser is signed in with; None when it holds none.
+
+    The session is in the cookie, in localStorage, or in both, so both are read.
+    """
+    return session_from(ctx.profile.cookies, ctx.profile.local_storage)
+
+
+def require_session(ctx: ToolContext) -> Session:
+    s = session(ctx)
+    if s is None:
+        raise AuthExpiredError("The app signed this account out. Sign in again in Chrome, then reconnect.")
+    return s
+
+
+async def _csrf_token(ctx: ToolContext, s: Session, *, fresh: bool = False) -> str:
+    key = (ctx.profile.browser_id, s.origin)
+    cached = _csrf.get(key)
+    if cached and not fresh and time.time() - cached[1] < _CSRF_TTL_S:
+        return cached[0]
+    response = await ctx.call("GET", f"{s.origin}/bkutility/v1/preload", headers=_headers(s, None))
+    data = (response.json().get("response") or {}).get("data")
+    if not isinstance(data, str) or not data:
+        raise ToolError("BookingKoala did not answer its preload.", ErrorCode.TARGET_ERROR)
+    _csrf[key] = (data, time.time())
+    return data
+
+
+def auth_headers(s: Session, csrf: str) -> dict[str, str]:
+    """What an admin call adds to the page's own headers; a new nonce each time. login.py sends them from the tab."""
+    nonce = base64.b64encode(secrets.token_bytes(32)).decode()
+    signed = base64.b64encode(f"{csrf}__{s.store}__{nonce}".encode()).decode()
+    return {"authorization": f"Bearer {s.token}", "ip": s.ip, "auth-session-v2": signed}
+
+
+async def request_headers(ctx: ToolContext) -> dict[str, str]:
+    """Bearer, `ip` and a fresh `auth-session-v2` for one admin call."""
+    s = require_session(ctx)
+    return auth_headers(s, await _csrf_token(ctx, s))
+
+
+def _headers(s: Session, csrf: str | None) -> dict[str, str]:
+    headers = {
+        "accept": "application/json, text/plain, */*",
+        "origin": s.origin,
+        "referer": f"{s.origin}/admin/dashboard",
+    }
+    return headers if csrf is None else {**headers, **auth_headers(s, csrf)}
+
+
+async def api(ctx: ToolContext, method: str, path: str, *, s: Session | None = None, **kwargs: Any) -> Any:
+    """One admin API call (`path` from the host root, e.g. `/api/v6/users/1`); returns `response.data`.
+
+    `AuthExpiredError` when the app says signed out, `ToolError` on any other refusal. A stale csrf gets one
+    new preload and one retry.
+    """
+    s = s or require_session(ctx)
+    extra = kwargs.pop("headers", None) or {}
+    answer: dict[str, Any] = {}
+    for attempt in range(2):
+        csrf = await _csrf_token(ctx, s, fresh=attempt > 0)
+        response = await ctx.call(method, f"{s.origin}{path}", headers={**_headers(s, csrf), **extra}, **kwargs)
+        body = response.json()
+        answer = (body.get("response") if isinstance(body, dict) else None) or {}
+        status, message = answer.get("api_status"), str(answer.get("message") or "")
+        if status == _SIGNED_OUT:
+            raise AuthExpiredError("The app signed this account out. Sign in again in Chrome, then reconnect.")
+        if status == _OK:
+            return answer.get("data")
+        if status != _CSRF_REFUSED and not message.startswith(_STALE_CSRF):
+            break
+    raise ToolError(
+        f"BookingKoala refused {method} {path}: {answer.get('message') or 'no answer'}.", ErrorCode.TARGET_ERROR
+    )

bookingkoala_api_mcp/bookingkoala/tools/_bookings.py

@@ -0,0 +1,130 @@
+"""Booking shapes shared by the booking tools.
+
+Bookings are small integers (`_id`). A booking's `status` is a number: 0 upcoming, 1 completed, 8 unassigned
+(seen on the team store); the others come from the list filter the panel uses. Times: `booking_date`
+`YYYY-MM-DD`, `arrival_time` an `HHMM` number in the store's time zone.
+"""
+
+from __future__ import annotations
+
+from datetime import date
+from typing import Any
+
+from bookingkoala_api_mcp.core.errors import ErrorCode, ToolError
+
+BOOKING_ID: dict[str, Any] = {"type": "integer", "minimum": 1, "description": "Booking id from list_bookings."}
+PROVIDER_ID: dict[str, Any] = {
+    "type": "integer",
+    "minimum": 1,
+    "description": "Provider or team id (BookingKoala's provider `_id`).",
+}
+# Seen on the team store: 0 upcoming, 1 completed, 8 unassigned. Others pass through as numbers.
+STATUSES = {0: "upcoming", 1: "completed", 2: "cancelled", 8: "unassigned"}
+
+EXAMPLE_BOOKING: dict[str, Any] = {
+    "booking_id": 3,
+    "status": "upcoming",
+    "date": "2026-11-16",
+    "arrival_time": "11:00",
+    "length_minutes": 160,
+    "occurrence": "recurring",
+    "recurring_id": 1,
+    "frequency": "every_4_weeks",
+    "customer": {"customer_id": 2, "name": "Dana Whitfield", "email": "dana.whitfield@example.com"},
+    "address": "540 W 28th Street, New York, NY 10022",
+    "provider_ids": [3],
+    "providers": [{"provider_id": 3, "name": "Marcus Lee"}],
+    "payment_method": "cash",
+    "total": 200.0,
+    "charged": False,
+}
+
+
+def text(value: Any) -> str | None:
+    value = str(value).strip() if value is not None else ""
+    return value or None
+
+
+def time_of(value: Any) -> str | None:
+    """`1100` -> `11:00`; None when unset."""
+    if not isinstance(value, int | float) or value < 0:
+        return None
+    hours, minutes = divmod(int(value), 100)
+    return f"{hours:02d}:{minutes:02d}"
+
+
+def parse_time(value: str, field: str) -> int:
+    """`11:00`, `9:30` or `14` -> the `HHMM` number BookingKoala keeps."""
+    raw = value.strip().lower().replace(" ", "")
+    pm, am = raw.endswith("pm"), raw.endswith("am")
+    raw = raw.removesuffix("pm").removesuffix("am")
+    hours_raw, _, minutes_raw = raw.partition(":")
+    try:
+        hours, minutes = int(hours_raw), int(minutes_raw or 0)
+    except ValueError:
+        raise ToolError(f"{field} is a time like 09:30.", ErrorCode.INVALID_INPUT) from None
+    if pm and hours < 12:
+        hours += 12
+    if am and hours == 12:
+        hours = 0
+    if not (0 <= hours < 24 and 0 <= minutes < 60):
+        raise ToolError(f"{field} is a time like 09:30.", ErrorCode.INVALID_INPUT)
+    return hours * 100 + minutes
+
+
+def parse_day(value: str, field: str) -> str:
+    try:
+        return date.fromisoformat(value.strip()).isoformat()
+    except ValueError:
+        raise ToolError(f"{field} is a date like 2026-11-16.", ErrorCode.INVALID_INPUT) from None
+
+
+def money(value: Any) -> float | None:
+    try:
+        return round(float(value), 2)
+    except (TypeError, ValueError):
+        return None
+
+
+def status_of(value: Any) -> str | int | None:
+    return STATUSES.get(value, value) if isinstance(value, int) else None
+
+
+def address_text(address: dict[str, Any] | None) -> str | None:
+    if not address:
+        return None
+    line = text(address.get("address"))
+    apt = text(address.get("apt"))
+    return ", ".join(part for part in (line, f"apt {apt}" if apt else None) if part) or None
+
+
+def booking_row(
+    booking: dict[str, Any], users: dict[str, Any] | None = None, addresses: dict[str, Any] | None = None
+) -> dict[str, Any]:
+    """One booking in list form; `users` and `addresses` are the search answer's `users_info` and `addresses`."""
+    users, addresses = users or {}, addresses or {}
+    customer = users.get(str(booking.get("uid"))) or {}
+    provider_ids = [int(pid) for pid in booking.get("provider_ids") or []]
+    return {
+        "booking_id": booking.get("_id"),
+        "status": status_of(booking.get("status")),
+        "date": booking.get("booking_date"),
+        "arrival_time": time_of(booking.get("arrival_time")),
+        "length_minutes": booking.get("length"),
+        "occurrence": booking.get("occurrence"),
+        "recurring_id": booking.get("recurring_id") or None,
+        "frequency": text(booking.get("frequency_repeat_slug")),
+        "customer": {
+            "customer_id": booking.get("uid"),
+            "name": text(customer.get("full_name")),
+            "email": text(customer.get("email_id")),
+        },
+        "address": address_text(addresses.get(str(booking.get("address_id")))),
+        "provider_ids": provider_ids,
+        "providers": [
+            {"provider_id": pid, "name": text((users.get(str(pid)) or {}).get("full_name"))} for pid in provider_ids
+        ],
+        "payment_method": text(booking.get("payment_method")),
+        "total": money(booking.get("final_amount")),
+        "charged": bool(booking.get("is_charged")),
+    }