@wix/bookings 1.0.1776 → 1.0.1778

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/build/cjs/context-booking-checkout.d.ts +243 -108
  2. package/build/cjs/context-booking-checkout.js +177 -183
  3. package/build/cjs/context-booking-checkout.js.map +1 -1
  4. package/build/cjs/context-categories.d.ts +16 -143
  5. package/build/cjs/context-categories.js +412 -412
  6. package/build/cjs/context-categories.js.map +1 -1
  7. package/build/cjs/context-locations.d.ts +16 -287
  8. package/build/cjs/context-locations.js +336 -336
  9. package/build/cjs/context-locations.js.map +1 -1
  10. package/build/cjs/context-service-addons.d.ts +2 -2
  11. package/build/cjs/context-service-addons.js +1 -1
  12. package/build/cjs/context-service-addons.js.map +1 -1
  13. package/build/cjs/context-service.d.ts +71 -33
  14. package/build/cjs/context-service.js +98 -96
  15. package/build/cjs/context-service.js.map +1 -1
  16. package/build/cjs/context-services.js +1 -1
  17. package/build/cjs/context-services.js.map +1 -1
  18. package/build/cjs/context-time-slots.d.ts +10 -0
  19. package/build/cjs/context-time-slots.js +2 -2
  20. package/build/cjs/context-time-slots.js.map +1 -1
  21. package/build/es/context-booking-checkout.d.mts +243 -108
  22. package/build/es/context-booking-checkout.mjs +177 -180
  23. package/build/es/context-booking-checkout.mjs.map +1 -1
  24. package/build/es/context-categories.d.mts +16 -143
  25. package/build/es/context-categories.mjs +412 -412
  26. package/build/es/context-categories.mjs.map +1 -1
  27. package/build/es/context-locations.d.mts +16 -287
  28. package/build/es/context-locations.mjs +336 -336
  29. package/build/es/context-locations.mjs.map +1 -1
  30. package/build/es/context-service-addons.d.mts +2 -2
  31. package/build/es/context-service-addons.mjs +1 -1
  32. package/build/es/context-service-addons.mjs.map +1 -1
  33. package/build/es/context-service.d.mts +71 -33
  34. package/build/es/context-service.mjs +98 -96
  35. package/build/es/context-service.mjs.map +1 -1
  36. package/build/es/context-services.mjs +1 -1
  37. package/build/es/context-services.mjs.map +1 -1
  38. package/build/es/context-time-slots.d.mts +10 -0
  39. package/build/es/context-time-slots.mjs +2 -2
  40. package/build/es/context-time-slots.mjs.map +1 -1
  41. package/build/internal/cjs/context-booking-checkout.d.ts +243 -108
  42. package/build/internal/cjs/context-categories.d.ts +16 -143
  43. package/build/internal/cjs/context-locations.d.ts +16 -287
  44. package/build/internal/cjs/context-service-addons.d.ts +2 -2
  45. package/build/internal/cjs/context-service.d.ts +71 -33
  46. package/build/internal/cjs/context-time-slots.d.ts +10 -0
  47. package/build/internal/es/context-booking-checkout.d.mts +243 -108
  48. package/build/internal/es/context-categories.d.mts +16 -143
  49. package/build/internal/es/context-locations.d.mts +16 -287
  50. package/build/internal/es/context-service-addons.d.mts +2 -2
  51. package/build/internal/es/context-service.d.mts +71 -33
  52. package/build/internal/es/context-time-slots.d.mts +10 -0
  53. package/{_sdk-exports → context-runtime}/context-booking-checkout/runtime.d.ts +243 -108
  54. package/context-runtime/context-booking-checkout/runtime.js +3 -0
  55. package/{_sdk-exports → context-runtime}/context-categories/runtime.d.ts +16 -143
  56. package/context-runtime/context-categories/runtime.js +2 -0
  57. package/context-runtime/context-locations/runtime.d.ts +195 -0
  58. package/context-runtime/context-locations/runtime.js +2 -0
  59. package/{_sdk-exports → context-runtime}/context-service/runtime.d.ts +71 -33
  60. package/{_sdk-exports → context-runtime}/context-service/runtime.js +3 -3
  61. package/{_sdk-exports → context-runtime}/context-service-addons/runtime.d.ts +2 -2
  62. package/{_sdk-exports → context-runtime}/context-time-slots/runtime.d.ts +10 -0
  63. package/{_sdk-exports → context-runtime}/context-time-slots/runtime.js +2 -2
  64. package/package.json +8 -8
  65. package/_sdk-exports/context-booking-checkout/runtime.js +0 -3
  66. package/_sdk-exports/context-categories/runtime.js +0 -2
  67. package/_sdk-exports/context-locations/runtime.d.ts +0 -466
  68. package/_sdk-exports/context-locations/runtime.js +0 -2
  69. /package/{_sdk-exports → context-runtime}/context-service-addons/runtime.js +0 -0
  70. /package/{_sdk-exports → context-runtime}/context-services/runtime.d.ts +0 -0
  71. /package/{_sdk-exports → context-runtime}/context-services/runtime.js +0 -0
