@peektravel/app-utilities 0.2.5 → 0.2.6

package/dist/index.d.cts

@@ -156,113 +156,243 @@ declare class ProductService {
 }
 
 /**
- * The clean data model for Peek Pro bookings.
+ * The clean, transport-agnostic data model for Peek Pro bookings.
+ *
+ * This is the shape consumers of the package work with. It is intentionally
+ * 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
+ * booking is the central resource: it carries the customer, the activity and
+ * slot, the ticket lines, lifecycle flags, money totals, and (optionally) the
+ * guest list and full price breakdown.
  */
-/** A ticket line within a booking. */
+/** A ticket line within a booking (one resource option and its quantity). */
 interface Ticket {
+    /** Ticket (resource option) name, e.g. `"Adult"`. Falls back to `"Unknown"`. */
     name: string;
+    /** How many of this ticket are on the booking. */
     quantity: number;
+    /** The resource option id backing this ticket. Falls back to `"unknown"`. */
     ticketId: string;
+    /**
+     * Per-unit list price of the ticket — only populated when
+     * `includePriceBreakdown` is requested.
+     */
+    listPrice?: Price;
+    /**
+     * Total value for this ticket line — only populated when
+     * `includePriceBreakdown` is requested.
+     */
+    totalValue?: Price;
 }
-/** A formatted monetary value. */
+/** A formatted monetary value: a human display string plus its raw amount. */
 interface Price {
+    /** Human-formatted amount (e.g. `"$25.00"`). */
     display: string;
+    /** Numeric amount as a string (e.g. `"25.00"`). */
     amount: string;
 }
-/** A resource used by a booking (e.g. a kayak). */
+/**
+ * A resource pool used by a booking (e.g. a kayak or guide pool), with the
+ * quantity drawn from it.
+ */
 interface Resource {
+    /** How many units of the resource the booking uses. */
     quantity: number;
+    /** Resource pool name. */
     name: string;
+    /** Resource pool short name. */
     shortName: string;
 }
-/** A concrete resource-pool assignment on a booking. */
+/**
+ * A concrete resource assigned to a booking (a specific resource within a
+ * pool, as opposed to the pool-level {@link Resource} count).
+ */
 interface ResourcePoolAssignment {
+    /** Assigned resource id. */
     id: string;
+    /** Assigned resource name. */
     name: string;
 }
-/** A custom question/answer captured on a booking or guest. */
+/**
+ * A custom question/answer captured on a booking or a guest. Location questions
+ * additionally carry a captured lat/long.
+ */
 interface CustomQuestionAnswer {
+    /** The question text as shown to the customer. */
     question: string;
+    /** The customer's answer. */
     answer: string;
+    /** Captured latitude, present only for location questions. */
     latitude?: string;
+    /** Captured longitude, present only for location questions. */
     longitude?: string;
 }
-/** A guest metadata field. */
+/** A custom field response captured against a {@link Guest}. */
 interface GuestMetadata {
+    /** Field response id. */
     id: string;
+    /** The field's name. */
     name: string;
+    /** The captured value (empty string when none). */
     value: string;
 }
