Merge pull request #26 from peek-travel/feat/typed-http-errors-install-webhook-react19

Typed HTTP errors, install-webhook verifier, React 19-safe UI props

Author: oskarbruening

README.md

@@ -109,8 +109,14 @@ Two kinds of failures surface as exceptions:
   rights). Carries `.statusCode === 418`.
 - `RateLimitError` — HTTP 429 after the configured `retryDelaysMs` backoff was
   exhausted. Carries `.statusCode === 429`.
-- `PeekGraphQLError` — the response contained a GraphQL `errors` array, preserved
-  on `.graphqlErrors`.
+- `PeekGraphQLError` — the response contained a GraphQL `errors` array (a
+  resolver-level failure), preserved on `.graphqlErrors`.
+- `PeekHttpError` — the gateway returned a non-2xx HTTP status (other than
+  418/429) with no GraphQL `errors` array — a transport-level failure such as
+  `401` (auth/secret wrong), `404` (wrong app id / not provisioned), or `5xx`.
+  Carries `.statusCode`, `.url`, and the raw `.body` (parsed JSON when possible,
+  otherwise the response text). Surfaced *before* the body is parsed as JSON, so
+  a non-JSON error page reports its real status instead of a JSON parse error.
 - `PiiAccessDisabledError` — a payment / booking-modification operation was
   called on an access service created without `fullCustomerAccess` (see [Access options
   / PII](#access-options--pii)). Carries `.operation` (the blocked method name).
@@ -127,6 +133,7 @@ import {
   RateLimitError,
   AdminAccountRequiredError,
   PeekGraphQLError,
+  PeekHttpError,
 } from '@peektravel/app-utilities';
 
 try {
@@ -136,6 +143,8 @@ try {
     // back off and retry later
   } else if (err instanceof AdminAccountRequiredError) {
     // this install can't perform admin-only operations
+  } else if (err instanceof PeekHttpError) {
+    console.error(err.statusCode, err.url, err.body); // which config is wrong
   } else if (err instanceof PeekGraphQLError) {
     console.error(err.graphqlErrors); // raw gateway errors
   } else {
@@ -229,16 +238,20 @@ Functions runtime) resolve correctly. Its only runtime dependency is
 
 ## 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:
+Receiver apps can consume Peek **booking**, **waiver**, and **install-status**
+webhooks without hand-writing the payload handling. The booking and waiver
+webhooks have a pure parser (construct nothing — no auth/network) that returns a
+clean model; the install-status webhook delivers a signed token, so its helper
+**verifies** it:
 
 ```ts
 import {
   parseBookingWebhook,
   parseWaiverWebhook,
+  verifyInstallWebhook,
   type Booking,
   type Waiver,
+  type InstallWebhookClaims,
 } from "@peektravel/app-utilities";
 
 app.post("/booking-webhook", (req, res) => {
@@ -251,17 +264,38 @@ app.post("/waiver-webhook", (req, res) => {
   const waiver: Waiver = parseWaiverWebhook(req.body, { fullCustomerAccess: true });
   res.sendStatus(200);
 });
+
+app.post("/install-webhook", (req, res) => {
+  try {
+    // The payload IS a signed JWT — verify signature/issuer/audience/expiry:
+    const claims: InstallWebhookClaims = verifyInstallWebhook(req.body, process.env.PEEK_INTERNAL_SECRET!);
+    if (claims.status === "uninstalled") {
+      /* tear down this install */
+    }
+    res.sendStatus(200);
+  } catch {
+    res.sendStatus(401); // bad signature / issuer / audience / expired
+  }
+});
 ```
 
-Both tolerate the delivery envelope / a bare node / a JSON string and never throw
-on malformed input. `parseWaiverWebhook` also takes an optional `AccessOptions`
-(`{ fullCustomerAccess }`) and redacts the participant `guestName` + document `fileUrl`
-by default — see [Access options / PII](#access-options--pii) below. 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).**
+The booking and waiver parsers tolerate the delivery envelope / a bare node / a
+JSON string and never throw on malformed input; **authenticating those deliveries
+is the receiver's job**. `parseWaiverWebhook` also takes an optional
+`AccessOptions` (`{ fullCustomerAccess }`) and redacts the participant `guestName`
++ document `fileUrl` by default — see [Access options / PII](#access-options--pii)
+below. `verifyInstallWebhook(token, secret)` is different: the payload is a signed
+`app_registry_v2` JWT, so it validates the HMAC signature, expiry, issuer, and
+`"Joken"` audience (the same checks as `verifyPeekAuthToken`) and returns typed
+claims (`installId`, `account.id`, `status`, `displayVersion`, and a **nullable**
+`user` for system-initiated events), throwing the underlying `jsonwebtoken` error
+on any failure. The booking and waiver webhooks 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 the **waiver**
+and **install-status** webhooks have fixed payloads, so you just subscribe to
+their event with no query. **The query to register and the full guide:
+[`docs/webhooks.md`](docs/webhooks.md) (shipped).**
 
 ## UI components (`/ui`)
 
@@ -299,6 +333,27 @@ attribute. Exported classes/types and helpers (`iconSvg`, `registerIcon`,
 `portal`, `position`, `toast`) are available from `@peektravel/app-utilities/ui`
 for subclassing or typing.
 
+### Using the components from React 19
+
+React 19 sets JSX props on a custom element as DOM **properties**
+(`el.searchable = true`), not attributes. That's handled for you: every
+reflected/read-only accessor accepts assignment, so `<ody-dropdown-single
+searchable options={items} />` and friends work without the
+`Cannot set property … which has only a getter` crash that a getter-only
+property would otherwise cause. Two things worth knowing:
+
+- **Boolean and data props reflect to the attribute**, so they take effect as
+  expected. Pass booleans as real booleans (`searchable={true}`) and rich data
+  as values (`options={items}`) — the object is reflected as a JSON attribute.
+- **Read-only state accessors are inert to assignment.** Props that mirror live
+  internal state (`isOpen`, `isVisible`) ignore writes — drive them through the
+  imperative methods on a `ref` (`ref.current.openPopover()`, `.show()`) and read
+  them back through the component's `CustomEvent`s, not by setting the prop.
+
+TypeScript still types these accessors as read-only, so a direct
+`el.isOpen = true` in TS is flagged — the setters are a runtime safety net for
+framework-driven assignment, not an invitation to write to derived state.
+
 **Try the gallery:** `npm run sample` builds the package and serves
 `examples/ui-gallery.html`, which shows every component with its variants.
 

docs/internal/ARCHITECTURE.md

@@ -57,10 +57,13 @@ GraphQL) and gateway routing (`cng_backoffice_api-v1` /
 - Exposes **top-level short-form methods** that delegate directly to the
   underlying service, e.g. `peek.getAllProducts()` → `peek.getProductService().getAllProducts()`. Every public service method has a named proxy on `PeekAccessService`; the names are prefixed with the resource noun where disambiguation is needed (e.g. `getBookingById`, `getTimeslotById`).
 - Exposes `verifyPeekAuthToken(token)` to verify HMAC-signed JWTs issued by
-  the Peek app registry (`iss: "app_registry_v2"`), returning
+  the Peek app registry (`iss: "app_registry_v2"`, `aud: "Joken"`), returning
   a fully typed `PeekAuthTokenClaims` (including the nested `PeekAuthTokenUser`
   object). Throws `JsonWebTokenError` / `TokenExpiredError` / `NotBeforeError`
-  from `jsonwebtoken` on failure.
+  from `jsonwebtoken` on failure. The signature-check core (issuer + audience +
+  user mapping) lives in the internal `peek-auth-token.ts` module, shared with
+  the standalone `verifyInstallWebhook` (§ install webhooks) so the two can't
+  drift apart.
 - Composes dependencies between services where needed:
   - `TimeslotService` receives the resource-pool and account-user services (for
     guide resolution).
@@ -104,12 +107,16 @@ Responsibilities:
 - Collapses query whitespace (`\s+` → single space) before sending.
 - Retries HTTP 429 using the configured backoff delays, then throws
   `RateLimitError`.
+- Reads the response body via the shared `parseBody` helper (`text()` → try
+  `JSON.parse`, falling back to raw text) *before* branching on status, so a
+  non-JSON error page never throws a `SyntaxError` that hides the real status.
 - Maps known failures to typed errors:
   - HTTP 418 → `AdminAccountRequiredError`
   - HTTP 429 (after retries) → `RateLimitError`
   - GraphQL `errors` array present → `PeekGraphQLError` (raw errors preserved on
     `.graphqlErrors`)
-  - other non-2xx → generic `Error` with the status.
+  - other non-2xx → `PeekHttpError` (carries `.statusCode`, `.url`, and raw
+    `.body`).
 
 ### 4. Per-resource services
 `src/internal/peek/<resource>/`
@@ -213,7 +220,20 @@ pure `fromWaiverNode` converter, which maps the fixed `snake_case` payload to th
 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`
+webhook module and the model.
+
+The **install-status** webhook (`installs/install-webhook.ts`) is the third and
+most distinct: its payload is not a data node but a **signed `app_registry_v2`
+JWT**, so `verifyInstallWebhook(token, secret)` *verifies* it (signature +
+expiry + issuer + `Joken` audience, via the shared `peek-auth-token.ts` core)
+before mapping to the clean `InstallWebhookClaims` (`installId`, `account.id`,
+`status`, `displayVersion`, and a **nullable** `user` — install lifecycle events
+are often system-initiated). Standalone-function rationale as above, with an
+extra reason: the receiver has no per-install service to inherit a secret from
+yet (the webhook can precede the first session or describe a tear-down), so the
+app secret is passed directly. Like `waivers`, `installs` carries no
+queries/service triad — just the verifier and the (shared `auth-token.ts`) 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.
@@ -315,14 +335,16 @@ pinned by the drift-guard test; `fullCustomerAccess` governs only the runtime re
 The barrel re-exports only the public contract: `PeekAccessService` + its config,
 the `AccessOptions` type (see §4b), each resource service class (and the
 options/result types callers need), all data-model **types** (including
-`PeekAuthTokenClaims` and `PeekAuthTokenUser`), the `Logger` interface +
+`PeekAuthTokenClaims`, `PeekAuthTokenUser`, and the install-webhook
+`InstallWebhookClaims`/`InstallWebhookAccount`), the `Logger` interface +
 `noopLogger`, and the typed error classes (`AdminAccountRequiredError`,
-`RateLimitError`, `PeekGraphQLError`, `PiiAccessDisabledError`, `CngApiError`,
-`AcmeApiError`). Query strings and raw response interfaces are deliberately kept
+`RateLimitError`, `PeekGraphQLError`, `PeekHttpError`, `PiiAccessDisabledError`,
+`CngApiError`, `AcmeApiError`). Query strings and raw response interfaces are deliberately kept
 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).
+`parseWaiverWebhook` plus the install-status verifier `verifyInstallWebhook`
+(and the `Waiver` / `InstallWebhookClaims` model types; see the webhook notes above).
 
 ### 5b. CNG accessor (REST)
 `src/cng-access-service.ts`, `src/internal/cng/`, `src/models/cng/product.ts`
@@ -340,8 +362,10 @@ plumbing rather than forking the package.
   `GraphQLClient`. Builds `${baseUrl}/${appId}/${extendableSlug}/${path}` with
   `extendableSlug = cng_backoffice_api-v1`, GETs it with `X-Peek-Auth: Bearer`
   (no `pk-api-key`, no `{query,variables}` body), and runs through the shared
-  `requestWithRetry` loop. Parses the body as JSON, falling back to raw text
-  when unparseable; non-2xx (other than 418/429) → `CngApiError` (status + body).
+  `requestWithRetry` loop. Reads the body with the shared `parseBody` helper
+  (`http-transport.ts`) — JSON with a raw-text fallback when unparseable — the
+  same helper the Peek `GraphQLClient` and ACME `RestClient` use; non-2xx (other
+  than 418/429) → `CngApiError` (status + body).
 - **Products triad** (`src/internal/cng/products/`) — same shape as every Peek
   resource: `product-queries.ts` (raw REST `ProductNode`/`ProductsResponse`
   interfaces, internal), `product-converter.ts` (pure `fromProductNodes` →
@@ -465,6 +489,17 @@ Load-bearing rules:
   component file). `package.json` `"sideEffects"` is therefore an allow-list
   (`**/ui/**`, `**/*.css`) rather than `false`, so bundlers don't tree-shake the
   registrations away.
+- **React 19 safety at registration.** `define()` (in `base.ts`) runs
+  `addReactSafeSetters` on the class before `customElements.define`: it walks the
+  component's own prototypes (up to `OdyElement`) and gives every getter-only
+  accessor a setter, so React 19 — which assigns JSX props as DOM *properties*
+  (`el.searchable = true`) — can't throw `only a getter`. When the property name
+  maps to an `observedAttribute` the setter **reflects** the value onto that
+  attribute (booleans as presence, objects as JSON, scalars as strings) so the
+  prop takes effect; otherwise it is a no-op for derived/imperative state
+  (`isOpen`). The static `.d.ts` types keep these accessors read-only — the
+  setters are a runtime-only safety net. Documented for consumers in `docs/ui.md`
+  §3.5 and the README.
 - **Dependency-free & token-based.** No `ember-power-select`/`-calendar`,
   `svg-jar`, or bootstrap. Colours/spacing reference the `tokens.css` custom
   properties; icons are inlined; button variant colours (which live in a

docs/ui.md

@@ -109,8 +109,8 @@ placeholder. So the element's children become its body/label content:
 **Vanilla HTML / JS** — declarative; set rich data and add listeners via the
 element reference.
 
-**React** (especially < 19) does not set DOM properties or bind custom events
-from JSX attributes. Use lowercase tag names, a `ref` to set properties, and
+**React < 19** does not set DOM properties or bind custom events from JSX
+attributes. Use lowercase tag names, a `ref` to set properties, and
 `addEventListener` for events:
 
 ```jsx
@@ -128,6 +128,30 @@ function Guests({ columns, rows, onSort }) {
 }
 ```
 
+**React 19** sets JSX props on a custom element as DOM **properties**
+(`el.searchable = true`), not attributes. The components are built for this: every
+reflected/read-only accessor accepts assignment, so passing props directly works
+and does **not** throw the `Cannot set property … which has only a getter` error
+a getter-only property would otherwise raise. Concretely:
+
+- **Reflected props (booleans, and rich data) take effect.** `searchable`,
+  `disabled`, `options`, etc. reflect the assigned value onto the backing
+  attribute — booleans as presence, objects/arrays as a JSON string:
+
+  ```jsx
+  <ody-dropdown-single searchable options={items} value={value} />
+  ```
+
+- **Read-only state accessors ignore assignment.** Props that mirror live
+  internal state (`isOpen`, `isVisible`) are inert to writes — they are not
+  controlled by re-render. Drive them imperatively through a `ref`
+  (`ref.current.openPopover()` / `.show()`) and observe changes via the
+  component's `CustomEvent`s.
+
+TypeScript still types these accessors as read-only (the setters are a runtime
+safety net for framework-driven assignment), so `el.isOpen = true` in TS code is
+flagged — assign only via JSX props / refs as above.
+
 **Vue / Angular** support custom elements natively: bind properties with
 `:prop` / `[prop]` and events with `@event` / `(event)`. (Configure Vue's
 `compilerOptions.isCustomElement` / Angular's `CUSTOM_ELEMENTS_SCHEMA`.)