@nextcommerce/campaigns-os 1.53.0 → 1.54.0

package/src/qa-browser.mjs

@@ -77,6 +77,22 @@ const DEFAULT_TEST_CARD = "6011111111111117";
 const DEFAULT_TEST_CVV = "123";
 const DEFAULT_TEST_EXP_MONTH = "12";
 const DEFAULT_TEST_EXP_YEAR = "2030";
+// The card number and CVV iframes, matched by id prefix because each id ends
+// in a per-load suffix. SDK 0.4.40 and earlier mount Spreedly's iFrame v1
+// (spreedly-number-frame-1234); 0.4.41 mounts the Spreedly Checkout SDK fields
+// that NEXT's payments.29next.com/js/v1/payment.js loads
+// (spreedly-hosted-number-oujmii2uzjk). A page carries one generation or the
+// other, and each frame holds a single text input. fillPaymentFields refuses
+// by name unless exactly one number frame and one CVV frame match, so a page
+// mounting both generations, or two forms, fails at the card step instead of
+// on whichever frame happens to come first.
+const CARD_NUMBER_FRAME = 'iframe[id^="spreedly-number-frame"], iframe[id^="spreedly-hosted-number"]';
+const CARD_CVV_FRAME = 'iframe[id^="spreedly-cvv-frame"], iframe[id^="spreedly-hosted-cvv"]';
+// Typing the card is read back and retried this many times in all before the
+// card step fails by name.
+const CARD_TYPE_ATTEMPTS = 3;
+// How long the card step waits for the SDK to report the card fields ready.
+const CARD_READY_TIMEOUT_MS = 15000;
 const DEFAULT_MAX_TEST_ORDERS = 6;
 // Planned-path ids listed in a refused --max-test-orders message before the
 // remainder is counted rather than printed.
