@ticketboothapp/booking 1.2.123 → 1.2.125

package/src/components/booking/change-booking-flow-helpers.ts

@@ -0,0 +1,706 @@
+import { parseISO } from 'date-fns';
+import { formatInTimeZone } from 'date-fns-tz';
+import type {
+  AddOn,
+  AdminFeAuthoritativeReceipt,
+  Availability,
+  PricingConfig,
+  PrecomputedPricesByCategory,
+  Product,
+  ReturnOption,
+} from '../../lib/booking-api';
+import {
+  getDisplayPriceFromBaseInDisplayCurrency,
+  computePriceBreakdown,
+} from '../../lib/booking/pricing';
+import { roundMoney } from '../../lib/booking/change-flow-pricing';
+import type { PriceSummaryLine } from './PriceSummary';
+import type { Currency } from './CurrencySwitcher';
+
+const ZERO_PRICE_SUMMARY_LINE = 0.005;
+
+export type AddOnSelection = { addOnId: string; variantId?: string; quantity?: number };
+
+/** Change-quote receipt lines may include a $0 promo/discount row; omit from sidebar summary only. */
+export function omitZeroAmountPromoDiscountSummaryLines(lines: PriceSummaryLine[]): PriceSummaryLine[] {
+  return lines.filter((line) => {
+    if (line.kind !== 'line') return true;
+    if (Math.abs(line.amount) >= ZERO_PRICE_SUMMARY_LINE) return true;
+    const t = String(line.type ?? '').toUpperCase();
+    if (t === 'PROMO_CODE' || t === 'DISCOUNT' || t === 'GIFT_CARD' || t === 'VOUCHER') return false;
+    const lab = line.label.toLowerCase();
+    if (lab.includes('promo')) return false;
+    if (lab.includes('voucher') || lab.includes('gift card')) return false;
+    return true;
+  });
+}
+
+export function isPromoDiscountGiftCardOrVoucherLine(line: {
+  type?: string | null;
+  label?: string | null;
+  amount?: number | null;
+}): boolean {
+  const type = String(line.type ?? '').trim().toUpperCase();
+  if (type === 'PROMO_CODE' || type === 'DISCOUNT' || type === 'GIFT_CARD' || type === 'VOUCHER') {
+    return true;
+  }
+  const label = String(line.label ?? '').trim().toLowerCase();
+  return /promo|discount|voucher|gift\s*card/.test(label);
+}
+
+export function deriveOriginalReceiptPromoAdjustment(originalReceipt: {
+  promoAmount?: number | null;
+  promoLabel?: string | null;
+  lineItems?: Array<{ type?: string | null; label?: string | null; amount?: number | null }>;
+} | null | undefined): {
+  amount: number;
+  label: string | null;
+  type: 'PROMO_CODE' | 'GIFT_CARD' | 'VOUCHER' | 'DISCOUNT';
+} {
+  let amount = Math.max(0, Number(originalReceipt?.promoAmount) || 0);
+  let label = originalReceipt?.promoLabel?.trim() || null;
+  let type: 'PROMO_CODE' | 'GIFT_CARD' | 'VOUCHER' | 'DISCOUNT' = 'PROMO_CODE';
+
+  for (const line of originalReceipt?.lineItems ?? []) {
+    if (!isPromoDiscountGiftCardOrVoucherLine(line)) continue;
+    const lineAmount = Number(line.amount) || 0;
+    if (lineAmount < -0.005) {
+      amount = Math.max(amount, Math.abs(lineAmount));
+      if (!label) label = line.label?.trim() || null;
+    }
+    const lineType = String(line.type ?? '').trim().toUpperCase();
+    const lineLabel = String(line.label ?? '').trim().toLowerCase();
+    if (lineType === 'GIFT_CARD' || /gift\s*card/.test(lineLabel)) {
+      type = 'GIFT_CARD';
+    } else if (lineType === 'VOUCHER' || /voucher/.test(lineLabel)) {
+      type = 'VOUCHER';
+    } else if (lineType === 'DISCOUNT' || /discount/.test(lineLabel)) {
+      type = 'DISCOUNT';
+    }
+  }
+
+  return { amount: roundMoney(amount), label, type };
+}
+
+export function resolveTicketQtyFromQuantities(
+  category: string,
+  quantities: Record<string, number>,
+): number | undefined {
+  const c = category.trim();
+  if (Object.prototype.hasOwnProperty.call(quantities, c)) return quantities[c];
+  const up = c.toUpperCase();
+  for (const [key, val] of Object.entries(quantities)) {
+    if (key.toUpperCase() === up) return val;
+  }
+  return undefined;
+}
+
+export function mergePickerTicketQtyIntoPriceSummaryLines(
+  lines: PriceSummaryLine[],
+  quantities: Record<string, number>,
+): PriceSummaryLine[] {
+  return lines.map((line) => {
+    if (line.kind !== 'ticket') return line;
+    const uiQty = resolveTicketQtyFromQuantities(line.category, quantities);
+    const lineQty = Math.max(0, Number(line.qty) || 0);
+    const effectiveQty = uiQty != null && uiQty >= 0 ? Math.round(uiQty) : lineQty;
+    let itemTotal = roundMoney(line.itemTotal);
+    if (lineQty > 0 && effectiveQty !== lineQty) {
+      itemTotal = roundMoney((line.itemTotal * effectiveQty) / lineQty);
+    }
+    return { ...line, qty: Math.max(0, effectiveQty), itemTotal };
+  });
+}
+
+export function normalizeFeReceiptLineItemType(type: string | null | undefined): string | undefined {
+  const normalized = String(type ?? '').trim().toUpperCase();
+  if (!normalized) return undefined;
+  switch (normalized) {
+    case 'TICKET':
+    case 'ADULT':
+    case 'CHILD':
+    case 'INFANT':
+    case 'SENIOR':
+    case 'STUDENT':
+      return 'TICKET';
+    case 'RETURN':
+    case 'RETURN_OPTION':
+    case 'RETURNOPTION':
+      return 'RETURN_OPTION';
+    case 'CANCELLATION':
+    case 'CANCELLATION_UPGRADE':
+    case 'CANCELLATION_POLICY_UPGRADE':
+      return 'CANCELLATION_UPGRADE';
+    case 'PROMO':
+    case 'PROMO_CODE':
+      return 'PROMO_CODE';
+    case 'VOUCHER':
+    case 'DISCOUNT':
+      return 'DISCOUNT';
+    case 'GIFT_CARD':
+      return 'GIFT_CARD';
+    case 'DEAL':
+      return 'DEAL';
+    case 'TAX':
+      return 'TAX';
+    case 'ROUNDING':
+      return 'ROUNDING';
+    case 'BOOKING_CHANGE':
+      return 'BOOKING_CHANGE';
+    case 'FEE':
+      return 'FEE';
+    default:
+      return 'FEE';
+  }
+}
+
+/** Receipt TICKET rows sent on admin quote must follow picker quantities. */
+export function mapSummaryLinesToFeReceiptLineItems(
+  lines: PriceSummaryLine[],
+  quantities: Record<string, number>,
+): NonNullable<AdminFeAuthoritativeReceipt['lineItems']> {
+  return lines.map((line) => {
+    if (line.kind === 'ticket') {
+      const uiQty = resolveTicketQtyFromQuantities(line.category, quantities);
+      const lineQty = Math.max(0, line.qty);
+      const effectiveQty =
+        uiQty != null && uiQty >= 0 ? Math.round(uiQty) : lineQty;
+      let amount = roundMoney(line.itemTotal);
+      if (lineQty > 0 && effectiveQty !== lineQty) {
+        amount = roundMoney((line.itemTotal * effectiveQty) / lineQty);
+      }
+      return {
+        label: line.category,
+        amount,
+        type: 'TICKET',
+        quantity: Math.max(0, effectiveQty),
+      };
+    }
+    return {
+      label: line.label,
+      amount: roundMoney(line.amount),
+      type: normalizeFeReceiptLineItemType(line.type),
+      quantity: line.quantity ?? undefined,
+    };
+  });
+}
+
+export function formatTicketLineItemsForSummary(lines: Array<{ category: string; qty: number }>): string {
+  const labels: Record<string, string> = {
+    ADULT: 'adult',
+    CHILD: 'child',
+    INFANT: 'infant',
+    SENIOR: 'senior',
+    STUDENT: 'student',
+  };
+  const parts = lines
+    .filter((l) => l.qty > 0)
+    .map((l) => {
+      const label = labels[l.category] || l.category.toLowerCase();
+      return `${l.qty} ${label}${l.qty !== 1 ? 's' : ''}`;
+    });
+  return parts.length > 0 ? parts.join(', ') : '—';
+}
+
+export function normalizeTicketCategoryFromReceiptLabel(raw: string): string | null {
+  const normalized = raw.trim().toUpperCase();
+  if (!normalized) return null;
+  if (['ADULT', 'CHILD', 'INFANT', 'SENIOR', 'STUDENT'].includes(normalized)) return normalized;
+  const compact = normalized.replace(/[^A-Z]/g, ' ').replace(/\s+/g, ' ').trim();
+  if (/\bADULTS?\b/.test(compact)) return 'ADULT';
+  if (/\bCHILD(REN)?\b/.test(compact)) return 'CHILD';
+  if (/\bINFANTS?\b/.test(compact)) return 'INFANT';
+  if (/\bSENIORS?\b/.test(compact)) return 'SENIOR';
+  if (/\bSTUDENTS?\b/.test(compact)) return 'STUDENT';
+  return null;
+}
+
+export function extractTrailingQty(label: string): { baseLabel: string; qty: number } {
+  const trimmed = label.trim();
+  const m = trimmed.match(/^(.*?)(?:\s*[×x]\s*(\d+))$/);
+  if (!m) return { baseLabel: trimmed, qty: 1 };
+  const baseLabel = (m[1] || '').trim();
+  const qty = Math.max(1, Number(m[2]) || 1);
+  return { baseLabel, qty };
+}
+
+export function normalizeLineLabelForCompare(label: string): string {
+  return label
+    .toLowerCase()
+    .replace(/\([^)]*\)/g, '')
+    .replace(/[^a-z0-9]+/g, '')
+    .trim();
+}
+
+export function deriveAddOnSelectionsFromReceiptLines(
+  addOns: AddOn[],
+  lines: Array<{ type?: string; label?: string; amount?: number; quantity?: number }>
+): AddOnSelection[] {
+  const selections: AddOnSelection[] = [];
+  for (const line of lines) {
+    const type = (line.type || '').trim().toUpperCase();
+    if (type !== 'FEE') continue;
+    const amount = Number(line.amount ?? 0);
+    if (!Number.isFinite(amount) || amount <= 0) continue;
+    const rawLabel = (line.label || '').trim();
+    if (!rawLabel) continue;
+
+    const { baseLabel, qty } = extractTrailingQty(rawLabel);
+    let matched = false;
+
+    for (const addOn of addOns) {
+      if (matched) break;
+      const addOnName = addOn.name?.trim();
+      if (!addOnName) continue;
+
+      if (addOn.variantType === 'single_choice' || addOn.variantType === 'multi_quantity') {
+        for (const variant of addOn.variants ?? []) {
+          const variantLabel = variant.label?.trim();
+          if (!variantLabel) continue;
+          if (baseLabel === `${addOnName} (${variantLabel})`) {
+            selections.push({ addOnId: addOn.addOnId, variantId: variant.id, quantity: qty });
+            matched = true;
+            break;
+          }
+        }
+      } else if (baseLabel === addOnName) {
+        selections.push({ addOnId: addOn.addOnId, quantity: qty });
+        matched = true;
+      }
+    }
+  }
+  return selections;
+}
+
+export function findMergedAvailabilityForSelection(
+  merged: Availability[],
+  selected: Availability | null
+): Availability | undefined {
+  if (!selected) return undefined;
+  const optId = getAvailabilityOptionId(selected) || undefined;
+  const dt = selected.dateTime;
+  const availId = selected.availabilityId?.trim();
+  if (availId && optId) {
+    const exact = merged.find(
+      (a) =>
+        a.availabilityId === availId &&
+        getAvailabilityOptionId(a) === optId
+    );
+    if (exact) return exact;
+  }
+  return merged.find((a) => a.dateTime === dt && getAvailabilityOptionId(a) === optId);
+}
+
+export function getAvailabilityOptionId(availability: Availability, fallbackOptionId?: string): string {
+  const productOptionId = availability.productOptionId?.trim();
+  if (productOptionId) return productOptionId;
+  const productId = availability.productId?.trim();
+  if (productId?.startsWith('po_')) return productId;
+  return fallbackOptionId?.trim() ?? '';
+}
+
+export function getAvailabilityCacheKey(availability: Availability): string {
+  return `${availability.dateTime}-${getAvailabilityOptionId(availability)}`;
+}
+
+export type PricingRate = {
+  category: string;
+  rateId: string;
+  available: number | undefined;
+  price: number;
+  priceCAD: number;
+  baseInDisplayCurrency: number;
+  appliedAdjustments: Array<{ type: string; id: string; name: string; changeByCurrency?: Record<string, number> }>;
+};
+
+/** Ticket rates for one availability row; mirrors main cart pricing so baseline slots match BE. */
+export function buildPricingFromAvailability(
+  selectedAvailability: Availability | null,
+  activeOptions: Product['options'],
+  precomputedPricesByOption: Record<string, PrecomputedPricesByCategory> | null | undefined,
+  currency: Currency,
+  pricingConfig: PricingConfig | null,
+  hasFees: boolean,
+  isSimplifiedPricingView: boolean,
+) {
+  if (!selectedAvailability || !pricingConfig) return [];
+  const optionId = getAvailabilityOptionId(selectedAvailability);
+  const selectedOption = activeOptions.find((opt) => opt.optionId === optionId);
+  const precomputed = optionId ? precomputedPricesByOption?.[optionId] : undefined;
+  const rateToDisplayPrice = (backendInDisplayCurrency: number) =>
+    getDisplayPriceFromBaseInDisplayCurrency(backendInDisplayCurrency, currency, pricingConfig, hasFees);
+  const getBaseInDisplayCurrency = (category: string) => {
+    const fromPrecomputed = precomputed?.[category]?.[currency];
+    if (fromPrecomputed != null) return fromPrecomputed;
+    return 0;
+  };
+  const buildRate = (
+    category: string,
+    backendPriceCAD: number,
+    backendInDisplayCurrency: number,
+    baseInDisplayCurrency: number,
+    appliedAdjustments: Array<{ type: string; id: string; name: string; changeByCurrency?: Record<string, number> }>,
+  ) => {
+    const basePriceCAD = selectedOption?.pricing?.[category.toUpperCase()] ?? 0;
+    const hasOptionScopedPrice = baseInDisplayCurrency > 0;
+    const priceCADForBreakdown =
+      hasOptionScopedPrice && currency === 'CAD' ? baseInDisplayCurrency : backendPriceCAD;
+    const displayCurrencyPriceForFallback = hasOptionScopedPrice
+      ? baseInDisplayCurrency
+      : backendInDisplayCurrency;
+    const isPublicMode = isSimplifiedPricingView;
+    const breakdown = computePriceBreakdown(
+      pricingConfig,
+      currency,
+      priceCADForBreakdown,
+      basePriceCAD,
+      hasFees,
+      appliedAdjustments,
+      undefined,
+      baseInDisplayCurrency,
+      isPublicMode,
+    );
+    const price = breakdown?.finalPrice ?? rateToDisplayPrice(displayCurrencyPriceForFallback);
+    return { category, baseInDisplayCurrency, appliedAdjustments, price, priceCAD: priceCADForBreakdown };
+  };
+  return (
+    selectedAvailability.rates?.map((rate) => {
+      const backendPriceCAD = rate.price ?? 0;
+      const backendInDisplayCurrency =
+        rate.priceByCurrency?.[currency] ?? (currency === 'CAD' ? backendPriceCAD : 0);
+      const baseInDisplayCurrency = getBaseInDisplayCurrency(rate.category);
+      const built = buildRate(
+        rate.category,
+        backendPriceCAD,
+        backendInDisplayCurrency,
+        baseInDisplayCurrency,
+        rate.appliedAdjustments ?? rate.applied_adjustments ?? [],
+      );
+      return {
+        category: rate.category,
+        rateId: rate.rateId || rate.category,
+        available: rate.available,
+        price: built.price,
+        priceCAD: built.priceCAD,
+        baseInDisplayCurrency: built.baseInDisplayCurrency,
+        appliedAdjustments: built.appliedAdjustments,
+      };
+    }) ||
+    selectedAvailability.pricesByCategory?.retailPrices?.map((p) => {
+      const priceCADFromApi = p.price / 100;
+      const baseInDisplayCurrency = getBaseInDisplayCurrency(p.category);
+      const backendInDisplayCurrency = currency === 'CAD' ? priceCADFromApi : 0;
+      const built = buildRate(p.category, priceCADFromApi, backendInDisplayCurrency, baseInDisplayCurrency, []);
+      return {
+        category: p.category,
+        rateId: p.category,
+        available: selectedAvailability.vacancies,
+        price: built.price,
+        priceCAD: built.priceCAD,
+        baseInDisplayCurrency: built.baseInDisplayCurrency,
+        appliedAdjustments: built.appliedAdjustments,
+      };
+    }) ||
+    []
+  );
+}
+
+export function findMergedReturnVacancies(
+  outbound: Availability | undefined,
+  selectedReturn: ReturnOption | null | undefined
+): number | null {
+  if (!selectedReturn?.returnAvailabilityId || !outbound?.returnOptions?.length) return null;
+  const ro = outbound.returnOptions.find(
+    (r) => r.returnAvailabilityId === selectedReturn.returnAvailabilityId
+  );
+  return ro ? ro.vacancies : null;
+}
+
+export function normalizeAddOnSelections(selections: AddOnSelection[]): AddOnSelection[] {
+  const qtyByKey = new Map<string, number>();
+  for (const sel of selections) {
+    const addOnId = sel.addOnId?.trim();
+    if (!addOnId) continue;
+    const variantId = sel.variantId?.trim() || '';
+    const key = `${addOnId}::${variantId}`;
+    qtyByKey.set(key, (qtyByKey.get(key) ?? 0) + Math.max(1, Number(sel.quantity) || 1));
+  }
+  return Array.from(qtyByKey.entries()).map(([key, qty]) => {
+    const [addOnId, variantIdRaw] = key.split('::');
+    const variantId = variantIdRaw?.trim() || undefined;
+    return { addOnId, variantId, quantity: qty };
+  });
+}
+
+export function parseAvailabilityDateTime(value: string): Date {
+  // If API omits timezone offset, treat it as UTC to prevent user-local day shifts.
+  const hasExplicitOffset = /(?:Z|[+-]\d{2}:?\d{2})$/i.test(value);
+  return parseISO(hasExplicitOffset ? value : `${value}Z`);
+}
+
+export function deriveDefaultQuantitiesFromAvailabilities(
+  availabilities: Availability[]
+): Record<string, number> | null {
+  const firstWithRates = availabilities.find((avail) => avail.rates && avail.rates.length > 0);
+  if (!firstWithRates?.rates?.length) return null;
+
+  const initialQuantities: Record<string, number> = {};
+  firstWithRates.rates.forEach((rate) => {
+    initialQuantities[rate.category] = rate.category === 'ADULT' ? 1 : 0;
+  });
+
+  return Object.keys(initialQuantities).length > 0 ? initialQuantities : null;
+}
+
+/** Clock time in the company IANA zone, never the browser local zone. */
+export function getMinutesFromMidnightInTimezone(isoDateTime: string, ianaTimeZone: string): number {
+  const dt = parseAvailabilityDateTime(isoDateTime);
+  const h = parseInt(formatInTimeZone(dt, ianaTimeZone, 'H'), 10);
+  const m = parseInt(formatInTimeZone(dt, ianaTimeZone, 'm'), 10);
+  return h * 60 + m;
+}
+
+export function minCircularMinutesDiff(a: number, b: number): number {
+  const d = Math.abs(a - b);
+  return Math.min(d, 24 * 60 - d);
+}
+
+export function pickOutboundMatchingPreviousSelection(
+  timesForSelectedDate: Availability[],
+  anchor: { productOptionId: string | null; minutesFromMidnight: number },
+  companyTimezone: string,
+  optionsMap: Map<string, { mostPopular?: boolean }>,
+  includeSoldOut = false
+): Availability | null {
+  const selectable = timesForSelectedDate.filter((a) => (a.vacancies ?? 0) > 0 || includeSoldOut);
+  if (selectable.length === 0) return null;
+
+  const withOption =
+    anchor.productOptionId != null
+      ? selectable.filter((a) => a.productOptionId === anchor.productOptionId)
+      : [];
+  const pool = withOption.length > 0 ? withOption : selectable;
+
+  const sorted = [...pool].sort((a, b) => {
+    const da = minCircularMinutesDiff(
+      getMinutesFromMidnightInTimezone(a.dateTime, companyTimezone),
+      anchor.minutesFromMidnight
+    );
+    const db = minCircularMinutesDiff(
+      getMinutesFromMidnightInTimezone(b.dateTime, companyTimezone),
+      anchor.minutesFromMidnight
+    );
+    if (Math.abs(da - db) > 0.5) return da - db;
+    const aPop = optionsMap.get(a.productOptionId ?? '')?.mostPopular ? 1 : 0;
+    const bPop = optionsMap.get(b.productOptionId ?? '')?.mostPopular ? 1 : 0;
+    if (aPop !== bPop) return bPop - aPop;
+    return parseAvailabilityDateTime(a.dateTime).getTime() - parseAvailabilityDateTime(b.dateTime).getTime();
+  });
+  return sorted[0] ?? null;
+}
+
+export function pickReturnMatchingPreviousSelection(
+  sortedReturnOptions: ReturnOption[],
+  anchor: { returnLocation: string; minutesFromMidnight: number },
+  companyTimezone: string,
+  includeSoldOut = false
+): ReturnOption | null {
+  const eligible = sortedReturnOptions.filter((o) => (o.vacancies ?? 0) > 0 || includeSoldOut);
+  if (eligible.length === 0) return null;
+
+  const sameLoc = eligible.filter((o) => o.returnLocation === anchor.returnLocation);
+  const pool = sameLoc.length > 0 ? sameLoc : eligible;
+
+  const sorted = [...pool].sort((a, b) => {
+    const da = minCircularMinutesDiff(
+      getMinutesFromMidnightInTimezone(a.dateTime, companyTimezone),
+      anchor.minutesFromMidnight
+    );
+    const db = minCircularMinutesDiff(
+      getMinutesFromMidnightInTimezone(b.dateTime, companyTimezone),
+      anchor.minutesFromMidnight
+    );
+    if (Math.abs(da - db) > 0.5) return da - db;
+    return parseAvailabilityDateTime(a.dateTime).getTime() - parseAvailabilityDateTime(b.dateTime).getTime();
+  });
+  return sorted[0] ?? null;
+}
+
+export function scoreTicketSubtotalForOption(
+  optionId: string | undefined,
+  bookingItems: Array<{ category: string; count: number }> | null | undefined,
+  precomputedPricesByOption: Record<string, PrecomputedPricesByCategory> | null | undefined,
+  currency: Currency
+): number | null {
+  if (!optionId || !bookingItems?.length || !precomputedPricesByOption?.[optionId]) return null;
+  const precomputed = precomputedPricesByOption[optionId];
+  let sum = 0;
+  for (const { category, count } of bookingItems) {
+    if (count <= 0) continue;
+    const key = category?.trim();
+    if (!key) continue;
+    const unit =
+      precomputed[key]?.[currency] ??
+      precomputed[key.toUpperCase()]?.[currency] ??
+      precomputed[key.toLowerCase()]?.[currency];
+    if (unit == null) return null;
+    sum += unit * count;
+  }
+  return sum;
+}
+
+export function disambiguateAvailabilityCandidates(
+  candidates: Availability[],
+  initialProductOptionId: string | undefined,
+  bookingItems: Array<{ category: string; count: number }> | null | undefined,
+  precomputedPricesByOption: Record<string, PrecomputedPricesByCategory> | null | undefined,
+  currency: Currency,
+  originalSubtotalBeforeTax: number | undefined
+): Availability | null {
+  const withVacancyFirst = [...candidates].sort((a, b) => (b.vacancies > 0 ? 1 : 0) - (a.vacancies > 0 ? 1 : 0));
+  const pool = withVacancyFirst.length > 0 ? withVacancyFirst : candidates;
+  if (pool.length === 0) return null;
+  if (pool.length === 1) return pool[0];
+
+  if (initialProductOptionId) {
+    const matched = pool.find((a) => a.productOptionId === initialProductOptionId);
+    if (matched) return matched;
+  }
+
+  if (originalSubtotalBeforeTax != null && precomputedPricesByOption && bookingItems?.length) {
+    let best: Availability | null = null;
+    let bestDiff = Infinity;
+    for (const c of pool) {
+      const score = scoreTicketSubtotalForOption(c.productOptionId, bookingItems, precomputedPricesByOption, currency);
+      if (score == null) continue;
+      const diff = Math.abs(score - originalSubtotalBeforeTax);
+      if (
+        diff < bestDiff - 0.005 ||
+        (diff <= bestDiff + 0.005 && (best == null || (c.vacancies > 0 && best.vacancies <= 0)))
+      ) {
+        bestDiff = diff;
+        best = c;
+      }
+    }
+    if (best) return best;
+  }
+
+  return pool.find((a) => a.vacancies > 0) ?? pool[0];
+}
+
+export function resolveInitialAvailabilityFromBooking(
+  timesForSelectedDate: Availability[],
+  target: Date,
+  companyTimezone: string,
+  initialAvailabilityId: string | null | undefined,
+  initialProductOptionId: string | null | undefined,
+  bookingItems: Array<{ category: string; count: number }> | null | undefined,
+  precomputedPricesByOption: Record<string, PrecomputedPricesByCategory> | null | undefined,
+  currency: Currency,
+  originalSubtotalBeforeTax: number | undefined
+): { selection: Availability | null; defer: boolean } {
+  const availId = initialAvailabilityId?.trim() || null;
+  const optId = initialProductOptionId?.trim() || null;
+
+  if (availId) {
+    const byAvail = timesForSelectedDate.find((a) => a.availabilityId === availId);
+    if (byAvail) return { selection: byAvail, defer: false };
+  }
+
+  const targetMs = target.getTime();
+  const sameInstant = timesForSelectedDate.filter(
+    (a) => parseAvailabilityDateTime(a.dateTime).getTime() === targetMs
+  );
+
+  if (sameInstant.length > 0) {
+    if (sameInstant.length === 1) {
+      return { selection: sameInstant[0], defer: false };
+    }
+    const ambiguous =
+      !optId &&
+      !availId &&
+      new Set(sameInstant.map((s) => s.productOptionId).filter(Boolean)).size > 1;
+    if (ambiguous && !precomputedPricesByOption) {
+      return { selection: null, defer: true };
+    }
+    const picked = disambiguateAvailabilityCandidates(
+      sameInstant,
+      optId ?? undefined,
+      bookingItems,
+      precomputedPricesByOption,
+      currency,
+      originalSubtotalBeforeTax
+    );
+    return { selection: picked, defer: false };
+  }
+
+  const localKey = formatInTimeZone(target, companyTimezone, 'yyyy-MM-dd HH:mm');
+  const sameLocalWall = timesForSelectedDate.filter((a) => {
+    const key = formatInTimeZone(parseAvailabilityDateTime(a.dateTime), companyTimezone, 'yyyy-MM-dd HH:mm');
+    return key === localKey;
+  });
+
+  if (sameLocalWall.length > 0) {
+    if (sameLocalWall.length === 1) {
+      return { selection: sameLocalWall[0], defer: false };
+    }
+    const ambiguous =
+      !optId &&
+      !availId &&
+      new Set(sameLocalWall.map((s) => s.productOptionId).filter(Boolean)).size > 1;
+    if (ambiguous && !precomputedPricesByOption) {
+      return { selection: null, defer: true };
+    }
+    const picked = disambiguateAvailabilityCandidates(
+      sameLocalWall,
+      optId ?? undefined,
+      bookingItems,
+      precomputedPricesByOption,
+      currency,
+      originalSubtotalBeforeTax
+    );
+    return { selection: picked, defer: false };
+  }
+
+  if (optId) {
+    const byOption = timesForSelectedDate.filter((a) => a.productOptionId === optId);
+    if (byOption.length > 0) {
+      const timeMatch = byOption.find((a) => parseAvailabilityDateTime(a.dateTime).getTime() === targetMs);
+      if (timeMatch) return { selection: timeMatch, defer: false };
+      const localMatch = byOption.find(
+        (a) =>
+          formatInTimeZone(parseAvailabilityDateTime(a.dateTime), companyTimezone, 'yyyy-MM-dd HH:mm') === localKey
+      );
+      if (localMatch) return { selection: localMatch, defer: false };
+      const picked = disambiguateAvailabilityCandidates(
+        byOption,
+        optId,
+        bookingItems,
+        precomputedPricesByOption,
+        currency,
+        originalSubtotalBeforeTax
+      );
+      return { selection: picked, defer: false };
+    }
+  }
+
+  const fallback = timesForSelectedDate.find((a) => a.vacancies > 0) ?? null;
+  return { selection: fallback, defer: false };
+}
+
+export function isPrivateShuttleProduct(product: Pick<Product, 'productType'> | null | undefined): boolean {
+  return product?.productType === 'PRIVATE_SHUTTLE';
+}
+
+export function getAdminChangeEligibleProducts(products: Product[], currentProduct: Product): Product[] {
+  if (isPrivateShuttleProduct(currentProduct)) return [currentProduct];
+  const activeStandardProducts = products.filter(
+    (p) =>
+      p.status === 'ACTIVE' &&
+      !isPrivateShuttleProduct(p) &&
+      p.options?.some((o) => o.status === 'ACTIVE'),
+  );
+  return activeStandardProducts.some((p) => p.productId === currentProduct.productId)
+    ? activeStandardProducts
+    : [currentProduct, ...activeStandardProducts];
+}