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

partiful_api_mcp/partiful/client.py

@@ -0,0 +1,118 @@
+"""Partiful's API, recorded on the dev account (21.10.2026).
+
+Every call is a Firebase callable: POST `api.partiful.com/<function>` with `{"data": {"params": {...}}}`,
+answered with `{"result": {"data": ...}}`, and the account's Firebase ID token as `Authorization: Bearer`.
+The `_partiful_session` cookie does not authenticate it (401 without the token) and no page on partiful.com
+renders the user on the server, so the cookie only tells the core that the browser has signed in.
+
+The ID token lives an hour. The web app keeps the Firebase user, with its refresh token, in IndexedDB
+(`firebaseLocalStorageDb`, key `AUTH_USER_KEY`); `id_token` reads that record from the profile's storage for
+partiful.com and trades the refresh token at securetoken.googleapis.com. Google answers with the same
+refresh token, so nothing has to be written back. Tokens stay in this process's memory, never in Redis.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from typing import TYPE_CHECKING, Any
+from urllib.parse import urlencode
+
+from partiful_api_mcp.core.errors import AuthExpiredError, ErrorCode, ToolError
+
+if TYPE_CHECKING:
+    from partiful_api_mcp.core.context import ToolContext
+
+WEB = "https://partiful.com"
+API = "https://api.partiful.com"
+# Public web key of Firebase project getpartiful; Google refuses it without a partiful.com referer.
+FIREBASE_KEY = "AIzaSyCky6PJ7cHRdBKk5X7gjuWERWaKWBHr4_k"
+SECURETOKEN = f"https://securetoken.googleapis.com/v1/token?key={FIREBASE_KEY}"
+AUTH_USER_KEY = f"firebase:authUser:{FIREBASE_KEY}:[DEFAULT]"
+_HEADERS = {"origin": WEB, "referer": f"{WEB}/"}
+# A token this close to its end is refreshed first (seconds).
+_MARGIN_S = 300
+# (browser_id, uid) -> (ID token, expiry as epoch seconds)
+_tokens: dict[tuple[str, str], tuple[str, float]] = {}
+
+
+def firebase_user(ctx: ToolContext) -> dict[str, Any] | None:
+    """The signed-in Firebase user from the browser's storage for partiful.com; None when there is none."""
+    return auth_user(ctx.profile.local_storage)
+
+
+def auth_user(local_storage: dict[str, dict[str, str]]) -> dict[str, Any] | None:
+    """The Firebase user in a jar's or a tab's `local_storage`; None without a uid and a refresh token."""
+    raw = (local_storage.get(WEB) or {}).get(AUTH_USER_KEY)
+    if not raw:
+        return None
+    try:
+        user = json.loads(raw) if isinstance(raw, str) else raw
+    except ValueError:
+        return None
+    if not isinstance(user, dict) or not user.get("uid") or not (user.get("stsTokenManager") or {}).get("refreshToken"):
+        return None
+    return user
+
+
+async def id_token(ctx: ToolContext) -> tuple[str, str]:
+    """(uid, ID token) of the account. `AuthExpiredError` when the browser holds no usable Firebase session."""
+    user = firebase_user(ctx)
+    if user is None:
+        raise AuthExpiredError("The app signed this account out. Reconnect it in the console.")
+    uid, tokens = user["uid"], user["stsTokenManager"]
+    key = (ctx.profile.browser_id, uid)
+    now = time.time()
+    cached = _tokens.get(key)
+    if cached and cached[1] - now > _MARGIN_S:
+        return uid, cached[0]
+    stored, expires_ms = tokens.get("accessToken"), tokens.get("expirationTime") or 0
+    if stored and expires_ms / 1000 - now > _MARGIN_S:
+        _tokens[key] = (stored, expires_ms / 1000)
+        return uid, stored
+    response = await ctx.call(
+        "POST",
+        SECURETOKEN,
+        data=urlencode({"grant_type": "refresh_token", "refresh_token": tokens["refreshToken"]}),
+        headers={**_HEADERS, "content-type": "application/x-www-form-urlencoded"},
+    )
+    answer = response.json()
+    if response.status == 400:
+        # INVALID_REFRESH_TOKEN, TOKEN_EXPIRED, USER_DISABLED, USER_NOT_FOUND: the session is over.
+        raise AuthExpiredError("The app signed this account out. Reconnect it in the console.")
+    if response.status != 200 or not answer.get("id_token"):
+        raise ToolError("Partiful's sign-in service did not renew the session.", ErrorCode.TARGET_ERROR)
+    token = answer["id_token"]
+    _tokens[key] = (token, now + int(answer.get("expires_in") or 3600))
+    return uid, token
+
+
+async def call(
+    ctx: ToolContext,
+    function: str,
+    params: dict[str, Any] | None = None,
+    paging: dict[str, Any] | None = None,
+    *,
+    whole: bool = False,
+) -> Any:
+    """One callable on api.partiful.com; returns `result.data` (`result` with `whole`, for its `paging`).
+
+    `paging` (`cursor`, `maxResults`) goes next to `params`, as the web app sends it. A 401 raises
+    `AuthExpiredError` in `ctx.call`.
+    """
+    _, token = await id_token(ctx)
+    data: dict[str, Any] = {"params": params or {}}
+    if paging:
+        data["paging"] = paging
+    response = await ctx.call(
+        "POST",
+        f"{API}/{function}",
+        json={"data": data},
+        headers={**_HEADERS, "authorization": f"Bearer {token}"},
+    )
+    answer = response.json()
+    if response.status != 200 or "result" not in answer:
+        message = (answer.get("error") or {}).get("message") if isinstance(answer, dict) else None
+        raise ToolError(f"Partiful refused {function}: {message or response.status}.", ErrorCode.TARGET_ERROR)
+    result = answer["result"] or {}
+    return result if whole else result.get("data")