@@ -3868,7 +3884,7 @@ async function executeTestOrderPath({ page, events, email, ladder, checkoutPage,
     }, { timeoutMs: budget() });
     await ladder.run("card_fields_filled", async () => {
       ensurePageFillable(page, checkoutPage.url);
-      await fillPaymentFields(page, args);
+      return fillPaymentFields(page, args);
     }, { timeoutMs: budget() });
     await ladder.run("cart_created", async () => {
       const cart = cartCreationEvidence(events);
@@ -5083,14 +5099,69 @@ async function fillPaymentFields(page, args) {
 
   const card = normalizeCard(stringArg(args["test-card"]) || DEFAULT_TEST_CARD);
   const cvv = stringArg(args["test-cvv"]) || DEFAULT_TEST_CVV;
-  const numberInput = page.frameLocator('iframe[id^="spreedly-number-frame"]').locator("input").first();
-  const cvvInput = page.frameLocator('iframe[id^="spreedly-cvv-frame"]').locator("input").first();
-  await numberInput.click();
-  await numberInput.pressSequentially(card, { delay: 20 });
-  await cvvInput.click();
-  await cvvInput.pressSequentially(cvv, { delay: 20 });
-  await page.locator("body").click({ position: { x: 20, y: 20 } }).catch(() => {});
-  await page.waitForTimeout(500);
+  const frames = await cardFrames(page);
+  const readyWaitMs = await waitForCardFieldsReady(page);
+  const numberInput = page.frameLocator(CARD_NUMBER_FRAME).locator("input").first();
+  const cvvInput = page.frameLocator(CARD_CVV_FRAME).locator("input").first();
+  const typed = async (input) => normalizeCard(await input.inputValue());
+  let attempts = 0;
+  let held = null;
+  while (attempts < CARD_TYPE_ATTEMPTS) {
+    attempts++;
+    if (attempts > 1) {
+      await numberInput.fill("");
+      await cvvInput.fill("");
+    }
+    await numberInput.click();
+    await numberInput.pressSequentially(card, { delay: 20 });
+    await cvvInput.click();
+    await cvvInput.pressSequentially(cvv, { delay: 20 });
+    await page.locator("body").click({ position: { x: 20, y: 20 } }).catch(() => {});
+    await page.waitForTimeout(500);
+    held = { number: await typed(numberInput), cvv: await typed(cvvInput) };
+    if (held.number === card && held.cvv === normalizeCard(cvv)) {
+      return { evidence: { ...frames, ready_wait_ms: readyWaitMs, attempts } };
+    }
+  }
+  throw new Error(`card fields did not keep the typed card after ${attempts} attempts: number field holds ${held.number.length} digit(s) ending ${held.number.slice(-4) || "(empty)"} (typed ${card.length} ending ${card.slice(-4)}), CVV field holds ${held.cvv.length} digit(s)`);
+}
+
+// Typing into the card fields before the SDK reports them ready can lose
+// keystrokes: on SDK 0.4.41 the Spreedly-hosted number input exists before
+// its script has loaded, and digits typed in that window are dropped (seen
+// as a number missing its leading digits, which the SDK then refuses without
+// tokenizing, so the order never posts). The checkout form carries
+// next-loading-spreedly from before the card iframes mount until the fields
+// are ready, in 0.4.38 through 0.4.41, so wait for it to clear. A page whose
+// SDK never set it is ready at once. The SDK also clears it when the card
+// script fails to load, so a class still set after the wait means the card
+// script never answered; the step refuses by name rather than type into
+// fields that may drop the number.
+async function waitForCardFieldsReady(page) {
+  const started = Date.now();
+  await page.waitForFunction(() => !document.querySelector(".next-loading-spreedly"), null, { timeout: CARD_READY_TIMEOUT_MS }).catch((error) => {
+    if (error?.name !== "TimeoutError") throw error;
+    throw new Error(`card fields did not report ready within ${CARD_READY_TIMEOUT_MS / 1000}s: the checkout form still carries next-loading-spreedly, so the card script never finished loading`);
+  });
+  return Date.now() - started;
+}
+
+// The card iframes the step is about to type into, once the SDK has mounted
+// them. Exactly one of each, of one generation, or the step fails by name.
+async function cardFrames(page) {
+  await page.locator(CARD_NUMBER_FRAME).first().waitFor({ state: "attached" });
+  await page.locator(CARD_CVV_FRAME).first().waitFor({ state: "attached" });
+  const ids = async (selector) => page.locator(selector).evaluateAll((nodes) => nodes.map((node) => node.id));
+  const number = await ids(CARD_NUMBER_FRAME);
+  const cvv = await ids(CARD_CVV_FRAME);
+  const all = [...number, ...cvv];
+  const generation = all.every((id) => id.startsWith("spreedly-hosted-"))
+    ? "spreedly-hosted"
+    : all.every((id) => /^spreedly-(number|cvv)-frame/.test(id)) ? "spreedly-iframe-v1" : "mixed";
+  if (number.length !== 1 || cvv.length !== 1 || generation === "mixed") {
+    throw new Error(`expected one card number iframe and one CVV iframe of one generation; found number=[${number.join(", ")}] cvv=[${cvv.join(", ")}]`);
+  }
+  return { generation, number_frame_id: number[0], cvv_frame_id: cvv[0] };
 }
 
 async function clickCreditPaymentMethod(page) {

package/src/qa-node.mjs

@@ -168,7 +168,9 @@ Options:
                                   qa publish reads the same directory when looking up the sidecar's run.
   --post-verdict                  (default) Publish the verdict to the QA portal at
                                   <proxy-base>/api/qa/verdicts and print the QA portal link.
-                                  Publishing is automatic; this flag is retained for clarity.
+                                  Publishing is automatic, except for a run whose base URL is a local
+                                  address (localhost, *.localhost, 127.x.x.x, 0.0.0.0, [::1], an IPv4-mapped loopback): that verdict stays local unless
+                                  this flag is passed.
   --no-post-verdict, --local-only Skip publishing; write only the local verdict copy (offline / dev / CI).
                                   Publish it later, without a re-run, with qa publish.
   --verdict <path>                qa promote / qa publish: the full verdict file under qa-output/. qa publish
@@ -2668,7 +2670,7 @@ async function finalizeQaRun({ args, resolved, runId, startedAt, assertions, tes
   const consent = resolveConsent({ proxyBase: resolved.proxyBase });
   const publishDecision = resolved.localSpecId
     ? { publish: false, reason: "local_spec", flag_invalid: false }
-    : decidePublishVerdict({ args, portalManaged: resolved.portalManaged === true, consent });
+    : decidePublishVerdict({ args, portalManaged: resolved.portalManaged === true, consent, baseUrl: resolved.baseUrl });
   if (publishDecision.flag_invalid) {
     process.stderr.write(`[campaigns-os] --post-verdict "${args["post-verdict"]}" is not a recognized value (use true|1|yes|y|on or false|0|no|n|off); the flag was ignored and the default publish decision applied.\n`);
   }
@@ -3472,6 +3474,9 @@ function output(value, args) {
     } else if (value.publish_skipped && value.publish_decision?.reason === "consent_off") {
       console.log(`QA portal: publish skipped — telemetry consent is off, so this non-portal-managed verdict stays local.`);
       console.log(`  Destination would be ${value.publish_decision.destination}. Opt in for this run with --post-verdict, or enable with \`${cmd("telemetry")} on\`.`);
+    } else if (value.publish_skipped && value.publish_decision?.reason === "loopback_base_url") {
+      console.log(`QA portal: publish skipped — the base URL is a local address, so this verdict stays local.`);
+      console.log(`  Destination would be ${value.publish_decision.destination}. Publish this run with \`${cmd("qa")} publish\`, or pass --post-verdict on the next run.`);
     } else if (value.publish_skipped) {
       console.log(`QA portal: publish skipped (--no-post-verdict); local verdict only.`);
     } else {
@@ -3757,8 +3762,13 @@ export function forcedAnalyticsCorrectness(args) {
 // else (client projects, fixtures, local shakeouts on a local spec), consent
 // off (CAMPAIGNS_OS_TELEMETRY=off / `campaigns-os telemetry off`) means the
 // verdict stays local, with the destination and the opt-in flag named in the
-// run output. Publishing for the portal path is never weakened.
-export function decidePublishVerdict({ args = {}, portalManaged = false, consent = null } = {}) {
+// run output. Publishing for the portal path is never weakened by consent.
+// #486: a run against a local-address base URL (localhost or any *.localhost
+// name, any 127.x.x.x, 0.0.0.0, [::1] or an IPv4-mapped loopback; see
+// isLocalAddressUrl below) is a local check, so by default its verdict stays
+// local whatever the spec source; the output names --post-verdict and qa
+// publish. An explicit --post-verdict still publishes.
+export function decidePublishVerdict({ args = {}, portalManaged = false, consent = null, baseUrl = null } = {}) {
   if (args["no-post-verdict"] === true || args["local-only"] === true) {
     return { publish: false, reason: "flag_opt_out" };
   }
@@ -3775,11 +3785,30 @@ export function decidePublishVerdict({ args = {}, portalManaged = false, consent
     flagInvalid = true;
   }
   const decorate = (decision) => (flagInvalid ? { ...decision, flag_invalid: true } : decision);
+  if (isLocalAddressUrl(baseUrl)) return decorate({ publish: false, reason: "loopback_base_url" });
   if (portalManaged) return decorate({ publish: true, reason: "portal_managed_default" });
   if (consent?.state === "off") return decorate({ publish: false, reason: "consent_off" });
   return decorate({ publish: true, reason: "default" });
 }
 
+// The publish default (#486) reads "local" more widely than the shared
+// LOOPBACK_HOSTNAMES list, which also decides where plain http is allowed and
+// so stays narrow: any 127.0.0.0/8 address, 0.0.0.0, [::1], an IPv4-mapped
+// loopback, and localhost or any *.localhost name (with or without a trailing
+// dot). Keeping such a run local is the safe direction: --post-verdict and
+// qa publish still send it.
+function isLocalAddressUrl(value) {
+  if (typeof value !== "string" || !value.trim()) return false;
+  let hostname;
+  try { hostname = new URL(value.trim()).hostname.toLowerCase(); } catch { return false; }
+  const name = hostname.replace(/\.$/, "");
+  if (name === "localhost" || name.endsWith(".localhost")) return true;
+  if (/^127(?:\.\d{1,3}){3}$/.test(name) || name === "0.0.0.0") return true;
+  if (name === "[::1]" || name === "[::]") return true;
+  // WHATWG URL serializes ::ffff:127.x.y.z as [::ffff:7fxx:xxxx].
+  return /^\[::ffff:7f[0-9a-f]{2}:[0-9a-f]{1,4}\]$/.test(name);
+}
+
 function policySnapshot(packet) {
   return {
     campaign: {

package/src/sdk-attribute-index.mjs

@@ -1,25 +1,43 @@
 // The Campaign Cart SDK attribute index, vendored for the static SDK markup
 // checks (#303).
 //
-// Source: docs/attribute-index.md in NextCommerceCo/campaign-cart at tag
-// v0.4.38 (the SDK pin every certified starter family ships today), which is
-// generated from the feature manifests. Only the data-next-* names are kept:
-// the checks that read this list ask "does the SDK read this data-next-*
-// attribute at all", and the SDK's other attribute families (data-item-*,
-// data-package-*, plain data-*) are not what an agent kit misspells.
+// Source: the SDK's own source in NextCommerceCo/campaign-cart at tag
+// v0.4.41 (the SDK pin every certified starter family ships today): every
+// data-next-* name the SDK's non-test TypeScript names as a string, plus every
+// `dataset.next*` property it reads or writes, turned back into its
+// attribute. Only the data-next-* names are kept: the checks that read this
+// list ask "does the SDK read this data-next-* attribute at all", and the
+// SDK's other attribute families (data-item-*, data-package-*, plain data-*)
+// are not what an agent kit misspells.
 //
 // This is a hardcoded copy and says so, rather than restating the SDK in
 // prose that then drifts (the partner kit's mistake): the list is regenerated
-// whole from the index at a named tag, never edited by hand.
+// whole from the source at a named tag, never edited by hand.
 //
-//   git -C ../campaign-cart show v0.4.38:docs/attribute-index.md \
-//     | grep -oE '`data-[a-z0-9-]+(\s*/\s*data-[a-z0-9-]+)*`' \
-//     | tr -d '`' | tr '/' '\n' | tr -d ' ' | grep '^data-next-' | sort -u
+//   paths=('src/**/*.ts' ':!src/**/*.test.ts' ':!src/**/tests/**' ':!src/docs/**')
+//   { git -C ../campaign-cart grep -h -oP 'data-next-[a-z0-9]+(?:-[a-z0-9]+)*-?' v0.4.41 -- "${paths[@]}"
+//     git -C ../campaign-cart grep -h -oP 'dataset\.next[A-Z][A-Za-z0-9]*' v0.4.41 -- "${paths[@]}" \
+//       | sed 's/^dataset\.//' | perl -pe 's/([A-Z])/-\L$1/g; s/^/data-/'
+//   } | sort -u
+//
+// Up to v0.4.40 the list came from docs/attribute-index.md, which the SDK
+// generated from its feature manifests. v0.4.41 removed the manifests and the
+// index (campaign-cart 5d81b4eb), and its hand-written attribute docs
+// (docs/sdk-attributes.md, docs/guides/reference/data-attributes.md, each
+// feature's guide/) leave out names the source still reads, such as
+// data-next-package-selector and data-next-remove-item. Run at v0.4.40, the
+// source recipe returns every name the v0.4.40 index listed, plus names the
+// manifests never did (the address block's, data-next-i18n,
+// data-next-bump-section, data-next-button-text, the variant option state).
+// At v0.4.41 it returns every name of the v0.4.38 list this replaces, plus
+// those and data-next-phone-e164 / data-next-phone-country.
 //
 // A name ending in "-" (data-next-class-) is a prefix the SDK reads with any
 // suffix.
 
-export const SDK_ATTRIBUTE_INDEX_VERSION = "0.4.38";
+import { RELEASED_SDK_VERSION_PATTERN } from "../campaign-spec/dist/index.js";
+
+export const SDK_ATTRIBUTE_INDEX_VERSION = "0.4.41";
 
 export const SDK_DATA_NEXT_ATTRIBUTES = Object.freeze([
   "data-next-accordion",
@@ -28,8 +46,15 @@ export const SDK_DATA_NEXT_ATTRIBUTES = Object.freeze([
   "data-next-accordion-trigger",
   "data-next-action",
   "data-next-active",
+  "data-next-address",
+  "data-next-address-api",
+  "data-next-address-field",
+  "data-next-address-lang",
+  "data-next-address-row",
+  "data-next-address-state",
   "data-next-await",
   "data-next-bump",
+  "data-next-bump-section",
   "data-next-bundle-card",
   "data-next-bundle-display",
   "data-next-bundle-id",
@@ -47,6 +72,7 @@ export const SDK_DATA_NEXT_ATTRIBUTES = Object.freeze([
   "data-next-bundle-template-id",
   "data-next-bundle-vouchers",
   "data-next-bundles",
+  "data-next-button-text",
   "data-next-cart-item-id",
   "data-next-cart-items",
   "data-next-cart-selector",
@@ -74,6 +100,7 @@ export const SDK_DATA_NEXT_ATTRIBUTES = Object.freeze([
   "data-next-fallback",
   "data-next-format",
   "data-next-hide",
+  "data-next-i18n",
   "data-next-id",
   "data-next-in-cart",
   "data-next-include-shipping",
@@ -98,6 +125,8 @@ export const SDK_DATA_NEXT_ATTRIBUTES = Object.freeze([
   "data-next-payment-form",
   "data-next-payment-method",
   "data-next-payment-state",
+  "data-next-phone-country",
+  "data-next-phone-e164",
   "data-next-product-sync",
   "data-next-property",
   "data-next-property-container",
@@ -138,6 +167,7 @@ export const SDK_DATA_NEXT_ATTRIBUTES = Object.freeze([
   "data-next-tooltip-offset",
   "data-next-tooltip-placement",
   "data-next-tracking-tag",
+  "data-next-unavailable",
   "data-next-upsell",
   "data-next-upsell-action",
   "data-next-upsell-action-for",
@@ -152,17 +182,21 @@ export const SDK_DATA_NEXT_ATTRIBUTES = Object.freeze([
   "data-next-url",
   "data-next-validate",
   "data-next-variant-code",
+  "data-next-variant-name",
   "data-next-variant-option",
   "data-next-variant-option-template-id",
   "data-next-variant-options",
   "data-next-variant-selector-template-id",
   "data-next-variant-selectors",
+  "data-next-variant-value",
 ]);
 
-// The fixed data-next-checkout-field names, from the same tag. The SDK maps a
-// field to the order by this value, so an unlisted name is a silent no-op: the
-// input renders, the shopper fills it, nothing reaches the order. Sources at
-// v0.4.38: src/features/checkout/README.md ("Standard field names"), the
+// The fixed data-next-checkout-field names. The SDK maps a field to the order
+// by this value, so an unlisted name is a silent no-op: the input renders, the
+// shopper fills it, nothing reaches the order. Taken at v0.4.38 and unchanged
+// through v0.4.41 (the README's "Standard field names" line is the same; the
+// names v0.4.39 and v0.4.41 added are the version-gated aliases below).
+// Sources: src/features/checkout/README.md ("Standard field names"), the
 // checkout-form enhancer and its validation/persistence tables, the hosted
 // payment field slots (cc-number, cvv, cc-month/cc-year and their exp-*
 // spellings), payment-method, and accepts_marketing. Billing fields are the
@@ -188,7 +222,7 @@ export const SDK_CHECKOUT_FIELD_NAMES = Object.freeze([
   "exp-month",
   "exp-year",
   "cvv",
-  // Legacy spellings the README at v0.4.38 still lists.
+  // Legacy spellings the README still lists at v0.4.41.
   "card-number",
   "card-expiry",
   "card-cvv",
@@ -197,6 +231,53 @@ export const SDK_CHECKOUT_FIELD_NAMES = Object.freeze([
 
 export const SDK_CHECKOUT_FIELD_PREFIXES = Object.freeze(["billing-"]);
 
+// Field names a later SDK added, each with the first version that maps it.
+// They are the orders API's own names, which the SDK reads as another
+// spelling of its older one (src/utils/checkout-field-names.ts, SDK_NAME):
+// first_name and last_name from v0.4.39 (v0.4.40 is the same SDK), and
+// phone_number from v0.4.41, whose data-attributes reference ("Field names")
+// makes these the names to write and says fname/lname/phone still work. The
+// older names stay in SDK_CHECKOUT_FIELD_NAMES and are valid on every
+// version. A page whose SDK version is unknown is judged as an earlier SDK:
+// the older name works on every version, so asking for it is always safe,
+// and accepting the newer name there could pass a field that never reaches
+// the order. Kept in step with version_gated_aliases in
+// contracts/campaign-cart-checkout-field-contract.v0.json (a test holds the
+// two equal).
+export const SDK_CHECKOUT_FIELD_NAMES_SINCE = Object.freeze({
+  first_name: Object.freeze({ since: "0.4.39", sdk_name: "fname" }),
+  last_name: Object.freeze({ since: "0.4.39", sdk_name: "lname" }),
+  phone_number: Object.freeze({ since: "0.4.41", sdk_name: "phone" }),
+});
+
+// Whether `version` is an exact released SDK version at or after `since`.
+// "Exact released" is campaign-spec's RELEASED_SDK_VERSION_PATTERN, the one
+// doctor's campaigns.json pin check uses, so doctor and standardize agree.
+// Anything else (null, a range, a prerelease, @latest, a v prefix) is not: a
+// prerelease sorts before its release, so 0.4.39-beta.1 does not carry
+// 0.4.39's names.
+export function sdkVersionAtLeast(version, since) {
+  const have = typeof version === "string" ? RELEASED_SDK_VERSION_PATTERN.exec(version) : null;
+  const need = typeof since === "string" ? RELEASED_SDK_VERSION_PATTERN.exec(since) : null;
+  if (!have || !need) return false;
+  for (let index = 1; index <= 3; index += 1) {
+    const diff = Number(have[index]) - Number(need[index]);
+    if (diff !== 0) return diff > 0;
+  }
+  return true;
+}
+
+// The version-gated entry for a field name, billing- prefix included
+// ("billing-first_name" → first_name's entry), or null.
+export function checkoutFieldNameSince(value) {
+  let name = String(value ?? "");
+  const prefix = SDK_CHECKOUT_FIELD_PREFIXES.find((candidate) => name.startsWith(candidate));
+  if (prefix) name = name.slice(prefix.length);
+  if (!Object.hasOwn(SDK_CHECKOUT_FIELD_NAMES_SINCE, name)) return null;
+  const entry = SDK_CHECKOUT_FIELD_NAMES_SINCE[name];
+  return { name, since: entry.since, sdk_name: `${prefix || ""}${entry.sdk_name}` };
+}
+
 const exact = new Set(SDK_DATA_NEXT_ATTRIBUTES.filter((name) => !name.endsWith("-")));
 const prefixes = SDK_DATA_NEXT_ATTRIBUTES.filter((name) => name.endsWith("-"));
 
@@ -205,15 +286,20 @@ export function isIndexedSdkAttribute(name) {
   return exact.has(value) || prefixes.some((prefix) => value.startsWith(prefix) && value.length > prefix.length);
 }
 
-export function isKnownCheckoutFieldName(value) {
+// Whether the SDK maps `value`. `sdkVersion` is the page's exact SDK
+// version; without one, a version-gated name is not known (see
+// SDK_CHECKOUT_FIELD_NAMES_SINCE).
+export function isKnownCheckoutFieldName(value, sdkVersion = null) {
   const name = String(value ?? "");
-  return SDK_CHECKOUT_FIELD_NAMES.includes(name)
-    || SDK_CHECKOUT_FIELD_PREFIXES.some((prefix) => name.startsWith(prefix) && name.length > prefix.length);
+  if (SDK_CHECKOUT_FIELD_NAMES.includes(name)
+    || SDK_CHECKOUT_FIELD_PREFIXES.some((prefix) => name.startsWith(prefix) && name.length > prefix.length)) return true;
+  const gated = checkoutFieldNameSince(name);
+  return Boolean(gated) && sdkVersionAtLeast(sdkVersion, gated.since);
 }
 
 // The Campaign Cart template placeholders, for the raw cart placeholder check
 // (built_output.cart_placeholders). Generated from the SDK renderers at the
-// same tag as the attribute index above, v0.4.38:
+// v0.4.38 (line numbers are at that tag):
 //
 //   src/features/cart/cart-summary/cart-summary.renderer.ts:46-83 (bare vars)
 //   src/features/cart/cart-summary/cart-summary.line-renderer.ts:150-173,
@@ -278,6 +364,8 @@ export const SDK_TEMPLATE_PLACEHOLDERS = Object.freeze({
 });
 
 // The SDK versions whose renderer files above were verified unchanged from
-// v0.4.38 (git blob ids equal at v0.4.38, v0.4.39 and v0.4.40). A page whose
-// loader pins another version cannot pass the placeholder check.
-export const SDK_TEMPLATE_PLACEHOLDERS_VERIFIED_PINS = Object.freeze(["0.4.38", "0.4.39", "0.4.40"]);
+// v0.4.38 (git blob ids equal at v0.4.38, v0.4.39, v0.4.40 and v0.4.41, for
+// the eight renderer files cited above plus cart-item-list.enhancer.ts and
+// order-item-list.enhancer.ts). A page whose loader pins another version
+// cannot pass the placeholder check.
+export const SDK_TEMPLATE_PLACEHOLDERS_VERIFIED_PINS = Object.freeze(["0.4.38", "0.4.39", "0.4.40", "0.4.41"]);

package/src/sdk-markup.mjs

@@ -22,7 +22,12 @@
 //   WRONG_FIELD_NAME           data-next-checkout-field with a value the SDK
 //                              does not map (firstName, lastName, zip …). The
 //                              input renders, the value never reaches the
-//                              order.
+//                              order. first_name, last_name and phone_number
+//                              are judged against the page's SDK version
+//                              (SDK_CHECKOUT_FIELD_NAMES_SINCE): the page's
+//                              own exact loader pin, else the campaign's
+//                              campaigns.json sdk_version, else unknown, which
+//                              is judged as an earlier SDK.
 //   MISSING_SELECTOR_ID_MATCH  an add-to-cart button whose data-next-selector-id
 //                              names no selector on the page. The button waits
 //                              for a selection that can never arrive.
@@ -64,8 +69,13 @@
 
 import { parse } from "parse5";
 
+// cart-placeholders.mjs imports this module's template constants as well;
+// both sides read the other's bindings only inside functions, so the cycle
+// is safe at load.
+import { readLoaderPin } from "./cart-placeholders.mjs";
 import {
   SDK_ATTRIBUTE_INDEX_VERSION,
+  checkoutFieldNameSince,
   isIndexedSdkAttribute,
   isKnownCheckoutFieldName,
 } from "./sdk-attribute-index.mjs";
@@ -158,10 +168,13 @@ function describe(entry) {
 /**
  * Scan one built page. Returns findings with { code_name, code, severity,
  * page_id, file, message, detail } and the set of unknown data-next-* names.
+ * `sdk_version` is the campaign's SDK pin, used when the page carries no
+ * exact loader pin of its own.
  */
-export function scanPageMarkup({ page_id, file = null, content = "" }) {
+export function scanPageMarkup({ page_id, file = null, content = "", sdk_version = null }) {
   const document = parse(String(content || ""));
   const where = file || page_id;
+  const sdk = resolvePageSdkVersion(document, sdk_version);
   const findings = [];
   const unknown = new Set();
 
@@ -187,10 +200,8 @@ export function scanPageMarkup({ page_id, file = null, content = "" }) {
 
     if (a.has("data-next-checkout-field")) {
       const value = a.get("data-next-checkout-field") ?? "";
-      if (!isKnownCheckoutFieldName(value)) {
-        findings.push(finding("WRONG_FIELD_NAME", page_id, where,
-          `data-next-checkout-field="${value}" on ${where} is not a field name the SDK ${SDK_ATTRIBUTE_INDEX_VERSION} maps (${suggestFieldName(value)}). The input renders and the value never reaches the order.`,
-          { value, suggestion: suggestFieldName(value, true) }));
+      if (!isKnownCheckoutFieldName(value, sdk.version)) {
+        findings.push(wrongFieldName(page_id, where, value, sdk));
       }
     }
 
@@ -291,6 +302,32 @@ export function scanPageMarkup({ page_id, file = null, content = "" }) {
   return { page_id, file, findings, unknown_attributes: [...unknown].sort() };
 }
 
+// The SDK version a page runs: its own exact loader pin, else the campaign
+// pin handed in, else null (unknown).
+function resolvePageSdkVersion(document, campaignVersion) {
+  const page = readLoaderPin(document);
+  if (page) return { version: page, source: "loader" };
+  const campaign = typeof campaignVersion === "string" && campaignVersion.trim() ? campaignVersion.trim() : null;
+  if (campaign) return { version: campaign, source: "campaigns_json" };
+  return { version: null, source: null };
+}
+
+function wrongFieldName(page_id, where, value, sdk) {
+  const gated = checkoutFieldNameSince(value);
+  const versionDetail = { sdk_version: sdk.version, sdk_version_source: sdk.source };
+  if (!gated) {
+    return finding("WRONG_FIELD_NAME", page_id, where,
+      `data-next-checkout-field="${value}" on ${where} is not a field name the SDK ${SDK_ATTRIBUTE_INDEX_VERSION} maps (${suggestFieldName(value)}). The input renders and the value never reaches the order.`,
+      { value, suggestion: suggestFieldName(value, true), ...versionDetail });
+  }
+  const running = sdk.version
+    ? `this page loads SDK ${sdk.version} (${sdk.source === "loader" ? "its loader pin" : "the campaigns.json sdk_version"})`
+    : "this page's SDK version could not be read (no exact loader pin on the page and no sdk_version in campaigns.json), so it is judged as an earlier SDK";
+  return finding("WRONG_FIELD_NAME", page_id, where,
+    `data-next-checkout-field="${value}" on ${where} is a field name the SDK maps only from ${gated.since}, and ${running}. The input renders and the value never reaches the order. Use "${gated.sdk_name}", which every SDK version maps, or pin the SDK to ${gated.since} or later.`,
+    { value, suggestion: gated.sdk_name, since: gated.since, ...versionDetail });
+}
+
 function finding(codeName, page_id, file, message, detail = {}) {
   const { code, severity } = SDK_MARKUP_CODES[codeName];
   return { code_name: codeName, code, severity, page_id, file, message: `${codeName}: ${message}`, detail };
@@ -318,11 +355,13 @@ function suggestFieldName(value, bare = false) {
 /**
  * Evaluate the SDK markup family over built pages.
  *
- * @param {{ subject: object, pages: Array<{ page_id: string, file?: string|null, content: string }> }} input
+ * @param {{ subject: object, pages: Array<{ page_id: string, file?: string|null, content: string }>, sdkVersion?: string|null }} input
+ *   `sdkVersion` is the campaign's SDK pin (campaigns.json sdk_version), the
+ *   fallback for a page with no exact loader pin of its own.
  */
-export function evaluateSdkMarkup({ subject, pages = [] } = {}) {
+export function evaluateSdkMarkup({ subject, pages = [], sdkVersion = null } = {}) {
   const resolvedSubject = subject && typeof subject === "object" ? subject : {};
-  const base = { id: SDK_MARKUP, scope: SDK_MARKUP, waivable: false, subject: resolvedSubject, waiver: null, sdk_attribute_index_version: SDK_ATTRIBUTE_INDEX_VERSION };
+  const base = { id: SDK_MARKUP, scope: SDK_MARKUP, waivable: false, subject: resolvedSubject, waiver: null, sdk_attribute_index_version: SDK_ATTRIBUTE_INDEX_VERSION, campaign_sdk_version: typeof sdkVersion === "string" && sdkVersion.trim() ? sdkVersion.trim() : null };
   const list = Array.isArray(pages) ? pages : [];
 
   if (list.length === 0) {
@@ -333,7 +372,7 @@ export function evaluateSdkMarkup({ subject, pages = [] } = {}) {
   const warned = [];
   const unknown = new Map();
   for (const page of list) {
-    const scan = scanPageMarkup(page);
+    const scan = scanPageMarkup({ ...page, sdk_version: page?.sdk_version ?? sdkVersion });
     for (const item of scan.findings) (item.severity === "error" ? findings : warned).push(item);
     for (const name of scan.unknown_attributes) {
       if (!unknown.has(name)) unknown.set(name, []);