@peektravel/app-utilities 0.5.0 → 0.5.2

package/dist/index.d.ts

@@ -52,6 +52,247 @@ declare class GraphQLClient {
     private buildHeaders;
 }
 
+/**
+ * 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;
+    /**
+     * Human-formatted display string for the amount (e.g. `"$50.00"`), as
+     * rendered by the Peek gateway.
+     *
+     * Populated on values **read back** from the gateway (resolved overrides,
+     * product ticket price ranges). It is optional and purely informational —
+     * omit it when *building* an override input; the gateway derives it from
+     * `amount`/`currency`.
+     */
+    displayPrice?: 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, transport-agnostic data model for a Peek Pro product.
  *
@@ -59,6 +300,7 @@ declare class GraphQLClient {
  * decoupled from the underlying Peek GraphQL schema — the raw GraphQL types and
  * the conversion logic live inside the package and are never exposed here.
  */
+
 /**
  * A bookable product in a Peek Pro account.
  *
@@ -95,6 +337,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.
      *
@@ -109,6 +359,20 @@ interface ProductTicket {
     id: string;
     /** Human-readable name of the ticket / option. */
     name: string;
+    /**
+     * Lowest price this ticket can be sold at, across its price range.
+     *
+     * Populated for activity/rental resource options that expose a price range;
+     * `null` for add-on options (which carry no range) and when Peek reports none.
+     */
+    minPrice: PricingMoney | null;
+    /**
+     * Highest price this ticket can be sold at, across its price range.
+     *
+     * Populated for activity/rental resource options that expose a price range;
+     * `null` for add-on options (which carry no range) and when Peek reports none.
+     */
+    maxPrice: PricingMoney | null;
 }
 /** {@link Product.type} for standard bookable activities. */
 declare const ACTIVITY_PRODUCT_TYPE = "ACTIVITY";
@@ -1469,6 +1733,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
@@ -1557,6 +1854,7 @@ declare class PeekAccessService {
     private timeslotService?;
     private resellerService?;
     private promoCodeService?;
+    private pricingService?;
     private dailyNoteService?;
     private availabilityService?;
     private membershipService?;
@@ -1613,6 +1911,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.
@@ -1668,6 +1971,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}. */
@@ -2129,4 +2442,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 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, PiiAccessDisabledError, 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 };