@ticketboothapp/booking 1.2.180 → 1.2.182

package/src/lib/booking-api.ts

@@ -22,16 +22,34 @@ import {
   sanitizeBookingSourceUrl,
   type BookingSourceMetadata,
 } from './booking/source-metadata';
+import {
+  getOrCreateReservationAttempt,
+  reservationIdempotencyEnabled,
+  type ReservationAttemptContext,
+} from './booking/reservation-attempt';
 
-const API_BASE = ENV.API_URL;
+const API_BASE = ENV.API_URL.replace(/\/$/, '');
+const BOOKING_READ_API_BASE = ENV.BOOKING_READ_API_URL.replace(/\/$/, '');
+const BOOKING_GATEWAY_PREFIX = '/api/booking';
 
 /** When set (e.g. booking-portal partner session), reserve/checkout use Bearer instead of Basic. */
 let partnerPortalBookingJwtGetter: () => string | null = () => null;
+let partnerPortalBookingAuthorizationFailureHandler: () => void = () => {};
+
+/** Partner sessions retain their Bearer-authenticated read path. Public reads use the gateway. */
+function bookingReadApiBase(): string {
+  return partnerPortalBookingJwtGetter() ? API_BASE : BOOKING_READ_API_BASE;
+}
 
 export function setPartnerPortalBookingJwtGetter(fn: () => string | null): void {
   partnerPortalBookingJwtGetter = fn;
 }
 
