@ticketboothapp/booking 0.1.10 → 0.1.12

package/src/lib/booking/correlation-id.ts

@@ -0,0 +1,46 @@
+/**
+ * One opaque id per browser tab/session for joining client telemetry → TicketBooth Lambda logs.
+ */
+
+export const BOOKING_CORRELATION_HEADER = 'X-Correlation-Id';
+
+const STORAGE_KEY = 'tb_booking_correlation_id';
+
+function newCorrelationId(): string {
+  try {
+    if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+      return crypto.randomUUID();
+    }
+  } catch {
+    /* fall through */
+  }
+  return `${Date.now()}-${Math.random().toString(36).slice(2, 12)}`;
+}
+
+/** Stable for the lifetime of this tab's sessionStorage (until the tab closes / storage cleared). */
+export function getOrCreateBookingCorrelationId(): string {
+  if (typeof window === 'undefined') return '';
+  try {
+    let id = sessionStorage.getItem(STORAGE_KEY);
+    if (!id) {
+      id = newCorrelationId();
+      sessionStorage.setItem(STORAGE_KEY, id);
+    }
+    return id;
+  } catch {
+    return newCorrelationId();
+  }
+}
+
+/** Merge correlation header into outbound API headers (browser only). */
+export function withBookingCorrelationId(
+  headers: Record<string, string>
+): Record<string, string> {
+  if (typeof window === 'undefined') return headers;
+  const id = getOrCreateBookingCorrelationId();
+  if (!id) return headers;
+  return {
+    ...headers,
+    [BOOKING_CORRELATION_HEADER]: id,
+  };
+}

package/src/lib/{i18n → booking/i18n}/messages/en.json

@@ -6,6 +6,10 @@
     "change": "Change",
     "cancel": "Cancel",
     "close": "Close",
+    "videoPause": "Pause video",
+    "videoPlay": "Play video",
+    "videoMute": "Mute",
+    "videoUnmute": "Unmute",
     "loading": "Loading...",
     "error": "Error",
     "total": "Total",
@@ -19,6 +23,13 @@
     "requestDifferentTime": "Request different time",
     "preferredPickupTime": "Preferred pickup time",
     "selectReturnTime": "Select Return Time",
+    "selectPhotoSessionTime": "Select session time",
+    "dapPhotoSessionAddOn": "Photo session (add-on)",
+    "dapYourCurrentItinerary": "Your current itinerary",
+    "dapRefItineraryLoading": "Looking up your booking…",
+    "dapRefItineraryEmpty": "We didn’t get shuttle times for this reference yet. Your booking may still be valid — choose a session length (if needed) and load available times.",
+    "dapRefItineraryLookupFailed": "We couldn’t find a booking with that reference, or it isn’t eligible for this add-on. Double-check the code from your confirmation.",
+    "dapItineraryFallbackFoot": "After you pay, you’ll see this add-on with your full itinerary in Manage booking.",
     "mostPopular": "Most popular",
     "pickupAtTourStart": "<b>Your pickup time depends on your pickup location.</b><br>Your exact pickup time will be confirmed once you have confirmed your pickup location. Pickups start in Canmore and end in Lake Louise.",
     "pickupAtTourStartLocation": "tour start location",
@@ -53,15 +64,25 @@
     "dropOffAtPickup": "Arrive at {pickupLocation}",
     "yourPickupLocation": "your pickup location",
     "tickets": "Tickets",
+    "overbookingWarnDeparture": "WARN OVERBOOKING: Only {count} seats available on {time} departure.",
+    "overbookingWarnReturn": "WARN OVERBOOKING: Only {count} seats available on {time} return.",
+    "overbookingWarnBoth": "WARN OVERBOOKING: Only {count} seats available on both trip directions.",
+    "overbookingResourcesSuffix": "({count} shared resources.)",
+    "adminBookingLoadLine1": "Booking {projected} /",
+    "adminBookingLoadLine2": "{total} total",
     "available": "available",
     "soldOut": "Sold out",
     "continueToPayment": "Continue to Payment",
