@peektravel/app-utilities 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,1272 @@
+/**
+ * Minimal structured logger interface the package can write diagnostics to.
+ *
+ * Consumers may supply their own implementation (e.g. wrapping an existing
+ * application logger). When none is provided the package stays completely
+ * silent via {@link noopLogger}.
+ */
+interface Logger {
+    info(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    error(message: string, context?: Record<string, unknown>): void;
+}
+/** A {@link Logger} that discards everything. Used as the default. */
+declare const noopLogger: Logger;
+
+/** The raw body of a GraphQL HTTP response. */
+interface GraphQLBody<T> {
+    data?: T;
+    errors?: unknown[];
+}
+interface GraphQLClientOptions {
+    /** Base URL of the backoffice GraphQL gateway (no trailing slash). */
+    baseUrl: string;
+    /** Peek app ID, used in the endpoint path. */
+    appId: string;
+    /** API gateway key sent as the `pk-api-key` header. */
+    gatewayKey: string;
+    /** Supplies a valid bearer token for each request. */
+    getToken: () => string;
+    /** Backoff delays (ms) applied on successive HTTP 429 responses. */
+    retryDelaysMs: number[];
+    /** Diagnostics sink. */
+    logger: Logger;
+    /** `fetch` implementation to use. */
+    fetchFn: typeof fetch;
+}
+declare class GraphQLClient {
+    private readonly options;
+    constructor(options: GraphQLClientOptions);
+    /**
+     * Executes a GraphQL query against the named endpoint and returns the raw
+     * response body. Retries on HTTP 429 per the configured backoff.
+     */
+    request<T>(endpointName: string, query: string, variables: object): Promise<GraphQLBody<T>>;
+    private endpoint;
+    private buildHeaders;
+}
+
+/**
+ * The clean data model for a Peek Pro account user (staff member / guide).
+ */
+/**
+ * An account user on a Peek Pro account.
+ *
+ * Only **active** users are returned by the account-user service — inactive
+ * users are filtered out — so there is no status field on this model.
+ */
+interface AccountUser {
+    /** Unique identifier of the account user. */
+    id: string;
+    /** Full name. */
+    name: string;
+    /** Email address. */
+    email: string;
+    /** Phone number. */
+    phone: string;
+    /** The activities this user is assigned to. */
+    assignedActivities: AssignedActivity[];
+}
+/** An activity an {@link AccountUser} is assigned to. */
+interface AssignedActivity {
+    /** Activity (product) id. */
+    id: string;
+    /** Activity name. */
+    name: string;
+}
+
+/** Tuning options for an {@link AccountUserService}. */
+interface AccountUserServiceOptions {
+    /** Page size for cursor pagination. Default: 50. */
+    pageSize?: number;
+}
+declare class AccountUserService {
+    private readonly client;
+    private readonly pageSize;
+    constructor(client: GraphQLClient, options?: AccountUserServiceOptions);
+    /**
+     * Returns all active account users, walking the cursor pagination to the end.
+     * Inactive users are omitted.
+     */
+    getAll(): Promise<AccountUser[]>;
+    /**
+     * Returns a single active account user by id, or `null` when no active user
+     * matches.
+     */
+    getById(userId: string): Promise<AccountUser | null>;
+}
+
+/**
+ * The clean data model for Peek Pro activity availability times.
+ */
+/** A single bookable availability time slot for an activity. */
+interface AvailabilityTime {
+    /** Unique identifier. */
+    id: string;
+    /** Time label. */
+    time: string;
+    /** Slot start. */
+    from: string;
+    /** Slot end. */
+    end: string;
+    /** Slot duration. */
+    duration: Duration;
+    /** Availability status. */
+    status: string;
+    /** Per-resource-option availability. */
+    availability: Availability[];
+}
+/** Duration of an {@link AvailabilityTime} slot. */
+interface Duration {
+    name: string;
+    length: {
+        amount: number;
+        unit: string;
+    };
+}
+/** Availability for a specific resource option within a slot. */
+interface Availability {
+    qty: number;
+    taken: number;
+    resourceOptionId: string;
+}
+/** A requested resource-option quantity used when querying availability. */
+interface ResourceOptionQuantity {
+    resourceOptionId: string;
+    quantity: number;
+}
+/** Query parameters for fetching availability times. */
+interface AvailabilityTimesQuery {
+    /** Activity (product) id. */
+    activityId: string;
+    /** Date (YYYY-MM-DD). */
+    date: string;
+    /** The resource options and quantities to check availability for. */
+    resourceOptionQuantities: ResourceOptionQuantity[];
+}
+
+declare class AvailabilityService {
+    private readonly client;
+    constructor(client: GraphQLClient);
+    /** Returns the availability times for an activity/date and requested quantities. */
+    getAvailabilityTimes(query: AvailabilityTimesQuery): Promise<AvailabilityTime[]>;
+}
+
+/**
+ * The clean, transport-agnostic data model for a Peek Pro product.
+ *
+ * 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 bookable product in a Peek Pro account.
+ *
+ * `PeekAccessService.getAllProducts()` returns a single flat list that combines
+ * two distinct Peek concepts into one uniform shape:
+ *
+ * - **Activities** — the primary bookable experiences (tours, rentals, classes,
+ *   etc.). Their {@link Product.type} is whatever Peek reports for the activity.
+ * - **Add-ons** — optional item options offered alongside activities. They are
+ *   grouped under their parent item and always carry the
+ *   {@link ADD_ON_PRODUCT_TYPE} (`"ADD-ON"`) type, so callers can tell the two
+ *   apart with a single field check.
+ */
+interface Product {
+    /**
+     * Stable unique identifier for the product.
+     *
+     * - Activities: the primary GraphQL `id` (falls back to the `legacyId`).
+     * - Add-ons: the id of the parent item the options belong to.
+     */
+    productId: string;
+    /** Human-readable display name. */
+    name: string;
+    /**
+     * Product type.
+     *
+     * For activities this is the type reported by Peek; for add-ons it is always
+     * {@link ADD_ON_PRODUCT_TYPE}.
+     */
+    type: string;
+    /**
+     * Display color as a hex string (e.g. `"#1A2B3C"`).
+     *
+     * Add-ons default to white (`"#FFFFFF"`). Empty string when no color is set.
+     */
+    color: string;
+    /**
+     * The bookable sub-options of this product.
+     *
+     * - Activities: the activity's resource options.
+     * - Add-ons: each individual item option grouped under the parent item.
+     */
+    tickets: ProductTicket[];
+}
+/** A single bookable sub-option (resource option or add-on item option). */
+interface ProductTicket {
+    /** Unique identifier of the ticket / option. */
+    id: string;
+    /** Human-readable name of the ticket / option. */
+    name: string;
+}
+/**
+ * The {@link Product.type} value assigned to add-on products.
+ *
+ * Exposed so callers can filter add-ons out of (or in to) the combined list
+ * returned by {@link Product} queries without hard-coding the string.
+ */
+declare const ADD_ON_PRODUCT_TYPE = "ADD-ON";
+
+/** Tuning options for a {@link ProductService}. */
+interface ProductServiceOptions {
+    /** Page size for cursor-paginated item options. Default: 50. */
+    itemOptionsPageSize?: number;
+}
+declare class ProductService {
+    private readonly client;
+    private readonly itemOptionsPageSize;
+    constructor(client: GraphQLClient, options?: ProductServiceOptions);
+    /**
+     * Returns every product as a single flat list: activities plus add-ons (the
+     * latter tagged with the add-on type). Add-ons are gathered across all
+     * cursor-paginated pages.
+     *
+     * @example Split activities from add-ons
+     * ```ts
+     * import { ADD_ON_PRODUCT_TYPE } from "@peektravel/app-utilities";
+     *
+     * const products = await peek.getProductService().getAllProducts();
+     * const activities = products.filter((p) => p.type !== ADD_ON_PRODUCT_TYPE);
+     * const addons = products.filter((p) => p.type === ADD_ON_PRODUCT_TYPE);
+     * ```
+     */
+    getAllProducts(): Promise<Product[]>;
+    private fetchActivities;
+    private fetchAllItemOptionNodes;
+}
+
+/**
+ * The clean data model for Peek Pro bookings.
+ */
+/** A ticket line within a booking. */
+interface Ticket {
+    name: string;
+    quantity: number;
+    ticketId: string;
+}
+/** A formatted monetary value. */
+interface Price {
+    display: string;
+    amount: string;
+}
+/** A resource used by a booking (e.g. a kayak). */
+interface Resource {
+    quantity: number;
+    name: string;
+    shortName: string;
+}
+/** A concrete resource-pool assignment on a booking. */
+interface ResourcePoolAssignment {
+    id: string;
+    name: string;
+}
+/** A custom question/answer captured on a booking or guest. */
+interface CustomQuestionAnswer {
+    question: string;
+    answer: string;
+    latitude?: string;
+    longitude?: string;
+}
+/** A guest metadata field. */
+interface GuestMetadata {
+    id: string;
+    name: string;
+    value: string;
+}
+/** A guest on a booking. */
+interface Guest {
+    id: string;
+    name: string | null;
+    country: string | null;
+    dateOfBirth: Date | null;
+    phone: string | null;
+    email: string | null;
+    isGdpr: boolean;
+    isParticipant: boolean;
+    isPrimary: boolean;
+    optinSms: boolean;
+    optinMarketing: boolean;
+    postalCode: string | null;
+    metadata: GuestMetadata[];
+}
+/** A booking in Peek Pro. */
+interface Booking {
+    bookingId: string;
+    displayId: string;
+    source: string;
+    sourceApp: string;
+    sourceDescription: string;
+    customerName: string | null;
+    customerEmail: string | null;
+    customerPhone: string | null;
+    productId: string;
+    productName: string;
+    isRentalProduct: boolean;
+    timeslotId: string | null;
+    totalTickets: number;
+    ticketDescription: string;
+    tickets: Ticket[];
+    isCanceled: boolean;
+    isNoShow: boolean;
+    isCheckedIn: boolean;
+    isReturned: boolean;
+    purchasedAt: string | null;
+    purchasedAtUtc: string | null;
+    startsAt: string | null;
+    startsAtUtc: string | null;
+    endsAt: string | null;
+    endsAtUtc: string | null;
+    durationMin: number;
+    availabilityTimeId: string | null;
+    portalUrl: string | null;
+    notes: string;
+    valueDisplay: string;
+    valueAmount: string;
+    outstandingBalanceAmount: string;
+    outstandingBalanceDisplay: string;
+    promoCodes: string[];
+    tips: Price[];
+    /** Price breakdown — only populated when `includePriceBreakdown` is requested. */
+    convenienceFee?: Price;
+    deposit?: Price;
+    discount?: Price;
+    discountedPrice?: Price;
+    fees?: Price;
+    flatPartnerFee?: Price;
+    price?: Price;
+    retailPrice?: Price;
+    taxes?: Price;
+    tipsBreakdown?: Price;
+    resources: Resource[];
+    resourcePoolAssignments: ResourcePoolAssignment[];
+    resellerId: string | null;
+    resellerName: string | null;
+    orderId: string;
+    customQuestionAnswers: CustomQuestionAnswer[];
+    customGuestQuestionAnswers: CustomQuestionAnswer[];
+    /** Guests — only populated when `includeGuests` is requested. */
+    guests?: Guest[];
+}
+/** How to interpret the start/end range when searching bookings. */
+type BookingSearchBy = "purchaseDate" | "activityDate";
+/** Options shared by booking reads. */
+interface BookingReadOptions {
+    /** Include guests in the result. */
+    includeGuests?: boolean;
+    /** Include the price breakdown fields. */
+    includePriceBreakdown?: boolean;
+}
+/** Parameters for searching bookings by a time range. */
+interface BookingTimeRangeSearch extends BookingReadOptions {
+    /** Range start (ISO datetime). */
+    start: string;
+    /** Range end (ISO datetime). */
+    end: string;
+    /** Whether the range matches purchase date or activity date. Default: purchaseDate. */
+    searchBy?: BookingSearchBy;
+    /** Restrict to a product/activity id. */
+    productId?: string;
+    /** Filter by primary guest email. */
+    email?: string;
+    /** Free-text search string. */
+    searchString?: string;
+}
+/** How an appended note should be applied. */
+type NoteMode = "append" | "overwrite";
+/** A requested ticket (resource option) and quantity for a new booking. */
+interface CreateBookingTicket {
+    resourceOptionId: string;
+    quantity: number;
+}
+/** Guest details for a new booking. */
+interface CreateBookingGuest {
+    name: string;
+    email?: string;
+    phone?: string;
+    postalCode?: string;
+    country?: string;
+    optinMarketing?: boolean;
+    optinSms?: boolean;
+}
+/**
+ * Input for creating a booking. IDs must already be resolved — the package does
+ * not do free-text product/ticket/time matching (that stays in the caller).
+ */
+interface CreateBookingInput {
+    /** Activity (product) id. */
+    activityId: string;
+    /** Availability time id for the slot. */
+    availabilityTimeId: string;
+    /** Tickets to book (each expanded to `quantity` seats). */
+    tickets: CreateBookingTicket[];
+    /** Primary guest. */
+    guest: CreateBookingGuest;
+    /** Operator notes to attach. */
+    operatorNotes?: string;
+    /** Suppress the customer confirmation email. Default: false. */
+    skipCustomerEmail?: boolean;
+    /** Clone the quote from an existing order. */
+    parentOrderId?: string | null;
+    /** Mark the booking paid after creation (requires `idempotencyKey`). */
+    markAsPaid?: boolean;
+    /** Partial payment amount when marking paid; defaults to the full balance. */
+    markAsPaidAmount?: string;
+    /** Idempotency key for the mark-paid charge. */
+    idempotencyKey?: string;
+}
+/** The result of creating a booking. */
+interface CreatedBooking {
+    orderId: string;
+    bookingId: string;
+    displayId: string;
+    balanceAmount: string;
+    balanceCurrency: string;
+    balanceFormatted: string;
+    /** Set when the booking was marked paid. */
+    transactionId?: string;
+}
+
+/**
+ * The clean data model for a booking's payments on file.
+ */
+/** A single payment applied to a booking's order. */
+interface Payment {
+    id: string;
+    /** Date the payment was applied (YYYY-MM-DD). */
+    paidAt: string;
+    currentAmount: {
+        amount: string;
+        currency: string;
+    };
+    refundableAmount: {
+        amount: string;
+        currency: string;
+    };
+}
+/** A payment source on the order, with any payments made against it. */
+interface PaymentSource {
+    description: string;
+    id: string;
+    type: string;
+    /** Payments made against this source, when any exist. */
+    payments?: Payment[];
+}
+/** The payments-on-file result for a booking. */
+interface BookingPaymentsOnFile {
+    bookingId: string;
+    orderId: string;
+    paymentsOnFile: PaymentSource[];
+}
+/** Input for charging a booking. */
+interface MakePaymentInput {
+    /** Booking id (normalized internally). */
+    bookingId: string;
+    /** Payment source id (`ps_…`, or one of `cash/cash`, `custom/other`, `custom/voucher`). */
+    paymentSourceId: string;
+    /** Amount as a numeric string. */
+    amount: string;
+    /** 3-letter uppercase ISO currency code. */
+    currency: string;
+    /** Idempotency key passed through to Peek. */
+    idempotencyKey: string;
+    /** Optional message appended to the default customer message. */
+    customerMessage?: string;
+}
+/** Result of charging a booking. */
+interface MakePaymentResult {
+    transactionId: string;
+    bookingId: string;
+    orderId: string;
+    amount: string;
+    currency: string;
+    paymentSourceId: string;
+}
+/** Input for refunding a booking payment. */
+interface RefundInput {
+    /** Booking id (normalized internally). */
+    bookingId: string;
+    /** Payment id to refund (`pmt_…`). */
+    paymentId: string;
+    /** Amount as a numeric string. */
+    amount: string;
+    /** 3-letter uppercase ISO currency code. */
+    currency: string;
+    /** Idempotency key passed through to Peek. */
+    idempotencyKey: string;
+}
+/** Result of refunding a booking payment. */
+interface RefundResult {
+    transactionId: string;
+    bookingId: string;
+    orderId: string;
+    amount: string;
+    currency: string;
+    paymentId: string;
+}
+/** Result of creating an invoice link. */
+interface InvoiceLinkResult {
+    bookingId: string;
+    orderId: string;
+    invoiceLink: string;
+}
+
+/**
+ * Clean, public data models for a booking's add-ons.
+ *
+ * These are the only add-on shapes a consumer sees. The detailed per-option
+ * model used to build add/cancel mutations (refids, reservation statuses) is
+ * an internal implementation detail and is intentionally not exported.
+ */
+/** Money amount for an add-on line, as returned by the gateway. */
+interface BookingAddonMoney {
+    amount: string;
+    currency: string;
+    formatted: string;
+}
+/** A single add-on option with the quantity attached to the booking. */
+interface BookingAddonOption {
+    /** The item option id (`itemOptionSnapshot.id`). */
+    addonOptionId: string;
+    /** The item option name (`itemOptionSnapshot.name`). */
+    addonOptionName: string;
+    /** How many live (non-canceled) units of this option are on the booking. */
+    quantity: number;
+}
+/** An add-on attached to a booking, grouped by add-on item. */
+interface BookingAddon {
+    /** The add-on item id (`itemSnapshot.id`). */
+    addonId: string;
+    /** The add-on item name (`itemSnapshot.name`). */
+    addonName: string;
+    /** The booking line-item total for this add-on, when present. */
+    total: BookingAddonMoney | null;
+    /** Live options on this add-on, combined by option id with a count. */
+    addonOptions: BookingAddonOption[];
+}
+/** A booking's add-ons. */
+interface BookingAddons {
+    bookingId: string;
+    displayId: string;
+    orderId: string;
+    /** Add-ons with at least one live option; fully-canceled add-ons are omitted. */
+    addons: BookingAddon[];
+}
+/**
+ * Result of an add-on mutation (add or remove). Both operations finish by
+ * re-listing the booking's add-ons and returning the post-change state rather
+ * than echoing quote details.
+ */
+interface BookingAddonsMutationResult {
+    updatedBookingAddons: BookingAddons;
+}
+
+/** Result of cancelling a booking. */
+interface CancelBookingResult {
+    id: string;
+    displayId: string;
+    reservationStatus: string;
+}
+/** Tuning options for a {@link BookingService}. */
+interface BookingServiceOptions {
+    /** Page size for cursor pagination. Default: 50. */
+    pageSize?: number;
+}
+/** Dependencies the {@link BookingService} composes for add-on resolution. */
+interface BookingServiceDeps {
+    productService: ProductService;
+}
+/** Input for adding or removing an add-on on a booking. */
+interface AddAddonInput {
+    /** The add-on (item option) id. */
+    addonOptionId?: string;
+    /**
+     * @deprecated Use `addonOptionId`. Still accepted for backwards
+     * compatibility; treated as `addonOptionId` when `addonOptionId` is absent.
+     */
+    addonId?: string;
+    /** Quantity as a positive integer string. */
+    quantity: string;
+}
+declare class BookingService {
+    private readonly client;
+    private readonly deps;
+    private readonly pageSize;
+    constructor(client: GraphQLClient, deps: BookingServiceDeps, options?: BookingServiceOptions);
+    /**
+     * Returns a single booking by id, or null when not found. The `bookingId` is
+     * normalized internally (lowercased, `-` → `_`), so `B-ABC123` and `b_abc123`
+     * resolve to the same booking.
+     *
+     * @example
+     * ```ts
+     * const bookings = peek.getBookingService();
+     * const booking = await bookings.getById("b_abc123", {
+     *   includeGuests: true,
+     *   includePriceBreakdown: true,
+     * });
+     * if (booking) console.log(booking.displayId, booking.outstandingBalanceAmount);
+     * ```
+     */
+    getById(bookingId: string, options?: BookingReadOptions): Promise<Booking | null>;
+    /** Returns all bookings matching a time range (paginated). */
+    searchByTimeRange(input: BookingTimeRangeSearch): Promise<Booking[]>;
+    /** Returns all bookings on a timeslot (paginated). */
+    searchByTimeslot(timeslotId: string, options?: BookingReadOptions): Promise<Booking[]>;
+    /** Returns the guests on a booking (primary guest included). */
+    getGuests(bookingId: string): Promise<Guest[]>;
+    /** Returns the payments on file for a booking, or null when not found. */
+    getPaymentsOnFile(bookingId: string): Promise<BookingPaymentsOnFile | null>;
+    /**
+     * Appends to (or overwrites) a booking's operator notes. Returns the updated
+     * booking, or null when the booking is not found.
+     */
+    appendNote(bookingId: string, note: string, mode?: NoteMode): Promise<Booking | null>;
+    /**
+     * Sets a booking's check-in status. Returns the refreshed booking, or null
+     * when not found.
+     */
+    setCheckinStatus(bookingId: string, checkedIn: boolean): Promise<Booking | null>;
+    /** Cancels a booking and returns its id/displayId/status. */
+    cancel(bookingId: string, notes?: string): Promise<CancelBookingResult>;
+    /**
+     * Charges a booking. Validates input, resolves the order + payment source via
+     * payments-on-file, then applies the payment. The `idempotencyKey` is passed
+     * through to Peek.
+     *
+     * @example
+     * ```ts
+     * const result = await peek.getBookingService().makePayment({
+     *   bookingId: "b_abc123",
+     *   paymentSourceId: "custom/other", // or a "ps_…" source on file
+     *   amount: "25.00",
+     *   currency: "USD",
+     *   idempotencyKey: crypto.randomUUID(),
+     * });
+     * console.log(result.transactionId);
+     * ```
+     *
+     * @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.
+     */
+    makePayment(input: MakePaymentInput): Promise<MakePaymentResult>;
+    /**
+     * Refunds a booking payment. Validates input, resolves the order + payment via
+     * payments-on-file, then applies the refund.
+     */
+    refund(input: RefundInput): Promise<RefundResult>;
+    /** Creates an invoice link for a booking's order. */
+    createInvoiceLink(bookingId: string): Promise<InvoiceLinkResult>;
+    /** Returns the add-ons on a booking, grouped by add-on item (clean model). */
+    listAddons(bookingId: string): Promise<BookingAddons>;
+    /**
+     * Adds an add-on to a booking via createQuoteFromOrder → updateQuoteV2 →
+     * amendOrder. Lists the booking's add-ons first to derive the order id and
+     * reuse an existing add-on refid; resolves the add-on's parent item via the
+     * product service. Returns the booking's add-ons after the change.
+     *
+     * `quantity` is a **positive-integer string** ("1", "2", …); one add-on
+     * itemOption is created per unit. `addonOptionId` is the add-on's item-option
+     * id (a ticket id on an `ADD_ON_PRODUCT_TYPE` product from
+     * {@link ProductService.getAllProducts}).
+     *
+     * @example
+     * ```ts
+     * const result = await peek.getBookingService().addAddon("b_abc123", {
+     *   addonOptionId: "io_helmet",
+     *   quantity: "2",
+     * });
+     * console.log(result.updatedBookingAddons.addons);
+     * ```
+     *
+     * @throws {Error} when `addonOptionId` is missing, `quantity` is not a
+     * positive-integer string, the add-on is not found on any product, or any of
+     * the underlying quote/order mutations fail.
+     */
+    addAddon(bookingId: string, input: AddAddonInput): Promise<BookingAddonsMutationResult>;
+    /**
+     * Removes (cancels) add-on options from a booking. Lists the booking's
+     * add-ons first to get the order id and the existing item/option refids, then
+     * issues the same three mutations as {@link addAddon} but with cancellation
+     * variables. Returns the booking's add-ons after the change.
+     */
+    removeAddon(bookingId: string, input: AddAddonInput): Promise<BookingAddonsMutationResult>;
+    /**
+     * Runs the sales add-ons query for a booking, validates that exactly one
+     * booking matched, and parses the node into the internal model.
+     */
+    private fetchBookingSale;
+    /**
+     * Runs `createQuoteFromOrder` and validates the response, returning the new
+     * quote id and the first sale quote refid (empty string when absent).
+     */
+    private createQuoteFromOrderOrThrow;
+    /** Runs `updateQuoteV2` with the given quoteInput and validates the response. */
+    private updateQuoteOrThrow;
+    /** Runs `amendOrder` and validates the response. */
+    private amendOrderOrThrow;
+    /**
+     * Creates a booking via createQuoteV2 → createOrderFromQuote, optionally
+     * marking it paid. IDs must be pre-resolved (no free-text matching) — resolve
+     * `activityId` + ticket `resourceOptionId`s from {@link ProductService} and
+     * `availabilityTimeId` from {@link AvailabilityService.getAvailabilityTimes}.
+     *
+     * @example
+     * ```ts
+     * const created = await peek.getBookingService().create({
+     *   activityId: "a_kayak_tour",
+     *   availabilityTimeId: "at_2026_06_20_0900",
+     *   tickets: [{ resourceOptionId: "ro_adult", quantity: 2 }],
+     *   guest: { name: "Sam Rivera", email: "sam@example.com" },
+     *   markAsPaid: true,
+     *   idempotencyKey: crypto.randomUUID(),
+     * });
+     * console.log(created.bookingId, created.displayId, created.balanceFormatted);
+     * ```
+     *
+     * @throws {Error} when `activityId`, `availabilityTimeId`, a ticket
+     * `resourceOptionId`/positive `quantity`, or the guest `name` is missing; when
+     * `markAsPaid` is set without an `idempotencyKey`; or when the quote/order
+     * mutations fail.
+     */
+    create(input: CreateBookingInput): Promise<CreatedBooking>;
+    private markCreatedBookingPaid;
+    /** Finds the parent item id of an add-on by matching its option id. */
+    private resolveParentItemId;
+    private validatePaymentInput;
+    private validateRefundInput;
+    private fetchPaginated;
+}
+
+/**
+ * The clean data model for a Peek Pro daily (dashboard) note.
+ */
+/** The daily note shown on the Peek Pro dashboard. */
+interface DailyNote {
+    /** The note text. */
+    note: string;
+}
+
+declare class DailyNoteService {
+    private readonly client;
+    constructor(client: GraphQLClient);
+    /** Returns today's daily note, or null when none is set. */
+    getToday(): Promise<DailyNote | null>;
+    /** Upserts the daily note and returns the saved note, or null. */
+    update(note: string): Promise<DailyNote | null>;
+}
+
+/**
+ * The clean data model for Peek Pro memberships.
+ */
+/**
+ * A flat representation of a Peek Pro membership variant.
+ *
+ * A membership can expose multiple variants; this model flattens each variant
+ * into its own record, carrying the parent membership's stable id and display
+ * name alongside the variant-level details. Memberships with no variants
+ * produce no records.
+ */
+interface Membership {
+    /** Parent membership id. */
+    id: string;
+    /** Variant id. */
+    membershipVariantId: string;
+    /** Variant description, or null. */
+    description: string | null;
+    /** Variant external (customer-facing) name. */
+    externalName: string;
+    /** Variant image URL, or null. */
+    imageUrl: string | null;
+    /** Variant internal name. */
+    internalName: string;
+    /** Parent membership display name. */
+    displayName: string;
+}
+/** Input for purchasing a membership. */
+interface MembershipPurchaseInput {
+    /** The membership variant to purchase. */
+    membershipVariantId: string;
+    /** Member email (required). */
+    email: string;
+    /** ISO country code (optional). */
+    country?: string;
+    /** Formatted address (optional). */
+    formattedAddress?: string;
+    /** Membership code (optional). */
+    membershipCode?: string;
+    /** Member phone (optional). */
+    phone?: string;
+    /** Member name (optional). */
+    name?: string;
+}
+/** The result of purchasing a membership. */
+interface PurchasedMembership {
+    orderId: string;
+    membershipId: string;
+    displayId: string;
+    primaryMemberId: string | null;
+    primaryMemberName: string | null;
+    balanceAmount: string;
+    balanceCurrency: string;
+    balanceFormatted: string;
+}
+
+declare class MembershipService {
+    private readonly client;
+    constructor(client: GraphQLClient);
+    /** Returns all membership variants, flattened into {@link Membership} records. */
+    getAll(): Promise<Membership[]>;
+    /**
+     * Purchases a membership via the two-step quote → order flow. Throws on
+     * invalid input or when Peek returns errors.
+     */
+    purchase(input: MembershipPurchaseInput): Promise<PurchasedMembership>;
+}
+
+/**
+ * The clean data model for Peek Pro reseller channels and their agents.
+ */
+/** A reseller channel on a Peek Pro account. */
+interface Channel {
+    /** Unique identifier. */
+    id: string;
+    /** Channel name. */
+    name: string;
+    /** Free-text notes, or null. */
+    notes: string | null;
+    /** Pricing model reported by Peek. */
+    pricingModel: string;
+    /** Channel state (e.g. active/inactive). */
+    state: string;
+    /** Channel type. */
+    type: string;
+    /** Agents belonging to this channel. */
+    agents: Agent[];
+}
+/** An agent (contact) belonging to a {@link Channel}. */
+interface Agent {
+    /** Email address, or null. */
+    email: string | null;
+    /** Agent name. */
+    name: string;
+    /** Internal notes, or null. */
+    internalNotes: string | null;
+    /** Phone number, or null. */
+    phone: string | null;
+}
+
+declare class ResellerService {
+    private readonly client;
+    constructor(client: GraphQLClient);
+    /**
+     * Returns all reseller channels, each with up to `agentsPerChannel` agents
+     * (default 10).
+     */
+    getAllChannels(agentsPerChannel?: number): Promise<Channel[]>;
+}
+
+/**
+ * The clean data model for a Peek Pro resource pool (e.g. guides, equipment).
+ */
+/** Filter mode for which resource pools to return. */
+type ResourcePoolMode = "ACTIVITY" | "ALL";
+/** A resource pool on a Peek Pro account. */
+interface ResourcePool {
+    /** Unique identifier. */
+    id: string;
+    /** Display name. */
+    name: string;
+    /** Image URL, or null. */
+    imageUrl: string | null;
+    /** Allocation mode reported by Peek. */
+    mode: string;
+    /** Display color as a hex string, or null. */
+    colorHex: string | null;
+    /** Configured quantity, or null when not set. */
+    quantity: number | null;
+    /** Category (e.g. `"guide"`). */
+    category: string;
+    /** Capacity, or null when not set. */
+    capacity: number | null;
+    /** How the resource is tracked, or null. */
+    resourceTrackingMode: string | null;
+    /** The account user backing this pool (e.g. for guides), or null. */
+    accountUser: ResourcePoolAccountUser | null;
+}
+/** Minimal account-user reference attached to a {@link ResourcePool}. */
+interface ResourcePoolAccountUser {
+    id: string;
+    name: string;
+}
+
+declare class ResourcePoolService {
+    private readonly client;
+    constructor(client: GraphQLClient);
+    /**
+     * Returns all resource pools for the given mode filter (defaults to `"ALL"`).
+     */
+    getAll(mode?: ResourcePoolMode): Promise<ResourcePool[]>;
+}
+
+/**
+ * The clean data model for Peek Pro timeslots and timeslot operations.
+ */
+/** A bookable timeslot for an activity. */
+interface Timeslot {
+    /** Unique identifier. */
+    id: string;
+    /** The activity (product) id this timeslot belongs to. */
+    productId: string;
+    /** Total capacity of the timeslot. */
+    totalCapacity: number;
+    /** Remaining available capacity. */
+    availableCapacity: number;
+    /** Maximum party size per booking. */
+    maxPartySize: number;
+    /** Number of bookings on the timeslot. */
+    bookingCount: number;
+    /** Number of checked-in guests. */
+    checkedInCount: number;
+    /** Status reported by Peek (e.g. open/closed). */
+    status: string;
+    /** Manifest notes, or null. */
+    notes: string | null;
+    /** Duration in minutes. */
+    durationMin: number;
+    /** Date (YYYY-MM-DD). */
+    date: string;
+    /** Start time, or null. */
+    startTime: string | null;
+    /** Resources (e.g. guides, equipment) allocated to this timeslot. */
+    assignedResources: AssignedResource[];
+}
+/** A resource allocated to a {@link Timeslot}. */
+interface AssignedResource {
+    /** Resource pool id. */
+    id: string;
+    /** Resource pool name. */
+    name: string;
+    /** Resource pool capacity. */
+    capacity: number;
+    /** Resource pool category (e.g. `"guide"`). */
+    category: string;
+    /** Allocated quantity. */
+    quantity: number;
+    /** Backing account user id, or null. */
+    accountUserId: string | null;
+}
+/** Booking filter for {@link Timeslot} day queries. */
+type TimeslotFilter = "all" | "withBookings" | "withoutBookings";
+/** Result of a timeslot update (set availability / notes). */
+interface UpdateTimeslotResult {
+    manifestNotes: string | null;
+    status: string | null;
+}
+/** Input describing a guide (un)assignment across timeslots. */
+interface GuideAssignment {
+    /** Timeslots to (un)assign. */
+    timeslotIds: string[];
+    /** Guides to (un)assign — matched by resource-pool id, account-user id, or name. */
+    guideIds: string[];
+    /** Whether to assign or unassign. */
+    action: "assign" | "unassign";
+}
+/** Result of a guide (un)assignment request. */
+interface AssignGuideResult {
+    status: "success" | "error";
+    /** The created allocation request id on success, else null. */
+    resourceAllocationRequestId: string | null;
+    /** Error details on failure, else null. */
+    errors: Array<{
+        message: string;
+    }> | null;
+}
+
+/**
+ * Timeslot operations against the Peek gateway.
+ *
+ * Obtain an instance via {@link PeekAccessService.getTimeslotService}. The
+ * `assignGuide` operation composes the resource-pool and account-user services
+ * to resolve guides before issuing the allocation request.
+ */
+
+/** Dependencies the {@link TimeslotService} composes for guide assignment. */
+interface TimeslotServiceDeps {
+    resourcePoolService: ResourcePoolService;
+    accountUserService: AccountUserService;
+}
+declare class TimeslotService {
+    private readonly client;
+    private readonly deps;
+    constructor(client: GraphQLClient, deps: TimeslotServiceDeps);
+    /** Returns the timeslots for an activity on a given date. */
+    getForDay(productId: string, date: string, filter?: TimeslotFilter): Promise<Timeslot[]>;
+    /** Returns a single timeslot by id, or null when not found. */
+    getById(timeslotId: string): Promise<Timeslot | null>;
+    /** Sets the timeslot's status (e.g. open/closed). */
+    setAvailability(timeslotId: string, status: string): Promise<UpdateTimeslotResult>;
+    /** Sets the timeslot's manifest notes. */
+    setNotes(timeslotId: string, manifestNotes: string): Promise<UpdateTimeslotResult>;
+    /**
+     * Assigns or unassigns guides across timeslots. Guides are resolved to
+     * resource pools (by pool id, account-user id, or name) before the bulk
+     * allocation request is issued.
+     *
+     * @example
+     * ```ts
+     * await peek.getTimeslotService().assignGuide({
+     *   timeslotIds: ["ts_2026_06_20_0900"],
+     *   guideIds: ["Alex Guide"], // pool id, account-user id, or name
+     *   action: "assign",
+     * });
+     * ```
+     */
+    assignGuide(assignment: GuideAssignment): Promise<AssignGuideResult>;
+    private updateTimeslot;
+}
+
+/**
+ * The clean data model for Peek Pro promo codes.
+ */
+/** A promo code on a Peek Pro account. */
+interface PromoCode {
+    /** Unique identifier. */
+    id: string;
+    /** Display name. */
+    name: string;
+    /** Percentage discount (0–100), or null for a fixed-amount code. */
+    percentAmount: number | null;
+    /** Whether the discount applies per ticket. */
+    perTicketDiscount: boolean;
+    /** The code guests redeem. */
+    redemptionCode: string;
+    /** Fixed-amount discount, or null for a percentage code. */
+    fixedAmount: PromoCodeFixedAmount | null;
+}
+/** A fixed monetary discount on a {@link PromoCode}. */
+interface PromoCodeFixedAmount {
+    /** Amount in the currency's minor/major unit as reported by Peek. */
+    amount: number;
+    /** ISO currency code. */
+    currency: string;
+    /** Human-formatted amount (e.g. `"$10.00"`). */
+    formatted: string;
+}
+/** Input for creating a promo code. */
+interface CreatePromoCodeInput {
+    /** Display name. */
+    name: string;
+    /** The redemption code. */
+    code: string;
+    /** Discount amount as a string (percentage or fixed value). */
+    amount: string;
+    /** Whether `amount` is a percentage or a fixed monetary value. */
+    discountType: "percent" | "fixed";
+    /** Optional cap on total redemptions. */
+    maxRedemptions?: number;
+    /** ISO currency code for fixed discounts. Defaults to `"USD"`. */
+    currency?: string;
+}
+/** The result of creating a promo code (the mutation returns id + name). */
+interface CreatedPromoCode {
+    id: string;
+    name: string;
+}
+
+/** Tuning options for a {@link PromoCodeService}. */
+interface PromoCodeServiceOptions {
+    /** Page size for cursor pagination. Default: 50. */
+    pageSize?: number;
+}
+declare class PromoCodeService {
+    private readonly client;
+    private readonly pageSize;
+    constructor(client: GraphQLClient, options?: PromoCodeServiceOptions);
+    /** Returns all promo codes, walking the cursor pagination to the end. */
+    getAll(): Promise<PromoCode[]>;
+    /**
+     * Creates a promo code. Throws on invalid input or when Peek returns an
+     * InvalidDataError.
+     */
+    create(input: CreatePromoCodeInput): Promise<CreatedPromoCode>;
+}
+
+/**
+ * Authenticated root entry point to the Peek backoffice GraphQL gateway.
+ *
+ * Configure one instance per install with everything needed to authenticate and
+ * reach the gateway. The access service owns the shared, authenticated
+ * transport (it mints and caches tokens on demand) and hands out per-resource
+ * service objects — e.g. {@link PeekAccessService.getProductService} — that
+ * carry the resource-specific business logic.
+ */
+
+/** Configuration for a {@link PeekAccessService} instance. */
+interface PeekAccessServiceConfig {
+    /** Peek install ID. Becomes the JWT subject. */
+    installId: string;
+    /** HMAC secret used to sign the JWT (the Peek internal secret). */
+    jwtSecret: string;
+    /** JWT issuer — the app name. */
+    issuer: string;
+    /** Peek app ID, used in the gateway endpoint path. */
+    appId: string;
+    /** API gateway key, sent as the `pk-api-key` header. */
+    gatewayKey: string;
+    /** Override the gateway base URL. Default: Peek production gateway. */
+    baseUrl?: string;
+    /** JWT lifetime in seconds. Default: 3600. */
+    tokenTtlSeconds?: number;
+    /** Re-mint the cached token this many seconds before expiry. Default: 60. */
+    tokenRefreshLeewaySeconds?: number;
+    /** Backoff delays (ms) for HTTP 429 retries. Default: [1000, 2000, 4000]. */
+    retryDelaysMs?: number[];
+    /** Optional logger. Default: no-op (silent). */
+    logger?: Logger;
+    /** Custom `fetch` implementation. Default: the global `fetch`. */
+    fetch?: typeof fetch;
+    /** Page size for cursor-paginated item options. Default: 50. */
+    itemOptionsPageSize?: number;
+}
+/**
+ * Authenticated root entry point to the Peek backoffice GraphQL gateway.
+ *
+ * Construct one instance per install, then call the `get<Resource>Service()`
+ * accessors to reach the resource-specific operations. Each accessor returns a
+ * memoized service bound to the shared, authenticated transport — the access
+ * service mints and caches a short-lived JWT on demand.
+ *
+ * @example Configure once, then call resource services
+ * ```ts
+ * import { PeekAccessService, type Product } from "@peektravel/app-utilities";
+ *
+ * const peek = new PeekAccessService({
+ *   installId: "install-123",            // JWT subject
+ *   jwtSecret: process.env.PEEK_INTERNAL_SECRET!, // signs the JWT
+ *   issuer: process.env.APP_NAME!,        // JWT issuer
+ *   appId: process.env.PEEK_APP_ID!,      // gateway path segment
+ *   gatewayKey: process.env.PEEK_GATEWAY_KEY!, // pk-api-key header
+ * });
+ *
+ * const products: Product[] = await peek.getProductService().getAllProducts();
+ * const booking = await peek.getBookingService().getById("b_abc123");
+ * ```
+ *
+ * @throws {Error} from the constructor when any required config field
+ * (`installId`, `jwtSecret`, `issuer`, `appId`, `gatewayKey`) is empty.
+ */
+declare class PeekAccessService {
+    private readonly client;
+    private readonly productServiceOptions;
+    private productService?;
+    private accountUserService?;
+    private resourcePoolService?;
+    private timeslotService?;
+    private resellerService?;
+    private promoCodeService?;
+    private dailyNoteService?;
+    private availabilityService?;
+    private membershipService?;
+    private bookingService?;
+    constructor(config: PeekAccessServiceConfig);
+    /**
+     * Returns the {@link ProductService} for this install, bound to the shared
+     * authenticated transport. The instance is created lazily and reused.
+     */
+    getProductService(): ProductService;
+    /**
+     * Returns the {@link AccountUserService} for this install, bound to the shared
+     * authenticated transport. The instance is created lazily and reused.
+     */
+    getAccountUserService(): AccountUserService;
+    /**
+     * Returns the {@link ResourcePoolService} for this install, bound to the
+     * shared authenticated transport. The instance is created lazily and reused.
+     */
+    getResourcePoolService(): ResourcePoolService;
+    /**
+     * Returns the {@link TimeslotService} for this install, bound to the shared
+     * authenticated transport. The instance is created lazily and reused; its
+     * guide assignment composes the resource-pool and account-user services.
+     */
+    getTimeslotService(): TimeslotService;
+    /**
+     * Returns the {@link ResellerService} for this install, bound to the shared
+     * authenticated transport. The instance is created lazily and reused.
+     */
+    getResellerService(): ResellerService;
+    /**
+     * Returns the {@link PromoCodeService} for this install, bound to the shared
+     * authenticated transport. The instance is created lazily and reused.
+     */
+    getPromoCodeService(): PromoCodeService;
+    /**
+     * Returns the {@link DailyNoteService} for this install, bound to the shared
+     * authenticated transport. The instance is created lazily and reused.
+     */
+    getDailyNoteService(): DailyNoteService;
+    /**
+     * Returns the {@link AvailabilityService} for this install, bound to the
+     * shared authenticated transport. The instance is created lazily and reused.
+     */
+    getAvailabilityService(): AvailabilityService;
+    /**
+     * Returns the {@link MembershipService} for this install, bound to the shared
+     * authenticated transport. The instance is created lazily and reused.
+     */
+    getMembershipService(): MembershipService;
+    /**
+     * Returns the {@link BookingService} for this install, bound to the shared
+     * authenticated transport. The instance is created lazily and reused.
+     */
+    getBookingService(): BookingService;
+}
+
+/**
+ * Typed errors thrown by the package. Each mirrors a failure mode of the Peek
+ * GraphQL gateway so callers can branch on the error type rather than parsing
+ * messages.
+ */
+/**
+ * Thrown when the gateway responds with HTTP 418, indicating the install is not
+ * permitted to perform the request because an admin account is required.
+ */
+declare class AdminAccountRequiredError extends Error {
+    /** The HTTP status that triggered this error. */
+    readonly statusCode = 418;
+    constructor(message?: string);
+}
+/**
+ * Thrown when the gateway responds with HTTP 429 and all configured retries
+ * have been exhausted.
+ */
+declare class RateLimitError extends Error {
+    /** The HTTP status that triggered this error. */
+    readonly statusCode = 429;
+    constructor(message?: string);
+}
+/**
+ * Thrown when a GraphQL response contains an `errors` array. The raw errors are
+ * preserved on {@link PeekGraphQLError.graphqlErrors} for inspection.
+ */
+declare class PeekGraphQLError extends Error {
+    /** The raw `errors` array returned by the GraphQL endpoint. */
+    readonly graphqlErrors: unknown[];
+    constructor(graphqlErrors: unknown[], message?: string);
+}
+
+export { ADD_ON_PRODUCT_TYPE, type AccountUser, AccountUserService, type AccountUserServiceOptions, 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 CreateBookingGuest, type CreateBookingInput, type CreateBookingTicket, type CreatePromoCodeInput, type CreatedBooking, type CreatedPromoCode, type CustomQuestionAnswer, type DailyNote, DailyNoteService, type Duration, type Guest, type GuestMetadata, type GuideAssignment, type InvoiceLinkResult, type Logger, type MakePaymentInput, type MakePaymentResult, type Membership, type MembershipPurchaseInput, MembershipService, type NoteMode, type Payment, type PaymentSource, PeekAccessService, type PeekAccessServiceConfig, PeekGraphQLError, type Price, type Product, ProductService, type ProductServiceOptions, type ProductTicket, type PromoCode, type PromoCodeFixedAmount, PromoCodeService, type PromoCodeServiceOptions, type PurchasedMembership, RateLimitError, type RefundInput, type RefundResult, ResellerService, type Resource, type ResourceOptionQuantity, type ResourcePool, type ResourcePoolAccountUser, type ResourcePoolAssignment, type ResourcePoolMode, ResourcePoolService, type Ticket, type Timeslot, type TimeslotFilter, TimeslotService, type UpdateTimeslotResult, noopLogger };