@ticketboothapp/booking 1.2.123 → 1.2.124

package/src/components/booking/change-booking-payment-modal-builders.ts

@@ -0,0 +1,151 @@
+import { formatBookingRefForDisplay } from '../../lib/booking-ref';
+import {
+  MANAGE_BOOKING_FROM_CHANGE_PAYMENT,
+  MANAGE_BOOKING_QUERY_FROM,
+} from '../../lib/manage-booking-post-checkout';
+import type { OrderSummary } from '../../lib/booking/pricing';
+import type { CheckoutModalLineItem } from './CheckoutModal';
+
+export type ChangeBookingSuccessUrlFactory = (params: {
+  reservationRef: string;
+  lastName: string;
+  focusDate?: string;
+}) => string;
+
+export interface ChangeBookingPaidCheckoutModalData {
+  reservationReference: string;
+  reservationExpiration?: string;
+  customerLastName?: string;
+  bookingDate?: string;
+  successUrlOverride?: string;
+  ticketLines: CheckoutModalLineItem[];
+  feeLineItems: OrderSummary['feeLineItems'];
+  returnPriceAdjustment: number;
+  cancellationPolicyFee: number;
+  cancellationPolicyLabel?: string;
+  subtotal: number;
+  tax: number;
+  total: number;
+  promoDiscountAmount?: number;
+  discountLabel?: string | null;
+  totalQuantity: number;
+  isTaxIncludedInPrice: boolean;
+  taxRate: number;
+  changeTotals?: {
+    previousTotal: number;
+    newTotal: number;
+    differenceTotal: number;
+  };
+}
+
+export interface BuildChangeBookingPaymentSuccessUrlParams {
+  enabled: boolean;
+  bookingReference?: string | null;
+  lastName: string;
+  datePart: string;
+  changeIntentId?: string;
+  preferHostSuccessUrl?: boolean;
+  getSuccessUrl?: ChangeBookingSuccessUrlFactory;
+}
+
+export function buildChangeBookingPaymentSuccessUrl({
+  enabled,
+  bookingReference,
+  lastName,
+  datePart,
+  changeIntentId,
+  preferHostSuccessUrl,
+  getSuccessUrl,
+}: BuildChangeBookingPaymentSuccessUrlParams): string | undefined {
+  if (!enabled || !bookingReference) return undefined;
+  const displayRef = formatBookingRefForDisplay(bookingReference) || bookingReference;
+  const trimmedLastName = lastName.trim();
+
+  if (preferHostSuccessUrl && getSuccessUrl) {
+    return getSuccessUrl({
+      reservationRef: displayRef,
+      lastName: trimmedLastName,
+      focusDate: datePart,
+    });
+  }
+
+  const origin = typeof window !== 'undefined' ? window.location.origin : '';
+  const ref = encodeURIComponent(displayRef);
+  const ln = encodeURIComponent(trimmedLastName);
+  const fromQ = `${MANAGE_BOOKING_QUERY_FROM}=${encodeURIComponent(MANAGE_BOOKING_FROM_CHANGE_PAYMENT)}`;
+  const intentQ = changeIntentId ? `&changeIntentId=${encodeURIComponent(changeIntentId)}` : '';
+  return `${origin}/manage-booking?ref=${ref}&lastName=${ln}&${fromQ}${intentQ}`;
+}
+
+export interface BuildChangeBookingPaidCheckoutModalDataParams {
+  bookingReference?: string | null;
+  lastName: string;
+  datePart: string;
+  ticketLines: CheckoutModalLineItem[];
+  feeLineItems: OrderSummary['feeLineItems'];
+  returnPriceAdjustment: number;
+  cancellationPolicyFee: number;
+  cancellationPolicyLabel?: string;
+  subtotal: number;
+  tax: number;
+  total: number;
+  totalQuantity: number;
+  isTaxIncludedInPrice: boolean;
+  taxRate: number;
+  promoDiscountAmount: number;
+  discountLabel?: string | null;
+  previousTotal?: number | null;
+  newTotal?: number | null;
+  successUrl: BuildChangeBookingPaymentSuccessUrlParams;
+}
+
+export function buildChangeBookingPaidCheckoutModalData({
+  bookingReference,
+  lastName,
+  datePart,
+  ticketLines,
+  feeLineItems,
+  returnPriceAdjustment,
+  cancellationPolicyFee,
+  cancellationPolicyLabel,
+  subtotal,
+  tax,
+  total,
+  totalQuantity,
+  isTaxIncludedInPrice,
+  taxRate,
+  promoDiscountAmount,
+  discountLabel,
+  previousTotal,
+  newTotal,
+  successUrl,
+}: BuildChangeBookingPaidCheckoutModalDataParams): ChangeBookingPaidCheckoutModalData {
+  return {
+    reservationReference: bookingReference ?? '',
+    reservationExpiration: undefined,
+    customerLastName: lastName.trim(),
+    bookingDate: datePart,
+    successUrlOverride: buildChangeBookingPaymentSuccessUrl(successUrl),
+    ticketLines,
+    feeLineItems,
+    returnPriceAdjustment,
+    cancellationPolicyFee,
+    cancellationPolicyLabel,
+    subtotal,
+    tax,
+    total,
+    totalQuantity,
+    isTaxIncludedInPrice,
+    taxRate,
+    promoDiscountAmount,
+    discountLabel,
+    changeTotals:
+      previousTotal != null && newTotal != null
+        ? {
+            previousTotal,
+            newTotal,
+            differenceTotal: total,
+          }
+        : undefined,
+  };
+}

