@peektravel/app-utilities 0.4.1 → 0.5.1

package/dist/index.d.cts

@@ -95,6 +95,14 @@ interface Product {
      * Add-ons default to white (`"#FFFFFF"`). Empty string when no color is set.
      */
     color: string;
+    /**
+     * ISO 4217 currency code the activity prices in (e.g. `"USD"`).
+     *
+     * Populated for activities and rentals; empty string for add-ons (which carry
+     * no currency of their own) and when Peek reports none. Consumers building
+     * pricing overrides use this to set the currency on fixed-price adjustments.
+     */
+    currency: string;
     /**
      * The bookable sub-options of this product.
      *
@@ -156,6 +164,31 @@ declare class ProductService {
     private fetchAllItemOptionNodes;
 }
 
+/**
+ * Cross-cutting options that govern what data an access service will read and
+ * expose. Passed once when constructing an access service and threaded down to
+ * the resource services (and the webhook parsers) so a single object controls
+ * behaviour everywhere, rather than a boolean being passed hand-to-hand.
+ *
+ * Kept deliberately small — today it carries a single PII toggle, but new
+ * cross-cutting flags slot in here without changing any downstream signatures.
+ */
+/** Options controlling PII exposure across an access service's reads. */
+interface AccessOptions {
+    /**
+     * When `true`, customer PII (guest names/emails/phones, custom question
+     * answers, the customer booking-portal URL, waiver participant details, …) is
+     * requested and returned, and payment/booking-modification operations are
+     * available.
+     *
+     * When `false` (the default), those PII fields are never requested from the
+     * gateway and come back `null`/empty, and the payment/booking-modification
+     * operations that touch customer financial data are disabled (they throw a
+     * {@link PiiAccessDisabledError}).
+     */
+    fullCustomerAccess?: boolean;
+}
+
 /**
  * The clean, transport-agnostic data model for Peek Pro bookings.
  *
@@ -667,6 +700,8 @@ interface CancelBookingResult {
 interface BookingServiceOptions {
     /** Page size for cursor pagination. Default: 50. */
     pageSize?: number;
+    /** Cross-cutting access options (PII exposure). Default: PII off. */
+    accessOptions?: AccessOptions;
 }
 /** Dependencies the {@link BookingService} composes for add-on resolution. */
 interface BookingServiceDeps {
@@ -688,7 +723,15 @@ declare class BookingService {
     private readonly client;
     private readonly deps;
     private readonly pageSize;
+    /** Whether customer PII is requested and payment operations are allowed. */
+    private readonly fullCustomerAccess;
     constructor(client: GraphQLClient, deps: BookingServiceDeps, options?: BookingServiceOptions);
+    /**
+     * Throws a {@link PiiAccessDisabledError} for `operation` when this service was
+     * created without `fullCustomerAccess` — used to gate payment and booking-modification
+     * operations that touch customer financial data.
+     */
+    private assertPiiEnabled;
     /**
      * Returns a single booking by id, or null when not found. The `bookingId` is
      * normalized internally (lowercased, `-` → `_`), so `B-ABC123` and `b_abc123`
@@ -965,6 +1008,237 @@ interface AvailabilityTimesQuery {
     resourceOptionQuantities: ResourceOptionQuantity[];
 }
 
+/**
+ * The clean data model for Peek Pro pricing engines and pricing overrides.
+ *
+ * A **pricing engine** is a named container Peek Pro applies at checkout. A
+ * caller creates one lazily, stores its id, then repeatedly **upserts pricing
+ * overrides** onto it for a given date range. Overrides adjust ticket prices
+ * (fixed replacement or percentage adjustment) for an activity, optionally
+ * gated by how many spots are already taken and/or a start-time window.
+ *
+ * Scope note: this package is a thin wrapper over the Peek GraphQL primitives.
+ * It does **not** own the domain logic that decides *what* the overrides should
+ * be — segmenting an activity across time windows, ordering overrides by tier,
+ * or computing the `spotsTaken` bounds. The caller builds an
+ * {@link UpsertOverridesInput} and the service sends it faithfully; the service
+ * only maps between these clean shapes and the raw GraphQL payload.
+ */
+/**
+ * A monetary value on a pricing override.
+ *
+ * `amount` is intentionally a **string** (e.g. `"50.00"`), never a number — the
+ * Peek API rejects floats here, and stringly-typed money avoids precision loss.
+ */
+interface PricingMoney {
+    /** Numeric amount as a decimal string (e.g. `"50.00"`). */
+    amount: string;
+    /** ISO 4217 currency code (e.g. `"USD"`). */
+    currency: string;
+}
+/** An `{ id, name }` reference to a Peek entity echoed back in a response. */
+interface PricingNamedRef {
+    /** Stable Peek identifier. */
+    id: string;
+    /** Human-readable display name. */
+    name: string;
+}
+/** Input for creating a pricing engine. */
+interface CreateEngineInput {
+    /** Display name for the engine. */
+    name: string;
+    /**
+     * Optional list of activity ids the engine is scoped to. Omit (or pass an
+     * empty array) to create an unfiltered engine that applies to all activities.
+     */
+    activityIds?: string[];
+}
+/**
+ * The result of creating a pricing engine.
+ *
+ * The create mutation returns only the new engine's id; store it as the
+ * schedule's `source_refid` for subsequent override upserts.
+ */
+interface CreatedPricingEngine {
+    /** The new engine's id. */
+    id: string;
+}
+/** Input for updating a pricing engine's name and/or activity scope. */
+interface UpdateEngineInput {
+    /** The engine to update. */
+    engineId: string;
+    /** New display name. */
+    name: string;
+    /**
+     * Activity ids the engine should be scoped to. An empty array (or omitting
+     * the field) **clears** the filter so the engine applies to all activities.
+     */
+    activityIds?: string[];
+}
+/** A pricing engine reference as echoed back by the API. */
+interface PricingEngine {
+    /** Engine id. */
+    id: string;
+    /** Engine display name. */
+    name: string;
+}
+/**
+ * A single ticket (resourceOption) price override, discriminated by `mode`.
+ *
+ * - `fixed` — replace the ticket price outright with {@link PricingMoney}.
+ * - `percentage` — adjust the ticket price by a percentage. The adjustment is a
+ *   decimal **string** (e.g. `"-25"` for 25% off) and must be greater than
+ *   `-100`.
+ */
+type ResourceOptionOverride = {
+    /** The Peek resourceOption (ticket) id being overridden. */
+    id: string;
+    mode: "fixed";
+    /** The replacement price. */
+    price: PricingMoney;
+} | {
+    /** The Peek resourceOption (ticket) id being overridden. */
+    id: string;
+    mode: "percentage";
+    /** Percentage adjustment as a decimal string, e.g. `"-25"`. Must be > -100. */
+    percentageAdjustment: string;
+};
+/**
+ * A filter gating when an override applies. Both variants are optional and an
+ * override may carry zero, one, or both.
+ */
+type PricingOverrideFilter = {
+    /**
+     * Restricts the override by how many spots are already taken.
+     *
+     * `minSpots`/`maxSpots` are **zero-indexed spots-taken counts**, not
+     * ticket counts — e.g. "applies from the 5th ticket onward" is
+     * `{ minSpots: 4 }`. The caller is responsible for this off-by-one
+     * conversion from ticket-count ranges.
+     */
+    spotsTaken: {
+        /** Lower bound (inclusive) on spots already taken. Omit for no lower bound. */
+        minSpots?: number;
+        /** Upper bound (inclusive) on spots already taken. Omit for no upper bound. */
+        maxSpots?: number;
+    };
+} | {
+    /**
+     * Restricts the override to a start-time window, as a PostgreSQL-style
+     * inclusive range string `"[HH:MM:SS,HH:MM:SS]"`.
+     */
+    startTimeRange: string;
+};
+/**
+ * One override entry for an activity: which tickets it adjusts, in what order,
+ * under which filters.
+ */
+interface PricingOverride {
+    /**
+     * The override's precedence index (0-based). The caller assigns this — Peek
+     * evaluates lower `order` values first, so higher-discount / more-specific
+     * tiers should get lower numbers.
+     */
+    order: number;
+    /** The per-ticket price overrides applied by this entry. */
+    resourceOptions: ResourceOptionOverride[];
+    /** Zero or more filters gating when this entry applies. */
+    filters: PricingOverrideFilter[];
+}
+/** The set of overrides to apply for a single activity. */
+interface ActivityOverrides {
+    /** The Peek activity id these overrides apply to. */
+    activityId: string;
+    /**
+     * The overrides for this activity. Pass an **empty array to clear** all
+     * overrides for the activity — never omit the activity to clear it.
+     */
+    overrides: PricingOverride[];
+}
+/**
+ * The full input for upserting pricing overrides onto an engine.
+ *
+ * Mirrors the Peek `upsertPricingOverridesActivityContexts` input verbatim. The
+ * caller owns all segmentation and ordering; the service sends this as-is.
+ */
+interface UpsertOverridesInput {
+    /** The engine to write overrides to (its {@link CreatedPricingEngine.id}). */
+    engineId: string;
+    /**
+     * The date range the overrides apply to, as a PostgreSQL-style inclusive
+     * range string. For a single day, both ends are the same: `"[2025-07-04,2025-07-04]"`.
+     */
+    dateRange: string;
+    /** One entry per activity being written (or cleared). */
+    activities: ActivityOverrides[];
+}
+/**
+ * Convenience input for clearing all overrides across a set of activities for a
+ * date range. Equivalent to an {@link UpsertOverridesInput} whose every
+ * activity carries `overrides: []`.
+ */
+interface ClearOverridesInput {
+    /** The engine to clear overrides on. */
+    engineId: string;
+    /** The date range to clear, same format as {@link UpsertOverridesInput.dateRange}. */
+    dateRange: string;
+    /** The activity ids to clear. Recover these from a prior sync's payload. */
+    activityIds: string[];
+}
+/**
+ * A ticket price override as **resolved** by Peek, discriminated by `mode`.
+ *
+ * This normalizes Peek's GraphQL union (a `price` object vs a bare
+ * `percentageAdjustment`) into the same `mode`-tagged shape used on input.
+ */
+type ResolvedOverride = {
+    mode: "fixed";
+    /** The resolved replacement price. */
+    price: PricingMoney;
+} | {
+    mode: "percentage";
+    /** The resolved percentage adjustment as a decimal string. */
+    percentageAdjustment: string;
+};
+/** A single ticket's resolved override within a returned context. */
+interface ResolvedResourceOption {
+    /** The ticket (resourceOption) this override resolved for. */
+    resourceOption: PricingNamedRef;
+    /** The resolved fixed or percentage override. */
+    override: ResolvedOverride;
+}
+/** A single resolved override entry within a returned activity context. */
+interface ResolvedPricingOverride {
+    /** The override's precedence index as stored by Peek. */
+    order: number;
+    /** The resolved per-ticket overrides. */
+    resourceOptions: ResolvedResourceOption[];
+    /**
+     * The filters gating this override, normalized to the same shape as the
+     * {@link PricingOverrideFilter} used on input.
+     */
+    filters: PricingOverrideFilter[];
+}
+/**
+ * The resolved pricing state for one activity on one date, as returned by an
+ * upsert or clear. Useful as an audit record of exactly what Peek stored.
+ */
+interface PricingActivityContext {
+    /** The date the context applies to (ISO `YYYY-MM-DD`). */
+    date: string;
+    /** The activity the overrides belong to. */
+    activity: PricingNamedRef;
+    /** The engine the overrides live under. */
+    engine: PricingNamedRef;
+    /** The resolved overrides (empty when the date was cleared). */
+    overrides: ResolvedPricingOverride[];
+}
+/** The result of an upsert or clear: the resolved contexts Peek returned. */
+interface UpsertOverridesResult {
+    /** One entry per activity written or cleared in the request. */
+    activityContexts: PricingActivityContext[];
+}
+
 /**
  * The clean data model for Peek Pro promo codes.
  */
@@ -1226,6 +1500,12 @@ interface BaseAccessServiceConfig {
     logger?: Logger;
     /** Custom `fetch` implementation. Default: the global `fetch`. */
     fetch?: typeof fetch;
+    /**
+     * Cross-cutting access options (PII exposure, …). When omitted, defaults are
+     * used ({@link AccessOptions.fullCustomerAccess} `false`). Threaded down to the
+     * resource services that read customer data.
+     */
+    accessOptions?: AccessOptions;
 }
 
 declare class MembershipService {
@@ -1335,7 +1615,9 @@ interface Review {
  */
 declare class ReviewService {
     private readonly client;
-    constructor(client: GraphQLClient);
+    /** Whether reviewer PII (name/email) is requested. */
+    private readonly fullCustomerAccess;
+    constructor(client: GraphQLClient, accessOptions?: AccessOptions);
     /**
      * Returns up to `reviewCount` reviews for an activity in **descending order
      * by review date (newest first)**, skipping the `reviewOffset` newest reviews
@@ -1426,6 +1708,39 @@ declare class PromoCodeService {
     create(input: CreatePromoCodeInput): Promise<CreatedPromoCode>;
 }
 
+declare class PricingService {
+    private readonly client;
+    constructor(client: GraphQLClient);
+    /**
+     * Creates a pricing engine. Store the returned id and reuse it on every
+     * subsequent override upsert. Throws on an InvalidDataError from Peek.
+     */
+    createEngine(input: CreateEngineInput): Promise<CreatedPricingEngine>;
+    /**
+     * Updates a pricing engine's name and/or activity scope. Throws on an
+     * InvalidDataError or NotFoundError from Peek.
+     */
+    updateEngine(input: UpdateEngineInput): Promise<PricingEngine>;
+    /**
+     * Deletes a pricing engine. Idempotent — resolves whether the engine existed
+     * or was already gone (Peek's NotFoundError is treated as success).
+     */
+    deleteEngine(engineId: string): Promise<void>;
+    /**
+     * Upserts pricing overrides for the engine and date range in `input`. Returns
+     * the resolved contexts Peek stored. Throws on an InvalidDataError from Peek.
+     */
+    upsertOverrides(input: UpsertOverridesInput): Promise<UpsertOverridesResult>;
+    /**
+     * Clears all overrides for the given activities across a date range. This is
+     * an upsert with empty overrides — never clear by omitting an activity.
+     */
+    clearOverrides(input: ClearOverridesInput): Promise<UpsertOverridesResult>;
+    private sendUpsert;
+    private validateUpsertInput;
+    private validateResourceOption;
+}
+
 /**
  * Platform that embedded the app for this session. Verification is
  * brand-agnostic — one peek-auth JWT is minted for every platform — so this
@@ -1506,6 +1821,7 @@ interface PeekAccessServiceConfig extends BaseAccessServiceConfig {
 declare class PeekAccessService {
     private readonly client;
     private readonly productServiceOptions;
+    private readonly accessOptions;
     private readonly jwtSecret;
     private productService?;
     private accountUserService?;
@@ -1513,6 +1829,7 @@ declare class PeekAccessService {
     private timeslotService?;
     private resellerService?;
     private promoCodeService?;
+    private pricingService?;
     private dailyNoteService?;
     private availabilityService?;
     private membershipService?;
@@ -1569,6 +1886,11 @@ declare class PeekAccessService {
      * authenticated transport. The instance is created lazily and reused.
      */
     getPromoCodeService(): PromoCodeService;
+    /**
+     * Returns the {@link PricingService} for this install, bound to the shared
+     * authenticated transport. The instance is created lazily and reused.
+     */
+    getPricingService(): PricingService;
     /**
      * Returns the {@link DailyNoteService} for this install, bound to the shared
      * authenticated transport. The instance is created lazily and reused.
@@ -1624,6 +1946,16 @@ declare class PeekAccessService {
     getAllPromoCodes(): Promise<PromoCode[]>;
     /** Create a promo code. Delegates to {@link PromoCodeService.create}. */
     createPromoCode(input: CreatePromoCodeInput): Promise<CreatedPromoCode>;
+    /** Create a pricing engine. Delegates to {@link PricingService.createEngine}. */
+    createPricingEngine(input: CreateEngineInput): Promise<CreatedPricingEngine>;
+    /** Update a pricing engine. Delegates to {@link PricingService.updateEngine}. */
+    updatePricingEngine(input: UpdateEngineInput): Promise<PricingEngine>;
+    /** Delete a pricing engine (idempotent). Delegates to {@link PricingService.deleteEngine}. */
+    deletePricingEngine(engineId: string): Promise<void>;
+    /** Upsert pricing overrides. Delegates to {@link PricingService.upsertOverrides}. */
+    upsertPricingOverrides(input: UpsertOverridesInput): Promise<UpsertOverridesResult>;
+    /** Clear pricing overrides for a set of activities. Delegates to {@link PricingService.clearOverrides}. */
+    clearPricingOverrides(input: ClearOverridesInput): Promise<UpsertOverridesResult>;
     /** Today's daily note. Delegates to {@link DailyNoteService.getToday}. */
     getDailyNoteToday(): Promise<DailyNote | null>;
     /** Update today's daily note. Delegates to {@link DailyNoteService.update}. */
@@ -2001,8 +2333,13 @@ interface Waiver {
  * Accepts the raw request body — either the `{ waiver: … }` envelope or a bare
  * waiver node, and a JSON string is parsed first. Never throws on malformed
  * input: a missing/garbled body yields a {@link Waiver} with empty fields.
+ *
+ * Because a waiver webhook has no GraphQL selection to trim (Peek delivers a
+ * fixed payload), the PII fields — the participant `guestName` and the signed
+ * document `fileUrl` — are instead redacted here at parse time when `options`
+ * does not enable PII. Pass `{ fullCustomerAccess: true }` to keep them.
  */
-declare function parseWaiverWebhook(payload: unknown): Waiver;
+declare function parseWaiverWebhook(payload: unknown, options?: AccessOptions): Waiver;
 
 /**
  * Typed errors thrown by the package. Each mirrors a failure mode of the Peek
@@ -2040,6 +2377,18 @@ declare class PeekGraphQLError extends Error {
     readonly graphqlErrors: unknown[];
     constructor(graphqlErrors: unknown[], message?: string);
 }
+/**
+ * Thrown when a payment or booking-modification operation is called on an
+ * access service that was constructed without `fullCustomerAccess` (PII access
+ * disabled). These operations — pulling payment sources, charging/refunding,
+ * creating invoice links, and adding/removing add-ons — touch customer
+ * financial data, so they are gated behind the same flag as customer PII.
+ */
+declare class PiiAccessDisabledError extends Error {
+    /** The name of the operation that was blocked (e.g. `"makePayment"`). */
+    readonly operation: string;
+    constructor(operation: string);
+}
 /**
  * Thrown when the CNG REST gateway returns a non-2xx response that is not one
  * of the specifically-handled statuses (418/429). The offending status is
@@ -2068,4 +2417,4 @@ declare class AcmeApiError extends Error {
     constructor(statusCode: number, body: unknown, message?: string);
 }
 
-export { ACTIVITY_PRODUCT_TYPE, ADD_ON_PRODUCT_TYPE, type AccountUser, AccountUserService, type AccountUserServiceOptions, AcmeAccessService, type AcmeAccessServiceConfig, type AcmeActivity, type AcmeActivityTicket, AcmeApiError, AcmeProductService, type Activity, 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, CngAccessService, type CngAccessServiceConfig, CngApiError, CngProductService, type CreateBookingGuest, type CreateBookingInput, type CreateBookingTicket, type CreatePromoCodeInput, type CreatedBooking, type CreatedPromoCode, type CustomQuestionAnswer, type DailyNote, DailyNoteService, type Duration, type Guest, type GuestMetadata, type Guide, type GuideAssignment, 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, type PeekPlatform, type Price, 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 Resource, type ResourceOptionQuantity, type ResourcePool, type ResourcePoolAccountUser, type ResourcePoolAssignment, type ResourcePoolMode, ResourcePoolService, type Review, ReviewService, type Ticket, type Timeslot, type TimeslotFilter, TimeslotService, type UpdateTimeslotResult, type Waiver, noopLogger, parseBookingWebhook, parseWaiverWebhook };
+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 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, 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 };