@@ -2469,62 +2469,94 @@ interface SlotLocation {
2469
2469
  /** Response for RescheduleBookingAnonymously */
2470
2470
  //#endregion
2471
2471
  //#region ../bookings-flow-data/dist/types.d.ts
2472
- /** Whether the Booking Preferences hold one service or a Multi-Service Appointment. Derived,
2473
- * not chosen: the bookings-uou writer sets it from the service count on every encode (2+
2474
- * services is `multi`). Readers should count `services` rather than read it. */
2475
- type BookingMode = 'single' | 'multi';
2476
- /** A committed resource selection for one resource *type* (staff, room, equipment…).
2477
- * Carried as ids — the server accepts ids via `resourceSelections`, so the full resource
2478
- * object (name, schedule) is never needed in the contract.
2472
+ /**
2473
+ * Whether the selection holds 1 service or several services booked together. Supported values:
2474
+ * - `'single'`: 1 service.
2475
+ * - `'multi'`: 2 or more services, booked together as a multi-service appointment.
2479
2476
  *
2480
- * Not `bookings.ResourceSelection` (API shape is `resourceTypeId` + `selectionMethod`). */
2477
+ * It follows the number of entries in `services`, so count those instead of reading it.
2478
+ */
2479
+ type BookingMode = 'single' | 'multi';
2480
+ /** Resources the visitor chose for 1 resource type, such as a staff member or a room. */
2481
2481
  interface ResourceSelection {
2482
+ /** ID of the resource type, such as the staff member resource type. */
2482
2483
  type: string;
2484
+ /** IDs of the chosen resources of this type. */
2483
2485
  ids: string[];
2484
- /** The user picked "any available" rather than a specific resource of this type. */
2486
+ /** Whether the visitor chose any available resource of this type, instead of a specific one. */
2485
2487
  anyResource?: boolean;
2486
2488
  }
2487
- /** A chosen service variant (dynamic pricing): participant count and/or option choices. */
2489
+ /** A variant the visitor chose for a service with variants: a number of participants, option choices, or both. */
2488
2490
  type SelectedVariant = Pick<ServiceChoices, 'numberOfParticipants'> & {
2489
- /** Selected option values (wire carries string ids / custom values, not full `ServiceChoice` objects). */choices?: string[];
2491
+ /** The chosen option values: a choice ID, or the text of a custom choice. */choices?: string[];
2490
2492
  };
2491
2493
  /** Genders a visitor can narrow "any staff member" to, in display order. Same literals as the
2492
2494
  * availability API's `requestedGender.gender`, single- and multi-service alike. */
2493
2495
  declare const REQUESTED_GENDERS: readonly ["ANY_FEMALE", "ANY_MALE"];
2494
2496
  type RequestedGender = (typeof REQUESTED_GENDERS)[number];
2495
- /** A chosen add-on with its quantity — maps SDK `BookedAddOn` fields to flow names (`id` ↔ `_id`). */
2497
+ /** An add-on the visitor chose, with its quantity. */
2496
2498
  type AddOn = {
2497
- id: NonNullable<BookedAddOn['_id']>;
2499
+ /** ID of the add-on. */id: NonNullable<BookedAddOn['_id']>; /** Number of the add-on to book. */
2498
2500
  quantity: NonNullable<BookedAddOn['quantity']>;
2499
2501
  };
2500
- /** One service's committed selections. Slot/schedule fields align with `bookings.V2Slot`. */
2502
+ /** What the visitor chose for 1 service: the service, its time slot, and their choices. */
2501
2503
  type ServicePreference = {
2502
- serviceId: NonNullable<V2Slot['serviceId']>;
2504
+ /** ID of the service. */serviceId: NonNullable<V2Slot['serviceId']>; /** Slug of the service, as in its page URL. */
2503
2505
  slug?: NonNullable<Slug['name']>;
2504
- serviceType?: Service['type']; /** ISO local datetimes — per service (services in a bundle can start at different times). */
2505
- slotStart?: V2Slot['startDate'];
2506
- slotEnd?: V2Slot['endDate'];
2507
- eventId?: V2Slot['eventId'];
2508
- scheduleId?: V2Slot['scheduleId']; /** Needed to rehydrate class sessions in the OOI form. */
2509
- sessionId?: V2Slot['sessionId']; /** Id only — maps to `SlotLocation._id` / location refetch at the destination. */
2510
- locationId?: NonNullable<SlotLocation['_id']>; /** Availability naming (`BUSINESS` | `CUSTOM` | `CUSTOMER`); the booking step translates it to the bookings enum. */
2511
- locationType?: 'BUSINESS' | 'CUSTOM' | 'CUSTOMER';
2512
- resources?: ResourceSelection[];
2513
- selectedVariants?: SelectedVariant[];
2514
- addOns?: AddOn[]; /** The duration variant choice's id, sent to availability as `customerChoices.durationChoiceId`. */
2515
- durationChoiceId?: string;
2516
- /** A chosen duration in minutes, sent as `customerChoices.durationInMinutes`. With add-ons the
2517
- * API requires it to equal the service duration plus theirs, so writers usually omit it. */
2518
- durationInMinutes?: number; /** Narrows "any staff member" to a gender, sent as `customerChoices.requestedGender`. */
2506
+ /**
2507
+ * Type of the service. Supported values:
2508
+ * - `'APPOINTMENT'`: An appointment, booked by time slot.
2509
+ * - `'CLASS'`: A class session.
2510
+ * - `'COURSE'`: A course, booked as a whole by its schedule.
2511
+ */
2512
+ serviceType?: Service['type'];
2513
+ /**
2514
+ * Start of the time slot, as a local date and time without an offset, such as
2515
+ * `'2026-10-08T10:00:00'`. It's in the selection's `timezone`. Each service has its own, because
2516
+ * services booked together can start at different times. Absent for a course.
2517
+ */
2518
+ slotStart?: V2Slot['startDate']; /** End of the time slot, in the same format as `slotStart`. Absent for a course. */
2519
+ slotEnd?: V2Slot['endDate']; /** ID of the calendar event of a class session. */
2520
+ eventId?: V2Slot['eventId']; /** ID of the schedule the slot belongs to. For a course, the course's schedule. */
2521
+ scheduleId?: V2Slot['scheduleId']; /** ID of the class session. */
2522
+ sessionId?: V2Slot['sessionId']; /** ID of the business location of the slot. */
2523
+ locationId?: NonNullable<SlotLocation['_id']>;
2524
+ /**
2525
+ * Where the service takes place. Supported values:
2526
+ * - `'BUSINESS'`: At one of the business's locations, in `locationId`.
2527
+ * - `'CUSTOM'`: At an address the business set for the service.
2528
+ * - `'CUSTOMER'`: At the customer's address.
2529
+ */
2530
+ locationType?: 'BUSINESS' | 'CUSTOM' | 'CUSTOMER'; /** Resources the visitor chose, such as a staff member, by resource type. */
2531
+ resources?: ResourceSelection[]; /** Variants the visitor chose, for a service with variants. */
2532
+ selectedVariants?: SelectedVariant[]; /** Add-ons the visitor chose. */
2533
+ addOns?: AddOn[]; /** ID of the duration choice the visitor chose, for a service with a choice of durations. */
2534
+ durationChoiceId?: string; /** Duration the visitor chose, in minutes. */
2535
+ durationInMinutes?: number;
2536
+ /**
2537
+ * Gender the visitor asked for when they chose any available staff member. Supported values:
2538
+ * `'ANY_FEMALE'`, `'ANY_MALE'`.
2539
+ */
2519
2540
  requestedGender?: RequestedGender;
2520
2541
  };
2521
- /** One accumulating object; each destination builder projects the slice it needs. */
2542
+ /** What the visitor selected to book: the services, their time slots, and their choices. */
2522
2543
  interface BookingPreferences {
2544
+ /** Whether the selection holds 1 service or several. Count `services` instead of reading it. */
2523
2545
  mode: BookingMode;
2546
+ /**
2547
+ * Time zone of the slots' local dates and times, as an IANA name such as `'Europe/London'`.
2548
+ * Can be absent when the selection has no time slot, such as a course.
2549
+ */
2524
2550
  timezone?: V2Slot['timezone'];
2551
+ /** The selected services, in booking order. */
2525
2552
  services: ServicePreference[];
2526
- /** The visitor ticked "I have a coupon" in the Booking Summary, so checkout must not be skipped.
2527
- * Absent means unticked; writers omit `false`. */
2553
+ /**
2554
+ * Whether the visitor asked to enter a promo code, in the booking summary. When it's `true`, a
2555
+ * priced booking paid in person goes through the checkout page, where the visitor enters the
2556
+ * code.
2557
+ *
2558
+ * Default: `false`
2559
+ */
2528
2560
  wantsPromoCode?: boolean;
2529
2561
  }
2530
2562
  //#endregion
@@ -2698,7 +2730,7 @@ interface MembershipRowData {
2698
2730
  /** Date the membership expires. `null` when it doesn't expire. */
2699
2731
  expirationDate: string | null;
2700
2732
  }
2701
- interface PaymentOption$1 {
2733
+ interface PaymentOption {
2702
2734
  /** Option ID. For a membership option, the membership's ID. */
2703
2735
  id: string;
2704
2736
  /**
@@ -2782,6 +2814,12 @@ interface PaymentOption$1 {
2782
2814
  */
2783
2815
  planBenefit?: PlanBenefit | null;
2784
2816
  }
2817
+ /**
2818
+ * A payment option as the Booking Checkout context takes it. Only `membership` and
2819
+ * `purchasablePlan` are required, which is all the context reads. Pass the other fields too for a
2820
+ * booking summary to show the option's price and how it's paid.
2821
+ */
2822
+ type CheckoutPaymentOption = Pick<PaymentOption, 'membership' | 'purchasablePlan'> & Partial<Omit<PaymentOption, 'membership' | 'purchasablePlan'>>;
2785
2823
  //#endregion
2786
2824
  //#region src/domains/payment-options/to-booking.d.ts
2787
2825
  interface SelectedMembership {
@@ -2809,7 +2847,11 @@ interface ParticipantsServiceChoice {
2809
2847
  optionId?: string;
2810
2848
  }>;
2811
2849
  }
2812
- /** The count's previewed price, in the service's currency: the response carries none. */
2850
+ /**
2851
+ * Price of a number of participants, in the service's currency. The price doesn't include the
2852
+ * currency: read it from the service's `payment.fixed.price.currency`, or for a varied price from
2853
+ * `payment.varied.defaultPrice.currency`, as the Service context returns them.
2854
+ */
2813
2855
  interface ParticipantsPrice {
2814
2856
  /** Total price for the participants. */
2815
2857
  total: number;
@@ -2830,7 +2872,6 @@ interface ContactDetailsInput {
2830
2872
  */
2831
2873
  phone?: string;
2832
2874
  }
2833
- type PaymentOption = BookingPaymentOption;
2834
2875
  type OfferedAddOnGroup = Pick<NonNullable<Service$1['addOnGroups']>[number], '_id' | 'addOnIds'>;
2835
2876
  interface BookingPayment {
2836
2877
  /**
@@ -2840,7 +2881,7 @@ interface BookingPayment {
2840
2881
  * - `'MEMBERSHIP'`: With a plan the visitor has, or buys in the same checkout. Set the plan in
2841
2882
  * `membership`, `memberships`, or `purchase`. Without one, the booking is paid online.
2842
2883
  */
2843
- paymentOption: PaymentOption;
2884
+ paymentOption: BookingPaymentOption;
2844
2885
  /** Deposit (`true`) or full amount (`false`). */
2845
2886
  depositSelected: boolean | null;
2846
2887
  /** The plan bought in the same cart that pays this entry. */
@@ -2953,16 +2994,42 @@ interface PlanAndBookFlow {
2953
2994
  //#region src/domains/booking-checkout/checkout-error.d.ts
2954
2995
  /** Why a `createBooking()` or `addToCart()` call failed. */
2955
2996
  interface CheckoutError {
2956
- /** Error code from the server, such as `'SLOT_NOT_AVAILABLE'`, or `'UNKNOWN'` without one. */
2997
+ /**
2998
+ * Error code from the server, or `'UNKNOWN'` when the failure has none. Common codes:
2999
+ * - `'SLOT_NOT_AVAILABLE'`: The time slot is no longer available.
3000
+ * - `'SESSION_CAPACITY_EXCEEDED'`, `'SCHEDULE_CAPACITY_EXCEEDED'`: Not enough spots are left for
3001
+ * the participants.
3002
+ * - `'EXCEEDED_ALLOWED_MAX_NUMBER_OF_PARTICIPANTS'`: More participants than the service allows in
3003
+ * 1 booking.
3004
+ * - `'BOOKING_POLICY_VIOLATION'`: The service's booking policy doesn't allow the booking at this
3005
+ * time.
3006
+ * - `'VIOLATIONS_WITH_ERROR_SEVERITY'`: The booking breaks a rule the server describes in
3007
+ * `violation`.
3008
+ * - `'INVALID_CHOICES'`: The selected variant choices aren't valid for the service.
3009
+ * - `'NON_SUFFICIENT_FUNDS'`: The visitor's plan doesn't have enough credits for the booking.
3010
+ * - `'CART_IS_ALREADY_ASSOCIATED_WITH_DIFFERENT_LOCATION'`: From `addToCart()` only. The cart
3011
+ * already holds bookings at another business location. Nothing is booked.
3012
+ *
3013
+ * Other codes can occur. A site without an eCom Thank You page fails with `'UNKNOWN'` when the
3014
+ * order is placed without the checkout page.
3015
+ */
2957
3016
  code: string;
2958
- /** The first violation's text, sent with the `'VIOLATIONS_WITH_ERROR_SEVERITY'` code. */
3017
+ /** Text of the first rule the booking breaks, when the server sends one. */
2959
3018
  violation?: string;
2960
3019
  }
2961
3020
  //#endregion
2962
3021
  //#region src/extensions/contexts/booking-checkout-context/use-booking-checkout.d.ts
2963
3022
  interface BookingFormHandle {
2964
3023
  /**
2965
- * Whether the selection overlaps an appointment with the same staff member in the visitor's cart.
3024
+ * Whether the selection can't join the visitor's cart: the cart holds an appointment with the
3025
+ * same staff member at an overlapping time, or the cart's bookings of the selected class or course
3026
+ * already take all its open spots. Compute it from the visitor's current cart and the selected
3027
+ * slot. While it's `true`, `addToCart()` does nothing. `createBooking()` doesn't check it, because
3028
+ * it books in a cart of its own.
3029
+ *
3030
+ * The context reads it when the form is registered, so register the form again when it changes.
3031
+ *
3032
+ * Default: `false`
2966
3033
  */
2967
3034
  hasCartConflict?: boolean;
2968
3035
  /**
@@ -3003,11 +3070,15 @@ interface BookingFormHandle {
3003
3070
  */
3004
3071
  getBiParams?: () => Record<string, unknown>;
3005
3072
  }
3006
- /** What the Booking Form tells the widgets beside it, once it is usable and the cart is read. */
3073
+ /**
3074
+ * What the booking form shares with the components beside it, such as a booking summary: how the
3075
+ * visitor pays for each service, and whether their cart already holds bookings. Publish it once the
3076
+ * form can be submitted and the visitor's cart is read.
3077
+ */
3007
3078
  interface FormFacts {
3008
- /** How the visitor pays each booked service. */
3079
+ /** How the visitor pays for each booked service, in the order of `selection.services`. */
3009
3080
  payments: {
3010
- /** ID of the booked service, or `null` when it isn't known. */serviceId: string | null;
3081
+ /** ID of the booked service. `null` while the service is loading or failed to load. */serviceId: string | null;
3011
3082
  /**
3012
3083
  * How the visitor pays for the service. Supported values:
3013
3084
  * - `'ONLINE'`: Online.
@@ -3025,7 +3096,10 @@ interface FormFacts {
3025
3096
  */
3026
3097
  participantsPrice?: PreviewedParticipantsPrice;
3027
3098
  }
3028
- /** `failed` too when the preview has no price; `count` is the count it prices. */
3099
+ /**
3100
+ * Price of a number of participants, while it loads and once it's loaded. `'failed'` also covers a
3101
+ * preview that returned no price.
3102
+ */
3029
3103
  type PreviewedParticipantsPrice = {
3030
3104
  /** The price is loading. */status: 'loading';
3031
3105
  } | {
@@ -3034,17 +3108,11 @@ type PreviewedParticipantsPrice = {
3034
3108
  /** The price is loaded. */status: 'loaded'; /** Number of participants the price is for. */
3035
3109
  count: number;
3036
3110
  } & ParticipantsPrice);
3037
- interface BookingCheckoutResult {
3038
- /** IDs of the bookings created. */
3039
- bookingIds: string[];
3040
- /** ID of the cart that holds the bookings. */
3041
- cartId: string;
3042
- }
3043
- /** Where addToCart() sends the visitor once the items are in the cart. `stay` leaves them on the page. */
3111
+ /** Where `addToCart()` sends the visitor once the bookings are in the cart. `'stay'` leaves them on the page. */
3044
3112
  type AddToCartDestination = 'cart' | 'home' | 'stay' | OwnerLink;
3045
3113
  /**
3046
- * The failure, or the bookings now in the cart and whether this page is being left. Null when the
3047
- * form is invalid, a run is in flight or the selection changed before it failed.
3114
+ * What `addToCart()` resolves with: the failure, or the bookings added to the cart and whether the
3115
+ * visitor leaves the page. `null` when nothing ran; see `addToCart()` for each case.
3048
3116
  */
3049
3117
  type AddToCartOutcome = {
3050
3118
  /** Why adding the bookings to the cart failed. */error: CheckoutError;
@@ -3056,23 +3124,40 @@ type AddToCartOutcome = {
3056
3124
  */
3057
3125
  leavesPage: boolean;
3058
3126
  } | null;
3059
- /** The failure, for the clicked button to show; null when nothing failed, nothing ran or the selection changed before it failed. */
3127
+ /**
3128
+ * What `createBooking()` resolves with: the failure, for the clicked button to show. `null` in every
3129
+ * other case; see `createBooking()` for each case.
3130
+ */
3060
3131
  type CreateBookingOutcome = {
3061
3132
  /** Why creating the booking failed. */error: CheckoutError;
3062
3133
  } | null;
3063
3134
  interface BookingCheckoutState {
3064
3135
  /**
3065
- * Booking preferences from the page URL's `b` query parameter: the services the visitor selected,
3066
- * with their time slots and choices.
3136
+ * The services the visitor selected, with their time slots and choices, read from the page URL's
3137
+ * `b` query parameter. The Service and Time Slots contexts write that parameter when they send the
3138
+ * visitor to the Booking Form page. To build a link that carries the selection yourself, use the
3139
+ * Service context's `withSelectionParam()`. The parameter's format is internal and can change.
3067
3140
  *
3068
- * `null` when the URL has no booking preferences, or they hold no service.
3141
+ * `null` when the URL has no selection, or it holds no service.
3069
3142
  */
3070
3143
  selection: BookingPreferences | null;
3071
- /** Whether every service in the selection can be booked and a booking form is registered. */
3144
+ /**
3145
+ * Whether the selection has everything a booking needs and a booking form is registered. Every
3146
+ * service needs a service type, a time slot with a time zone, and a schedule or session ID. A
3147
+ * course needs only its schedule ID, and can't be booked together with other services. Services
3148
+ * booked together must be at the same location.
3149
+ *
3150
+ * It doesn't check availability or booking policies. The server checks them when you book, and a
3151
+ * failure comes back as a `CheckoutError`.
3152
+ */
3072
3153
  canBook: boolean;
3073
3154
  /**
3074
3155
  * What the submit button offers and where `createBooking()` sends the visitor, based on the
3075
3156
  * payment options in `selectedPaymentOptions`.
3157
+ *
3158
+ * `{ cta: 'BOOK', route: 'CHECKOUT' }` while `selectedPaymentOptions` is `null`, such as while the
3159
+ * payment options load. Wait for `isLoadingPaymentOptions` to be `false` before you show the
3160
+ * button's label.
3076
3161
  */
3077
3162
  planAndBookFlow: PlanAndBookFlow;
3078
3163
  /**
@@ -3081,7 +3166,7 @@ interface BookingCheckoutState {
3081
3166
  *
3082
3167
  * `null` until the form publishes them for the current selection, and while they load.
3083
3168
  */
3084
- selectedPaymentOptions: Array<PaymentOption$1 | null> | null;
3169
+ selectedPaymentOptions: Array<CheckoutPaymentOption | null> | null;
3085
3170
  /**
3086
3171
  * Whether the booking form is loading the payment options for the current selection.
3087
3172
  *
@@ -3092,18 +3177,24 @@ interface BookingCheckoutState {
3092
3177
  * Publishes the payment option the visitor chose for each booked service. It doesn't wait for
3093
3178
  * the form to be valid.
3094
3179
  *
3095
- * It sets `selectedPaymentOptions` and `planAndBookFlow`. Options published for an earlier
3096
- * selection don't apply: when the selection changes, `selectedPaymentOptions` is `null` until
3097
- * the form publishes again.
3098
- *
3099
- * @param options Payment option the visitor chose for each booked service, with `null` for a
3100
- * service with none chosen. Pass `null` while the options are loading, which sets
3101
- * `isLoadingPaymentOptions` to `true`.
3180
+ * It sets `selectedPaymentOptions` and `planAndBookFlow`, which decide the button's label and
3181
+ * where `createBooking()` sends the visitor. What's booked and charged comes from the form's
3182
+ * `getInput().payments` instead, so publish the same choices in both. Options published for an
3183
+ * earlier selection don't apply: when the selection changes, `selectedPaymentOptions` is `null`
3184
+ * until the form publishes again.
3185
+ *
3186
+ * @param options Payment option the visitor chose for each booked service, in the order of
3187
+ * `selection.services`, with `null` for a service with none chosen. The context reads only
3188
+ * `membership`, for a plan the visitor has, and `purchasablePlan`, for a plan they buy. For any
3189
+ * other way to pay, set `membership` to `null` and leave `purchasablePlan` out. A booking summary
3190
+ * shows the option's price and how it's paid only for a full option, with every field set. Pass
3191
+ * `null` instead of the array while the options are loading, which sets `isLoadingPaymentOptions`
3192
+ * to `true`.
3102
3193
  * @param isPlanAndBookBlocked Whether a plan the visitor buys must be bought before booking,
3103
3194
  * instead of in the same checkout as the booking. When it's `true` and an option buys a plan,
3104
- * `planAndBookFlow` sends the visitor to buy the plan first. Set it to `true` when a service
3105
- * charges a cancellation fee or saves the visitor's card, or when more than 1 participant is
3106
- * booked.
3195
+ * `planAndBookFlow` sends the visitor to buy the plan first. Set it to `true` when more than 1
3196
+ * participant is booked, or when a booked service's `bookingPolicy.cancellationFeePolicy.enabled`
3197
+ * or `bookingPolicy.saveCreditCardPolicy.enabled` is `true` in the Services API.
3107
3198
  * @returns Function that clears these payment options, unless a later call replaced them. Call it
3108
3199
  * when your component unmounts.
3109
3200
  * @example Publish the visitor's payment choices
@@ -3127,10 +3218,11 @@ interface BookingCheckoutState {
3127
3218
  * }
3128
3219
  * ```
3129
3220
  */
3130
- registerPaymentOptions: (options: Array<PaymentOption$1 | null> | null, isPlanAndBookBlocked: boolean) => () => void;
3221
+ registerPaymentOptions: (options: Array<CheckoutPaymentOption | null> | null, isPlanAndBookBlocked: boolean) => () => void;
3131
3222
  /**
3132
- * Whether the selection overlaps an appointment with the same staff member in the visitor's cart,
3133
- * as the registered form reports it. While it's `true`, `addToCart()` does nothing.
3223
+ * Whether the selection can't join the visitor's cart, as the registered form reports it in its
3224
+ * `hasCartConflict`. While it's `true`, `addToCart()` does nothing. `createBooking()` doesn't check
3225
+ * it.
3134
3226
  *
3135
3227
  * `false` while no form is registered.
3136
3228
  */
@@ -3147,7 +3239,7 @@ interface BookingCheckoutState {
3147
3239
  * its `hasCartConflict` changes.
3148
3240
  *
3149
3241
  * @param form Form to register, or `null` to remove the registered form.
3150
- * @example Register a contact form
3242
+ * @example Register a contact form that books payment in person
3151
3243
  * ```tsx
3152
3244
  * import { useEffect, useRef, useState } from 'react';
3153
3245
  * import { useBookingCheckoutContext } from '@wix/bookings/context/booking-checkout';
@@ -3156,6 +3248,8 @@ interface BookingCheckoutState {
3156
3248
  * function ContactForm() {
3157
3249
  * const { selection, registerForm } = useBookingCheckoutContext();
3158
3250
  * const [contact, setContact] = useState({ firstName: '', lastName: '', email: '' });
3251
+ * // The context calls validate() and getInput() when the visitor submits, not on each
3252
+ * // render, so they read the latest values from a ref.
3159
3253
  * const latest = useRef({ contact, selection });
3160
3254
  * latest.current = { contact, selection };
3161
3255
  *
@@ -3249,8 +3343,24 @@ interface BookingCheckoutState {
3249
3343
  * Validates the registered form, creates the bookings and a cart for them, and then either places
3250
3344
  * the order or sends the visitor to the checkout page.
3251
3345
  *
3252
- * When a plan has to be bought first, as `planAndBookFlow` says, it sends the visitor to buy the
3253
- * plan instead. Only 1 `createBooking()` or `addToCart()` call runs at a time.
3346
+ * It places the order and opens the Thank You page only when the visitor has nothing to pay now,
3347
+ * the form's input doesn't set `requiresCheckoutPage`, and the visitor didn't ask to enter a promo
3348
+ * code for a priced booking paid in person. Otherwise the visitor goes to the checkout page.
3349
+ *
3350
+ * What it does depends on `planAndBookFlow.route`:
3351
+ * - `'CHECKOUT'`: As above.
3352
+ * - `'INLINE_CART'`: Puts the plan and the bookings in one cart, and opens the checkout page.
3353
+ * - `'DETAILS_PAGE'`: Creates the bookings and their cart, then opens the plan's page that collects
3354
+ * what the plan needs, such as a start date.
3355
+ * - `'PRICING_PLANS'`: Books nothing, and opens a page to buy the plan. The visitor comes back to
3356
+ * book with it.
3357
+ *
3358
+ * Only 1 `createBooking()` or `addToCart()` call runs at a time. When a call fails after the
3359
+ * bookings were created, a retry for the same selection, participant count and payment choices
3360
+ * uses those bookings instead of booking again. A retry with the other function does too, unless
3361
+ * the failed call already put the bookings in a cart; the other function then books again.
3362
+ * The bookings keep the details from the call that created them, so a correction the visitor
3363
+ * makes in between, such as to their email, doesn't apply.
3254
3364
  *
3255
3365
  * @returns An object with the failure in `error` when creating the booking fails. The same
3256
3366
  * failure is in `createError`.
@@ -3291,15 +3401,17 @@ interface BookingCheckoutState {
3291
3401
  /**
3292
3402
  * Why the last `createBooking()` call failed.
3293
3403
  *
3294
- * `null` when it didn't fail. The next `createBooking()` or `addToCart()` call clears it, and so
3295
- * does a change to the selection or to the number of participants.
3404
+ * `null` when it didn't fail. The next `createBooking()` or `addToCart()` call that runs clears
3405
+ * it, and so does a change to the selection or to the number of participants. A call that returns
3406
+ * `null` right away, because `canBook` is `false` or another call is in progress, leaves it.
3296
3407
  */
3297
3408
  createError: CheckoutError | null;
3298
3409
  /**
3299
3410
  * Validates the registered form, creates the bookings, adds them to the visitor's current cart,
3300
3411
  * and sends the visitor to `destination`.
3301
3412
  *
3302
- * Only 1 `addToCart()` or `createBooking()` call runs at a time.
3413
+ * Only 1 `addToCart()` or `createBooking()` call runs at a time. A retry after a failure reuses
3414
+ * bookings already created, as described in `createBooking()`.
3303
3415
  *
3304
3416
  * @param destination Where to send the visitor once the bookings are in the cart. Supported
3305
3417
  * values:
@@ -3316,7 +3428,7 @@ interface BookingCheckoutState {
3316
3428
  * location, the failure's `code` is `'CART_IS_ALREADY_ASSOCIATED_WITH_DIFFERENT_LOCATION'` and
3317
3429
  * nothing is booked.
3318
3430
  *
3319
- * `null` when nothing runs because `canBook` is `false`, the form has a cart conflict,
3431
+ * `null` when nothing runs because `canBook` is `false`, `hasCartConflict` is `true`,
3320
3432
  * `planAndBookFlow.cta` isn't `'BOOK'`, the form isn't valid, or another `createBooking()` or
3321
3433
  * `addToCart()` call is in progress. Also `null` when the selection or the participant count
3322
3434
  * changed before the call failed.
@@ -3326,9 +3438,22 @@ interface BookingCheckoutState {
3326
3438
  * import { useBookingCheckoutContext } from '@wix/bookings/context/booking-checkout';
3327
3439
  *
3328
3440
  * function AddToCartButton() {
3329
- * const { canBook, hasCartConflict, isAddingToCart, addToCart } = useBookingCheckoutContext();
3441
+ * const {
3442
+ * canBook,
3443
+ * hasCartConflict,
3444
+ * isCreating,
3445
+ * isAddingToCart,
3446
+ * planAndBookFlow,
3447
+ * addToCart,
3448
+ * addToCartError,
3449
+ * } = useBookingCheckoutContext();
3330
3450
  * const [isAdded, setIsAdded] = useState(false);
3331
3451
  *
3452
+ * // A plan to buy can't go in the visitor's cart, so addToCart() does nothing then.
3453
+ * if (planAndBookFlow.cta !== 'BOOK') {
3454
+ * return null;
3455
+ * }
3456
+ *
3332
3457
  * const handleClick = async () => {
3333
3458
  * const outcome = await addToCart('stay');
3334
3459
  * setIsAdded(outcome !== null && 'bookingIds' in outcome);
@@ -3336,10 +3461,14 @@ interface BookingCheckoutState {
3336
3461
  *
3337
3462
  * return (
3338
3463
  * <div>
3339
- * <button disabled={!canBook || hasCartConflict || isAddingToCart} onClick={handleClick}>
3464
+ * <button
3465
+ * disabled={!canBook || hasCartConflict || isCreating || isAddingToCart}
3466
+ * onClick={handleClick}
3467
+ * >
3340
3468
  * Add to cart
3341
3469
  * </button>
3342
3470
  * {isAdded && <p>Added to your cart.</p>}
3471
+ * {addToCartError && <p role="alert">We couldn't add this to your cart. Try again.</p>}
3343
3472
  * </div>
3344
3473
  * );
3345
3474
  * }
@@ -3357,14 +3486,19 @@ interface BookingCheckoutState {
3357
3486
  /**
3358
3487
  * Why the last `addToCart()` call failed.
3359
3488
  *
3360
- * `null` when it didn't fail. The next `createBooking()` or `addToCart()` call clears it, and so
3361
- * does a change to the selection or to the number of participants.
3489
+ * `null` when it didn't fail. The next `createBooking()` or `addToCart()` call that runs clears
3490
+ * it, and so does a change to the selection or to the number of participants. A call that returns
3491
+ * `null` right away leaves it: see `addToCart()` for those cases.
3362
3492
  */
3363
3493
  addToCartError: CheckoutError | null;
3364
3494
  /**
3365
3495
  * Number of participants to book when the selected service's variants don't set the count, such
3366
3496
  * as a single service with no variants.
3367
3497
  *
3498
+ * It applies only to a selection of 1 service. In a selection of several services, each service
3499
+ * is booked with the count its own choices set, or 1. The count isn't kept in the page URL, so it
3500
+ * goes back to `1` when the page reloads.
3501
+ *
3368
3502
  * Default: `1`
3369
3503
  */
3370
3504
  participants: number;
@@ -3377,49 +3511,43 @@ interface BookingCheckoutState {
3377
3511
  * Changing the count clears `createError` and `addToCartError`.
3378
3512
  *
3379
3513
  * @param count Number of participants.
3380
- * @example Add a participants field
3514
+ * @example Add a participants stepper
3381
3515
  * ```tsx
3382
3516
  * import { useBookingCheckoutContext } from '@wix/bookings/context/booking-checkout';
3383
3517
  *
3384
- * function ParticipantsField() {
3518
+ * function ParticipantsStepper() {
3385
3519
  * const { participants, setParticipants } = useBookingCheckoutContext();
3386
3520
  *
3387
3521
  * return (
3388
- * <label>
3389
- * Participants
3390
- * <input
3391
- * type="number"
3392
- * min={1}
3393
- * value={participants}
3394
- * onChange={(event) => setParticipants(Number(event.target.value))}
3395
- * />
3396
- * </label>
3522
+ * <div role="group" aria-label="Participants">
3523
+ * <button disabled={participants <= 1} onClick={() => setParticipants(participants - 1)}>
3524
+ * -
3525
+ * </button>
3526
+ * <span>{participants}</span>
3527
+ * <button onClick={() => setParticipants(participants + 1)}>+</button>
3528
+ * </div>
3397
3529
  * );
3398
3530
  * }
3399
3531
  * ```
3400
3532
  */
3401
3533
  setParticipants: (count: number) => void;
3402
- /**
3403
- * IDs of the bookings and the cart from the last `createBooking()` or `addToCart()` call that put
3404
- * the bookings in a cart.
3405
- *
3406
- * `null` before such a call.
3407
- */
3408
- lastResult: BookingCheckoutResult | null;
3409
3534
  }
3410
- declare function canBookSelection(selection: BookingPreferences | null): boolean;
3411
3535
  //#endregion
3412
3536
  //#region src/extensions/contexts/booking-checkout-context/booking-checkout-context.d.ts
3413
3537
  /** The booking in progress: the selection decoded from the page URL, its payment options and participant count, and the actions to create the booking or add it to the cart. */
3414
3538
  type BookingCheckoutContextValue = BookingCheckoutState;
3415
- declare const bookingCheckoutContext: React.Context<BookingCheckoutState | null>;
3416
- declare const BOOKING_CHECKOUT_CONTEXT_MISSING_PROVIDER_ERROR = "useBookingCheckoutContext must be used within BookingCheckoutContextProvider";
3417
3539
  /**
3418
3540
  * The `useBookingCheckoutContext()` hook provides access to the booking a visitor is about to make,
3419
3541
  * including the services and times they selected, how they pay, and the number of participants. Use
3420
3542
  * it to send the booking to checkout, add it to the visitor's cart, and connect a booking form to
3421
- * the buttons and summary beside it. When you pass `true` to the hook, it returns `null` where the
3422
- * context isn't available.
3543
+ * the buttons and summary beside it.
3544
+ *
3545
+ * Where the context isn't available, the hook throws an error with the message
3546
+ * `'useBookingCheckoutContext must be used within BookingCheckoutContextProvider'`. Pass `true` to
3547
+ * get `null` there instead.
3548
+ *
3549
+ * @param optional Pass `true` to get `null` instead of an error where the context isn't available.
3550
+ * @returns The context's properties and functions, or `null` where the context isn't available.
3423
3551
  */
3424
3552
  declare function useBookingCheckoutContext(optional: true): BookingCheckoutContextValue | null;
3425
3553
  /**
@@ -3428,7 +3556,14 @@ declare function useBookingCheckoutContext(optional: true): BookingCheckoutConte
3428
3556
  * it to send the booking to checkout, add it to the visitor's cart, and connect a booking form to
3429
3557
  * the buttons and summary beside it.
3430
3558
  *
3431
- * It throws an error where the context isn't available.
3559
+ * Where the context isn't available, the hook throws an error with the message
3560
+ * `'useBookingCheckoutContext must be used within BookingCheckoutContextProvider'`. Pass `true` to
3561
+ * get `null` there instead.
3562
+ *
3563
+ * @param optional Leave it out, or pass `false`, to throw where the context isn't available.
3564
+ *
3565
+ * Default: `false`
3566
+ * @returns The context's properties and functions.
3432
3567
  */
3433
3568
  declare function useBookingCheckoutContext(optional?: false): BookingCheckoutContextValue;
3434
3569
  /** Props accepted by {@link BookingCheckoutContextProvider}. */
@@ -3440,4 +3575,4 @@ declare function BookingCheckoutContextProvider({
3440
3575
  children
3441
3576
  }: BookingCheckoutContextProviderProps): React.JSX.Element;
3442
3577
 
3443
- export { BOOKING_CHECKOUT_CONTEXT_MISSING_PROVIDER_ERROR, BookingCheckoutContextProvider, type BookingCheckoutContextProviderProps, type BookingCheckoutContextValue, type BookingCheckoutResult, type BookingFormHandle, type CreateBookingInput, bookingCheckoutContext, canBookSelection, BookingCheckoutContextProvider as default, useBookingCheckoutContext };
3578
+ export { BookingCheckoutContextProvider, type BookingCheckoutContextProviderProps, type BookingCheckoutContextValue, type BookingFormHandle, type CreateBookingInput, BookingCheckoutContextProvider as default, useBookingCheckoutContext };