Merge pull request #7 from peek-travel/booking-hook

Booking hook

Author: oskarbruening

README.md

@@ -196,6 +196,39 @@ both `import` and `require` consumers (including the Node 22 / CommonJS Firebase
 Functions runtime) resolve correctly. Its only runtime dependency is
 `jsonwebtoken`.
 
+## Webhooks
+
+Receiver apps can consume Peek **booking** and **waiver** webhooks without
+hand-writing a payload parser. Each has a pure parser (construct nothing — no
+auth/network) that returns a clean model:
+
+```ts
+import {
+  parseBookingWebhook,
+  parseWaiverWebhook,
+  type Booking,
+  type Waiver,
+} from "@peektravel/app-utilities";
+
+app.post("/booking-webhook", (req, res) => {
+  const booking: Booking = parseBookingWebhook(req.body);
+  res.sendStatus(200);
+});
+
+app.post("/waiver-webhook", (req, res) => {
+  const waiver: Waiver = parseWaiverWebhook(req.body);
+  res.sendStatus(200);
+});
+```
+
+Both tolerate the delivery envelope / a bare node / a JSON string and never throw
+on malformed input. They differ on registration: a **booking** webhook's payload
+shape is set by a GraphQL query configured **once in an external system** (the
+App Store `broadcast_to_url` config) — this package documents and drift-guards
+the exact query to paste there — whereas a **waiver** webhook has a fixed payload,
+so you just subscribe to its event with no query. **The query to register and the
+full guide: [`docs/webhooks.md`](docs/webhooks.md) (shipped).**
+
 ## UI components (`/ui`)
 
 The package also ships framework-agnostic **Web Components** ported from the Peek
