@ticketboothapp/booking 1.2.123 → 1.2.125

package/src/components/booking/useChangeBookingQuotePreview.ts

@@ -0,0 +1,442 @@
+import {
+  useEffect,
+  useMemo,
+  useRef,
+  type Dispatch,
+  type SetStateAction,
+} from 'react';
+import {
+  quoteChangeBooking,
+  type Availability,
+  type ItineraryDisplayStep,
+  type Product,
+  type ReturnOption,
+} from '../../lib/booking-api';
+import { getItineraryStepLabel } from '../../lib/booking/itinerary-display';
+import type { OrderSummaryTicketLine } from '../../lib/booking/pricing';
+import { formatCurrencyAmount } from '../../lib/currency';
+import type { ChangeBookingFlowProps, ChangeFlowSelectionPreview } from './booking-flow-types';
+import {
+  sliceAndMergeChangeQuoteForUi,
+  type ChangeBookingMergedQuoteState,
+} from './change-booking-quote-state';
+import {
+  formatTicketLineItemsForSummary,
+  getAvailabilityOptionId,
+} from './change-booking-flow-helpers';
+import type { Currency } from './CurrencySwitcher';
+
+type AddOnSelection = { addOnId: string; variantId?: string; quantity?: number };
+
+interface ChangeSelectionDetailsForPreview {
+  hasChangesFromInitial: boolean;
+  dateChanged: boolean;
+  ticketsChanged: boolean;
+}
+
+export interface UseChangeBookingQuotePreviewParams {
+  hasChangeSelection: boolean;
+  hasEffectiveChangeSelection: boolean;
+  selectedAvailability: Availability | null;
+  selectedReturnOption: ReturnOption | null;
+  initialValues: ChangeBookingFlowProps['initialValues'];
+  lastName: string;
+  product: Product;
+  pickupLocationId: string | null;
+  quantities: Record<string, number>;
+  addOnSelections: AddOnSelection[];
+  latestChangeQuote: ChangeBookingMergedQuoteState | null;
+  setLatestChangeQuote: Dispatch<SetStateAction<ChangeBookingMergedQuoteState | null>>;
+  changeQuoteLoading: boolean;
+  setChangeQuoteLoading: Dispatch<SetStateAction<boolean>>;
+  changeQuoteFetchError: string | null;
+  setChangeQuoteFetchError: Dispatch<SetStateAction<string | null>>;
+  totalQuantity: number;
+  ticketLineItems: OrderSummaryTicketLine[];
+  computeItineraryDisplay: () => ItineraryDisplayStep[] | null;
+  changeSelectionDetails: ChangeSelectionDetailsForPreview;
+  originalReceipt: ChangeBookingFlowProps['originalReceipt'];
+  suppressSelfServeCurrencyUi: boolean;
+  selfServePricingConfirmed: boolean;
+  displayChangeFlowProposedTotal: number;
+  displayChangeFlowSubtotal: number;
+  displayChangeFlowTax: number;
+  totalPrice: number;
+  effectiveSubtotal: number;
+  effectiveTax: number;
+  currency: Currency;
+  changeFlowClientEstimateDue: number;
+  changeFlowInitialTicketCount: number;
+  changeFlowNewBookingTotal: number;
+  isTaxIncludedInPrice: boolean;
+  isPublicSelectableAvailability: (availability: Availability, now?: Date) => boolean;
+  t: (key: string) => string;
+  locale: string;
+  error: string;
+  onChangeFlowSelectionPreview?: ChangeBookingFlowProps['onChangeFlowSelectionPreview'];
+  onPricePreviewChange?: ChangeBookingFlowProps['onPricePreviewChange'];
+}
+
+export interface UseChangeBookingQuotePreviewResult {
+  missingRequiredReturnSelection: boolean;
+  isChangeQuoteBlocked: boolean;
+  changeFlowSubmitDisabled: boolean;
+  changeCheckoutButtonLabel: string | undefined;
+  checkoutFormError: string;
+}
+
+export function useChangeBookingQuotePreview({
+  hasChangeSelection,
+  hasEffectiveChangeSelection,
+  selectedAvailability,
+  selectedReturnOption,
+  initialValues,
+  lastName,
+  product,
+  pickupLocationId,
+  quantities,
+  addOnSelections,
+  latestChangeQuote,
+  setLatestChangeQuote,
+  changeQuoteLoading,
+  setChangeQuoteLoading,
+  changeQuoteFetchError,
+  setChangeQuoteFetchError,
+  totalQuantity,
+  ticketLineItems,
+  computeItineraryDisplay,
+  changeSelectionDetails,
+  originalReceipt,
+  suppressSelfServeCurrencyUi,
+  selfServePricingConfirmed,
+  displayChangeFlowProposedTotal,
+  displayChangeFlowSubtotal,
+  displayChangeFlowTax,
+  totalPrice,
+  effectiveSubtotal,
+  effectiveTax,
+  currency,
+  changeFlowClientEstimateDue,
+  changeFlowInitialTicketCount,
+  changeFlowNewBookingTotal,
+  isTaxIncludedInPrice,
+  isPublicSelectableAvailability,
+  t,
+  locale,
+  error,
+  onChangeFlowSelectionPreview,
+  onPricePreviewChange,
+}: UseChangeBookingQuotePreviewParams): UseChangeBookingQuotePreviewResult {
+  const lastChangeFlowPreviewKeyRef = useRef<string | null>(null);
+  const lastCompletedQuoteInputsKeyRef = useRef<string | null>(null);
+  const inFlightQuoteInputsKeyRef = useRef<string | null>(null);
+  const changeQuoteRequestSeq = useRef(0);
+
+  const changeFlowNeedsServerPrice =
+    hasChangeSelection &&
+    !!initialValues?.bookingReference?.trim() &&
+    !!lastName.trim();
+
+  const isChangeQuoteBlocked = latestChangeQuote?.canProceed === false;
+  const requiresReturnInChangeFlow = !!initialValues?.returnAvailabilityId?.trim();
+  const missingRequiredReturnSelection = requiresReturnInChangeFlow && !selectedReturnOption;
+  const changeQuoteInputsKey = useMemo(() => JSON.stringify({
+    bookingReference: initialValues?.bookingReference?.trim() ?? '',
+    lastName: lastName.trim().toLowerCase(),
+    parentProductId: product.productId,
+    optionId: selectedAvailability ? getAvailabilityOptionId(selectedAvailability) : '',
+    dateTime: selectedAvailability?.dateTime ?? '',
+    availabilityId: selectedAvailability?.availabilityId ?? null,
+    pickupLocationId: pickupLocationId ?? null,
+    returnAvailabilityId: selectedReturnOption?.returnAvailabilityId ?? null,
+    quantities,
+    addOnSelections,
+  }), [
+    initialValues?.bookingReference,
+    lastName,
+    product.productId,
+    selectedAvailability,
+    pickupLocationId,
+    selectedReturnOption?.returnAvailabilityId,
+    quantities,
+    addOnSelections,
+  ]);
+
+  const changeFlowSubmitDisabled =
+    missingRequiredReturnSelection ||
+    (changeFlowNeedsServerPrice &&
+      (changeQuoteLoading || (!latestChangeQuote && !changeQuoteFetchError)));
+
+  const changeCheckoutButtonLabel = (() => {
+    if (!hasEffectiveChangeSelection) return undefined;
+    if (changeFlowNeedsServerPrice) {
+      if (changeQuoteLoading) {
+        const tr = t('booking.updatingPrice');
+        return tr !== 'booking.updatingPrice' ? tr : 'Updating price\u2026';
+      }
+      if (changeQuoteFetchError) {
+        const tr = t('booking.changeBookingRetry');
+        return tr !== 'booking.changeBookingRetry' ? tr : 'Change booking (retry)';
+      }
+      if (isChangeQuoteBlocked) {
+        const tr = t('booking.changeBookingNotAvailable');
+        return tr !== 'booking.changeBookingNotAvailable' ? tr : 'Change not available';
+      }
+      if (latestChangeQuote) {
+        const d = Math.round(changeFlowClientEstimateDue * 100) / 100;
+        return d > 0
+          ? `Change booking (${formatCurrencyAmount(d, currency, locale as 'en' | 'fr')})`
+          : 'Change booking (no charge)';
+      }
+      const tr = t('booking.changeBooking');
+      return tr !== 'booking.changeBooking' ? tr : 'Change booking';
+    }
+    const est = Math.round(changeFlowClientEstimateDue * 100) / 100;
+    return est > 0
+      ? `Change booking (${formatCurrencyAmount(est, currency, locale as 'en' | 'fr')})`
+      : 'Change booking (no charge)';
+  })();
+
+  const checkoutFormError =
+    (error || '') ||
+    (missingRequiredReturnSelection ? 'Removing return option in self-serve is not available. Please contact support.' : '') ||
+    (isChangeQuoteBlocked ? (latestChangeQuote?.reasonIfBlocked ?? '') : '') ||
+    (changeQuoteFetchError ?? '');
+
+  const changeFlowSelectionPreview = useMemo((): ChangeFlowSelectionPreview | null => {
+    if (!selectedAvailability || totalQuantity <= 0) return null;
+    const ticketsLine = formatTicketLineItemsForSummary(
+      ticketLineItems.map((l) => ({ category: l.category, qty: l.qty }))
+    );
+    const itinerary = computeItineraryDisplay();
+    const itinerarySteps =
+      itinerary?.map((s) => ({
+        time: s.time?.trim() || null,
+        label: getItineraryStepLabel(s),
+      })) ?? [];
+    return {
+      tourName: product.name?.trim() || '',
+      dateTime: selectedAvailability.dateTime,
+      ticketsLine,
+      itinerarySteps,
+      dateChanged: changeSelectionDetails.dateChanged,
+      ticketsChanged: changeSelectionDetails.ticketsChanged,
+      hasChangesFromInitial: changeSelectionDetails.hasChangesFromInitial,
+      selectionTotal:
+        originalReceipt
+          ? suppressSelfServeCurrencyUi && !selfServePricingConfirmed
+            ? null
+            : displayChangeFlowProposedTotal
+          : totalPrice,
+      selectionCurrency: currency,
+    };
+  }, [
+    selectedAvailability,
+    totalQuantity,
+    ticketLineItems,
+    computeItineraryDisplay,
+    product.name,
+    changeSelectionDetails,
+    totalPrice,
+    currency,
+    originalReceipt,
+    displayChangeFlowProposedTotal,
+    suppressSelfServeCurrencyUi,
+    selfServePricingConfirmed,
+  ]);
+
+  useEffect(() => {
+    if (!onChangeFlowSelectionPreview) return;
+    const next = changeFlowSelectionPreview;
+    const key =
+      next === null
+        ? 'null'
+        : JSON.stringify({
+            tourName: next.tourName,
+            dateTime: next.dateTime,
+            ticketsLine: next.ticketsLine,
+            itinerarySteps: next.itinerarySteps,
+            dateChanged: next.dateChanged,
+            ticketsChanged: next.ticketsChanged,
+            hasChangesFromInitial: next.hasChangesFromInitial,
+            selectionTotal: next.selectionTotal,
+            selectionCurrency: next.selectionCurrency,
+          });
+    if (key === lastChangeFlowPreviewKeyRef.current) return;
+    lastChangeFlowPreviewKeyRef.current = key;
+    onChangeFlowSelectionPreview(next);
+  }, [changeFlowSelectionPreview, onChangeFlowSelectionPreview]);
+
+  useEffect(() => {
+    if (!onPricePreviewChange) return;
+    if (!selectedAvailability || totalQuantity <= 0) {
+      onPricePreviewChange(null);
+      return;
+    }
+    if (suppressSelfServeCurrencyUi && !selfServePricingConfirmed) {
+      onPricePreviewChange(null);
+      return;
+    }
+    onPricePreviewChange({
+      subtotal: originalReceipt ? displayChangeFlowSubtotal : effectiveSubtotal,
+      tax:
+        !isTaxIncludedInPrice
+          ? originalReceipt
+            ? displayChangeFlowTax
+            : effectiveTax
+          : 0,
+      total: originalReceipt ? displayChangeFlowProposedTotal : totalPrice,
+      currency,
+    });
+  }, [
+    onPricePreviewChange,
+    selectedAvailability,
+    totalQuantity,
+    effectiveSubtotal,
+    effectiveTax,
+    displayChangeFlowProposedTotal,
+    displayChangeFlowSubtotal,
+    displayChangeFlowTax,
+    currency,
+    isTaxIncludedInPrice,
+    originalReceipt,
+    totalPrice,
+    suppressSelfServeCurrencyUi,
+    selfServePricingConfirmed,
+  ]);
+
+  /** Debounced server quote so CTA + amount owed match PaymentIntent; avoids free confirm when FE estimate differs. */
+  useEffect(() => {
+    if (
+      !hasChangeSelection ||
+      !selectedAvailability ||
+      !initialValues?.bookingReference?.trim() ||
+      !lastName.trim() ||
+      missingRequiredReturnSelection
+    ) {
+      setLatestChangeQuote(null);
+      setChangeQuoteLoading(false);
+      setChangeQuoteFetchError(null);
+      lastCompletedQuoteInputsKeyRef.current = null;
+      inFlightQuoteInputsKeyRef.current = null;
+      return;
+    }
+
+    if (
+      changeQuoteInputsKey &&
+      (inFlightQuoteInputsKeyRef.current === changeQuoteInputsKey ||
+        lastCompletedQuoteInputsKeyRef.current === changeQuoteInputsKey)
+    ) {
+      setChangeQuoteLoading(false);
+      return;
+    }
+
+    const optionId = getAvailabilityOptionId(selectedAvailability);
+    if (!optionId) {
+      setLatestChangeQuote(null);
+      setChangeQuoteLoading(false);
+      setChangeQuoteFetchError(null);
+      lastCompletedQuoteInputsKeyRef.current = null;
+      inFlightQuoteInputsKeyRef.current = null;
+      return;
+    }
+    if (!isPublicSelectableAvailability(selectedAvailability, new Date())) {
+      setLatestChangeQuote(null);
+      setChangeQuoteLoading(false);
+      setChangeQuoteFetchError(null);
+      lastCompletedQuoteInputsKeyRef.current = null;
+      inFlightQuoteInputsKeyRef.current = null;
+      return;
+    }
+
+    if (changeQuoteInputsKey && lastCompletedQuoteInputsKeyRef.current !== changeQuoteInputsKey) {
+      setLatestChangeQuote(null);
+    }
+    setChangeQuoteLoading(true);
+    setChangeQuoteFetchError(null);
+    const seq = ++changeQuoteRequestSeq.current;
+    const bookingReferenceForQuote = initialValues.bookingReference.trim();
+    const timer = window.setTimeout(() => {
+      void (async () => {
+        inFlightQuoteInputsKeyRef.current = changeQuoteInputsKey;
+        const bookingItems = Object.entries(quantities)
+          .filter(([, count]) => count > 0)
+          .map(([category, count]) => ({ category, count }));
+        try {
+          const quote = await quoteChangeBooking({
+            bookingReference: bookingReferenceForQuote,
+            lastName: lastName.trim(),
+            newProductId: optionId,
+            newDateTime: selectedAvailability.dateTime,
+            newAvailabilityId: selectedAvailability.availabilityId || null,
+            newPickupLocationId: pickupLocationId || null,
+            newReturnAvailabilityId: selectedReturnOption?.returnAvailabilityId ?? null,
+            newPassengerCounts: bookingItems,
+            // Omit when empty: backend treats [] as "clear all"; missing = preserve stored selections (BookingChangeIntentService).
+            ...(addOnSelections.length > 0 ? { newAddOnSelections: addOnSelections } : {}),
+            clientProposedTotal: changeFlowNewBookingTotal,
+            capacitySeatCredit: {
+              enabled: true,
+              previousPassengerCount: changeFlowInitialTicketCount,
+              previousAvailabilityId: initialValues.availabilityId ?? null,
+              previousReturnAvailabilityId: initialValues.returnAvailabilityId ?? null,
+            },
+          });
+          if (seq !== changeQuoteRequestSeq.current) return;
+          setLatestChangeQuote(
+            sliceAndMergeChangeQuoteForUi(quote, {
+              total: changeFlowNewBookingTotal,
+              subtotal: effectiveSubtotal,
+              tax: effectiveTax,
+            }, currency).mergedQuote,
+          );
+          lastCompletedQuoteInputsKeyRef.current = changeQuoteInputsKey;
+        } catch (e) {
+          if (seq !== changeQuoteRequestSeq.current) return;
+          setLatestChangeQuote(null);
+          setChangeQuoteFetchError(e instanceof Error ? e.message : 'Failed to get price for this change');
+          lastCompletedQuoteInputsKeyRef.current = null;
+        } finally {
+          if (inFlightQuoteInputsKeyRef.current === changeQuoteInputsKey) {
+            inFlightQuoteInputsKeyRef.current = null;
+          }
+          if (seq === changeQuoteRequestSeq.current) {
+            setChangeQuoteLoading(false);
+          }
+        }
+      })();
+    }, 450);
+
+    return () => {
+      window.clearTimeout(timer);
+    };
+  }, [
+    hasChangeSelection,
+    selectedAvailability,
+    initialValues,
+    lastName,
+    missingRequiredReturnSelection,
+    pickupLocationId,
+    selectedReturnOption?.returnAvailabilityId,
+    quantities,
+    addOnSelections,
+    changeFlowInitialTicketCount,
+    changeFlowNewBookingTotal,
+    effectiveSubtotal,
+    effectiveTax,
+    currency,
+    isPublicSelectableAvailability,
+    changeQuoteInputsKey,
+    setLatestChangeQuote,
+    setChangeQuoteLoading,
+    setChangeQuoteFetchError,
+  ]);
+
+  return {
+    missingRequiredReturnSelection,
+    isChangeQuoteBlocked,
+    changeFlowSubmitDisabled,
+    changeCheckoutButtonLabel,
+    checkoutFormError,
+  };
+}