partiful_api_mcp/partiful/editing.py

@@ -0,0 +1,123 @@
+"""Event edits as the web app makes them (recorded 21.10.2026): a Firestore update of `events/{eventId}` with
+`updatedBy`, and the location through the callable `setEventLocation`, which keeps it out of that update.
+
+Guest Approval and a guest limit exclude each other: turning approval on clears `maxCapacity` and the
+waitlist, and the first guest limit turns the waitlist on, as the settings panel does.
+"""
+
+from __future__ import annotations
+
+import time
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+
+from partiful_api_mcp.core.errors import ErrorCode, ToolError
+from partiful_api_mcp.partiful import firestore
+from partiful_api_mcp.partiful.client import call, id_token
+from partiful_api_mcp.partiful.events import moment, zone
+
+if TYPE_CHECKING:
+    from partiful_api_mcp.core.context import ToolContext
+
+# The inputs create_event and update_event share; create_event requires title and start_at.
+FIELDS: dict[str, Any] = {
+    "title": {"type": "string", "minLength": 1, "maxLength": 200, "description": "Event title."},
+    "start_at": {
+        "type": "string",
+        "description": "Start, ISO 8601. Without an offset it is read in the event's time zone.",
+    },
+    "end_at": {"type": "string", "description": "End, ISO 8601. Optional; must be after start_at."},
+    "timezone": {"type": "string", "description": "IANA zone the event is shown in, e.g. America/New_York."},
+    "location": {"type": "string", "maxLength": 300, "description": "Address, place name or link."},
+    "description": {"type": "string", "maxLength": 5000, "description": "Event details shown on the page."},
+    "rsvp_deadline": {"type": "string", "description": "Last moment guests can RSVP, ISO 8601."},
+    "max_guests": {
+        "type": ["integer", "null"],
+        "minimum": 1,
+        "description": "Guest limit; RSVPs over it go to the waitlist. null removes the limit.",
+    },
+    "guest_approval": {
+        "type": "boolean",
+        "description": "Guests ask to join and you approve them (Guest Approval). Clears max_guests.",
+    },
+    "questions": {
+        "type": "array",
+        "items": {"type": "string", "minLength": 1, "maxLength": 200},
+        "maxItems": 10,
+        "description": "Guest Questionnaire, short-answer questions asked at RSVP. An empty list turns it off.",
+    },
+}
+
+
+async def apply(ctx: ToolContext, event_id: str, old: dict[str, Any], args: dict[str, Any]) -> list[str]:
+    """Writes the given inputs to the event `old` (getEventInfo's event); returns the input names changed."""
+    uid, _ = await id_token(ctx)
+    tz_name = args.get("timezone") or old.get("timezone") or ctx.profile.timezone
+    tz = zone(tz_name)
+    changes: dict[str, Any] = {}
+    remove: list[str] = []
+    append: dict[str, list[Any]] = {}
+    if "timezone" in args:
+        changes["timezone"] = tz.key
+    for name, field in (("title", "title"), ("description", "description")):
+        if name in args:
+            changes[field] = args[name].strip() if name == "title" else args[name]
+    start = moment(args["start_at"], tz, "start_at") if args.get("start_at") else _stored(old.get("startDate"))
+    end = moment(args["end_at"], tz, "end_at") if args.get("end_at") else _stored(old.get("endDate"))
+    if args.get("start_at"):
+        changes["startDate"] = start
+    if args.get("end_at"):
+        changes["endDate"] = end
+    if start and end and end <= start and (args.get("start_at") or args.get("end_at")):
+        raise ToolError("end_at must be after start_at.", ErrorCode.INVALID_INPUT)
+    if args.get("rsvp_deadline"):
+        changes["rsvpDeadline"] = moment(args["rsvp_deadline"], tz, "rsvp_deadline")
+    approval = args.get("guest_approval")
+    if approval is True and args.get("max_guests") is not None:
+        raise ToolError("Guest Approval events have no guest limit: give one of the two.", ErrorCode.INVALID_INPUT)
+    if approval is not None:
+        changes["guestAction"] = "APPLY" if approval else "RSVP"
+        if approval:
+            remove.append("maxCapacity")
+            changes["enableWaitlist"] = False
+    if "max_guests" in args:
+        if old.get("guestAction") == "APPLY" and approval is not False and args["max_guests"] is not None:
+            raise ToolError("This event uses Guest Approval, which has no guest limit.", ErrorCode.INVALID_INPUT)
+        if args["max_guests"] is None:
+            remove.append("maxCapacity")
+            changes["enableWaitlist"] = False
+        else:
+            changes["maxCapacity"] = args["max_guests"]
+            if old.get("maxCapacity") is None:
+                changes["enableWaitlist"] = True
+    if "questions" in args:
+        if args["questions"]:
+            base = int(time.time() * 1000)
+            version = {
+                "questions": [
+                    {"id": str(base + i), "text": text.strip(), "required": False, "type": "short_answer"}
+                    for i, text in enumerate(args["questions"])
+                ],
+                "createdAt": datetime.now(UTC),
+                "createdBy": firestore.Ref(f"users/{uid}"),
+            }
+            append["questionnaireVersions"] = [version]
+            changes["questionnaireEnabled"] = True
+        else:
+            changes["questionnaireEnabled"] = False
+    if changes or remove or append:
+        changes["updatedBy"] = firestore.Ref(f"users/{uid}")
+        await firestore.update(ctx, f"events/{event_id}", changes, tuple(remove), append)
+    if "location" in args:
+        await call(
+            ctx,
+            "setEventLocation",
+            {"eventId": event_id, "locationInfo": {"type": "freeform", "value": args["location"].strip()}},
+        )
+    return [name for name in FIELDS if name in args]
+
+
+def _stored(value: Any) -> datetime | None:
+    if not isinstance(value, str) or not value[:1].isdigit():
+        return None
+    return datetime.fromisoformat(value.replace("Z", "+00:00"))

