@nextcommerce/campaigns-os 1.46.0 → 1.47.0

package/src/qa-browser.mjs

@@ -428,11 +428,11 @@ async function dispatchTestOrderPlans({ context, plans, checkoutPage, args = {},
 // with --analytics-baseline's legacy receipt, and identity resolution cannot
 // derive a receipt page yet (receipt-aware capture is out of packet 01's
 // scope). Absent that override, the candidate IS the resolved target.
-function analyticsParityCaptureAssertions({ baseline, candidate, baselineUrl, candidateUrl, capturePage = null, rootFallback = null }) {
+function analyticsParityCaptureAssertions({ baseline, candidate, baselineUrl, candidateUrl, capturePage = null, rootFallback = null, candidatePage = null }) {
   const baselinePublicUrl = redactUrlQuery(baselineUrl);
   const candidatePublicUrl = redactUrlQuery(candidateUrl);
   const analyticsPage = { page_id: "analytics", url: candidatePublicUrl || baselinePublicUrl || undefined };
-  const assertions = diffAnalyticsParity(baseline, candidate, { url: candidatePublicUrl });
+  const assertions = diffAnalyticsParity(baseline, candidate, { url: candidatePublicUrl, ...(candidatePage ? { candidatePage } : {}) });
   assertions.unshift(assertion({
     id: "analytics-parity:capture",
     family: "analytics-parity",
@@ -540,9 +540,24 @@ async function captureAnalyticsParityInContext(context, baselineUrl, targetUrl,
     candidateUrl: selected.url,
     capturePage: selected.capturePage,
     rootFallback: selected.rootFallback,
+    candidatePage: automaticParityCandidatePage(selected),
   });
 }
 
+// #512: what the automatic candidate is, for the Purchase checks. The campaign
+// root is never a receipt; a built entry is one only when its topology page
+// type says so. A receipt loaded without an order fires no Purchase, so the
+// leg does not go looking for the topology's receipt step: the operator pairs
+// receipts with --analytics-candidate.
+function automaticParityCandidatePage(selected) {
+  const pageType = selected.pageType || null;
+  return {
+    receipt: contractPageType({ page_type: pageType }) === "receipt",
+    source: selected.capturePage?.source || null,
+    page_type: pageType,
+  };
+}
+
 // Analytics CORRECTNESS inventory leg: capture ONE page and assess only
 // declared tags/pixels. Purchase is finalized later from the canonical
 // typed-card order's recognized receipt; this inventory visit is never treated
@@ -716,6 +731,7 @@ function analyticsCaptureCandidates(url, options = {}) {
       source: "built_entry",
       page_id: entry.page_id || null,
       funnel_id: entry.funnel_id || null,
+      page_type: entry.page_type || null,
       // The query value is redacted from every record; this says the entry
       // was told apart from the root by its query alone.
       ...(url && isQueryRoutedFrom(trim(entry.url), url) ? { query_routed: true } : {}),
@@ -761,6 +777,7 @@ async function captureFirstAnsweringAnalyticsPage(context, url, args, extraHosts
           ...queryRouted(candidate),
           http_status: httpStatus ?? null,
         },
+        pageType: candidate.page_type || null,
         rootFallback: usedFallback ? rootFallback : null,
       };
     }
@@ -5171,10 +5188,18 @@ async function clickUpsellPath(page, path, { trace = null } = {}) {
   // the browser's wall time at request start), and armedAt is read before the
   // click is sent, so this click's request starts at or after it. A request
   // with no known start time is not excluded: nothing shows it is stale.
+  //
+  // A redirected POST (307/308) is one mutation across several hops, and
+  // Playwright gives each hop its own Request. The watch matches a hop by the
+  // request that started its chain, and passes over a hop the browser follows,
+  // so it resolves on the chain's final response: that is the one carrying the
+  // order. A chain with no final response is not answered (#516).
   const armedAt = Date.now();
   const mutationPromise = path === "accept"
     ? page.waitForResponse((response) => {
-        if (response.request().method() !== "POST" || !isOrderUpsellsUrl(response.url())) return false;
+        if (isFollowedRedirect(response)) return false;
+        const root = responseRequest(response);
+        if (!root || root.method() !== "POST" || !isOrderUpsellsUrl(root.url())) return false;
         const startedAt = responseRequestStartedAt(response);
         return startedAt === null || startedAt >= armedAt;
       }, { timeout: UPSELL_MUTATION_TIMEOUT_MS + (perpetual ? 0 : UPSELL_CLICK_TIMEOUT_MS) }).catch(() => null)
@@ -5205,9 +5230,9 @@ async function clickUpsellPath(page, path, { trace = null } = {}) {
     // waits for a later read-back before it judges the step.
     ...(bodyRead ? { api_response_body_read: { timed_out: bodyRead.timed_out, waited_ms: bodyRead.waited_ms, bound_ms: bodyRead.bound_ms } } : {}),
   };
-  // The request this click made. Another step's upsell mutation posts to the
-  // same order-upsells URL, so a late body is this step's only when it
-  // answers this request.
+  // The request this click made (the root of its redirect chain). Another
+  // step's upsell mutation posts to the same order-upsells URL, so a late body
+  // is this step's only when it answers this request.
   const mutationRequest = mutationResponse ? responseRequest(mutationResponse) : null;
   if (mutationRequest) record[REQUEST_IDENTITY] = mutationRequest;
   return record;
@@ -6191,21 +6216,52 @@ function mutationRespondedAt(response) {
 // it). Playwright hands every listener the same Request object for one
 // request, and a different one for each request, even to the same URL: an
 // upsell step matches its own mutation's late body by this identity (#505).
+//
+// A redirect gives each hop a new Request, so the identity is the request
+// that started the chain (followed back through redirectedFrom()): every hop
+// of one redirected POST carries the same identity, and two POSTs never do
+// (#516).
 const REQUEST_IDENTITY = Symbol("campaigns-os.request-identity");
 
 function responseRequest(response) {
   try {
-    return response.request() || null;
+    return redirectChainRoot(response.request());
   } catch {
     return null;
   }
 }
 
+// Walks back to the chain's first request. A visited set ends the walk on any
+// chain, however long, so every hop of one chain reports the same root.
+function redirectChainRoot(request) {
+  let root = request || null;
+  const visited = new Set();
+  while (root && typeof root.redirectedFrom === "function" && !visited.has(root)) {
+    visited.add(root);
+    const previous = root.redirectedFrom();
+    if (!previous) break;
+    root = previous;
+  }
+  return root;
+}
+
+// A 3xx hop the browser follows: it names a Location, and the chain's answer
+// is a later hop's response. A 3xx with no Location is a final response.
+function isFollowedRedirect(response) {
+  try {
+    const status = response.status();
+    return status >= 300 && status < 400 && Boolean(response.headers()?.location);
+  } catch {
+    return false;
+  }
+}
+
 // When the browser started a response's request, in epoch milliseconds (the
-// same clock as Date.now()), or null when Playwright does not report it.
+// same clock as Date.now()), or null when Playwright does not report it. For a
+// redirected request this is when its chain's first hop started.
 function responseRequestStartedAt(response) {
   try {
-    const startTime = response.request().timing().startTime;
+    const startTime = responseRequest(response).timing().startTime;
     return Number.isFinite(startTime) && startTime > 0 ? startTime : null;
   } catch {
     return null;
@@ -6228,11 +6284,16 @@ function captureCheckoutEvents(page) {
   // polls for it. A bound here would record a slow but successful order body
   // as null for good, and the order would read as not created.
   page.on("response", async (response) => {
-    if (!interesting.test(response.url())) return;
+    // A redirected chain is logged by where it started, so its final hop is
+    // captured even when it answers from a URL this filter would not match
+    // (#516): the late-body search finds it by request identity.
+    const request = responseRequest(response);
+    let chainUrl = null;
+    try { chainUrl = request?.url() ?? null; } catch { /* identity only */ }
+    if (!interesting.test(response.url()) && !(chainUrl && interesting.test(chainUrl))) return;
     // Taken before the body read: an entry lands in the log when its body
     // finishes, so its position says nothing about when it was requested.
     const requestStartedAt = responseRequestStartedAt(response);
-    const request = responseRequest(response);
     const entry = {
       status: response.status(),
       url: response.url(),
@@ -7369,7 +7430,8 @@ async function waitForLateUpsellEvidence(events, { responseIndexBefore, mutation
       const response = fresh[index];
       if (!response.body || typeof response.body !== "object" || Array.isArray(response.body)) continue;
       if (!(response.status >= 200 && response.status < 300)) continue;
-      if (!ORDER_UPSELLS_RESPONSE_PATTERN.test(response.url)) continue;
+      // A redirected mutation's final hop may answer from another URL; its
+      // identity, the root of its chain, is what ties it to this step (#516).
       if (mutationRequest && response[REQUEST_IDENTITY] === mutationRequest) return { source: "late_upsell_body", body: response.body };
     }
     for (let index = fresh.length - 1; index >= 0; index -= 1) {

package/src/sdk-markup.mjs

@@ -40,12 +40,11 @@
 //   TEMPLATE_DOUBLE_BRACE      `{{` inside an SDK-owned <template>. SDK tokens
 //                              are single-brace and conditions are no-brace;
 //                              a double brace renders literally.
-//   CHECKOUT_BUMP_IS_UPSELL    data-next-is-upsell="true" on a checkout page
-//                              (#535). A checkout bump is a pre-purchase
-//                              add-on; the flag puts it on the initial order
-//                              as an upsell line. The page type is a live,
-//                              unambiguous next-page-type meta, since it is
-//                              what the SDK reads; otherwise the route type.
+//
+//   Not a finding: data-next-is-upsell="true" on a checkout order bump. The
+//   selected bump is a line item on the checkout order, tagged as an upsell so
+//   order reports show it apart from core items. That is the intended default;
+//   a bump include opts out with is_upsell: false.
 //
 //   Info (advisory, one note per campaign, no code)
 //   unknown_attributes[]       a data-next-* name the pinned SDK's attribute
@@ -70,9 +69,6 @@ import {
   isIndexedSdkAttribute,
   isKnownCheckoutFieldName,
 } from "./sdk-attribute-index.mjs";
-import { builtPageTypeMeta } from "./upsell-selector-scope.mjs";
-
-const normalizedPageTypeValue = (type) => (type == null ? null : String(type).trim().toLowerCase());
 
 export const SDK_MARKUP = "built_output.sdk_markup";
 
@@ -84,7 +80,6 @@ export const SDK_MARKUP_CODES = Object.freeze({
   ORPHANED_UPSELL_ACTION: { code: `${SDK_MARKUP}.orphaned_upsell_action`, severity: "error" },
   DOUBLE_SELECTED: { code: `${SDK_MARKUP}.double_selected`, severity: "warning" },
   TEMPLATE_DOUBLE_BRACE: { code: `${SDK_MARKUP}.template_double_brace`, severity: "warning" },
-  CHECKOUT_BUMP_IS_UPSELL: { code: `${SDK_MARKUP}.checkout_bump_is_upsell`, severity: "warning" },
   // Unknown data-next-* names are not a finding and carry no code: they are
   // information on the gate (unknown_attributes[]) and one advisory ready line.
 });
@@ -160,22 +155,11 @@ function describe(entry) {
   return `${bits.join("")}>`;
 }
 
-function describeBump(entry) {
-  const id = entry.attrs.get("id");
-  const packageId = entry.attrs.get("data-next-package-id");
-  const bits = [`<${entry.tag}`];
-  if (id) bits.push(` id="${id}"`);
-  if (packageId) bits.push(` data-next-package-id="${packageId}"`);
-  return `${bits.join("")}>`;
-}
-
 /**
  * Scan one built page. Returns findings with { code_name, code, severity,
  * page_id, file, message, detail } and the set of unknown data-next-* names.
- * `page_type` is the route-inferred type, used only when the page declares no
- * live, unambiguous next-page-type meta (builtPageTypeMeta).
  */
-export function scanPageMarkup({ page_id, file = null, content = "", page_type = null }) {
+export function scanPageMarkup({ page_id, file = null, content = "" }) {
   const document = parse(String(content || ""));
   const where = file || page_id;
   const findings = [];
@@ -186,13 +170,10 @@ export function scanPageMarkup({ page_id, file = null, content = "", page_type =
   const selectorIds = new Set(); // ids of elements that are themselves a selector
   const templates = []; // { entry, sdkOwned }
   const referencedTemplateIds = new Set();
-  const upsellFlagged = []; // entries carrying data-next-is-upsell="true"
 
   walkElements(document, (entry) => {
     const { tag, attrs: a, ancestors } = entry;
 
-    if ((a.get("data-next-is-upsell") || "").trim().toLowerCase() === "true") upsellFlagged.push(entry);
-
     for (const [name] of a) {
       if (name.startsWith("data-next-") && !isIndexedSdkAttribute(name)) unknown.add(name);
       if (TEMPLATE_ID_ATTRIBUTES.test(name) && a.get(name)) referencedTemplateIds.add(a.get(name).trim());
@@ -307,26 +288,6 @@ export function scanPageMarkup({ page_id, file = null, content = "", page_type =
       { template_id: id || null, snippet }));
   }
 
-  // One finding per page, naming every flagged element: the repair is the
-  // same for each (drop the flag from the bump include's markup; several
-  // starter includes write it unconditionally, so an is_upsell=false argument
-  // does not always clear it).
-  // The page type is read only when a flag is present, so a page without one
-  // is not parsed a second time.
-  const pageTypeMeta = upsellFlagged.length ? builtPageTypeMeta(content) : null;
-  // The live, unambiguous meta wins because it is what the SDK reads; the
-  // upsell gate's narrower oto-route rule (builtPageTypeOverRouteGuess) does
-  // not apply to a checkout bump.
-  const effectivePageType = upsellFlagged.length
-    ? normalizedPageTypeValue(pageTypeMeta ?? page_type)
-    : null;
-  if (effectivePageType === "checkout") {
-    const elements = upsellFlagged.map(describeBump);
-    findings.push(finding("CHECKOUT_BUMP_IS_UPSELL", page_id, where,
-      `${elements.length > 1 ? `${elements.length} order bumps` : "An order bump"} on checkout page ${where} (${elements.join(", ")}) ${elements.length > 1 ? "carry" : "carries"} data-next-is-upsell="true". A checkout bump is a pre-purchase add-on; the flag puts it on the initial order as an upsell line. The flag comes from the bump include's markup, and several starter bump includes write it unconditionally, so remove data-next-is-upsell="true" from the include in this campaign unless the line really should be billed as an upsell.`,
-      { page_type: effectivePageType, page_type_source: pageTypeMeta !== null ? "next-page-type" : "route", elements }));
-  }
-
   return { page_id, file, findings, unknown_attributes: [...unknown].sort() };
 }
 

package/src/sdk-storage-compatibility.mjs

@@ -57,8 +57,9 @@ export function readStorageManifest(path) {
   version(value.sdkVersion);
   version(value.supportedSdkVersions?.min);
   version(value.supportedSdkVersions?.max);
-  if (compare(value.sdkVersion, value.supportedSdkVersions.max) !== 0)
-    throw new Error('Manifest source SDK version must equal supported maximum.');
+  // A release manifest may describe a supported range ending below its own release; it cannot vouch past itself.
+  if (compare(value.sdkVersion, value.supportedSdkVersions.max) < 0)
+    throw new Error('Manifest source SDK version is below its supported maximum.');
   const unique = new Set();
   if (compare(value.supportedSdkVersions.min, value.supportedSdkVersions.max) > 0)
     throw new Error('Invalid manifest version range.');

package/src/tooling-setup.mjs

@@ -101,6 +101,13 @@ export function setupTooling(args, { packageRoot, installSkills, installAgentCon
   if (!existsSync(join(target, "node_modules", "next-campaign-page-kit", "package.json"))) {
     throw new Error("tooling setup: page-kit is declared but not installed; run npm ci in the selected project first.");
   }
+  // Page-kit builds the deployed pages, so a dev-only declaration disappears
+  // from any host that installs with --omit=dev or NODE_ENV=production.
+  // The command names the installed version, so it can be pasted as-is.
+  const pageKitVersion = json(join(target, "node_modules", "next-campaign-page-kit", "package.json")).version;
+  const warnings = manifest.dependencies?.["next-campaign-page-kit"] ? [] : [
+    `next-campaign-page-kit is declared only in devDependencies, so builds that run npm ci --omit=dev or set NODE_ENV=production will not install it. Move it back with npm install --save-exact next-campaign-page-kit@${pageKitVersion}.`,
+  ];
 
   // Preflight every destination before any installer runs. Custom repository
   // instructions are preserved; only one Claude import line is appended.
@@ -136,6 +143,7 @@ export function setupTooling(args, { packageRoot, installSkills, installAgentCon
     context,
     instructions: { path: instructions, action: !ready ? "not_run" : hasImport ? "unchanged" : "append_import" },
     browser,
+    warnings,
     next_action: contextFailed
       ? `Setup could not add the runtime ignore block (${context.gitignore.reason}). Fix .gitignore and rerun setup; skills and context files may already be installed.`
       : args["dry-run"]
@@ -154,6 +162,7 @@ export function setupTextLines(result) {
     `Skills revision: ${result.skills_revision}`,
     `Browser: ${result.browser.status}`,
     ...(result.browser.note ? [result.browser.note] : []),
+    ...(result.warnings ?? []).map((warning) => `Warning: ${warning}`),
     result.next_action,
     result.note,
   ];