@code-collective/booking-widget 1.0.9 → 1.0.12

package/src/lib/messages.ts

@@ -1,77 +1,157 @@
-// The widget's own components talk to each other over postMessage - a cart added in bw-configurator has to
-// reach the bar in bw-cart and the modal in bw-checkout, which are separate custom elements with no shared
-// Svelte tree. That makes every one of these messages same-window and same-origin, and the guards below exist
-// to keep it that way.
-
-/** Messages this widget sends itself. Anything else on the wire is not ours. */
-const WIDGET_MESSAGE_TYPES = new Set([
-  'cart:change',
-  'cart:updated',
-  // The cart the widget was holding onto is gone because its clock ran out - a strict subset of
-  // cart:updated's own cart:null case (see that message's own callers), fired alongside it so a host that
-  // wants to react to expiry specifically (analytics, a redirect, its own message) does not have to infer it
-  // from an absent cart, which cart:updated also carries for an ordinary manual clear.
-  'cart:expired',
-  'modal:open',
-  'modal:close',
-  'order:complete',
-  // A Peach checkout is open for the cart / has been abandoned so the cart is Open again. Posted by
-  // CheckoutModal for CartExpiryGuard, which keeps prompting but stops acting on the deadline itself while
-  // the server exempts the cart from expiry.
-  'payment:started',
-  'payment:ended',
-  // The cart's one clock ran out while a Peach checkout was open. Posted by CartExpiryGuard for
-  // CheckoutModal, which tears the attempt down (Peach's real status permitting) so the shopper sees the
-  // cart expire there too, rather than an ever-open card form for a cart that is already gone.
-  'payment:timed-out',
-]);
-
-/**
- * Sends a widget message.
- *
- * Targets this window's own origin rather than '*'. These payloads carry `cart`, and CheckoutCartDetailDto
- * includes `cartToken` - a bearer credential that authorises reading, modifying and paying for the cart. With
- * '*' that went to whatever origin happened to be framing the widget, which in the standalone iframe build is
- * not necessarily anyone we trust.
- */
-export function postMessage(data: Record<string, unknown>): void {
-  window.parent?.postMessage(JSON.stringify(data), window.location.origin);
-}
-
-/**
- * Subscribes to widget messages, ignoring anything that did not come from this widget.
- *
- * The elements mount directly into the merchant's own document (shadow: 'none'), so these listeners sit on
- * the top-level window of a third-party page. Without this check, any iframe already on that page - an ad, a
- * chat widget, a tag manager - could reach them with window.parent.postMessage and drive the widget: spoof
- * the total on the payment consent screen, fire a forged order confirmation into the merchant's analytics, or
- * close the modal mid-confirm on a card that has already been charged.
- *
- * Checking `source` is what does the real work: a message from another frame carries that frame's own window,
- * never ours, and it cannot be spoofed. The origin check is belt-and-braces for the same-window case.
- */
-export function onWidgetMessage(handler: (data: Record<string, unknown>) => void): () => void {
-  function listener(e: MessageEvent) {
-    if (e.source !== window || e.origin !== window.location.origin) {
-      return;
-    }
-
-    let data: Record<string, unknown>;
-    try {
-      data = typeof e.data === 'string' ? JSON.parse(e.data) : e.data;
-    } catch {
-      return;
-    }
-
-    // Anything without one of our own type values is someone else's traffic sharing this window - a library
-    // or the host page talking to itself - not something to hand to a widget handler.
-    if (typeof data?.type !== 'string' || !WIDGET_MESSAGE_TYPES.has(data.type)) {
-      return;
-    }
-
-    handler(data);
-  }
-
-  window.addEventListener('message', listener);
-  return () => window.removeEventListener('message', listener);
-}
+// The widget's own components talk to each other over postMessage - a cart added in bw-configurator has to
+// reach the bar in bw-cart and the modal in bw-checkout, which are separate custom elements with no shared
+// Svelte tree. That makes every one of these messages same-window and same-origin, and the guards below exist
+// to keep it that way.
+
+import type { CheckoutCartDetailDto } from './client-types';
+
+/** An item was added to the cart from a configurator. */
+export interface CartChangeMessage {
+  type: 'cart:change';
+  itemCount: number;
+  cartItemId: string;
+  totalFormatted: string;
+  // Whether this add should carry the shopper on into checkout. The single source of truth for auto-open on
+  // both builds - createBookingHost reads it directly, and register.ts reaches it through the same host - so
+  // the elements build and the ES build cannot drift on when checkout opens.
+  openCheckout: boolean;
+}
+
+/** The cart's contents changed, anywhere on the page. `cart` is null once the cart is gone. */
+export interface CartUpdatedMessage {
+  type: 'cart:updated';
+  cart: CheckoutCartDetailDto | null;
+}
+
+/**
+ * The cart's window ran out and the cart is gone - distinct from the `cart:updated` with a null cart that
+ * also accompanies it, which a confirmed order posts too. A host telling the shopper "your cart expired"
+ * needs the difference.
+ */
+export interface CartExpiredMessage {
+  type: 'cart:expired';
+}
+
+/** Something asked for checkout to be shown - the cart bar's button, or the expiry guard resuming a payment. */
+export interface ModalOpenMessage {
+  type: 'modal:open';
+}
+
+/** Checkout was dismissed. */
+export interface ModalCloseMessage {
+  type: 'modal:close';
+}
+
+/** Payment completed *and* was confirmed. Does not fire while a confirmation webhook is still pending. */
+export interface OrderCompleteMessage {
+  type: 'order:complete';
+  cartToken: string;
+  value: number;
+  currency: string;
+}
+
+/**
+ * A Peach checkout is open for the cart / has been abandoned so the cart is Open again. Posted by
+ * CheckoutModal for CartExpiryGuard, which keeps prompting but stops acting on the deadline itself while the
+ * server exempts the cart from expiry.
+ */
+export interface PaymentStartedMessage {
+  type: 'payment:started';
+}
+
+export interface PaymentEndedMessage {
+  type: 'payment:ended';
+}
+
+/**
+ * The cart's one clock ran out while a Peach checkout was open. Posted by CartExpiryGuard for CheckoutModal,
+ * which tears the attempt down (Peach's real status permitting) so the shopper sees the cart expire there
+ * too, rather than an ever-open card form for a cart that is already gone.
+ */
+export interface PaymentTimedOutMessage {
+  type: 'payment:timed-out';
+}
+
+/** Every message this widget sends itself. Anything else on the wire is not ours. */
+export type WidgetMessage =
+  | CartChangeMessage
+  | CartUpdatedMessage
+  | CartExpiredMessage
+  | ModalOpenMessage
+  | ModalCloseMessage
+  | OrderCompleteMessage
+  | PaymentStartedMessage
+  | PaymentEndedMessage
+  | PaymentTimedOutMessage;
+
+export type WidgetMessageType = WidgetMessage['type'];
+
+const WIDGET_MESSAGE_TYPES = new Set<string>([
+  'cart:change',
+  'cart:updated',
+  'cart:expired',
+  'modal:open',
+  'modal:close',
+  'order:complete',
+  'payment:started',
+  'payment:ended',
+  'payment:timed-out',
+] satisfies WidgetMessageType[]);
+
+/**
+ * Sends a widget message.
+ *
+ * Targets this window's own origin rather than '*'. These payloads carry `cart`, and CheckoutCartDetailDto
+ * includes `cartToken` - a bearer credential that authorises reading, modifying and paying for the cart. With
+ * '*' that went to whatever origin happened to be framing the widget, which in the standalone iframe build is
+ * not necessarily anyone we trust.
+ */
+export function postMessage(data: WidgetMessage): void {
+  // No window means a server render - an Astro island is server-rendered before it hydrates, and a host
+  // built during that pass would otherwise take the whole page down with a ReferenceError.
+  if (typeof window === 'undefined') return;
+  window.parent?.postMessage(JSON.stringify(data), window.location.origin);
+}
+
+/**
+ * Subscribes to widget messages, ignoring anything that did not come from this widget. Returns an
+ * unsubscribe function.
+ *
+ * The elements mount directly into the merchant's own document (shadow: 'none'), so these listeners sit on
+ * the top-level window of a third-party page. Without this check, any iframe already on that page - an ad, a
+ * chat widget, a tag manager - could reach them with window.parent.postMessage and drive the widget: spoof
+ * the total on the payment consent screen, fire a forged order confirmation into the merchant's analytics, or
+ * close the modal mid-confirm on a card that has already been charged.
+ *
+ * Checking `source` is what does the real work: a message from another frame carries that frame's own window,
+ * never ours, and it cannot be spoofed. The origin check is belt-and-braces for the same-window case.
+ */
+export function onWidgetMessage(handler: (data: WidgetMessage) => void): () => void {
+  // Same reason as postMessage above: nothing to subscribe to on the server, and createBookingHost
+  // subscribes the moment it is built.
+  if (typeof window === 'undefined') return () => {};
+
+  function listener(e: MessageEvent) {
+    if (e.source !== window || e.origin !== window.location.origin) {
+      return;
+    }
+
+    let data: WidgetMessage;
+    try {
+      data = typeof e.data === 'string' ? JSON.parse(e.data) : e.data;
+    } catch {
+      return;
+    }
+
+    // Anything without one of our own type values is someone else's traffic sharing this window - a library
+    // or the host page talking to itself - not something to hand to a widget handler.
+    if (typeof data?.type !== 'string' || !WIDGET_MESSAGE_TYPES.has(data.type)) {
+      return;
+    }
+
+    handler(data);
+  }
+
+  window.addEventListener('message', listener);
+  return () => window.removeEventListener('message', listener);
+}