+/** Called when TicketBooth rejects the current partner JWT so the portal can clear stale authority. */
+export function setPartnerPortalBookingAuthorizationFailureHandler(fn: () => void): void {
+  partnerPortalBookingAuthorizationFailureHandler = fn;
+}
+
 interface ApiErrorPayload {
   errorCode?: string;
   errorMessage?: string;
@@ -42,15 +60,85 @@ function isApiErrorPayload(value: unknown): value is ApiErrorPayload {
   return typeof value === 'object' && value !== null;
 }
 
+function notifyPartnerPortalAuthorizationFailure(): void {
+  if (!partnerPortalBookingJwtGetter()) return;
+  try {
+    partnerPortalBookingAuthorizationFailureHandler();
+  } catch {
+    // Authentication cleanup must never mask the original API error.
+  }
+}
+
+function isRejectedAuthenticationPayload(value: unknown): value is ApiErrorPayload {
+  if (!isApiErrorPayload(value) || value.errorCode !== 'AUTHORIZATION_FAILURE') return false;
+  return value.errorMessage?.trim().toLowerCase() !== 'access denied';
+}
+
 async function parseJsonSafely(res: Response): Promise<unknown> {
   try {
-    return await res.json();
+    const payload: unknown = await res.json();
+    if (isRejectedAuthenticationPayload(payload)) {
+      notifyPartnerPortalAuthorizationFailure();
+    }
+    return payload;
   } catch {
     return null;
   }
 }
 
 type BookingClientErrorClass = 'NETWORK' | 'HTTP' | 'APP_ERROR_200';
+const TELEMETRY_DEDUPE_WINDOW_MS = 30_000;
+const telemetryDedupeFallback = new Map<string, number>();
+
+function telemetryDedupeKey(
+  eventName: string,
+  correlationId: string,
+  fields: Record<string, unknown>
+): string | null {
+  if (
+    eventName === 'BOOKING_DIALOG_REQUEST_TIMING' ||
+    eventName === 'BOOKING_DIALOG_REQUEST_RETRYING' ||
+    eventName === 'BOOKING_DIALOG_NETWORK_PROBE_PING'
+  ) return null;
+  const endpoint = typeof fields.endpoint === 'string' ? fields.endpoint : '';
+  if (!endpoint) return null;
+  const signature = [
+    correlationId,
+    eventName,
+    endpoint,
+    fields.errorClass,
+    fields.errorCode,
+    fields.httpStatus,
+    fields.errorName,
+  ].map((value) => String(value ?? '')).join('|');
+  let hash = 2166136261;
+  for (let index = 0; index < signature.length; index += 1) {
+    hash ^= signature.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return `tb_booking_telemetry_${(hash >>> 0).toString(16)}`;
+}
+
+function shouldEmitBookingTelemetry(
+  eventName: string,
+  correlationId: string,
+  fields: Record<string, unknown>
+): boolean {
+  const key = telemetryDedupeKey(eventName, correlationId, fields);
+  if (!key) return true;
+  const now = Date.now();
+  try {
+    const previous = Number(sessionStorage.getItem(key));
+    if (Number.isFinite(previous) && now - previous < TELEMETRY_DEDUPE_WINDOW_MS) return false;
+    sessionStorage.setItem(key, String(now));
+    return true;
+  } catch {
+    const previous = telemetryDedupeFallback.get(key);
+    if (previous != null && now - previous < TELEMETRY_DEDUPE_WINDOW_MS) return false;
+    telemetryDedupeFallback.set(key, now);
+    return true;
+  }
+}
 
 /** Thrown by booking-api helpers; includes API error details for UX branching (e.g. capacity conflicts). */
 export type BookingClientError = Error & {
@@ -88,7 +176,7 @@ function logBookingApiNetworkError(endpoint: string, err: unknown): void {
   if (typeof window === 'undefined') return;
   const details = {
     endpoint,
-    apiBase: API_BASE,
+    apiBase: bookingReadApiBase(),
     online: window.navigator.onLine,
     userAgent: window.navigator.userAgent,
     error: err instanceof Error ? err.message : String(err),
@@ -102,16 +190,18 @@ function reportBookingClientTelemetryEvent(
   fields: Record<string, unknown>
 ): void {
   if (typeof window === 'undefined') return;
-  const telemetryEndpoint = `${API_BASE}/1/client-telemetry`;
+  const telemetryEndpoint = `${BOOKING_READ_API_BASE}/1/client-telemetry`;
   const correlationId = getOrCreateBookingCorrelationId();
+  if (!shouldEmitBookingTelemetry(eventName, correlationId, fields)) return;
   const traceparent = buildTraceparent();
   const traceId = traceIdFromTraceparent(traceparent);
   const event = {
     event: eventName,
+    clientBuildId: ENV.BOOKING_CLIENT_BUILD_ID,
     correlationId,
     traceparent,
     ...(traceId ? { traceId } : {}),
-    apiBase: API_BASE,
+    apiBase: BOOKING_READ_API_BASE,
     pageUrl: sanitizeBookingSourceUrl(window.location.href) ?? window.location.origin,
     userAgent: window.navigator.userAgent,
     online: window.navigator.onLine,
@@ -153,6 +243,11 @@ function reportClientFetchError(payload: {
   });
 }
 
+function gatewayResponseMetadata(response: Response): Record<string, string> | undefined {
+  const requestId = response.headers.get('X-Booking-Gateway-Request-Id');
+  return requestId ? { gatewayRequestId: requestId } : undefined;
+}
+
 function isInsufficientCapacityApiError(errorCode?: string, errorMessage?: string): boolean {
   const msg = (errorMessage ?? '').toLowerCase();
   return errorCode === 'VALIDATION_FAILURE' && msg.includes('insufficient capacity');
@@ -193,6 +288,8 @@ function createUserError(
     ? 'This reservation hold has expired. Close this window and restart checkout to get current availability and pricing.'
     : bookingApiErrorCode === 'RESERVATION_NOT_ACTIVE'
       ? 'This reservation has already been completed or closed. Refresh before trying again.'
+      : bookingApiErrorCode === 'RESERVATION_OUTCOME_UNKNOWN'
+        ? 'We could not safely confirm whether your reservation was created. Please keep this page open and try recovery again; do not start another checkout yet.'
       : `${getUserFacingMessage(endpoint)} (${supportCode})`;
   const error = new Error(userMessage) as BookingClientError;
   error.debugMessage = debugMessage;
@@ -355,8 +452,19 @@ function logBookingSourceDebug(
   }
 }
 
-function getAuthHeaders(): Record<string, string> {
+function isBookingGatewayUrl(url: string): boolean {
+  try {
+    return new URL(url, API_BASE).pathname.startsWith(`${BOOKING_GATEWAY_PREFIX}/`);
+  } catch {
+    return false;
+  }
+}
+
+function getAuthHeaders(url?: string): Record<string, string> {
   const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+  if (url && isBookingGatewayUrl(url)) {
+    return withBookingOutboundHeaders(headers);
+  }
   const partnerJwt = partnerPortalBookingJwtGetter();
   if (partnerJwt) {
     headers['Authorization'] = `Bearer ${partnerJwt}`;
@@ -393,7 +501,9 @@ function newBookingAttemptId(): string {
 function getEndpointFromUrl(url: string): string {
   try {
     const parsed = new URL(url, typeof window !== 'undefined' ? window.location.href : API_BASE);
-    return parsed.pathname;
+    return parsed.pathname.startsWith(`${BOOKING_GATEWAY_PREFIX}/`)
+      ? parsed.pathname.slice(BOOKING_GATEWAY_PREFIX.length)
+      : parsed.pathname;
   } catch {
     return '';
   }
@@ -442,7 +552,10 @@ function getBrowserDiagnostics(): Record<string, number | string | boolean> {
 function getAvailabilityQueryShape(url: string): Record<string, string | boolean | string[]> | null {
   try {
     const parsed = new URL(url, typeof window !== 'undefined' ? window.location.href : API_BASE);
-    if (parsed.pathname !== '/1/get-availabilities') return null;
+    const endpoint = parsed.pathname.startsWith(`${BOOKING_GATEWAY_PREFIX}/`)
+      ? parsed.pathname.slice(BOOKING_GATEWAY_PREFIX.length)
+      : parsed.pathname;
+    if (endpoint !== '/1/get-availabilities') return null;
     const params = parsed.searchParams;
     return {
       queryKeys: Array.from(params.keys()).sort(),
@@ -556,6 +669,8 @@ async function collectNetworkFailureProbeResults(
 ): Promise<Array<Record<string, number | string | boolean | null>>> {
   if (typeof window === 'undefined') return [];
   const cacheBust = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  const telemetryUrl = `${BOOKING_READ_API_BASE}/1/client-telemetry`;
+  const telemetryIsSameOrigin = new URL(telemetryUrl, window.location.href).origin === window.location.origin;
   return Promise.all([
     runNetworkFailureProbe(
       'same_origin_asset_head',
@@ -563,11 +678,11 @@ async function collectNetworkFailureProbeResults(
       { method: 'HEAD', mode: 'same-origin' }
     ),
     runNetworkFailureProbe(
-      'api_telemetry_cors_post',
-      `${API_BASE}/1/client-telemetry`,
+      telemetryIsSameOrigin ? 'booking_telemetry_same_origin_post' : 'api_telemetry_cors_post',
+      telemetryUrl,
       {
         method: 'POST',
-        mode: 'cors',
+        mode: telemetryIsSameOrigin ? 'same-origin' : 'cors',
         headers: {
           'Content-Type': 'application/json',
           [BOOKING_CORRELATION_HEADER]: correlationId,
@@ -575,10 +690,11 @@ async function collectNetworkFailureProbeResults(
         },
         body: JSON.stringify({
           event: 'BOOKING_DIALOG_NETWORK_PROBE_PING',
+          clientBuildId: ENV.BOOKING_CLIENT_BUILD_ID,
           endpoint,
           correlationId,
           traceparent,
-          apiBase: API_BASE,
+          apiBase: BOOKING_READ_API_BASE,
           pageUrl: sanitizeBookingSourceUrl(window.location.href) ?? window.location.origin,
           userAgent: window.navigator.userAgent,
           online: window.navigator.onLine,
@@ -610,7 +726,7 @@ function bookingRequestTelemetryContext(
     attemptNumber,
     maxRetries: BOOKING_GET_MAX_RETRIES,
     requestUrlPath: endpoint,
-    requestMode: 'cors',
+    requestMode: isBookingGatewayUrl(url) ? 'same-origin' : 'cors',
     requestCache: 'default',
     requestCredentials: 'same-origin',
     requestUrlSearchLength: (() => {
@@ -641,23 +757,22 @@ async function fetchBookingGetWithRetry(
     }
     const requestAttemptId = newBookingAttemptId();
     const headers: Record<string, string> = {
-      ...getAuthHeaders(),
+      ...getAuthHeaders(url),
       [BOOKING_ATTEMPT_HEADER]: requestAttemptId,
     };
     const startedAt = typeof performance !== 'undefined' ? performance.now() : Date.now();
-    if (isBookingCriticalEndpoint(endpoint)) {
-      reportBookingClientTelemetryEvent('BOOKING_DIALOG_REQUEST_STARTED', {
-        ...bookingRequestTelemetryContext(url, endpoint, headers, requestAttemptId, attempt + 1),
-      });
-    }
     try {
       const res = await fetch(url, {
         ...extra,
         method: 'GET',
         headers,
       });
+      if (res.status === 401) {
+        notifyPartnerPortalAuthorizationFailure();
+      }
       const elapsedMs = Math.round((typeof performance !== 'undefined' ? performance.now() : Date.now()) - startedAt);
       if (
+        !res.ok ||
         elapsedMs >= SLOW_REQUEST_THRESHOLD_MS ||
         (isBookingCriticalEndpoint(endpoint) && Math.random() < SUCCESS_TIMING_SAMPLE_RATE)
       ) {
@@ -665,6 +780,9 @@ async function fetchBookingGetWithRetry(
           ...bookingRequestTelemetryContext(url, endpoint, headers, requestAttemptId, attempt + 1, elapsedMs),
           httpStatus: res.status,
           ok: res.ok,
+          sampleRate: !res.ok || elapsedMs >= SLOW_REQUEST_THRESHOLD_MS ? 1 : SUCCESS_TIMING_SAMPLE_RATE,
+          slowThresholdMs: SLOW_REQUEST_THRESHOLD_MS,
+          ...gatewayResponseMetadata(res),
           resourceTiming: latestResourceTiming(url),
         });
       }
@@ -675,6 +793,12 @@ async function fetchBookingGetWithRetry(
         attempt < BOOKING_GET_MAX_RETRIES &&
         (res.status === 502 || res.status === 503 || res.status === 504)
       ) {
+        reportBookingClientTelemetryEvent('BOOKING_DIALOG_REQUEST_RETRYING', {
+          ...bookingRequestTelemetryContext(url, endpoint, headers, requestAttemptId, attempt + 1, elapsedMs),
+          httpStatus: res.status,
+          retryReason: 'retryable_http_status',
+          ...gatewayResponseMetadata(res),
+        });
         continue;
       }
       return res;
@@ -874,9 +998,16 @@ export interface PricingConfig {
   cancellationPolicies?: CancellationPolicyOption[];
 }
 
-export async function fetchProducts(companyId: string): Promise<Product[]> {
+export async function fetchProducts(
+  companyId: string,
+  options?: { productId?: string }
+): Promise<Product[]> {
   const endpoint = '/1/products';
-  const url = `${API_BASE}${endpoint}?companyId=${encodeURIComponent(companyId)}`;
+  const params = new URLSearchParams({ companyId });
+  if (options?.productId?.trim()) {
+    params.set('productId', options.productId.trim());
+  }
+  const url = `${bookingReadApiBase()}${endpoint}?${params}`;
   let res: Response;
   try {
     res = await fetchBookingGetWithRetry(url);
@@ -900,6 +1031,7 @@ export async function fetchProducts(companyId: string): Promise<Product[]> {
       message: debugMessage,
       httpStatus: res.status,
       errorCode: isApiErrorPayload(errPayload) ? errPayload.errorCode : undefined,
+      metadata: gatewayResponseMetadata(res),
     });
     throw createUserError(endpoint, 'HTTP', debugMessage);
   }
@@ -912,6 +1044,7 @@ export async function fetchProducts(companyId: string): Promise<Product[]> {
       errorClass: 'APP_ERROR_200',
       message: appError,
       errorCode: isApiErrorPayload(data) ? data.errorCode : undefined,
+      metadata: gatewayResponseMetadata(res),
     });
     throw createUserError(endpoint, 'APP_ERROR_200', appError);
   }
@@ -921,13 +1054,13 @@ export async function fetchProducts(companyId: string): Promise<Product[]> {
 }
 
 export async function getProduct(productId: string, companyId: string): Promise<Product | null> {
-  const products = await fetchProducts(companyId);
+  const products = await fetchProducts(companyId, { productId });
   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)}`,
+    `${bookingReadApiBase()}/1/companies/${encodeURIComponent(companyId)}`,
   );
   if (!res.ok) {
     const err = await res.json();
@@ -965,7 +1098,7 @@ export async function validatePromoCode(
   if (normalizedProductId) params.set('productId', normalizedProductId);
   if (hasOngoingDiscount === true) params.set('hasOngoingDiscount', 'true');
   if (dateTime?.trim()) params.set('dateTime', dateTime.trim());
-  const res = await fetchBookingGetWithRetry(`${API_BASE}/1/validate-promo?${params}`);
+  const res = await fetchBookingGetWithRetry(`${bookingReadApiBase()}/1/validate-promo?${params}`);
   if (!res.ok) {
     const err = await res.json();
     throw new Error(err.errorMessage || err.error || 'Failed to validate promo code');
@@ -1094,7 +1227,7 @@ export async function getPromoDiscount(
   ) {
     params.set('legacyPromoNewAddOnSubtotal', String(bookingChange.legacyPromoNewAddOnSubtotal));
   }
-  const res = await fetchBookingGetWithRetry(`${API_BASE}/1/get-promo-discount?${params}`);
+  const res = await fetchBookingGetWithRetry(`${bookingReadApiBase()}/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');
@@ -1114,7 +1247,7 @@ export async function getAddOns(
   }
   if (options?.preCheckout !== undefined) params.set('preCheckout', String(options.preCheckout));
   if (options?.dateTime?.trim()) params.set('dateTime', options.dateTime.trim());
-  const res = await fetchBookingGetWithRetry(`${API_BASE}/1/add-ons?${params}`);
+  const res = await fetchBookingGetWithRetry(`${bookingReadApiBase()}/1/add-ons?${params}`);
   if (!res.ok) {
     const err = await res.json();
     throw new Error(err.errorMessage || err.error || 'Failed to get add-ons');
@@ -1779,6 +1912,7 @@ export async function quoteAdminChangeBookingV2(
   request: ChangeBookingQuoteRequest
 ): Promise<ChangeBookingQuoteResponse> {
   const { bookingReference, lastName: _lastName, ...payload } = request;
+  void _lastName;
   const res = await fetch(
     `${API_BASE}/1/admin/bookings/${encodeURIComponent(bookingReference)}/change/quote-v2`,
     {
@@ -2093,7 +2227,7 @@ export async function getAvailabilities(
     params.set('cancellationPolicyProfileId', cancellationPolicyProfileId);
   }
   const endpoint = '/1/get-availabilities';
-  const url = `${API_BASE}${endpoint}?${params}`;
+  const url = `${bookingReadApiBase()}${endpoint}?${params}`;
   let res: Response;
   try {
     res = await fetchBookingGetWithRetry(url);
@@ -2117,6 +2251,7 @@ export async function getAvailabilities(
       message: debugMessage,
       httpStatus: res.status,
       errorCode: isApiErrorPayload(errPayload) ? errPayload.errorCode : undefined,
+      metadata: gatewayResponseMetadata(res),
     });
     throw createUserError(endpoint, 'HTTP', debugMessage);
   }
@@ -2129,6 +2264,7 @@ export async function getAvailabilities(
       errorClass: 'APP_ERROR_200',
       message: appError,
       errorCode: isApiErrorPayload(data) ? data.errorCode : undefined,
+      metadata: gatewayResponseMetadata(res),
     });
     throw createUserError(endpoint, 'APP_ERROR_200', appError);
   }
@@ -2191,6 +2327,8 @@ export interface ReserveRequest {
   source?: string;
   sourceMetadata?: BookingSourceMetadata;
   source_metadata?: BookingSourceMetadata;
+  /** One key per logical hold attempt; generated and retained by createReservation when enabled. */
+  idempotencyKey?: string;
 }
 
 /** Safe subset of reserve payload for telemetry (no free-text traveler fields). */
@@ -2368,9 +2506,107 @@ export interface ReserveResponse {
   currency?: string;
 }
 
+interface ReserveApiEnvelope {
+  data?: Partial<ReserveResponse> & { state?: string; retryAfterMs?: number };
+  errorCode?: string;
+  errorMessage?: string;
+  error?: string;
+  message?: string;
+}
+
+function parseReserveEnvelope(text: string): ReserveApiEnvelope {
+  try {
+    return JSON.parse(text) as ReserveApiEnvelope;
+  } catch {
+    return { errorMessage: text || 'Invalid response from server' };
+  }
+}
+
+function normalizedReserveResponse(data: ReserveApiEnvelope['data']): ReserveResponse | null {
+  if (!data?.reservationReference) return null;
+  const expiration = data.reservationExpiration ?? data.expiresAt;
+  if (!expiration) return null;
+  return {
+    reservationReference: data.reservationReference,
+    reservationExpiration: expiration,
+    expiresAt: expiration,
+    totalAmount: data.totalAmount,
+    currency: data.currency,
+  };
+}
+
+function reserveEnvelopeError(payload: ReserveApiEnvelope, fallback: string): {
+  code?: string;
+  message: string;
+} {
+  return {
+    code: payload.errorCode,
+    message: payload.errorMessage || payload.error || payload.message || fallback,
+  };
+}
+
+async function recoverReservationAttempt(
+  reservePayload: ReserveRequest,
+  attempt: ReservationAttemptContext<ReserveRequest>
+): Promise<ReserveResponse> {
+  const endpoint = '/1/reserve/status';
+  const delays = [0, 250, 750, 1500];
+  let lastMessage = 'The reservation outcome is still unknown.';
+  for (const delay of delays) {
+    if (delay > 0) {
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+    let response: Response;
+    try {
+      response = await fetch(`${API_BASE}${endpoint}`, {
+        method: 'POST',
+        headers: getAuthHeaders(),
+        body: JSON.stringify({ data: reservePayload }),
+      });
+    } catch (error) {
+      lastMessage = error instanceof Error ? error.message : String(error);
+      continue;
+    }
+    const payload = parseReserveEnvelope(await response.text());
+    const recovered = normalizedReserveResponse(payload.data);
+    if (response.ok && recovered) {
+      attempt.clear();
+      return recovered;
+    }
+    if (response.status === 202 || payload.data?.state === 'IN_PROGRESS') {
+      lastMessage = 'The reservation is still being processed.';
+      continue;
+    }
+    const failure = reserveEnvelopeError(payload, `Recovery failed with HTTP ${response.status}`);
+    lastMessage = failure.message;
+    if (response.status === 422) {
+      attempt.clear();
+      throw createUserError(endpoint, 'HTTP', failure.message, failure.code);
+    }
+    if (response.status === 400 || response.status === 409) {
+      throw createUserError(endpoint, 'HTTP', failure.message, failure.code);
+    }
+  }
+  reportClientFetchError({
+    endpoint,
+    errorClass: 'NETWORK',
+    message: lastMessage,
+    errorCode: 'RESERVATION_OUTCOME_UNKNOWN',
+    metadata: {
+      failureKind: 'RESERVATION_RECOVERY_EXHAUSTED',
+      reserveRequest: summarizeReserveRequestForTelemetry(reservePayload),
+    },
+  });
+  throw createUserError(endpoint, 'NETWORK', lastMessage, 'RESERVATION_OUTCOME_UNKNOWN');
+}
+
 export async function createReservation(request: ReserveRequest): Promise<ReserveResponse> {
   const endpoint = '/1/reserve';
-  const reservePayload = withExplicitBookingSource(request);
+  const baseReservePayload = withExplicitBookingSource(request);
+  const attempt = reservationIdempotencyEnabled()
+    ? await getOrCreateReservationAttempt(baseReservePayload)
+    : null;
+  const reservePayload = attempt?.request ?? baseReservePayload;
   let res: Response;
   try {
     res = await fetch(`${API_BASE}${endpoint}`, {
@@ -2380,6 +2616,9 @@ export async function createReservation(request: ReserveRequest): Promise<Reserv
     });
   } catch (err) {
     const debugMessage = err instanceof Error ? err.message : String(err);
+    if (attempt) {
+      return recoverReservationAttempt(reservePayload, attempt);
+    }
     reportClientFetchError({
       endpoint,
       errorClass: 'NETWORK',
@@ -2392,15 +2631,23 @@ export async function createReservation(request: ReserveRequest): Promise<Reserv
     throw createUserError(endpoint, 'NETWORK', debugMessage);
   }
   const text = await res.text();
+  const payload = parseReserveEnvelope(text);
+  if (res.status === 202 && attempt) {
+    return recoverReservationAttempt(reservePayload, attempt);
+  }
   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 failure = reserveEnvelopeError(payload, 'Failed to create reservation');
+    const ambiguousTransportOutcome =
+      failure.code === 'RESERVATION_OUTCOME_UNKNOWN' ||
+      (res.status >= 500 && failure.code !== 'IDEMPOTENCY_UNAVAILABLE');
+    if (attempt && ambiguousTransportOutcome) {
+      return recoverReservationAttempt(reservePayload, attempt);
     }
-    const debugMessage = err.errorMessage || err.error || 'Failed to create reservation';
-    const insufficientCapacity = isInsufficientCapacityApiError(err.errorCode, debugMessage);
+    if (attempt && failure.code !== 'IDEMPOTENCY_CONFLICT') {
+      attempt.clear();
+    }
+    const debugMessage = failure.message;
+    const insufficientCapacity = isInsufficientCapacityApiError(failure.code, debugMessage);
     reportClientFetchError({
       endpoint,
       errorClass: 'HTTP',
@@ -2408,66 +2655,45 @@ export async function createReservation(request: ReserveRequest): Promise<Reserv
         ? `[RESERVE_INSUFFICIENT_CAPACITY] ${debugMessage}`
         : debugMessage,
       httpStatus: res.status,
-      errorCode: err.errorCode,
+      errorCode: failure.code,
       metadata: {
         failureKind: insufficientCapacity
           ? 'RESERVE_INSUFFICIENT_CAPACITY'
           : 'RESERVE_HTTP_ERROR',
         reserveRequest: summarizeReserveRequestForTelemetry(request),
         apiErrorMessage: debugMessage,
-        apiErrorCode: err.errorCode ?? null,
+        apiErrorCode: failure.code ?? 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');
+    throw createUserError(endpoint, 'HTTP', debugMessage, failure.code);
   }
-  if (data.errorCode || data.errorMessage) {
-    const debugMessage = data.errorMessage || 'Failed to create reservation';
-    const insufficientCapacity = isInsufficientCapacityApiError(data.errorCode, debugMessage);
+  if (payload.errorCode || payload.errorMessage) {
+    const failure = reserveEnvelopeError(payload, 'Failed to create reservation');
+    attempt?.clear();
+    const debugMessage = failure.message;
+    const insufficientCapacity = isInsufficientCapacityApiError(failure.code, debugMessage);
     reportClientFetchError({
       endpoint,
       errorClass: 'APP_ERROR_200',
       message: insufficientCapacity
         ? `[RESERVE_INSUFFICIENT_CAPACITY] ${debugMessage}`
         : debugMessage,
-      errorCode: data.errorCode,
+      errorCode: failure.code,
       metadata: {
         failureKind: insufficientCapacity
           ? 'RESERVE_INSUFFICIENT_CAPACITY'
           : 'RESERVE_APP_ERROR_200',
         reserveRequest: summarizeReserveRequestForTelemetry(request),
         apiErrorMessage: debugMessage,
-        apiErrorCode: data.errorCode ?? null,
+        apiErrorCode: failure.code ?? 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');
+    throw createUserError(endpoint, 'APP_ERROR_200', debugMessage, failure.code);
   }
-  return {
-    reservationReference: raw.reservationReference,
-    reservationExpiration: expiration,
-    expiresAt: expiration,
-    totalAmount: raw.totalAmount,
-    currency: raw.currency,
-  };
+  const normalized = normalizedReserveResponse(payload.data);
+  if (!normalized) throw new Error('Invalid response: missing reservationReference or hold expiration');
+  attempt?.clear();
+  return normalized;
 }
 
 export async function cancelReservation(reservationReference: string): Promise<void> {

package/src/lib/env.ts

@@ -24,6 +24,17 @@ const getApiUrl = (): string => {
   return apiUrl;
 };
 
+/**
+ * Read-only booking traffic can use a same-origin gateway while transactional
+ * writes continue to use NEXT_PUBLIC_API_URL.
+ */
+const getBookingReadApiUrl = (): string => {
+  return process.env.NEXT_PUBLIC_BOOKING_READ_API_URL?.trim() || getApiUrl();
+};
+
+const getBookingClientBuildId = (): string =>
+  process.env.NEXT_PUBLIC_BOOKING_CLIENT_BUILD_ID?.trim() || 'source-unknown';
+
 const getGoogleMapsApiKey = (): string => {
   return process.env.NEXT_PUBLIC_GOOGLE_MAPS_API_KEY ?? '';
 };
@@ -92,6 +103,8 @@ export const isLocalhost = (): boolean =>
 
 export const ENV = {
   API_URL: getApiUrl(),
+  BOOKING_READ_API_URL: getBookingReadApiUrl(),
+  BOOKING_CLIENT_BUILD_ID: getBookingClientBuildId(),
   GOOGLE_MAPS_API_KEY: getGoogleMapsApiKey(),
   STRIPE_PUBLISHABLE_KEY: getStripePublishableKey(),
   BASIC_AUTH: getBasicAuth(),