@nextcommerce/campaigns-os 1.54.0 → 1.57.0

package/src/qa-cart-entry.mjs

@@ -70,12 +70,21 @@ export const CART_ENTRY_ROUTE_ATTRIBUTE = "data-next-url";
 // preventDefault() unconditionally, so its href never navigates, and it
 // resolves the attribute against the origin (campaign-cart url-utils), not the
 // document base. Without the attribute such a control adds to the cart and
-// stays put — no route. Anywhere else the SDK attribute has no navigation
+// stays put — no route. A control matching one of `declaredRoutes` (each
+// `{ selector, url }`, a route the page declares rather than one the control
+// carries: the SDK checkout form's submit button and an upsell's accept /
+// decline actions) goes to that url and nothing else, because the SDK
+// handles the submission or the click itself, so an href="#" or the form's
+// action never navigates. Anywhere else the SDK attribute has no navigation
 // semantics: an HTML anchor's own resolved href (native, so a <base href> is
 // honoured), then an href attribute, then `data-href`, then a wrapping form's
-// action. Only spellings with real navigation semantics count — an attribute
-// the SDK does not declare is not a route.
-export function cartEntryHrefFor(element, { cartEntrySelector, cartEntryRouteAttribute, origin, baseHref }) {
+// action — for that form's submit button only, and never inside a form
+// matching `checkoutFormSelector`: the SDK checkout form, which the SDK
+// submits itself, or, on a checkout or upsell / downsell page, every form,
+// since there the only form-borne route is the one in `declaredRoutes`. Only
+// spellings with real navigation semantics count — an attribute the SDK does
+// not declare is not a route.
+export function cartEntryHrefFor(element, { cartEntrySelector, cartEntryRouteAttribute, declaredRoutes = [], checkoutFormSelector = null, origin, baseHref }) {
   if (!element || typeof element.getAttribute !== "function") return null;
   if (typeof element.matches === "function" && element.matches(cartEntrySelector)) {
     const sdkRoute = String(element.getAttribute(cartEntryRouteAttribute) || "").trim();
@@ -88,12 +97,26 @@ export function cartEntryHrefFor(element, { cartEntrySelector, cartEntryRouteAtt
       return null;
     }
   }
+  const declared = typeof element.matches === "function"
+    ? (declaredRoutes || []).find((route) => route?.selector && element.matches(route.selector))
+    : null;
+  if (declared) {
+    try {
+      return new URL(declared.url, baseHref).href;
+    } catch {
+      return null;
+    }
+  }
   // An HTML anchor resolves its own href (an SVG <a> exposes an object, not a
   // string, and falls through to the attribute reading).
-  if (String(element.tagName || "").toUpperCase() === "A" && typeof element.href === "string" && element.href) return element.href;
+  const tag = String(element.tagName || "").toUpperCase();
+  if (tag === "A" && typeof element.href === "string" && element.href) return element.href;
+  // The reflected type, so a <button> with no type attribute submits too.
+  const submits = (tag === "BUTTON" || tag === "INPUT") && String(element.type || "").toLowerCase() === "submit";
+  const insideRoutelessForm = Boolean(checkoutFormSelector) && typeof element.closest === "function" && Boolean(element.closest(checkoutFormSelector));
   const attr = element.getAttribute("href")
     || element.getAttribute("data-href")
-    || (typeof element.closest === "function" ? element.closest("form")?.getAttribute("action") : null);
+    || (submits && !insideRoutelessForm && typeof element.closest === "function" ? element.closest("form")?.getAttribute("action") : null);
   if (!attr) return null;
   try {
     return new URL(attr, baseHref).href;
@@ -104,6 +127,17 @@ export function cartEntryHrefFor(element, { cartEntrySelector, cartEntryRouteAtt
   }
 }
 
+// A select page (campaigns-os#641) has no add-to-cart control: its swap-mode
+// bundle selector writes the cart when a card is chosen, the SDK persists the
+// cart between pages, and a checkout button or link moves on. The runner
+// treats "bundle cards plus one of these" as a cart-entry control: the SDK's
+// checkout action, or a plain link into the next page. Matched by this one
+// selector so the chosen control replays with nth().
+export const CART_ENTRY_CHECKOUT_BUTTON_SELECTOR = '[data-next-action="checkout"], a[href]';
+
+// The bundle cards a select page renders, outside the cart summary.
+export const CART_ENTRY_BUNDLE_CARD_SELECTOR = "[data-next-bundle-card]";
+
 // Route-shaped spellings the runner used to consult and no longer does,
 // because the SDK never declares them. They are not routes, but a page that
 // carries one is reported so an operator can tell "the runner narrowed its
@@ -115,8 +149,10 @@ export const UNDECLARED_ROUTE_ATTRIBUTES = Object.freeze(["data-next-href", "dat
 // shop-single-step landing declares; the rest are the entry-like types
 // `deriveEntryUrls` already recognises.
 // Pages that can only follow the checkout: the checkout itself plus the
-// topology module's own offer and receipt sets, so the two never drift.
-const POST_CHECKOUT_PAGE_TYPES = new Set(["checkout", ...OFFER_PAGE_TYPES, ...RECEIPT_PAGE_TYPES]);
+// topology module's own offer and receipt sets, so the two never drift. A
+// checkout_step is never a cart entry either: it is a form page of the
+// checkout path itself (campaigns-os#641).
+const POST_CHECKOUT_PAGE_TYPES = new Set(["checkout", "checkout_step", ...OFFER_PAGE_TYPES, ...RECEIPT_PAGE_TYPES]);
 const PREFERRED_ENTRY_PAGE_TYPES = ["select", "landing", "product", "presell", "entry", "lander", "advertorial", "listicle", "review", "opt-in", "optin"];
 
 export function codedError(code, message) {
@@ -211,18 +247,22 @@ export function summarizeSelectionSurface(surface) {
   return parts.length ? parts.join(", ") : "none";
 }
 
-// evaluate() body: the cart-entry controls the entry page renders. Two kinds:
-//   add_to_cart   the SDK action controls (CART_ENTRY_CONTROL_SELECTOR); the
-//                 SDK adds the package and navigates via data-next-url;
-//   checkout_link a plain link into the checkout URL carrying
-//                 `?forcePackageId=`, which the SDK reads on the checkout page
-//                 to pre-load the cart. This is what the certified
-//                 shop-single-step landing renders today.
+// evaluate() body: the cart-entry controls the entry page renders. Three kinds:
+//   add_to_cart     the SDK action controls (CART_ENTRY_CONTROL_SELECTOR); the
+//                   SDK adds the package and navigates via data-next-url;
+//   checkout_link   a plain link into the checkout URL carrying
+//                   `?forcePackageId=`, which the SDK reads on the checkout
+//                   page to pre-load the cart. This is what the certified
+//                   shop-single-step landing renders today;
+//   checkout_button on a page with bundle cards only: the SDK checkout action
+//                   or a plain link into the checkout URL. The selected card
+//                   is the cart; `bundle_package_ids` lists what the cards
+//                   carry so --select-package can name one (campaigns-os#641).
 // Each control reports its visibility, text, and the package id it carries
 // (own attribute, nearest card, or the forcePackageId ref), so the caller can
 // prefer a visible SDK control and honour --select-package in one round trip.
 export function cartEntryControlsScript() {
-  return ({ selector, checkoutUrl }) => {
+  return ({ selector, checkoutUrl, checkoutButtonSelector = null, bundleCardSelector = null }) => {
     const clean = (value) => String(value || "").replace(/\s+/g, " ").trim();
     const isVisible = (element) => {
       const rect = element.getBoundingClientRect();
@@ -290,7 +330,39 @@ export function cartEntryControlsScript() {
         }];
       })
       : [];
-    return [...actions, ...links];
+    const cards = Array.from(document.querySelectorAll(bundleCardSelector || "[data-next-bundle-card]"))
+      .filter((card) => !card.closest("[data-next-cart-summary], [data-next-upsell-context], [data-next-upsell], template"));
+    const bundlePackageIds = [...new Set(cards.flatMap((card) => {
+      const own = clean(card.getAttribute("data-next-package-id"));
+      const nested = Array.from(card.querySelectorAll("[data-next-package-id]")).map((node) => clean(node.getAttribute("data-next-package-id")));
+      return [own, ...nested].filter(Boolean);
+    }))];
+    const buttons = cards.length && checkoutButtonSelector
+      ? Array.from(document.querySelectorAll(checkoutButtonSelector)).flatMap((element, index) => {
+        const isAction = element.getAttribute("data-next-action") === "checkout";
+        if (!isAction) {
+          const href = element.getAttribute("href");
+          if (!checkout || canonical(href) !== checkout) return [];
+          try {
+            if (new URL(href, document.baseURI).searchParams.get("forcePackageId")) return [];
+          } catch {
+            return [];
+          }
+        }
+        return [{
+          kind: "checkout_button",
+          index,
+          visible: isVisible(element),
+          text: label(element),
+          package_id: null,
+          bundle_package_ids: bundlePackageIds,
+          quantity: 1,
+          next_url: isAction ? null : element.getAttribute("href"),
+          tag: element.tagName.toLowerCase(),
+        }];
+      })
+      : [];
+    return [...actions, ...links, ...buttons];
   };
 }
 
@@ -300,7 +372,7 @@ export function cartEntryControlsScript() {
 // control is only used when nothing is visible.
 export function chooseCartEntryControl(controls = [], requested = []) {
   const list = Array.isArray(controls) ? controls : [];
-  if (!list.length) return { control: null, reason: "no add-to-cart control or forcePackageId checkout link rendered on the entry page" };
+  if (!list.length) return { control: null, reason: "no add-to-cart control, forcePackageId checkout link, or bundle cards with a checkout button rendered on the entry page" };
   const wanted = Array.isArray(requested) ? requested.filter((item) => item?.packageId) : [];
   if (wanted.length > 1) {
     return {
@@ -308,9 +380,24 @@ export function chooseCartEntryControl(controls = [], requested = []) {
       reason: `--select-package requested ${wanted.length} refs, but a landing-page entry can select at most one package before the SDK navigates to checkout`,
     };
   }
+  // A select page's checkout button carries no package of its own: the
+  // requested package is the bundle card the runner clicks before it. Used
+  // only when no add-to-cart control or forcePackageId link carries the ref.
+  const buttons = list.filter((control) => control.kind === "checkout_button");
+  const carriers = list.filter((control) => control.kind !== "checkout_button");
   const byRef = wanted.length
-    ? list.filter((control) => String(control.package_id) === String(wanted[0].packageId))
-    : list;
+    ? carriers.filter((control) => String(control.package_id) === String(wanted[0].packageId))
+    : carriers;
+  if (!byRef.length && buttons.length) {
+    const pick = (pool) => pool.find((control) => control.visible) || pool[0];
+    if (!wanted.length) return { control: pick(buttons), reason: null };
+    const withCard = buttons.filter((control) => (control.bundle_package_ids || []).map(String).includes(String(wanted[0].packageId)));
+    if (withCard.length) return { control: pick(withCard), select_card: wanted[0], reason: null };
+    return {
+      control: null,
+      reason: `--select-package ${wanted[0].packageId}: no bundle card on the entry page carries package ${wanted[0].packageId} (rendered: ${[...new Set(buttons.flatMap((control) => control.bundle_package_ids || []))].join(", ") || "(none)"})`,
+    };
+  }
   if (!byRef.length) {
     return {
       control: null,