@ticketboothapp/booking 1.2.25-rc.0 → 1.2.27

package/src/lib/booking-api.ts

@@ -1,1793 +0,0 @@
-/**
- * API helpers for booking flow and manage-booking
- * Uses TicketBooth backend (api.ticketboothapp.com or localhost)
- */
-
-import {
-  BOOKING_CORRELATION_HEADER,
-  getOrCreateBookingCorrelationId,
-} from '@/lib/booking/correlation-id';
-import {
-  buildTraceparent,
-  traceIdFromTraceparent,
-  withBookingOutboundHeaders,
-} from '@/lib/booking/trace-context';
-import {
-  normalizeAvailabilityLookupId,
-  normalizeBookingProductId,
-} from '@/lib/booking/normalize-booking-product-id';
-import { ENV } from '@/lib/env';
-import { DEFAULT_BOOKING_SOURCE, type BookingSourceMetadata } from '@/lib/booking/source-metadata';
-
-const API_BASE = ENV.API_URL;
-
-/** When set (e.g. booking-portal partner session), reserve/checkout use Bearer instead of Basic. */
-let partnerPortalBookingJwtGetter: () => string | null = () => null;
-
-export function setPartnerPortalBookingJwtGetter(fn: () => string | null): void {
-  partnerPortalBookingJwtGetter = fn;
-}
-
-interface ApiErrorPayload {
-  errorCode?: string;
-  errorMessage?: string;
-  error?: string;
-}
-
-function isApiErrorPayload(value: unknown): value is ApiErrorPayload {
-  return typeof value === 'object' && value !== null;
-}
-
-async function parseJsonSafely(res: Response): Promise<unknown> {
-  try {
-    return await res.json();
-  } catch {
-    return null;
-  }
-}
-
-type BookingClientErrorClass = 'NETWORK' | 'HTTP' | 'APP_ERROR_200';
-
-/** Thrown by booking-api helpers; includes API error details for UX branching (e.g. capacity conflicts). */
-export type BookingClientError = Error & {
-  debugMessage?: string;
-  bookingApiErrorCode?: string;
-};
-
-function getUserFacingMessage(endpoint: string): string {
-  switch (endpoint) {
-    case '/1/get-availabilities':
-      return 'Unable to load available times right now. Please try again.';
-    case '/1/products':
-      return 'Unable to load booking options right now. Please try again.';
-    case '/1/reserve':
-      return 'Unable to hold your booking right now. Please try again.';
-    case '/checkout/payment-intent':
-      return 'Unable to continue to payment right now. Please try again.';
-    default:
-      return 'Something went wrong while loading booking details. Please try again.';
-  }
-}
-
-function buildSupportCode(endpoint: string, errorClass: BookingClientErrorClass): string {
-  const endpointCode = endpoint
-    .replace(/^\//, '')
-    .replace(/[^a-zA-Z0-9]+/g, '-')
-    .toUpperCase();
-  return `BD-${errorClass}-${endpointCode}`;
-}
-
-function logBookingApiNetworkError(endpoint: string, err: unknown): void {
-  if (typeof window === 'undefined') return;
-  const details = {
-    endpoint,
-    apiBase: API_BASE,
-    online: window.navigator.onLine,
-    userAgent: window.navigator.userAgent,
-    error: err instanceof Error ? err.message : String(err),
-  };
-  console.error('[booking-api] Network request failed', details);
-}
-
-/** Shared client → API `/1/client-telemetry` sender (never throws). */
-function reportBookingClientTelemetryEvent(
-  eventName: string,
-  fields: Record<string, unknown>
-): void {
-  if (typeof window === 'undefined') return;
-  const telemetryEndpoint = `${API_BASE}/1/client-telemetry`;
-  const correlationId = getOrCreateBookingCorrelationId();
-  const traceparent = buildTraceparent();
-  const traceId = traceIdFromTraceparent(traceparent);
-  const event = {
-    event: eventName,
-    correlationId,
-    traceparent,
-    ...(traceId ? { traceId } : {}),
-    apiBase: API_BASE,
-    pageUrl: window.location.href,
-    userAgent: window.navigator.userAgent,
-    online: window.navigator.onLine,
-    occurredAt: new Date().toISOString(),
-    ...fields,
-  };
-  fetch(telemetryEndpoint, {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      ...(correlationId ? { [BOOKING_CORRELATION_HEADER]: correlationId } : {}),
-      traceparent,
-    },
-    body: JSON.stringify(event),
-    keepalive: true,
-  }).catch(() => {
-    // Never throw from telemetry reporting.
-  });
-}
-
-function reportClientFetchError(payload: {
-  endpoint: string;
-  errorClass: BookingClientErrorClass;
-  message: string;
-  httpStatus?: number;
-  errorCode?: string;
-  /** Structured context for dashboards (reserve failures, etc.). */
-  metadata?: Record<string, unknown>;
-}): void {
-  reportBookingClientTelemetryEvent('BOOKING_DIALOG_CLIENT_FETCH_ERROR', {
-    endpoint: payload.endpoint,
-    errorClass: payload.errorClass,
-    message: payload.message,
-    httpStatus: payload.httpStatus,
-    errorCode: payload.errorCode,
-    ...(payload.metadata && Object.keys(payload.metadata).length > 0
-      ? { metadata: payload.metadata }
-      : {}),
-  });
-}
-
-function isInsufficientCapacityApiError(errorCode?: string, errorMessage?: string): boolean {
-  const msg = (errorMessage ?? '').toLowerCase();
-  return errorCode === 'VALIDATION_FAILURE' && msg.includes('insufficient capacity');
-}
-
-/**
- * After a reserve failure + availabilities reload, records what the UI believes inventory is now.
- * Pairs with `BOOKING_DIALOG_CLIENT_FETCH_ERROR` from the same correlation/session for debugging races.
- */
-export function reportReserveCapacityConflictClientContext(payload: {
-  flow: 'standard_tour' | 'private_shuttle';
-  productId?: string;
-  selectedDate?: string | null;
-  outboundDateTime?: string | null;
-  outboundVacanciesAfterRefresh: number | null;
-  returnVacanciesAfterRefresh: number | null;
-  partySizeOrPassengers: number;
-  hasReturnSelection?: boolean;
-  returnAvailabilityId?: string | null;
-  reloadAvailabilitiesSucceeded: boolean;
-  reloadErrorMessage?: string;
-}): void {
-  reportBookingClientTelemetryEvent('BOOKING_RESERVE_CAPACITY_CONFLICT_CONTEXT', {
-    severity: 'critical_booking_path',
-    issue: 'reserve_failed_inventory_race',
-    ...payload,
-  });
-}
-
-function createUserError(
-  endpoint: string,
-  errorClass: BookingClientErrorClass,
-  debugMessage: string,
-  bookingApiErrorCode?: string
-): BookingClientError {
-  const supportCode = buildSupportCode(endpoint, errorClass);
-  const userMessage = `${getUserFacingMessage(endpoint)} (${supportCode})`;
-  const error = new Error(userMessage) as BookingClientError;
-  error.debugMessage = debugMessage;
-  if (bookingApiErrorCode) error.bookingApiErrorCode = bookingApiErrorCode;
-  return error;
-}
-
-/** Reserve failed because inventory changed (race) — API returns VALIDATION_FAILURE + insufficient capacity message. */
-export function isInsufficientCapacityReserveError(err: unknown): boolean {
-  if (!(err instanceof Error)) return false;
-  const bookingErr = err as BookingClientError;
-  const msg = (bookingErr.debugMessage ?? '').toLowerCase();
-  return (
-    bookingErr.bookingApiErrorCode === 'VALIDATION_FAILURE' &&
-    msg.includes('insufficient capacity')
-  );
-}
-
-/** Standard tour: explain which leg(s) are short after a fresh availabilities reload. */
-export function describeStandardTourCapacityConflictMessage(params: {
-  partySize: number;
-  outboundVacancies: number | null;
-  returnVacancies: number | null;
-  hasReturnSelection: boolean;
-}): string {
-  const { partySize, outboundVacancies, returnVacancies, hasReturnSelection } = params;
-  const people = partySize === 1 ? 'person' : 'people';
-  const weakOut =
-    outboundVacancies != null && outboundVacancies < partySize ? outboundVacancies : null;
-  const weakRet =
-    hasReturnSelection && returnVacancies != null && returnVacancies < partySize
-      ? returnVacancies
-      : null;
-
-  if (weakOut != null || weakRet != null) {
-    const bits: string[] = [];
-    if (weakOut != null) {
-      bits.push(
-        weakOut === 0
-          ? 'your outbound departure is now full'
-          : `your outbound departure only has ${weakOut} spot${weakOut === 1 ? '' : 's'} left`
-      );
-    }
-    if (weakRet != null) {
-      bits.push(
-        weakRet === 0
-          ? 'your return trip is now full'
-          : `your return trip only has ${weakRet} spot${weakRet === 1 ? '' : 's'} left`
-      );
-    }
-    return `Not enough seats for ${partySize} ${people}: ${bits.join(
-      '; '
-    )}. Please choose another departure or return time, pick another date, or reduce the number of tickets.`;
-  }
-
-  return `We're sorry, our availability changed while you were making your selections — we could not reserve enough space for your group (${partySize} ${people}). Please choose another date or time, or reduce the number of tickets, then try again.`;
-}
-
-export function describePrivateShuttleCapacityConflictMessage(params: {
-  passengersRequested: number;
-  vacancies: number | null;
-}): string {
-  const { passengersRequested, vacancies } = params;
-  if (vacancies != null) {
-    if (vacancies === 0) {
-      return `This departure just sold out. Please pick another date or start time (you had ${passengersRequested} passenger${
-        passengersRequested === 1 ? '' : 's'
-      }).`;
-    }
-    if (vacancies < passengersRequested) {
-      return `Only ${vacancies} spot${vacancies === 1 ? '' : 's'} remain for this departure, but you need space for ${passengersRequested} passenger${
-        passengersRequested === 1 ? '' : 's'
-      }. Try a different date or time, reduce the passenger count, or split the booking.`;
-    }
-  }
-  return `We're sorry, our availability changed while you were making your selections — we could not reserve enough space for ${passengersRequested} passenger${
-    passengersRequested === 1 ? '' : 's'
-  }. Please pick another date or time or adjust the passenger count.`;
-}
-
-function toHttpErrorMessage(
-  endpoint: string,
-  status: number,
-  payload: unknown,
-  fallback: string
-): string {
-  if (isApiErrorPayload(payload)) {
-    return payload.errorMessage || payload.error || `${fallback} (HTTP ${status})`;
-  }
-  return `${fallback} (HTTP ${status})`;
-}
-
-function toAppLevelErrorMessage(
-  endpoint: string,
-  payload: unknown,
-  fallback: string
-): string | null {
-  if (!isApiErrorPayload(payload) || (!payload.errorCode && !payload.errorMessage && !payload.error)) {
-    return null;
-  }
-  const message = payload.errorMessage || payload.error || fallback;
-  const codeSuffix = payload.errorCode ? ` [${payload.errorCode}]` : '';
-  return `${message}${codeSuffix} (endpoint: ${endpoint})`;
-}
-
-/**
- * Ensures checkout/reserve payloads always include `source` so the API never falls back to header-only auto-detect.
- * Booking UIs that compose attribution (main site, `/partner/…` pages, dedicated partner portal on `booking.*`) normally
- * send `source` (e.g. `PARTNER_PORTAL` or `WEBSITE`) and `sourceMetadata` explicitly; this only supplies
- * {@link DEFAULT_BOOKING_SOURCE} when `source` is missing.
- */
-function withExplicitBookingSource<T extends { source?: string }>(request: T): T & { source: string } {
-  const s = request.source?.trim();
-  if (s) return { ...request, source: s };
-  return { ...request, source: DEFAULT_BOOKING_SOURCE };
-}
-
-function logBookingSourceDebug(
-  stage: 'request' | 'response' | 'error',
-  endpoint: string,
-  payload: unknown
-): void {
-  if (typeof window === 'undefined') return;
-  const prefix = `[booking-source-debug] ${stage} ${endpoint}`;
-  try {
-    if (payload && typeof payload === 'object') {
-      const maybe = payload as {
-        source?: string;
-        sourceMetadata?: {
-          pagePath?: string;
-          pageUrl?: string;
-          partnerId?: string;
-          utmSource?: string;
-          utmMedium?: string;
-          utmCampaign?: string;
-        };
-        source_metadata?: {
-          pagePath?: string;
-          pageUrl?: string;
-          partnerId?: string;
-          utmSource?: string;
-          utmMedium?: string;
-          utmCampaign?: string;
-        };
-      };
-      const md = maybe.sourceMetadata ?? maybe.source_metadata;
-      if (md) {
-        console.info(
-          `${prefix} summary source=${maybe.source ?? 'n/a'} path=${md.pagePath ?? 'n/a'} partner=${md.partnerId ?? 'n/a'} utm_source=${md.utmSource ?? 'n/a'} utm_medium=${md.utmMedium ?? 'n/a'} utm_campaign=${md.utmCampaign ?? 'n/a'}`
-        );
-      }
-    }
-    console.info(`${prefix} payload\n${JSON.stringify(payload, null, 2)}`);
-  } catch {
-    console.info(prefix, payload);
-  }
-}
-
-function getAuthHeaders(): Record<string, string> {
-  const headers: Record<string, string> = { 'Content-Type': 'application/json' };
-  const partnerJwt = partnerPortalBookingJwtGetter();
-  if (partnerJwt) {
-    headers['Authorization'] = `Bearer ${partnerJwt}`;
-    return withBookingOutboundHeaders(headers);
-  }
-  if (ENV.BASIC_AUTH) {
-    headers['Authorization'] = `Basic ${ENV.BASIC_AUTH}`;
-  }
-  return withBookingOutboundHeaders(headers);
-}
-
-/** Idempotent GET retries: transient network errors and 502/503/504 (new trace span each attempt). */
-const BOOKING_GET_MAX_RETRIES = 2;
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-async function fetchBookingGetWithRetry(
-  url: string,
-  extra?: Pick<RequestInit, 'cache' | 'signal'>,
-): Promise<Response> {
-  let lastErr: unknown;
-  for (let attempt = 0; attempt <= BOOKING_GET_MAX_RETRIES; attempt++) {
-    if (attempt > 0) {
-      await sleep(250 * attempt);
-    }
-    try {
-      const res = await fetch(url, {
-        ...extra,
-        method: 'GET',
-        headers: getAuthHeaders(),
-      });
-      if (res.ok) {
-        return res;
-      }
-      if (
-        attempt < BOOKING_GET_MAX_RETRIES &&
-        (res.status === 502 || res.status === 503 || res.status === 504)
-      ) {
-        continue;
-      }
-      return res;
-    } catch (e) {
-      lastErr = e;
-      if (attempt < BOOKING_GET_MAX_RETRIES) {
-        continue;
-      }
-      throw e;
-    }
-  }
-  throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
-}
-
-export interface PickupLocation {
-  id: string;
-  name: string;
-  address: string;
-  coordinates?: { lat: number; lng: number };
-  pickupTimeOffsetMinutes?: number;
-  travelMinutesFromDestination?: Record<string, number>;
-  freeParking?: boolean;
-  notes?: string;
-  driverNotes?: string;
-}
-
-export interface ItineraryItem {
-  destinationName: string;
-  travelTimeFromPreviousHours: number;
-  durationHours?: number;
-}
-
-export interface ItineraryOverride {
-  startDate: string;
-  endDate: string;
-  itinerary: ItineraryItem[];
-}
-
-export interface ProductOption {
-  optionId: string;
-  name: string;
-  description: string | null;
-  pricing: Record<string, number>;
-  status: string;
-  mostPopular?: boolean;
-  itinerary?: ItineraryItem[];
-  itineraryOverrides?: ItineraryOverride[];
-  /** Private Shuttle only: config for start times, duration, deposit, itinerary builder */
-  privateShuttleConfig?: {
-    baseDurationMinutes: number;
-    suggestedStartTimes: string[];
-    depositConfig?: { percentage?: number; fixedAmount?: number };
-    balanceChargeDaysBefore?: number;
-    itineraryBuilderConfig?: {
-      optionBlacklist: string[];
-      defaultDestinations?: string[];
-    };
-  };
-}
-
-export interface ItineraryBuilderDestination {
-  id: string;
-  label: string;
-  latitude: number;
-  longitude: number;
-}
-
-export interface ItineraryBuilder {
-  destinations: ItineraryBuilderDestination[];
-}
-
-export interface Destination {
-  name: string;
-  latitude: number;
-  longitude: number;
-}
-
-export interface Product {
-  productId: string;
-  companyId?: string;
-  name: string;
-  description: string | null;
-  status: string;
-  mostPopular?: boolean;
-  productType?: 'STANDARD' | 'PRIVATE_SHUTTLE';
-  options: ProductOption[];
-  minPriceByCurrency?: Record<string, number>;
-  pickupLocations?: PickupLocation[];
-  destinations?: Destination[];
-  /** Private Shuttle only: shared destinations for itinerary builder */
-  itineraryBuilder?: ItineraryBuilder;
-}
-
-export interface AddOnVariant {
-  id: string;
-  label: string;
-  priceAdjustment: number;
-}
-
-export interface AddOn {
-  addOnId: string;
-  name: string;
-  description?: string | null;
-  price: number;
-  currency: string;
-  preCheckout: boolean;
-  postCheckout: boolean;
-  variantType: 'none' | 'single_choice' | 'multi_quantity';
-  variants: AddOnVariant[];
-  productOptionIds: string[];
-}
-
-export interface CompanySettings {
-  currency?: string;
-  timezone?: string;
-}
-
-export interface Company {
-  companyId: string;
-  name: string;
-  status: string;
-  settings?: CompanySettings;
-}
-
-export const ItineraryStepType = {
-  pickup: 'pickup',
-  arrive: 'arrive',
-  depart: 'depart',
-  drop_off: 'drop_off',
-  trip_end: 'trip_end',
-  draft: 'draft',
-  other: 'other',
-} as const;
-export type ItineraryStepType = (typeof ItineraryStepType)[keyof typeof ItineraryStepType];
-
-export interface ItineraryDisplayStep {
-  stepType: ItineraryStepType;
-  time: string;
-  place?: string | null;
-}
-
-export interface RefundTierOption {
-  hoursBefore: number;
-  refundPercent: number;
-}
-
-export interface CancellationPolicyOption {
-  id: string;
-  label: string;
-  feeByCurrency: Record<string, number>;
-  refundTiers?: RefundTierOption[];
-  changeWindowHoursBefore?: number | null;
-}
-
-export interface PricingConfig {
-  /** Combined GST/tax + service charge on pre-tax subtotal (from backend pricing config). */
-  taxRate: number;
-  currenciesWithTaxIncluded: string[];
-  fees?: Record<string, { feePerPerson: number; description?: string }>;
-  feesByCurrency?: Record<string, Record<string, number>>;
-  exchangeRates?: Record<string, number>;
-  cancellationPolicies?: CancellationPolicyOption[];
-}
-
-export async function fetchProducts(companyId: string): Promise<Product[]> {
-  const endpoint = '/1/products';
-  const url = `${API_BASE}${endpoint}?companyId=${encodeURIComponent(companyId)}`;
-  let res: Response;
-  try {
-    res = await fetchBookingGetWithRetry(url);
-  } catch (err) {
-    logBookingApiNetworkError(endpoint, err);
-    const debugMessage = err instanceof Error ? err.message : String(err);
-    reportClientFetchError({
-      endpoint,
-      errorClass: 'NETWORK',
-      message: debugMessage,
-    });
-    throw createUserError(endpoint, 'NETWORK', debugMessage);
-  }
-
-  if (!res.ok) {
-    const errPayload = await parseJsonSafely(res);
-    const debugMessage = toHttpErrorMessage(endpoint, res.status, errPayload, 'Failed to fetch products');
-    reportClientFetchError({
-      endpoint,
-      errorClass: 'HTTP',
-      message: debugMessage,
-      httpStatus: res.status,
-      errorCode: isApiErrorPayload(errPayload) ? errPayload.errorCode : undefined,
-    });
-    throw createUserError(endpoint, 'HTTP', debugMessage);
-  }
-
-  const data = await parseJsonSafely(res);
-  const appError = toAppLevelErrorMessage(endpoint, data, 'Failed to fetch products');
-  if (appError) {
-    reportClientFetchError({
-      endpoint,
-      errorClass: 'APP_ERROR_200',
-      message: appError,
-      errorCode: isApiErrorPayload(data) ? data.errorCode : undefined,
-    });
-    throw createUserError(endpoint, 'APP_ERROR_200', appError);
-  }
-
-  const products = (data as { data?: { products?: Product[] } } | null)?.data?.products;
-  return products ?? [];
-}
-
-export async function getProduct(productId: string, companyId: string): Promise<Product | null> {
-  const products = await fetchProducts(companyId);
-  return products.find((p) => p.productId === productId) ?? null;
-}
-
-export async function getCompany(companyId: string): Promise<Company> {
-  const res = await fetchBookingGetWithRetry(
-    `${API_BASE}/1/companies/${encodeURIComponent(companyId)}`,
-  );
-  if (!res.ok) {
-    const err = await res.json();
-    throw new Error(err.errorMessage || err.error || 'Failed to get company');
-  }
-  const data = await res.json();
-  return data.data?.company ?? null;
-}
-
-export interface ValidatePromoResponse {
-  valid: boolean;
-  name?: string;
-  error?: string;
-  /** When set, this promo forces the user to use this cancellation policy. Frontend should auto-select and optionally hide the selector. */
-  forcedCancellationPolicyId?: string | null;
-  /** Label for the forced policy (for display when policy has show_at_checkout=false). */
-  forcedCancellationPolicyLabel?: string | null;
-  /** Refund tiers for the forced policy (for display). */
-  forcedCancellationPolicyRefundTiers?: RefundTierOption[];
-  /** Change window in hours before booking (for "make changes x days before" when no refund tiers). */
-  forcedChangeWindowHoursBefore?: number | null;
-}
-
-export async function validatePromoCode(
-  promoCode: string,
-  companyId: string,
-  productId?: string,
-  hasOngoingDiscount?: boolean
-): Promise<ValidatePromoResponse> {
-  const params = new URLSearchParams({ promoCode: promoCode.trim(), companyId });
-  const normalizedProductId = productId?.trim()
-    ? normalizeBookingProductId(productId)
-    : '';
-  if (normalizedProductId) params.set('productId', normalizedProductId);
-  if (hasOngoingDiscount === true) params.set('hasOngoingDiscount', 'true');
-  const res = await fetchBookingGetWithRetry(`${API_BASE}/1/validate-promo?${params}`);
-  if (!res.ok) {
-    const err = await res.json();
-    throw new Error(err.errorMessage || err.error || 'Failed to validate promo code');
-  }
-  const data = await res.json();
-  return data.data ?? { valid: false, error: 'Invalid response' };
-}
-
-export interface GetPromoDiscountResponse {
-  discount: number;
-  currency: string;
-  isGiftCard?: boolean;
-  isVoucher?: boolean;
-}
-
-export async function getPromoDiscount(
-  promoCode: string,
-  companyId: string,
-  productId: string,
-  optionId: string,
-  currency: string,
-  items: Array<{ category: string; qty: number }>,
-  dateTime?: string,
-  subtotal?: number
-): Promise<GetPromoDiscountResponse> {
-  const itemsStr = items.map((i) => `${i.category}:${i.qty}`).join(',');
-  const params = new URLSearchParams({
-    promoCode: promoCode.trim(),
-    companyId,
-    productId: normalizeBookingProductId(productId),
-    optionId: normalizeBookingProductId(optionId),
-    currency,
-    items: itemsStr,
-  });
-  if (dateTime) params.set('dateTime', dateTime);
-  if (subtotal != null && subtotal > 0) params.set('subtotal', String(subtotal));
-  const res = await fetchBookingGetWithRetry(`${API_BASE}/1/get-promo-discount?${params}`);
-  if (!res.ok) {
-    const err = await res.json();
-    throw new Error(err.errorMessage || err.error || 'Failed to get promo discount');
-  }
-  const data = await res.json();
-  return data.data ?? { discount: 0, currency, isGiftCard: false, isVoucher: false };
-}
-
-export async function getAddOns(
-  companyId: string,
-  options?: { productOptionId?: string; preCheckout?: boolean }
-): Promise<AddOn[]> {
-  const params = new URLSearchParams({ companyId });
-  if (options?.productOptionId) {
-    const po = normalizeBookingProductId(options.productOptionId);
-    if (po) params.set('productOptionId', po);
-  }
-  if (options?.preCheckout !== undefined) params.set('preCheckout', String(options.preCheckout));
-  const res = await fetchBookingGetWithRetry(`${API_BASE}/1/add-ons?${params}`);
-  if (!res.ok) {
-    const err = await res.json();
-    throw new Error(err.errorMessage || err.error || 'Failed to get add-ons');
-  }
-  const data = await res.json();
-  return data.data?.addOns ?? [];
-}
-
-export interface UpdatePickupLocationPayload {
-  /** Pickup location ID from product's pickup locations */
-  pickupLocationId?: string | null;
-  /** Custom address (e.g. hotel name) - for Private Shuttle when using "Use this address" */
-  travelerHotel?: string | null;
-}
-
-export async function updatePickupLocation(
-  bookingReference: string,
-  lastName: string,
-  payload: UpdatePickupLocationPayload | string
-): Promise<unknown> {
-  const body =
-    typeof payload === 'string'
-      ? { pickupLocationId: payload }
-      : {
-          pickupLocationId: payload.pickupLocationId ?? undefined,
-          travelerHotel: payload.travelerHotel ?? undefined,
-        };
-  const res = await fetch(
-    `${API_BASE}/1/public/bookings/${encodeURIComponent(bookingReference)}/pickup-location?lastName=${encodeURIComponent(lastName)}`,
-    {
-      method: 'PATCH',
-      headers: withBookingOutboundHeaders({ 'Content-Type': 'application/json' }),
-      body: JSON.stringify(body),
-    }
-  );
-  if (!res.ok) {
-    const err = await res.json();
-    throw new Error(err.errorMessage || err.error || 'Failed to update pickup location');
-  }
-  const data = await res.json();
-  return data.data;
-}
-
-/** Preview itinerary with new pickup (no save). Returns updated itineraryDisplay or null if preview not supported. */
-export async function previewPickupLocationChange(
-  bookingReference: string,
-  lastName: string,
-  payload: UpdatePickupLocationPayload
-): Promise<{ itineraryDisplay?: Array<{ stepType?: string; time?: string; place?: string; label?: string }> } | null> {
-  const body = {
-    pickupLocationId: payload.pickupLocationId ?? undefined,
-    travelerHotel: payload.travelerHotel ?? undefined,
-  };
-  const url = `${API_BASE}/1/public/bookings/${encodeURIComponent(bookingReference)}/pickup-location?lastName=${encodeURIComponent(lastName)}&preview=true`;
-  const res = await fetch(url, {
-    method: 'PATCH',
-    headers: getAuthHeaders(),
-    body: JSON.stringify(body),
-  });
-  if (!res.ok) return null;
-  const data = await res.json();
-  return data.data ?? null;
-}
-
-export type CommunicationMethod = 'EMAIL' | 'WHATSAPP' | 'SMS';
-
-export interface UpdateContactPayload {
-  communicationPreference?: CommunicationMethod[];
-  email?: string | null;
-  phoneNumber?: string | null;
-  whatsAppNumber?: string | null;
-}
-
-export async function updateContactDetails(
-  bookingReference: string,
-  lastName: string,
-  payload: UpdateContactPayload
-): Promise<unknown> {
-  const res = await fetch(
-    `${API_BASE}/1/public/bookings/${encodeURIComponent(bookingReference)}/contact?lastName=${encodeURIComponent(lastName)}`,
-    {
-      method: 'PATCH',
-      headers: withBookingOutboundHeaders({ 'Content-Type': 'application/json' }),
-      body: JSON.stringify(payload),
-    }
-  );
-  if (!res.ok) {
-    const err = await res.json();
-    throw new Error(err.errorMessage || err.error || 'Failed to update contact details');
-  }
-  const data = await res.json();
-  return data.data;
-}
-
-export type ItineraryReviewGuestAction = 'approve' | 'request_changes';
-
-/** Guest approves proposed private shuttle itinerary or requests changes (manage-booking). */
-export async function respondToItineraryReview(
-  bookingReference: string,
-  lastName: string,
-  action: ItineraryReviewGuestAction,
-  comment?: string
-): Promise<unknown> {
-  const body: { action: string; comment?: string } = { action };
-  if (action === 'request_changes') {
-    body.comment = comment ?? '';
-  }
-  const res = await fetch(
-    `${API_BASE}/1/public/bookings/${encodeURIComponent(bookingReference)}/itinerary-review?lastName=${encodeURIComponent(lastName)}`,
-    {
-      method: 'PATCH',
-      headers: withBookingOutboundHeaders({ 'Content-Type': 'application/json' }),
-      body: JSON.stringify(body),
-    }
-  );
-  if (!res.ok) {
-    const err = await res.json().catch(() => ({}));
-    throw new Error(
-      (err as { errorMessage?: string; error?: string }).errorMessage ||
-        (err as { error?: string }).error ||
-        'Failed to update itinerary'
-    );
-  }
-  const data = await res.json();
-  return data.data;
-}
-
-export interface CreatePaymentIntentResponse {
-  clientSecret: string;
-  amount: number;
-  currency: string;
-}
-
-export interface ChangeBookingQuoteRequest {
-  bookingReference: string;
-  lastName: string;
-  newProductId: string;
-  newDateTime: string;
-  /** Outbound availability id for the new selection (must match option + datetime server-side). */
-  newAvailabilityId?: string | null;
-  newPickupLocationId?: string | null;
-  newReturnAvailabilityId?: string | null;
-  newPassengerCounts?: Array<{ category: string; count: number }>;
-  newAddOnSelections?: Array<{ addOnId: string; variantId?: string; quantity?: number }>;
-  /** Full new-booking total shown in the UI; server verifies within tolerance then uses this for the session so charge matches screen. */
-  clientProposedTotal?: number;
-}
-
-export interface ChangeBookingQuoteReceipt {
-  subtotal?: number;
-  tax?: number;
-  total: number;
-  currency?: string;
-  lineItems?: Array<{
-    label?: string;
-    amount?: number;
-    type?: string;
-    quantity?: number;
-  }>;
-}
-
-export interface ChangeBookingQuoteResponse {
-  changeIntentId?: string;
-  previousTotalCents?: number;
-  newTotalCents?: number;
-  amountDueCents?: number;
-  expiresAt?: string;
-  original?: {
-    total?: number;
-    currency?: string;
-    lineItems?: Array<{ label?: string; amount?: number; type?: string; quantity?: number }>;
-  };
-  proposed?: {
-    total?: number;
-    currency?: string;
-    lineItems?: Array<{ label?: string; amount?: number; type?: string; quantity?: number }>;
-  };
-  originalReceipt?: ChangeBookingQuoteReceipt;
-  newReceipt?: ChangeBookingQuoteReceipt;
-  priceDiff: number;
-  currency?: string;
-  canProceed?: boolean;
-  reasonIfBlocked?: string;
-}
-
-export interface CreateChangePaymentIntentResponse {
-  paymentIntentId: string;
-  clientSecret: string;
-  amountDueCents: number;
-  currency: string;
-}
-
-export interface ConfirmFreeChangeResponse {
-  status?: string;
-  booking?: unknown;
-}
-
-export interface ApplyPaidChangeResponse {
-  status: 'APPLIED' | 'PROCESSING' | 'FAILED';
-  booking?: unknown;
-  failureCode?: string;
-  failureMessage?: string;
-}
-
-export interface BookingChangeIntentStatusResponse {
-  status: 'CREATED' | 'PAYMENT_REQUIRED' | 'PAYMENT_SUCCEEDED' | 'APPLYING' | 'APPLIED' | 'FAILED' | 'EXPIRED';
-  bookingReference?: string;
-  booking?: unknown;
-  failureCode?: string;
-  failureMessage?: string;
-}
-
-export async function createManagePaymentIntent(
-  bookingReference: string,
-  lastName: string,
-  paymentType: 'deposit' | 'full'
-): Promise<CreatePaymentIntentResponse> {
-  const res = await fetch(`${API_BASE}/checkout/manage-payment-intent`, {
-    method: 'POST',
-    headers: withBookingOutboundHeaders({ 'Content-Type': 'application/json' }),
-    body: JSON.stringify({ bookingReference, lastName, paymentType }),
-  });
-  if (!res.ok) {
-    const err = await res.json();
-    throw new Error(err.errorMessage || err.error || 'Failed to create payment');
-  }
-  const data = await res.json();
-  return (data.data ?? data) as CreatePaymentIntentResponse;
-}
-
-/** Cancel a booking (public manage-booking page). Requires lastName for verification. */
-export async function cancelBookingPublic(
-  bookingReference: string,
-  lastName: string
-): Promise<{ bookingReference: string; status: string }> {
-  const res = await fetch(
-    `${API_BASE}/1/public/bookings/${encodeURIComponent(bookingReference)}/cancel?lastName=${encodeURIComponent(lastName)}`,
-    {
-      method: 'POST',
-      headers: withBookingOutboundHeaders({ 'Content-Type': 'application/json' }),
-    }
-  );
-  if (!res.ok) {
-    if (res.status === 404) throw new Error('Booking not found or last name does not match');
-    const err = await res.json();
-    throw new Error(err.errorMessage || err.error || 'Failed to cancel booking');
-  }
-  const data = await res.json();
-  return data.data ?? { bookingReference, status: 'CANCELLED' };
-}
-
-export async function createBalancePaymentIntent(
-  bookingReference: string,
-  lastName: string
-): Promise<CreatePaymentIntentResponse> {
-  const res = await fetch(`${API_BASE}/checkout/balance-payment-intent`, {
-    method: 'POST',
-    headers: withBookingOutboundHeaders({ 'Content-Type': 'application/json' }),
-    body: JSON.stringify({ bookingReference, lastName }),
-  });
-  if (!res.ok) {
-    const err = await res.json();
-    throw new Error(err.errorMessage || err.error || 'Failed to create payment');
-  }
-  const data = await res.json();
-  return (data.data ?? data) as CreatePaymentIntentResponse;
-}
-
-export async function quoteChangeBooking(
-  request: ChangeBookingQuoteRequest
-): Promise<ChangeBookingQuoteResponse> {
-  const { bookingReference, lastName, ...payload } = request;
-  const res = await fetch(
-    `${API_BASE}/1/public/bookings/${encodeURIComponent(bookingReference)}/change/quote?lastName=${encodeURIComponent(lastName)}`,
-    {
-      method: 'POST',
-      headers: getAuthHeaders(),
-      body: JSON.stringify(payload),
-    }
-  );
-  if (!res.ok) {
-    const err = await parseJsonSafely(res);
-    const message = isApiErrorPayload(err)
-      ? err.errorMessage || err.error || 'Failed to quote booking change'
-      : 'Failed to quote booking change';
-    throw new Error(message);
-  }
-  const data = await parseJsonSafely(res);
-  return ((data as { data?: ChangeBookingQuoteResponse } | null)?.data ??
-    data) as ChangeBookingQuoteResponse;
-}
-
-export async function createChangeBookingPaymentIntent(
-  changeIntentId: string
-): Promise<CreateChangePaymentIntentResponse> {
-  const res = await fetch(
-    `${API_BASE}/1/public/booking-change-intents/${encodeURIComponent(changeIntentId)}/payment-intent`,
-    {
-      method: 'POST',
-      headers: getAuthHeaders(),
-    }
-  );
-  if (!res.ok) {
-    const err = await parseJsonSafely(res);
-    const message = isApiErrorPayload(err)
-      ? err.errorMessage || err.error || 'Failed to create payment intent for booking change'
-      : 'Failed to create payment intent for booking change';
-    throw new Error(message);
-  }
-  const data = await parseJsonSafely(res);
-  return ((data as { data?: CreateChangePaymentIntentResponse } | null)?.data ??
-    data) as CreateChangePaymentIntentResponse;
-}
-
-export async function confirmFreeChangeBooking(
-  changeIntentId: string
-): Promise<ConfirmFreeChangeResponse> {
-  const res = await fetch(
-    `${API_BASE}/1/public/booking-change-intents/${encodeURIComponent(changeIntentId)}/confirm-free`,
-    {
-      method: 'POST',
-      headers: getAuthHeaders(),
-    }
-  );
-  if (!res.ok) {
-    const err = await parseJsonSafely(res);
-    const message = isApiErrorPayload(err)
-      ? err.errorMessage || err.error || 'Failed to confirm free booking change'
-      : 'Failed to confirm free booking change';
-    throw new Error(message);
-  }
-  const data = await parseJsonSafely(res);
-  return ((data as { data?: ConfirmFreeChangeResponse } | null)?.data ??
-    data) as ConfirmFreeChangeResponse;
-}
-
-export async function applyPaidChangeBooking(
-  changeIntentId: string,
-  paymentIntentId: string
-): Promise<ApplyPaidChangeResponse> {
-  const res = await fetch(
-    `${API_BASE}/1/public/booking-change-intents/${encodeURIComponent(changeIntentId)}/apply`,
-    {
-      method: 'POST',
-      headers: getAuthHeaders(),
-      body: JSON.stringify({ paymentIntentId }),
-    }
-  );
-  if (!res.ok) {
-    const err = await parseJsonSafely(res);
-    const message = isApiErrorPayload(err)
-      ? err.errorMessage || err.error || 'Failed to apply paid booking change'
-      : 'Failed to apply paid booking change';
-    throw new Error(message);
-  }
-  const data = await parseJsonSafely(res);
-  return ((data as { data?: ApplyPaidChangeResponse } | null)?.data ??
-    data) as ApplyPaidChangeResponse;
-}
-
-export async function getBookingChangeIntentStatus(
-  changeIntentId: string
-): Promise<BookingChangeIntentStatusResponse> {
-  const res = await fetchBookingGetWithRetry(
-    `${API_BASE}/1/public/booking-change-intents/${encodeURIComponent(changeIntentId)}`,
-    { cache: 'no-store' },
-  );
-  if (!res.ok) {
-    const err = await parseJsonSafely(res);
-    const message = isApiErrorPayload(err)
-      ? err.errorMessage || err.error || 'Failed to get booking change status'
-      : 'Failed to get booking change status';
-    throw new Error(message);
-  }
-  const data = await parseJsonSafely(res);
-  return ((data as { data?: BookingChangeIntentStatusResponse } | null)?.data ??
-    data) as BookingChangeIntentStatusResponse;
-}
-
-// ============ Booking Flow (availability, reserve, checkout) ============
-
-/** Applied pricing adjustment (dynamic rule or deal) for price breakdown display */
-export interface AppliedAdjustment {
-  type: string;
-  id: string;
-  name: string;
-  changeByCurrency?: Record<string, number>;
-  adjustmentType?: string;
-  adjustmentValue?: number;
-}
-
-export interface AvailabilityRate {
-  rateId: string;
-  category: string;
-  available: number;
-  price?: number;
-  priceByCurrency?: Record<string, number>;
-  appliedAdjustments?: AppliedAdjustment[];
-  applied_adjustments?: AppliedAdjustment[];
-}
-
-export interface ReturnOption {
-  returnAvailabilityId: string;
-  dateTime: string;
-  vacancies: number;
-  totalCapacity: number;
-  bookedCapacity?: number;
-  pricesByCategory?: { retailPrices: Array<{ category: string; price: number }> };
-  priceAdjustmentByCurrency?: Record<string, number>;
-  returnLocation: string;
-  mostPopular?: boolean;
-}
-
-export interface Availability {
-  dateTime: string;
-  productId?: string;
-  vacancies: number;
-  totalCapacity?: number;
-  bookedCapacity?: number;
-  resourceCount?: number;
-  currency: string;
-  availabilityId?: string;
-  productOptionId?: string;
-  productType?: 'STANDARD' | 'PRIVATE_SHUTTLE';
-  suggestedStartTimes?: string[];
-  rates?: AvailabilityRate[];
-  returnOptions?: ReturnOption[];
-  pricesByCategory?: {
-    retailPrices: Array<{ category: string; price: number }>;
-  };
-}
-
-export type PrecomputedPricesByCategory = Record<string, Record<string, number>>;
-
-export interface GetAvailabilitiesResponse {
-  availabilities: Availability[];
-  pricingConfig?: PricingConfig;
-  precomputedPrices?: PrecomputedPricesByCategory;
-  resourcePriceByCurrency?: Record<string, number>;
-  resourcePriceByOption?: Record<string, Record<string, number>>;
-}
-
-export interface GetAvailabilitiesOptions {
-  promoCode?: string | null;
-  allOptions?: boolean;
-  /**
-   * When set, TicketBooth should return rates/precomputed prices for this partner pricing profile.
-   * Must match the profile linked on the partner (e.g. capabilities.pricingProfileId).
-   */
-  pricingProfileId?: string | null;
-  /**
-   * When set, TicketBooth returns only cancellation policies allowed by this partner profile.
-   */
-  cancellationPolicyProfileId?: string | null;
-}
-
-export async function getAvailabilities(
-  productIdOrOptionId: string,
-  startDate: string,
-  endDate: string,
-  options?: GetAvailabilitiesOptions
-): Promise<GetAvailabilitiesResponse> {
-  const normalizedLookupId = normalizeAvailabilityLookupId(productIdOrOptionId);
-  if (!normalizedLookupId) {
-    const endpoint = '/1/get-availabilities';
-    const debugMessage = 'Missing productId/productOptionId for availabilities request';
-    if (typeof window !== 'undefined') {
-      console.warn('[booking-api] Skipping availabilities request due to invalid lookup ID', {
-        original: productIdOrOptionId,
-      });
-    }
-    reportClientFetchError({
-      endpoint,
-      errorClass: 'APP_ERROR_200',
-      message: debugMessage,
-    });
-    return { availabilities: [] };
-  }
-  if (normalizedLookupId !== productIdOrOptionId.trim() && typeof window !== 'undefined') {
-    console.warn('[booking-api] Sanitized malformed availability lookup ID', {
-      original: productIdOrOptionId,
-      sanitized: normalizedLookupId,
-    });
-  }
-  const params = new URLSearchParams({
-    productId: normalizedLookupId,
-    startDate,
-    endDate,
-  });
-  if (options?.promoCode?.trim()) params.set('promoCode', options.promoCode.trim());
-  if (options?.allOptions === true) params.set('allOptions', 'true');
-  const pricingProfileId = options?.pricingProfileId?.trim();
-  if (pricingProfileId) params.set('pricingProfileId', pricingProfileId);
-  const cancellationPolicyProfileId = options?.cancellationPolicyProfileId?.trim();
-  if (cancellationPolicyProfileId) {
-    params.set('cancellationPolicyProfileId', cancellationPolicyProfileId);
-  }
-  const endpoint = '/1/get-availabilities';
-  const url = `${API_BASE}${endpoint}?${params}`;
-  let res: Response;
-  try {
-    res = await fetchBookingGetWithRetry(url);
-  } catch (err) {
-    logBookingApiNetworkError(endpoint, err);
-    const debugMessage = err instanceof Error ? err.message : String(err);
-    reportClientFetchError({
-      endpoint,
-      errorClass: 'NETWORK',
-      message: debugMessage,
-    });
-    throw createUserError(endpoint, 'NETWORK', debugMessage);
-  }
-
-  if (!res.ok) {
-    const errPayload = await parseJsonSafely(res);
-    const debugMessage = toHttpErrorMessage(endpoint, res.status, errPayload, 'Failed to get availabilities');
-    reportClientFetchError({
-      endpoint,
-      errorClass: 'HTTP',
-      message: debugMessage,
-      httpStatus: res.status,
-      errorCode: isApiErrorPayload(errPayload) ? errPayload.errorCode : undefined,
-    });
-    throw createUserError(endpoint, 'HTTP', debugMessage);
-  }
-
-  const data = await parseJsonSafely(res);
-  const appError = toAppLevelErrorMessage(endpoint, data, 'Failed to get availabilities');
-  if (appError) {
-    reportClientFetchError({
-      endpoint,
-      errorClass: 'APP_ERROR_200',
-      message: appError,
-      errorCode: isApiErrorPayload(data) ? data.errorCode : undefined,
-    });
-    throw createUserError(endpoint, 'APP_ERROR_200', appError);
-  }
-
-  const bookingData = (data as { data?: GetAvailabilitiesResponse } | null)?.data;
-  return {
-    availabilities: bookingData?.availabilities ?? [],
-    pricingConfig: bookingData?.pricingConfig,
-    precomputedPrices: bookingData?.precomputedPrices,
-    resourcePriceByCurrency: bookingData?.resourcePriceByCurrency,
-    resourcePriceByOption: bookingData?.resourcePriceByOption,
-  };
-}
-
-export interface BookingItem {
-  category: string;
-  count: number;
-}
-
-export interface ReserveRequest {
-  productId: string;
-  dateTime: string;
-  /** Exact outbound inventory row from get-availabilities; ensures reserve matches the slot the user selected. */
-  availabilityId?: string;
-  bookingItems: BookingItem[];
-  pickupLocationId?: string;
-  returnAvailabilityId?: string;
-  currency?: string;
-  travelerHotel?: string;
-  promoCode?: string;
-  cancellationPolicyId?: string;
-  addOnSelections?: Array<{ addOnId: string; variantId?: string; quantity?: number }>;
-  /** Private Shuttle only: user-selected start time (ISO 8601) */
-  startTime?: string;
-  /** Private Shuttle only: total passenger count (may be capped when capacity limited) */
-  passengerCount?: number;
-  /** Private Shuttle only: what customer actually requested (use when capacity limited; for display in emails/manage) */
-  requestedPassengerCount?: number;
-  /** Private Shuttle only: draft destinations and planning notes */
-  draftItinerary?: { destinations: string[]; planningNotes?: string };
-  /** Private Shuttle only: child safety seats count */
-  childSafetySeatsCount?: number;
-  /** Private Shuttle only: dietary restrictions / food allergies */
-  foodRestrictions?: string;
-  /** Admin only: additional hours add-on (extends duration) */
-  additionalHoursCount?: number;
-  /**
-   * Admin only: allow outbound/return capacity holds above vacancies. Server requires admin JWT
-   * and still validates permission; omit or false for public/partner flows.
-   */
-  allowOverbook?: boolean;
-  /** Optional; merged with server tracking (authenticated reserve). */
-  source?: string;
-  sourceMetadata?: BookingSourceMetadata;
-  source_metadata?: BookingSourceMetadata;
-}
-
-/** Safe subset of reserve payload for telemetry (no free-text traveler fields). */
-export function summarizeReserveRequestForTelemetry(req: ReserveRequest): Record<string, unknown> {
-  const ticketUnits = req.bookingItems.reduce(
-    (sum, b) => sum + Math.max(0, Number(b.count) || 0),
-    0
-  );
-  return {
-    productId: req.productId,
-    dateTime: req.dateTime,
-    availabilityId: req.availabilityId ?? null,
-    returnAvailabilityId: req.returnAvailabilityId ?? null,
-    pickupLocationId: req.pickupLocationId ?? null,
-    bookingItems: req.bookingItems.map((b) => ({ category: b.category, count: b.count })),
-    totalTicketUnits: ticketUnits,
-    passengerCount: req.passengerCount ?? null,
-    requestedPassengerCount: req.requestedPassengerCount ?? null,
-    startTime: req.startTime ?? null,
-    currency: req.currency ?? null,
-    cancellationPolicyId: req.cancellationPolicyId ?? null,
-    hasAddOns: Array.isArray(req.addOnSelections) && req.addOnSelections.length > 0,
-    addOnSelectionsCount: req.addOnSelections?.length ?? 0,
-    promoPresent: Boolean(req.promoCode?.trim()),
-    additionalHoursCount: req.additionalHoursCount ?? null,
-    childSafetySeatsCount: req.childSafetySeatsCount ?? null,
-    allowOverbook: req.allowOverbook === true,
-  };
-}
-
-/**
- * `/1/reserve` success payload (`ReserveResponseData` on the API).
- * Hold expiry is serialized as `reservationExpiration` (not `expiresAt`).
- */
-export interface ReserveResponse {
-  reservationReference: string;
-  /** ISO 8601 instant when the hold expires (API field name). */
-  reservationExpiration: string;
-  /**
-   * Same as `reservationExpiration`; populated in `createReservation()` for callers that still read `expiresAt`.
-   */
-  expiresAt: string;
-  totalAmount?: number;
-  currency?: string;
-}
-
-export async function createReservation(request: ReserveRequest): Promise<ReserveResponse> {
-  const endpoint = '/1/reserve';
-  const reservePayload = withExplicitBookingSource(request);
-  let res: Response;
-  try {
-    res = await fetch(`${API_BASE}${endpoint}`, {
-      method: 'POST',
-      headers: getAuthHeaders(),
-      body: JSON.stringify({ data: reservePayload }),
-    });
-  } catch (err) {
-    const debugMessage = err instanceof Error ? err.message : String(err);
-    reportClientFetchError({
-      endpoint,
-      errorClass: 'NETWORK',
-      message: debugMessage,
-      metadata: {
-        failureKind: 'RESERVE_NETWORK',
-        reserveRequest: summarizeReserveRequestForTelemetry(request),
-      },
-    });
-    throw createUserError(endpoint, 'NETWORK', debugMessage);
-  }
-  const text = await res.text();
-  if (!res.ok) {
-    let err: { errorMessage?: string; error?: string; errorCode?: string };
-    try {
-      err = JSON.parse(text);
-    } catch {
-      err = { errorMessage: text || 'Failed to create reservation' };
-    }
-    const debugMessage = err.errorMessage || err.error || 'Failed to create reservation';
-    const insufficientCapacity = isInsufficientCapacityApiError(err.errorCode, debugMessage);
-    reportClientFetchError({
-      endpoint,
-      errorClass: 'HTTP',
-      message: insufficientCapacity
-        ? `[RESERVE_INSUFFICIENT_CAPACITY] ${debugMessage}`
-        : debugMessage,
-      httpStatus: res.status,
-      errorCode: err.errorCode,
-      metadata: {
-        failureKind: insufficientCapacity
-          ? 'RESERVE_INSUFFICIENT_CAPACITY'
-          : 'RESERVE_HTTP_ERROR',
-        reserveRequest: summarizeReserveRequestForTelemetry(request),
-        apiErrorMessage: debugMessage,
-        apiErrorCode: err.errorCode ?? null,
-      },
-    });
-    throw createUserError(endpoint, 'HTTP', debugMessage, err.errorCode);
-  }
-  let data: { data?: ReserveResponse; errorCode?: string; errorMessage?: string };
-  try {
-    data = JSON.parse(text);
-  } catch {
-    throw new Error('Invalid response from server');
-  }
-  if (data.errorCode || data.errorMessage) {
-    const debugMessage = data.errorMessage || 'Failed to create reservation';
-    const insufficientCapacity = isInsufficientCapacityApiError(data.errorCode, debugMessage);
-    reportClientFetchError({
-      endpoint,
-      errorClass: 'APP_ERROR_200',
-      message: insufficientCapacity
-        ? `[RESERVE_INSUFFICIENT_CAPACITY] ${debugMessage}`
-        : debugMessage,
-      errorCode: data.errorCode,
-      metadata: {
-        failureKind: insufficientCapacity
-          ? 'RESERVE_INSUFFICIENT_CAPACITY'
-          : 'RESERVE_APP_ERROR_200',
-        reserveRequest: summarizeReserveRequestForTelemetry(request),
-        apiErrorMessage: debugMessage,
-        apiErrorCode: data.errorCode ?? null,
-      },
-    });
-    throw createUserError(endpoint, 'APP_ERROR_200', debugMessage, data.errorCode);
-  }
-  if (!data.data?.reservationReference) {
-    throw new Error('Invalid response: missing reservationReference');
-  }
-  const raw = data.data as {
-    reservationReference: string;
-    reservationExpiration?: string;
-    expiresAt?: string;
-    totalAmount?: number;
-    currency?: string;
-  };
-  const expiration = raw.reservationExpiration ?? raw.expiresAt;
-  if (!expiration) {
-    throw new Error('Invalid response: missing reservation hold expiration');
-  }
-  return {
-    reservationReference: raw.reservationReference,
-    reservationExpiration: expiration,
-    expiresAt: expiration,
-    totalAmount: raw.totalAmount,
-    currency: raw.currency,
-  };
-}
-
-export async function cancelReservation(reservationReference: string): Promise<void> {
-  const res = await fetch(`${API_BASE}/1/cancel-reservation`, {
-    method: 'POST',
-    headers: getAuthHeaders(),
-    body: JSON.stringify({ data: { reservationReference, gygBookingReference: '' } }),
-  });
-  if (!res.ok) {
-    const err = await res.json();
-    throw new Error(err.errorMessage || err.error || 'Failed to cancel reservation');
-  }
-}
-
-/**
- * Best-effort reservation cancellation for unload/pagehide flows.
- * Uses keepalive and never throws.
- */
-export function cancelReservationBestEffort(reservationReference: string): void {
-  try {
-    void fetch(`${API_BASE}/1/cancel-reservation`, {
-      method: 'POST',
-      headers: getAuthHeaders(),
-      body: JSON.stringify({ data: { reservationReference, gygBookingReference: '' } }),
-      keepalive: true,
-    }).catch(() => {
-      // best-effort only
-    });
-  } catch {
-    // best-effort only
-  }
-}
-
-export interface CheckoutReceiptLine {
-  label: string;
-  amount: number;
-  type?: string;
-  quantity?: number;
-}
-
-export interface CheckoutBreakdown {
-  lineItems: CheckoutReceiptLine[];
-  totalAmount: number;
-  currency: string;
-}
-
-export interface CreatePaymentIntentRequest {
-  productId: string;
-  optionId: string;
-  date: string;
-  time: string;
-  quantity: number;
-  customerEmail?: string;
-  customerFirstName?: string;
-  customerLastName?: string;
-  currency?: string;
-  reservationReference?: string;
-  travelerHotel?: string;
-  pickupLocationId?: string;
-  returnAvailabilityId?: string;
-  promoCode?: string;
-  cancellationPolicyId?: string;
-  termsAcceptedAt?: string;
-  checkoutBreakdown?: CheckoutBreakdown;
-  itineraryDisplay?: ItineraryDisplayStep[];
-  skipConfirmationCommunications?: boolean;
-  disableAutoCommunications?: boolean;
-  /** Private Shuttle deposit: pay deposit now, balance charged before trip */
-  paymentPlanType?: 'DEPOSIT';
-  depositAmount?: number;
-  balanceAmount?: number;
-  totalAmount?: number;
-  balanceChargeDaysBefore?: number;
-  source?: string;
-  sourceMetadata?: BookingSourceMetadata;
-  source_metadata?: BookingSourceMetadata;
-}
-
-export interface CreatePaymentIntentResponseFull {
-  clientSecret?: string;
-  freeBooking?: boolean;
-  totalAmount?: number;
-  currency?: string;
-}
-
-export async function createBookingPaymentIntent(
-  request: CreatePaymentIntentRequest
-): Promise<CreatePaymentIntentResponseFull> {
-  const endpoint = '/checkout/payment-intent';
-  const payload = withExplicitBookingSource(request);
-  logBookingSourceDebug('request', '/checkout/payment-intent', {
-    reservationReference: payload.reservationReference,
-    source: payload.source,
-    sourceMetadata: payload.sourceMetadata,
-    source_metadata: payload.source_metadata,
-  });
-  let res: Response;
-  try {
-    res = await fetch(`${API_BASE}${endpoint}`, {
-      method: 'POST',
-      headers: getAuthHeaders(),
-      body: JSON.stringify(payload),
-    });
-  } catch (err) {
-    const debugMessage = err instanceof Error ? err.message : String(err);
-    reportClientFetchError({
-      endpoint,
-      errorClass: 'NETWORK',
-      message: debugMessage,
-    });
-    throw createUserError(endpoint, 'NETWORK', debugMessage);
-  }
-  if (!res.ok) {
-    const err = await parseJsonSafely(res);
-    logBookingSourceDebug('error', '/checkout/payment-intent', err);
-    const debugMessage = toHttpErrorMessage(
-      endpoint,
-      res.status,
-      err,
-      'Failed to create payment intent'
-    );
-    reportClientFetchError({
-      endpoint,
-      errorClass: 'HTTP',
-      message: debugMessage,
-      httpStatus: res.status,
-      errorCode: isApiErrorPayload(err) ? err.errorCode : undefined,
-    });
-    throw createUserError(endpoint, 'HTTP', debugMessage);
-  }
-  const data = await parseJsonSafely(res);
-  const appError = toAppLevelErrorMessage(endpoint, data, 'Failed to create payment intent');
-  if (appError) {
-    reportClientFetchError({
-      endpoint,
-      errorClass: 'APP_ERROR_200',
-      message: appError,
-      errorCode: isApiErrorPayload(data) ? data.errorCode : undefined,
-    });
-    throw createUserError(endpoint, 'APP_ERROR_200', appError);
-  }
-  logBookingSourceDebug('response', '/checkout/payment-intent', data);
-  return (data as { data?: CreatePaymentIntentResponseFull } | null)?.data ?? (data as CreatePaymentIntentResponseFull);
-}
-
-/** Alias for createBookingPaymentIntent (used by ticketbooth BookingFlow) */
-export const createPaymentIntent = createBookingPaymentIntent;
-
-export interface ConfirmFreeBookingRequest {
-  reservationReference: string;
-  productId: string;
-  optionId: string;
-  date: string;
-  time: string;
-  customerEmail?: string;
-  customerFirstName?: string;
-  customerLastName?: string;
-  currency?: string;
-  travelerHotel?: string;
-  pickupLocationId?: string;
-  termsAcceptedAt?: string;
-  itineraryDisplay?: ItineraryDisplayStep[];
-  skipConfirmationCommunications?: boolean;
-  disableAutoCommunications?: boolean;
-  source?: string;
-  sourceMetadata?: BookingSourceMetadata;
-  source_metadata?: BookingSourceMetadata;
-}
-
-export interface ConfirmFreeBookingResponse {
-  bookingReference: string;
-  reservationReference: string;
-}
-
-export async function confirmFreeBooking(
-  request: ConfirmFreeBookingRequest
-): Promise<ConfirmFreeBookingResponse> {
-  const endpoint = '/checkout/confirm-free-booking';
-  const payload = withExplicitBookingSource(request);
-  logBookingSourceDebug('request', '/checkout/confirm-free-booking', {
-    reservationReference: payload.reservationReference,
-    source: payload.source,
-    sourceMetadata: payload.sourceMetadata,
-    source_metadata: payload.source_metadata,
-  });
-  let res: Response;
-  try {
-    res = await fetch(`${API_BASE}${endpoint}`, {
-      method: 'POST',
-      headers: getAuthHeaders(),
-      body: JSON.stringify(payload),
-    });
-  } catch (err) {
-    const debugMessage = err instanceof Error ? err.message : String(err);
-    reportClientFetchError({ endpoint, errorClass: 'NETWORK', message: debugMessage });
-    throw createUserError(endpoint, 'NETWORK', debugMessage);
-  }
-  if (!res.ok) {
-    const err = await parseJsonSafely(res);
-    logBookingSourceDebug('error', '/checkout/confirm-free-booking', err);
-    const debugMessage = toHttpErrorMessage(endpoint, res.status, err, 'Failed to confirm free booking');
-    reportClientFetchError({
-      endpoint,
-      errorClass: 'HTTP',
-      message: debugMessage,
-      httpStatus: res.status,
-      errorCode: isApiErrorPayload(err) ? err.errorCode : undefined,
-    });
-    throw createUserError(endpoint, 'HTTP', debugMessage);
-  }
-  const data = await parseJsonSafely(res);
-  const appError = toAppLevelErrorMessage(endpoint, data, 'Failed to confirm free booking');
-  if (appError) {
-    reportClientFetchError({
-      endpoint,
-      errorClass: 'APP_ERROR_200',
-      message: appError,
-      errorCode: isApiErrorPayload(data) ? data.errorCode : undefined,
-    });
-    throw createUserError(endpoint, 'APP_ERROR_200', appError);
-  }
-  logBookingSourceDebug('response', '/checkout/confirm-free-booking', data);
-  return ((data as { data?: ConfirmFreeBookingResponse } | null)?.data ??
-    data) as ConfirmFreeBookingResponse;
-}
-
-export interface ConfirmBookingWithoutPaymentRequest {
-  reservationReference: string;
-  productId: string;
-  optionId: string;
-  date: string;
-  time: string;
-  customerEmail?: string;
-  customerFirstName?: string;
-  customerLastName?: string;
-  currency?: string;
-  travelerHotel?: string;
-  pickupLocationId?: string;
-  itineraryDisplay?: ItineraryDisplayStep[];
-  termsAcceptedAt?: string;
-  skipConfirmationCommunications?: boolean;
-  disableAutoCommunications?: boolean;
-  checkoutBreakdown: CheckoutBreakdown;
-  depositAmount: number;
-  balanceAmount: number;
-  totalAmount: number;
-  balanceChargeDaysBefore?: number;
-  source?: string;
-  sourceMetadata?: BookingSourceMetadata;
-  source_metadata?: BookingSourceMetadata;
-}
-
-export interface ConfirmBookingWithoutPaymentResponse {
-  bookingReference: string;
-  reservationReference: string;
-}
-
-export async function confirmBookingWithoutPayment(
-  request: ConfirmBookingWithoutPaymentRequest
-): Promise<ConfirmBookingWithoutPaymentResponse> {
-  const endpoint = '/checkout/confirm-booking-without-payment';
-  const payload = withExplicitBookingSource(request);
-  logBookingSourceDebug('request', '/checkout/confirm-booking-without-payment', {
-    reservationReference: payload.reservationReference,
-    source: payload.source,
-    sourceMetadata: payload.sourceMetadata,
-    source_metadata: payload.source_metadata,
-  });
-  let res: Response;
-  try {
-    res = await fetch(`${API_BASE}${endpoint}`, {
-      method: 'POST',
-      headers: getAuthHeaders(),
-      body: JSON.stringify(payload),
-    });
-  } catch (err) {
-    const debugMessage = err instanceof Error ? err.message : String(err);
-    reportClientFetchError({ endpoint, errorClass: 'NETWORK', message: debugMessage });
-    throw createUserError(endpoint, 'NETWORK', debugMessage);
-  }
-  if (!res.ok) {
-    const err = await parseJsonSafely(res);
-    logBookingSourceDebug('error', '/checkout/confirm-booking-without-payment', err);
-    const debugMessage = toHttpErrorMessage(endpoint, res.status, err, 'Failed to confirm booking');
-    reportClientFetchError({
-      endpoint,
-      errorClass: 'HTTP',
-      message: debugMessage,
-      httpStatus: res.status,
-      errorCode: isApiErrorPayload(err) ? err.errorCode : undefined,
-    });
-    throw createUserError(endpoint, 'HTTP', debugMessage);
-  }
-  const data = await parseJsonSafely(res);
-  const appError = toAppLevelErrorMessage(endpoint, data, 'Failed to confirm booking');
-  if (appError) {
-    reportClientFetchError({
-      endpoint,
-      errorClass: 'APP_ERROR_200',
-      message: appError,
-      errorCode: isApiErrorPayload(data) ? data.errorCode : undefined,
-    });
-    throw createUserError(endpoint, 'APP_ERROR_200', appError);
-  }
-  logBookingSourceDebug('response', '/checkout/confirm-booking-without-payment', data);
-  return ((data as { data?: ConfirmBookingWithoutPaymentResponse } | null)?.data ??
-    data) as ConfirmBookingWithoutPaymentResponse;
-}
-
-/** Partner portal DEFERRED_INVOICE: same body as [confirmBookingWithoutPayment]; uses Bearer partner JWT. */
-export async function confirmPartnerBookingWithoutPayment(
-  request: ConfirmBookingWithoutPaymentRequest,
-): Promise<ConfirmBookingWithoutPaymentResponse> {
-  const endpoint = '/1/partner/confirm-booking-without-payment';
-  const payload = withExplicitBookingSource(request);
-  logBookingSourceDebug('request', endpoint, {
-    reservationReference: payload.reservationReference,
-    source: payload.source,
-    sourceMetadata: payload.sourceMetadata,
-    source_metadata: payload.source_metadata,
-  });
-  let res: Response;
-  try {
-    res = await fetch(`${API_BASE}${endpoint}`, {
-      method: 'POST',
-      headers: {
-        ...getAuthHeaders(),
-        'Content-Type': 'application/json',
-      },
-      body: JSON.stringify(payload),
-    });
-  } catch (err) {
-    const debugMessage = err instanceof Error ? err.message : String(err);
-    reportClientFetchError({ endpoint, errorClass: 'NETWORK', message: debugMessage });
-    throw createUserError(endpoint, 'NETWORK', debugMessage);
-  }
-  if (!res.ok) {
-    const err = await parseJsonSafely(res);
-    logBookingSourceDebug('error', endpoint, err);
-    const debugMessage = toHttpErrorMessage(endpoint, res.status, err, 'Failed to confirm booking');
-    reportClientFetchError({
-      endpoint,
-      errorClass: 'HTTP',
-      message: debugMessage,
-      httpStatus: res.status,
-      errorCode: isApiErrorPayload(err) ? err.errorCode : undefined,
-    });
-    throw createUserError(endpoint, 'HTTP', debugMessage);
-  }
-  const data = await parseJsonSafely(res);
-  const appError = toAppLevelErrorMessage(endpoint, data, 'Failed to confirm booking');
-  if (appError) {
-    reportClientFetchError({
-      endpoint,
-      errorClass: 'APP_ERROR_200',
-      message: appError,
-      errorCode: isApiErrorPayload(data) ? data.errorCode : undefined,
-    });
-    throw createUserError(endpoint, 'APP_ERROR_200', appError);
-  }
-  logBookingSourceDebug('response', endpoint, data);
-  return ((data as { data?: ConfirmBookingWithoutPaymentResponse } | null)?.data ??
-    data) as ConfirmBookingWithoutPaymentResponse;
-}