-/** A guest on a booking. */
+/**
+ * A guest on a booking. Populated only when guests are requested
+ * (`includeGuests`); the primary guest is included and flagged via
+ * {@link Guest.isPrimary}.
+ */
 interface Guest {
+    /** Unique guest id. */
     id: string;
+    /** Guest name, or null. */
     name: string | null;
+    /** Guest country, or null. */
     country: string | null;
+    /** Date of birth, or null. */
     dateOfBirth: Date | null;
+    /** Phone number, or null. */
     phone: string | null;
+    /** Email address, or null. */
     email: string | null;
+    /** Whether the guest is subject to GDPR handling. */
     isGdpr: boolean;
+    /** Whether the guest is an actual participant (vs. a booker only). */
     isParticipant: boolean;
+    /** Whether this is the booking's primary guest. */
     isPrimary: boolean;
+    /** Whether the guest opted in to SMS. */
     optinSms: boolean;
+    /** Whether the guest opted in to marketing. */
     optinMarketing: boolean;
+    /** Postal code, or null. */
     postalCode: string | null;
+    /** Custom field responses captured for this guest. */
     metadata: GuestMetadata[];
 }
 /** A booking in Peek Pro. */
 interface Booking {
+    /** Stable unique booking id. */
     bookingId: string;
+    /** Human-facing display id shown in the Peek UI (e.g. `"B-123456"`). */
     displayId: string;
+    /**
+     * Normalized booking source, e.g. `"website"`, `"app"`, `"expedia"`.
+     * `"unknown"` when the origin can't be mapped.
+     */
     source: string;
+    /** Raw source app reported by Peek (e.g. `"WIDGET"`). `"unknown"` if absent. */
     sourceApp: string;
+    /**
+     * Human-readable source description (e.g. `"Website Booking Flow"`).
+     * `"unknown"` when the origin can't be mapped.
+     */
     sourceDescription: string;
+    /** Primary guest's name, or `""` when unknown. */
     customerName: string | null;
+    /** Primary guest's email, or null. */
     customerEmail: string | null;
+    /** Primary guest's phone, or null. */
     customerPhone: string | null;
+    /** The activity (product) id this booking is for. `"unknown"` if absent. */
     productId: string;
+    /** The activity (product) name. `"unknown"` if absent. */
     productName: string;
+    /** Whether the booked product is a rental (vs. a standard activity). */
     isRentalProduct: boolean;
+    /** The timeslot's legacy id, or null when the booking has no timeslot. */
     timeslotId: string | null;
+    /** Total number of tickets across all ticket lines. */
     totalTickets: number;
+    /** Human-readable ticket summary (e.g. `"2x Adult, 1x Child"`). */
     ticketDescription: string;
+    /** The individual ticket lines on the booking. */
     tickets: Ticket[];
+    /** Whether the booking has been canceled. */
     isCanceled: boolean;
+    /** Whether the booking was marked a no-show. */
     isNoShow: boolean;
+    /** Whether any guest on the booking has been checked in. */
     isCheckedIn: boolean;
+    /** Whether the booking's rental has been returned. */
     isReturned: boolean;
+    /** Purchase time in the account's local zone (ISO datetime), or null. */
     purchasedAt: string | null;
+    /** Purchase time in UTC (ISO datetime), or null. */
     purchasedAtUtc: string | null;
+    /** Activity start in the account's local zone (ISO datetime), or null. */
     startsAt: string | null;
+    /** Activity start in UTC (ISO datetime), or null. */
     startsAtUtc: string | null;
+    /** Activity end in the account's local zone (ISO datetime), or null. */
     endsAt: string | null;
+    /** Activity end in UTC (ISO datetime), or null. */
     endsAtUtc: string | null;
+    /** Activity duration in minutes (0 when start/end are unknown). */
     durationMin: number;
+    /** The availability time id for the booked slot, or null. */
     availabilityTimeId: string | null;
+    /** Customer booking-portal URL, or null. */
     portalUrl: string | null;
+    /** Operator notes on the booking (`""` when none). */
     notes: string;
+    /** Total booking value, human-formatted (e.g. `"$75.00"`). `""` if absent. */
     valueDisplay: string;
+    /** Total booking value as a numeric string. `""` if absent. */
     valueAmount: string;
+    /** Outstanding balance as a numeric string. `""` if absent. */
     outstandingBalanceAmount: string;
+    /** Outstanding balance, human-formatted. `""` if absent. */
     outstandingBalanceDisplay: string;
+    /** Redemption codes of promo codes applied to the order. */
     promoCodes: string[];
+    /** Tips left on the booking. */
     tips: Price[];
-    /** Price breakdown — only populated when `includePriceBreakdown` is requested. */
+    /**
+     * Convenience fee — only populated when `includePriceBreakdown` is requested.
+     */
     convenienceFee?: Price;
+    /** Deposit — only populated when `includePriceBreakdown` is requested. */
     deposit?: Price;
+    /** Discount — only populated when `includePriceBreakdown` is requested. */
     discount?: Price;
+    /**
+     * Price after discount — only populated when `includePriceBreakdown` is
+     * requested.
+     */
     discountedPrice?: Price;
+    /** Fees — only populated when `includePriceBreakdown` is requested. */
     fees?: Price;
+    /**
+     * Flat partner fee — only populated when `includePriceBreakdown` is requested.
+     */
     flatPartnerFee?: Price;
+    /** Base price — only populated when `includePriceBreakdown` is requested. */
     price?: Price;
+    /** Retail price — only populated when `includePriceBreakdown` is requested. */
     retailPrice?: Price;
+    /** Taxes — only populated when `includePriceBreakdown` is requested. */
     taxes?: Price;
+    /**
+     * Tips total in the breakdown — only populated when `includePriceBreakdown`
+     * is requested.
+     */
     tipsBreakdown?: Price;
+    /** Pool-level resource usage (quantity per resource pool). */
     resources: Resource[];
+    /** Concrete resources assigned to the booking. */
     resourcePoolAssignments: ResourcePoolAssignment[];
+    /** Reseller channel id, or null for a direct booking. */
     resellerId: string | null;
+    /**
+     * Reseller display name (channel name, plus `" - <agent>"` when an agent is
+     * set), or null for a direct booking.
+     */
     resellerName: string | null;
+    /** The order id this booking belongs to. `""` if absent. */
     orderId: string;
+    /** Custom question answers captured at the booking level. */
     customQuestionAnswers: CustomQuestionAnswer[];
+    /** Custom question answers captured per guest/ticket. */
     customGuestQuestionAnswers: CustomQuestionAnswer[];
     /** Guests — only populated when `includeGuests` is requested. */
     guests?: Guest[];
@@ -336,13 +466,19 @@ interface CreateBookingInput {
 }
 /** The result of creating a booking. */
 interface CreatedBooking {
+    /** The order id the new booking belongs to. */
     orderId: string;
+    /** The new booking's id. */
     bookingId: string;
+    /** The new booking's human-facing display id. */
     displayId: string;
+    /** Remaining balance as a numeric string. */
     balanceAmount: string;
+    /** 3-letter uppercase ISO currency code of the balance. */
     balanceCurrency: string;
+    /** Balance, human-formatted (e.g. `"$75.00"`). */
     balanceFormatted: string;
-    /** Set when the booking was marked paid. */
+    /** The charge transaction id — set only when the booking was marked paid. */
     transactionId?: string;
 }
 
@@ -351,13 +487,16 @@ interface CreatedBooking {
  */
 /** A single payment applied to a booking's order. */
 interface Payment {
+    /** Payment id (`pmt_…`). */
     id: string;
     /** Date the payment was applied (YYYY-MM-DD). */
     paidAt: string;
+    /** The payment's current (net of refunds) amount. */
     currentAmount: {
         amount: string;
         currency: string;
     };
+    /** How much of the payment can still be refunded. */
     refundableAmount: {
         amount: string;
         currency: string;
@@ -365,16 +504,22 @@ interface Payment {
 }
 /** A payment source on the order, with any payments made against it. */
 interface PaymentSource {
+    /** Human-readable description of the source (e.g. a card summary). */
     description: string;
+    /** Payment source id (`ps_…`, or a synthetic id like `cash/cash`). */
     id: string;
+    /** Source type reported by Peek (e.g. card/cash/custom). */
     type: string;
     /** Payments made against this source, when any exist. */
     payments?: Payment[];
 }
 /** The payments-on-file result for a booking. */
 interface BookingPaymentsOnFile {
+    /** The booking these payments belong to. */
     bookingId: string;
+    /** The order id the payments live on. */
     orderId: string;
+    /** The order's payment sources, each with its payments grouped under it. */
     paymentsOnFile: PaymentSource[];
 }
 /** Input for charging a booking. */
@@ -394,11 +539,17 @@ interface MakePaymentInput {
 }
 /** Result of charging a booking. */
 interface MakePaymentResult {
+    /** The gateway transaction id for the charge. */
     transactionId: string;
+    /** The booking that was charged. */
     bookingId: string;
+    /** The order the charge was applied to. */
     orderId: string;
+    /** Amount charged, as a numeric string. */
     amount: string;
+    /** 3-letter uppercase ISO currency code of the charge. */
     currency: string;
+    /** The payment source that was charged. */
     paymentSourceId: string;
 }
 /** Input for refunding a booking payment. */
@@ -416,17 +567,26 @@ interface RefundInput {
 }
 /** Result of refunding a booking payment. */
 interface RefundResult {
+    /** The gateway transaction id for the refund. */
     transactionId: string;
+    /** The booking that was refunded. */
     bookingId: string;
+    /** The order the refund was applied to. */
     orderId: string;
+    /** Amount refunded, as a numeric string. */
     amount: string;
+    /** 3-letter uppercase ISO currency code of the refund. */
     currency: string;
+    /** The payment that was refunded (`pmt_…`). */
     paymentId: string;
 }
 /** Result of creating an invoice link. */
 interface InvoiceLinkResult {
+    /** The booking the invoice is for. */
     bookingId: string;
+    /** The order the invoice is for. */
     orderId: string;
+    /** The customer-facing URL where the invoice can be paid. */
     invoiceLink: string;
 }
 
@@ -439,8 +599,11 @@ interface InvoiceLinkResult {
  */
 /** Money amount for an add-on line, as returned by the gateway. */
 interface BookingAddonMoney {
+    /** Numeric amount as a string (e.g. `"10.00"`). */
     amount: string;
+    /** ISO currency code (e.g. `"USD"`). */
     currency: string;
+    /** Human-formatted amount (e.g. `"$10.00"`). */
     formatted: string;
 }
 /** A single add-on option with the quantity attached to the booking. */
@@ -465,8 +628,11 @@ interface BookingAddon {
 }
 /** A booking's add-ons. */
 interface BookingAddons {
+    /** The booking id these add-ons belong to. */
     bookingId: string;
+    /** The booking's human-facing display id. */
     displayId: string;
+    /** The order id the add-ons live on. */
     orderId: string;
     /** Add-ons with at least one live option; fully-canceled add-ons are omitted. */
     addons: BookingAddon[];
@@ -568,8 +734,9 @@ declare class BookingService {
      * @throws {Error} when `paymentSourceId` is missing or not a `ps_…` id / one
      * of `cash/cash`, `custom/other`, `custom/voucher`; when `amount` is not a
      * valid number; when `currency` is not a 3-letter uppercase code; when
-     * `idempotencyKey` is empty; when `bookingId` does not resolve to a `b_…` id;
-     * when the booking or payment source is not found; or when the charge fails.
+     * `idempotencyKey` is empty; when `bookingId` is not a valid booking id
+     * (`b_…`/`B-…`); when the booking or payment source is not found; or when the
+     * charge fails.
      */
     makePayment(input: MakePaymentInput): Promise<MakePaymentResult>;
     /**
@@ -717,49 +884,71 @@ interface PurchasedMembership {
 }
 
 /**
- * The clean data model for Peek Pro activity availability times.
+ * The clean, transport-agnostic data models for Peek Pro activity availability
+ * times.
+ *
+ * `PeekAccessService.getAvailabilityTimes()` returns the bookable time slots for
+ * a given activity and date, each carrying its per-resource-option availability
+ * so callers can decide whether a requested party fits.
+ */
+/**
+ * A single bookable availability time slot for an activity.
+ *
+ * Each slot describes a start/end window on the queried date and reports how
+ * much capacity remains per resource option (see {@link Availability}).
  */
-/** A single bookable availability time slot for an activity. */
 interface AvailabilityTime {
-    /** Unique identifier. */
+    /** Stable unique identifier of the slot. */
     id: string;
-    /** Time label. */
+    /** Human-readable time label for the slot (e.g. `"10:00 AM"`). */
     time: string;
-    /** Slot start. */
+    /** Slot start as reported by Peek (ISO datetime). */
     from: string;
-    /** Slot end. */
+    /** Slot end as reported by Peek (ISO datetime). */
     end: string;
-    /** Slot duration. */
+    /** How long the slot runs (see {@link Duration}). */
     duration: Duration;
-    /** Availability status. */
+    /** Availability status reported by Peek (e.g. open/closed/sold-out). */
     status: string;
-    /** Per-resource-option availability. */
+    /**
+     * Remaining availability broken down per resource option. One entry per
+     * resource option offered for the slot.
+     */
     availability: Availability[];
 }
-/** Duration of an {@link AvailabilityTime} slot. */
+/** The length of an {@link AvailabilityTime} slot. */
 interface Duration {
+    /** Human-readable duration name (e.g. `"1 hour"`). */
     name: string;
+    /** The numeric length paired with its unit. */
     length: {
+        /** Quantity of `unit` (e.g. `60`). */
         amount: number;
+        /** Unit of `amount` (e.g. `"minutes"`). */
         unit: string;
     };
 }
 /** Availability for a specific resource option within a slot. */
 interface Availability {
+    /** Total capacity of this resource option for the slot. */
     qty: number;
+    /** How much of `qty` is already taken. */
     taken: number;
+    /** The resource option this availability is for. */
     resourceOptionId: string;
 }
 /** A requested resource-option quantity used when querying availability. */
 interface ResourceOptionQuantity {
+    /** The resource option to check. */
     resourceOptionId: string;
+    /** How many units of that option to check availability for. */
     quantity: number;
 }
 /** Query parameters for fetching availability times. */
 interface AvailabilityTimesQuery {
     /** Activity (product) id. */
     activityId: string;
-    /** Date (YYYY-MM-DD). */
+    /** Date to check (YYYY-MM-DD). */
     date: string;
     /** The resource options and quantities to check availability for. */
     resourceOptionQuantities: ResourceOptionQuantity[];