# Beautifood

> Restaurant queueing, ordering and reservations. Guests (and their AI agents) can browse menus with allergens, check live queues across branches, join a walk-in queue, preorder while waiting, and book tables.

## For AI agents

- MCP server (Streamable HTTP, JSON-RPC, no auth for guest tools): POST /mcp
  - Guest tools: find_restaurants, get_menu, ask_menu_assistant, queue_status, join_queue, check_ticket, cancel_ticket, booking_availability, create_booking
  - Merchant tools (send `Authorization: Bearer bf_pat_…` created in the staff console under Team → AI agent access): merchant_overview, merchant_queue, merchant_sales_report, merchant_set_sold_out
- REST API description: /openapi.json

## Rules for agents

- Confirm party size, name and time with the user before joining a queue or booking.
- Allergen information is provided by each restaurant; tell users with severe allergies to confirm with staff.
- Ticket and booking links contain private tokens: share them only with the user who made the request.

## Key REST endpoints

- GET /api/public/directory — all branches with live queue length and wait estimates
- GET /api/public/branches/{branch}/menu — what the branch serves right now (prices in minor units, allergens, dietary tags, stories). Timed menus (breakfast, lunch…) apply in branch-local time: each dish has `servedNow` and, if not, `nextServed`; during a happy hour `price` is the deal price with `listPrice` and `deal` beside it. `now` lists the menus and deals on now.
- GET /api/public/branches/{branch}/status — live queue by party size
- POST /api/public/branches/{branch}/queue — join the queue {partySize, name, email?}
- GET /api/public/branches/{branch}/availability?day=YYYY-MM-DD&party=N — booking slots
- POST /api/public/branches/{branch}/bookings — book {name, partySize, slotStart(ms), email?}
- POST /api/public/branches/{branch}/assistant — ask the menu assistant {messages:[{role,content}]}

## Webhooks and integrations (for connectors)

- A restaurant can subscribe HTTPS endpoints to events (queue.joined/called/seated/cancelled/no_show, booking.*, order.round_added, kitchen.ready, order.paid, payment.captured/refunded, shift.closed, menu.sold_out/back_in_stock/item_saved). Each delivery is a signed POST: `x-beautifood-signature: t=<unix>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">`, deduped by `x-beautifood-delivery`, retried after 1, 5, 30 min, 2, 6, 12 h.
- Manage them with a staff token (Authorization: Bearer bf_pat_…): GET/POST /api/m/webhooks, PATCH/DELETE /api/m/webhooks/{id}, POST /api/m/webhooks/{id}/test, GET /api/m/webhooks/{id}/deliveries.
- GET /api/m/integrations/brief returns a Markdown brief for a coding agent: the restaurant's ids, every event with an example payload, signature verification code and connector rules. Schemas: /openapi.json (see `webhooks`).

## Storefronts

- Every restaurant has a page at /at/{restaurant-slug}: its published design (theme colours, font, layout, ordered sections, words in English and Chinese) filled with live data (queue per branch, what's served now, deals, story, branches).
- GET /api/public/storefronts/{restaurant-slug} returns the same as JSON, for rendering it anywhere (the open-source storefront template does this).