@peektravel/app-utilities 0.7.1 → 0.7.3

package/dist/index.d.cts

@@ -19,10 +19,20 @@ interface GraphQLBody<T> {
     errors?: unknown[];
 }
 interface GraphQLClientOptions {
-    /** Base URL of the backoffice GraphQL gateway (no trailing slash). */
-    baseUrl: string;
-    /** Peek app ID, used in the endpoint path. */
-    appId: string;
+    /**
+     * The install's app endpoint URL (the install webhook's `apiUrl`). When set it
+     * is the **sole request URL** — every GraphQL call POSTs to it unmodified, and
+     * `baseUrl`/`appId`/`endpointPathPrefix`/`endpointName` are ignored for URL
+     * construction. Takes precedence over `baseUrl`.
+     */
+    apiUrl?: string;
+    /**
+     * Base URL of the backoffice GraphQL gateway (no trailing slash). Used only
+     * when `apiUrl` is not set; the URL is `baseUrl/appId/[prefix/]endpointName`.
+     */
+    baseUrl?: string;
+    /** Peek app ID, used in the endpoint path (legacy `baseUrl` mode only). */
+    appId?: string;
     /** API gateway key sent as the `pk-api-key` header. Omitted from headers when absent (v2 mode). */
     gatewayKey?: string;
     /** Supplies a valid bearer token for each request. */
@@ -1536,9 +1546,29 @@ interface BaseAccessServiceConfig {
     jwtSecret: string;
     /** JWT issuer — the app name / app ID. */
     issuer: string;
-    /** App ID, used in the gateway endpoint path. */
-    appId: string;
-    /** Override the gateway base URL. Default: per-service. */
+    /**
+     * The install's **app endpoint URL** — persist the install webhook's `apiUrl`
+     * and pass it here. When set it is used **as given**: for Peek it is the sole
+     * request URL (every call POSTs to it); for CNG/ACME it is the base and the
+     * REST path is appended. No app-id/gateway segment is inserted, so `appId` is
+     * not required. This is the forward-looking way to target an install — prefer
+     * it over `baseUrl`/`appId`, which are deprecated (the hardcoded base-URL
+     * fallbacks will be removed and a URL will become required in a future release).
+     */
+    apiUrl?: string;
+    /**
+     * App ID, inserted into the gateway endpoint path.
+     *
+     * @deprecated Required only in the legacy `baseUrl` mode. Prefer `apiUrl` (the
+     * install's app endpoint), which needs no app-id segment.
+     */
+    appId?: string;
+    /**
+     * Override the gateway base URL. Default: per-service.
+     *
+     * @deprecated Prefer `apiUrl` (the install's app endpoint, used as given). The
+     * hardcoded per-service default will be removed and a URL will become required.
+     */
     baseUrl?: string;
     /** JWT lifetime in seconds. Default: 3600. */
     tokenTtlSeconds?: number;
@@ -1803,20 +1833,34 @@ declare const PEEK_PLATFORMS: readonly ["peek", "cng", "acme"];
  * claim is the single thing that identifies which platform a request came from.
  */
 type PeekPlatform = (typeof PEEK_PLATFORMS)[number];
-/** User context embedded in a Peek auth token. */
+/**
+ * User context embedded in a Peek auth token.
+ *
+ * Every field is nullable: the token is untrusted even after its signature
+ * verifies, so a claim may be absent, `null`, or a sentinel (`""`, `"null"`)
+ * that this package normalizes to `null`. Never assume a field is populated —
+ * always null-check.
+ */
 interface PeekAuthTokenUser {
-    /** User's email address. */
-    email: string;
-    /** User's Peek account ID */
-    id: string;
-    /** Whether the user has admin privileges. */
-    isAdmin: boolean;
-    /** User's locale (e.g. `"en"`). */
-    locale: string;
-    /** User's display name. */
-    name: string;
-    /** Which platform embedded the app for this session. */
-    platform: PeekPlatform;
+    /** User's email address, or `null` if the token omits it. */
+    email: string | null;
+    /**
+     * The user's own Peek user ID — it identifies the signed-in person, **not**
+     * the account or partner they belong to. Use it only to key the user; never
+     * treat it as an account/partner id. `null` when the token omits it.
+     */
+    id: string | null;
+    /** Whether the user has admin privileges, or `null` if the token omits it. */
+    isAdmin: boolean | null;
+    /** User's locale (e.g. `"en"`), or `null` if the token omits it. */
+    locale: string | null;
+    /** User's display name, or `null` if the token omits it. */
+    name: string | null;
+    /**
+     * Which platform embedded the app for this session, or `null` when the token
+     * omits it or reports one this version of the package doesn't recognize.
+     */
+    platform: PeekPlatform | null;
 }
 /** Claims returned by {@link PeekAccessService.verifyPeekAuthToken}. */
 interface PeekAuthTokenClaims {
@@ -1824,8 +1868,11 @@ interface PeekAuthTokenClaims {
     installId: string;
     /** App display version at time of issuance. */
     displayVersion: string;
-    /** Authenticated user context. */
-    user: PeekAuthTokenUser;
+    /**
+     * Authenticated user context, or `null` when the token carries no `user`
+     * block. Do not assume a session token always names a user.
+     */
+    user: PeekAuthTokenUser | null;
 }
 /** The Peek account an install belongs to, as reported on an install webhook. */
 interface InstallWebhookAccount {
@@ -1935,13 +1982,15 @@ declare class PeekAccessService {
      *   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: string): PeekAuthTokenClaims;
     /**
@@ -2090,12 +2139,22 @@ declare class PeekAccessService {
 }
 
 interface RestClientOptions$1 {
-    /** Base URL of the backoffice gateway (no trailing slash). */
-    baseUrl: string;
-    /** App ID, used in the endpoint path. */
-    appId: string;
-    /** Fixed extendable slug inserted between `appId` and the REST path. */
-    extendableSlug: string;
+    /**
+     * The install's app endpoint URL (the install webhook's `apiUrl`). When set it
+     * is the **base URL** and only the REST path is appended (`apiUrl/path`) —
+     * `baseUrl`/`appId`/`extendableSlug` are ignored. Takes precedence over
+     * `baseUrl`.
+     */
+    apiUrl?: string;
+    /**
+     * Base URL of the backoffice gateway (no trailing slash). Used only when
+     * `apiUrl` is not set; the URL is `baseUrl/appId/extendableSlug/path`.
+     */
+    baseUrl?: string;
+    /** App ID, used in the endpoint path (legacy `baseUrl` mode only). */
+    appId?: string;
+    /** Fixed extendable slug inserted between `appId` and the REST path (legacy mode). */
+    extendableSlug?: string;
     /** Supplies a valid bearer token for each request. */
     getToken: () => string;
     /** Backoff delays (ms) applied on successive HTTP 429 responses. */
@@ -2217,12 +2276,22 @@ declare class CngAccessService {
 }
 
 interface RestClientOptions {
-    /** Base URL of the backoffice gateway (no trailing slash). */
-    baseUrl: string;
-    /** App ID, used in the endpoint path. */
-    appId: string;
-    /** Fixed extendable slug inserted between `appId` and the REST path. */
-    extendableSlug: string;
+    /**
+     * The install's app endpoint URL (the install webhook's `apiUrl`). When set it
+     * is the **base URL** and only the REST path is appended (`apiUrl/path`) —
+     * `baseUrl`/`appId`/`extendableSlug` are ignored. Takes precedence over
+     * `baseUrl`.
+     */
+    apiUrl?: string;
+    /**
+     * Base URL of the backoffice gateway (no trailing slash). Used only when
+     * `apiUrl` is not set; the URL is `baseUrl/appId/extendableSlug/path`.
+     */
+    baseUrl?: string;
+    /** App ID, used in the endpoint path (legacy `baseUrl` mode only). */
+    appId?: string;
+    /** Fixed extendable slug inserted between `appId` and the REST path (legacy mode). */
+    extendableSlug?: string;
     /** Supplies a valid bearer token for each request. */
     getToken: () => string;
     /** Backoff delays (ms) applied on successive HTTP 429 responses. */
@@ -2341,6 +2410,52 @@ declare class AcmeAccessService {
     getAllActivities(): Promise<AcmeActivity[]>;
 }
 
+/**
+ * Factory that turns a persisted install (or a parsed install webhook) into the
+ * right access service for its platform, wired to the install's own app
+ * endpoint.
+ *
+ * The install webhook is the only source of an install's `platform` and `apiUrl`
+ * (see `src/models/peek/install.ts`), and those two facts are exactly what's
+ * needed to target it: `platform` picks the service class, and `apiUrl` is used
+ * **as given** as that service's endpoint. This helper encodes that mapping so a
+ * consumer that persisted an install can construct its client in one call
+ * instead of switching on the platform and hand-wiring the URL.
+ */
+
+/**
+ * The per-install facts needed to build an access service — a structural subset
+ * of {@link InstallWebhook}, so a persisted install record (or the webhook event
+ * itself) satisfies it directly.
+ */
+interface InstallAccessTarget {
+    /** Which platform serves the install (the install webhook's `platform`). */
+    platform: PeekPlatform | null;
+    /** The install's app endpoint URL (the install webhook's `apiUrl`), used as given. */
+    apiUrl: string;
+    /** The install id (the install webhook's `installId`) — becomes the JWT subject. */
+    installId: string;
+}
+/**
+ * The per-app credentials/options shared by every access service — everything
+ * except the per-install `installId`/`apiUrl` (supplied by the target) and the
+ * deprecated `appId`/`baseUrl`/`mode` URL controls (superseded by `apiUrl`).
+ * `gatewayKey` is accepted for Peek and ignored by CNG/ACME.
+ */
+type InstallAccessConfig = Omit<PeekAccessServiceConfig, "installId" | "apiUrl" | "appId" | "baseUrl" | "mode">;
+/** The union of access services this factory can return, narrowed by `platform`. */
+type InstallAccessService = PeekAccessService | CngAccessService | AcmeAccessService;
+/**
+ * Builds the access service for `install.platform`, using `install.apiUrl` as
+ * the service's endpoint. Narrow the return by `install.platform` (or
+ * `instanceof`) to reach a platform-specific surface.
+ *
+ * @throws {Error} when `install.platform` is `null` or unrecognised — an install
+ * with an unknown platform has no service to route to, and silently defaulting
+ * would point it at the wrong gateway.
+ */
+declare function createAccessServiceForInstall(install: InstallAccessTarget, config: InstallAccessConfig): InstallAccessService;
+
 /**
  * Public webhook surface for bookings.
  *
@@ -2432,16 +2547,24 @@ declare function parseWaiverWebhook(payload: unknown, options?: AccessOptions):
  * POSTs when an app is installed, uninstalled, or updated.
  *
  * That delivery carries two things at once: a **signed `app_registry_v2` JWT**
- * (the security boundary) and a plain **JSON body** (the enrichment channel).
+ * (the security boundary) and a plain **JSON body** (the event payload).
  * `parseInstallWebhook` verifies the JWT and merges both into this shape, so a
  * consumer sees one clean, flat, JSON-safe record instead of two differently
- * shaped payloads. The verified JWT is authoritative for the fields it carries
- * (`installId`, `accountId`, `status`, `displayVersion`, `user`); the JSON body
- * is the only source of `accountName`, `platform`, and `isTest`.
- *
- * It is also the single origin of the account id in the whole system: no
- * GraphQL read returns it, so whatever a consumer persists from this event is
- * all it will ever have.
+ * shaped payloads. The **JSON body is the source of the event data** — it
+ * carries every field below; the verified JWT authenticates the delivery and
+ * acts as the **fallback** for the fields it also happens to carry (`installId`,
+ * `accountId`, `status`, `displayVersion`, `user`) when the body omits them.
+ *
+ * It is also the single origin of the account id (and the `apiUrl`/`timezone`)
+ * in the whole system: no GraphQL read returns them, so whatever a consumer
+ * persists from this event is all it will ever have.
+ *
+ * **Every install event is a full snapshot — upsert by `installId`.** An
+ * `update_installed` event carries the *same complete record* as the original
+ * `installed` event, so treat each delivery as an upsert keyed by `installId`
+ * and overwrite the stored fields with the incoming ones. This is how the
+ * registry pushes changes — e.g. a new `apiUrl` — so a consumer that only reads
+ * the first `installed` event and ignores later updates will keep stale data.
  */
 
 /**
@@ -2460,9 +2583,10 @@ type InstallStatus = (typeof INSTALL_STATUSES)[number];
  * returns is the shape a consumer persists and later rehydrates. There is
  * deliberately no nested identity object and no second representation.
  *
- * Fields sourced from the **verified JWT** (`installId`, `accountId`, `status`,
- * `rawStatus`, `displayVersion`, `user`) are trustworthy; the enrichment fields
- * (`accountName`, `platform`, `isTest`) come from the unauthenticated JSON body.
+ * Every field is read from the **JSON body** first, falling back to the
+ * **verified JWT** for the fields it also carries (`installId`, `accountId`,
+ * `status`, `displayVersion`, `user`). The delivery is authenticated as a whole
+ * by the JWT signature, so the body is trusted within a verified request.
  */
 interface InstallWebhook {
     /** Install ID — Peek-assigned UUID. Also the JWT subject (`sub`). */
@@ -2490,6 +2614,31 @@ interface InstallWebhook {
     platform: PeekPlatform | null;
     /** Whether this is a test account. Defaults to `false` when not reported. */
     isTest: boolean;
+    /**
+     * The account's IANA timezone (e.g. `"America/New_York"`), or `""` when the
+     * body omits it.
+     *
+     * **Persist this per install.** It has no source other than this event, and
+     * downstream date/time handling for the install (scheduling, day boundaries,
+     * display) needs the account's own timezone rather than the server's.
+     */
+    timezone: string;
+    /**
+     * The **app endpoint URL** the registry serves this install from (the body's
+     * `api.url`), or `""` when the body omits it.
+     *
+     * Use it **as given** as the base URL for this install's API calls — do not
+     * decompose it or append your own app id. The registry may tag traffic with an
+     * app id in the path; that is the registry's concern and opaque to callers, so
+     * hit the URL unmodified.
+     *
+     * **Persist this per install, and refresh it on every install event.** It is
+     * install-specific, has no source other than this webhook, and the registry
+     * can change it: an `update_installed` event redelivers the full record with a
+     * (possibly new) `apiUrl`, so re-key by `installId` and overwrite the stored
+     * URL whenever an event arrives.
+     */
+    apiUrl: string;
     /**
      * The lifecycle status, or `null` when the registry sent a status this
      * version of the package does not know. Handle `null` explicitly — treating
@@ -2502,7 +2651,8 @@ interface InstallWebhook {
     displayVersion: string;
     /**
      * The user that triggered the event, or `null` for system-initiated events
-     * (install lifecycle changes are often system-initiated). From the JWT.
+     * (install lifecycle changes are often system-initiated). Read from the body's
+     * `modified_by`, falling back to the JWT's `user`.
      */
     user: PeekAuthTokenUser | null;
 }
@@ -2511,12 +2661,14 @@ interface InstallWebhook {
  * Verifies an install-status webhook token and merges it with the delivered
  * JSON body into one flat {@link InstallWebhook}.
  *
- * The **verified token** is the authoritative source of `installId`,
- * `accountId`, `status`, `displayVersion`, and `user`. The **JSON body** — which
- * is not signed and so is trusted only for fields the token cannot carry —
- * supplies `accountName`, `platform`, and `isTest`. A missing or malformed body
- * degrades those three to `""`/`null`/`false`; it never overrides an
- * authenticated field and never throws.
+ * The **JSON body** is the source of the event data — `installId`, `accountId`,
+ * `accountName`, `platform`, `isTest`, `timezone`, `apiUrl`, `status`,
+ * `displayVersion`, and `user`. The **verified token** authenticates the whole
+ * delivery and is the **fallback** for the fields it also carries (`installId`,
+ * `accountId`, `status`, `displayVersion`, `user`) when the body omits them. A
+ * missing or malformed body degrades the body-only fields (`accountName`,
+ * `platform`, `isTest`, `timezone`, `apiUrl`) to `""`/`null`/`false` and leans
+ * on the token for the rest; it never throws.
  *
  * Signature verification is strict: the HMAC signature (with `secret`), the
  * token expiry, the `"app_registry_v2"` issuer, and the `"Joken"` audience are
@@ -2644,19 +2796,6 @@ declare class PeekHttpError extends Error {
     readonly body: unknown;
     constructor(statusCode: number, url: string, body: unknown, message?: string);
 }
-/**
- * Thrown when an `app_registry_v2` token passes signature/issuer/audience
- * verification but its `user` block is missing a required `id`. The signature is
- * authentic, so this signals a structurally malformed token from the app
- * registry rather than a forged one — distinct from the `jsonwebtoken`
- * `JsonWebTokenError` family. The offending field is preserved on
- * {@link InvalidPeekTokenError.field}.
- */
-declare class InvalidPeekTokenError extends Error {
-    /** The token field that was missing or empty (e.g. `"user.id"`). */
-    readonly field: string;
-    constructor(field: string);
-}
 /**
  * Thrown when a payment or booking-modification operation is called on an
  * access service that was constructed without `fullCustomerAccess` (PII access
@@ -2697,4 +2836,4 @@ declare class AcmeApiError extends Error {
     constructor(statusCode: number, body: unknown, message?: string);
 }
 
-export { ACTIVITY_PRODUCT_TYPE, ADD_ON_PRODUCT_TYPE, type AccessOptions, type AccountUser, AccountUserService, type AccountUserServiceOptions, AcmeAccessService, type AcmeAccessServiceConfig, type AcmeActivity, type AcmeActivityTicket, AcmeApiError, AcmeProductService, type Activity, type ActivityOverrides, type ActivityTicket, type AddAddonInput, AdminAccountRequiredError, type Agent, type AssignGuideResult, type AssignedActivity, type AssignedResource, type Availability, AvailabilityService, type AvailabilityTime, type AvailabilityTimesQuery, type Booking, type BookingAddon, type BookingAddonMoney, type BookingAddonOption, type BookingAddons, type BookingAddonsMutationResult, type BookingPaymentsOnFile, type BookingReadOptions, type BookingSearchBy, BookingService, type BookingServiceOptions, type BookingTimeRangeSearch, type CancelBookingResult, type Channel, type ClearOverridesInput, CngAccessService, type CngAccessServiceConfig, CngApiError, CngProductService, type CreateBookingGuest, type CreateBookingInput, type CreateBookingTicket, type CreateEngineInput, type CreatePromoCodeInput, type CreatedBooking, type CreatedPricingEngine, type CreatedPromoCode, type CustomQuestionAnswer, type DailyNote, DailyNoteService, type Duration, type Guest, type GuestMetadata, type Guide, type GuideAssignment, INSTALL_STATUSES, type InstallStatus, type InstallWebhook, type InstallWebhookAccount, type InstallWebhookClaims, InvalidPeekTokenError, type InvoiceLinkResult, type Logger, type MakePaymentInput, type MakePaymentResult, type Membership, type MembershipPurchaseInput, MembershipService, type NoteMode, type Payment, type PaymentSource, PeekAccessService, type PeekAccessServiceConfig, type PeekAuthTokenClaims, type PeekAuthTokenUser, PeekGraphQLError, PeekHttpError, type PeekPlatform, PiiAccessDisabledError, type Price, type PricingActivityContext, type PricingEngine, type PricingMoney, type PricingNamedRef, type PricingOverride, type PricingOverrideFilter, PricingService, type Product, type ProductMeetingLocation, ProductService, type ProductServiceOptions, type ProductTicket, type PromoCode, type PromoCodeFixedAmount, PromoCodeService, type PromoCodeServiceOptions, type PurchasedMembership, RENTAL_PRODUCT_TYPE, RateLimitError, type RefundInput, type RefundResult, ResellerService, type ResolvedOverride, type ResolvedPricingOverride, type ResolvedResourceOption, type Resource, type ResourceOptionOverride, type ResourceOptionQuantity, type ResourcePool, type ResourcePoolAccountUser, type ResourcePoolAssignment, type ResourcePoolMode, ResourcePoolService, type Review, ReviewService, type Ticket, type Timeslot, type TimeslotFilter, TimeslotService, type UpdateEngineInput, type UpdateTimeslotResult, type UpsertOverridesInput, type UpsertOverridesResult, type Waiver, noopLogger, parseBookingWebhook, parseInstallWebhook, parseWaiverWebhook, verifyInstallWebhook };
+export { ACTIVITY_PRODUCT_TYPE, ADD_ON_PRODUCT_TYPE, type AccessOptions, type AccountUser, AccountUserService, type AccountUserServiceOptions, AcmeAccessService, type AcmeAccessServiceConfig, type AcmeActivity, type AcmeActivityTicket, AcmeApiError, AcmeProductService, type Activity, type ActivityOverrides, type ActivityTicket, type AddAddonInput, AdminAccountRequiredError, type Agent, type AssignGuideResult, type AssignedActivity, type AssignedResource, type Availability, AvailabilityService, type AvailabilityTime, type AvailabilityTimesQuery, type Booking, type BookingAddon, type BookingAddonMoney, type BookingAddonOption, type BookingAddons, type BookingAddonsMutationResult, type BookingPaymentsOnFile, type BookingReadOptions, type BookingSearchBy, BookingService, type BookingServiceOptions, type BookingTimeRangeSearch, type CancelBookingResult, type Channel, type ClearOverridesInput, CngAccessService, type CngAccessServiceConfig, CngApiError, CngProductService, type CreateBookingGuest, type CreateBookingInput, type CreateBookingTicket, type CreateEngineInput, type CreatePromoCodeInput, type CreatedBooking, type CreatedPricingEngine, type CreatedPromoCode, type CustomQuestionAnswer, type DailyNote, DailyNoteService, type Duration, type Guest, type GuestMetadata, type Guide, type GuideAssignment, INSTALL_STATUSES, type InstallAccessConfig, type InstallAccessService, type InstallAccessTarget, type InstallStatus, type InstallWebhook, type InstallWebhookAccount, type InstallWebhookClaims, type InvoiceLinkResult, type Logger, type MakePaymentInput, type MakePaymentResult, type Membership, type MembershipPurchaseInput, MembershipService, type NoteMode, type Payment, type PaymentSource, PeekAccessService, type PeekAccessServiceConfig, type PeekAuthTokenClaims, type PeekAuthTokenUser, PeekGraphQLError, PeekHttpError, type PeekPlatform, PiiAccessDisabledError, type Price, type PricingActivityContext, type PricingEngine, type PricingMoney, type PricingNamedRef, type PricingOverride, type PricingOverrideFilter, PricingService, type Product, type ProductMeetingLocation, ProductService, type ProductServiceOptions, type ProductTicket, type PromoCode, type PromoCodeFixedAmount, PromoCodeService, type PromoCodeServiceOptions, type PurchasedMembership, RENTAL_PRODUCT_TYPE, RateLimitError, type RefundInput, type RefundResult, ResellerService, type ResolvedOverride, type ResolvedPricingOverride, type ResolvedResourceOption, type Resource, type ResourceOptionOverride, type ResourceOptionQuantity, type ResourcePool, type ResourcePoolAccountUser, type ResourcePoolAssignment, type ResourcePoolMode, ResourcePoolService, type Review, ReviewService, type Ticket, type Timeslot, type TimeslotFilter, TimeslotService, type UpdateEngineInput, type UpdateTimeslotResult, type UpsertOverridesInput, type UpsertOverridesResult, type Waiver, createAccessServiceForInstall, noopLogger, parseBookingWebhook, parseInstallWebhook, parseWaiverWebhook, verifyInstallWebhook };