@peektravel/app-utilities 0.5.2 → 0.5.4

package/docs/ui.md

@@ -79,10 +79,10 @@ they work declaratively in plain HTML:
 
 | Component | JS property | JSON attribute fallback |
 |---|---|---|
-| `ody-dropdown-single` / `ody-dropdown-multi` | `el.options = [...]` | `options='[{"value":"a","label":"A"}]'` |
+| `ody-dropdown-single` / `ody-dropdown-multi` / `ody-checkbox-group` | `el.options = [...]` | `options='[{"value":"a","label":"A"}]'` |
 | `ody-tabs` | — | `tabs='[{"id":"a","label":"A"}]'` |
 | `ody-toggle-button` | — | `options='[{"value":"a","label":"A"}]'` |
-| `ody-radio-button-group` / `ody-checkbox-group` | `el.options` (getter) | `options='[{"value":"a","label":"A"}]'` |
+| `ody-radio-button-group` | `el.options` (getter) | `options='[{"value":"a","label":"A"}]'` |
 | `ody-datepicker` | — | `presets='[{"label":"…","value":"…"}]'` |
 | `ody-table` | `el.columns`, `el.data` | none — JS only |
 
@@ -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`.)
@@ -616,12 +640,12 @@ are blocked; on blur the value is clamped/normalised.
 **Use when** several toggles, optionally with a "select all" parent (checked
 when all selected, indeterminate when some).
 **Attributes**
-- `options` — JSON array of `{ label, value }`.
+- `options` — JSON array of `{ label, value }` (also a JS property, below).
 - `value` — comma-separated selected values.
 - `select-all-label` — when present, renders the parent select-all row.
 - `size` — `base` | `small` (default `small`).
 - `disabled` — boolean.
-**Properties (JS)** — `value: string[]` (get returns array, set takes array); `options: OdyCheckboxOption[]` (read-only getter).
+**Properties (JS)** — `value: string[]` (get returns array, set takes array); `options: OdyCheckboxOption[]` (get parses the attribute, set writes the JSON attribute — assign `el.options = [...]` as with `<ody-dropdown-*>`).
 **Events** — `change` → `{ value: string[] }`.
 **Example**
 ```html

package/docs/webhooks.md

@@ -1,19 +1,25 @@
 # 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 |