package/src/components/booking/change-booking-quote-guards.ts

@@ -0,0 +1,223 @@
+import type { ChangeBookingQuoteResponse } from '../../lib/booking-api';
+import {
+  changeFlowBalanceVsOriginal,
+  normalizeNearZeroOwed,
+  roundMoney,
+  type ChangeQuoteUiSlice,
+} from '../../lib/booking/change-flow-pricing';
+
+const CHANGE_PAYMENT_CONFIRMATION_ERROR =
+  'This change requires payment, but the price could not be confirmed. Please refresh and try again.';
+
+export type ChangeBookingCheckoutQuoteAudience = 'customer' | 'admin';
+
+export type ChangeBookingCheckoutQuoteDecision =
+  | {
+      kind: 'free';
+      changeIntentId: string;
+      amountDueForCheckout: number;
+    }
+  | {
+      kind: 'paid';
+      changeIntentId: string;
+      amountDueForCheckout: number;
+    };
+
+export interface EvaluateChangeBookingQuoteForCheckoutParams {
+  quote: ChangeBookingQuoteResponse;
+  quoteSlice: ChangeQuoteUiSlice;
+  fallbackNewBookingTotal: number;
+  originalReceiptTotal: number;
+  audience: ChangeBookingCheckoutQuoteAudience;
+  useAdminFeAuthoritativeQuote?: boolean;
+  adminFeAmountDueMajorUnits?: number;
+}
+
+function resolveSignedBalanceMajor(quote: ChangeBookingQuoteResponse): number | null {
+  const pricingQuote = quote.pricingQuote ?? quote.quote;
+  if (quote.previousTotalCents != null && quote.newTotalCents != null) {
+    return (quote.newTotalCents - quote.previousTotalCents) / 100;
+  }
+  return quote.balanceDeltaMajorUnits ?? quote.balanceDelta ?? pricingQuote?.balanceDelta ?? null;
+}
+
+function resolveServerNewTotalForGuard({
+  quote,
+  quoteSlice,
+  fallbackNewBookingTotal,
+}: Pick<
+  EvaluateChangeBookingQuoteForCheckoutParams,
+  'quote' | 'quoteSlice' | 'fallbackNewBookingTotal'
+>): number {
+  const pricingQuote = quote.pricingQuote ?? quote.quote;
+  return (
+    quoteSlice.quotedTotal ??
+    pricingQuote?.payableTotal ??
+    pricingQuote?.totalAmount ??
+    quoteSlice.serverDisplay?.total ??
+    quote.proposed?.total ??
+    quote.newReceipt?.total ??
+    fallbackNewBookingTotal
+  );
+}
+
+function resolveAmountDueForCheckout({
+  quote,
+  signedBalanceMajor,
+  audience,
+  useAdminFeAuthoritativeQuote,
+  adminFeAmountDueMajorUnits,
+}: {
+  quote: ChangeBookingQuoteResponse;
+  signedBalanceMajor: number | null;
+  audience: ChangeBookingCheckoutQuoteAudience;
+  useAdminFeAuthoritativeQuote?: boolean;
+  adminFeAmountDueMajorUnits?: number;
+}): number {
+  const pricingQuote = quote.pricingQuote ?? quote.quote;
+  if (useAdminFeAuthoritativeQuote) {
+    return Math.max(0, adminFeAmountDueMajorUnits ?? 0);
+  }
+  if (quote.amountToCharge != null) return quote.amountToCharge;
+  if (pricingQuote?.amountToCharge != null) return pricingQuote.amountToCharge;
+  if (signedBalanceMajor != null) return Math.max(0, signedBalanceMajor);
+  if (quote.amountDueCents != null) {
+    const amountDue = quote.amountDueCents / 100;
+    return audience === 'customer' ? Math.max(0, amountDue) : amountDue;
+  }
+  return Math.max(0, quote.priceDiff ?? 0);
+}
+
+function resolveFeChangeDue({
+  signedBalanceMajor,
+  serverNewTotalForGuard,
+  originalReceiptTotal,
+  audience,
+  useAdminFeAuthoritativeQuote,
+  adminFeAmountDueMajorUnits,
+}: {
+  signedBalanceMajor: number | null;
+  serverNewTotalForGuard: number;
+  originalReceiptTotal: number;
+  audience: ChangeBookingCheckoutQuoteAudience;
+  useAdminFeAuthoritativeQuote?: boolean;
+  adminFeAmountDueMajorUnits?: number;
+}): number {
+  if (useAdminFeAuthoritativeQuote) return adminFeAmountDueMajorUnits ?? 0;
+  if (audience === 'admin' && signedBalanceMajor != null) return signedBalanceMajor;
+  return changeFlowBalanceVsOriginal({
+    newTotal: serverNewTotalForGuard,
+    originalReceiptTotal,
+    audience,
+  });
+}
+
+function assertNoUnconfirmedNoChargeUpgrade({
+  quote,
+  quoteSlice,
+  audience,
+  useAdminFeAuthoritativeQuote,
+}: {
+  quote: ChangeBookingQuoteResponse;
+  quoteSlice: ChangeQuoteUiSlice;
+  audience: ChangeBookingCheckoutQuoteAudience;
+  useAdminFeAuthoritativeQuote?: boolean;
+}): void {
+  const pricingQuote = quote.pricingQuote ?? quote.quote;
+
+  if (audience === 'admin') {
+    const upgradeWithoutCharge =
+      !useAdminFeAuthoritativeQuote &&
+      quote.newTotalCents != null &&
+      quote.previousTotalCents != null &&
+      quote.newTotalCents > quote.previousTotalCents + 1;
+    if (upgradeWithoutCharge) throw new Error(CHANGE_PAYMENT_CONFIRMATION_ERROR);
+    return;
+  }
+
+  const proposedTotal =
+    quoteSlice.quotedTotal ??
+    pricingQuote?.payableTotal ??
+    pricingQuote?.totalAmount ??
+    quote.proposed?.total ??
+    quote.newReceipt?.total;
+  const originalTotal =
+    pricingQuote?.amountPreviouslyPaid ?? quote.original?.total ?? quote.originalReceipt?.total;
+  if (proposedTotal != null && originalTotal != null && proposedTotal - originalTotal > 0.01) {
+    throw new Error(CHANGE_PAYMENT_CONFIRMATION_ERROR);
+  }
+}
+
+export function evaluateChangeBookingQuoteForCheckout(
+  params: EvaluateChangeBookingQuoteForCheckoutParams
+): ChangeBookingCheckoutQuoteDecision {
+  const {
+    quote,
+    quoteSlice,
+    fallbackNewBookingTotal,
+    originalReceiptTotal,
+    audience,
+    useAdminFeAuthoritativeQuote,
+    adminFeAmountDueMajorUnits,
+  } = params;
+
+  if (!quoteSlice.canProceed) {
+    throw new Error(quote.reasonIfBlocked || 'This booking change cannot be completed right now.');
+  }
+
+  const signedBalanceMajor = resolveSignedBalanceMajor(quote);
+  const serverNewTotalForGuard = resolveServerNewTotalForGuard({
+    quote,
+    quoteSlice,
+    fallbackNewBookingTotal,
+  });
+  const amountDue = resolveAmountDueForCheckout({
+    quote,
+    signedBalanceMajor,
+    audience,
+    useAdminFeAuthoritativeQuote,
+    adminFeAmountDueMajorUnits,
+  });
+  const feChangeDue = resolveFeChangeDue({
+    signedBalanceMajor,
+    serverNewTotalForGuard,
+    originalReceiptTotal,
+    audience,
+    useAdminFeAuthoritativeQuote,
+    adminFeAmountDueMajorUnits,
+  });
+  const amountDueForCheckout =
+    audience === 'admin' ? normalizeNearZeroOwed(roundMoney(amountDue)) : amountDue;
+
+  if (feChangeDue > 0.02 && amountDue <= 0.009) {
+    throw new Error(CHANGE_PAYMENT_CONFIRMATION_ERROR);
+  }
+
+  if (amountDue <= 0.009) {
+    if (feChangeDue > 0.02) throw new Error(CHANGE_PAYMENT_CONFIRMATION_ERROR);
+    assertNoUnconfirmedNoChargeUpgrade({
+      quote,
+      quoteSlice,
+      audience,
+      useAdminFeAuthoritativeQuote,
+    });
+    if (!quote.changeIntentId) {
+      throw new Error('Missing change intent for booking change confirmation.');
+    }
+    return {
+      kind: 'free',
+      changeIntentId: quote.changeIntentId,
+      amountDueForCheckout,
+    };
+  }
+
+  const paidChangeIntentId = quoteSlice.changeIntentId;
+  if (!paidChangeIntentId) {
+    throw new Error('Missing change intent for payment.');
+  }
+  return {
+    kind: 'paid',
+    changeIntentId: paidChangeIntentId,
+    amountDueForCheckout,
+  };
+}