partiful_api_mcp/partiful/events.py

@@ -0,0 +1,158 @@
+"""Events and guests as the tools return them (recorded 21.10.2026, MAP.md).
+
+Partiful keeps start, end and RSVP deadline in UTC with the event's IANA zone next to them; a cloned event
+has `startDate: "TBD"` until it gets a date. Guest statuses are Partiful's own, mapped to the catalog's
+names below.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+from partiful_api_mcp.core.errors import ErrorCode, ToolError
+from partiful_api_mcp.partiful.client import WEB, call, id_token
+
+if TYPE_CHECKING:
+    from partiful_api_mcp.core.context import ToolContext
+
+# Catalog status -> Partiful's guest statuses (getEventInfo `guestStatusCounts`, guest `status`).
+STATUSES: dict[str, tuple[str, ...]] = {
+    "going": ("GOING", "APPROVED"),
+    "maybe": ("MAYBE",),
+    "cant_go": ("DECLINED",),
+    "invited": ("READY_TO_SEND", "SENDING", "SENT", "SEND_ERROR", "DELIVERY_ERROR"),
+    "waitlist": ("WAITLIST", "WAITLISTED_FOR_APPROVAL"),
+    "pending": ("PENDING_APPROVAL",),
+}
+# The rest, shown in list_guests but not counted in `guests`.
+_OTHER = {
+    "INTERESTED": "interested",
+    "WITHDRAWN": "withdrawn",
+    "REJECTED": "rejected",
+    "RESPONDED_TO_FIND_A_TIME": "responded_to_poll",
+}
+STATUS_NAMES = list(STATUSES)
+
+EVENT_ID: dict[str, Any] = {"type": "string", "description": "event_id from list_events."}
+GUEST_IDS: dict[str, Any] = {
+    "type": "array",
+    "items": {"type": "string"},
+    "minItems": 1,
+    "maxItems": 500,
+    "description": "guest_id values from list_guests.",
+}
+
+
+def status_name(status: str | None) -> str:
+    """Partiful's guest status as the catalog name."""
+    for name, values in STATUSES.items():
+        if status in values:
+            return name
+    return _OTHER.get(status or "", (status or "unknown").lower())
+
+
+def counts(item: dict[str, Any]) -> dict[str, int]:
+    """Guests per catalog status from `guestStatusCounts`."""
+    raw = item.get("guestStatusCounts") or {}
+    return {name: sum(int(raw.get(value) or 0) for value in values) for name, values in STATUSES.items()}
+
+
+def zone(name: str | None) -> ZoneInfo:
+    try:
+        return ZoneInfo(name or "UTC")
+    except (ZoneInfoNotFoundError, ValueError) as exc:
+        raise ToolError("timezone must be an IANA name such as America/New_York.", ErrorCode.INVALID_INPUT) from exc
+
+
+def moment(value: str, tz: ZoneInfo, field: str) -> datetime:
+    """An input time as an aware datetime; without an offset it is read in the event's zone."""
+    try:
+        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError as exc:
+        raise ToolError(f"{field} must be ISO 8601, e.g. 2026-11-14T19:00-05:00.", ErrorCode.INVALID_INPUT) from exc
+    return parsed.replace(tzinfo=tz) if parsed.tzinfo is None else parsed
+
+
+def utc_iso(value: datetime) -> str:
+    """The form createEvent takes: UTC with milliseconds."""
+    return value.astimezone(UTC).strftime("%Y-%m-%dT%H:%M:%S.000Z")
+
+
+def local(value: Any, tz_name: str | None) -> str | None:
+    """A stored UTC time in the event's zone with its offset; None for none or TBD."""
+    if not isinstance(value, str) or not value[:1].isdigit():
+        return None
+    parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    try:
+        tz = ZoneInfo(tz_name or "UTC")
+    except (ZoneInfoNotFoundError, ValueError):
+        tz = ZoneInfo("UTC")
+    return parsed.astimezone(tz).isoformat(timespec="seconds")
+
+
+def url(event_id: str) -> str:
+    return f"{WEB}/e/{event_id}"
+
+
+def status(item: dict[str, Any]) -> str:
+    return {"PUBLISHED": "active", "CANCELED": "canceled", "UNSAVED": "draft"}.get(item.get("status") or "", "active")
+
+
+def summary(item: dict[str, Any]) -> dict[str, Any]:
+    """One event in list_events."""
+    tz = item.get("timezone")
+    return {
+        "event_id": item.get("id"),
+        "title": item.get("title"),
+        "start_at": local(item.get("startDate"), tz),
+        "end_at": local(item.get("endDate"), tz),
+        "timezone": tz,
+        "location": item.get("location"),
+        "status": status(item),
+        "guests": counts(item),
+        "url": url(item.get("id") or ""),
+    }
+
+
+def questions(item: dict[str, Any]) -> list[dict[str, Any]]:
+    """The current Guest Questionnaire: `questionnaire`, else the last of `questionnaireVersions`."""
+    current = item.get("questionnaire")
+    if not current and item.get("questionnaireVersions") and item.get("questionnaireEnabled", True):
+        current = item["questionnaireVersions"][-1]
+    return [q for q in (current or {}).get("questions") or [] if isinstance(q, dict)]
+
+
+def detail(item: dict[str, Any]) -> dict[str, Any]:
+    """One event in get_event and the write tools' answers."""
+    tz = item.get("timezone")
+    return {
+        **summary(item),
+        "description": item.get("description"),
+        "rsvp_deadline": local(item.get("rsvpDeadline"), tz),
+        "max_guests": item.get("maxCapacity"),
+        "waitlist": bool(item.get("enableWaitlist")),
+        "guest_approval": item.get("guestAction") == "APPLY",
+        "questions": [q.get("text") for q in questions(item)],
+        "visibility": item.get("visibility"),
+        "short_url": item.get("publicShortUrl"),
+    }
+
+
+async def event_info(ctx: ToolContext, event_id: str) -> dict[str, Any]:
+    """getEventInfo's event, with its id."""
+    data = await call(ctx, "getEventInfo", {"eventId": event_id})
+    item = (data or {}).get("event")
+    if not item:
+        raise ToolError("Partiful has no such event.", ErrorCode.INVALID_INPUT)
+    return {**item, "id": item.get("id") or event_id}
+
+
+async def hosted(ctx: ToolContext, event_id: str) -> dict[str, Any]:
+    """The event, refused unless this account hosts it."""
+    uid, _ = await id_token(ctx)
+    item = await event_info(ctx, event_id)
+    if uid not in (item.get("ownerIds") or []):
+        raise ToolError("Only a host of this event can do that.", ErrorCode.APP_PERMISSION_DENIED)
+    return item