+`@peektravel/app-utilities`. Three webhook types are supported today —
+**booking**, **waiver**, and **install-status** — and each has a helper 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), a waiver webhook has a fixed payload (so
+there's nothing to register beyond subscribing to the event), and an
+install-status webhook delivers a **signed token** (so the helper *verifies* it
+rather than just parsing it).
+
+| Webhook | Register | Handle 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` |
+| Install-status | subscribe to the event — **no query needed** | `verifyInstallWebhook(token, secret)` → `InstallWebhookClaims` |
 
-Both parsers are pure transforms — no auth, no network, construct nothing.
+The booking and waiver parsers are pure transforms — no auth, no network,
+construct nothing; **authenticating those deliveries is the receiver's job**. The
+install-status webhook is different: its payload *is* a signed JWT, so
+`verifyInstallWebhook` checks the signature for you.
 
 # Booking webhooks
 
@@ -147,3 +153,68 @@ The resulting `Waiver` is flat:
 | `isOptinSms` | `boolean` | `waiver_data.participant_optin_sms` |
 
 Authenticating the delivery is the receiver's responsibility, as with bookings.
+
+# Install-status webhooks
+
+## The problem this solves
+
+Peek's app registry notifies your app of install lifecycle changes — installed,
+uninstalled, status changed — by POSTing a **signed `app_registry_v2` JWT**.
+Unlike a booking or waiver webhook, the whole payload *is* the token, so
+verifying its signature is the point: it proves the notification really came from
+Peek before your app acts on it (for example, de-provisioning an uninstall).
+Hand-rolling that check (issuer, audience, expiry, HMAC) is exactly the
+security-critical boilerplate `verifyInstallWebhook` removes.
+
+## Step 1 — subscribe to the event (external, one-time)
+
+Nothing to register in code: subscribe your endpoint to the install-status event
+in the App Store config. There is no GraphQL selection to paste.
+
+## Step 2 — verify the delivered token
+
+Extract the JWT from the delivery (the request body, or the `Authorization`
+header with the `Bearer ` prefix stripped) and pass it — plus your app's signing
+secret (the same `jwtSecret` you construct `PeekAccessService` with) — to
+`verifyInstallWebhook`:
+
+```ts
+import { verifyInstallWebhook, type InstallWebhookClaims } from "@peektravel/app-utilities";
+
+app.post("/webhooks/install", (req, res) => {
+  let claims: InstallWebhookClaims;
+  try {
+    claims = verifyInstallWebhook(req.body /* raw JWT string */, process.env.PEEK_INTERNAL_SECRET!);
+  } catch {
+    return res.sendStatus(401); // signature/issuer/audience/expiry failed
+  }
+
+  if (claims.status === "uninstalled") {
+    // tear down this install's resources
+  }
+  res.sendStatus(200);
+});
+```
+
+`verifyInstallWebhook` validates the HMAC signature, the token expiry, the
+`"app_registry_v2"` issuer, and the `"Joken"` audience — the same checks as
+[`PeekAccessService.verifyPeekAuthToken`](../README.md#access-options--pii) — then
+maps the payload to the clean `InstallWebhookClaims`. It throws the underlying
+`jsonwebtoken` error (`JsonWebTokenError` / `TokenExpiredError` /
+`NotBeforeError`) on any verification failure, so a single `try/catch` → `401`
+covers every bad-token case.
+
+The signature checks are strict (they are the security boundary); claim
+*extraction* is defensive, so a validly-signed token that omits an optional field
+yields an empty value rather than throwing. The resulting `InstallWebhookClaims`:
+
+| Field | Type | From | Notes |
+| --- | --- | --- | --- |
+| `installId` | `string` | `sub` | Peek-assigned install UUID |
+| `account.id` | `string` | `account.id` | account that owns the install |
+| `status` | `string` | `status` | e.g. `"installed"`, `"uninstalled"` |
+| `displayVersion` | `string` | `display_version` | `""` when absent |
+| `user` | `PeekAuthTokenUser \| null` | `user` | `null` for system-initiated events |
+
+Unlike `verifyPeekAuthToken`, `user` is nullable: install lifecycle events are
+often system-initiated (no acting user), so the verifier tolerates `user: null`.

package/llms.txt

@@ -148,18 +148,21 @@ stay internal.
 ## Errors
 
 - `AdminAccountRequiredError` (HTTP 418), `RateLimitError` (HTTP 429 after
-  retries), `PeekGraphQLError` (`.graphqlErrors` holds the raw array),
-  `PiiAccessDisabledError` (a payment/booking-modification op was called without
-  `fullCustomerAccess`), and the REST-sibling `CngApiError` / `AcmeApiError` —
-  all importable; branch with `instanceof`.
+  retries), `PeekGraphQLError` (`.graphqlErrors` holds the raw array — a
+  resolver-level failure), `PeekHttpError` (a non-2xx HTTP status other than
+  418/429 with no GraphQL `errors` — e.g. 401/404/5xx; carries `.statusCode`,
+  `.url`, and raw `.body`; surfaced before JSON parsing so non-JSON error pages
+  keep their status), `PiiAccessDisabledError` (a payment/booking-modification op
+  was called without `fullCustomerAccess`), and the REST-sibling `CngApiError` /
+  `AcmeApiError` — all importable; branch with `instanceof`.
 - Plain `Error` for validation/precondition failures thrown before any request.
 
-## Webhooks (booking + waiver)
+## Webhooks (booking + waiver + install-status)
 
-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.
+Two pure-transform parsers plus one signature-verifier. The parsers need no
+auth/network/`PeekAccessService`; accept the `{<key>:…}` envelope, a bare node,
+or a JSON string; never throw 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
@@ -171,6 +174,15 @@ external system** (App Store config), not from code.
   register** — just subscribe to the `agreement_signature_created` event. Takes
   the same `AccessOptions`; by default (`fullCustomerAccess` off) `guestName` and
   `fileUrl` are redacted — pass `{ fullCustomerAccess: true }` to keep them.
+- `verifyInstallWebhook(token, secret): InstallWebhookClaims` — for install
+  lifecycle events (installed/uninstalled/status changed). The payload *is* a
+  signed `app_registry_v2` JWT, so this **verifies** it (HMAC signature + expiry +
+  `app_registry_v2` issuer + `Joken` audience — same checks as
+  `verifyPeekAuthToken`) rather than just parsing. Returns clean claims
+  (`installId`, `account.id`, `status`, `displayVersion`, and `user` which is
+  **nullable** for system-initiated events). Throws the underlying `jsonwebtoken`
+  error on any failure — one `try/catch` → `401`. `secret` is the app's
+  `jwtSecret`. No query to register; just subscribe to the event.
 
 **Full guide + booking query-to-register: `docs/webhooks.md` (shipped).**
 
@@ -194,6 +206,13 @@ Conventions: scalar config = HTML **attributes**; rich data = JS **properties**
 accept JSON-string attrs like `options='[…]'` / `tabs='[…]'`); output = bubbling
 **`CustomEvent`s** (read `event.detail`); content = light-DOM children.
 
+React 19: JSX props are set as DOM **properties**. Safe by design — every
+getter-only accessor accepts assignment (registration adds a setter): reflected
+props (`searchable`/`disabled`/`options`) reflect onto the attribute and take
+effect; read-only state props (`isOpen`/`isVisible`) ignore the write (drive them
+via a `ref`'s imperative methods). No `only a getter` crash. TS still types them
+read-only — the setters are a runtime safety net.
+
 Tags by tier (see `docs/ui.md` for attributes/events/examples per component):
 - display: `ody-button`, `ody-tag`, `ody-alert`, `ody-card`, `ody-divider`,
   `ody-status-dot`, `ody-message`, `ody-icon`, `ody-loading-spinner`, `ody-loading-bar`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peektravel/app-utilities",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "GraphQL JS mapping utilities extracted from the Peek Pro Autopilot connector.",
   "license": "MIT",
   "repository": {