@peektravel/app-utilities 0.6.0 → 0.7.0

package/README.md

@@ -15,6 +15,10 @@ npm install @peektravel/app-utilities
 npm update  @peektravel/app-utilities
 ```
 
+Before updating to a new version, consult [`changelog.md`](./changelog.md) —
+it records every caller-visible change grouped by version, including any
+breaking changes and the concrete action you need to take to migrate.
+
 See [Releasing](#releasing) for how new versions are published.
 
 ## Usage
@@ -120,6 +124,10 @@ Two kinds of failures surface as exceptions:
 - `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).
+- `InvalidPeekTokenError` — `verifyPeekAuthToken` (or `parseInstallWebhook` /
+  `verifyInstallWebhook`)
+  received a token whose signature is valid but whose `user` block has no `id`.
+  Carries `.field` (`"user.id"`). Thrown alongside the `jsonwebtoken` errors.
 
 **Plain `Error` validation/precondition failures** thrown by the service layer
 *before* any network call — e.g. an empty config field, a `bookingId` that
@@ -238,20 +246,20 @@ Functions runtime) resolve correctly. Its only runtime dependency is
 
 ## Webhooks
 
-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:
+Receiver apps can consume Peek **booking**, **waiver**, and **install** 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 webhook delivers a signed token alongside a JSON body, so its helper
+**verifies** the token before merging the two:
 
 ```ts
 import {
   parseBookingWebhook,
+  parseInstallWebhook,
   parseWaiverWebhook,
-  verifyInstallWebhook,
   type Booking,
+  type InstallWebhook,
   type Waiver,
-  type InstallWebhookClaims,
 } from "@peektravel/app-utilities";
 
 app.post("/booking-webhook", (req, res) => {
@@ -265,17 +273,23 @@ app.post("/waiver-webhook", (req, res) => {
   res.sendStatus(200);
 });
 
-app.post("/install-webhook", (req, res) => {
+app.post("/install-webhook", async (req, res) => {
+  let event: InstallWebhook;
   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);
+    // Verifies the signed token, then merges in the JSON body:
+    event = parseInstallWebhook(req.token, req.body, process.env.PEEK_INTERNAL_SECRET!);
   } catch {
-    res.sendStatus(401); // bad signature / issuer / audience / expired
+    return res.sendStatus(401); // bad signature / issuer / audience / expired
+  }
+  switch (event.status) {
+    case "installed":        await provision(event); break;
+    case "uninstalled":      await deprovision(event); break;
+    case "update_installed": await recordVersion(event); break;
+    // `status` is null when Peek sends one this version doesn't know. Peek
+    // doesn't redeliver a 2xx, so fail loudly rather than silently no-op.
+    default: return res.status(500).json({ error: `unknown status: ${event.rawStatus}` });
   }
+  res.sendStatus(200);
 });
 ```
 
@@ -284,17 +298,31 @@ JSON string and never throw on malformed input; **authenticating those deliverie
 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:
