#SchCP sample booking site

A sandbox for the SchCP reference implementation. It boots the simulated world from src/sim/world.ts (four fictional businesses, a booking platform, three people whose own agents keep their calendars on a personal-calendar service, key apps and agents, all on one machine with a real clock) and puts one web app in front of it:

• a public website for each business, where humans book through a widget, and a profile page for each person (their calendar is private: no widget),
• a host dashboard showing holds, bookings, approvals and the live protocol log (for a person, their own calendar),
• an agent playground, where you play the consumer agent and every step is a real, signed SchCP request made through the SDK.

Humans and agents book from the same calendar, so anything one does shows up for the other. Nothing on the site moves money: SchCP v0.4 never charges anything. A stated price is shown as what the person pays the host directly; a playdate has no price at all. Cancelling is always free and records nothing; what a late cancellation or a no-show means is the host's own business, outside SchCP.

#Run it

npm install
npm run site            # http://127.0.0.1:4600
PORT=5000 npm run site  # another port
HOST=0.0.0.0 npm run site  # listen on all interfaces

Node 22.18 or later runs the TypeScript directly. There is no build step and no extra dependency: plain node:http, static HTML and CSS, and vanilla JS. State lives in memory and resets when you restart. On boot the site seeds a few web and phone bookings, a lunch break and some walk-ins in Rosie's calendar, and two weeks of the people's own commitments (school pickup, swim lessons, football practice) in Noor's and Ellis's calendars.

#Pages

Host ids: maple-street-auto, fades-on-queen, harbourview-dental, rosies-nails, and the people noor-haddad and ellis-moreau (on daybook.example, contacts only; Ellis approves each request, Noor accepts requests from her contacts that fit). Add ?theme=dark or ?theme=light to any page to override the system colour scheme.

#Host dashboard

• Day timeline. One row per resource, one column per hour. Shading marks hours when that resource isn't working. Colours: hold amber, with a live countdown to expiry; booking green; tentative green with a dashed border; needs approval orange; proposed move purple; calendar event grey. A red line marks the current time.
• Needs attention. Active holds, bookings waiting for approval, and open proposals, from any day.
• Needs attention also lists tentative bookings waiting for a participant to confirm (and bookings waiting for the booker to reconfirm), with the deadline counting down, and open change offers with who asked for them. A hold the host placed for a waitlist entry is labelled waitlist offer.
• Bookings for the day. Each shows its channel (◆ agent, ◎ web, ☎ phone), its stated all-in total (or "no price"), and the host's actions: approve or decline a pending booking (decline asks for a registered reason: fully_booked, service_not_offered, needs_consultation or other, plus a message), cancel with a reason (the agent receives a signed booking.cancelled_by_host webhook), propose a new time, and, once the appointment has started, mark it completed or a no-show (a booking status: a no-show bumps the sequence and sends the signed booking.no_show webhook, and nothing more). Where the host keeps a waitlist, decline and cancel offer Release the time to the waitlist; leave it unticked when the time itself is the problem. Under each booking: its price lines when there are several, where it happens (a place the guest named), "open-ended" for a booking with no agreed end, participants and their status (pending with its deadline, accepted, declined, named only), the refusal on a declined, cancelled or expired booking, and the open change offer (who asked, the new time, its all-in total, and the prev hash it chains from). + Phone booking adds a booking the way a front desk would (businesses only).
• Waitlist for the day: each entry's status (waiting, offered, booked, left, lapsed, expired), its place in line, and the hold offered to it with a countdown.
• Protocol event log. Fed by Server-Sent Events from engine.on('event'), plus the webhooks delivered to the playground agent.
• Rosie's calendar (Rosie's Nails only). Lists the events in the shared calendar, marking which ones Rosie typed and which ones the adapter wrote. Sync calendar runs the calendar adapter. Add walk-in writes an event into the calendar the way Rosie would. Agents can't see a walk-in until you sync, which is the reason calendar hosts approve every booking.

#Agent playground scenarios

Each trace step shows the method, the public URL, the status, the time taken and the key fields. Expand a step to see the request and response. Mandates appear when the agent first uses them, along with their constraints and the human's consent statement.

#Things to try