package/src/components/booking/change-booking-quote-state.ts

@@ -0,0 +1,64 @@
+import type { ChangeBookingQuoteResponse } from '../../lib/booking-api';
+import {
+  type ChangeQuoteUiSlice,
+  sliceChangeQuoteForUi,
+} from '../../lib/booking/change-flow-pricing';
+import {
+  normalizePricingDriftDetailFromQuote,
+  normalizeTicketPricingTraceFromQuote,
+} from '../../lib/booking/change-booking-pricing-drift';
+import {
+  buildChangeBookingServerPreview,
+} from '../../lib/booking/change-booking-server-preview';
+import type { Currency } from './CurrencySwitcher';
+
+export type ChangeBookingServerPreview = ReturnType<typeof buildChangeBookingServerPreview>;
+export type ChangeBookingMergedQuoteState = ReturnType<typeof mergeQuoteSliceWithServerPreview>;
+
+export function mergeQuoteSliceWithServerPreview(
+  slice: ChangeQuoteUiSlice,
+  quote: ChangeBookingQuoteResponse,
+  fallbackCart: { total: number; subtotal: number; tax: number },
+  currency: Currency,
+) {
+  return {
+    ...slice,
+    currency: (slice.currency || currency) as Currency,
+    serverPreview: buildChangeBookingServerPreview(quote, fallbackCart, currency),
+    pricingDriftDetail: normalizePricingDriftDetailFromQuote(quote),
+    ticketPricingTrace: normalizeTicketPricingTraceFromQuote(quote),
+    /** Same cent pair the BE uses for `amountDueCents` / intent & receipt "New Booking Difference". */
+    quotePreviousTotalCents: quote.previousTotalCents,
+    quoteNewTotalCents: quote.newTotalCents,
+  };
+}
+
+export function sliceAndMergeChangeQuoteForUi(
+  quote: ChangeBookingQuoteResponse,
+  fallbackCart: { total: number; subtotal: number; tax: number },
+  currency: Currency,
+): { quoteSlice: ChangeQuoteUiSlice; mergedQuote: ChangeBookingMergedQuoteState } {
+  const quoteSlice = sliceChangeQuoteForUi(quote, fallbackCart, currency);
+  return {
+    quoteSlice,
+    mergedQuote: mergeQuoteSliceWithServerPreview(quoteSlice, quote, fallbackCart, currency),
+  };
+}
+
+export function resolveConfirmedChangeNewTotalForCheckout({
+  quote,
+  quoteSlice,
+  fallbackNewBookingTotal,
+}: {
+  quote: ChangeBookingQuoteResponse;
+  quoteSlice: ChangeQuoteUiSlice;
+  fallbackNewBookingTotal: number;
+}): number {
+  return (
+    quoteSlice.serverDisplay?.total ??
+    quoteSlice.quotedTotal ??
+    quote.proposed?.total ??
+    quote.newReceipt?.total ??
+    fallbackNewBookingTotal
+  );
+}

