@ticketboothapp/booking 1.2.24 → 1.2.25-rc.0

package/src/lib/analytics.ts

@@ -0,0 +1,197 @@
+/**
+ * Frontend analytics for GA4 and Meta Pixel.
+ * Events deduplicate with backend using transaction_id / eventID = Stripe paymentIntent.id.
+ * - development/staging: log to console only (no GA4/Meta)
+ * - production: send to GA4/Meta when consent is granted
+ */
+import { ENV, isLocalhost, isProduction, shouldLogPurchaseToConsole } from '@/lib/env';
+
+const CONSENT_KEY = 'cookie-consent';
+const PENDING_PURCHASE_KEY = 'pending_purchase';
+
+declare global {
+  interface Window {
+    dataLayer?: unknown[];
+    gtag?: (...args: unknown[]) => void;
+    fbq?: (...args: unknown[]) => void;
+  }
+}
+
+/** Check if user has granted cookie consent. */
+export function hasAnalyticsConsent(): boolean {
+  if (typeof window === 'undefined') return false;
+  try {
+    return localStorage.getItem(CONSENT_KEY) === 'granted';
+  } catch {
+    return false;
+  }
+}
+
+/** Mark consent as granted (call from cookie banner on Accept). */
+export function setAnalyticsConsentGranted(): void {
+  if (typeof window === 'undefined') return;
+  try {
+    localStorage.setItem(CONSENT_KEY, 'granted');
+  } catch {
+    /* ignore */
+  }
+}
+
+/**
+ * Store purchase data before Stripe redirect.
+ * Success page reads payment_intent from URL and fires purchase with transaction_id = payment_intent.
+ */
+export function storePendingPurchase(value: number, currency: string): void {
+  if (typeof window === 'undefined') return;
+  try {
+    sessionStorage.setItem(
+      PENDING_PURCHASE_KEY,
+      JSON.stringify({ value, currency })
+    );
+  } catch {
+    /* ignore */
+  }
+}
+
+/** Read and clear pending purchase from sessionStorage. */
+export function consumePendingPurchase(): { value: number; currency: string } | null {
+  if (typeof window === 'undefined') return null;
+  try {
+    const raw = sessionStorage.getItem(PENDING_PURCHASE_KEY);
+    sessionStorage.removeItem(PENDING_PURCHASE_KEY);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as { value?: number; currency?: string };
+    if (typeof parsed?.value === 'number' && typeof parsed?.currency === 'string') {
+      return { value: parsed.value, currency: parsed.currency };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function safeGtag(...args: unknown[]): void {
+  if (typeof window !== 'undefined' && window.gtag) {
+    window.gtag(...args);
+  }
+}
+
+function safeFbq(...args: unknown[]): void {
+  if (typeof window !== 'undefined' && window.fbq) {
+    window.fbq(...args);
+  }
+}
+
+/** Fire view_item when user selects or views a product. */
+export function trackViewItem(
+  productId: string,
+  productName: string,
+  price: number,
+  currency: string
+): void {
+  const data = { productId, productName, price, currency };
+
+  if (isLocalhost() || shouldLogPurchaseToConsole()) {
+    console.log('analytics view_item', data);
+    return;
+  }
+
+  if (!hasAnalyticsConsent()) return;
+
+  if (ENV.GA4_MEASUREMENT_ID) {
+      safeGtag('event', 'view_item', {
+      items: [{ item_id: productId, item_name: productName, price, currency }],
+    });
+  }
+  if (ENV.META_PIXEL_ID) {
+    safeFbq('track', 'ViewContent', {
+    content_ids: [productId],
+    content_name: productName,
+    content_type: 'product',
+    value: price,
+    currency,
+  });
+  }
+}
+
+export interface BeginCheckoutItem {
+  id: string;
+  name: string;
+  qty: number;
+  price: number;
+}
+
+/** Fire begin_checkout when checkout modal opens. */
+export function trackBeginCheckout(
+  value: number,
+  currency: string,
+  items: BeginCheckoutItem[]
+): void {
+  const data = { value, currency, items };
+
+  if (isLocalhost() || shouldLogPurchaseToConsole()) {
+    console.log('analytics begin_checkout', data);
+    return;
+  }
+
+  if (!hasAnalyticsConsent()) return;
+
+  if (ENV.GA4_MEASUREMENT_ID) {
+    safeGtag('event', 'begin_checkout', {
+    value,
+    currency,
+    items: items.map((i) => ({
+      item_id: i.id,
+      item_name: i.name,
+      quantity: i.qty,
+      price: i.price,
+    })),
+  });
+  }
+  if (ENV.META_PIXEL_ID) {
+    safeFbq('track', 'InitiateCheckout', {
+    value,
+    currency,
+    content_ids: items.map((i) => i.id),
+    content_type: 'product',
+    num_items: items.reduce((s, i) => s + i.qty, 0),
+  });
+  }
+}
+
+/**
+ * Fire purchase on success page.
+ * transactionId MUST be Stripe paymentIntent.id (from URL param payment_intent) for dedup with backend.
+ */
+export function trackPurchase(
+  transactionId: string,
+  value: number,
+  currency: string,
+  items: Array<{ item_id: string; item_name: string; quantity: number; price: number }> = []
+): void {
+  const data = { transaction_id: transactionId, value, currency, items };
+
+  if (isLocalhost() || shouldLogPurchaseToConsole()) {
+    console.log('analytics purchase', data);
+    return;
+  }
+
+  if (!hasAnalyticsConsent()) return;
+
+  if (ENV.GA4_MEASUREMENT_ID) {
+    safeGtag('event', 'purchase', {
+    transaction_id: transactionId,
+    value,
+    currency,
+    items,
+  });
+  }
+  if (ENV.META_PIXEL_ID) {
+    safeFbq('track', 'Purchase', {
+    value,
+    currency,
+    order_id: transactionId,
+    eventID: transactionId,
+  });
+  }
+}

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

@@ -0,0 +1,51 @@
+/**
+ * Channel values the API persists on reservations/bookings (aligned with ticketbooth-be
+ * `BookingMarketingSource` + `SourceTrackingService` auto-detect: WEBSITE, AFFILIATE, DASHBOARD,
+ * GYG, VIATOR, plus dynamic uppercase `utm_source` strings when no fixed bucket applies).
+ */
+export enum KnownBookingSource {
+  WEBSITE = 'WEBSITE',
+  /** Main-site partner embed (e.g. `/partner/{slug}`); not the dedicated `booking.*` portal app. */
+  PUBLIC_PARTNER_WEBSITE = 'PUBLIC_PARTNER_WEBSITE',
+  PARTNER_PORTAL = 'PARTNER_PORTAL',
+  AFFILIATE = 'AFFILIATE',
+  DASHBOARD = 'DASHBOARD',
+  GYG = 'GYG',
+  VIATOR = 'VIATOR',
+}
+
+/** Default reserve/checkout `source` when the client does not send a more specific channel. */
+export const DEFAULT_BOOKING_SOURCE = KnownBookingSource.WEBSITE;
+
+/** Client `source` when booking through the signed-in partner org / marketing partner flows. */
+export const PARTNER_PORTAL_BOOKING_SOURCE = KnownBookingSource.PARTNER_PORTAL;
+
+const PUBLIC_BOOKING_SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/**
+ * True when metadata carries a partner org id or a normalized public marketing slug (same shape
+ * as backend `publicBookingSlug`), independent of hostname or URL path — use with route-level
+ * `canonicalAttribution.partnerSlug` so localhost and stripped URLs still attribute.
+ */
+export function mergedMetadataImpliesPartnerPortal(
+  merged: Partial<{ partnerId?: string; partnerSlug?: string }>,
+): boolean {
+  const pid = typeof merged.partnerId === 'string' ? merged.partnerId.trim() : '';
+  if (pid.startsWith('par_')) return true;
+  const slug = typeof merged.partnerSlug === 'string' ? merged.partnerSlug.trim().toLowerCase() : '';
+  return slug.length > 0 && PUBLIC_BOOKING_SLUG_RE.test(slug);
+}
+
+/**
+ * Fixed client channel from product / option identifiers (GYG / Viator embeds). Everything else
+ * is treated as main-site {@link KnownBookingSource.WEBSITE}; AFFILIATE/DASHBOARD are set server-side.
+ */
+export function inferClientBookingSourceFromProductIds(
+  productId: string,
+  productOptionId?: string | null,
+): KnownBookingSource {
+  const haystack = `${productId} ${productOptionId ?? ''}`.toLowerCase();
+  if (haystack.includes('gyg_')) return KnownBookingSource.GYG;
+  if (haystack.includes('viator_')) return KnownBookingSource.VIATOR;
+  return KnownBookingSource.WEBSITE;
+}

package/src/lib/booking/checkout-breakdown.ts

@@ -0,0 +1,69 @@
+import type { CheckoutBreakdown, CheckoutReceiptLine } from '@/lib/booking-api';
+
+/**
+ * Round to 2 decimal places. Used so breakdown amounts and totals are stable
+ * and pass backend validation (sum of line items ≈ totalAmount within 0.02).
+ */
+export function round2(n: number): number {
+  return Math.round(n * 100) / 100;
+}
+
+export interface CheckoutLineInput {
+  label: string;
+  amount: number;
+  type: string;
+  quantity?: number;
+}
+
+/** Line types for checkout breakdown. ADDITIONAL_HOURS reserved for future private shuttle extra hours. */
+export const CheckoutLineType = {
+  TICKET: 'TICKET',
+  DEPOSIT: 'DEPOSIT',
+  FEE: 'FEE',
+  RETURN_OPTION: 'return',
+  CANCELLATION_UPGRADE: 'cancellation',
+  TAX: 'TAX',
+  PROMO_CODE: 'PROMO_CODE',
+  ROUNDING: 'ROUNDING',
+  ADDITIONAL_HOURS: 'ADDITIONAL_HOURS', // Future: private shuttle extra hours line
+} as const;
+
+export interface BuildCheckoutBreakdownParams {
+  /** Line items in display order (tickets, return, cancellation, fees, tax, promo, etc.) */
+  lines: CheckoutLineInput[];
+  /** Total amount to charge (will be rounded to 2 decimals). */
+  totalAmount: number;
+  currency: string;
+  /** Label for rounding line when added (e.g. "Rounding"). */
+  roundingLabel: string;
+}
+
+/**
+ * Builds a CheckoutBreakdown from the given lines and total.
+ * Rounds each line amount to 2 decimals; if the sum differs from total by more than 0.02,
+ * adds a rounding line so the backend validator accepts it.
+ * Reused by BookingFlow and PrivateShuttleBookingFlow so Stripe and /manage match the UI.
+ */
+export function buildCheckoutBreakdown(params: BuildCheckoutBreakdownParams): CheckoutBreakdown {
+  const { lines, totalAmount, currency, roundingLabel } = params;
+  const totalRounded = round2(totalAmount);
+  const lineItems: CheckoutReceiptLine[] = lines.map((line) => ({
+    label: line.label,
+    amount: round2(line.amount),
+    type: line.type,
+    quantity: line.quantity,
+  }));
+  const sumLines = lineItems.reduce((s, l) => s + l.amount, 0);
+  if (Math.abs(sumLines - totalRounded) > 0.02) {
+    lineItems.push({
+      label: roundingLabel,
+      amount: round2(totalRounded - sumLines),
+      type: 'ROUNDING',
+    });
+  }
+  return {
+    lineItems,
+    totalAmount: totalRounded,
+    currency,
+  };
+}

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/booking/i18n/config.ts

@@ -0,0 +1,21 @@
+/**
+ * i18n Configuration
+ * 
+ * This file sets up the internationalization configuration.
+ * Currently supports English (en) as default, ready to add more languages.
+ */
+
+export const locales = ['en', 'fr'] as const;
+export type Locale = (typeof locales)[number];
+
+export const defaultLocale: Locale = 'en';
+
+// Language display names
+export const languageNames: Record<Locale, string> = {
+  en: 'English',
+  fr: 'Français',
+  // Add more languages here:
+  // es: 'Español',
+  // de: 'Deutsch',
+};
+

package/src/lib/booking/i18n/index.tsx

@@ -0,0 +1,144 @@
+'use client';
+
+/**
+ * i18n Utilities
+ * 
+ * Simple translation utilities for client components.
+ * For server components, use next-intl directly.
+ */
+
+import { useState, useEffect, createContext, useContext } from 'react';
+import type { ReactNode } from 'react';
+import messagesEn from './messages/en.json';
+import messagesFr from './messages/fr.json';
+import { defaultLocale, locales, type Locale } from './config';
+
+type Messages = typeof messagesEn;
+
+const messages: Record<Locale, Messages> = {
+  en: messagesEn,
+  fr: messagesFr,
+};
+
+// Context for locale
+const LocaleContext = createContext<{
+  locale: Locale;
+  setLocale: (locale: Locale) => void;
+}>({
+  locale: defaultLocale,
+  setLocale: () => {},
+});
+
+// Provider component
+export function LocaleProvider({ children }: { children: ReactNode }) {
+  // Always start with default locale to ensure server/client match
+  const [locale, setLocaleState] = useState<Locale>(defaultLocale);
+
+  // Load from localStorage after hydration to avoid SSR mismatch
+  useEffect(() => {
+    try {
+      const saved = localStorage.getItem('booking-locale') as Locale | null;
+      // Validate that saved locale is in our supported locales array
+      if (saved && locales.includes(saved)) {
+        setLocaleState(saved);
+      }
+    } catch (error) {
+      // localStorage might be disabled or throw errors
+      console.warn('Failed to read locale from localStorage:', error);
+    }
+  }, []);
+
+  const setLocale = (newLocale: Locale) => {
+    // Validate locale before setting
+    if (!locales.includes(newLocale)) {
+      console.warn(`Invalid locale: ${newLocale}. Falling back to ${defaultLocale}`);
+      setLocaleState(defaultLocale);
+      return;
+    }
+    
+    setLocaleState(newLocale);
+    if (typeof window !== 'undefined') {
+      try {
+        localStorage.setItem('booking-locale', newLocale);
+      } catch (error) {
+        // localStorage might be disabled or full
+        console.warn('Failed to save locale to localStorage:', error);
+      }
+    }
+  };
+
+  return (
+    <LocaleContext.Provider value={{ locale, setLocale }}>
+      {children}
+    </LocaleContext.Provider>
+  );
+}
+
+// Hook to use translations
+export function useTranslations() {
+  const { locale } = useContext(LocaleContext);
+  
+  // Ensure we have a valid locale, fallback to default if invalid
+  const validLocale = locales.includes(locale) ? locale : defaultLocale;
+  const currentMessages = messages[validLocale] || messages[defaultLocale];
+
+  const t = (key: string, params?: Record<string, string | number>): string => {
+    if (!key || typeof key !== 'string') {
+      console.warn('Invalid translation key:', key);
+      return String(key || '');
+    }
+
+    const keys = key.split('.');
+    let value: unknown = currentMessages;
+
+    for (const k of keys) {
+      if (value === null || value === undefined) {
+        break;
+      }
+      // Safe property access on unknown type
+      value = (value as Record<string, unknown>)[k];
+    }
+
+    if (value === undefined || value === null) {
+      // In development, show the key to help identify missing translations
+      if (process.env.NODE_ENV === 'development') {
+        console.warn(`Translation key not found: ${key} (locale: ${validLocale})`);
+      }
+      return key;
+    }
+
+    // Ensure value is a string
+    if (typeof value !== 'string') {
+      console.warn(`Translation value is not a string for key: ${key}`);
+      return key;
+    }
+
+    // Simple parameter replacement
+    if (params) {
+      return value.replace(/\{(\w+)\}/g, (match, paramKey) => {
+        const paramValue = params[paramKey];
+        return paramValue !== undefined && paramValue !== null 
+          ? String(paramValue) 
+          : match;
+      });
+    }
+
+    return value;
+  };
+
+  return { t };
+}
+
+// Hook to use locale switching
+export function useLocale() {
+  return useContext(LocaleContext);
+}
+
+// Type-safe translation key helper
+export type TranslationKey = 
+  | `common.${keyof Messages['common']}`
+  | `booking.${keyof Messages['booking']}`
+  | `pickup.${keyof Messages['pickup']}`
+  | `calendar.${keyof Messages['calendar']}`
+  | `products.${keyof Messages['products']}`;
+