@nextcommerce/campaigns-os 1.55.0 → 1.59.0

package/campaign-spec/dist/routing.js

@@ -76,9 +76,12 @@ export const DECLINE_ROUTE_FIELD = 'on_decline';
  * is about one field's MEANING: reading a payment-shaped field on a page with
  * no payment is not respecting the author's intent, it is inventing one.
  *
- * Membership is deliberately narrow. The three-step shop family types its
- * `information` / `shipping` / `billing` pages as `checkout`, so they are
- * already covered; no certified family carries a second payment-bearing type.
+ * Membership is deliberately narrow. From CampaignSpec v5 (campaigns-os#641)
+ * `checkout` means exactly the page that takes payment; the earlier steps of a
+ * split checkout (the three-step shop family's `information` and `shipping`)
+ * are `checkout_step`, which take no payment and advance through `next_page`.
+ * A v4 spec that chained `checkout → checkout` is retyped on read
+ * (checkout-flow.ts), so the billing page alone stays payment-bearing here.
  * An `upsell` takes a one-click payment but expresses its post-purchase branch
  * through `on_accept`, which has its own applicability rule below.
  * Ratified on campaigns-os#234, 2026-08-25.

package/campaign-spec/dist/rules/checkout-forward-target.d.ts

@@ -0,0 +1,17 @@
+/**
+ * CheckoutForwardTarget — a Checkout takes payment, so where it sends the
+ * shopper next must be a post-payment page: an upsell, a downsell or a
+ * thank-you page (campaigns-os#641).
+ *
+ * A `checkout` forwarding to another checkout-shaped page, a landing page or a
+ * select page means one of two things, both wrong: the page is really a step
+ * that collects details and moves on (type it `checkout_step`), or the order
+ * would be placed before the shopper reaches the page meant to take payment.
+ *
+ * Only a target this funnel resolves is judged. An off-graph destination (a
+ * rooted path into an existing downstream campaign, an absolute URL) is the
+ * partial-scope shape and passes; an unresolved typo is RouteTargetResolves';
+ * a Checkout with no forward route at all is CheckoutHasSuccessUrl's.
+ */
+import type { Rule } from '../types.ts';
+export declare const CheckoutForwardTarget: Rule;

package/campaign-spec/dist/rules/checkout-forward-target.js

@@ -0,0 +1,48 @@
+/**
+ * CheckoutForwardTarget — a Checkout takes payment, so where it sends the
+ * shopper next must be a post-payment page: an upsell, a downsell or a
+ * thank-you page (campaigns-os#641).
+ *
+ * A `checkout` forwarding to another checkout-shaped page, a landing page or a
+ * select page means one of two things, both wrong: the page is really a step
+ * that collects details and moves on (type it `checkout_step`), or the order
+ * would be placed before the shopper reaches the page meant to take payment.
+ *
+ * Only a target this funnel resolves is judged. An off-graph destination (a
+ * rooted path into an existing downstream campaign, an absolute URL) is the
+ * partial-scope shape and passes; an unresolved typo is RouteTargetResolves';
+ * a Checkout with no forward route at all is CheckoutHasSuccessUrl's.
+ */
+import { forwardRouteTarget } from "../routing.js";
+import { POST_PAYMENT_PAGE_TYPES, forwardTargetPage, isPaymentPage } from "../checkout-flow.js";
+export const CheckoutForwardTarget = {
+    id: 'CheckoutForwardTarget',
+    severity: 'error',
+    tags: ['fast', 'structure', 'spec-only'],
+    check(spec) {
+        const violations = [];
+        spec.funnels.forEach((funnel, funnelIdx) => {
+            const pages = funnel.pages ?? [];
+            pages.forEach((page, pageIdx) => {
+                if (!isPaymentPage(page))
+                    return;
+                const target = forwardTargetPage(pages, page);
+                if (!target)
+                    return;
+                const targetType = typeof target.type === 'string' ? target.type : '';
+                if (POST_PAYMENT_PAGE_TYPES.includes(targetType))
+                    return;
+                violations.push({
+                    ruleId: 'CheckoutForwardTarget',
+                    severity: 'error',
+                    message: `Checkout "${page.id}" forwards to "${target.id}" (type "${targetType || 'none'}"). ` +
+                        'A Checkout takes payment, so it must forward to an upsell, downsell or thank-you page. ' +
+                        'If this page collects details and moves on without placing an order, type it "checkout_step".',
+                    path: `/funnels/${funnelIdx}/pages/${pageIdx}`,
+                    data: { pageId: page.id, target: forwardRouteTarget(page), targetPageId: target.id, targetType },
+                });
+            });
+        });
+        return violations;
+    },
+};

package/campaign-spec/dist/rules/checkout-step-reaches-checkout.d.ts

@@ -0,0 +1,12 @@
+/**
+ * CheckoutStepReachesCheckout — every `checkout_step` page must lie on a path
+ * to a Checkout. Following its forward links has to arrive at a `checkout`
+ * page; a step that dead-ends, loops, leaves the funnel or reaches an offer
+ * first collects the shopper's details and never takes payment
+ * (campaigns-os#641).
+ *
+ * Forward links only: a step has no decline branch that could carry the
+ * shopper to payment instead.
+ */
+import type { Rule } from '../types.ts';
+export declare const CheckoutStepReachesCheckout: Rule;

package/campaign-spec/dist/rules/checkout-step-reaches-checkout.js

@@ -0,0 +1,37 @@
+/**
+ * CheckoutStepReachesCheckout — every `checkout_step` page must lie on a path
+ * to a Checkout. Following its forward links has to arrive at a `checkout`
+ * page; a step that dead-ends, loops, leaves the funnel or reaches an offer
+ * first collects the shopper's details and never takes payment
+ * (campaigns-os#641).
+ *
+ * Forward links only: a step has no decline branch that could carry the
+ * shopper to payment instead.
+ */
+import { isCheckoutStepPage, paymentPageFrom } from "../checkout-flow.js";
+export const CheckoutStepReachesCheckout = {
+    id: 'CheckoutStepReachesCheckout',
+    severity: 'error',
+    tags: ['structure', 'spec-only'],
+    check(spec) {
+        const violations = [];
+        spec.funnels.forEach((funnel, funnelIdx) => {
+            const pages = funnel.pages ?? [];
+            pages.forEach((page, pageIdx) => {
+                if (!isCheckoutStepPage(page))
+                    return;
+                if (paymentPageFrom(pages, page))
+                    return;
+                violations.push({
+                    ruleId: 'CheckoutStepReachesCheckout',
+                    severity: 'error',
+                    message: `Checkout step "${page.id}" is not on a path to a Checkout. ` +
+                        'Follow its next_page links to the page that takes payment (type "checkout").',
+                    path: `/funnels/${funnelIdx}/pages/${pageIdx}`,
+                    data: { pageId: page.id },
+                });
+            });
+        });
+        return violations;
+    },
+};

package/campaign-spec/dist/rules/exit-intent-validation.js

@@ -19,6 +19,7 @@
  *
  * Message text inherited verbatim from the pre-#110 validator at migration time.
  */
+import { isCheckoutFlowPage } from "../checkout-flow.js";
 function isTruthyString(value) {
     return typeof value === 'string' && value.trim().length > 0;
 }
@@ -55,7 +56,7 @@ export const ExitIntentValidation = {
                 const refOffer = ref ? index.byRefId.get(String(ref)) : null;
                 const codeOffer = code ? index.byCode.get(String(code).toUpperCase()) : null;
                 // 1. Placement
-                if (page.type !== 'checkout') {
+                if (!isCheckoutFlowPage(page)) {
                     violations.push({
                         ruleId: 'ExitIntentValidation',
                         severity: 'warning',

package/campaign-spec/dist/rules/index.d.ts

@@ -31,6 +31,10 @@ export { UpsellHasPackages } from './upsell-has-packages.ts';
 export { UpsellRoutingComplete } from './upsell-routing-complete.ts';
 export { RouteFieldIgnoredForPageType } from './route-field-ignored-for-page-type.ts';
 export { CheckoutHasSuccessUrl } from './checkout-has-success-url.ts';
+export { CheckoutForwardTarget } from './checkout-forward-target.ts';
+export { PrePaymentForwardTarget } from './pre-payment-forward-target.ts';
+export { CheckoutStepReachesCheckout } from './checkout-step-reaches-checkout.ts';
+export { OneCheckoutPerPath } from './one-checkout-per-path.ts';
 export { UpsellWithoutCheckout } from './upsell-without-checkout.ts';
 export { DownsellWithoutUpsell } from './downsell-without-upsell.ts';
 export { PackagePricingSanity } from './package-pricing-sanity.ts';

package/campaign-spec/dist/rules/index.js

@@ -30,6 +30,10 @@ import { UpsellRoutingComplete } from "./upsell-routing-complete.js";
 import { RouteTargetResolves } from "./route-target-resolves.js";
 import { RouteFieldIgnoredForPageType } from "./route-field-ignored-for-page-type.js";
 import { CheckoutHasSuccessUrl } from "./checkout-has-success-url.js";
+import { CheckoutForwardTarget } from "./checkout-forward-target.js";
+import { PrePaymentForwardTarget } from "./pre-payment-forward-target.js";
+import { CheckoutStepReachesCheckout } from "./checkout-step-reaches-checkout.js";
+import { OneCheckoutPerPath } from "./one-checkout-per-path.js";
 import { UpsellWithoutCheckout } from "./upsell-without-checkout.js";
 import { DownsellWithoutUpsell } from "./downsell-without-upsell.js";
 import { CampaignMetadata } from "./campaign-metadata.js";
@@ -61,6 +65,10 @@ export { UpsellHasPackages } from "./upsell-has-packages.js";
 export { UpsellRoutingComplete } from "./upsell-routing-complete.js";
 export { RouteFieldIgnoredForPageType } from "./route-field-ignored-for-page-type.js";
 export { CheckoutHasSuccessUrl } from "./checkout-has-success-url.js";
+export { CheckoutForwardTarget } from "./checkout-forward-target.js";
+export { PrePaymentForwardTarget } from "./pre-payment-forward-target.js";
+export { CheckoutStepReachesCheckout } from "./checkout-step-reaches-checkout.js";
+export { OneCheckoutPerPath } from "./one-checkout-per-path.js";
 export { UpsellWithoutCheckout } from "./upsell-without-checkout.js";
 export { DownsellWithoutUpsell } from "./downsell-without-upsell.js";
 export { PackagePricingSanity } from "./package-pricing-sanity.js";
@@ -102,6 +110,10 @@ export const allRules = [
     RouteTargetResolves,
     RouteFieldIgnoredForPageType,
     CheckoutHasSuccessUrl,
+    CheckoutForwardTarget,
+    PrePaymentForwardTarget,
+    CheckoutStepReachesCheckout,
+    OneCheckoutPerPath,
     UpsellWithoutCheckout,
     DownsellWithoutUpsell,
     PackagePricingSanity,

package/campaign-spec/dist/rules/one-checkout-per-path.d.ts

@@ -0,0 +1,25 @@
+/**
+ * OneCheckoutPerPath — every path from an entry page to an upsell or downsell
+ * passes exactly one Checkout (campaigns-os#641).
+ *
+ * None means the shopper reaches a post-purchase offer with no order placed;
+ * two means the path takes payment twice. A campaign may hold several
+ * Checkouts — split-test paths each reach their own — so the rule counts per
+ * path, never per spec.
+ *
+ * Paths follow both edges a page can traverse (forward and decline, from
+ * routing.ts) and start at the funnel's entry pages (checkout-flow.ts
+ * `entryPages`): pages flagged `is_entry`, else those nothing routes to. No
+ * page order or name is consulted. The search runs, per entry page, over
+ * (page, checkouts passed so far: 0, 1, 2+) states, so each bad page is
+ * reported once per entry and count however many of that entry's paths reach it.
+ *
+ * A spec with no Checkout anywhere is left to UpsellWithoutCheckout, so the
+ * two never report one defect twice.
+ *
+ * With build_scope.mode === 'partial' a path that reaches an offer with no
+ * Checkout is a warning, as in UpsellWithoutCheckout: a partial upsell build
+ * may ship an offer an existing checkout elsewhere routes into.
+ */
+import type { Rule } from '../types.ts';
+export declare const OneCheckoutPerPath: Rule;

package/campaign-spec/dist/rules/one-checkout-per-path.js

@@ -0,0 +1,84 @@
+/**
+ * OneCheckoutPerPath — every path from an entry page to an upsell or downsell
+ * passes exactly one Checkout (campaigns-os#641).
+ *
+ * None means the shopper reaches a post-purchase offer with no order placed;
+ * two means the path takes payment twice. A campaign may hold several
+ * Checkouts — split-test paths each reach their own — so the rule counts per
+ * path, never per spec.
+ *
+ * Paths follow both edges a page can traverse (forward and decline, from
+ * routing.ts) and start at the funnel's entry pages (checkout-flow.ts
+ * `entryPages`): pages flagged `is_entry`, else those nothing routes to. No
+ * page order or name is consulted. The search runs, per entry page, over
+ * (page, checkouts passed so far: 0, 1, 2+) states, so each bad page is
+ * reported once per entry and count however many of that entry's paths reach it.
+ *
+ * A spec with no Checkout anywhere is left to UpsellWithoutCheckout, so the
+ * two never report one defect twice.
+ *
+ * With build_scope.mode === 'partial' a path that reaches an offer with no
+ * Checkout is a warning, as in UpsellWithoutCheckout: a partial upsell build
+ * may ship an offer an existing checkout elsewhere routes into.
+ */
+import { outgoingEdgeIds } from "../routing.js";
+import { POST_PURCHASE_OFFER_PAGE_TYPES, entryPages, isPaymentPage, resolveRouteTargetPage } from "../checkout-flow.js";
+function isOffer(page) {
+    const type = typeof page.type === 'string' ? page.type.trim().toLowerCase() : '';
+    return POST_PURCHASE_OFFER_PAGE_TYPES.includes(type);
+}
+export const OneCheckoutPerPath = {
+    id: 'OneCheckoutPerPath',
+    severity: 'error',
+    tags: ['structure', 'spec-only'],
+    check(spec) {
+        const violations = [];
+        const partial = spec.build_scope?.mode === 'partial';
+        // A spec with no Checkout at all is UpsellWithoutCheckout's to report; this
+        // rule speaks only when Checkouts exist and some path misses or doubles one.
+        const anyCheckout = spec.funnels.some((funnel) => (funnel.pages ?? []).some((page) => isPaymentPage(page)));
+        spec.funnels.forEach((funnel, funnelIdx) => {
+            const pages = (funnel.pages ?? []).filter((page) => page && page.enabled !== false);
+            const indexOf = new Map();
+            (funnel.pages ?? []).forEach((page, idx) => indexOf.set(page, idx));
+            // Searched once per entry page, so every entry whose path misses or
+            // doubles the Checkout is named, not only the first one to reach the page.
+            for (const entry of entryPages(funnel)) {
+                const seen = new Set();
+                const reported = new Set();
+                const stack = [[entry, 0]];
+                while (stack.length) {
+                    const [page, before] = stack.pop();
+                    const passed = Math.min(before + (isPaymentPage(page) ? 1 : 0), 2);
+                    const key = `${indexOf.get(page)}:${passed}`;
+                    if (seen.has(key))
+                        continue;
+                    seen.add(key);
+                    if (isOffer(page) && passed !== 1 && (passed > 1 || anyCheckout)) {
+                        const reportKey = `${indexOf.get(page)}:${passed === 0 ? 0 : 2}`;
+                        if (!reported.has(reportKey)) {
+                            reported.add(reportKey);
+                            const none = passed === 0;
+                            violations.push({
+                                ruleId: 'OneCheckoutPerPath',
+                                severity: none && partial ? 'warning' : 'error',
+                                message: none
+                                    ? `A path from entry page "${entry.id}" reaches "${page.id}" (${page.type}) without passing a Checkout, so no order has been placed.` +
+                                        (partial ? ' Valid for partial upsell builds when an existing checkout routes into this page.' : '')
+                                    : `A path from entry page "${entry.id}" reaches "${page.id}" (${page.type}) after passing more than one Checkout, so it takes payment twice.`,
+                                path: `/funnels/${funnelIdx}/pages/${indexOf.get(page)}`,
+                                data: { pageId: page.id, entryPageId: entry.id, checkoutsPassed: none ? 0 : 2, isPartialScope: partial },
+                            });
+                        }
+                    }
+                    for (const target of outgoingEdgeIds(page)) {
+                        const next = resolveRouteTargetPage(pages, target);
+                        if (next)
+                            stack.push([next, passed]);
+                    }
+                }
+            }
+        });
+        return violations;
+    },
+};

package/campaign-spec/dist/rules/pre-payment-forward-target.d.ts

@@ -0,0 +1,12 @@
+/**
+ * PrePaymentForwardTarget — a `select` or `checkout_step` page takes no
+ * payment, so it must not forward straight to a post-payment page (an upsell,
+ * a downsell or a thank-you page). Doing so skips the Checkout: the shopper
+ * reaches an offer or a receipt with no order placed (campaigns-os#641).
+ *
+ * Only the resolved forward link is judged — routing.ts already ignores a
+ * `success_url` or `on_accept` on these types, and RouteFieldIgnoredForPageType
+ * warns about those separately.
+ */
+import type { Rule } from '../types.ts';
+export declare const PrePaymentForwardTarget: Rule;

package/campaign-spec/dist/rules/pre-payment-forward-target.js

@@ -0,0 +1,42 @@
+/**
+ * PrePaymentForwardTarget — a `select` or `checkout_step` page takes no
+ * payment, so it must not forward straight to a post-payment page (an upsell,
+ * a downsell or a thank-you page). Doing so skips the Checkout: the shopper
+ * reaches an offer or a receipt with no order placed (campaigns-os#641).
+ *
+ * Only the resolved forward link is judged — routing.ts already ignores a
+ * `success_url` or `on_accept` on these types, and RouteFieldIgnoredForPageType
+ * warns about those separately.
+ */
+import { forwardRouteTarget } from "../routing.js";
+import { POST_PAYMENT_PAGE_TYPES, forwardTargetPage, isPrePaymentPage } from "../checkout-flow.js";
+export const PrePaymentForwardTarget = {
+    id: 'PrePaymentForwardTarget',
+    severity: 'error',
+    tags: ['fast', 'structure', 'spec-only'],
+    check(spec) {
+        const violations = [];
+        spec.funnels.forEach((funnel, funnelIdx) => {
+            const pages = funnel.pages ?? [];
+            pages.forEach((page, pageIdx) => {
+                if (!isPrePaymentPage(page))
+                    return;
+                const target = forwardTargetPage(pages, page);
+                if (!target)
+                    return;
+                const targetType = typeof target.type === 'string' ? target.type : '';
+                if (!POST_PAYMENT_PAGE_TYPES.includes(targetType))
+                    return;
+                violations.push({
+                    ruleId: 'PrePaymentForwardTarget',
+                    severity: 'error',
+                    message: `"${page.type}" page "${page.id}" forwards to "${target.id}" (type "${targetType}") without passing a Checkout. ` +
+                        'Route it (via next_page) to the next checkout step or to the Checkout that takes payment.',
+                    path: `/funnels/${funnelIdx}/pages/${pageIdx}/next_page`,
+                    data: { pageId: page.id, pageType: page.type, target: forwardRouteTarget(page), targetPageId: target.id, targetType },
+                });
+            });
+        });
+        return violations;
+    },
+};

package/campaign-spec/dist/rules/promo-code-input-validation.js

@@ -4,6 +4,7 @@
  * intent because both surfaces apply a voucher/code-backed Offer through the
  * same Campaign Cart SDK/Campaigns API pricing path.
  */
+import { isCheckoutFlowPage } from "../checkout-flow.js";
 function isTruthyString(value) {
     return typeof value === 'string' && value.trim().length > 0;
 }
@@ -39,7 +40,7 @@ export const PromoCodeInputValidation = {
                 const code = promo.offer_code;
                 const refOffer = ref ? index.byRefId.get(String(ref)) : null;
                 const codeOffer = code ? index.byCode.get(String(code).toUpperCase()) : null;
-                if (page.type !== 'checkout') {
+                if (!isCheckoutFlowPage(page)) {
                     violations.push({
                         ruleId: 'PromoCodeInputValidation',
                         severity: 'warning',

package/campaign-spec/dist/rules/schema-version.d.ts

@@ -9,13 +9,18 @@
  * lineage errors here at authoring/export time instead of surfacing as
  * downstream shape drift.
  *
- * SUPPORTED_SCHEMA_VERSIONS must stay identical to the schema_version enum in
- * schemas/campaign-spec.v4.schema.json (and compatibility.json's campaign_spec
- * range). The rule stays pure (no filesystem), so the constant duplicates the
+ * SUPPORTED_SCHEMA_VERSIONS must stay identical to the schema_version enums of
+ * schemas/campaign-spec.v4.schema.json and schemas/campaign-spec.v5.schema.json,
+ * concatenated (and compatibility.json's campaign_spec range). The rule stays pure (no filesystem), so the constant duplicates the
  * schema enum — the sync test in ../test/rules/schema-version.test.ts is the
  * drift gate, following the UnknownTopLevelFields pattern.
  */
 import type { Rule } from '../types.ts';
-/** Supported CampaignSpec lineage versions — keep in sync with the v4 JSON Schema enum. */
+/**
+ * Supported CampaignSpec lineage versions — the v4 JSON Schema enum followed by
+ * the v5 one, in that order. A 4.2/4.3 spec is upgraded to v5 on read
+ * (checkout-flow.ts), so this rule sees `5.0` for it after normalize(); the v4
+ * entries stay so a caller running the rule on an un-normalized spec agrees.
+ */
 export declare const SUPPORTED_SCHEMA_VERSIONS: readonly string[];
 export declare const SchemaVersion: Rule;

package/campaign-spec/dist/rules/schema-version.js

@@ -9,14 +9,19 @@
  * lineage errors here at authoring/export time instead of surfacing as
  * downstream shape drift.
  *
- * SUPPORTED_SCHEMA_VERSIONS must stay identical to the schema_version enum in
- * schemas/campaign-spec.v4.schema.json (and compatibility.json's campaign_spec
- * range). The rule stays pure (no filesystem), so the constant duplicates the
+ * SUPPORTED_SCHEMA_VERSIONS must stay identical to the schema_version enums of
+ * schemas/campaign-spec.v4.schema.json and schemas/campaign-spec.v5.schema.json,
+ * concatenated (and compatibility.json's campaign_spec range). The rule stays pure (no filesystem), so the constant duplicates the
  * schema enum — the sync test in ../test/rules/schema-version.test.ts is the
  * drift gate, following the UnknownTopLevelFields pattern.
  */
-/** Supported CampaignSpec lineage versions — keep in sync with the v4 JSON Schema enum. */
-export const SUPPORTED_SCHEMA_VERSIONS = Object.freeze(['4.2', '4.3']);
+/**
+ * Supported CampaignSpec lineage versions — the v4 JSON Schema enum followed by
+ * the v5 one, in that order. A 4.2/4.3 spec is upgraded to v5 on read
+ * (checkout-flow.ts), so this rule sees `5.0` for it after normalize(); the v4
+ * entries stay so a caller running the rule on an un-normalized spec agrees.
+ */
+export const SUPPORTED_SCHEMA_VERSIONS = Object.freeze(['4.2', '4.3', '5.0']);
 export const SchemaVersion = {
     id: 'SchemaVersion',
     severity: 'error',

package/campaign-spec/dist/types.d.ts

@@ -2,8 +2,9 @@
  * Type surface for the CampaignSpec contract layer.
  *
  * The CampaignSpec is the central authoring contract of this repo (see
- * ../CONTEXT.md). v4.3 is the authoring shape; v4.2 funnels[] is the canonical
- * internal shape that rules operate on (after normalize()).
+ * ../CONTEXT.md). v5.0 is the authoring shape; funnels[] is the canonical
+ * internal shape that rules operate on (after normalize(), which upgrades a
+ * v4.2/v4.3 spec to the v5 page vocabulary — see checkout-flow.ts).
  *
  * Types here are intentionally permissive on optional fields — the rule
  * registry catches missing/malformed fields, rather than the type system
@@ -63,7 +64,23 @@ export type PageType = 'presell' | 'landing'
  * Not to be confused with the page ID "select", which several family
  * contracts use for this page and which is a separate namespace.
  */
- | 'select' | 'checkout' | 'upsell' | 'downsell' | 'thankyou';
+ | 'select'
+/**
+ * A page with a checkout form that collects details and moves on without
+ * placing an order: the information and shipping steps of a split checkout
+ * (campaigns-os#641). Routes forward through `next_page`; it takes no
+ * payment, so `success_url` and `on_accept` are ignored here as on `select`.
+ * Renders as SDK page type `checkout`; its form carries
+ * `data-next-checkout-step` and `data-next-step-number`.
+ */
+ | 'checkout_step'
+/**
+ * The page that takes payment. Exactly one on every path from an entry page
+ * to an upsell. Routes forward through `success_url` (or `next_page`) to an
+ * upsell, downsell or thank-you page. A campaign may hold several, one per
+ * path.
+ */
+ | 'checkout' | 'upsell' | 'downsell' | 'thankyou';
 /**
  * Offer condition/benefit blocks, as exported by the Map Builder. Both share
  * the { type, value, description } shape (e.g. condition

package/campaign-spec/dist/types.js

@@ -2,8 +2,9 @@
  * Type surface for the CampaignSpec contract layer.
  *
  * The CampaignSpec is the central authoring contract of this repo (see
- * ../CONTEXT.md). v4.3 is the authoring shape; v4.2 funnels[] is the canonical
- * internal shape that rules operate on (after normalize()).
+ * ../CONTEXT.md). v5.0 is the authoring shape; funnels[] is the canonical
+ * internal shape that rules operate on (after normalize(), which upgrades a
+ * v4.2/v4.3 spec to the v5 page vocabulary — see checkout-flow.ts).
  *
  * Types here are intentionally permissive on optional fields — the rule
  * registry catches missing/malformed fields, rather than the type system

package/compatibility.json

@@ -1,9 +1,9 @@
 {
   "package": "@nextcommerce/campaigns-os",
-  "version": "1.55.0",
+  "version": "1.59.0",
   "status": "developer-preview",
   "contracts": {
-    "campaign_spec": "4.2-4.3",
+    "campaign_spec": "4.2-5.0",
     "build_packet": "campaign-runtime-build-packet/v0",
     "build_context": "campaign-runtime-build-context/v0",
     "assembly_report": "campaign-runtime-assembly-report/v0",

package/contracts/campaign-cart-sdk-support-policy.v0.json

@@ -2,8 +2,8 @@
   "schema_version": "campaign-cart-sdk-support-policy/v0",
   "provenance": {
     "source": "NextCommerceCo/campaign-cart release tags",
-    "latest_known_release": "0.4.41",
-    "captured_at": "2026-10-07"
+    "latest_known_release": "0.4.42",
+    "captured_at": "2026-10-09"
   },
   "source": "contracts/campaign-cart-sdk-support-policy.v0.json",
   "minimum_supported": "0.4.20",

package/contracts/commerce-surface-catalog.json

@@ -848,9 +848,9 @@
         }
       },
       "verification": {
-        "sdk_version": "0.4.41",
-        "verified_at": "2026-10-06T23:03:41Z",
-        "evidence": "sdk-0.4.41-2026-10-06.5",
+        "sdk_version": "0.4.42",
+        "verified_at": "2026-10-09T01:35:51Z",
+        "evidence": "sdk-0.4.42-2026-10-09",
         "status": "certified",
         "source": "template-verification.json"
       }
@@ -1272,9 +1272,9 @@
         }
       },
       "verification": {
-        "sdk_version": "0.4.41",
-        "verified_at": "2026-10-06T23:03:41Z",
-        "evidence": "sdk-0.4.41-2026-10-06.5",
+        "sdk_version": "0.4.42",
+        "verified_at": "2026-10-09T01:35:51Z",
+        "evidence": "sdk-0.4.42-2026-10-09",
         "status": "certified",
         "source": "template-verification.json"
       }
@@ -1583,9 +1583,9 @@
         }
       },
       "verification": {
-        "sdk_version": "0.4.41",
-        "verified_at": "2026-10-06T23:03:41Z",
-        "evidence": "sdk-0.4.41-2026-10-06.5",
+        "sdk_version": "0.4.42",
+        "verified_at": "2026-10-09T01:35:51Z",
+        "evidence": "sdk-0.4.42-2026-10-09",
         "status": "certified",
         "source": "template-verification.json"
       }
@@ -1886,9 +1886,9 @@
         }
       },
       "verification": {
-        "sdk_version": "0.4.41",
-        "verified_at": "2026-10-06T23:03:41Z",
-        "evidence": "sdk-0.4.41-2026-10-06.5",
+        "sdk_version": "0.4.42",
+        "verified_at": "2026-10-09T01:35:51Z",
+        "evidence": "sdk-0.4.42-2026-10-09",
         "status": "certified",
         "source": "template-verification.json"
       }
@@ -2227,9 +2227,9 @@
         }
       },
       "verification": {
-        "sdk_version": "0.4.41",
-        "verified_at": "2026-10-06T23:03:41Z",
-        "evidence": "sdk-0.4.41-2026-10-06.5",
+        "sdk_version": "0.4.42",
+        "verified_at": "2026-10-09T01:35:51Z",
+        "evidence": "sdk-0.4.42-2026-10-09",
         "status": "certified",
         "source": "template-verification.json"
       }
@@ -2666,9 +2666,9 @@
         }
       },
       "verification": {
-        "sdk_version": "0.4.41",
-        "verified_at": "2026-10-06T23:03:41Z",
-        "evidence": "sdk-0.4.41-2026-10-06.5",
+        "sdk_version": "0.4.42",
+        "verified_at": "2026-10-09T01:35:51Z",
+        "evidence": "sdk-0.4.42-2026-10-09",
         "status": "certified",
         "source": "template-verification.json"
       }
@@ -2686,7 +2686,6 @@
       ],
       "canonicalSurfaces": {
         "selectStep": "mv-selection-step",
-        "checkoutSelector": "mv-selected-bundle-review",
         "variantSlots": "bundle-slot-selector",
         "personalization": "per-slot picker (data-next-property per slot, toggled by slot_personalization); order-wide default via personalization-field (ships unwired)",
         "orderSummary": "cart-summary03|cart-summary04",
@@ -3023,9 +3022,9 @@
         }
       },
       "verification": {
-        "sdk_version": "0.4.41",
-        "verified_at": "2026-10-06T23:03:41Z",
-        "evidence": "sdk-0.4.41-2026-10-06.5",
+        "sdk_version": "0.4.42",
+        "verified_at": "2026-10-09T01:35:51Z",
+        "evidence": "sdk-0.4.42-2026-10-09",
         "status": "certified",
         "source": "template-verification.json"
       }
@@ -3313,9 +3312,9 @@
         }
       },
       "verification": {
-        "sdk_version": "0.4.41",
-        "verified_at": "2026-10-06T23:03:41Z",
-        "evidence": "sdk-0.4.41-2026-10-06.5",
+        "sdk_version": "0.4.42",
+        "verified_at": "2026-10-09T01:35:51Z",
+        "evidence": "sdk-0.4.42-2026-10-09",
         "status": "certified",
         "source": "template-verification.json"
       }
@@ -3504,6 +3503,6 @@
     }
   },
   "_synced_from_repo": "NextCommerceCo/campaign-cart-starter-templates",
-  "_synced_from_ref": "783329017c6994a94d11e46580c33bd052aabdb0",
-  "_synced_from_sha": "783329017c6994a94d11e46580c33bd052aabdb0"
+  "_synced_from_ref": "main",
+  "_synced_from_sha": "d5ff501ab57aef160a7108341de8a952006a28a4"
 }