@@ -326,6 +359,7 @@ src/ui/                    Web Components + Odyssey CSS (barrel: src/ui/index.ts
 test/                      vitest unit tests (test/ui/* run under happy-dom)
 examples/ui-gallery.html   component gallery (npm run sample)
 dist/                      build output (generated, git-ignored)
+docs/webhooks.md           booking-webhook consumer guide (shipped)
 docs/internal/             maintainer docs (ARCHITECTURE.md — not shipped)
 llms.txt                   AI-agent quickstart (shipped in the package)
 ```

docs/internal/ARCHITECTURE.md

@@ -94,11 +94,52 @@ Resources: `products`, `account-users`, `resource-pools`, `timeslots`,
 `resellers`, `promo-codes`, `daily-notes`, `availability`, `memberships`,
 `bookings`, `reviews`. Clean data shapes live in `src/models/`.
 
+`waivers` is a **webhook-only resource**: it has no GraphQL reads (so no
+queries/service/converter triad), just `src/internal/waivers/waiver-webhook.ts`
+and the `src/models/waiver.ts` model. See the webhook notes below.
+
 A resource may split into more than one triad when it carries a distinct
 sub-domain. `bookings` does: alongside `booking-queries`/`booking-converter`,
 the add-on flows live in `addon-queries.ts` (the `sales` add-ons query + raw
 node shapes) and `addon-converter.ts` (raw node → the internal `AddonItem`
-detail model and the clean public `BookingAddon`). The detailed `AddonItem`
+detail model and the clean public `BookingAddon`).
+
+`bookings` also carries the webhook surface (`booking-webhook.ts`). A Peek
+booking webhook's payload shape is defined by the GraphQL field selection
+registered with it, so the registered query and the parser must stay in lockstep.
+Crucially, that registration is done **once in an external system** (the App
+Store `broadcast_to_url` config), not from consumer code — so the package
+registers nothing at runtime, and the two halves split:
+
+- **The query is a setup-time artifact, not a runtime API.**
+  `BOOKING_WEBHOOK_GQL_QUERY` is the single maximal selection set (guests + full
+  price breakdown always included) built from the same field fragments the read
+  path uses (`bookingQueryFields`, `bookingGuestsFields`, `PRICE_BREAKDOWN_FIELDS`,
+  exported from `booking-queries` for reuse). It is the bare selection set (no
+  `query`/`sales` wrapper — the webhook system supplies that; whitespace
+  collapsed so it drops into a JSON config string). It is **internal** —
+  surfaced for humans/AI through `docs/webhooks.md` and pinned by a drift-guard
+  test that snapshots the exact string, so a field change is caught here before
+  it diverges from the external config (e.g. the connector's `app.json`).
+- **The parser is the only public runtime export.** The pure
+  `parseBookingWebhook(body)` unwraps the `{booking:…}` delivery envelope (or a
+  bare node / JSON string) and runs the existing `fromBookingNode` converter,
+  auto-detecting guests/price-breakdown from the payload (nothing to keep in sync
+  with the registered query) and never throwing on malformed input. Parsing needs
+  no auth, network, or client, so it is a **standalone function, not a method on
+  `PeekAccessService`** (a receiver may not hold gateway credentials).
+
+The **waiver** webhook (`waivers/waiver-webhook.ts`) is the simpler sibling and
+deliberately diverges from the booking shape because the upstream webhook does
+too: it has **no GraphQL query** (the App Store `waiver_webhook_data` output
+format ships a fixed payload, `output_fields_gql_query` is null), so there is no
+query constant and no drift-guard — only a parser. `parseWaiverWebhook(body)`
+unwraps the `{waiver:…}` envelope (or a bare node / JSON string) and runs the
+pure `fromWaiverNode` converter, which maps the fixed `snake_case` payload to the
+flat clean `Waiver` model (defaulting missing fields to `""`/`null`/`false`, so
+it never throws). Same standalone-pure-function rationale as bookings. Because
+there are no reads, `waivers` carries no queries/service triad — just the
+webhook module and the model. The detailed `AddonItem`
 model (refids + reservation statuses) is **internal only** — consumers see just
 the grouped `BookingAddons`; the internal model exists solely so add/remove can
 build their mutation payloads.
@@ -148,7 +189,10 @@ The barrel re-exports only the public contract: `PeekAccessService` + its config
 each resource service class (and the options/result types callers need), all
 data-model **types**, the `Logger` interface + `noopLogger`, and the three typed
 error classes. Query strings and raw response interfaces are deliberately kept
-internal.
+internal — including the booking-webhook registration query
+(`BOOKING_WEBHOOK_GQL_QUERY` stays internal, documented via `docs/webhooks.md`).
+The webhook-related public exports are the two parsers `parseBookingWebhook` and
+`parseWaiverWebhook` (plus the `Waiver` model type; see the webhook notes above).
 
 ### 6. UI components — the `./ui` subpath
 `src/ui/`

docs/webhooks.md

@@ -0,0 +1,141 @@
+# Webhooks
+
+A guide for wiring a receiver app up to Peek "backoffice" webhooks using
+`@peektravel/app-utilities`. Two webhook types are supported today — **booking**
+and **waiver** — and each has a parser that turns the delivered payload into a
+clean data model. They differ in one important way: a booking webhook is
+configured with a GraphQL query (so the package documents the exact query to
+register), while a waiver webhook has a fixed payload (so there's nothing to
+register beyond subscribing to the event).
+
+| Webhook | Register | Parse the delivery |
+| --- | --- | --- |
+| Booking | paste a GraphQL query into the external config (below) | `parseBookingWebhook(body)` → `Booking` |
+| Waiver | subscribe to the event — **no query needed** | `parseWaiverWebhook(body)` → `Waiver` |
+
+Both parsers are pure transforms — no auth, no network, construct nothing.
+
+# Booking webhooks
+
+## The problem this solves
+
+A Peek booking webhook is unusual: its payload shape is **not fixed**. The
+webhook is configured with a GraphQL field selection (`output_fields_gql_query`);
+each time it fires, the gateway runs that selection against the booking and POSTs
+the result to your receiver. So two things must agree — the registered selection
+and the code that parses the payload.
+
+That registration is done **once, in an external system** (the Peek App Store
+`broadcast_to_url` config / your app's `app.json`), not from your application
+code. So the two halves split cleanly:
+
+| Half | Where it lives | This package provides |
+| --- | --- | --- |
+| Register the query | external config, set once | the canonical query string to paste (below) |
+| Parse the delivery | your receiver's code | `parseBookingWebhook(body)` → a clean `Booking` |
+
+The query string below and the parser are derived from the **same** field
+selection this package uses for booking reads, and a test pins the string, so the
+two can't silently drift.
+
+## Step 1 — register this query (external, one-time)
+
+Paste the following into the webhook's `output_fields_gql_query` field (with
+`output_format: "gql"`). It is the **maximal** selection — it includes guests and
+the full price breakdown, so one registration captures everything; the parser
+auto-detects whatever a given payload carries.
+
+```
+{ displayId id primaryGuest { name email phone optinMarketing optinSms isGdpr postalCode } activitySnapshot { type name id } ticketQuantities { quantity resourceOptionSnapshot { name id } } reservationStatus checkinStatus returnStatus fulfillmentStatusOverride { status } timeSnapshot { id legacyId } purchasedAt purchasedAtUtc startsAt startsAtUtc endsAt endsAtUtc availabilityTimeId bookingPortalUrl operatorNotes value { convenienceFee { amount formatted } deposit { amount formatted } discount { amount formatted } discountedPrice { amount formatted } fees { amount formatted } flatPartnerFee { amount formatted } price { amount formatted } retailPrice { amount formatted } taxes { amount formatted } tips { amount formatted } total { formatted amount } } balance { total { amount formatted } } tips { price { amount formatted } } order { displayId id promoCodes { code } channelSnapshot { id name agent { name } } initialQuote { source { actor { app } } } } questionAnswers { answer questionText questionLocationSnapshot { latitude longitude } } tickets { questionAnswers { answer questionText } } resourcePoolAssignments { quantity resourcePool { name shortName resources { name } } resourceAssignments { resource { id name } } } bookingGuests { id name country dateOfBirth email isGdpr isParticipant optinSms optinMarketing phone postalCode fieldResponses { id text fieldLocation { field { name } } } } primaryGuest { id name country dateOfBirth email isGdpr isParticipant optinSms optinMarketing phone postalCode fieldResponses { id text fieldLocation { field { name } } } } }
+```
+
+> This package owns this string internally and snapshots it in
+> `test/bookings/booking-webhook.test.ts`. If the booking fields ever change, the
+> test fails here first — update the test snapshot, this doc, and the external
+> config together.
+
+## Step 2 — parse the delivered webhook into a `Booking`
+
+This is the only part that lives in your code. Hand the raw request body to
+`parseBookingWebhook`; it returns the same clean
+[`Booking`](../README.md#resources) model the read services return.
+
+```ts
+import { parseBookingWebhook, type Booking } from "@peektravel/app-utilities";
+
+app.post("/booking-webhook", (req, res) => {
+  const booking: Booking = parseBookingWebhook(req.body);
+  // booking.bookingId, booking.customerName, booking.startsAt, booking.isCanceled, …
+  res.sendStatus(200);
+});
+```
+
+`parseBookingWebhook`:
+
+- **Needs no auth, network, or `PeekAccessService`** — it is a pure transform.
+  Construct nothing; just call it. (This is why it's a standalone function, not a
+  method on the access service, and why the receiver needs no gateway
+  credentials to parse.)
+- **Tolerates the delivery envelope.** It accepts the `{ booking: … }` wrapper
+  the webhook sends, a bare booking node, or a JSON string body.
+- **Auto-detects** guests and the price breakdown from the payload, so there is
+  nothing to keep in sync with the registered query — `booking.guests` and
+  `booking.taxes`/`booking.fees`/… populate when present.
+- **Never throws on malformed input** — a missing/garbled body yields a `Booking`
+  with empty fields rather than an exception, so a bad delivery can't crash your
+  handler.
+
+## Notes
+
+- The webhook fires on booking **create** and **update**; both deliver the same
+  booking payload, and `parseBookingWebhook` handles them identically. It does
+  not currently surface which event fired.
+- Authenticating the delivery (verifying it really came from Peek) is the
+  receiver's responsibility and out of scope for this parser.
+
+# Waiver webhooks
+
+A waiver webhook fires when a participant signs a liability agreement. Unlike the
+booking webhook, its payload is **fixed** — Peek delivers a predefined shape (the
+`waiver_webhook_data` output format), so there is **no GraphQL query to
+register**.
+
+## Step 1 — subscribe to the event (external, one-time)
+
+Register the webhook for the `agreement_signature_created` event in the external
+config. Leave `output_fields_gql_query` null; the `output_format` is
+`waiver_webhook_data`. There is nothing query-shaped to paste.
+
+## Step 2 — parse the delivered webhook into a `Waiver`
+
+```ts
+import { parseWaiverWebhook, type Waiver } from "@peektravel/app-utilities";
+
+app.post("/waiver-webhook", (req, res) => {
+  const waiver: Waiver = parseWaiverWebhook(req.body);
+  // waiver.bookingId, waiver.templateId, waiver.fileUrl, waiver.signedAt,
+  // waiver.guestName, waiver.isSignedByGuardian, …
+  res.sendStatus(200);
+});
+```
+
+`parseWaiverWebhook` mirrors the booking parser: a pure transform (no
+auth/network/`PeekAccessService`), it tolerates the `{ waiver: … }` envelope / a
+bare node / a JSON string, maps the raw `snake_case` payload to the clean
+camelCase [`Waiver`](#waiver-webhooks) model, and never throws on malformed input
+(missing fields become `""` / `null` / `false`).
+
+The resulting `Waiver` is flat:
+
+| Field | Type | From |
+| --- | --- | --- |
+| `templateId` | `string` | `agreement_template_id` |
+| `bookingId` | `string` | `booking_id` |
+| `fileUrl` | `string` | `file_url` |
+| `signedAt` | `string` | `signed_at` (ISO) |
+| `isSignedByGuardian` | `boolean` | `signed_by_guardian` |
+| `guestName` | `string \| null` | `waiver_data.participant_name` |
+| `isOptinMarketing` | `boolean` | `waiver_data.participant_optin_marketing` |
+| `isOptinSms` | `boolean` | `waiver_data.participant_optin_sms` |
+
+Authenticating the delivery is the receiver's responsibility, as with bookings.

llms.txt

@@ -68,6 +68,24 @@ const peek = new PeekAccessService({
   importable; branch with `instanceof`.
 - Plain `Error` for validation/precondition failures thrown before any request.
 
+## Webhooks (booking + waiver)
+
+Two webhook parsers, each a pure transform — needs no auth/network/
+`PeekAccessService`; accepts the `{<key>:…}` envelope, a bare node, or a JSON
+string; never throws on malformed input. Registration is done **once in an
+external system** (App Store config), not from code.
+
+- `parseBookingWebhook(body): Booking` — auto-detects guests/breakdown. Booking
+  payload shape is defined by a GraphQL selection registered externally; paste
+  the canonical maximal selection into `output_fields_gql_query`. That string is
+  documented in `docs/webhooks.md` and pinned by a drift-guard test — it is NOT a
+  runtime export.
+- `parseWaiverWebhook(body): Waiver` — maps the fixed `snake_case`
+  `waiver_webhook_data` payload to the clean `Waiver` model. **No query to
+  register** — just subscribe to the `agreement_signature_created` event.
+
+**Full guide + booking query-to-register: `docs/webhooks.md` (shipped).**
+
 ## UI components (`@peektravel/app-utilities/ui`)
 
 Browser-only, framework-agnostic Web Components (Custom Elements, light DOM,

package.json

@@ -39,7 +39,8 @@
   "files": [
     "dist",
     "llms.txt",
-    "docs/ui.md"
+    "docs/ui.md",
+    "docs/webhooks.md"
   ],
   "sideEffects": [
     "**/ui/**",

src/index.ts

@@ -36,6 +36,10 @@ export type {
   CancelBookingResult,
 } from "./internal/bookings/booking-service.js";
 
+export { parseBookingWebhook } from "./internal/bookings/booking-webhook.js";
+
+export { parseWaiverWebhook } from "./internal/waivers/waiver-webhook.js";
+
 export { ReviewService } from "./internal/reviews/review-service.js";
 
 export { ADD_ON_PRODUCT_TYPE } from "./models/product.js";
@@ -110,6 +114,7 @@ export type {
   BookingAddonsMutationResult,
 } from "./models/booking-addon.js";
 export type { Guide, Review } from "./models/review.js";
+export type { Waiver } from "./models/waiver.js";
 
 export { noopLogger } from "./logger.js";
 export type { Logger } from "./logger.js";

src/internal/bookings/booking-queries.ts

@@ -35,7 +35,7 @@ const guestFields = `
   }
 `;
 
-const bookingGuestsFields = `
+export const bookingGuestsFields = `
   bookingGuests {
     ${guestFields}
   }
@@ -44,7 +44,7 @@ const bookingGuestsFields = `
   }
 `;
 
-const bookingQueryFields = `
+export const bookingQueryFields = `
   displayId
   id
   primaryGuest {
@@ -158,7 +158,7 @@ const bookingQueryFields = `
   }
 `;
 
-const PRICE_BREAKDOWN_FIELDS = `
+export const PRICE_BREAKDOWN_FIELDS = `
   convenienceFee { amount formatted }
   deposit { amount formatted }
   discount { amount formatted }