+    "continueToSecurePayment": "Continue to secure payment",
+    "preparingCheckout": "Preparing…",
     "creatingReservation": "Creating reservation...",
     "securePayment": "Secure payment powered by Stripe",
     "selectTimeAndTickets": "Please select a time and at least one ticket",
     "selectPickupLocation": "Please select a pickup location",
     "loadingTimes": "Loading available times...",
     "noAvailability": "No availability found for the next 30 days. Please check back later.",
+    "seeFullTourDescription": "See full tour description",
+    "seeFullAddOnDescription": "See full experience details",
     "communicationPreference": "How would you like to receive future communication (confirmation, reminders, etc.)?",
     "communicationEmail": "Email",
     "communicationEmailDesc": "Send confirmation via email",
@@ -74,17 +95,24 @@
     "invalidPhoneNumber": "Please enter a valid phone number",
     "selectCommunicationPreference": "Please select how you would like to receive your confirmation",
     "enterEmail": "Please enter your email address",
+    "enterFirstName": "Please enter your first name",
     "enterLastName": "Please enter your last name",
     "enterPhoneNumber": "Please enter your phone number",
     "firstName": "First Name",
     "firstNamePlaceholder": "Jane",
     "lastName": "Last Name",
     "lastNamePlaceholder": "Smith",
+    "dapNoLastNameOnFile": "We couldn’t find a last name on this booking in our system. Please contact us, or use Manage booking with the last name from your confirmation email.",
+    "dapCancellationPolicyHeading": "Cancellation policy",
+    "dapCancellationPolicyBody": "You may cancel this add-on for a full refund up to {days} {daysUnit} before your scheduled photo session. Cancellations made after that deadline may forfeit the entire add-on cost.",
+    "dapCancellationPolicyDayUnit": "day",
+    "dapCancellationPolicyDaysUnit": "days",
     "noActiveOption": "No active product options available",
     "people": "people",
     "person": "person",
     "rounding": "Rounding",
     "deposit": "Deposit",
+    "totalOwedForBookingChange": "Total owed for booking difference",
     "subtotal": "Subtotal",
     "tax": "Taxes and fees",
     "returnOption": "Return Option",
@@ -110,8 +138,11 @@
     "promoCodesCannotStackWithDiscounts": "Promo codes cannot be stacked with deals",
     "discount": "Discount",
     "cancellationPolicy": "Cancellation policy",
-    "promoRequiresCancellationPolicy": "This promo requires {{policy}}",
-    "promoRequiresThisPolicy": "Required by your promo code",
+    "promoIncludesCancellationPolicy": "This promo includes {label} cancellation policy",
+    "cancellationRefundTierDays": "Cancel <b>{days} days before</b> for <b>{percent}% refund</b>",
+    "cancellationRefundTierHours": "Cancel <b>{hours} hours before</b> for <b>{percent}% refund</b>",
+    "cancellationNoRefunds": "<b>No cancellation, no refunds</b>. You can make changes to your booking up to <b>{days} days before</b>.",
+    "cancellationNoRefundsNoDays": "<b>No cancellation, no refunds</b>. You can make changes to your booking before your booking date.",
     "cancellationStandard": "Standard cancellation",
     "included": "Included",
     "flexibleCancellation": "Flexible cancellation",
@@ -145,13 +176,18 @@
     "yesAddNowSubtext": "You can change this later.",
     "skipWarningTitle": "Important Notice",
     "skipWarningMessage": "You are not guaranteed to be picked up if you do not <b>update your booking with your pickup location at least 12 hours prior</b>.",