package/src/lib/peach-sdk.ts

@@ -1,40 +1,86 @@
-const SDK_URLS: Record<string, string> = {
-  prod: 'https://checkout.peachpayments.com/js/checkout.js',
-  qa: 'https://sandbox-checkout.peachpayments.com/js/checkout.js',
-};
-
-let loadPromise: Promise<void> | null = null;
-
-// Lazily injects Peach's Copy&Pay SDK the first time PaymentPage mounts, so consumers embedding the widget
-// (any of the three integration options) never have to know this script exists, let alone which
-// environment's URL to point at - same window.BW_CHECKOUT_ENV convention elements/env.ts already uses for
-// the checkout API base URL, with an explicit override for anything that doesn't fit that pattern.
-export function loadPeachSdk(): Promise<void> {
-  if ((window as any).Checkout) {
-    return Promise.resolve();
-  }
-  if (loadPromise) {
-    return loadPromise;
-  }
-
-  const w = window as any;
-  const env: string = w.BW_CHECKOUT_ENV ?? 'prod';
-  const src: string = w.BW_CHECKOUT_PEACH_SDK_URL ?? SDK_URLS[env] ?? SDK_URLS.prod;
-
-  loadPromise = new Promise((resolve, reject) => {
-    const existing = document.querySelector(`script[src="${src}"]`);
-    if (existing) {
-      existing.addEventListener('load', () => resolve());
-      existing.addEventListener('error', () => reject(new Error('Failed to load the Peach Payments SDK script')));
-      return;
-    }
-
-    const script = document.createElement('script');
-    script.src = src;
-    script.onload = () => resolve();
-    script.onerror = () => reject(new Error('Failed to load the Peach Payments SDK script'));
-    document.head.appendChild(script);
-  });
-
-  return loadPromise;
-}
+const SDK_URLS: Record<string, string> = {
+  prod: 'https://checkout.peachpayments.com/js/checkout.js',
+  qa: 'https://sandbox-checkout.peachpayments.com/js/checkout.js',
+};
+
+let loadPromise: Promise<void> | null = null;
+let configuredUrl: string | null = null;
+let loadedUrl: string | null = null;
+
+/** Which SDK was actually loaded. Only worth knowing when Peach then refuses to render - see PaymentPage. */
+export function loadedPeachSdkUrl(): string | null {
+  return loadedUrl;
+}
+
+export type PeachEnv = 'prod' | 'qa';
+
+/**
+ * Chooses which Peach SDK to load, for consumers with no window globals to set.
+ *
+ * window.BW_CHECKOUT_ENV is the custom-elements build's convention, read off the page that loaded the
+ * script. An ES consumer has no such page - it passes apiBaseUrl to createBookingHost and nothing else -
+ * so without this it silently got the production SDK while its checkout API was creating sandbox
+ * checkoutIds, and Peach answered with "An unrecoverable error has occurred while attempting to render the
+ * checkout experience". createBookingHost calls this for you; it is exported for anyone composing without
+ * a host.
+ */
+export function setPeachSdk(options: { url?: string; env?: PeachEnv }): void {
+  const next = options.url ?? (options.env ? SDK_URLS[options.env] : undefined);
+  if (!next || next === configuredUrl) return;
+  configuredUrl = next;
+  // A different SDK than the one already promised has to be fetched afresh.
+  loadPromise = null;
+}
+
+// Lazily injects Peach's Copy&Pay SDK the first time PaymentPage mounts, so consumers embedding the widget
+// (any of the three integration options) never have to know this script exists, let alone which
+// environment's URL to point at - same window.BW_CHECKOUT_ENV convention elements/env.ts already uses for
+// the checkout API base URL, with an explicit override for anything that doesn't fit that pattern.
+export function loadPeachSdk(): Promise<void> {
+  const w = window as any;
+  const env: string = w.BW_CHECKOUT_ENV ?? 'prod';
+  // Explicit window override first (it is the most specific thing a page can say), then whatever a host
+  // was configured with, then the elements build's env global, then production.
+  const src: string = w.BW_CHECKOUT_PEACH_SDK_URL ?? configuredUrl ?? SDK_URLS[env] ?? SDK_URLS.prod;
+
+  // Peach's SDK cannot be swapped once it has installed window.Checkout, so a page that already loaded one
+  // - its own <script> tag, or an earlier host configured differently - is stuck with it. Resolving in
+  // silence is what made this hard to find the first time: the only symptom is Peach's opaque
+  // "unrecoverable error" card, from a production SDK holding a sandbox checkoutId.
+  if (w.Checkout) {
+    if (loadedUrl !== null && loadedUrl !== src) {
+      console.warn(
+        `[booking-widget] Peach SDK already loaded from ${loadedUrl}, so ${src} was not used. ` +
+          `Configure peachEnv before the first payment, or set window.BW_CHECKOUT_PEACH_SDK_URL.`,
+      );
+    } else if (loadedUrl === null) {
+      console.warn(
+        `[booking-widget] Peach SDK was already on the page when the widget first needed it, so ${src} ` +
+          `was not used. If its environment does not match the checkout API, the card form will not render.`,
+      );
+    }
+    return Promise.resolve();
+  }
+
+  if (loadPromise) {
+    return loadPromise;
+  }
+
+  loadedUrl = src;
+  loadPromise = new Promise((resolve, reject) => {
+    const existing = document.querySelector(`script[src="${src}"]`);
+    if (existing) {
+      existing.addEventListener('load', () => resolve());
+      existing.addEventListener('error', () => reject(new Error('Failed to load the Peach Payments SDK script')));
+      return;
+    }
+
+    const script = document.createElement('script');
+    script.src = src;
+    script.onload = () => resolve();
+    script.onerror = () => reject(new Error('Failed to load the Peach Payments SDK script'));
+    document.head.appendChild(script);
+  });
+
+  return loadPromise;
+}

package/src/lib/portal.ts

@@ -0,0 +1,23 @@
+/**
+ * Moves an element out to `document.body` (or another target) for as long as it is mounted, and puts nothing
+ * back - the node is removed with the component.
+ *
+ * `position: fixed` only escapes to the viewport while no ancestor has established a containing block for it.
+ * A `transform`, `filter`, `backdrop-filter`, `perspective`, `contain` or `will-change` anywhere above, and a
+ * `position: sticky` ancestor's stacking context, are all enough to trap a fixed overlay inside the subtree
+ * and let the host's own header paint over it. No z-index inside that subtree can win, because the contest is
+ * between the ancestor and the header, not between the overlay and anything.
+ *
+ * Consumers hit this the moment they put checkout in a sticky sidebar, which is the ordinary way to lay a
+ * product page out - so the modal portals itself rather than leaving each host to discover the rule.
+ */
+export function portal(node: HTMLElement, target?: HTMLElement | null) {
+  const destination = target ?? (typeof document === 'undefined' ? null : document.body);
+  destination?.appendChild(node);
+
+  return {
+    destroy() {
+      node.remove();
+    },
+  };
+}