@peektravel/app-utilities 0.6.0 → 0.7.0

package/dist/index.d.cts

@@ -1791,13 +1791,18 @@ declare class PricingService {
     private validateResourceOption;
 }
 
+/**
+ * Every platform this package knows about. Exported as a value (not just a
+ * union) so runtime code can recognise a reported platform without restating
+ * the list. New platforms extend this array.
+ */
+declare const PEEK_PLATFORMS: readonly ["peek", "cng", "acme"];
 /**
  * Platform that embedded the app for this session. Verification is
  * brand-agnostic — one peek-auth JWT is minted for every platform — so this
  * claim is the single thing that identifies which platform a request came from.
- * New platforms extend this union.
  */
-type PeekPlatform = "peek" | "cng" | "acme";
+type PeekPlatform = (typeof PEEK_PLATFORMS)[number];
 /** User context embedded in a Peek auth token. */
 interface PeekAuthTokenUser {
     /** User's email address. */
@@ -1929,10 +1934,13 @@ declare class PeekAccessService {
      *   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: string): PeekAuthTokenClaims;
     /**
@@ -2417,15 +2425,148 @@ interface Waiver {
  */
 declare function parseWaiverWebhook(payload: unknown, options?: AccessOptions): Waiver;
 
+/**
+ * The clean data model for an app-store **install lifecycle event** — the single
+ * flat object `parseInstallWebhook` returns for the webhook Peek's app registry
+ * 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).
+ * `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.
+ */
+
+/**
+ * Every install lifecycle status Peek's app registry sends today. Exported so
+ * consumers can validate or enumerate without restating the vocabulary.
+ */
+declare const INSTALL_STATUSES: readonly ["installed", "uninstalled", "update_installed"];
+/** Install lifecycle status. */
+type InstallStatus = (typeof INSTALL_STATUSES)[number];
+/**
+ * A verified install lifecycle event — what happened, to which install, and who
+ * (if anyone) triggered it — as one flat, JSON-safe record.
+ *
+ * This is the shape `parseInstallWebhook` returns. It is flat by design: it
+ * round-trips through a datastore unchanged, so the same shape the parser
+ * 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.
+ */
+interface InstallWebhook {
+    /** Install ID — Peek-assigned UUID. Also the JWT subject (`sub`). */
+    installId: string;
+    /**
+     * Stable Peek account id — the same value Peek calls the **partner ID**.
+     * This event is its only source; it cannot be re-fetched later.
+     */
+    accountId: string;
+    /** Partner display name. `""` when the JSON body omits it. */
+    accountName: string;
+    /**
+     * Which Peek platform owns the install, or `null` when the registry reported
+     * a platform this version of the package does not know. `null` means "newer
+     * than this package", **not** "absent" — do not coerce it to a default.
+     *
+     * **Persist and track this per install.** It is not cosmetic: the platform
+     * determines which APIs the install is served by, and therefore which access
+     * service a consumer must construct for it — `PeekAccessService` for `"peek"`,
+     * `CngAccessService` for `"cng"`, `AcmeAccessService` for `"acme"`, each
+     * routed at a different gateway. Two installs of the same app can sit on
+     * different platforms, so this cannot be inferred from app-level config and
+     * has no source other than this event.
+     */
+    platform: PeekPlatform | null;
+    /** Whether this is a test account. Defaults to `false` when not reported. */
+    isTest: boolean;
+    /**
+     * The lifecycle status, or `null` when the registry sent a status this
+     * version of the package does not know. Handle `null` explicitly — treating
+     * it as a no-op silently drops a lifecycle transition.
+     */
+    status: InstallStatus | null;
+    /** The status exactly as delivered, for logging and for the `null` case. */
+    rawStatus: string;
+    /** App display version at the time of the event. */
+    displayVersion: string;
+    /**
+     * The user that triggered the event, or `null` for system-initiated events
+     * (install lifecycle changes are often system-initiated). From the JWT.
+     */
+    user: PeekAuthTokenUser | null;
+}
+
+/**
+ * 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.
+ *
+ * Signature verification is strict: the HMAC signature (with `secret`), the
+ * token expiry, the `"app_registry_v2"` issuer, and the `"Joken"` audience are
+ * all checked — the same checks as {@link PeekAccessService.verifyPeekAuthToken}.
+ * Any failure throws from the `jsonwebtoken` library, so callers can branch on
+ * the error kind:
+ *
+ * - `JsonWebTokenError` — signature invalid, wrong issuer/audience, or malformed
+ * - `TokenExpiredError` — past `exp`
+ * - `NotBeforeError` — before `nbf`
+ *
+ * An unrecognised `status` or `platform` maps to `null` (with the wire status
+ * preserved on {@link InstallWebhook.rawStatus}) rather than being coerced —
+ * Peek treats any 2xx as delivered and does not redeliver, so handle a `null`
+ * `status` explicitly:
+ *
+ * ```ts
+ * const event = parseInstallWebhook(token, req.body, secret);
+ * switch (event.status) {
+ *   case "installed":        return provision(event);
+ *   case "uninstalled":      return deprovision(event);
+ *   case "update_installed": return recordVersion(event);
+ *   default:                 throw new Error(`unknown install status: ${event.rawStatus}`);
+ * }
+ * ```
+ *
+ * @param token the raw JWT delivered by the install webhook (no `Bearer` prefix)
+ * @param body the delivered JSON body (raw object or a JSON string)
+ * @param secret the app's HMAC signing secret (the `jwtSecret` you construct
+ *   `PeekAccessService` with)
+ * @throws {JsonWebTokenError} signature invalid or token malformed
+ * @throws {TokenExpiredError} token has expired
+ * @throws {NotBeforeError} token not yet valid
+ */
+declare function parseInstallWebhook(token: string, body: unknown, secret: string): InstallWebhook;
 /**
  * Verifies an install-status webhook token and returns its clean claims.
  *
+ * @deprecated Use {@link parseInstallWebhook} instead. This verifier reads only
+ * the signed token, so it cannot report the account **name**, **platform**, or
+ * **test** flag that the webhook's JSON body also carries — the caller was left
+ * to parse that body separately and stitch the two shapes together.
+ * `parseInstallWebhook(token, body, secret)` verifies the same token and returns
+ * one flat {@link InstallWebhook} with every field. This function remains only
+ * for backwards compatibility.
+ *
  * Validates the HMAC signature (with `secret`), the token expiry, the
  * `"app_registry_v2"` issuer, and the `"Joken"` audience — the same checks as
  * {@link PeekAccessService.verifyPeekAuthToken} — then maps the payload to
  * {@link InstallWebhookClaims}, tolerating a `null` `user` (system events).
- * Throws from the `jsonwebtoken` library on any verification failure, so callers
- * can branch on the error kind:
+ * Throws from the `jsonwebtoken` library on any verification failure:
  *
  * - `JsonWebTokenError` — signature invalid, wrong issuer/audience, or malformed
  * - `TokenExpiredError` — past `exp`
@@ -2498,6 +2639,19 @@ 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
@@ -2538,4 +2692,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, 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, noopLogger, parseBookingWebhook, 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 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 };

package/dist/index.d.ts

@@ -1791,13 +1791,18 @@ declare class PricingService {
     private validateResourceOption;
 }
 
+/**
+ * Every platform this package knows about. Exported as a value (not just a
+ * union) so runtime code can recognise a reported platform without restating
+ * the list. New platforms extend this array.
+ */
+declare const PEEK_PLATFORMS: readonly ["peek", "cng", "acme"];
 /**
  * Platform that embedded the app for this session. Verification is
  * brand-agnostic — one peek-auth JWT is minted for every platform — so this
  * claim is the single thing that identifies which platform a request came from.
- * New platforms extend this union.
  */
-type PeekPlatform = "peek" | "cng" | "acme";
+type PeekPlatform = (typeof PEEK_PLATFORMS)[number];
 /** User context embedded in a Peek auth token. */
 interface PeekAuthTokenUser {
     /** User's email address. */
@@ -1929,10 +1934,13 @@ declare class PeekAccessService {
      *   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: string): PeekAuthTokenClaims;
     /**
@@ -2417,15 +2425,148 @@ interface Waiver {
  */
 declare function parseWaiverWebhook(payload: unknown, options?: AccessOptions): Waiver;
 
+/**
+ * The clean data model for an app-store **install lifecycle event** — the single
+ * flat object `parseInstallWebhook` returns for the webhook Peek's app registry
+ * 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).
+ * `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.
+ */
+
+/**
+ * Every install lifecycle status Peek's app registry sends today. Exported so
+ * consumers can validate or enumerate without restating the vocabulary.
+ */
+declare const INSTALL_STATUSES: readonly ["installed", "uninstalled", "update_installed"];
+/** Install lifecycle status. */
+type InstallStatus = (typeof INSTALL_STATUSES)[number];
+/**
+ * A verified install lifecycle event — what happened, to which install, and who
+ * (if anyone) triggered it — as one flat, JSON-safe record.
+ *
+ * This is the shape `parseInstallWebhook` returns. It is flat by design: it
+ * round-trips through a datastore unchanged, so the same shape the parser
+ * 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.
+ */
+interface InstallWebhook {
+    /** Install ID — Peek-assigned UUID. Also the JWT subject (`sub`). */
+    installId: string;
+    /**
+     * Stable Peek account id — the same value Peek calls the **partner ID**.
+     * This event is its only source; it cannot be re-fetched later.
+     */
+    accountId: string;
+    /** Partner display name. `""` when the JSON body omits it. */
+    accountName: string;
+    /**
+     * Which Peek platform owns the install, or `null` when the registry reported
+     * a platform this version of the package does not know. `null` means "newer
+     * than this package", **not** "absent" — do not coerce it to a default.
+     *
+     * **Persist and track this per install.** It is not cosmetic: the platform
+     * determines which APIs the install is served by, and therefore which access
+     * service a consumer must construct for it — `PeekAccessService` for `"peek"`,
+     * `CngAccessService` for `"cng"`, `AcmeAccessService` for `"acme"`, each
+     * routed at a different gateway. Two installs of the same app can sit on
+     * different platforms, so this cannot be inferred from app-level config and
+     * has no source other than this event.
+     */
+    platform: PeekPlatform | null;
+    /** Whether this is a test account. Defaults to `false` when not reported. */
+    isTest: boolean;
+    /**
+     * The lifecycle status, or `null` when the registry sent a status this
+     * version of the package does not know. Handle `null` explicitly — treating
+     * it as a no-op silently drops a lifecycle transition.
+     */
+    status: InstallStatus | null;
+    /** The status exactly as delivered, for logging and for the `null` case. */
+    rawStatus: string;
+    /** App display version at the time of the event. */
+    displayVersion: string;
+    /**
+     * The user that triggered the event, or `null` for system-initiated events
+     * (install lifecycle changes are often system-initiated). From the JWT.
+     */
+    user: PeekAuthTokenUser | null;
+}
+
+/**
+ * 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.
+ *
+ * Signature verification is strict: the HMAC signature (with `secret`), the
+ * token expiry, the `"app_registry_v2"` issuer, and the `"Joken"` audience are
+ * all checked — the same checks as {@link PeekAccessService.verifyPeekAuthToken}.
+ * Any failure throws from the `jsonwebtoken` library, so callers can branch on
+ * the error kind:
+ *
+ * - `JsonWebTokenError` — signature invalid, wrong issuer/audience, or malformed
+ * - `TokenExpiredError` — past `exp`
+ * - `NotBeforeError` — before `nbf`
+ *
+ * An unrecognised `status` or `platform` maps to `null` (with the wire status
+ * preserved on {@link InstallWebhook.rawStatus}) rather than being coerced —
+ * Peek treats any 2xx as delivered and does not redeliver, so handle a `null`
+ * `status` explicitly:
+ *
+ * ```ts
+ * const event = parseInstallWebhook(token, req.body, secret);
+ * switch (event.status) {
+ *   case "installed":        return provision(event);
+ *   case "uninstalled":      return deprovision(event);
+ *   case "update_installed": return recordVersion(event);
+ *   default:                 throw new Error(`unknown install status: ${event.rawStatus}`);
+ * }
+ * ```
+ *
+ * @param token the raw JWT delivered by the install webhook (no `Bearer` prefix)
+ * @param body the delivered JSON body (raw object or a JSON string)
+ * @param secret the app's HMAC signing secret (the `jwtSecret` you construct
+ *   `PeekAccessService` with)
+ * @throws {JsonWebTokenError} signature invalid or token malformed
+ * @throws {TokenExpiredError} token has expired
+ * @throws {NotBeforeError} token not yet valid
+ */
+declare function parseInstallWebhook(token: string, body: unknown, secret: string): InstallWebhook;
 /**
  * Verifies an install-status webhook token and returns its clean claims.
  *
+ * @deprecated Use {@link parseInstallWebhook} instead. This verifier reads only
+ * the signed token, so it cannot report the account **name**, **platform**, or
+ * **test** flag that the webhook's JSON body also carries — the caller was left
+ * to parse that body separately and stitch the two shapes together.
+ * `parseInstallWebhook(token, body, secret)` verifies the same token and returns
+ * one flat {@link InstallWebhook} with every field. This function remains only
+ * for backwards compatibility.
+ *
  * Validates the HMAC signature (with `secret`), the token expiry, the
  * `"app_registry_v2"` issuer, and the `"Joken"` audience — the same checks as
  * {@link PeekAccessService.verifyPeekAuthToken} — then maps the payload to
  * {@link InstallWebhookClaims}, tolerating a `null` `user` (system events).
- * Throws from the `jsonwebtoken` library on any verification failure, so callers
- * can branch on the error kind:
+ * Throws from the `jsonwebtoken` library on any verification failure:
  *
  * - `JsonWebTokenError` — signature invalid, wrong issuer/audience, or malformed
  * - `TokenExpiredError` — past `exp`
@@ -2498,6 +2639,19 @@ 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
@@ -2538,4 +2692,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, 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, noopLogger, parseBookingWebhook, 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 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 };

package/dist/index.js

@@ -225,6 +225,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;
@@ -2037,6 +2046,9 @@ function verifyPeekJwt(token, secret) {
   });
 }
 function mapPeekTokenUser(u) {
+  if (!u.id) {
+    throw new InvalidPeekTokenError("user.id");
+  }
   return {
     email: u.email,
     id: u.id,
@@ -3560,10 +3572,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);
@@ -4234,7 +4249,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 {
@@ -4246,6 +4307,6 @@ function verifyInstallWebhook(token, secret) {
   };
 }
 
-export { ACTIVITY_PRODUCT_TYPE, ADD_ON_PRODUCT_TYPE, AccountUserService, AcmeAccessService, AcmeApiError, AcmeProductService, AdminAccountRequiredError, AvailabilityService, BookingService, CngAccessService, CngApiError, CngProductService, DailyNoteService, MembershipService, PeekAccessService, PeekGraphQLError, PeekHttpError, PiiAccessDisabledError, PricingService, ProductService, PromoCodeService, RENTAL_PRODUCT_TYPE, RateLimitError, ResellerService, ResourcePoolService, ReviewService, TimeslotService, noopLogger, parseBookingWebhook, parseWaiverWebhook, verifyInstallWebhook };
+export { ACTIVITY_PRODUCT_TYPE, ADD_ON_PRODUCT_TYPE, AccountUserService, AcmeAccessService, AcmeApiError, AcmeProductService, AdminAccountRequiredError, AvailabilityService, BookingService, CngAccessService, CngApiError, CngProductService, DailyNoteService, INSTALL_STATUSES, InvalidPeekTokenError, MembershipService, PeekAccessService, PeekGraphQLError, PeekHttpError, PiiAccessDisabledError, PricingService, ProductService, PromoCodeService, RENTAL_PRODUCT_TYPE, RateLimitError, ResellerService, ResourcePoolService, ReviewService, TimeslotService, noopLogger, parseBookingWebhook, parseInstallWebhook, parseWaiverWebhook, verifyInstallWebhook };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map