-    "iUnderstand": "I understand"
+    "iUnderstand": "I understand",
+    "nevermindSelectLocation": "Nevermind, I'll select my location",
+    "outsideServiceArea": "This address is outside our service area. We offer pickups between Lake Louise and Kananaskis. Please choose a preset location or search for an address in that area."
   },
   "calendar": {
     "previousWeeks": "Previous 2 weeks",
     "nextWeeks": "Next 2 weeks",
     "soldOut": "Sold out",
     "left": "{count} left",
+    "timesAvailable": "{count} times",
+    "spotsAvailable": "{count} available",
+    "available": "Available",
     "days": {
       "sun": "SUN",
       "mon": "MON",
@@ -179,7 +215,15 @@
   "products": {
     "backToExperiences": "Back to experiences",
     "from": "From",
-    "noDescription": "No description available"
+    "noDescription": "No description available",
+    "productGridFilters": {
+      "all": "All",
+      "moraineLake": "Moraine Lake",
+      "lakeLouise": "Lake Louise",
+      "emeraldLake": "Emerald Lake",
+      "private": "Private",
+      "sunrise": "Sunrise"
+    }
   },
   "terms": {
     "title": "Terms & Conditions",

package/src/lib/{i18n → booking/i18n}/messages/fr.json

@@ -6,6 +6,10 @@
     "change": "Changer",
     "cancel": "Annuler",
     "close": "Fermer",
+    "videoPause": "Mettre en pause",
+    "videoPlay": "Lire la vidéo",
+    "videoMute": "Couper le son",
+    "videoUnmute": "Activer le son",
     "loading": "Chargement...",
     "error": "Erreur",
     "total": "Total",
@@ -19,6 +23,13 @@
     "requestDifferentTime": "Demander une autre heure",
     "preferredPickupTime": "Heure de prise en charge préférée",
     "selectReturnTime": "Sélectionner l'heure de retour",
+    "selectPhotoSessionTime": "Choisir l'heure de la séance photo",
+    "dapPhotoSessionAddOn": "Séance photo (option)",
+    "dapYourCurrentItinerary": "Votre itinéraire actuel",
+    "dapRefItineraryLoading": "Recherche de votre réservation…",
+    "dapRefItineraryEmpty": "Nous n’avons pas encore d’horaires de navette pour cette référence. Votre réservation peut quand même être valide — choisissez une durée de séance (si besoin) et chargez les heures disponibles.",
+    "dapRefItineraryLookupFailed": "Nous n’avons pas trouvé de réservation avec cette référence, ou elle n’est pas admissible à cette option. Vérifiez le code dans votre courriel de confirmation.",
+    "dapItineraryFallbackFoot": "Après le paiement, vous verrez cette option avec l’itinéraire complet dans Gérer la réservation.",
     "mostPopular": "Le plus populaire",
     "pickupAtTourStart": "<b>Votre heure de prise en charge dépend de votre lieu de prise en charge.</b><br>Votre heure de prise en charge exacte sera confirmée une fois que vous aurez confirmé votre lieu de prise en charge. Les prises en charge commencent à Canmore et se terminent à Lake Louise.",
     "pickupAtTourStartLocation": "lieu de départ du tour",
@@ -53,15 +64,25 @@
     "dropOffAtPickup": "Arrivée à {pickupLocation}",
     "yourPickupLocation": "votre lieu de prise en charge",
     "tickets": "Billets",
+    "overbookingWarnDeparture": "ALERTE SURRÉSERVATION : seulement {count} places pour le départ à {time}.",
+    "overbookingWarnReturn": "ALERTE SURRÉSERVATION : seulement {count} places pour le retour à {time}.",
+    "overbookingWarnBoth": "ALERTE SURRÉSERVATION : seulement {count} places sur les deux segments du trajet (aller et retour).",
+    "overbookingResourcesSuffix": "({count} ressources partagées.)",
+    "adminBookingLoadLine1": "Réservation {projected} /",
+    "adminBookingLoadLine2": "{total} au total",
     "available": "disponible",
     "soldOut": "Complet",
     "continueToPayment": "Continuer vers le paiement",
+    "continueToSecurePayment": "Continuer vers le paiement sécurisé",
+    "preparingCheckout": "Préparation…",
     "creatingReservation": "Création de la réservation...",
     "securePayment": "Paiement sécurisé par Stripe",
     "selectTimeAndTickets": "Veuillez sélectionner une heure et au moins un billet",
     "selectPickupLocation": "Veuillez sélectionner un lieu de prise en charge",
     "loadingTimes": "Chargement des heures disponibles...",
     "noAvailability": "Aucune disponibilité trouvée pour les 30 prochains jours. Veuillez réessayer plus tard.",
+    "seeFullTourDescription": "Voir la description complète du circuit",
+    "seeFullAddOnDescription": "Voir tous les détails de l'expérience",
     "communicationPreference": "Comment souhaitez-vous recevoir les communications futures (confirmation, rappels, etc.)?",
     "communicationEmail": "Courriel",
     "communicationEmailDesc": "Envoyer la confirmation par courriel",
@@ -74,17 +95,24 @@
     "invalidPhoneNumber": "Veuillez entrer un numéro de téléphone valide",
     "selectCommunicationPreference": "Veuillez sélectionner comment vous souhaitez recevoir votre confirmation",
     "enterEmail": "Veuillez entrer votre adresse courriel",
+    "enterFirstName": "Veuillez entrer votre prénom",
     "enterLastName": "Veuillez entrer votre nom de famille",
     "enterPhoneNumber": "Veuillez entrer votre numéro de téléphone",
     "firstName": "Prénom",
     "firstNamePlaceholder": "Jeanne",
     "lastName": "Nom de famille",
     "lastNamePlaceholder": "Dupont",
+    "dapNoLastNameOnFile": "Nous n’avons pas trouvé de nom de famille pour cette réservation. Contactez-nous, ou utilisez Gérer la réservation avec le nom figurant sur votre courriel de confirmation.",
+    "dapCancellationPolicyHeading": "Politique d’annulation",
+    "dapCancellationPolicyBody": "Vous pouvez annuler cette option avec remboursement intégral jusqu’à {days} {daysUnit} avant votre séance photo prévue. Toute annulation après cette date peut entraîner la perte du montant total de l’option.",
+    "dapCancellationPolicyDayUnit": "jour",
+    "dapCancellationPolicyDaysUnit": "jours",
     "noActiveOption": "Aucune option de produit disponible",
     "people": "personnes",
     "person": "personne",
     "rounding": "Arrondi",
     "deposit": "Acompte",
+    "totalOwedForBookingChange": "Montant dû pour le changement de réservation",
     "subtotal": "Sous-total",
     "tax": "Taxes et frais",
     "returnOption": "Option de retour",
@@ -110,8 +138,11 @@
     "promoCodesCannotStackWithDiscounts": "Les codes promo ne peuvent pas être cumulés avec les offres",
     "discount": "Réduction",
     "cancellationPolicy": "Politique d'annulation",
-    "promoRequiresCancellationPolicy": "Ce code promo exige {{policy}}",
-    "promoRequiresThisPolicy": "Exigé par votre code promo",
+    "promoIncludesCancellationPolicy": "Ce code promo inclut la politique d'annulation {label}",
+    "cancellationRefundTierDays": "Annuler <b>{days} jours avant</b> pour <b>{percent}% de remboursement</b>",
+    "cancellationRefundTierHours": "Annuler <b>{hours} heures avant</b> pour <b>{percent}% de remboursement</b>",
+    "cancellationNoRefunds": "<b>Pas d'annulation, pas de remboursement</b>. Vous pouvez modifier votre réservation jusqu'à <b>{days} jours avant</b>.",
+    "cancellationNoRefundsNoDays": "<b>Pas d'annulation, pas de remboursement</b>. Vous pouvez modifier votre réservation avant la date de votre réservation.",
     "cancellationStandard": "Annulation standard",
     "included": "Inclus",
     "flexibleCancellation": "Annulation flexible",
@@ -145,13 +176,18 @@
     "yesAddNowSubtext": "Vous pourrez modifier cela plus tard.",
     "skipWarningTitle": "Avis important",
     "skipWarningMessage": "Vous n'êtes pas garanti d'être pris en charge si vous ne <b>mettez pas à jour votre réservation avec votre lieu de prise en charge au moins 12 heures à l'avance</b>.",
-    "iUnderstand": "Je comprends"
+    "iUnderstand": "Je comprends",
+    "nevermindSelectLocation": "Annuler, je vais sélectionner mon lieu",
+    "outsideServiceArea": "Cette adresse est en dehors de notre zone de service. Nous proposons des prises en charge entre le lac Louise et Kananaskis. Veuillez choisir un lieu prédéfini ou rechercher une adresse dans cette zone."
   },
   "calendar": {
     "previousWeeks": "2 semaines précédentes",
     "nextWeeks": "2 semaines suivantes",
     "soldOut": "Complet",
     "left": "{count} restant",
+    "timesAvailable": "{count} départs",
+    "spotsAvailable": "{count} places",
+    "available": "Disponible",
     "days": {
       "sun": "DIM",
       "mon": "LUN",
@@ -179,7 +215,15 @@
   "products": {
     "backToExperiences": "Retour aux expériences",
     "from": "À partir de",
-    "noDescription": "Aucune description disponible"
+    "noDescription": "Aucune description disponible",
+    "productGridFilters": {
+      "all": "Tous",
+      "moraineLake": "Lac Moraine",
+      "lakeLouise": "Lac Louise",
+      "emeraldLake": "Lac Émeraude",
+      "private": "Privé",
+      "sunrise": "Levé de soleil"
+    }
   },
   "terms": {
     "title": "Conditions générales",

package/src/lib/booking/itinerary-display.ts

@@ -0,0 +1,36 @@
+/**
+ * Shared itinerary step labels for manage booking, change-booking dialog, etc.
+ * Keeps display consistent with BookingDetails.
+ */
+export type ItineraryStepForLabel = {
+  label?: string | null;
+  place?: string | null;
+  stepType?: string | null;
+};
+
+export function getItineraryStepLabel(step: ItineraryStepForLabel): string {
+  if (step.label?.trim()) return step.label.trim();
+  const place = step.place?.trim();
+  const placeDisplay =
+    place === 'your_pickup_location'
+      ? 'your pickup location'
+      : place === 'the_destination'
+        ? 'the destination'
+        : place ?? '';
+  switch (step.stepType) {
+    case 'pickup':
+      return placeDisplay ? `Pickup at ${placeDisplay}` : 'Pickup';
+    case 'drop_off':
+      return placeDisplay ? `Drop off at ${placeDisplay}` : 'Drop-off';
+    case 'arrive':
+      return placeDisplay ? `Arrive at ${placeDisplay}` : 'Arrive';
+    case 'depart':
+      return placeDisplay ? `Depart ${placeDisplay}` : 'Depart';
+    case 'trip_end':
+      return 'Trip ends';
+    case 'draft':
+      return placeDisplay || 'Stop';
+    default:
+      return placeDisplay || (step.stepType ?? 'Step');
+  }
+}

package/src/lib/{itinerary-labels.ts → booking/itinerary-labels.ts}

@@ -1,4 +1,4 @@
-import type { ItineraryDisplayStep } from './api';
+import type { ItineraryDisplayStep } from '@/lib/booking-api';
 
 export type TranslationFn = (key: string, params?: Record<string, string>) => string;
 

package/src/lib/{location-calculations.ts → booking/location-calculations.ts}

@@ -2,14 +2,14 @@
  * Location calculation utilities
  */
 
-import type { PickupLocation } from './api';
-import type { Coordinates } from './location-utils';
-import type { NearbyLocation } from './pickup-location-types';
+import type { PickupLocation } from '@/lib/booking-api';
+import type { Coordinates } from '@/lib/booking/location-utils';
+import type { NearbyLocation } from '@/lib/booking/pickup-location-types';
 import {
   calculateDistance,
   estimateWalkingTime,
   estimateDrivingTime,
-} from './location-utils';
+} from '@/lib/booking/location-utils';
 
 const EXACT_MATCH_THRESHOLD_KM = 0.05; // 50 meters - tighter threshold for exact matches
 

package/src/lib/{location-utils.ts → booking/location-utils.ts}

@@ -104,6 +104,32 @@ export function formatTime(minutes: number): string {
   }
 }
 
+/**
+ * Service area for Private Shuttle custom pickups: Lake Louise to Kananaskis casino corridor.
+ * Bounding box encompasses: Lake Louise, Banff, Canmore, Kananaskis.
+ * Excludes Calgary and areas east.
+ */
+export const PRIVATE_SHUTTLE_SERVICE_BOUNDS = {
+  latMin: 51.0,
+  latMax: 51.5,
+  lngMin: -116.5,
+  lngMax: -114.8,
+} as const;
+
+/**
+ * Check if coordinates are within the Private Shuttle service area
+ * (corridor from Lake Louise to Kananaskis casino).
+ */
+export function isWithinPrivateShuttleServiceArea(coords: Coordinates): boolean {
+  const { latMin, latMax, lngMin, lngMax } = PRIVATE_SHUTTLE_SERVICE_BOUNDS;
+  return (
+    coords.lat >= latMin &&
+    coords.lat <= latMax &&
+    coords.lng >= lngMin &&
+    coords.lng <= lngMax
+  );
+}
+
 /**
  * Geocode an address using Google Maps Geocoding API
  * Note: This requires a Google Maps API key

package/src/lib/{map-utils.ts → booking/map-utils.ts}

@@ -2,9 +2,9 @@
  * Google Maps utilities
  */
 
-import type { Coordinates } from './location-utils';
-import type { PickupLocation } from './api';
-import type { NearbyLocation } from './pickup-location-types';
+import type { Coordinates } from '@/lib/booking/location-utils';
+import type { PickupLocation } from '@/lib/booking-api';
+import type { NearbyLocation } from '@/lib/booking/pickup-location-types';
 
 export interface MapCenter {
   lat: number;

package/src/lib/booking/normalize-booking-product-id.ts

@@ -1,3 +1,8 @@
+/**
+ * Normalize IDs used in TicketBooth query params (product id, product option id).
+ * Strips hash fragments, accidental query strings, or concatenated `&…` tails — aligned with
+ * defensive parsing in GetAvailabilitiesHandler.
+ */
 export function normalizeBookingProductId(rawId: string): string {
   const trimmed = rawId.trim();
   if (!trimmed) return '';
@@ -7,8 +12,10 @@ export function normalizeBookingProductId(rawId: string): string {
   return normalized.trim();
 }
 
+/** True when the raw value clearly contains URL/query junk and should be normalized before use. */
 export function isSuspiciousBookingProductId(value: string): boolean {
   return /[?&=]/.test(value);
 }
 
+/** Alias: same normalization for get-availabilities lookup id (product or option). */
 export const normalizeAvailabilityLookupId = normalizeBookingProductId;

package/src/lib/{pickup-location-types.ts → booking/pickup-location-types.ts}

@@ -2,8 +2,8 @@
  * Types for pickup location selector
  */
 
-import type { PickupLocation } from './api';
-import type { Coordinates } from './location-utils';
+import type { PickupLocation } from '@/lib/booking-api';
+import type { Coordinates } from '@/lib/booking/location-utils';
 
 export interface NearbyLocation extends PickupLocation {
   distance: number;

package/src/lib/{pricing.ts → booking/pricing.ts}

@@ -1,5 +1,5 @@
-import type { Currency } from '@/components/CurrencySwitcher';
-import type { PricingConfig } from '@/lib/api';
+import type { Currency } from '@/components/booking/CurrencySwitcher';
+import type { PricingConfig } from '@/lib/booking-api';
 import { DEFAULT_EXCHANGE_RATES } from '@/lib/currency';
 
 const BASE_CURRENCY = 'CAD' as const;

package/src/lib/booking/product-option-id.ts

@@ -0,0 +1,35 @@
+/**
+ * TicketBooth / GYG-style ids: bookings often persist parent product_id (`p_…`) while
+ * availabilities and change sessions use option ids (`po_…`). Match backend semantics:
+ * never use a parent id where an option id is required (e.g. change-booking preselection).
+ */
+
+export function isParentProductId(id: string | null | undefined): boolean {
+  const t = id?.trim();
+  if (!t) return false;
+  return t.startsWith('p_') && !t.startsWith('po_');
+}
+
+/** Returns the id if it is usable as a product option id for matching availabilities; otherwise null. */
+export function normalizeProductOptionIdForChangeFlow(
+  id: string | null | undefined
+): string | null {
+  const t = id?.trim() || null;
+  if (!t || isParentProductId(t)) return null;
+  return t;
+}
+
+/**
+ * Option id to seed change-booking UI: prefer explicit productOptionId, else productId when it is
+ * already an option id (e.g. some payloads).
+ */
+export function effectiveProductOptionIdForChangeFlow(booking: {
+  productId?: string | null;
+  productOptionId?: string | null;
+}): string | null {
+  const fromOption = normalizeProductOptionIdForChangeFlow(booking.productOptionId);
+  if (fromOption) return fromOption;
+  const pid = booking.productId?.trim() || null;
+  if (pid?.startsWith('po_')) return pid;
+  return null;
+}

package/src/lib/booking/source-metadata.ts

@@ -4,9 +4,9 @@ export {
   PARTNER_PORTAL_BOOKING_SOURCE,
   inferClientBookingSourceFromProductIds,
   mergedMetadataImpliesPartnerPortal,
-} from './booking-source';
+} from '@/lib/booking/booking-source';
 
-import { KnownBookingSource, mergedMetadataImpliesPartnerPortal } from './booking-source';
+import { KnownBookingSource, mergedMetadataImpliesPartnerPortal } from '@/lib/booking/booking-source';
 
 export interface BookingSourceMetadata {
   pageUrl?: string;
@@ -33,17 +33,37 @@ function withDefinedValues<T extends object>(obj: T): Partial<T> {
   ) as Partial<T>;
 }
 
+/**
+ * Public marketing embed routes on the main site (`/partner/{slug}`). Used to decide when
+ * `partnerId` in the query string is intentional vs noisy on generic tour/product URLs.
+ */
 export function isPublicPartnerMarketingPath(pathname: string): boolean {
   return /^\/partner\/[^/]+/i.test(pathname.trim());
 }
 
+/** Partner booking SPA (`booking.*` prod/staging) — `?partnerId=` is intentional on `/` or any path. */
 export function isDedicatedPartnerBookingPortalHost(hostname: string): boolean {
   const h = hostname.trim().toLowerCase();
   return h === 'booking.viaviamorainelake.com' || h === 'staging.booking.viaviamorainelake.com';
 }
 
+/**
+ * Reads the **current browser URL** (and referrer) into attribution fields. Supplements
+ * `mergeBookingSourceMetadata` with `canonicalAttribution` from the route so identity does
+ * not depend on the visible URL alone.
+ *
+ * **`partnerId` from `?partnerId=`** is included when:
+ * - the path is **`/partner/:slug`** on the **main marketing site**, or
+ * - the host is the **dedicated partner booking app** (`booking.*` prod/staging).
+ *
+ * On other generic marketing pages we still capture UTMs and full `pageUrl`, but omit loose
+ * `partnerId` query params so promo + backend rules aren’t overshadowed by “explicit” metadata.
+ */
 export function buildBookingSourceMetadataFromLocation(): Partial<BookingSourceMetadata> {
-  if (typeof window === 'undefined') return {};
+  if (typeof window === 'undefined') {
+    return {};
+  }
+
   const currentUrl = new URL(window.location.href);
   const params = currentUrl.searchParams;
   const partnerMatch = currentUrl.pathname.match(/^\/partner\/([^/]+)/i);
@@ -75,6 +95,7 @@ export function buildBookingSourceMetadataFromLocation(): Partial<BookingSourceM
   });
 }
 
+/** Later layers override earlier ones (undefined / null / empty string in a layer are omitted). */
 export function mergeBookingSourceMetadata(
   ...layers: Array<Partial<BookingSourceMetadata> | null | undefined>
 ): Partial<BookingSourceMetadata> {
@@ -104,11 +125,22 @@ function hostnameForSourceDecision(merged: Partial<BookingSourceMetadata>): stri
 }
 
 export type BuildBookingSourceContextOptions = {
+  /**
+   * When metadata does not imply partner portal, use this channel (GYG/VIATOR/WEBSITE from product ids).
+   * AFFILIATE/DASHBOARD are normally set server-side from request headers.
+   */
   clientChannelSource?: KnownBookingSource;
+  /** Dedicated partner booking app (`booking.*`): persist `source` as PARTNER_PORTAL (not PUBLIC_PARTNER_WEBSITE). */
   forcePartnerPortalChannel?: boolean;
+  /** TicketBooth provider dashboard embed (`BookingAppProvider` mode `provider-dashboard`): persist `source` as DASHBOARD. */
   forceDashboardSource?: boolean;
 };
 
+/**
+ * Builds reserve/checkout `source` + `sourceMetadata` from composed metadata. Partner portal is
+ * inferred from `par_` org id or a valid marketing `partnerSlug` (including route-level canonical),
+ * not from hostname alone. Optional `clientChannelSource` supplies GYG/VIATOR/WEBSITE otherwise.
+ */
 export function buildBookingSourceContext(
   mergedMetadata: Partial<BookingSourceMetadata>,
   options?: BuildBookingSourceContextOptions,
@@ -122,7 +154,11 @@ export function buildBookingSourceContext(
 
   if (options?.forceDashboardSource === true) {
     const hasMeta = Object.keys(merged).length > 0;
-    return {
+    const context: {
+      source: KnownBookingSource;
+      sourceMetadata?: BookingSourceMetadata;
+      source_metadata?: BookingSourceMetadata;
+    } = {
       source: KnownBookingSource.DASHBOARD,
       ...(hasMeta
         ? {
@@ -131,13 +167,26 @@ export function buildBookingSourceContext(
           }
         : {}),
     };
+    try {
+      const md = context.sourceMetadata ?? context.source_metadata;
+      console.info(
+        `[booking-source-debug] built-context summary source=${context.source} path=${md?.pagePath ?? 'n/a'} partner=${md?.partnerId ?? 'n/a'} partner_slug=${md?.partnerSlug ?? 'n/a'} utm_source=${md?.utmSource ?? 'n/a'} utm_medium=${md?.utmMedium ?? 'n/a'} utm_campaign=${md?.utmCampaign ?? 'n/a'}`,
+      );
+      console.info(`[booking-source-debug] built-context payload\n${JSON.stringify(context, null, 2)}`);
+    } catch {
+      console.info('[booking-source-debug] built-context', context);
+    }
+    return context;
   }
 
-  if (Object.keys(merged).length === 0) return { source: channel };
+  if (Object.keys(merged).length === 0) {
+    return { source: channel };
+  }
 
   const host = hostnameForSourceDecision(merged);
   const dedicatedPartnerBookingHost =
-    host === 'booking.viaviamorainelake.com' || host === 'staging.booking.viaviamorainelake.com';
+    host === 'booking.viaviamorainelake.com' ||
+    host === 'staging.booking.viaviamorainelake.com';
   const pid = typeof merged.partnerId === 'string' ? merged.partnerId.trim() : '';
   const pslug = typeof merged.partnerSlug === 'string' ? merged.partnerSlug.trim() : '';
 
@@ -153,9 +202,25 @@ export function buildBookingSourceContext(
       ? KnownBookingSource.PUBLIC_PARTNER_WEBSITE
       : channel;
 
-  return {
+  const context: {
+    source: KnownBookingSource;
+    sourceMetadata?: BookingSourceMetadata;
+    source_metadata?: BookingSourceMetadata;
+  } = {
     source,
     sourceMetadata: merged as BookingSourceMetadata,
     source_metadata: merged as BookingSourceMetadata,
   };
+
+  try {
+    const md = context.sourceMetadata ?? context.source_metadata;
+    console.info(
+      `[booking-source-debug] built-context summary source=${context.source} path=${md?.pagePath ?? 'n/a'} partner=${md?.partnerId ?? 'n/a'} partner_slug=${md?.partnerSlug ?? 'n/a'} utm_source=${md?.utmSource ?? 'n/a'} utm_medium=${md?.utmMedium ?? 'n/a'} utm_campaign=${md?.utmCampaign ?? 'n/a'}`,
+    );
+    console.info(`[booking-source-debug] built-context payload\n${JSON.stringify(context, null, 2)}`);
+  } catch {
+    console.info('[booking-source-debug] built-context', context);
+  }
+
+  return context;
 }

package/src/lib/booking/sunday-week.ts

@@ -0,0 +1,14 @@
+import { addDays, parseISO } from 'date-fns';
+import { formatInTimeZone, fromZonedTime } from 'date-fns-tz';
+
+/**
+ * Sunday (week start) of the week containing `dateStr` (yyyy-MM-dd), in `timezone`.
+ * Matches the booking calendar grid so fetch windows align with the visible week.
+ */
+export function getSundayOfWeek(dateStr: string, timezone: string): string {
+  const noonInTz = fromZonedTime(parseISO(`${dateStr}T12:00:00`), timezone);
+  const isoDay = parseInt(formatInTimeZone(noonInTz, timezone, 'i'), 10); // 1=Mon, 7=Sun
+  const daysToSubtract = isoDay === 7 ? 0 : isoDay;
+  const sundayDate = addDays(noonInTz, -daysToSubtract);
+  return formatInTimeZone(sundayDate, timezone, 'yyyy-MM-dd');
+}