partiful_api_mcp/partiful/firestore.py

@@ -0,0 +1,135 @@
+"""Firestore REST on project getpartiful, with the same Firebase ID token as the callables (21.10.2026).
+
+The web app reads the host's guest list and writes event edits straight to Firestore; no callable does
+either. Security rules let the host read `events/{eventId}` with its `guests` and update the event.
+Documents come in Firestore's typed form (`{"stringValue": ...}`): `decode` and `encode` convert.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import TYPE_CHECKING, Any
+from urllib.parse import urlencode
+
+from partiful_api_mcp.core.errors import ErrorCode, ToolError
+from partiful_api_mcp.partiful.client import WEB, id_token
+
+if TYPE_CHECKING:
+    from partiful_api_mcp.core.context import ToolContext
+
+DATABASE = "projects/getpartiful/databases/(default)"
+DOCUMENTS = f"https://firestore.googleapis.com/v1/{DATABASE}/documents"
+
+
+@dataclass(frozen=True)
+class Ref:
+    """A document reference to write, as the web app writes `updatedBy: users/{uid}`."""
+
+    path: str
+
+
+def decode(value: dict[str, Any]) -> Any:
+    """One typed Firestore value as plain JSON; references become their `collection/id` path."""
+    if "mapValue" in value:
+        return fields(value["mapValue"])
+    if "arrayValue" in value:
+        return [decode(item) for item in value["arrayValue"].get("values") or []]
+    if "integerValue" in value:
+        return int(value["integerValue"])
+    if "referenceValue" in value:
+        return value["referenceValue"].split("/documents/", 1)[-1]
+    if "nullValue" in value:
+        return None
+    for kind in ("stringValue", "booleanValue", "doubleValue", "timestampValue"):
+        if kind in value:
+            return value[kind]
+    return None
+
+
+def fields(document: dict[str, Any]) -> dict[str, Any]:
+    """A document's (or map's) `fields` as a plain dict."""
+    return {name: decode(value) for name, value in (document.get("fields") or {}).items()}
+
+
+def encode(value: Any) -> dict[str, Any]:
+    """A plain value in Firestore's typed form. datetime goes as a timestamp."""
+    if value is None:
+        return {"nullValue": None}
+    if isinstance(value, Ref):
+        return {"referenceValue": f"{DATABASE}/documents/{value.path}"}
+    if isinstance(value, bool):
+        return {"booleanValue": value}
+    if isinstance(value, int):
+        return {"integerValue": str(value)}
+    if isinstance(value, float):
+        return {"doubleValue": value}
+    if isinstance(value, datetime):
+        return {"timestampValue": value.isoformat()}
+    if isinstance(value, dict):
+        return {"mapValue": {"fields": {key: encode(item) for key, item in value.items()}}}
+    if isinstance(value, list):
+        return {"arrayValue": {"values": [encode(item) for item in value]}}
+    return {"stringValue": str(value)}
+
+
+async def _request(ctx: ToolContext, method: str, url: str, body: Any = None) -> Any:
+    _, token = await id_token(ctx)
+    response = await ctx.call(
+        method,
+        url,
+        json=body,
+        headers={"origin": WEB, "referer": f"{WEB}/", "authorization": f"Bearer {token}"},
+    )
+    answer = response.json()
+    if response.status == 404:
+        raise ToolError("Partiful has no such event.", ErrorCode.INVALID_INPUT)
+    if response.status == 403:
+        raise ToolError("Only a host of this event can do that.", ErrorCode.APP_PERMISSION_DENIED)
+    if response.status != 200:
+        raise ToolError("Partiful did not answer the request.", ErrorCode.TARGET_ERROR)
+    return answer
+
+
+async def get(ctx: ToolContext, path: str) -> dict[str, Any]:
+    """One document's fields, with `id`."""
+    document = await _request(ctx, "GET", f"{DOCUMENTS}/{path}")
+    return {"id": document["name"].rsplit("/", 1)[-1], **fields(document)}
+
+
+async def list_page(
+    ctx: ToolContext, path: str, size: int, token: str | None
+) -> tuple[list[dict[str, Any]], str | None]:
+    """One page of a collection: documents with `id`, and the next page token."""
+    query = {"pageSize": size, **({"pageToken": token} if token else {})}
+    answer = await _request(ctx, "GET", f"{DOCUMENTS}/{path}?{urlencode(query)}")
+    docs = [{"id": doc["name"].rsplit("/", 1)[-1], **fields(doc)} for doc in answer.get("documents") or []]
+    return docs, answer.get("nextPageToken") or None
+
+
+async def update(
+    ctx: ToolContext,
+    path: str,
+    changes: dict[str, Any],
+    remove: tuple[str, ...] = (),
+    append: dict[str, list[Any]] | None = None,
+) -> None:
+    """Sets top-level fields of an existing document in one `commit`, as the web app's `Write` does.
+
+    A name in `remove` is in the mask but not in the body, which deletes the field. `append` adds array
+    items server-side (`arrayUnion`), so the stored items are never read back and rewritten.
+    """
+    write: dict[str, Any] = {
+        "update": {
+            "name": f"{DATABASE}/documents/{path}",
+            "fields": {name: encode(value) for name, value in changes.items()},
+        },
+        "updateMask": {"fieldPaths": [*changes, *remove]},
+        "currentDocument": {"exists": True},
+    }
+    if append:
+        write["updateTransforms"] = [
+            {"fieldPath": name, "appendMissingElements": {"values": [encode(item) for item in items]}}
+            for name, items in append.items()
+        ]
+    await _request(ctx, "POST", f"{DOCUMENTS}:commit", {"writes": [write]})