+below.
+
+`parseInstallWebhook(token, body, secret)` is different: the delivery carries a
+signed `app_registry_v2` JWT plus a JSON body. It validates the HMAC signature,
+expiry, issuer, and `"Joken"` audience (the same checks as `verifyPeekAuthToken`,
+throwing the underlying `jsonwebtoken` error — or `InvalidPeekTokenError` when a
+present `user` block has no `id`), then returns one flat, JSON-safe
+`InstallWebhook`: `installId`, `accountId` (**also called the partner ID**),
+`accountName`, `platform`, `isTest`, `status`, `rawStatus`, `displayVersion`, and
+a **nullable** `user`. The **verified token** is authoritative for `installId` /
+`accountId` / `status` / `displayVersion` / `user`; the unsigned body supplies
+only `accountName` / `platform` / `isTest`. This webhook is the only source of
+`accountId` in the package, since no GraphQL read returns it. `status` and
+`platform` are **nullable** — a value this version doesn't recognise stays `null`
+(wire value on `rawStatus`) instead of being coerced, so a newer registry can't be
+mistaken for an older one. (The older `verifyInstallWebhook(token, secret)` is
+still exported but **`@deprecated`** — it reads only the token, missing the
+account name/platform/test flag; `parseInstallEvent` has been **removed**.)
+
+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** 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`)

package/dist/index.cjs

@@ -247,6 +247,15 @@ var PeekHttpError = class extends Error {
     this.body = body;
   }
 };
+var InvalidPeekTokenError = class extends Error {
+  /** The token field that was missing or empty (e.g. `"user.id"`). */
+  field;
+  constructor(field) {
+    super(`Peek token is missing required field "${field}"`);
+    this.name = "InvalidPeekTokenError";
+    this.field = field;
+  }
+};
 var PiiAccessDisabledError = class extends Error {
   /** The name of the operation that was blocked (e.g. `"makePayment"`). */
   operation;
@@ -2059,6 +2068,9 @@ function verifyPeekJwt(token, secret) {
   });
 }
 function mapPeekTokenUser(u) {
+  if (!u.id) {
+    throw new InvalidPeekTokenError("user.id");
+  }
   return {
     email: u.email,
     id: u.id,
@@ -3582,10 +3594,13 @@ var PeekAccessService = class {
    *   malformed
    * - `TokenExpiredError` — past `exp`
    * - `NotBeforeError` — before `nbf`
+   * - `InvalidPeekTokenError` — signature valid but the `user` block is missing
+   *   its `id`
    *
    * @throws {JsonWebTokenError} signature invalid or token malformed
    * @throws {TokenExpiredError} token has expired
    * @throws {NotBeforeError} token not yet valid
+   * @throws {InvalidPeekTokenError} verified token has no `user.id`
    */
   verifyPeekAuthToken(token) {
     const payload = verifyPeekJwt(token, this.jwtSecret);
@@ -4256,7 +4271,53 @@ function extractWaiverNode(payload) {
   return record;
 }
 
+// src/models/peek/auth-token.ts
+var PEEK_PLATFORMS = ["peek", "cng", "acme"];
+
+// src/models/peek/install.ts
+var INSTALL_STATUSES = [
+  "installed",
+  "uninstalled",
+  "update_installed"
+];
+
+// src/internal/peek/installs/install-converter.ts
+function extractInstallWebhookBody(payload) {
+  let body = payload;
+  if (typeof body === "string") {
+    try {
+      body = JSON.parse(body);
+    } catch {
+      return {};
+    }
+  }
+  if (!body || typeof body !== "object") return {};
+  return body;
+}
+function toInstallStatus(raw) {
+  return INSTALL_STATUSES.includes(raw) ? raw : null;
+}
+function toPeekPlatform(raw) {
+  return PEEK_PLATFORMS.includes(raw) ? raw : null;
+}
+
 // src/internal/peek/installs/install-webhook.ts
+function parseInstallWebhook(token, body, secret) {
+  const payload = verifyPeekJwt(token, secret);
+  const account = extractInstallWebhookBody(body).account ?? {};
+  const rawStatus = payload.status ?? "";
+  return {
+    installId: payload.sub ?? "",
+    accountId: payload.account?.id ?? "",
+    accountName: account.name || "",
+    platform: toPeekPlatform(account.platform || ""),
+    isTest: Boolean(account.is_test),
+    status: toInstallStatus(rawStatus),
+    rawStatus,
+    displayVersion: payload.display_version ?? "",
+    user: payload.user ? mapPeekTokenUser(payload.user) : null
+  };
+}
 function verifyInstallWebhook(token, secret) {
   const payload = verifyPeekJwt(token, secret);
   return {
@@ -4281,6 +4342,8 @@ exports.CngAccessService = CngAccessService;
 exports.CngApiError = CngApiError;
 exports.CngProductService = CngProductService;
 exports.DailyNoteService = DailyNoteService;
+exports.INSTALL_STATUSES = INSTALL_STATUSES;
+exports.InvalidPeekTokenError = InvalidPeekTokenError;
 exports.MembershipService = MembershipService;
 exports.PeekAccessService = PeekAccessService;
 exports.PeekGraphQLError = PeekGraphQLError;
@@ -4297,6 +4360,7 @@ exports.ReviewService = ReviewService;
 exports.TimeslotService = TimeslotService;
 exports.noopLogger = noopLogger;
 exports.parseBookingWebhook = parseBookingWebhook;
+exports.parseInstallWebhook = parseInstallWebhook;
 exports.parseWaiverWebhook = parseWaiverWebhook;
 exports.verifyInstallWebhook = verifyInstallWebhook;
 //# sourceMappingURL=index.cjs.map