@peektravel/app-utilities 0.6.0 → 0.7.0

package/docs/webhooks.md

@@ -2,24 +2,33 @@
 
 A guide for wiring a receiver app up to Peek "backoffice" webhooks using
 `@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).
+**booking**, **waiver**, and **install** — 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 webhook delivers a
+**signed token alongside a JSON body** (so the helper *verifies* the token before
+merging the two).
 
 | 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` |
+| Install | subscribe to the event — **no query needed** | `parseInstallWebhook(token, body, secret)` → `InstallWebhook` |
 
 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.
+install webhook is different: it carries a signed JWT, so `parseInstallWebhook`
+checks the signature for you before returning the merged event.
+
+**The install webhook delivers two payloads at once.** A signed
+`app_registry_v2` JWT authenticates the notification and carries the account
+**id**, install id, status, version, and the acting `user`; a plain JSON body
+alongside it adds the account's **name**, **platform**, and **test** flag.
+`parseInstallWebhook` verifies the token and merges both into one flat
+`InstallWebhook`, so you make a single call. The verified token is authoritative
+for the fields it carries; the unsigned body is trusted only for name/platform/
+test.
 
 # Booking webhooks
 
@@ -154,67 +163,137 @@ The resulting `Waiver` is flat:
 
 Authenticating the delivery is the receiver's responsibility, as with bookings.
 
