@peektravel/app-utilities 0.6.0 → 0.6.1

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,9 @@ 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 `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,18 +245,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**, **install-event**, and
+**install-status** webhooks without hand-writing the payload handling. The
+booking, waiver, and install-event 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,
+  parseInstallEvent,
   parseWaiverWebhook,
   verifyInstallWebhook,
   type Booking,
+  type InstallEvent,
   type Waiver,
   type InstallWebhookClaims,
 } from "@peektravel/app-utilities";
@@ -265,6 +274,19 @@ app.post("/waiver-webhook", (req, res) => {
   res.sendStatus(200);
 });
 
+app.post("/install-event", async (req, res) => {
+  const event: InstallEvent = parseInstallEvent(req.body);
+  switch (event.status) {
+    case "installed":        await provision(event.identity); break;
+    case "uninstalled":      await deprovision(event.identity); break;
+    case "update_installed": await recordVersion(event.identity, event.displayVersion); 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);
+});
+
 app.post("/install-webhook", (req, res) => {
   try {
     // The payload IS a signed JWT — verify signature/issuer/audience/expiry:
@@ -279,9 +301,16 @@ app.post("/install-webhook", (req, res) => {
 });
 ```
 
-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
+The booking, waiver, and install-event 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**. `parseInstallEvent` returns an
+`InstallIdentity` (`installId`, `accountId` — **also called the partner ID** —
+`accountName`, `platform`, `isTest`) that is flat and JSON-safe, so it persists
+and rehydrates as a unit; that body is the only source of `accountId` in the
+package, since no GraphQL read or token returns it. Its `status` and `platform`
+are **nullable** — a value this version doesn't recognise stays `null` instead of
+being coerced, so a newer registry can't be mistaken for an older one.
+`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
@@ -289,7 +318,8 @@ below. `verifyInstallWebhook(token, secret)` is different: the payload is a sign
 `"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
+on any failure — or `InvalidPeekTokenError` when a present `user` block has no
+`id`. 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**

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);
@@ -4268,6 +4283,61 @@ function verifyInstallWebhook(token, secret) {
   };
 }
 
+// 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 toInstallStatus(raw) {
+  return INSTALL_STATUSES.includes(raw) ? raw : null;
+}
+function toPeekPlatform(raw) {
+  return PEEK_PLATFORMS.includes(raw) ? raw : null;
+}
+function fromInstallIdentityNode(node) {
+  const data = node ?? {};
+  const account = data.account ?? {};
+  return {
+    installId: data.install_id || "",
+    accountId: account.id || "",
+    accountName: account.name || "",
+    platform: toPeekPlatform(account.platform || ""),
+    isTest: Boolean(account.is_test)
+  };
+}
+function fromInstallEventNode(node) {
+  const rawStatus = node?.status || "";
+  return {
+    status: toInstallStatus(rawStatus),
+    rawStatus,
+    displayVersion: node?.display_version || "",
+    identity: fromInstallIdentityNode(node)
+  };
+}
+
+// src/internal/peek/installs/install-event.ts
+function parseInstallEvent(payload) {
+  return fromInstallEventNode(extractInstallEventNode(payload));
+}
+function extractInstallEventNode(payload) {
+  let body = payload;
+  if (typeof body === "string") {
+    try {
+      body = JSON.parse(body);
+    } catch {
+      return {};
+    }
+  }
+  if (!body || typeof body !== "object") return {};
+  return body;
+}
+
 exports.ACTIVITY_PRODUCT_TYPE = ACTIVITY_PRODUCT_TYPE;
 exports.ADD_ON_PRODUCT_TYPE = ADD_ON_PRODUCT_TYPE;
 exports.AccountUserService = AccountUserService;
@@ -4281,6 +4351,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 +4369,7 @@ exports.ReviewService = ReviewService;
 exports.TimeslotService = TimeslotService;
 exports.noopLogger = noopLogger;
 exports.parseBookingWebhook = parseBookingWebhook;
+exports.parseInstallEvent = parseInstallEvent;
 exports.parseWaiverWebhook = parseWaiverWebhook;
 exports.verifyInstallWebhook = verifyInstallWebhook;
 //# sourceMappingURL=index.cjs.map