package/src/components/booking/useChangeBookingReceiptDerivation.ts

@@ -0,0 +1,128 @@
+import { useMemo } from 'react';
+import {
+  changeFlowBalanceVsOriginal,
+  normalizeNearZeroOwed,
+  reconcileTaxIncludedChangeFlowTicketLines,
+  resolveChangeFlowDisplayedAmounts,
+  roundMoney,
+} from '../../lib/booking/change-flow-pricing';
+import type { PriceBreakdown as PriceBreakdownData } from '../../lib/booking/pricing';
+import type { ChangeBookingFlowProps } from './booking-flow-types';
+import type { ChangeBookingMergedQuoteState } from './change-booking-quote-state';
+import type { CheckoutModalLineItem } from './CheckoutModal';
+import type { PriceSummaryLine } from './PriceSummary';
+import type { PricingRate } from './change-booking-flow-helpers';
+
+type GetPriceBreakdown = (
+  category: string,
+  priceCAD: number,
+  baseInDisplayCurrency: number | undefined,
+  appliedAdjustments?: Array<{ type: string; id: string; name: string; changeByCurrency?: Record<string, number> }>,
+) => PriceBreakdownData | null;
+
+export interface UseChangeBookingReceiptDerivationParams {
+  latestChangeQuote: ChangeBookingMergedQuoteState | null;
+  changeQuoteFetchError: string | null;
+  changeFlowNewBookingTotal: number;
+  effectiveSubtotal: number;
+  effectiveTax: number;
+  isTaxIncludedInPrice: boolean;
+  originalReceipt: ChangeBookingFlowProps['originalReceipt'];
+  checkoutPriceSummaryLinesForCheckout: PriceSummaryLine[];
+  effectivePromoDiscountAmount: number;
+  pricing: PricingRate[];
+  getPriceBreakdown: GetPriceBreakdown;
+  totalPrice: number;
+}
+
+export function useChangeBookingReceiptDerivation({
+  latestChangeQuote,
+  changeQuoteFetchError,
+  changeFlowNewBookingTotal,
+  effectiveSubtotal,
+  effectiveTax,
+  isTaxIncludedInPrice,
+  originalReceipt,
+  checkoutPriceSummaryLinesForCheckout,
+  effectivePromoDiscountAmount,
+  pricing,
+  getPriceBreakdown,
+  totalPrice,
+}: UseChangeBookingReceiptDerivationParams) {
+  const displayedChangeAmounts = resolveChangeFlowDisplayedAmounts({
+    providerPreview: null,
+    serverQuotePreview: latestChangeQuote?.serverDisplay ? latestChangeQuote.serverDisplay : null,
+    fromCart: {
+      total: changeFlowNewBookingTotal,
+      subtotal: effectiveSubtotal,
+      tax: effectiveTax,
+    },
+  });
+  const displayChangeFlowProposedTotal = displayedChangeAmounts.total;
+  const displayChangeFlowSubtotal = displayedChangeAmounts.subtotal;
+  const displayChangeFlowTax = displayedChangeAmounts.tax;
+
+  const taxIncludedSelfServeReconciledPriceSummaryLines = useMemo(() => {
+    if (!isTaxIncludedInPrice || !originalReceipt) {
+      return checkoutPriceSummaryLinesForCheckout;
+    }
+    return reconcileTaxIncludedChangeFlowTicketLines(
+      checkoutPriceSummaryLinesForCheckout,
+      displayChangeFlowProposedTotal,
+      effectivePromoDiscountAmount,
+    );
+  }, [
+    isTaxIncludedInPrice,
+    originalReceipt,
+    checkoutPriceSummaryLinesForCheckout,
+    displayChangeFlowProposedTotal,
+    effectivePromoDiscountAmount,
+  ]);
+
+  const checkoutModalTicketLinesDisplay = useMemo((): CheckoutModalLineItem[] => {
+    return taxIncludedSelfServeReconciledPriceSummaryLines
+      .filter((line): line is Extract<PriceSummaryLine, { kind: 'ticket' }> => line.kind === 'ticket')
+      .map((line) => {
+        const rate = pricing.find((item) => item.category === line.category);
+        const breakdown = getPriceBreakdown(
+          line.category,
+          rate?.priceCAD ?? 0,
+          rate?.baseInDisplayCurrency,
+          rate?.appliedAdjustments ?? [],
+        );
+        const qty = Math.max(0, line.qty);
+        return {
+          line: {
+            category: line.category,
+            qty,
+            itemTotal: line.itemTotal,
+            pricePerUnit: qty > 0 ? roundMoney(line.itemTotal / qty) : 0,
+          },
+          breakdown,
+        };
+      });
+  }, [taxIncludedSelfServeReconciledPriceSummaryLines, pricing, getPriceBreakdown]);
+
+  const changeFlowClientEstimateDue = (() => {
+    if (!originalReceipt) return totalPrice;
+    if (latestChangeQuote != null && !changeQuoteFetchError) {
+      return normalizeNearZeroOwed(latestChangeQuote.priceDiff);
+    }
+    return changeFlowBalanceVsOriginal({
+      newTotal: displayChangeFlowProposedTotal,
+      originalReceiptTotal: originalReceipt.total,
+      audience: 'customer',
+    });
+  })();
+  const changeFlowAmountDue = normalizeNearZeroOwed(changeFlowClientEstimateDue);
+
+  return {
+    displayChangeFlowProposedTotal,
+    displayChangeFlowSubtotal,
+    displayChangeFlowTax,
+    taxIncludedSelfServeReconciledPriceSummaryLines,
+    checkoutModalTicketLinesDisplay,
+    changeFlowClientEstimateDue,
+    changeFlowAmountDue,
+  };
+}