@peektravel/app-utilities 0.7.1 → 0.7.3

package/README.md

@@ -124,10 +124,12 @@ 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.
+
+Once a token's signature verifies, claim *extraction* never throws: the whole
+`user` block may be absent (`claims.user === null`) and every field inside it is
+independently nullable, with a sentinel value (`""` or `"null"`) normalized to
+`null`. `user.id` is the signed-in person's own id — not an account or partner
+id — so its absence is not an error.
 
 **Plain `Error` validation/precondition failures** thrown by the service layer
 *before* any network call — e.g. an empty config field, a `bookingId` that
@@ -306,14 +308,22 @@ signed `app_registry_v2` JWT plus a JSON body. Peek sends the token in the
 `x-peek-auth` header — pass that value straight in (`token` accepts it with or
 without a `Bearer ` prefix). 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
+throwing the underlying `jsonwebtoken` error), 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
+`accountName`, `platform`, `isTest`, `timezone`, `apiUrl`, `status`, `rawStatus`,
+`displayVersion`, and a **nullable** `user`. The **JSON body is the source of the
+event data**; the fields it shares with the token (`installId` / `accountId` /
+`status` / `displayVersion` / `user`) fall back to the **verified token** when
+the body omits them. The token authenticates the whole delivery, so the body is
+trusted within a verified request. This webhook is the only source of
+`accountId`, `timezone`, and `apiUrl` in the package, since no GraphQL read
+returns them — **persist them per install**. `apiUrl` is the install's app
+endpoint: use it **as given** (don't reconstruct it from `appId`) — pass it as the
+access service's `apiUrl`, or hand the whole install to
+`createAccessServiceForInstall(install, { jwtSecret, issuer })`, which picks the
+service by `platform` and wires the endpoint for you. Every event is a **full
+snapshot** — an `update_installed` carries the same fields as the original
+`installed`, so upsert by `installId` and take the latest `apiUrl`. `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

package/dist/index.cjs

@@ -247,15 +247,6 @@ 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;
@@ -2044,7 +2035,8 @@ var GraphQLClient = class {
     );
   }
   endpoint(endpointName) {
-    const { baseUrl, appId, endpointPathPrefix } = this.options;
+    const { apiUrl, baseUrl, appId, endpointPathPrefix } = this.options;
+    if (apiUrl) return apiUrl;
     const prefix = endpointPathPrefix ? `${endpointPathPrefix}/` : "";
     return `${baseUrl}/${appId}/${prefix}${endpointName}`;
   }
@@ -2059,6 +2051,11 @@ var GraphQLClient = class {
     return headers;
   }
 };
+
+// src/models/peek/auth-token.ts
+var PEEK_PLATFORMS = ["peek", "cng", "acme"];
+
+// src/internal/peek/peek-auth-token.ts
 var PEEK_TOKEN_ISSUER = "app_registry_v2";
 var PEEK_TOKEN_AUDIENCE = "Joken";
 var BEARER_PREFIX = "bearer ";
@@ -2066,6 +2063,16 @@ function stripBearer(token) {
   const trimmed = token.trim();
   return trimmed.toLowerCase().startsWith(BEARER_PREFIX) ? trimmed.slice(BEARER_PREFIX.length).trim() : trimmed;
 }
+var NULLISH_STRINGS = /* @__PURE__ */ new Set(["", "null"]);
+function cleanTokenString(value) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return NULLISH_STRINGS.has(trimmed.toLowerCase()) ? null : trimmed;
+}
+function cleanTokenPlatform(value) {
+  const cleaned = cleanTokenString(value);
+  return cleaned !== null && PEEK_PLATFORMS.includes(cleaned) ? cleaned : null;
+}
 function verifyPeekJwt(token, secret) {
   return jwt__namespace.verify(stripBearer(token), secret, {
     issuer: PEEK_TOKEN_ISSUER,
@@ -2073,16 +2080,14 @@ function verifyPeekJwt(token, secret) {
   });
 }
 function mapPeekTokenUser(u) {
-  if (!u.id) {
-    throw new InvalidPeekTokenError("user.id");
-  }
+  if (!u) return null;
   return {
-    email: u.email,
-    id: u.id,
-    isAdmin: u.is_admin,
-    locale: u.locale,
-    name: u.name,
-    platform: u.platform
+    email: cleanTokenString(u.email),
+    id: cleanTokenString(u.id),
+    isAdmin: typeof u.is_admin === "boolean" ? u.is_admin : null,
+    locale: cleanTokenString(u.locale),
+    name: cleanTokenString(u.name),
+    platform: cleanTokenPlatform(u.platform)
   };
 }
 
@@ -3561,25 +3566,27 @@ var PeekAccessService = class {
   bookingService;
   reviewService;
   constructor(config) {
+    const hasApiUrl = !!config.apiUrl;
     const isV2 = config.mode === "v2";
     requireNonEmpty(config.installId, "installId", "PeekAccessService");
     requireNonEmpty(config.jwtSecret, "jwtSecret", "PeekAccessService");
     requireNonEmpty(config.issuer, "issuer", "PeekAccessService");
-    requireNonEmpty(config.appId, "appId", "PeekAccessService");
-    if (!isV2) requireNonEmpty(config.gatewayKey ?? "", "gatewayKey", "PeekAccessService");
+    if (!hasApiUrl) requireNonEmpty(config.appId ?? "", "appId", "PeekAccessService");
+    if (!hasApiUrl && !isV2) requireNonEmpty(config.gatewayKey ?? "", "gatewayKey", "PeekAccessService");
     this.jwtSecret = config.jwtSecret;
     const logger = config.logger ?? noopLogger;
     const tokens = createTokenManager(config);
     const defaultBaseUrl = isV2 ? DEFAULT_V2_BASE_URL : DEFAULT_BASE_URL;
     this.client = new GraphQLClient({
-      baseUrl: config.baseUrl ?? defaultBaseUrl,
-      appId: config.appId,
+      apiUrl: config.apiUrl,
+      baseUrl: hasApiUrl ? void 0 : config.baseUrl ?? defaultBaseUrl,
+      appId: hasApiUrl ? void 0 : config.appId,
       gatewayKey: config.gatewayKey,
       getToken: () => tokens.getToken(),
       retryDelaysMs: config.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS,
       logger,
       fetchFn: config.fetch ?? globalThis.fetch,
-      endpointPathPrefix: isV2 ? V2_EXTENDABLE_SLUG : void 0
+      endpointPathPrefix: !hasApiUrl && isV2 ? V2_EXTENDABLE_SLUG : void 0
     });
     this.productServiceOptions = {
       itemOptionsPageSize: config.itemOptionsPageSize
@@ -3600,13 +3607,15 @@ var PeekAccessService = class {
    *   malformed
    * - `TokenExpiredError` — past `exp`
    * - `NotBeforeError` — before `nbf`
-   * - `InvalidPeekTokenError` — signature valid but the `user` block is missing
-   *   its `id`
+   *
+   * Claim *extraction* is defensive: once the signature verifies, a token with
+   * no `user` block yields `claims.user === null`, and any individual user field
+   * that is absent or a sentinel (`""`, `"null"`) is normalized to `null`. This
+   * method never throws on a shape problem — only on a verification failure.
    *
    * @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);
@@ -4007,7 +4016,8 @@ var RestClient = class {
     );
   }
   endpoint(path) {
-    const { baseUrl, appId, extendableSlug } = this.options;
+    const { apiUrl, baseUrl, appId, extendableSlug } = this.options;
+    if (apiUrl) return `${apiUrl}/${path}`;
     return `${baseUrl}/${appId}/${extendableSlug}/${path}`;
   }
   buildHeaders() {
@@ -4024,15 +4034,17 @@ var CngAccessService = class {
   client;
   productService;
   constructor(config) {
+    const hasApiUrl = !!config.apiUrl;
     requireNonEmpty(config.installId, "installId", "CngAccessService");
     requireNonEmpty(config.jwtSecret, "jwtSecret", "CngAccessService");
     requireNonEmpty(config.issuer, "issuer", "CngAccessService");
-    requireNonEmpty(config.appId, "appId", "CngAccessService");
+    if (!hasApiUrl) requireNonEmpty(config.appId ?? "", "appId", "CngAccessService");
     const logger = config.logger ?? noopLogger;
     const tokens = createTokenManager(config);
     this.client = new RestClient({
-      baseUrl: config.baseUrl ?? DEFAULT_BASE_URL2,
-      appId: config.appId,
+      apiUrl: config.apiUrl,
+      baseUrl: hasApiUrl ? void 0 : config.baseUrl ?? DEFAULT_BASE_URL2,
+      appId: hasApiUrl ? void 0 : config.appId,
       extendableSlug: CNG_EXTENDABLE_SLUG,
       getToken: () => tokens.getToken(),
       retryDelaysMs: config.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS,
@@ -4138,7 +4150,8 @@ var RestClient2 = class {
     );
   }
   endpoint(path) {
-    const { baseUrl, appId, extendableSlug } = this.options;
+    const { apiUrl, baseUrl, appId, extendableSlug } = this.options;
+    if (apiUrl) return `${apiUrl}/${path}`;
     return `${baseUrl}/${appId}/${extendableSlug}/${path}`;
   }
   buildHeaders() {
@@ -4155,15 +4168,17 @@ var AcmeAccessService = class {
   client;
   productService;
   constructor(config) {
+    const hasApiUrl = !!config.apiUrl;
     requireNonEmpty(config.installId, "installId", "AcmeAccessService");
     requireNonEmpty(config.jwtSecret, "jwtSecret", "AcmeAccessService");
     requireNonEmpty(config.issuer, "issuer", "AcmeAccessService");
-    requireNonEmpty(config.appId, "appId", "AcmeAccessService");
+    if (!hasApiUrl) requireNonEmpty(config.appId ?? "", "appId", "AcmeAccessService");
     const logger = config.logger ?? noopLogger;
     const tokens = createTokenManager(config);
     this.client = new RestClient2({
-      baseUrl: config.baseUrl ?? DEFAULT_BASE_URL3,
-      appId: config.appId,
+      apiUrl: config.apiUrl,
+      baseUrl: hasApiUrl ? void 0 : config.baseUrl ?? DEFAULT_BASE_URL3,
+      appId: hasApiUrl ? void 0 : config.appId,
       extendableSlug: ACME_EXTENDABLE_SLUG,
       getToken: () => tokens.getToken(),
       retryDelaysMs: config.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS,
@@ -4187,6 +4202,23 @@ var AcmeAccessService = class {
   }
 };
 
+// src/access-service-factory.ts
+function createAccessServiceForInstall(install, config) {
+  const shared = { ...config, installId: install.installId, apiUrl: install.apiUrl };
+  switch (install.platform) {
+    case "peek":
+      return new PeekAccessService(shared);
+    case "cng":
+      return new CngAccessService(shared);
+    case "acme":
+      return new AcmeAccessService(shared);
+    default:
+      throw new Error(
+        `createAccessServiceForInstall: unknown or missing platform "${install.platform}" for install "${install.installId}"`
+      );
+  }
+}
+
 // src/internal/peek/bookings/booking-webhook.ts
 var PAYLOAD_BOOKING_KEY = "booking";
 var VALUE_OPEN_TOKEN = "value {";
@@ -4277,9 +4309,6 @@ 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",
@@ -4310,20 +4339,27 @@ function toPeekPlatform(raw) {
 // 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 ?? "";
+  const parsed = extractInstallWebhookBody(body);
+  const account = parsed.account ?? {};
+  const rawStatus = parsed.status || payload.status || "";
   return {
-    installId: payload.sub ?? "",
-    accountId: payload.account?.id ?? "",
+    installId: parsed.install_id || payload.sub || "",
+    accountId: account.id || payload.account?.id || "",
     accountName: account.name || "",
     platform: toPeekPlatform(account.platform || ""),
     isTest: Boolean(account.is_test),
+    timezone: account.timezone || "",
+    apiUrl: parsed.api?.url || "",
     status: toInstallStatus(rawStatus),
     rawStatus,
-    displayVersion: payload.display_version ?? "",
-    user: payload.user ? mapPeekTokenUser(payload.user) : null
+    displayVersion: parsed.display_version || payload.display_version || "",
+    user: resolveInstallUser(parsed.modified_by, payload.user)
   };
 }
+function resolveInstallUser(bodyUser, tokenUser) {
+  if (cleanTokenString(bodyUser?.id) !== null) return mapPeekTokenUser(bodyUser);
+  return mapPeekTokenUser(tokenUser);
+}
 function verifyInstallWebhook(token, secret) {
   const payload = verifyPeekJwt(token, secret);
   return {
@@ -4331,7 +4367,7 @@ function verifyInstallWebhook(token, secret) {
     account: { id: payload.account?.id ?? "" },
     status: payload.status ?? "",
     displayVersion: payload.display_version ?? "",
-    user: payload.user ? mapPeekTokenUser(payload.user) : null
+    user: mapPeekTokenUser(payload.user)
   };
 }
 
@@ -4349,7 +4385,6 @@ 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;
@@ -4364,6 +4399,7 @@ exports.ResellerService = ResellerService;
 exports.ResourcePoolService = ResourcePoolService;
 exports.ReviewService = ReviewService;
 exports.TimeslotService = TimeslotService;
+exports.createAccessServiceForInstall = createAccessServiceForInstall;
 exports.noopLogger = noopLogger;
 exports.parseBookingWebhook = parseBookingWebhook;
 exports.parseInstallWebhook = parseInstallWebhook;