@peektravel/app-utilities 0.5.4 → 0.6.1

package/dist/index.d.cts

@@ -345,6 +345,22 @@ interface Product {
      * pricing overrides use this to set the currency on fixed-price adjustments.
      */
     currency: string;
+    /**
+     * URL of the product's primary display image, or `null` when Peek reports
+     * none. Populated for activities/rentals; always `null` for add-ons.
+     */
+    imageUrl: string | null;
+    /**
+     * Long-form product description (may contain HTML), or `null` when Peek
+     * reports none. Populated for activities/rentals; always `null` for add-ons.
+     */
+    description: string | null;
+    /**
+     * Where the experience meets, or `null` when Peek reports no location detail.
+     * Populated for activities/rentals; always `null` for add-ons. Each field
+     * inside is independently nullable.
+     */
+    meetingLocation: ProductMeetingLocation | null;
     /**
      * The bookable sub-options of this product.
      *
@@ -353,6 +369,15 @@ interface Product {
      */
     tickets: ProductTicket[];
 }
+/** The meeting point for a bookable experience. Every field is nullable. */
+interface ProductMeetingLocation {
+    /** Free-text summary / instructions for the meeting point. */
+    summary: string | null;
+    /** Formatted postal address of the meeting point. */
+    address: string | null;
+    /** Map/link URL for the meeting point. */
+    url: string | null;
+}
 /** A single bookable sub-option (resource option or add-on item option). */
 interface ProductTicket {
     /** Unique identifier of the ticket / option. */
@@ -1766,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. */
@@ -1904,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;
     /**
@@ -2415,6 +2448,128 @@ declare function parseWaiverWebhook(payload: unknown, options?: AccessOptions):
  */
 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.
+ *
+ * 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.
+ */
+
+/**
+ * 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];
+/**
+ * Who an install is — the core account data, in one object.
+ *
+ * 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.
+ */
+interface InstallIdentity {
+    /** Install ID — Peek-assigned UUID. Also the subject of every peek-auth JWT. */
+    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. */
+    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;
+}
+/** 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
+     * 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 install's core account data. */
+    identity: InstallIdentity;
+}
+
+/**
+ * Public webhook surface for the **install-event** channel — the JSON body
+ * Peek's app registry POSTs on install, uninstall, and update.
+ *
+ * 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}.
+ *
+ * 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}.
+ *
+ * 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}.
+ *
+ * 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:
+ *
+ * ```ts
+ * const event = parseInstallEvent(req.body);
+ * 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);
+ *   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.
+ */
+declare function parseInstallEvent(payload: unknown): InstallEvent;
+
 /**
  * Typed errors thrown by the package. Each mirrors a failure mode of the Peek
  * GraphQL gateway (or the CNG REST gateway) so callers can branch on the error
@@ -2473,6 +2628,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
@@ -2513,4 +2681,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, 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 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 };

package/dist/index.d.ts

@@ -345,6 +345,22 @@ interface Product {
      * pricing overrides use this to set the currency on fixed-price adjustments.
      */
     currency: string;
+    /**
+     * URL of the product's primary display image, or `null` when Peek reports
+     * none. Populated for activities/rentals; always `null` for add-ons.
+     */
+    imageUrl: string | null;
+    /**
+     * Long-form product description (may contain HTML), or `null` when Peek
+     * reports none. Populated for activities/rentals; always `null` for add-ons.
+     */
+    description: string | null;
+    /**
+     * Where the experience meets, or `null` when Peek reports no location detail.
+     * Populated for activities/rentals; always `null` for add-ons. Each field
+     * inside is independently nullable.
+     */
+    meetingLocation: ProductMeetingLocation | null;
     /**
      * The bookable sub-options of this product.
      *
@@ -353,6 +369,15 @@ interface Product {
      */
     tickets: ProductTicket[];
 }
