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

booksy_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 booksy_api_mcp import call
+    services = call("list_services")["services"]
+"""
+
+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 booksy_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())

booksy_api_mcp/api.py

@@ -0,0 +1,212 @@
+"""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 booksy_api_mcp import __version__, app, mcp_server
+from booksy_api_mcp.core.errors import HTTP_STATUS, ErrorCode, ToolError
+from booksy_api_mcp.core.tools import ToolSpec
+from booksy_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 /clients/search wins over /clients/{client_id}."""
+    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 first part of the path (clients, appointments ...)."""
+    return path.strip("/").split("/")[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

booksy_api_mcp/app.py

@@ -0,0 +1,41 @@
+"""Everything the server knows about Booksy outside `booksy/`: names, domains and where the session lives.
+
+The rest of the package reads these values and never names the app itself.
+"""
+
+from __future__ import annotations
+
+NAME = "Booksy"
+SLUG = "booksy"
+# The command and the prefix of every environment variable (BOOKSY_MCP_HOME, BOOKSY_MCP_TOKEN ...).
+CLI = "booksy-mcp"
+ENV = "BOOKSY"
+# Requests may reach only these hosts and their subdomains. Their cookies are read from Chrome.
+DOMAINS = ("booksy.com",)
+# Cookies present only while signed in. Booksy has none that carries the session, so a token cannot be pasted.
+SESSION_COOKIES: tuple[str, ...] = ()
+COOKIE_DOMAIN = ".booksy.com"
+# localStorage read from Chrome at `connect`, by origin. The session is the `_<country>_identity` key of the
+# web-gateway.booksy.com frame the panel embeds; booksy.com's `app.country` says which country the panel has open.
+STORAGE_ORIGINS = ("https://web-gateway.booksy.com", "https://booksy.com")
+# Present only while signed in: origin -> key pattern (regex).
+SESSION_STORAGE = {"https://web-gateway.booksy.com": r"^_[a-z]{2}_identity$"}
+LOGIN_URL = "https://booksy.com/pro/en-us/onboarding/Login"
+# A final URL with one of these means the app signed the session out.
+LOGGED_OUT_MARKERS: tuple[str, ...] = ()
+# Text in a 403 body that means "sign in again": Booksy never answers 401, it names the token field that failed.
+RELOGIN_MARKERS = ('"field":"auth_header_token"', '"field":"access_token"')
+# URL path patterns of the account itself (sign-in, password, deletion): only GET may reach them.
+ACCOUNT_PATHS = (
+    r"/business_api/account(/|$)",
+    r"/business_api/me/?$",
+    r"/business_api/me/(businesses/\d+/)?account_deletion",
+    r"/utils/(password_check|phone_check)",
+)
+# REST routes live under this path, the same as on cotlet.dev.
+API_PREFIX = "/api/v1/booksy"
+# Prepended to the MCP server's instructions: where an agent starts.
+AGENT_START = (
+    "Start with list_services and list_staff: their ids are what the calendar tools take. "
+    "Times are local to the business."
+)

booksy_api_mcp/booksy/auth.py

@@ -0,0 +1,33 @@
+"""Who is signed in: Booksy's own answer for the account (business_api/me) and its businesses."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from booksy_api_mcp.booksy.client import headers, session
+from booksy_api_mcp.core.errors import AuthExpiredError, ErrorCode, ToolError
+
+if TYPE_CHECKING:
+    from booksy_api_mcp.core.context import ToolContext
+
+
+async def whoami(ctx: ToolContext) -> str | None:
+    """None when the gateway holds no identity or Booksy says signed out; any other failure raises."""
+    s = session(ctx)
+    if s is None:
+        return None
+    sent = headers(ctx, s)
+    try:
+        me = await ctx.call("GET", f"{s.api}/business_api/me/", headers=sent)
+        if me.status != 200:
+            raise ToolError(f"Booksy answered {me.status} to who am I.", ErrorCode.TARGET_ERROR)
+        owned = await ctx.call("GET", f"{s.api}/business_api/me/businesses/", headers=sent)
+    except AuthExpiredError:
+        return None
+    account = me.json().get("account") or {}
+    name = f"{account.get('first_name') or ''} {account.get('last_name') or ''}".strip() or account.get("email")
+    businesses = (owned.json().get("businesses") or []) if owned.status == 200 else []
+    # The identity's businessId is the one the panel has open; name it first.
+    businesses.sort(key=lambda b: b.get("id") != s.business_id)
+    names = ", ".join(b["name"] for b in businesses if b.get("name"))
+    return f"{name} ({names})" if name and names else name or None

booksy_api_mcp/booksy/calendar.py

@@ -0,0 +1,247 @@
+"""Calendar, appointments, open slots and time off: requests and shapes shared by those tools."""
+
+from __future__ import annotations
+
+from datetime import date, datetime, timedelta
+from typing import TYPE_CHECKING, Any
+from zoneinfo import ZoneInfo
+
+from booksy_api_mcp.booksy.client import headers, session
+from booksy_api_mcp.core.errors import AuthExpiredError, ErrorCode, ToolError
+
+if TYPE_CHECKING:
+    from booksy_api_mcp.core.context import HttpResponse, ToolContext
+
+
+async def request(
+    ctx: ToolContext,
+    method: str,
+    path: str,
+    *,
+    params: dict[str, Any] | None = None,
+    body: Any = None,
+    business: bool = True,
+) -> HttpResponse:
+    """One API call; `path` is under the open business (`~`) unless `business` is False."""
+    s = session(ctx)
+    if s is None or s.business_id is None:
+        raise AuthExpiredError("Booksy is signed out.")
+    base = f"{s.api}/business_api/me/businesses/{s.business_id}" if business else f"{s.api}/business_api/me"
+    kwargs: dict[str, Any] = {"headers": headers(ctx, s)}
+    if params:
+        kwargs["params"] = params
+    if body is not None:
+        kwargs["json"] = body
+    return await ctx.call(method, f"{base}{path}", **kwargs)
+
+
+def problem(response: HttpResponse) -> str | None:
+    """Booksy's own words for a refused request, or None when it went through."""
+    if response.status < 400:
+        return None
+    try:
+        data = response.json()
+    except ToolError:
+        return f"Booksy refused the request ({response.status})."
+    if isinstance(data, dict):
+        errors = data.get("errors")
+        if isinstance(errors, list) and errors:
+            texts = [_error_text(e) for e in errors if isinstance(e, dict)]
+            if any(texts):
+                return " ".join(t for t in texts if t)
+        if data.get("detail"):
+            return str(data["detail"])
+        for field, value in data.items():
+            if isinstance(value, list) and value and isinstance(value[0], str):
+                return f"{field}: {value[0]}"
+    return f"Booksy refused the request ({response.status})."
+
+
+def _error_text(error: dict[str, Any]) -> str:
+    text = str(error.get("description") or error.get("code") or "")
+    field = error.get("field")
+    return f"{field}: {text}" if field and field != "non_field_errors" and text else text
+
+
+async def ok_json(ctx: ToolContext, method: str, path: str, **kwargs: Any) -> Any:
+    response = await request(ctx, method, path, **kwargs)
+    if response.status == 404:
+        raise ToolError("Booksy has no such record.", ErrorCode.TARGET_ERROR)
+    if (text := problem(response)) is not None:
+        raise ToolError(text, ErrorCode.TARGET_ERROR)
+    return response.json() if response.text.strip() else {}
+
+
+async def business_zone(ctx: ToolContext) -> ZoneInfo:
+    """The business's time zone; times in the API are local to it."""
+    cached = await ctx.cache_get(f"tz:{_business_key(ctx)}")
+    if cached:
+        return ZoneInfo(cached)
+    data = await ok_json(ctx, "GET", "")
+    business = data.get("business") or data
+    name = ((business.get("location") or {}).get("time_zone_name")) or business.get("timezone_name") or "UTC"
+    await ctx.cache_set(f"tz:{_business_key(ctx)}", name, 3600)
+    return ZoneInfo(name)
+
+
+def _business_key(ctx: ToolContext) -> str:
+    s = session(ctx)
+    return f"{s.country}:{s.business_id}" if s else "none"
+
+
+def iso(local: str | None, zone: ZoneInfo) -> str | None:
+    """`YYYY-MM-DDTHH:MM` local to the business as ISO 8601 with its offset."""
+    if not local:
+        return None
+    return datetime.fromisoformat(local).replace(tzinfo=zone).isoformat()
+
+
+def local(value: str, zone: ZoneInfo) -> datetime:
+    """An ISO 8601 input as naive business-local time; a time without a zone is taken as local."""
+    try:
+        moment = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError as exc:
+        raise ToolError(f"Not an ISO 8601 date-time: {value}.", ErrorCode.INVALID_INPUT) from exc
+    if moment.tzinfo is not None:
+        moment = moment.astimezone(zone).replace(tzinfo=None)
+    return moment
+
+
+def stamp(moment: datetime) -> str:
+    return moment.strftime("%Y-%m-%dT%H:%M")
+
+
+def day(value: str) -> date:
+    try:
+        return date.fromisoformat(value)
+    except ValueError as exc:
+        raise ToolError(f"Not a date (YYYY-MM-DD): {value}.", ErrorCode.INVALID_INPUT) from exc
+
+
+def days(start: date, end: date) -> list[date]:
+    return [start + timedelta(days=n) for n in range((end - start).days + 1)]
+
+
+def int_id(value: Any, what: str) -> int:
+    try:
+        return int(str(value).strip())
+    except ValueError as exc:
+        raise ToolError(f"{what} must be a number from Booksy.", ErrorCode.INVALID_INPUT) from exc
+
+
+async def service_variant(ctx: ToolContext, service_id: str) -> tuple[dict[str, Any], dict[str, Any]]:
+    """The service and its first variant (duration, price, staffers); a variant id also finds its service."""
+    wanted = int_id(service_id, "service_id")
+    for service in (await ok_json(ctx, "GET", "/services")).get("services") or []:
+        variants = service.get("variants") or []
+        if service.get("id") == wanted and variants:
+            return service, variants[0]
+        for variant in variants:
+            if variant.get("id") == wanted:
+                return service, variant
+    raise ToolError("No service with this ID in Booksy. Take one from list_services.", ErrorCode.INVALID_INPUT)
+
+
+# Booksy's appointment status letters, as the calendar legend names them.
+STATUSES = {
+    "A": "confirmed",
+    "W": "pending",
+    "C": "cancelled",
+    "D": "declined",
+    "N": "no_show",
+    "F": "finished",
+    "P": "payment_pending",
+    "V": "pending_payment",
+    "R": "rejected",
+    "M": "modified",
+}
+
+
+def status_name(code: Any) -> str:
+    return STATUSES.get(str(code), str(code or "unknown").lower())
+
+
+def appointment_view(appointment: dict[str, Any], customer: dict[str, Any] | None, zone: ZoneInfo) -> dict[str, Any]:
+    """One appointment as the tools return it."""
+    subs = appointment.get("subbookings") or []
+    merged = (customer or {}).get("merged_data") or {}
+    client = None
+    if merged or (appointment.get("customer") or {}).get("id"):
+        client = {
+            "client_id": str(merged.get("id") or (appointment.get("customer") or {}).get("id") or ""),
+            "name": merged.get("full_name") or (appointment.get("customer") or {}).get("name") or "",
+        }
+    services = [
+        {
+            "service_id": str((sub.get("service") or {}).get("id") or ""),
+            "name": (sub.get("service") or {}).get("name") or "",
+            "price": ((sub.get("service") or {}).get("variant") or {}).get("price"),
+            "duration_minutes": ((sub.get("service") or {}).get("variant") or {}).get("duration"),
+            "staff_id": str(sub.get("staffer_id") or ""),
+            "staff": (sub.get("staffer") or {}).get("name") or "",
+            "start": iso(sub.get("booked_from"), zone),
+            "end": iso(sub.get("booked_till"), zone),
+        }
+        for sub in subs
+    ]
+    actions = appointment.get("actions") or {}
+    return {
+        "appointment_id": str(appointment.get("appointment_uid") or ""),
+        "status": status_name(appointment.get("status")),
+        "client": client,
+        "services": services,
+        "staff": services[0]["staff"] if services else "",
+        "start": iso(appointment.get("booked_from"), zone),
+        "end": iso(appointment.get("booked_till"), zone),
+        "total": appointment.get("total_value"),
+        "total_text": appointment.get("total"),
+        "note": appointment.get("business_secret_note") or "",
+        "client_note": appointment.get("business_note") or "",
+        "can": sorted(name for name, allowed in actions.items() if allowed),
+    }
+
+
+async def read_appointment(ctx: ToolContext, appointment_id: str) -> dict[str, Any]:
+    """The raw answer of GET appointments/{uid}/: `appointment` and `customer`."""
+    uid = int_id(appointment_id, "appointment_id")
+    return await ok_json(ctx, "GET", f"/appointments/{uid}/")
+
+
+MAX_DAYS = 31
+
+
+async def calendar(ctx: ToolContext, start: date, end: date) -> dict[str, Any]:
+    """The calendar grid for a day range: every resource, booking, block and time off."""
+    if end < start:
+        raise ToolError("The last day is before the first day.", ErrorCode.INVALID_INPUT)
+    if (end - start).days >= MAX_DAYS:
+        raise ToolError(f"Ask for at most {MAX_DAYS} days at a time.", ErrorCode.INVALID_INPUT)
+    params = {
+        "start_date": start.isoformat(),
+        "end_date": end.isoformat(),
+        "include_unconfirmed": "true",
+        "version": "3",
+        "resources_per_page": "500",
+    }
+    return await ok_json(ctx, "GET", "/calendar", params=params)
+
+
+def staff_names(grid: dict[str, Any]) -> dict[int, str]:
+    return {r["id"]: r.get("name") or "" for r in grid.get("resources") or [] if isinstance(r.get("id"), int)}
+
+
+# Time off is Shifts' whole-day absence, a block is the calendar's time reservation; one id names both.
+TIME_OFF_REASONS = ("vacation", "sick_day", "personal_day", "training", "early", "late", "no_show", "other")
+
+
+def time_off_id(kind: str, raw: Any) -> str:
+    return f"{'off' if kind == 'time_off' else 'block'}-{raw}"
+
+
+def parse_time_off_id(value: str) -> tuple[str, int]:
+    kind, _, raw = value.strip().partition("-")
+    if kind not in ("off", "block") or not raw.isdigit():
+        raise ToolError(
+            "time_off_id comes from add_time_off or list_time_off (off-… or block-…).", ErrorCode.INVALID_INPUT
+        )
+    return ("time_off" if kind == "off" else "block"), int(raw)

booksy_api_mcp/booksy/client.py

@@ -0,0 +1,100 @@
+"""Booksy Biz's session and API, recorded 21.10.2026.
+
+The session is not a cookie. The panel on booksy.com keeps its identity in the `web-gateway.booksy.com` iframe:
+localStorage key `_<country>_identity` (`_pl_identity`), JSON `{accessToken, loginType, profileType, profile}`.
+The gateway script builds the key as `_${country}_identity` and deletes it on sign-out (CLEAR_IDENTITY).
+booksy.com's own storage has no token. Every API call carries the token as `X-Access-Token`, the public
+`X-Api-Key` of the web panel and `X-Fingerprint` (the `_bf` cookie on .booksy.com).
+
+The API host is the country: `https://<country>.booksy.com/core/v2/...` (the bundle's `core` subdomain is
+`{country}`), so the country comes from the identity key and a US account goes to us.booksy.com.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from booksy_api_mcp.core.context import ToolContext
+
+WEB = "https://booksy.com"
+GATEWAY = "https://web-gateway.booksy.com"
+# Public key of the web panel (frontdesk), the same in every country.
+API_KEY = "frontdesk-76661e2b-25f0-49b4-b33a-9d78957a58e3"
+_IDENTITY_KEY = re.compile(r"^_([a-z]{2})_identity$")
+
+
+@dataclass(frozen=True)
+class Session:
+    country: str
+    token: str
+    profile: dict[str, Any]
+
+    @property
+    def api(self) -> str:
+        return f"https://{self.country}.booksy.com/core/v2"
+
+    @property
+    def business_id(self) -> int | None:
+        return self.profile.get("businessId")
+
+
+def _identity(raw: str | None) -> dict[str, Any] | None:
+    if not raw:
+        return None
+    try:
+        value = json.loads(raw)
+    except ValueError:
+        return None
+    if not isinstance(value, dict) or not isinstance(value.get("accessToken"), str):
+        return None
+    return value if value["accessToken"] and isinstance(value.get("profile"), dict) else None
+
+
+def session_of(local_storage: dict[str, dict[str, str]]) -> Session | None:
+    """The signed-in identity in a jar's or a tab's `local_storage`; None when the gateway holds none.
+
+    One browser can hold identities of several countries; the panel's last country (`app.country` on
+    booksy.com) wins, else the first one found.
+    """
+    stored = local_storage.get(GATEWAY) or {}
+    found: dict[str, dict[str, Any]] = {}
+    for key, raw in stored.items():
+        match = _IDENTITY_KEY.match(key)
+        if match and (identity := _identity(raw)) is not None:
+            found[match.group(1)] = identity
+    if not found:
+        return None
+    last = (local_storage.get(WEB) or {}).get("app.country", "").strip('"').lower()
+    country = last if last in found else sorted(found)[0]
+    return Session(country=country, token=found[country]["accessToken"], profile=found[country]["profile"])
+
+
+def session(ctx: ToolContext) -> Session | None:
+    return session_of(ctx.profile.local_storage)
+
+
+def headers(ctx: ToolContext, s: Session) -> dict[str, str]:
+    """What the panel sends with every API call."""
+    found = {
+        "x-api-key": API_KEY,
+        "x-access-token": s.token,
+        "x-app-version": "3.0",
+        "accept": "application/json",
+        "origin": WEB,
+        "referer": f"{WEB}/",
+    }
+    fingerprint = next((c.value for c in ctx.profile.cookies if c.name == "_bf" and c.value), None)
+    if fingerprint:
+        found["x-fingerprint"] = fingerprint
+    return found
+
+
+def request_headers(ctx: ToolContext) -> dict[str, str]:
+    """The tools' identity headers for one request; only the public
+    api key when the gateway holds no identity, so Booksy answers its signed-out 403."""
+    s = session(ctx)
+    return headers(ctx, s) if s is not None else {"x-api-key": API_KEY}