@peektravel/app-utilities 0.9.1 → 0.9.3

package/dist/index.d.cts

@@ -748,6 +748,11 @@ interface Booking {
     portalUrl: string | null;
     /** Operator notes on the booking (`""` when none). */
     notes: string;
+    /**
+     * Operator-facing custom status set on the booking (via
+     * {@link BookingService.updateCustomStatus}), or `null` when none is set.
+     */
+    customStatus: string | null;
     /** Total booking value, human-formatted (e.g. `"$75.00"`). `""` if absent. */
     valueDisplay: string;
     /** Total booking value as a numeric string. `""` if absent. */
@@ -899,6 +904,15 @@ interface CreateBookingInput {
     guest: CreateBookingGuest;
     /** Operator notes to attach. */
     operatorNotes?: string;
+    /**
+     * Total list price for the booking, as a positive number string (commas
+     * allowed — `"100"`, `"1,000"`, `"10.00"`). When set, it is split evenly
+     * across the booking's tickets (each of the first n-1 tickets gets
+     * `floor(total / n)`, the last ticket the remainder) and sent per ticket in
+     * the activity's currency (falling back to `"USD"`). Omit to let Peek price
+     * the tickets from the activity's configured pricing.
+     */
+    listPrice?: string;
     /**
      * Answers to the activity's custom questions. When non-empty, the activity's
      * custom questions are fetched and each answer is validated/resolved before
@@ -914,6 +928,16 @@ interface CreateBookingInput {
      * Default: `false`.
      */
     requireRequiredQuestions?: boolean;
+    /**
+     * When `true`, a `customQuestionAnswers` entry whose `questionIdOrText` is a
+     * `cq_…` id is accepted even if that id is **not** among the activity's custom
+     * questions — the check that a question id must match the activity's list is
+     * skipped, and the answer is sent as-is (as a text answer). Entries given by
+     * question **name** are unaffected: they still must match a question, so the
+     * activity's questions are fetched only when a by-name answer (or
+     * `requireRequiredQuestions`) needs them. Default: `false`.
+     */
+    acceptAllCustomQuestionIds?: boolean;
     /** Suppress the customer confirmation email. Default: false. */
     skipCustomerEmail?: boolean;
     /** Clone the quote from an existing order. */
@@ -943,6 +967,206 @@ interface CreatedBooking {
     transactionId?: string;
 }
 
+/**
+ * The clean, transport-agnostic data model for a booking's custom-field
+ * metadata (the booking's `fieldResponses`).
+ *
+ * Each {@link MetaData} entry flattens the field definition (id/name/slug/type),
+ * its prompt (label/hint/required), and the response `refid`, and carries a
+ * single typed {@link MetaDataValue} — a discriminated union (keyed by `kind`)
+ * mirroring the gateway's `FieldResponseValue` variants, so exactly one shape is
+ * present per entry and consumers narrow on `kind`.
+ */
+/** Barcode symbology reported on a `kind: "barcode"` metadata value. */
+type MetaDataBarcodeType = "BARCODE_CODE128" | "BARCODE_CODE39" | "DATA_MATRIX" | "EAN_13" | "ITF" | "QR_CODE" | "TEXT" | "UPC";
+/** Time unit reported on a `kind: "duration"` metadata value. */
+type MetaDataDurationUnit = "SECONDS" | "MINUTES" | "HOURS" | "DAYS" | "WEEKS" | "MONTHS" | "YEARS";
+/** Mass unit reported on a `kind: "weight"` metadata value. */
+type MetaDataWeightUnit = "KILOGRAM" | "POUND" | "STONE";
+/** Volume unit reported on a `kind: "volume"` metadata value. */
+type MetaDataVolumeUnit = "GALLON";
+/**
+ * A booking custom-field response value — a discriminated union keyed by `kind`,
+ * one variant per gateway `…FieldResponseValue` type. Numeric `Int` values are
+ * `number`; `Decimal` values are kept as strings to avoid float-precision loss;
+ * `Date`/`Time` values are ISO strings.
+ *
+ * Every variant also carries a `displayValue` — a human-readable, display-safe
+ * string rendering of the value (empty when the underlying value is absent). The
+ * `html` variant's `displayValue` is HTML-escaped so it is safe to render as
+ * text.
+ */
+type MetaDataValue = {
+    kind: "age";
+    age: number;
+    displayValue: string;
+} | {
+    kind: "attachment";
+    attachmentUrl: string;
+    mime: string | null;
+    name: string | null;
+    size: number | null;
+    displayValue: string;
+} | {
+    kind: "barcode";
+    barcodeType: MetaDataBarcodeType | null;
+    barcodeValue: string;
+    displayValue: string;
+} | {
+    kind: "boolean";
+    boolean: boolean;
+    displayValue: string;
+} | {
+    kind: "checkbox";
+    isChecked: boolean;
+    displayValue: string;
+} | {
+    kind: "currency";
+    currency: string;
+    displayValue: string;
+} | {
+    kind: "date";
+    date: string;
+    displayValue: string;
+} | {
+    kind: "decimal";
+    decimal: string | null;
+    displayValue: string;
+} | {
+    kind: "duration";
+    amount: number;
+    unit: MetaDataDurationUnit | null;
+    displayValue: string;
+} | {
+    kind: "email";
+    email: string | null;
+    displayValue: string;
+} | {
+    kind: "guest";
+    name: string | null;
+    email: string | null;
+    dateOfBirth: string | null;
+    notes: string | null;
+    waiverSigned: boolean | null;
+    displayValue: string;
+} | {
+    kind: "html";
+    html: string;
+    displayValue: string;
+} | {
+    kind: "imageUrl";
+    imageUrl: string;
+    displayValue: string;
+} | {
+    kind: "integer";
+    integer: number;
+    displayValue: string;
+} | {
+    kind: "location";
+    country: string | null;
+    county: string | null;
+    locality: string | null;
+    postalCode: string | null;
+    region: string | null;
+    streetAddress: string | null;
+    displayValue: string;
+} | {
+    kind: "longText";
+    longText: string;
+    displayValue: string;
+} | {
+    kind: "meta";
+    meta: unknown;
+    displayValue: string;
+} | {
+    kind: "percent";
+    percent: string | null;
+    displayValue: string;
+} | {
+    kind: "phone";
+    phone: string;
+    displayValue: string;
+} | {
+    kind: "shortText";
+    shortText: string;
+    displayValue: string;
+} | {
+    kind: "time";
+    time: string;
+    displayValue: string;
+} | {
+    kind: "url";
+    url: string | null;
+    displayValue: string;
+} | {
+    kind: "volume";
+    amount: string;
+    unit: MetaDataVolumeUnit | null;
+    displayValue: string;
+} | {
+    kind: "weight";
+    amount: string;
+    unit: MetaDataWeightUnit | null;
+    displayValue: string;
+};
+/** A single booking custom-field response (one `fieldResponse`). */
+interface MetaData {
+    /** Field definition id. */
+    id: string;
+    /** Field name (human label). */
+    name: string;
+    /**
+     * Field slug. When an `integrator` filter is applied, the matched
+     * `integrator:<integrator>:` prefix is stripped off (e.g.
+     * `integrator:bob:booking_url` → `booking_url`).
+     */
+    slug: string;
+    /** Raw field type reported by the gateway (kept as a string). */
+    type: string;
+    /** Prompt label shown for the field, or `null` when the field has no prompt. */
+    prompt: string | null;
+    /** Prompt hint text, or `null`. */
+    promptHint: string | null;
+    /** Whether the field is required (`false` when the field has no prompt). */
+    isRequired: boolean;
+    /** The response's reference id. */
+    refid: string;
+    /**
+     * The typed response value, or `null` when absent or of an unrecognized
+     * (future) variant.
+     */
+    value: MetaDataValue | null;
+}
+/** A guest entry for `BookingService.setMetaDataGuest`. */
+interface SetMetaDataGuestInput {
+    /** Guest name (required). */
+    name: string;
+    /** Guest email (required). */
+    email: string;
+    /** Date of birth as an ISO date (e.g. `"2010-06-21"`). */
+    dateOfBirth?: string;
+    /** Whether the guest signed the waiver. */
+    waiverSigned?: boolean;
+    /** Free-text notes. */
+    notes?: string;
+}
+/** An attachment entry for `BookingService.setMetaDataAttachment`. */
+interface SetMetaDataAttachmentInput {
+    /** Display name for the attachment (required). */
+    name: string;
+    /** URL of the attachment (required). */
+    attachmentUrl: string;
+}
+/** The result of a `setMetaData…` write. */
+interface SetMetaDataResult {
+    /** Whether the gateway reported the upsert succeeded. */
+    success: boolean;
+    /** The booking id echoed back (falls back to the requested id). */
+    bookingId: string;
+    /** The gateway's success or error message (`""` when none). */
+    message: string;
+}
+
 /**
  * The clean data model for a booking's payments on file.
  */
@@ -1119,6 +1343,12 @@ interface BookingServiceOptions {
     pageSize?: number;
     /** Cross-cutting access options (PII exposure). Default: PII off. */
     accessOptions?: AccessOptions;
+    /**
+     * Integrator id used to scope `getMetaData` results — only fields whose slug
+     * starts with `integrator:<integrator>:` are returned. Defaults to `""` (set
+     * by the access service to the install's issuer).
+     */
+    integrator?: string;
 }
 /** Dependencies the {@link BookingService} composes for add-on resolution. */
 interface BookingServiceDeps {
@@ -1142,6 +1372,8 @@ declare class BookingService {
     private readonly pageSize;
     /** Whether customer PII is requested and payment operations are allowed. */
     private readonly fullCustomerAccess;
+    /** Integrator id scoping `getMetaData` results. */
+    private readonly integrator;
     constructor(client: GraphQLClient, deps: BookingServiceDeps, options?: BookingServiceOptions);
     /**
      * Throws a {@link PiiAccessDisabledError} for `operation` when this service was
@@ -1171,6 +1403,51 @@ declare class BookingService {
     searchByTimeslot(timeslotId: string, options?: BookingReadOptions): Promise<Booking[]>;
     /** Returns the guests on a booking (primary guest included). */
     getGuests(bookingId: string): Promise<Guest[]>;
+    /**
+     * Returns a booking's custom-field metadata (its `fieldResponses`), scoped to
+     * this service's integrator. Only fields whose slug starts with
+     * `integrator:<integrator>:` are returned, and that prefix is stripped from
+     * each returned `slug`. Returns `[]` when the booking is not found or has no
+     * matching fields.
+     *
+     * @example
+     * ```ts
+     * const meta = await peek.getBookingService().getMetaData("b_abc123");
+     * for (const field of meta) {
+     *   if (field.value?.kind === "url") console.log(field.slug, field.value.url);
+     * }
+     * ```
+     */
+    getMetaData(bookingId: string): Promise<MetaData[]>;
+    /**
+     * Sets the booking's `guest` metadata field. Each guest requires a `name` and
+     * `email`; `dateOfBirth`/`waiverSigned`/`notes` are optional.
+     */
+    setMetaDataGuest(bookingId: string, guests: SetMetaDataGuestInput[]): Promise<SetMetaDataResult>;
+    /**
+     * Sets the booking's `attachment` metadata field. Each attachment requires a
+     * `name` and `attachmentUrl`.
+     */
+    setMetaDataAttachment(bookingId: string, attachments: SetMetaDataAttachmentInput[]): Promise<SetMetaDataResult>;
+    /** Sets the booking's `manifest_url` metadata field. */
+    setMetaDataManifestUrl(bookingId: string, url: string): Promise<SetMetaDataResult>;
+    /** Sets the booking's `reservation_id` metadata field. */
+    setMetaDataReservationId(bookingId: string, reservationId: string): Promise<SetMetaDataResult>;
+    /** Sets the booking's `booking_status` metadata field. */
+    setMetaDataBookingStatus(bookingId: string, status: string): Promise<SetMetaDataResult>;
+    /** Sets the booking's `assigned_product` metadata field. */
+    setMetaDataAssignedProduct(bookingId: string, productName: string): Promise<SetMetaDataResult>;
+    /** Sets the booking's `assigned_employee` metadata field. */
+    setMetaDataAssignedEmployee(bookingId: string, employeeName: string): Promise<SetMetaDataResult>;
+    /** Sets the booking's `insurance_purchased` metadata field. */
+    setMetaDataInsurancePurchased(bookingId: string, insurancePurchased: boolean): Promise<SetMetaDataResult>;
+    /** Validates a non-empty `shortText` value and upserts it under `fieldName`. */
+    private setShortTextField;
+    /**
+     * Validates the booking id and upserts a single field response (scoped to this
+     * service's integrator), mapping the result union into a {@link SetMetaDataResult}.
+     */
+    private upsertFieldResponse;
     /** Returns the payments on file for a booking, or null when not found. */
     getPaymentsOnFile(bookingId: string): Promise<BookingPaymentsOnFile | null>;
     /**
@@ -1183,6 +1460,20 @@ declare class BookingService {
      * when not found.
      */
     setCheckinStatus(bookingId: string, checkedIn: boolean): Promise<Booking | null>;
+    /**
+     * Sets a booking's operator-facing custom status. Returns `true` when the
+     * gateway confirms the stored `operatorStatus` equals the requested
+     * `customStatus`, `false` otherwise.
+     *
+     * @example
+     * ```ts
+     * const ok = await peek.getBookingService().updateCustomStatus("b_abc123", "Awaiting deposit");
+     * ```
+     *
+     * @throws {Error} when `bookingId` is not a valid booking id (`b_…`/`B-…`) or
+     * when `customStatus` is not a non-empty string.
+     */
+    updateCustomStatus(bookingId: string, customStatus: string): Promise<boolean>;
     /** Cancels a booking and returns its id/displayId/status. */
     cancel(bookingId: string, notes?: string): Promise<CancelBookingResult>;
     /**
@@ -1295,10 +1586,17 @@ declare class BookingService {
      * Resolves the input's custom-question answers into the quote's
      * `questionAnswers` payload (each tagged with a fresh `refid`), or `null` when
      * none were supplied. Fetches the activity's custom questions to validate
-     * against; throws on the first unmatched/ambiguous/invalid answer.
+     * against; throws on the first unmatched/ambiguous/invalid answer. When
+     * `acceptAllCustomQuestionIds` is set the fetch is skipped if every answer is
+     * given by id (a by-name answer still needs the list to resolve).
      */
     private buildQuestionAnswers;
     private markCreatedBookingPaid;
+    /**
+     * Resolves an activity's ISO currency via the product service, falling back to
+     * {@link DEFAULT_CURRENCY} when the activity (or its currency) can't be found.
+     */
+    private resolveActivityCurrency;
     /** Finds the parent item id of an add-on by matching its option id. */
     private resolveParentItemId;
     private validatePaymentInput;
@@ -1822,6 +2120,31 @@ interface Review {
     /** Free-text review. May be null. */
     comment: string | null;
 }
+/**
+ * Aggregate review statistics for a single activity (product), as returned by
+ * {@link ReviewService.getAllReviewSummaries}. Carries no per-review detail or
+ * PII — just the rating distribution and average.
+ */
+interface ProductReviewSummary {
+    /** Activity (product) id the summary is for. */
+    productId: string;
+    /** Activity (product) name. */
+    productName: string;
+    /** Average star rating as a decimal, or `null` when there are no ratings. */
+    avgRating: number | null;
+    /** Total number of reviews. */
+    countTotal: number;
+    /** Number of 1-star reviews. */
+    countOneStar: number;
+    /** Number of 2-star reviews. */
+    countTwoStar: number;
+    /** Number of 3-star reviews. */
+    countThreeStar: number;
+    /** Number of 4-star reviews. */
+    countFourStar: number;
+    /** Number of 5-star reviews. */
+    countFiveStar: number;
+}
 
 /**
  * Reads activity reviews from the gateway, which returns them newest-first
@@ -1862,6 +2185,22 @@ declare class ReviewService {
      * ```
      */
     getReviews(productId: string, reviewCount?: number, reviewOffset?: number): Promise<Review[]>;
+    /**
+     * Returns an aggregate review summary for **every** activity — its average
+     * rating and the count of reviews at each star level. This reads the same
+     * activity list as `getAllProducts`; it carries no per-review detail or PII, so
+     * it is unaffected by `fullCustomerAccess`. An activity with no reviews comes
+     * back with a `null` `avgRating` and zero counts.
+     *
+     * @example
+     * ```ts
+     * const summaries = await peek.getReviewService().getAllReviewSummaries();
+     * for (const s of summaries) {
+     *   console.log(s.productName, s.avgRating, s.countTotal);
+     * }
+     * ```
+     */
+    getAllReviewSummaries(): Promise<ProductReviewSummary[]>;
     private validate;
 }
 
@@ -2093,6 +2432,7 @@ declare class PeekAccessService {
     private readonly productServiceOptions;
     private readonly accessOptions;
     private readonly jwtSecret;
+    private readonly issuer;
     private productService?;
     private accountUserService?;
     private resourcePoolService?;
@@ -2103,7 +2443,7 @@ declare class PeekAccessService {
     private dailyNoteService?;
     private availabilityService?;
     private membershipService?;
-    private bookingService?;
+    private readonly bookingServices;
     private reviewService?;
     constructor(config: PeekAccessServiceConfig);
     /**
@@ -2184,9 +2524,14 @@ declare class PeekAccessService {
     getMembershipService(): MembershipService;
     /**
      * Returns the {@link BookingService} for this install, bound to the shared
-     * authenticated transport. The instance is created lazily and reused.
+     * authenticated transport. Instances are created lazily and reused per
+     * `integrator`.
+     *
+     * `integrator` scopes `getMetaData` results to a custom integrator id. **Do
+     * not set it** unless Peek engineering created a custom integrator id for this
+     * integration — omit it and the correct default is used.
      */
-    getBookingService(): BookingService;
+    getBookingService(integrator?: string): BookingService;
     /**
      * Returns the {@link ReviewService} for this install, bound to the shared
      * authenticated transport. The instance is created lazily and reused.
@@ -2990,4 +3335,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, CngPermissionError, CngProductService, type CreateBookingGuest, type CreateBookingInput, type CreateBookingTicket, type CreateEngineInput, type CreatePromoCodeInput, type CreatedBooking, type CreatedPricingEngine, type CreatedPromoCode, type CustomQuestion, type CustomQuestionAnswer, type CustomQuestionAnswerInput, type CustomQuestionOption, type DailyNote, DailyNoteService, type Duration, type Guest, type GuestMetadata, type Guide, type GuideAssignment, INSTALL_STATUSES, type InstallAccessConfig, type InstallAccessService, type InstallAccessTarget, type InstallStatus, type InstallWebhook, 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, 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, createAccessServiceForInstall, noopLogger, parseBookingWebhook, parseInstallWebhook, 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, CngPermissionError, CngProductService, type CreateBookingGuest, type CreateBookingInput, type CreateBookingTicket, type CreateEngineInput, type CreatePromoCodeInput, type CreatedBooking, type CreatedPricingEngine, type CreatedPromoCode, type CustomQuestion, type CustomQuestionAnswer, type CustomQuestionAnswerInput, type CustomQuestionOption, type DailyNote, DailyNoteService, type Duration, type Guest, type GuestMetadata, type Guide, type GuideAssignment, INSTALL_STATUSES, type InstallAccessConfig, type InstallAccessService, type InstallAccessTarget, type InstallStatus, type InstallWebhook, type InstallWebhookAccount, type InstallWebhookClaims, type InvoiceLinkResult, type Logger, type MakePaymentInput, type MakePaymentResult, type Membership, type MembershipPurchaseInput, MembershipService, type MetaData, type MetaDataBarcodeType, type MetaDataDurationUnit, type MetaDataValue, type MetaDataVolumeUnit, type MetaDataWeightUnit, 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, type ProductReviewSummary, 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 SetMetaDataAttachmentInput, type SetMetaDataGuestInput, type SetMetaDataResult, type Ticket, type Timeslot, type TimeslotFilter, TimeslotService, type UpdateEngineInput, type UpdateTimeslotResult, type UpsertOverridesInput, type UpsertOverridesResult, type Waiver, createAccessServiceForInstall, noopLogger, parseBookingWebhook, parseInstallWebhook, parseWaiverWebhook, verifyInstallWebhook };