1. Open /m/maple-street-auto/admin in one tab and /playground in another. Run a and watch an amber hold turn green.
2. Book a slot on /m/maple-street-auto, then check availability in the playground (or run a again). The slot you booked is no longer offered.
3. Run f, switch to Rosie's dashboard, and press Approve. The playground continues as soon as the webhook lands.
4. On Rosie's dashboard, add a walk-in at a time an agent can book. The public widget still offers that time until you press Sync calendar.
5. Cancel an agent booking from a dashboard. Bookings made in the playground carry the playground's callback URL, so the event log shows the booking.cancelled_by_host webhook going out.
6. Open Ellis's calendar (/m/ellis-moreau/admin) and run l. The playdate appears on both calendars; Ellis's stays orange until you answer for Ellis.
7. Run j with Fades' dashboard open on the day it picks: the waitlist panel shows the entry go from waiting to offered (with its countdown) to booked. Run k and leave Alex's question unanswered for a moment: the booking sits in Needs attention as tentative until you answer.

#Reaching the SchCP hosts from outside

Port 4600 is the site, not SchCP. Each simulated domain (maplestreetauto.example, chairly.example, rosiesnails.example, …) is its own HTTP server on a local port the operating system picks at start-up. npm run site prints the map, and GET /api/dns returns it as JSON ({"maplestreetauto.example": "http://127.0.0.1:41234", …}).

A client written elsewhere (another language, another SDK) uses it as its resolver: it addresses https://maplestreetauto.example/schcp/v0/…, signs that public URL as @target-uri (§3.2), and sends the request to the local origin the map gives. The hosts reconstruct the public URL themselves, so the signature verifies. implementations/python does this with --resolve maplestreetauto.example=http://127.0.0.1:PORT.

#API used by the pages

These are site endpoints, not SchCP. The SchCP endpoints live on the simulated host hosts.

GET  /api/dns                                          public hostname → local origin of every simulated domain
GET  /api/m/{id}/slots?service=&date=[&resource=]   open slots for one local day (for a person: their own view)
POST /api/m/{id}/book          {service_id,start,name,phone?,resource?,channel?}
GET  /api/m/{id}/dashboard?date=
GET  /api/m/{id}/events        Server-Sent Events (history, protocol, webhook, site)
POST /api/m/{id}/admin/{approve|decline|cancel|propose|no-show|completed}
       {booking_id, reason?, message?, release_to_waitlist?, start?}
       decline: reason ∈ fully_booked|service_not_offered|needs_consultation|other (default other)
       cancel:  reason is free text, sent to the guest
POST /api/m/rosies-nails/calendar/sync
POST /api/m/rosies-nails/calendar/walkin   {date,start,end,name}
POST /api/playground/run       {scenario,host?,auto?}  → NDJSON trace stream
POST /api/playground/answer    {run,id,value}

#Checking the scenarios

npm run site:check                 # every scenario against every host it supports
npm run site:check -- --only=waitlist,participants --verbose
npm run site:check -- --only=participants --auto=decline

It boots the same world as npm run site (no HTTP front door), answers questions with approve (or --auto=…), prints ok or BAD per run with its result, and exits non-zero on any BAD. It skips calendar-approval, which waits for a person on Rosie's dashboard, and walk-away, which waits out a 45 s hold.

auto answers human-in-the-loop questions automatically, for example {"scenario":"participants","auto":"approve"}, which is handy with curl -N.

#Files

• main.ts sets up the HTTP front door, routing, and the JSON, SSE and NDJSON endpoints.
• site.ts boots the world and holds the host registry (businesses and people), the SSE bus, the lookalike hosts, the seed data and the dashboard view model.
• snapshot-extras.ts holds read-only queries the dashboard needs beyond Engine.snapshot(): waitlist entries, bookings waiting on participants, and decoded change offers. It reads the host's store directly and never writes.
• check-scenarios.ts runs every playground scenario headlessly (npm run site:check).
• scenarios.ts contains the playground scenarios and run plumbing (questions, webhook routing).
• trace.ts wraps fetch so that every SDK call becomes a trace step.
• pages.ts renders the server-side page shells.
• static/ holds the stylesheet (design tokens as CSS variables, light-dark() for both themes) and one script per page.
• screenshots/ holds captures for the whitepaper, taken by hand from the v0.3 site; they predate the people and the removal of money.