-# Install-status webhooks
+# Install 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.
+uninstalled, updated — with a single POST that carries **two payloads at once**:
+a **signed `app_registry_v2` JWT** and a plain **JSON body**.
+
+- The **JWT** is the security boundary. Verifying its signature proves the
+  notification really came from Peek before your app acts on it (for example,
+  de-provisioning an uninstall). It carries the install id, account **id**,
+  status, version, and the acting `user`.
+- The **JSON body** is the enrichment channel. It adds the account's **name**,
+  **platform**, and **test** flag — the fields the token does not carry.
+
+This webhook is also where an app first learns **who the install belongs to** —
+and the only place it ever learns it: no GraphQL read returns the account id, so
+whatever you persist from this delivery is all you will ever have.
+
+`parseInstallWebhook(token, body, secret)` verifies the token (issuer, audience,
+expiry, HMAC — the security-critical boilerplate you'd otherwise hand-roll) and
+merges both payloads into one flat, JSON-safe `InstallWebhook` you store as a
+unit. The **verified token** is authoritative for the fields it carries; the
+unsigned body is trusted only for name/platform/test.
 
 ## 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.
+Nothing to register in code: subscribe your endpoint to the install event in the
+App Store config. There is no GraphQL selection to paste.
 
-## Step 2 — verify the delivered token
+## Step 2 — verify and parse the delivery
 
-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`:
+Extract the JWT from the delivery (the request token, or the `Authorization`
+header with the `Bearer ` prefix stripped) and pass it — along with the JSON body
+and your app's signing secret (the same `jwtSecret` you construct
+`PeekAccessService` with) — to `parseInstallWebhook`:
 
 ```ts
-import { verifyInstallWebhook, type InstallWebhookClaims } from "@peektravel/app-utilities";
+import { parseInstallWebhook, type InstallWebhook } from "@peektravel/app-utilities";
 
-app.post("/webhooks/install", (req, res) => {
-  let claims: InstallWebhookClaims;
+app.post("/webhooks/install", async (req, res) => {
+  let event: InstallWebhook;
   try {
-    claims = verifyInstallWebhook(req.body /* raw JWT string */, process.env.PEEK_INTERNAL_SECRET!);
+    event = parseInstallWebhook(req.token, req.body, 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
+  switch (event.status) {
+    case "installed":
+      await provision(event);
+      break;
+    case "uninstalled":
+      await deprovision(event);
+      break;
+    case "update_installed":
+      await recordVersion(event);
+      break;
+    default:
+      // Peek sent a status this package version does not know. Fail loudly —
+      // a 2xx here is a silently dropped lifecycle transition.
+      return res.status(500).json({ error: `unknown status: ${event.rawStatus}` });
   }
+
   res.sendStatus(200);
 });
 ```
 
-`verifyInstallWebhook` validates the HMAC signature, the token expiry, the
+`parseInstallWebhook` 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`.
+[`PeekAccessService.verifyPeekAuthToken`](../README.md#access-options--pii). 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 or a missing/garbled body yields empty fields rather than
+throwing.
+
+The resulting `InstallWebhook` is flat:
+
+| Field | Type | Source | From | Notes |
+| --- | --- | --- | --- | --- |
+| `installId` | `string` | token | `sub` | Peek-assigned install UUID |
+| `accountId` | `string` | token | `account.id` | **also called the partner ID** |
+| `accountName` | `string` | body | `account.name` | partner display name; `""` when absent |
+| `platform` | `PeekPlatform \| null` | body | `account.platform` | **persist per install** — see below; `null` when unrecognised |
+| `isTest` | `boolean` | body | `account.is_test` | defaults to `false` |
+| `status` | `InstallStatus \| null` | token | `status` | `null` when unrecognised — see below |
+| `rawStatus` | `string` | token | `status` | always the wire value, for logging |
+| `displayVersion` | `string` | token | `display_version` | `""` when absent |
+| `user` | `PeekAuthTokenUser \| null` | token | `user` | `null` for system-initiated events |
+
+Because the four fields present in **both** payloads (`installId`, `accountId`,
+`status`, `displayVersion`) are read from the **verified token**, a mismatched or
+forged body can never override an authenticated identity. Unlike
+`verifyPeekAuthToken`, `user` is nullable: install lifecycle events are often
+system-initiated (no acting user), so the parser tolerates `user: null`.
+
+> **Migrating from `verifyInstallWebhook` / `parseInstallEvent`?**
+> `verifyInstallWebhook(token, secret)` still works but is `@deprecated` — it
+> reads only the token, so it can't report the account name/platform/test flag.
+> `parseInstallEvent(body)` has been **removed**. Replace both with
+> `parseInstallWebhook(token, body, secret)`; the return is now flat, so read
+> `event.accountId` directly instead of `event.identity.accountId` or
+> `claims.account.id`.
+
+## Persist `platform` per install
+
+`event.platform` is not cosmetic. It decides which APIs the install is served by,
+and therefore which access service you construct for it:
+
+| `platform` | Access service | Gateway |
+| --- | --- | --- |
+| `"peek"` | `PeekAccessService` | Peek backoffice GraphQL |
+| `"cng"` | `CngAccessService` | CNG backoffice REST |
+| `"acme"` | `AcmeAccessService` | ACME backoffice REST |
+
+Two installs of the same app can sit on different platforms, so this cannot be
+inferred from app-level config — it is per install, it has no source other than
+this event, and it must be stored alongside `installId` and `accountId`.
+
+## Why `status` and `platform` can be `null`
+
+`parseInstallWebhook` never throws on the *body* (only token verification can
+throw). The sender is first-party and the payload contract is Peek's own, so a
+malformed body is not the failure worth designing for. The failure that *is* real
+is the contract **growing** — a new status, or a fourth platform.
+
+Both are therefore reported as `null` rather than coerced into a known value,
+with the wire value preserved on `rawStatus`. Coercing would be actively
+dangerous: Peek treats any 2xx as delivered and does not redeliver, so quietly
+mapping an unknown status onto a no-op loses a lifecycle transition permanently,
+and defaulting an unknown platform would point that install at the wrong gateway.
+Give both a `default:` branch that fails loudly.

package/llms.txt

@@ -157,14 +157,16 @@ stay internal.
   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`.
+  was called without `fullCustomerAccess`), `InvalidPeekTokenError` (a
+  signature-valid `app_registry_v2` token whose `user` block has no `id`;
+  carries `.field`), and the REST-sibling `CngApiError` / `AcmeApiError` — all
+  importable; branch with `instanceof`.
 - Plain `Error` for validation/precondition failures thrown before any request.
 
-## Webhooks (booking + waiver + install-status)
+## Webhooks (booking + waiver + install)
 
-Two pure-transform parsers plus one signature-verifier. The parsers need no
-auth/network/`PeekAccessService`; accept the `{<key>:…}` envelope, a bare node,
+Two pure-transform parsers plus one verify-and-parse call. The pure 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.
 
@@ -178,15 +180,29 @@ an 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 +
+- `parseInstallWebhook(token, body, secret): InstallWebhook` — the install
+  webhook delivers **two payloads at once**: a signed `app_registry_v2` JWT and a
+  JSON body. This **verifies** the token (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.
+  `verifyPeekAuthToken`, throwing the underlying `jsonwebtoken` error on failure,
+  one `try/catch` → `401`) and merges both into one flat, JSON-safe
+  `InstallWebhook`: `installId`, `accountId` (**also called the partner ID**),
+  `accountName`, `platform`, `isTest`, `status`, `rawStatus`, `displayVersion`,
+  `user` (nullable, for system-initiated events). The **verified token** is
+  authoritative for `installId`/`accountId`/`status`/`displayVersion`/`user`; the
+  unsigned body supplies only `accountName`/`platform`/`isTest`, so a forged body
+  can't override an authenticated field. This webhook is the **only** source of
+  `accountId` in the package — no GraphQL read returns it. `status` and `platform`
+  are **nullable**: a value this version does not recognise maps to `null` (wire
+  value kept on `rawStatus`) rather than being coerced, because Peek does not
+  redeliver a 2xx and a coerced status silently drops a lifecycle transition. Give
+  both a `default:` branch that fails loudly. `secret` is the app's `jwtSecret`,
+  app-wide, so it verifies fine on a brand-new install before any record exists.
+  No query to register; just subscribe to the event.
+  - **Deprecated / removed:** `verifyInstallWebhook(token, secret):
+    InstallWebhookClaims` still verifies the token but is `@deprecated` — it reads
+    only the token, missing the account name/platform/test flag. `parseInstallEvent`
+    (the JSON-body-only parser) has been **removed**. Use `parseInstallWebhook`.
 
 **Full guide + booking query-to-register: `docs/webhooks.md` (shipped).**
 

package/package.json

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