@nuitee/booking-widget 1.0.1 → 1.0.3

package/dist/core/booking-api.js

@@ -197,6 +197,7 @@ function deriveRatePolicyDetail(avRate) {
  * @param {string} [config.s3BaseUrl] - Base URL for room images (e.g. from VITE_AWS_S3_PATH).
  * @param {string|number} [config.propertyId] - Property ID (legacy). Prefer propertyKey for proxy endpoints.
  * @param {string} [config.propertyKey] - Property key for proxy endpoints (e.g. VITE_PROPERTY_KEY). Used in /proxy/availability and /proxy/ari-properties?key=.
+ * @param {string} [config.mode] - 'sandbox' to pass sandbox=true on all proxy/API calls; omit or 'live' to not pass it.
  * @param {string} [config.currency] - Currency code (e.g. 'MAD'). Default 'MAD'.
  * @param {Object} [config.headers] - Optional. Static headers for each request (e.g. { 'X-API-Key': '...' }).
  * @param {function(): Object} [config.getHeaders] - Optional. Return headers for each request (merged after headers). Use for dynamic headers.
@@ -215,6 +216,7 @@ function createBookingApi(config = {}) {
   if (rawKey && !propertyKey && typeof console !== 'undefined' && console.warn) {
     console.warn('[booking-api] Property key must start with "book_engine_". Ignoring invalid value. Set VITE_PROPERTY_KEY in your .env (see .env.example).');
   }
+  const sandbox = config.mode === 'sandbox';
   const currency = config.currency || 'MAD';
   const staticHeaders = config.headers || {};
   const getHeaders = config.getHeaders || (() => ({}));
@@ -279,8 +281,11 @@ function createBookingApi(config = {}) {
     // Fetch get_properties first to get currency_code (e.g. 'EUR') and room details
     let propertyRooms = {};
     let propertyCurrency = currency;
+    const propQuery = propertyKey
+      ? `key=${encodeURIComponent(propertyKey)}${sandbox ? '&sandbox=true' : ''}`
+      : '';
     const propFullUrl = propertyKey
-      ? `${availabilityBaseUrl}/proxy/ari-properties?key=${encodeURIComponent(propertyKey)}`
+      ? `${availabilityBaseUrl}/proxy/ari-properties?${propQuery}`
       : propertyBaseUrl
         ? `${propertyBaseUrl}/ari/get_properties?id=${encodeURIComponent(propertyId)}`
         : `/ari/get_properties?id=${encodeURIComponent(propertyId)}`;
@@ -307,7 +312,7 @@ function createBookingApi(config = {}) {
     };
 
     const availabilityPath = propertyKey
-      ? `/proxy/availability?key=${encodeURIComponent(propertyKey)}`
+      ? `/proxy/availability?key=${encodeURIComponent(propertyKey)}${sandbox ? '&sandbox=true' : ''}`
       : `/api/calendar/booking_engine/${propertyId}/availability`;
     const data = await request('POST', availabilityPath, body, availabilityBaseUrl);
     if (data && typeof data === 'object' && (data.error || data.message)) {
@@ -520,14 +525,15 @@ function computeCheckoutTotal(state, nights) {
  * Use this when integrating Stripe (amount/currency for Payment Intent) and your booking API (external_booking + internal_booking; add stripe_token after payment success).
  *
  * @param {Object} state - Widget state: checkIn, checkOut, rooms, occupancies, selectedRoom, selectedRate, guest
- * @param {Object} [options] - { propertyId: string|number, propertyKey: string, clientBookingReference?: string }
- * @returns {{ stripe: { amount: number, currency: string }, external_booking: Object, internal_booking: Object }}
+ * @param {Object} [options] - { propertyId: string|number, propertyKey: string, clientBookingReference?: string, sandbox?: boolean }
+ * @returns {{ stripe: { amount: number, currency: string }, external_booking: Object, internal_booking: Object, sandbox?: boolean }}
  */
 function buildCheckoutPayload(state, options = {}) {
   const propertyId = options.propertyId != null ? String(options.propertyId) : '';
   const rawKey = options.propertyKey != null && options.propertyKey !== '' ? String(options.propertyKey).trim() : '';
   const propertyKey = rawKey && rawKey.startsWith('book_engine_') ? rawKey : '';
   const clientBookingReference = options.clientBookingReference || 'nuitee-booking-widget';
+  const sandbox = options.sandbox === true;
 
   const checkIn = state.checkIn;
   const checkOut = state.checkOut;
@@ -591,7 +597,7 @@ function buildCheckoutPayload(state, options = {}) {
     room_id: state.selectedRoom?.id ?? '',
   };
 
-  return {
+  const out = {
     stripe: {
       amount: total,
       currency: currency.toLowerCase(),
@@ -599,6 +605,8 @@ function buildCheckoutPayload(state, options = {}) {
     external_booking,
     internal_booking,
   };
+  if (sandbox) out.sandbox = true;
+  return out;
 }
 
 /**
@@ -607,12 +615,23 @@ function buildCheckoutPayload(state, options = {}) {
  * Response: { clientSecret, confirmationToken }
  *
  * @param {Object} state - Widget state: checkIn, checkOut, rooms, occupancies, selectedRoom, selectedRate, guest
- * @param {Object} [options] - { propertyKey: string }
- * @returns {{ rate_identifier: string, key: string, metadata: Object }}
+ * @param {Object} [options] - { propertyKey: string, sandbox?: boolean }
+ * @returns {{ rate_identifier: string, key: string, metadata: Object, sandbox?: boolean }}
  */
+function generateUUID() {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+    return crypto.randomUUID();
+  }
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+    const r = Math.random() * 16 | 0;
+    return (c === 'x' ? r : (r & 0x3 | 0x8)).toString(16);
+  });
+}
+
 function buildPaymentIntentPayload(state, options = {}) {
   const rawKey = options.propertyKey != null && options.propertyKey !== '' ? String(options.propertyKey).trim() : '';
   const propertyKey = rawKey && rawKey.startsWith('book_engine_') ? rawKey : '';
+  const sandbox = options.sandbox === true;
   const checkIn = state.checkIn;
   const checkOut = state.checkOut;
   const nights = checkIn && checkOut
@@ -632,7 +651,7 @@ function buildPaymentIntentPayload(state, options = {}) {
     ...(Array.isArray(o.childrenAges) && o.childrenAges.length ? { child_ages: o.childrenAges } : {}),
   }));
 
-  return {
+  const out = {
     rate_identifier: rateIdentifier,
     key: propertyKey,
     metadata: {
@@ -648,8 +667,11 @@ function buildPaymentIntentPayload(state, options = {}) {
       email: g.email ?? '',
       occupancies: occupanciesForPayload,
       source_transaction: 'booking engine',
+      booking_code: generateUUID(),
     },
   };
+  if (sandbox) out.sandbox = true;
+  return out;
 }
 
 /**

package/dist/core/color-utils.js

@@ -0,0 +1,103 @@
+/**
+ * Color utilities for widget theming. Installers pass 4 base colors (background, text, primary, primaryText);
+ * we derive --card, --secondary, --muted, --border, --input-bg for a coherent theme.
+ */
+
+function expandHex(hex) {
+  if (!hex || typeof hex !== 'string') return null;
+  const h = hex.replace(/^#/, '').trim();
+  if (h.length === 3) return '#' + h.split('').map((c) => c + c).join('');
+  return h.length === 6 ? '#' + h : null;
+}
+
+function hexToRgb(hex) {
+  const expanded = expandHex(hex);
+  if (!expanded) return null;
+  return [
+    parseInt(expanded.slice(1, 3), 16),
+    parseInt(expanded.slice(3, 5), 16),
+    parseInt(expanded.slice(5, 7), 16),
+  ];
+}
+
+function hexToHsl(hex) {
+  const expanded = expandHex(hex);
+  if (!expanded) return null;
+  let r = parseInt(expanded.slice(1, 3), 16) / 255;
+  let g = parseInt(expanded.slice(3, 5), 16) / 255;
+  let b = parseInt(expanded.slice(5, 7), 16) / 255;
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  let h, s;
+  const l = (max + min) / 2;
+  if (max === min) {
+    h = s = 0;
+  } else {
+    const d = max - min;
+    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    switch (max) {
+      case r: h = ((g - b) / d + (g < b ? 6 : 0)) / 6; break;
+      case g: h = ((b - r) / d + 2) / 6; break;
+      case b: h = ((r - g) / d + 4) / 6; break;
+      default: h = 0;
+    }
+  }
+  return [Math.round(h * 360), Math.round(s * 100), Math.round(l * 100)];
+}
+
+/**
+ * Derive full widget CSS variables from 4 base colors.
+ * @param {Object} c - { background, text, primary, primaryText, card? }
+ * @returns {Object} CSS variable names to values, e.g. { '--bg': '#1a1a1a', ... }
+ */
+export function deriveWidgetStyles(c) {
+  if (!c || (!c.background && !c.text && !c.primary && !c.primaryText)) return {};
+  const bg = c.background || '#1a1a1a';
+  const fg = c.text || '#e0e0e0';
+  const primary = c.primary || '#3b82f6';
+  const primaryFg = c.primaryText || '#ffffff';
+  const cardExplicit = c.card;
+
+  const primaryRgb = hexToRgb(primary);
+  const bgHsl = hexToHsl(bg);
+  const fgHsl = hexToHsl(fg);
+
+  const styles = {
+    '--primary': primary,
+    '--primary-fg': primaryFg,
+    '--bg': bg,
+    '--fg': fg,
+    '--card-fg': fg,
+  };
+
+  if (primaryRgb) styles['--primary-rgb'] = `${primaryRgb[0]}, ${primaryRgb[1]}, ${primaryRgb[2]}`;
+
+  if (cardExplicit) {
+    styles['--card'] = cardExplicit + "40";
+    styles['--card-solid'] = cardExplicit;
+  } else if (bgHsl) {
+    const cardVal = `hsl(${bgHsl[0]}, ${bgHsl[1]}%, ${Math.min(95, bgHsl[2] + 2)}%)`;
+    styles['--card'] = cardVal;
+    styles['--card-solid'] = cardVal;
+  } else {
+    styles['--card'] = bg;
+    styles['--card-solid'] = bg;
+  }
+
+  if (bgHsl) {
+    styles['--secondary'] = `hsl(${bgHsl[0]}, ${bgHsl[1]}%, ${Math.min(95, bgHsl[2] + 10)}%)`;
+    styles['--border'] = `hsl(${bgHsl[0]}, ${bgHsl[1]}%, ${Math.min(95, bgHsl[2] + 14)}%)`;
+    styles['--input-bg'] = `hsl(${bgHsl[0]}, ${bgHsl[1]}%, ${Math.min(95, bgHsl[2] + 6)}%)`;
+  }
+
+  if (fgHsl) {
+    styles['--secondary-fg'] = `hsl(${fgHsl[0]}, ${fgHsl[1]}%, ${Math.max(20, fgHsl[2] - 10)}%)`;
+    styles['--muted'] = `hsl(${fgHsl[0]}, ${fgHsl[1]}%, ${Math.max(30, fgHsl[2] - 25)}%)`;
+  }
+
+  styles['--font-serif'] = "'Playfair Display', Georgia, serif";
+  styles['--font-sans'] = "'Inter', system-ui, sans-serif";
+  styles['--radius'] = '0.75rem';
+
+  return styles;
+}

package/dist/core/stripe-config.js

@@ -1,8 +1,10 @@
 /**
  * Config from CONFIG_URL (default https://ai.thehotelplanet.com/load-config). No .env used.
  * Property key is NOT from load-config; installers must set it (VITE_PROPERTY_KEY in app .env or propertyKey option).
+ * DEFAULT_COLORS from load-config CONFIG; installers can override via colors prop.
  */
 export const STRIPE_PUBLISHABLE_KEY = 'pk_test_51T0Se5EvQaQIixshRA8gbsI40NubMGwHlSWZmQM2LAx3jpVO0ThzVifqdTiMeGOyBfLNe8V9G8POGu8SjkvWOStM00H0i1U3uz';
 export const API_BASE_URL = 'https://ai.thehotelplanet.com';
 export const VITE_CONFIG_BASE_URL = 'https://ai.thehotelplanet.com/api';
 export const VITE_AWS_S3_PATH = 'https://nuitee-s3-temp.s3.us-west-1.amazonaws.com';
+export const DEFAULT_COLORS = {"background":"#022c32","text":"#ffffff","primary":"#f59e0b","primaryText":"#ffffff","card":"#395b60"};

package/dist/core/styles.css

@@ -106,6 +106,145 @@
   font-weight: 500;
 }
 
+/* ===== Config Error State ===== */
+.booking-widget-config-error {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 1.1em;
+  padding: 4em 2em;
+  text-align: center;
+  min-height: 300px;
+}
+
+.booking-widget-config-error__icon-wrap {
+  width: 5em;
+  height: 5em;
+  border-radius: 50%;
+  background: radial-gradient(circle, rgba(239,68,68,0.12) 0%, rgba(239,68,68,0.04) 100%);
+  border: 1.5px solid rgba(239, 68, 68, 0.22);
+  box-shadow: 0 0 0 6px rgba(239, 68, 68, 0.06);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: #f87171;
+  flex-shrink: 0;
+  margin-bottom: 0.25em;
+}
+
+.booking-widget-config-error__badge {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.4em;
+  font-size: 0.7em;
+  font-weight: 600;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+  color: #f87171;
+  background: rgba(239, 68, 68, 0.1);
+  border: 1px solid rgba(239, 68, 68, 0.18);
+  border-radius: 99em;
+  padding: 0.3em 0.85em;
+}
+
+.booking-widget-config-error__title {
+  font-family: var(--font-serif, 'Playfair Display', Georgia, serif);
+  font-size: 1.35em;
+  font-weight: 600;
+  color: var(--fg, #e8e0d5);
+  margin: 0;
+  letter-spacing: -0.01em;
+}
+
+.booking-widget-config-error__desc {
+  font-size: 0.875em;
+  color: var(--secondary-fg, #a09080);
+  max-width: 25em;
+  line-height: 1.7;
+  margin: 0;
+}
+
+.booking-widget-config-error__desc code {
+  font-family: 'SFMono-Regular', 'Consolas', 'Liberation Mono', Menlo, monospace;
+  font-size: 0.88em;
+  background: rgba(255, 255, 255, 0.06);
+  color: var(--primary, #f59e0b);
+  padding: 0.12em 0.45em;
+  border-radius: 0.3em;
+  border: 1px solid rgba(255, 255, 255, 0.09);
+}
+
+.booking-widget-config-error__divider {
+  width: 2.5em;
+  height: 1.5px;
+  background: var(--border, rgba(255,255,255,0.1));
+  border-radius: 1px;
+}
+
+.booking-widget-config-error__hint {
+  font-size: 0.78em;
+  color: var(--muted, #6b5f50);
+  max-width: 21em;
+  line-height: 1.6;
+  margin: 0;
+}
+
+.booking-widget-config-error__retry {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.45em;
+  padding: 0.55em 1.4em;
+  background: transparent;
+  color: var(--secondary-fg, #a09080);
+  border: 1.5px solid var(--border, rgba(255,255,255,0.13));
+  border-radius: 99em;
+  font-size: 0.8em;
+  font-family: var(--font-sans, system-ui, sans-serif);
+  font-weight: 500;
+  cursor: pointer;
+  letter-spacing: 0.02em;
+  transition: border-color 0.2s, color 0.2s, background 0.2s;
+  margin-top: 0.25em;
+}
+
+.booking-widget-config-error__retry:hover {
+  border-color: var(--primary, #f59e0b);
+  color: var(--primary, #f59e0b);
+  background: rgba(245, 158, 11, 0.06);
+}
+
+/* ===== Config Loading State ===== */
+.booking-widget-config-loading {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 1.25em;
+  padding: 4em 2em;
+  text-align: center;
+  min-height: 300px;
+}
+
+.booking-widget-config-loading__spinner {
+  width: 2.75em;
+  height: 2.75em;
+  border: 2px solid var(--border, rgba(255,255,255,0.1));
+  border-top-color: var(--primary, hsl(38,60%,55%));
+  border-radius: 50%;
+  animation: bw-spin 0.75s linear infinite;
+}
+
+@keyframes bw-spin {
+  to { transform: rotate(360deg); }
+}
+
+.booking-widget-config-loading__text {
+  font-size: 0.875em;
+  color: var(--muted, #888);
+  letter-spacing: 0.01em;
+}
+
 /* ===== Step Indicator ===== */
 .booking-widget-step-indicator {
   display: flex;
@@ -448,7 +587,7 @@
 }
 
 .booking-widget-modal .date-trigger:hover {
-  border-color: hsl(38, 60%, 55%, 0.5);
+  border-color: var(--primary);
 }
 
 .booking-widget-modal .date-trigger .placeholder {
@@ -472,7 +611,7 @@
   max-width: calc(100vw - 2em);
   box-sizing: border-box;
   z-index: 10;
-  background: var(--card);
+  background: var(--card-solid, var(--card));
   border: 1px solid var(--border);
   border-radius: var(--radius);
   padding: 1em;

package/dist/react/BookingWidget.jsx

@@ -4,6 +4,7 @@ import { Calendar, Users, User, Check, MapPin, Phone, Square, CreditCard, Lock,
 import '../core/styles.css';
 import { createBookingApi, formatPrice, buildCheckoutPayload, buildPaymentIntentPayload } from '../core/booking-api.js';
 import { STRIPE_PUBLISHABLE_KEY, API_BASE_URL } from '../core/stripe-config.js';
+import { fetchRuntimeConfig } from '../utils/config-service.js';
 
 const BASE_STEPS = [
   { key: 'dates', label: 'Dates & Guests', num: '01' },
@@ -31,6 +32,8 @@ const BookingWidget = ({
   apiSecret = '',
   propertyId = '',
   propertyKey = '',
+  /** 'sandbox' to pass sandbox=true on all proxy/API calls; omit or 'live' to not pass it. */
+  mode = '',
   availabilityBaseUrl = '',
   propertyBaseUrl = '',
   s3BaseUrl = '',
@@ -47,20 +50,23 @@ const BookingWidget = ({
   const env = typeof import.meta !== 'undefined' && import.meta.env ? import.meta.env : {};
   const apiBase = (env.VITE_API_BASE_URL || API_BASE_URL || '').replace(/\/$/, '');
   const effectivePaymentIntentUrl = (apiBase ? apiBase + '/proxy/create-payment-intent' : '').trim();
+  const isSandbox = mode === 'sandbox';
+  const hasPropertyKey = !!(propertyKey && String(propertyKey).trim());
   const createPaymentIntent = useMemo(() => {
     if (typeof createPaymentIntentProp === 'function') return createPaymentIntentProp;
     if (!effectivePaymentIntentUrl) return null;
     return async (payload) => {
+      const url = effectivePaymentIntentUrl + (isSandbox ? '?sandbox=true' : '');
       const headers = { 'Content-Type': 'application/json' };
-      if (effectivePaymentIntentUrl.includes('ngrok')) headers['ngrok-skip-browser-warning'] = 'true';
-      const res = await fetch(effectivePaymentIntentUrl, { method: 'POST', headers, body: JSON.stringify(payload) });
+      if (url.includes('ngrok')) headers['ngrok-skip-browser-warning'] = 'true';
+      const res = await fetch(url, { method: 'POST', headers, body: JSON.stringify(payload) });
       if (!res.ok) throw new Error(await res.text());
       const data = await res.json();
       const clientSecret = data.clientSecret ?? data.client_secret ?? data.data?.clientSecret ?? data.data?.client_secret ?? data.paymentIntent?.client_secret;
       const confirmationToken = data.confirmationToken ?? data.confirmation_token ?? data.data?.confirmationToken ?? data.data?.confirmation_token;
       return { clientSecret, confirmationToken };
     };
-  }, [createPaymentIntentProp, effectivePaymentIntentUrl]);
+  }, [createPaymentIntentProp, effectivePaymentIntentUrl, isSandbox]);
   const onBookingComplete = useMemo(() => onBookingCompleteProp ?? null, [onBookingCompleteProp]);
   const hasStripe = Boolean(stripePublishableKey && typeof createPaymentIntent === 'function');
   const STEPS = useMemo(() => buildSteps(hasStripe), [hasStripe]);
@@ -93,6 +99,11 @@ const BookingWidget = ({
   const [checkoutShowPaymentForm, setCheckoutShowPaymentForm] = useState(false);
   const [isClosing, setIsClosing] = useState(false);
   const [isReadyForOpen, setIsReadyForOpen] = useState(false);
+  const [configLoading, setConfigLoading] = useState(false);
+  const [configLoaded, setConfigLoaded] = useState(false);
+  const [configError, setConfigError] = useState(null);
+  const [runtimeWidgetStyles, setRuntimeWidgetStyles] = useState({});
+  const [configRetryCount, setConfigRetryCount] = useState(0);
   const widgetRef = useRef(null);
   const stripeRef = useRef(null);
   const elementsRef = useRef(null);
@@ -116,11 +127,12 @@ const BookingWidget = ({
         s3BaseUrl: effectiveS3BaseUrl || undefined,
         propertyId: propertyId || undefined,
         propertyKey: propertyKey || undefined,
+        mode: mode === 'sandbox' ? 'sandbox' : undefined,
         headers: apiSecret ? { 'X-API-Key': apiSecret } : undefined,
       });
     }
     return null;
-  }, [bookingApiProp, effectiveApiBaseUrl, effectiveAvailabilityBaseUrl, effectivePropertyBaseUrl, effectiveS3BaseUrl, apiSecret, propertyId, propertyKey]);
+  }, [bookingApiProp, effectiveApiBaseUrl, effectiveAvailabilityBaseUrl, effectivePropertyBaseUrl, effectiveS3BaseUrl, apiSecret, propertyId, propertyKey, mode]);
 
   useEffect(() => {
     if (isOpen && onOpen) onOpen();
@@ -145,7 +157,7 @@ const BookingWidget = ({
       setPaymentElementReady(false);
       return;
     }
-    const paymentIntentPayload = buildPaymentIntentPayload(state, { propertyKey: propertyKey || undefined });
+    const paymentIntentPayload = buildPaymentIntentPayload(state, { propertyKey: propertyKey || undefined, sandbox: isSandbox });
     let mounted = true;
     setPaymentElementReady(false);
     setApiError(null);
@@ -182,7 +194,7 @@ const BookingWidget = ({
       }
       stripeRef.current = null;
     };
-  }, [state.step, checkoutShowPaymentForm, stripePublishableKey, createPaymentIntent, onBookingComplete, state.checkIn, state.checkOut, state.rooms, state.occupancies, state.selectedRoom?.id, state.selectedRate?.id, state.guest, propertyId, propertyKey]);
+  }, [state.step, checkoutShowPaymentForm, stripePublishableKey, createPaymentIntent, onBookingComplete, state.checkIn, state.checkOut, state.rooms, state.occupancies, state.selectedRoom?.id, state.selectedRate?.id, state.guest, propertyId, propertyKey, isSandbox]);
 
   // After Stripe confirms payment, poll confirmation endpoint every 2s until status === 'confirmed'
   useEffect(() => {
@@ -192,7 +204,7 @@ const BookingWidget = ({
     const pollOnce = async () => {
       if (cancelled) return;
       try {
-        const url = `${effectiveConfirmationBaseUrl}/proxy/confirmation/${encodeURIComponent(String(confirmationToken).trim())}`;
+        const url = `${effectiveConfirmationBaseUrl}/proxy/confirmation/${encodeURIComponent(String(confirmationToken).trim())}${isSandbox ? '?sandbox=true' : ''}`;
         const res = await fetch(url, { method: 'POST' });
         if (!res.ok) throw new Error(await res.text());
         const data = await res.json();
@@ -212,28 +224,45 @@ const BookingWidget = ({
       cancelled = true;
       if (timer) clearTimeout(timer);
     };
-  }, [state.step, confirmationToken, effectiveConfirmationBaseUrl]);
+  }, [state.step, confirmationToken, effectiveConfirmationBaseUrl, isSandbox]);
 
-  // Apply custom colors
+  // Fetch runtime config (colors) from /load-config on mount and when propertyKey/colors change.
+  // The config service caches API results so re-renders triggered by other prop changes are cheap.
   useEffect(() => {
-    if (widgetRef.current && colors) {
-      const style = widgetRef.current.style;
-      if (colors.background) {
-        style.setProperty('--bg', colors.background);
-        style.setProperty('--card', colors.background);
-      }
-      if (colors.text) {
-        style.setProperty('--fg', colors.text);
-        style.setProperty('--card-fg', colors.text);
-      }
-      if (colors.primary) {
-        style.setProperty('--primary', colors.primary);
-      }
-      if (colors.primaryText) {
-        style.setProperty('--primary-fg', colors.primaryText);
-      }
+    if (!propertyKey || !String(propertyKey).trim()) {
+      setConfigError('propertyKey is required to initialize the booking widget.');
+      setConfigLoading(false);
+      setConfigLoaded(false);
+      setRuntimeWidgetStyles({});
+      return;
     }
-  }, [colors, isOpen]);
+    let cancelled = false;
+    setConfigLoading(true);
+    setConfigError(null);
+    setConfigLoaded(false);
+    fetchRuntimeConfig(propertyKey, colors)
+      .then(({ widgetStyles }) => {
+        if (cancelled) return;
+        setRuntimeWidgetStyles(widgetStyles);
+        setConfigLoaded(true);
+        setConfigLoading(false);
+      })
+      .catch((err) => {
+        if (cancelled) return;
+        setConfigError(err?.message || 'Failed to load widget configuration.');
+        setConfigLoading(false);
+      });
+    return () => { cancelled = true; };
+  }, [propertyKey, colors, configRetryCount]);
+
+  // Apply resolved CSS custom properties to the widget element.
+  useEffect(() => {
+    if (!widgetRef.current) return;
+    const style = widgetRef.current.style;
+    Object.entries(runtimeWidgetStyles).forEach(([key, val]) => {
+      if (val != null && val !== '') style.setProperty(key, val);
+    });
+  }, [runtimeWidgetStyles, isOpen]);
 
   const getNights = () => {
     if (!state.checkIn || !state.checkOut) return 0;
@@ -272,6 +301,8 @@ const BookingWidget = ({
   const stepIndex = (key) => STEPS.findIndex(s => s.key === key);
 
   const goToStep = (step) => {
+    // Block room/rate navigation until runtime config (colors) has been loaded.
+    if ((step === 'rooms' || step === 'rates') && !configLoaded) return;
     setApiError(null);
     if (step !== 'summary' && step !== 'payment') setCheckoutShowPaymentForm(false);
     if (step === 'payment') setCheckoutShowPaymentForm(true);
@@ -431,7 +462,7 @@ const BookingWidget = ({
   const confirmReservation = () => {
     const canSubmit = state.guest.firstName && state.guest.lastName && state.guest.email;
     if (!canSubmit) return;
-    const payload = buildCheckoutPayload(state, { propertyId: propertyId || undefined, propertyKey: propertyKey || undefined });
+    const payload = buildCheckoutPayload(state, { propertyId: propertyId || undefined, propertyKey: propertyKey || undefined, sandbox: isSandbox });
     // Summary step with Stripe: go to payment step (payment form loads there)
     if (state.step === 'summary' && stripePublishableKey && typeof createPaymentIntent === 'function') {
       setApiError(null);
@@ -1175,15 +1206,59 @@ const BookingWidget = ({
         onTransitionEnd={handleTransitionEnd}
       >
         <button className="booking-widget-close" onClick={requestClose}><X size={24} /></button>
-        {renderStepIndicator()}
-        <div className="booking-widget-step-content">
-          {state.step === 'dates' && renderDatesStep()}
-          {state.step === 'rooms' && renderRoomsStep()}
-          {state.step === 'rates' && renderRatesStep()}
-          {state.step === 'summary' && renderSummaryStep()}
-          {state.step === 'payment' && renderPaymentStep()}
-          {state.step === 'confirmation' && renderConfirmationStep()}
-        </div>
+        {configLoaded && hasPropertyKey && renderStepIndicator()}
+        {(!propertyKey || (typeof propertyKey === 'string' && !propertyKey.trim())) ? (
+          <div className="booking-widget-config-error" role="alert">
+            <div className="booking-widget-config-error__icon-wrap">
+              <Lock size={22} strokeWidth={1.5} />
+            </div>
+            <span className="booking-widget-config-error__badge">
+              <Lock size={10} strokeWidth={2} /> Missing Configuration
+            </span>
+            <h3 className="booking-widget-config-error__title">Widget Not Configured</h3>
+            <p className="booking-widget-config-error__desc">
+              A <code>propertyKey</code> prop is required to initialize this booking widget. Please provide it to load rooms and availability.
+            </p>
+            <div className="booking-widget-config-error__divider" />
+            <p className="booking-widget-config-error__hint">
+              Contact the site administrator to configure this widget.
+            </p>
+          </div>
+        ) : configError ? (
+          <div className="booking-widget-config-error" role="alert">
+            <div className="booking-widget-config-error__icon-wrap">
+              <svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round"><path d="M10.29 3.86L1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0z"/><line x1="12" y1="9" x2="12" y2="13"/><line x1="12" y1="17" x2="12.01" y2="17"/></svg>
+            </div>
+            <span className="booking-widget-config-error__badge">Configuration Error</span>
+            <h3 className="booking-widget-config-error__title">Could Not Load Config</h3>
+            <p className="booking-widget-config-error__desc">{configError}</p>
+            <div className="booking-widget-config-error__divider" />
+            <p className="booking-widget-config-error__hint">
+              Please try again or contact support.
+            </p>
+            <button
+              className="booking-widget-config-error__retry"
+              onClick={() => setConfigRetryCount(c => c + 1)}
+            >
+              <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M23 4v6h-6"/><path d="M1 20v-6h6"/><path d="M3.51 9a9 9 0 0 1 14.85-3.36L23 10M1 14l4.64 4.36A9 9 0 0 0 20.49 15"/></svg>
+              Try Again
+            </button>
+          </div>
+        ) : configLoading ? (
+          <div className="booking-widget-config-loading">
+            <div className="booking-widget-config-loading__spinner" />
+            <span className="booking-widget-config-loading__text">Loading configuration…</span>
+          </div>
+        ) : (
+          <div className="booking-widget-step-content">
+            {state.step === 'dates' && renderDatesStep()}
+            {state.step === 'rooms' && renderRoomsStep()}
+            {state.step === 'rates' && renderRatesStep()}
+            {state.step === 'summary' && renderSummaryStep()}
+            {state.step === 'payment' && renderPaymentStep()}
+            {state.step === 'confirmation' && renderConfirmationStep()}
+          </div>
+        )}
       </div>
     </>
   );