partiful_api_mcp/partiful/guests.py

@@ -0,0 +1,77 @@
+"""The host's guest list: Firestore `events/{eventId}/guests`, one document per guest (recorded 21.10.2026).
+
+No callable gives the host guest ids (`getGuests` refuses a host), so list_guests, approve_guests and
+check_in_guests start here. Questionnaire answers sit in `questionnaireResponse.answers`, keyed by
+question id of the version the guest answered.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from partiful_api_mcp.partiful import firestore
+from partiful_api_mcp.partiful.events import local, questions, status_name
+
+if TYPE_CHECKING:
+    from partiful_api_mcp.core.context import ToolContext
+
+# Firestore's page size for the guests collection; an event holds at most about 1,000 invites.
+_PAGE = 300
+_MAX_PAGES = 10
+
+
+async def all_guests(ctx: ToolContext, event_id: str) -> list[dict[str, Any]]:
+    """Every guest document of the event, oldest RSVP first."""
+    out: list[dict[str, Any]] = []
+    token: str | None = None
+    for _ in range(_MAX_PAGES):
+        docs, token = await firestore.list_page(ctx, f"events/{event_id}/guests", _PAGE, token)
+        out.extend(docs)
+        if not token:
+            break
+    return sorted(out, key=lambda doc: str(doc.get("rsvpDate") or doc.get("createdAt") or ""))
+
+
+def checked_in(doc: dict[str, Any]) -> bool:
+    """`checkIn` is `{checkedInBy, date}` while the guest is checked in."""
+    value = doc.get("checkIn")
+    return bool(value.get("date") or value.get("checkedInBy")) if isinstance(value, dict) else value is True
+
+
+def _answer(value: Any) -> str:
+    if isinstance(value, dict):
+        value = value.get("value", value.get("text", ""))
+    if isinstance(value, list):
+        return ", ".join(str(item) for item in value)
+    return "" if value is None else str(value)
+
+
+def guest(doc: dict[str, Any], event: dict[str, Any]) -> dict[str, Any]:
+    """One guest as list_guests returns it."""
+    response = doc.get("questionnaireResponse") or {}
+    versions = event.get("questionnaireVersions") or []
+    version = response.get("questionnaireVersion")
+    asked = (
+        versions[version].get("questions") or []
+        if isinstance(version, int) and 0 <= version < len(versions)
+        else questions(event)
+    )
+    texts = {q.get("id"): q.get("text") for q in asked if isinstance(q, dict)}
+    answers = response.get("answers") or {}
+    user = doc.get("user")
+    return {
+        "guest_id": doc["id"],
+        "name": doc.get("name"),
+        "status": status_name(doc.get("status")),
+        "count": int(doc.get("count") or 1),
+        "plus_ones": [p.get("name") for p in doc.get("plusOnes") or [] if isinstance(p, dict) and p.get("name")],
+        "checked_in": checked_in(doc),
+        "rsvp_at": local(doc.get("rsvpDate"), event.get("timezone")),
+        "message": doc.get("rsvpMessage") or None,
+        "user_id": user.rsplit("/", 1)[-1] if isinstance(user, str) else None,
+        "answers": [
+            {"question": texts.get(key, key), "answer": _answer(value)}
+            for key, value in answers.items()
+            if _answer(value)
+        ],
+    }