+/** The meeting point for a bookable experience. Every field is nullable. */
+interface ProductMeetingLocation {
+    /** Free-text summary / instructions for the meeting point. */
+    summary: string | null;
+    /** Formatted postal address of the meeting point. */
+    address: string | null;
+    /** Map/link URL for the meeting point. */
+    url: string | null;
+}
 /** A single bookable sub-option (resource option or add-on item option). */
 interface ProductTicket {
     /** Unique identifier of the ticket / option. */
@@ -1766,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. */
@@ -1904,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;
     /**
@@ -2415,6 +2448,128 @@ declare function parseWaiverWebhook(payload: unknown, options?: AccessOptions):
  */
 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.
+ *
+ * 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.
+ */
+
+/**
+ * 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];
+/**
+ * Who an install is — the core account data, in one object.
+ *
+ * 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.
+ */
+interface InstallIdentity {
+    /** Install ID — Peek-assigned UUID. Also the subject of every peek-auth JWT. */
+    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. */
+    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;
+}
+/** 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
+     * 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 install's core account data. */
+    identity: InstallIdentity;
+}
+
+/**
+ * Public webhook surface for the **install-event** channel — the JSON body
+ * Peek's app registry POSTs on install, uninstall, and update.
+ *
+ * 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}.
+ *
+ * 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}.
+ *
+ * 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}.
+ *
+ * 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:
+ *
+ * ```ts
+ * const event = parseInstallEvent(req.body);
+ * 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);
+ *   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.
+ */
+declare function parseInstallEvent(payload: unknown): InstallEvent;
+
 /**
  * Typed errors thrown by the package. Each mirrors a failure mode of the Peek
  * GraphQL gateway (or the CNG REST gateway) so callers can branch on the error
@@ -2473,6 +2628,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
@@ -2513,4 +2681,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, 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 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 };

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,
@@ -2854,6 +2866,13 @@ function toPricingMoney(raw) {
 
 // src/internal/peek/products/product-converter.ts
 var ADD_ON_COLOR = "#FFFFFF";
+function toMeetingLocation(activity) {
+  const summary = activity.infoMeetingLocation ?? null;
+  const address = activity.meetingLocationFormattedAddress ?? null;
+  const url = activity.meetingLocationUrl ?? null;
+  if (summary === null && address === null && url === null) return null;
+  return { summary, address, url };
+}
 function fromActivities(activities) {
   return activities.map(fromActivity);
 }
@@ -2865,6 +2884,9 @@ function fromActivity(activity) {
     type: activity.type,
     color: activity.colorHex || "",
     currency: activity.currency || "",
+    imageUrl: activity.imageUrl ?? null,
+    description: activity.description ?? null,
+    meetingLocation: toMeetingLocation(activity),
     tickets: (activity.resourceOptions ?? []).map((option) => ({
       id: option.id,
       name: option.name,
@@ -2886,6 +2908,9 @@ function fromItemOptionNodes(nodes) {
         type: ADD_ON_PRODUCT_TYPE,
         color: ADD_ON_COLOR,
         currency: "",
+        imageUrl: null,
+        description: null,
+        meetingLocation: null,
         tickets: []
       };
       grouped.set(itemId, product);
@@ -2911,6 +2936,11 @@ var PRODUCTS_QUERY = `
       type
       colorHex
       currency
+      imageUrl
+      description
+      meetingLocationFormattedAddress
+      meetingLocationUrl
+      infoMeetingLocation
       resourceOptions {
         id
         name
@@ -3542,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);
@@ -4228,6 +4261,61 @@ 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 };
+// 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 toInstallStatus(raw) {
+  return INSTALL_STATUSES.includes(raw) ? raw : null;
+}
+function toPeekPlatform(raw) {
+  return PEEK_PLATFORMS.includes(raw) ? raw : null;
+}
+function fromInstallIdentityNode(node) {
+  const data = node ?? {};
+  const account = data.account ?? {};
+  return {
+    installId: data.install_id || "",
+    accountId: account.id || "",
+    accountName: account.name || "",
+    platform: toPeekPlatform(account.platform || ""),
+    isTest: Boolean(account.is_test)
+  };
+}
+function fromInstallEventNode(node) {
+  const rawStatus = node?.status || "";
+  return {
+    status: toInstallStatus(rawStatus),
+    rawStatus,
+    displayVersion: node?.display_version || "",
+    identity: fromInstallIdentityNode(node)
+  };
+}
+
+// src/internal/peek/installs/install-event.ts
+function parseInstallEvent(payload) {
+  return fromInstallEventNode(extractInstallEventNode(payload));
+}
+function extractInstallEventNode(payload) {
+  let body = payload;
+  if (typeof body === "string") {
+    try {
+      body = JSON.parse(body);
+    } catch {
+      return {};
+    }
+  }
+  if (!body || typeof body !== "object") return {};
+  return body;
+}
+
+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, parseInstallEvent, parseWaiverWebhook, verifyInstallWebhook };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map