@peektravel/app-utilities 0.9.2 → 0.9.4

package/dist/index.d.ts

@@ -400,7 +400,12 @@ interface ProductMeetingLocation {
 }
 /** A single bookable sub-option (resource option or add-on item option). */
 interface ProductTicket {
-    /** Unique identifier of the ticket / option. */
+    /**
+     * Unique identifier of the ticket / option. This is also the
+     * **`resourceOptionId`** — the id passed as a ticket's `resourceOptionId` when
+     * creating a booking (see {@link CreateBookingTicket}) and reported per slot by
+     * {@link AvailabilityService.getAvailabilityTimes}.
+     */
     id: string;
     /** Human-readable name of the ticket / option. */
     name: string;
@@ -748,6 +753,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. */
@@ -843,6 +853,11 @@ interface BookingTimeRangeSearch extends BookingReadOptions {
 type NoteMode = "append" | "overwrite";
 /** A requested ticket (resource option) and quantity for a new booking. */
 interface CreateBookingTicket {
+    /**
+     * The resource option to book — this is the {@link ProductTicket.id} from the
+     * activity's `tickets` (also reported per slot by
+     * {@link AvailabilityService.getAvailabilityTimes}).
+     */
     resourceOptionId: string;
     quantity: number;
 }
@@ -899,6 +914,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
@@ -953,6 +977,186 @@ 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.
+ *
+ * A human-readable, display-safe rendering of the value lives on the parent
+ * {@link MetaData.displayValue}, not here.
+ */
+type MetaDataValue = {
+    kind: "age";
+    age: number;
+} | {
+    kind: "attachment";
+    attachmentUrl: string;
+    mime: string | null;
+    name: string | null;
+    size: number | null;
+} | {
+    kind: "barcode";
+    barcodeType: MetaDataBarcodeType | null;
+    barcodeValue: string;
+} | {
+    kind: "boolean";
+    boolean: boolean;
+} | {
+    kind: "checkbox";
+    isChecked: boolean;
+} | {
+    kind: "currency";
+    currency: string;
+} | {
+    kind: "date";
+    date: string;
+} | {
+    kind: "decimal";
+    decimal: string | null;
+} | {
+    kind: "duration";
+    amount: number;
+    unit: MetaDataDurationUnit | null;
+} | {
+    kind: "email";
+    email: string | null;
+} | {
+    kind: "guest";
+    name: string | null;
+    email: string | null;
+    dateOfBirth: string | null;
+    notes: string | null;
+    waiverSigned: boolean | null;
+} | {
+    kind: "html";
+    html: string;
+} | {
+    kind: "imageUrl";
+    imageUrl: string;
+} | {
+    kind: "integer";
+    integer: number;
+} | {
+    kind: "location";
+    country: string | null;
+    county: string | null;
+    locality: string | null;
+    postalCode: string | null;
+    region: string | null;
+    streetAddress: string | null;
+} | {
+    kind: "longText";
+    longText: string;
+} | {
+    kind: "meta";
+    meta: unknown;
+} | {
+    kind: "percent";
+    percent: string | null;
+} | {
+    kind: "phone";
+    phone: string;
+} | {
+    kind: "shortText";
+    shortText: string;
+} | {
+    kind: "time";
+    time: string;
+} | {
+    kind: "url";
+    url: string | null;
+} | {
+    kind: "volume";
+    amount: string;
+    unit: MetaDataVolumeUnit | null;
+} | {
+    kind: "weight";
+    amount: string;
+    unit: MetaDataWeightUnit | null;
+};
+/** 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
+     * `integrators:<integrator>:` prefix is stripped off (e.g.
+     * `integrators: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;
+    /**
+     * A human-readable, display-safe string rendering of the value. Always
+     * present — `""` when the value is absent or of an unrecognized variant. The
+     * `html` value's rendering is HTML-escaped so it is safe to render as text.
+     */
+    displayValue: 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.
  */
@@ -1129,6 +1333,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 `integrators:<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 {
@@ -1152,6 +1362,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
@@ -1181,6 +1393,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
+     * `integrators:<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>;
     /**
@@ -1193,6 +1450,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>;
     /**
@@ -1311,6 +1582,11 @@ declare class BookingService {
      */
     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;
@@ -2146,6 +2422,7 @@ declare class PeekAccessService {
     private readonly productServiceOptions;
     private readonly accessOptions;
     private readonly jwtSecret;
+    private readonly issuer;
     private productService?;
     private accountUserService?;
     private resourcePoolService?;
@@ -2156,7 +2433,7 @@ declare class PeekAccessService {
     private dailyNoteService?;
     private availabilityService?;
     private membershipService?;
-    private bookingService?;
+    private readonly bookingServices;
     private reviewService?;
     constructor(config: PeekAccessServiceConfig);
     /**
@@ -2237,9 +2514,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.
@@ -3043,4 +3325,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, 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 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 };