@peektravel/app-utilities 0.6.1 → 0.7.1

package/dist/index.d.cts

@@ -1926,9 +1926,10 @@ declare class PeekAccessService {
      * decoded claims.
      *
      * Validates the HMAC signature (using this service's `jwtSecret`), the token
-     * expiry, the `"app_registry_v2"` issuer, and the `"Joken"` audience. Throws
-     * from the `jsonwebtoken` library on any failure — callers should catch to
-     * distinguish error kinds:
+     * expiry, the `"app_registry_v2"` issuer, and the `"Joken"` audience. Pass the
+     * raw `x-peek-auth` request header value — a leading `Bearer ` prefix, if
+     * present, is stripped for you. Throws from the `jsonwebtoken` library on any
+     * failure — callers should catch to distinguish error kinds:
      *
      * - `JsonWebTokenError` — signature invalid, wrong issuer/audience, or token
      *   malformed
@@ -2426,41 +2427,21 @@ interface Waiver {
 declare function parseWaiverWebhook(payload: unknown, options?: AccessOptions): Waiver;
 
 /**
- * Verifies an install-status webhook token and returns its clean claims.
+ * 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.
  *
- * 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:
- *
- * - `JsonWebTokenError` — signature invalid, wrong issuer/audience, or malformed
- * - `TokenExpiredError` — past `exp`
- * - `NotBeforeError` — before `nbf`
- *
- * @param token the raw JWT delivered by the install webhook (no `Bearer` prefix)
- * @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 verifyInstallWebhook(token: string, secret: string): InstallWebhookClaims;
-
-/**
- * The clean data model for an app-store **install lifecycle event** — the JSON
- * webhook body Peek's app registry POSTs when an app is installed, uninstalled,
- * or updated.
- *
- * This is the sibling of the signed-JWT channel behind `verifyInstallWebhook`
- * (see `models/peek/auth-token.ts`). The two carry the same event; this one is
- * the richer of the pair, because only it reports the account **name**,
- * **platform**, and **test** flag.
+ * 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 and no peek-auth token returns it, so whatever a consumer
- * persists from this event is all it will ever have.
+ * GraphQL read returns it, so whatever a consumer persists from this event is
+ * all it will ever have.
  */
 
 /**
@@ -2471,21 +2452,27 @@ declare const INSTALL_STATUSES: readonly ["installed", "uninstalled", "update_in
 /** Install lifecycle status. */
 type InstallStatus = (typeof INSTALL_STATUSES)[number];
 /**
- * Who an install is — the core account data, in one object.
+ * 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.
  *
- * Flat and JSON-safe 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 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 InstallIdentity {
-    /** Install ID — Peek-assigned UUID. Also the subject of every peek-auth JWT. */
+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. */
+    /** Partner display name. `""` when the JSON body omits it. */
     accountName: string;
     /**
      * Which Peek platform owns the install, or `null` when the registry reported
@@ -2503,9 +2490,6 @@ interface InstallIdentity {
     platform: PeekPlatform | null;
     /** Whether this is a test account. Defaults to `false` when not reported. */
     isTest: boolean;
-}
-/** A parsed install lifecycle event: what happened, to which install. */
-interface InstallEvent {
     /**
      * The lifecycle status, or `null` when the registry sent a status this
      * version of the package does not know. Handle `null` explicitly — treating
@@ -2516,59 +2500,91 @@ interface InstallEvent {
     rawStatus: string;
     /** App display version at the time of the event. */
     displayVersion: string;
-    /** The install's core account data. */
-    identity: InstallIdentity;
+    /**
+     * 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;
 }
 
 /**
- * Public webhook surface for the **install-event** channel — the JSON body
- * Peek's app registry POSTs on install, uninstall, and update.
+ * Verifies an install-status webhook token and merges it with the delivered
+ * JSON body into one flat {@link InstallWebhook}.
  *
- * This is the second of the two install channels. Its sibling,
- * `verifyInstallWebhook`, receives the same lifecycle event as a signed
- * `app_registry_v2` JWT; that payload authenticates itself but carries only the
- * account **id**. This one carries the account's name, platform, and test flag
- * as well, which makes it the authoritative source of {@link InstallIdentity}.
+ * 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.
  *
- * Like the booking and waiver parsers, this is a pure transform — no auth, no
- * network, no client — so it is a standalone function rather than a method on
- * `PeekAccessService`. The receiver holds no gateway credentials for an install
- * it has not recorded yet, and an uninstall describes one being torn down.
- *
- * **It never throws.** The sender is first-party and the payload contract is
- * Peek's own, so defending against malformed input would be defending against a
- * case that does not arise. What the parser does guard is the contract
- * *growing*: an unrecognised `status` or `platform` surfaces as `null` rather
- * than being coerced into a known value, so a newer registry can never be
- * silently mistaken for an older one.
- */
-
-/**
- * Parses a delivered install-event webhook body into a clean
- * {@link InstallEvent}.
+ * 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:
  *
- * Accepts the raw request body, or a JSON string, which is parsed first.
- * Missing fields map to `""`/`false`; an unknown `status` or `platform` maps to
- * `null` with the wire value preserved on {@link InstallEvent.rawStatus}.
+ * - `JsonWebTokenError` — signature invalid, wrong issuer/audience, or malformed
+ * - `TokenExpiredError` — past `exp`
+ * - `NotBeforeError` — before `nbf`
  *
- * Handle a `null` `status` explicitly. Peek treats any 2xx as delivered and
- * will not redeliver, so responding successfully to a status the package does
- * not recognise silently drops a lifecycle transition:
+ * 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 = parseInstallEvent(req.body);
+ * const event = parseInstallWebhook(token, req.body, secret);
  * switch (event.status) {
- *   case "installed":        return provision(event.identity, event.displayVersion);
- *   case "uninstalled":      return deprovision(event.identity);
- *   case "update_installed": return recordVersion(event.identity, event.displayVersion);
+ *   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}`);
  * }
  * ```
  *
- * Persist `event.identity` as a unit: it is flat and JSON-safe, and its
- * `accountId` (the partner ID) has no other source in the system.
+ * @param token the JWT delivered by the install webhook. Pass the raw
+ *   `x-peek-auth` header value directly — a leading `Bearer ` prefix, if
+ *   present, is stripped for you.
+ * @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 parseInstallEvent(payload: unknown): InstallEvent;
+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:
+ *
+ * - `JsonWebTokenError` — signature invalid, wrong issuer/audience, or malformed
+ * - `TokenExpiredError` — past `exp`
+ * - `NotBeforeError` — before `nbf`
+ *
+ * @param token the JWT delivered by the install webhook. Pass the raw
+ *   `x-peek-auth` header value directly — a leading `Bearer ` prefix, if
+ *   present, is stripped for you.
+ * @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 verifyInstallWebhook(token: string, secret: string): InstallWebhookClaims;
 
 /**
  * Typed errors thrown by the package. Each mirrors a failure mode of the Peek
@@ -2681,4 +2697,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 InstallEvent, type InstallIdentity, type InstallStatus, 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, parseInstallEvent, 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

@@ -1926,9 +1926,10 @@ declare class PeekAccessService {
      * decoded claims.
      *
      * Validates the HMAC signature (using this service's `jwtSecret`), the token
-     * expiry, the `"app_registry_v2"` issuer, and the `"Joken"` audience. Throws
-     * from the `jsonwebtoken` library on any failure — callers should catch to
-     * distinguish error kinds:
+     * expiry, the `"app_registry_v2"` issuer, and the `"Joken"` audience. Pass the
+     * raw `x-peek-auth` request header value — a leading `Bearer ` prefix, if
+     * present, is stripped for you. Throws from the `jsonwebtoken` library on any
+     * failure — callers should catch to distinguish error kinds:
      *
      * - `JsonWebTokenError` — signature invalid, wrong issuer/audience, or token
      *   malformed
@@ -2426,41 +2427,21 @@ interface Waiver {
 declare function parseWaiverWebhook(payload: unknown, options?: AccessOptions): Waiver;
 
 /**
- * Verifies an install-status webhook token and returns its clean claims.
+ * 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.
  *
- * 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:
- *
- * - `JsonWebTokenError` — signature invalid, wrong issuer/audience, or malformed
- * - `TokenExpiredError` — past `exp`
- * - `NotBeforeError` — before `nbf`
- *
- * @param token the raw JWT delivered by the install webhook (no `Bearer` prefix)
- * @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 verifyInstallWebhook(token: string, secret: string): InstallWebhookClaims;
-
-/**
- * The clean data model for an app-store **install lifecycle event** — the JSON
- * webhook body Peek's app registry POSTs when an app is installed, uninstalled,
- * or updated.
- *
- * This is the sibling of the signed-JWT channel behind `verifyInstallWebhook`
- * (see `models/peek/auth-token.ts`). The two carry the same event; this one is
- * the richer of the pair, because only it reports the account **name**,
- * **platform**, and **test** flag.
+ * 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 and no peek-auth token returns it, so whatever a consumer
- * persists from this event is all it will ever have.
+ * GraphQL read returns it, so whatever a consumer persists from this event is
+ * all it will ever have.
  */
 
 /**
@@ -2471,21 +2452,27 @@ declare const INSTALL_STATUSES: readonly ["installed", "uninstalled", "update_in
 /** Install lifecycle status. */
 type InstallStatus = (typeof INSTALL_STATUSES)[number];
 /**
- * Who an install is — the core account data, in one object.
+ * 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.
  *
- * Flat and JSON-safe 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 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 InstallIdentity {
-    /** Install ID — Peek-assigned UUID. Also the subject of every peek-auth JWT. */
+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. */
+    /** Partner display name. `""` when the JSON body omits it. */
     accountName: string;
     /**
      * Which Peek platform owns the install, or `null` when the registry reported
@@ -2503,9 +2490,6 @@ interface InstallIdentity {
     platform: PeekPlatform | null;
     /** Whether this is a test account. Defaults to `false` when not reported. */
     isTest: boolean;
-}
-/** A parsed install lifecycle event: what happened, to which install. */
-interface InstallEvent {
     /**
      * The lifecycle status, or `null` when the registry sent a status this
      * version of the package does not know. Handle `null` explicitly — treating
@@ -2516,59 +2500,91 @@ interface InstallEvent {
     rawStatus: string;
     /** App display version at the time of the event. */
     displayVersion: string;
-    /** The install's core account data. */
-    identity: InstallIdentity;
+    /**
+     * 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;
 }
 
 /**
- * Public webhook surface for the **install-event** channel — the JSON body
- * Peek's app registry POSTs on install, uninstall, and update.
+ * Verifies an install-status webhook token and merges it with the delivered
+ * JSON body into one flat {@link InstallWebhook}.
  *
- * This is the second of the two install channels. Its sibling,
- * `verifyInstallWebhook`, receives the same lifecycle event as a signed
- * `app_registry_v2` JWT; that payload authenticates itself but carries only the
- * account **id**. This one carries the account's name, platform, and test flag
- * as well, which makes it the authoritative source of {@link InstallIdentity}.
+ * 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.
  *
- * Like the booking and waiver parsers, this is a pure transform — no auth, no
- * network, no client — so it is a standalone function rather than a method on
- * `PeekAccessService`. The receiver holds no gateway credentials for an install
- * it has not recorded yet, and an uninstall describes one being torn down.
- *
- * **It never throws.** The sender is first-party and the payload contract is
- * Peek's own, so defending against malformed input would be defending against a
- * case that does not arise. What the parser does guard is the contract
- * *growing*: an unrecognised `status` or `platform` surfaces as `null` rather
- * than being coerced into a known value, so a newer registry can never be
- * silently mistaken for an older one.
- */
-
-/**
- * Parses a delivered install-event webhook body into a clean
- * {@link InstallEvent}.
+ * 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:
  *
- * Accepts the raw request body, or a JSON string, which is parsed first.
- * Missing fields map to `""`/`false`; an unknown `status` or `platform` maps to
- * `null` with the wire value preserved on {@link InstallEvent.rawStatus}.
+ * - `JsonWebTokenError` — signature invalid, wrong issuer/audience, or malformed
+ * - `TokenExpiredError` — past `exp`
+ * - `NotBeforeError` — before `nbf`
  *
- * Handle a `null` `status` explicitly. Peek treats any 2xx as delivered and
- * will not redeliver, so responding successfully to a status the package does
- * not recognise silently drops a lifecycle transition:
+ * 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 = parseInstallEvent(req.body);
+ * const event = parseInstallWebhook(token, req.body, secret);
  * switch (event.status) {
- *   case "installed":        return provision(event.identity, event.displayVersion);
- *   case "uninstalled":      return deprovision(event.identity);
- *   case "update_installed": return recordVersion(event.identity, event.displayVersion);
+ *   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}`);
  * }
  * ```
  *
- * Persist `event.identity` as a unit: it is flat and JSON-safe, and its
- * `accountId` (the partner ID) has no other source in the system.
+ * @param token the JWT delivered by the install webhook. Pass the raw
+ *   `x-peek-auth` header value directly — a leading `Bearer ` prefix, if
+ *   present, is stripped for you.
+ * @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 parseInstallEvent(payload: unknown): InstallEvent;
+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:
+ *
+ * - `JsonWebTokenError` — signature invalid, wrong issuer/audience, or malformed
+ * - `TokenExpiredError` — past `exp`
+ * - `NotBeforeError` — before `nbf`
+ *
+ * @param token the JWT delivered by the install webhook. Pass the raw
+ *   `x-peek-auth` header value directly — a leading `Bearer ` prefix, if
+ *   present, is stripped for you.
+ * @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 verifyInstallWebhook(token: string, secret: string): InstallWebhookClaims;
 
 /**
  * Typed errors thrown by the package. Each mirrors a failure mode of the Peek
@@ -2681,4 +2697,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 InstallEvent, type InstallIdentity, type InstallStatus, 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, parseInstallEvent, 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 };