package/src/components/booking/pricing-v2-checkout-summary.ts

@@ -0,0 +1,144 @@
+import type {
+  PricingV2QuoteLineSnapshot,
+  PricingV2QuoteSnapshot,
+} from "../../lib/booking-api";
+import {
+  pricingV2QuoteTotal,
+  round2,
+} from "../../lib/booking/checkout-breakdown";
+import type { CheckoutModalSummaryOverride } from "./CheckoutModal";
+import type { PriceSummaryLine } from "./PriceSummary";
+
+function finiteNumber(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function normalizedLineType(type?: string | null): string {
+  const normalized = (type ?? "").trim().toUpperCase();
+  if (!normalized) return "FEE";
+  if (normalized === "RETURN") return "RETURN_OPTION";
+  if (normalized === "RETURNOPTION") return "RETURN_OPTION";
+  return normalized;
+}
+
+function fallbackLabel(type: string): string {
+  switch (type) {
+    case "TAX":
+      return "Taxes and fees";
+    case "PROMO_CODE":
+    case "DISCOUNT":
+    case "DEAL":
+      return "Discount";
+    case "GIFT_CARD":
+    case "PAYMENT_CREDIT":
+      return "Gift card comp";
+    case "RETURN_OPTION":
+      return "Return option";
+    case "CANCELLATION_UPGRADE":
+      return "Cancellation upgrade";
+    case "TICKET":
+      return "Ticket";
+    default:
+      return "Fee";
+  }
+}
+
+function priceSummaryLineFromQuoteLine(
+  line: PricingV2QuoteLineSnapshot,
+  index: number,
+): PriceSummaryLine | null {
+  if (line.billable === false) return null;
+  const amount = finiteNumber(line.amount);
+  if (amount == null) return null;
+
+  const type = normalizedLineType(line.type);
+  const label = line.label?.trim() || fallbackLabel(type);
+  const quantity = finiteNumber(line.quantity);
+
+  if (type === "TICKET") {
+    return {
+      kind: "ticket",
+      lineKey: line.lineId ?? `pricing-v2-ticket-${index}`,
+      category: label,
+      qty: Math.max(1, Math.round(quantity ?? 1)),
+      itemTotal: round2(amount),
+      breakdown: null,
+    };
+  }
+
+  return {
+    kind: "line",
+    lineKey: line.lineId ?? `pricing-v2-line-${index}`,
+    label,
+    amount: round2(amount),
+    type,
+    quantity: quantity == null ? undefined : Math.max(1, Math.round(quantity)),
+  };
+}
+
+export function buildCheckoutModalSummaryFromPricingV2Quote(
+  quote: PricingV2QuoteSnapshot | null | undefined,
+  roundingLabel: string,
+): CheckoutModalSummaryOverride | undefined {
+  const total = pricingV2QuoteTotal(quote);
+  if (total == null) return undefined;
+
+  const lines =
+    quote?.lines
+      ?.map((line, index) => priceSummaryLineFromQuoteLine(line, index))
+      .filter((line): line is PriceSummaryLine => line != null) ?? [];
+
+  if (lines.length === 0) return undefined;
+
+  const lineTotal = round2(
+    lines.reduce((sum, line) => {
+      if (line.kind === "ticket") return sum + line.itemTotal;
+      return sum + line.amount;
+    }, 0),
+  );
+  const roundingDelta = round2(total - lineTotal);
+  if (Math.abs(roundingDelta) > 0.02) {
+    lines.push({
+      kind: "line",
+      lineKey: "pricing-v2-rounding",
+      label: roundingLabel,
+      amount: roundingDelta,
+      type: "ROUNDING",
+    });
+  }
+
+  const hasTaxLine = lines.some(
+    (line) => line.kind === "line" && normalizedLineType(line.type) === "TAX",
+  );
+  const hasDiscountLine = lines.some((line) => {
+    if (line.kind !== "line") return false;
+    const type = normalizedLineType(line.type);
+    return (
+      line.amount < 0 ||
+      type === "PROMO_CODE" ||
+      type === "DISCOUNT" ||
+      type === "DEAL" ||
+      type === "GIFT_CARD" ||
+      type === "PAYMENT_CREDIT"
+    );
+  });
+  const subtotal = finiteNumber(
+    quote?.netSubtotalBeforeTax ?? quote?.subtotal ?? quote?.grossSubtotal,
+  );
+  const taxAmount = hasTaxLine
+    ? 0
+    : Math.max(0, finiteNumber(quote?.taxAmount ?? quote?.tax) ?? 0);
+  const discountAmount = hasDiscountLine
+    ? 0
+    : Math.max(0, finiteNumber(quote?.discountTotal) ?? 0);
+
+  return {
+    lines,
+    subtotal: subtotal == null ? undefined : round2(subtotal),
+    taxAmount: round2(taxAmount),
+    discountAmount: round2(discountAmount),
+    fullTotalAmount: round2(
+      finiteNumber(quote?.payableTotal ?? quote?.totalAmount) ?? total,
+    ),
+  };
+}

package/src/components/booking/private-shuttle-availability.ts

@@ -0,0 +1,111 @@
+import { parseISO } from 'date-fns';
+import { formatInTimeZone, fromZonedTime } from 'date-fns-tz';
+
+import type { Availability } from '../../lib/booking-api';
+import {
+  isDateAfterPublicBookingCutoff,
+  resolvePublicBookingCutoffMinutes,
+} from '../../lib/booking/booking-cutoffs';
+import type { Currency } from './CurrencySwitcher';
+
+const DATE_ONLY_REGEX = /^\d{4}-\d{2}-\d{2}$/;
+
+export function roundMoney(amount: number): number {
+  return Math.round(amount * 100) / 100;
+}
+
+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 privateShuttleStartDateTime(dateStr: string, timeStr: string, timezone: string): Date {
+  return fromZonedTime(parseISO(`${dateStr}T${timeStr}:00`), timezone);
+}
+
+export function privateShuttleStartTimeAllowed(
+  dateStr: string,
+  timeStr: string,
+  timezone: string,
+  now: Date,
+  cutoffMinutes?: number | null,
+): boolean {
+  return isDateAfterPublicBookingCutoff(
+    privateShuttleStartDateTime(dateStr, timeStr, timezone),
+    now,
+    cutoffMinutes,
+  );
+}
+
+export function privateShuttleBookingCutoffMessage(cutoffMinutes?: number | null): string {
+  const resolvedCutoffMinutes = resolvePublicBookingCutoffMinutes(cutoffMinutes);
+  if (resolvedCutoffMinutes % 60 === 0) {
+    return `Private shuttles must be booked at least ${resolvedCutoffMinutes / 60} hours before departure.`;
+  }
+  return `Private shuttles must be booked at least ${resolvedCutoffMinutes} minutes before departure.`;
+}
+
+export function privateShuttleAvailabilityDateInZone(
+  availability: Availability,
+  timezone: string,
+): string {
+  return DATE_ONLY_REGEX.test(availability.dateTime)
+    ? availability.dateTime
+    : formatInTimeZone(parseAvailabilityDateTime(availability.dateTime), timezone, 'yyyy-MM-dd');
+}
+
+export function findMergedPrivateShuttleAvailability(
+  merged: Availability[],
+  sel: Availability | null,
+  optionId: string | null,
+  selectedDateStr: string | null,
+  tz: string
+): Availability | undefined {
+  if (!sel || !optionId || !selectedDateStr) return undefined;
+  const oidMatches = (a: Availability) => getPrivateShuttleAvailabilityOptionId(a) === optionId;
+  const availId = sel.availabilityId?.trim();
+  if (availId) {
+    const hit = merged.find((a) => a.availabilityId === availId && oidMatches(a));
+    if (hit) return hit;
+  }
+  const onDay = merged.filter((a) => {
+    if (!oidMatches(a)) return false;
+    return privateShuttleAvailabilityDateInZone(a, tz) === selectedDateStr;
+  });
+  return onDay[0];
+}
+
+export function getPrivateShuttleAvailabilityOptionId(availability: Availability): string {
+  const productOptionId = availability.productOptionId?.trim();
+  if (productOptionId) return productOptionId;
+  const productId = availability.productId?.trim();
+  return productId?.startsWith('po_') ? productId : '';
+}
+
+export function getPrivateShuttleAvailabilityCacheKey(availability: Availability): string {
+  return `${availability.dateTime}-${getPrivateShuttleAvailabilityOptionId(availability)}`;
+}
+
+export function getResourceRate(availability: Availability | undefined | null) {
+  return availability?.rates?.find((r) => r.rateId === 'RESOURCE' || r.category === 'RESOURCE');
+}
+
+export function applyResourceAdjustments(
+  basePrice: number,
+  availability: Availability | undefined | null,
+  currency: Currency
+): number {
+  const resourceRate = getResourceRate(availability);
+  const adjustmentTotal =
+    resourceRate?.appliedAdjustments?.reduce(
+      (sum, adjustment) => sum + (adjustment.changeByCurrency?.[currency] ?? 0),
+      0
+    ) ??
+    resourceRate?.applied_adjustments?.reduce(
+      (sum, adjustment) => sum + (adjustment.changeByCurrency?.[currency] ?? 0),
+      0
+    ) ??
+    0;
+  return basePrice + adjustmentTotal;
+}