@peektravel/app-utilities 0.5.2 → 0.5.3

package/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.
 

package/dist/index.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
-var jwt = require('jsonwebtoken');
 var crypto = require('crypto');
+var jwt = require('jsonwebtoken');
 
 function _interopNamespace(e) {
   if (e && e.__esModule) return e;
@@ -23,8 +23,6 @@ function _interopNamespace(e) {
 
 var jwt__namespace = /*#__PURE__*/_interopNamespace(jwt);
 
-// src/peek-access-service.ts
-
 // src/internal/peek/gateway-endpoints.ts
 var SALES_ENDPOINT = "sales";
 var V2_EXTENDABLE_SLUG = "peek_backoffice_api-v1";
@@ -234,6 +232,21 @@ var PeekGraphQLError = class extends Error {
     this.graphqlErrors = graphqlErrors;
   }
 };
+var PeekHttpError = class extends Error {
+  /** The HTTP status that triggered this error. */
+  statusCode;
+  /** The request URL that produced the failing response. */
+  url;
+  /** The raw response body (parsed JSON when possible, otherwise text). */
+  body;
+  constructor(statusCode, url, body, message) {
+    super(message ?? `Peek request failed with HTTP ${statusCode}`);
+    this.name = "PeekHttpError";
+    this.statusCode = statusCode;
+    this.url = url;
+    this.body = body;
+  }
+};
 var PiiAccessDisabledError = class extends Error {
   /** The name of the operation that was blocked (e.g. `"makePayment"`). */
   operation;
@@ -1944,6 +1957,14 @@ function createTokenManager(config) {
 var RATE_LIMIT_STATUS = 429;
 var ADMIN_ACCOUNT_REQUIRED_STATUS = 418;
 var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function parseBody(response) {
+  const text = await response.text();
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
 async function requestWithRetry(http, url, init, label, onResponse) {
   const { retryDelaysMs, logger, fetchFn } = http;
   for (let attempt = 0; attempt <= retryDelaysMs.length; attempt++) {
@@ -1970,6 +1991,7 @@ async function requestWithRetry(http, url, init, label, onResponse) {
 }
 
 // src/internal/peek/graphql-client.ts
+var isObject = (value) => typeof value === "object" && value !== null;
 var GraphQLClient = class {
   constructor(options) {
     this.options = options;
@@ -1995,7 +2017,8 @@ var GraphQLClient = class {
       },
       endpointName,
       async (response) => {
-        const body = await response.json();
+        const raw = await parseBody(response);
+        const body = isObject(raw) ? raw : {};
         if (body.errors) {
           logger.error(`GraphQL errors for ${endpointName}`, {
             url,
@@ -2005,7 +2028,7 @@ var GraphQLClient = class {
         }
         if (!response.ok) {
           logger.error(`GraphQL request failed with HTTP ${response.status}`, { url });
-          throw new Error(`GraphQL request failed with HTTP ${response.status}`);
+          throw new PeekHttpError(response.status, url, raw);
         }
         return body;
       }
@@ -2027,6 +2050,24 @@ var GraphQLClient = class {
     return headers;
   }
 };
+var PEEK_TOKEN_ISSUER = "app_registry_v2";
+var PEEK_TOKEN_AUDIENCE = "Joken";
+function verifyPeekJwt(token, secret) {
+  return jwt__namespace.verify(token, secret, {
+    issuer: PEEK_TOKEN_ISSUER,
+    audience: PEEK_TOKEN_AUDIENCE
+  });
+}
+function mapPeekTokenUser(u) {
+  return {
+    email: u.email,
+    id: u.id,
+    isAdmin: u.is_admin,
+    locale: u.locale,
+    name: u.name,
+    platform: u.platform
+  };
+}
 
 // src/internal/peek/memberships/membership-converter.ts
 function fromMembershipsResponse(response) {
@@ -2495,10 +2536,17 @@ function fromTimeslotNode(node, productId) {
     durationMin: node.minuteLength ?? 0,
     date: node.date || "",
     startTime: node.start ?? null,
-    assignedResources: mapAssignedResources(node.inheritedResourceAllocations)
+    assignedResources: mapAssignedResources(selectResourceAllocations(node))
   };
 }
 var ACTIVE_ALLOCATION_STATUS = "ACTIVE";
+function selectResourceAllocations(node) {
+  const inherited = node.inheritedResourceAllocations;
+  if (Array.isArray(inherited) && inherited.length > 0) {
+    return inherited;
+  }
+  return node.resourceAllocations;
+}
 function mapAssignedResources(allocations) {
   if (!Array.isArray(allocations) || allocations.length === 0) {
     return [];
@@ -2585,9 +2633,24 @@ var TIMESLOTS_QUERY = `
           status
           date
           inheritedResourceAllocations {
+            id
+            status
+            quantity
+            resourcePool {
+              id
+              name
+              category
+              capacity
+              accountUser {
+                id
+              }
+            }
+          }
+          resourceAllocations {
             quantity
             status
             resourcePool {
+              id
               name
               category
               capacity
@@ -2623,9 +2686,24 @@ var TIMESLOT_BY_ID_QUERY = `
           status
           date
           inheritedResourceAllocations {
+            id
+            status
+            quantity
+            resourcePool {
+              id
+              name
+              category
+              capacity
+              accountUser {
+                id
+              }
+            }
+          }
+          resourceAllocations {
             quantity
             status
             resourcePool {
+              id
               name
               category
               capacity
@@ -3430,7 +3508,6 @@ var noopLogger = {
 // src/peek-access-service.ts
 var DEFAULT_BASE_URL = "https://apps.peekapis.com/backoffice-gql";
 var DEFAULT_V2_BASE_URL = "https://app-registry.peeklabs.com/installations-api";
-var PEEK_TOKEN_ISSUER = "app_registry_v2";
 var PeekAccessService = class {
   client;
   productServiceOptions;
@@ -3493,21 +3570,11 @@ var PeekAccessService = class {
    * @throws {NotBeforeError} token not yet valid
    */
   verifyPeekAuthToken(token) {
-    const payload = jwt__namespace.verify(token, this.jwtSecret, {
-      issuer: PEEK_TOKEN_ISSUER
-    });
-    const { user: u } = payload;
+    const payload = verifyPeekJwt(token, this.jwtSecret);
     return {
       installId: payload.sub,
       displayVersion: payload.display_version,
-      user: {
-        email: u.email,
-        id: u.id,
-        isAdmin: u.is_admin,
-        locale: u.locale,
-        name: u.name,
-        platform: u.platform
-      }
+      user: mapPeekTokenUser(payload.user)
     };
   }
   /**
@@ -3891,7 +3958,7 @@ var RestClient = class {
       { method: "GET", headers: this.buildHeaders() },
       path,
       async (response) => {
-        const body = await this.parseBody(response);
+        const body = await parseBody(response);
         if (!response.ok) {
           logger.error(`CNG request failed with HTTP ${response.status}`, { url });
           throw new CngApiError(response.status, body);
@@ -3900,15 +3967,6 @@ var RestClient = class {
       }
     );
   }
-  /** Reads the response body as JSON, falling back to raw text when unparseable. */
-  async parseBody(response) {
-    const text = await response.text();
-    try {
-      return JSON.parse(text);
-    } catch {
-      return text;
-    }
-  }
   endpoint(path) {
     const { baseUrl, appId, extendableSlug } = this.options;
     return `${baseUrl}/${appId}/${extendableSlug}/${path}`;
@@ -4031,7 +4089,7 @@ var RestClient2 = class {
       { method: "GET", headers: this.buildHeaders() },
       path,
       async (response) => {
-        const body = await this.parseBody(response);
+        const body = await parseBody(response);
         if (!response.ok) {
           logger.error(`ACME request failed with HTTP ${response.status}`, { url });
           throw new AcmeApiError(response.status, body);
@@ -4040,15 +4098,6 @@ var RestClient2 = class {
       }
     );
   }
-  /** Reads the response body as JSON, falling back to raw text when unparseable. */
-  async parseBody(response) {
-    const text = await response.text();
-    try {
-      return JSON.parse(text);
-    } catch {
-      return text;
-    }
-  }
   endpoint(path) {
     const { baseUrl, appId, extendableSlug } = this.options;
     return `${baseUrl}/${appId}/${extendableSlug}/${path}`;
@@ -4189,6 +4238,18 @@ function extractWaiverNode(payload) {
   return record;
 }
 
+// src/internal/peek/installs/install-webhook.ts
+function verifyInstallWebhook(token, secret) {
+  const payload = verifyPeekJwt(token, secret);
+  return {
+    installId: payload.sub ?? "",
+    account: { id: payload.account?.id ?? "" },
+    status: payload.status ?? "",
+    displayVersion: payload.display_version ?? "",
+    user: payload.user ? mapPeekTokenUser(payload.user) : null
+  };
+}
+
 exports.ACTIVITY_PRODUCT_TYPE = ACTIVITY_PRODUCT_TYPE;
 exports.ADD_ON_PRODUCT_TYPE = ADD_ON_PRODUCT_TYPE;
 exports.AccountUserService = AccountUserService;
@@ -4205,6 +4266,7 @@ exports.DailyNoteService = DailyNoteService;
 exports.MembershipService = MembershipService;
 exports.PeekAccessService = PeekAccessService;
 exports.PeekGraphQLError = PeekGraphQLError;
+exports.PeekHttpError = PeekHttpError;
 exports.PiiAccessDisabledError = PiiAccessDisabledError;
 exports.PricingService = PricingService;
 exports.ProductService = ProductService;
@@ -4218,5 +4280,6 @@ exports.TimeslotService = TimeslotService;
 exports.noopLogger = noopLogger;
 exports.parseBookingWebhook = parseBookingWebhook;
 exports.parseWaiverWebhook = parseWaiverWebhook;
+exports.verifyInstallWebhook = verifyInstallWebhook;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map