@nextcommerce/campaigns-os 1.60.0 → 1.62.0

package/campaign-spec/dist/rules/checkout-path-has-packages.js

@@ -0,0 +1,79 @@
+/**
+ * CheckoutPathHasPackages — every path from an entry page to a Checkout passes
+ * at least one page that sells a main-cart package (campaigns-os#711, #206).
+ *
+ * A Checkout the shopper reaches with nothing in the cart cannot take an
+ * order, and until this rule nothing said so before a test order failed. The
+ * selling page may be any page on the path up to and including the Checkout:
+ * a select page's bundle picker, a landing page's package cards, a checkout
+ * step, or the Checkout's own selector. So the rule counts per path, never per
+ * page: a Checkout with no packages of its own passes when every path into it
+ * sells first.
+ *
+ * "Main-cart package" is the ratified #206 contract (checkout-flow.ts
+ * `isMainCartPackage`, docs/template-family-contracts.md "Main-cart entry"):
+ * an entry with neither `is_upsell: true` nor `is_order_bump: true`. Bump rows
+ * alone sell nothing, `default_selected` never changes the role, and entries
+ * on upsell, downsell or thank-you pages never count.
+ *
+ * Paths are walked the way OneCheckoutPerPath walks them: both edges a page
+ * can traverse (routing.ts), starting at the funnel's entry pages
+ * (checkout-flow.ts `entryPages`). No page order or name is consulted. The
+ * search runs, per entry page, over (page, sold yet) states and stops at the
+ * first Checkout, so each empty Checkout is reported once per entry however
+ * many of that entry's paths reach it. A second Checkout on one path is
+ * OneCheckoutPerPath's to report.
+ *
+ * With build_scope.mode === 'partial' the finding is a warning: a partial
+ * build may ship a Checkout that a page outside the build fills.
+ */
+import { outgoingEdgeIds } from "../routing.js";
+import { entryPages, isPaymentPage, resolveRouteTargetPage, sellsMainCartPackage } from "../checkout-flow.js";
+export const CheckoutPathHasPackages = {
+    id: 'CheckoutPathHasPackages',
+    severity: 'error',
+    tags: ['structure', 'spec-only'],
+    check(spec) {
+        const violations = [];
+        const partial = spec.build_scope?.mode === 'partial';
+        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));
+            for (const entry of entryPages(funnel)) {
+                const seen = new Set();
+                const reported = new Set();
+                const stack = [[entry, false]];
+                while (stack.length) {
+                    const [page, before] = stack.pop();
+                    const sold = before || sellsMainCartPackage(page);
+                    const key = `${indexOf.get(page)}:${sold}`;
+                    if (seen.has(key))
+                        continue;
+                    seen.add(key);
+                    if (isPaymentPage(page)) {
+                        if (!sold && !reported.has(page)) {
+                            reported.add(page);
+                            violations.push({
+                                ruleId: 'CheckoutPathHasPackages',
+                                severity: partial ? 'warning' : 'error',
+                                message: `A path from entry page "${entry.id}" reaches Checkout "${page.id}" without passing a page that sells a main-cart package, so the cart is empty and no order can be placed. ` +
+                                    'Add a package entry not marked is_upsell or is_order_bump to the Checkout or a page before it on this path.' +
+                                    (partial ? ' Valid for partial builds when a page outside this build fills the cart.' : ''),
+                                path: `/funnels/${funnelIdx}/pages/${indexOf.get(page)}`,
+                                data: { pageId: page.id, entryPageId: entry.id, isPartialScope: partial },
+                            });
+                        }
+                        continue;
+                    }
+                    for (const target of outgoingEdgeIds(page)) {
+                        const next = resolveRouteTargetPage(pages, target);
+                        if (next)
+                            stack.push([next, sold]);
+                    }
+                }
+            }
+        });
+        return violations;
+    },
+};

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

@@ -35,11 +35,13 @@ 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 { CheckoutPathHasPackages } from './checkout-path-has-packages.ts';
 export { UpsellWithoutCheckout } from './upsell-without-checkout.ts';
 export { DownsellWithoutUpsell } from './downsell-without-upsell.ts';
 export { PackagePricingSanity } from './package-pricing-sanity.ts';
 export { ShippingMethodsPresent } from './shipping-methods-present.ts';
 export { ShippingCountriesShape } from './shipping-countries-shape.ts';
+export { CampaignCurrencies } from './campaign-currencies.ts';
 export { OfferRefIntegrity } from './offer-ref-integrity.ts';
 export { ExitIntentValidation } from './exit-intent-validation.ts';
 export { PromoCodeInputValidation } from './promo-code-input-validation.ts';

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

@@ -34,11 +34,13 @@ 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 { CheckoutPathHasPackages } from "./checkout-path-has-packages.js";
 import { UpsellWithoutCheckout } from "./upsell-without-checkout.js";
 import { DownsellWithoutUpsell } from "./downsell-without-upsell.js";
 import { CampaignMetadata } from "./campaign-metadata.js";
 import { ShippingMethodsPresent } from "./shipping-methods-present.js";
 import { ShippingCountriesShape } from "./shipping-countries-shape.js";
+import { CampaignCurrencies } from "./campaign-currencies.js";
 import { PackagePricingSanity } from "./package-pricing-sanity.js";
 import { OfferRefIntegrity } from "./offer-ref-integrity.js";
 import { ExitIntentValidation } from "./exit-intent-validation.js";
@@ -69,11 +71,13 @@ 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 { CheckoutPathHasPackages } from "./checkout-path-has-packages.js";
 export { UpsellWithoutCheckout } from "./upsell-without-checkout.js";
 export { DownsellWithoutUpsell } from "./downsell-without-upsell.js";
 export { PackagePricingSanity } from "./package-pricing-sanity.js";
 export { ShippingMethodsPresent } from "./shipping-methods-present.js";
 export { ShippingCountriesShape } from "./shipping-countries-shape.js";
+export { CampaignCurrencies } from "./campaign-currencies.js";
 export { OfferRefIntegrity } from "./offer-ref-integrity.js";
 export { ExitIntentValidation } from "./exit-intent-validation.js";
 export { PromoCodeInputValidation } from "./promo-code-input-validation.js";
@@ -114,11 +118,13 @@ export const allRules = [
     PrePaymentForwardTarget,
     CheckoutStepReachesCheckout,
     OneCheckoutPerPath,
+    CheckoutPathHasPackages,
     UpsellWithoutCheckout,
     DownsellWithoutUpsell,
     PackagePricingSanity,
     ShippingMethodsPresent,
     ShippingCountriesShape,
+    CampaignCurrencies,
     OfferRefIntegrity,
     ExitIntentValidation,
     PromoCodeInputValidation,

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

@@ -519,12 +519,17 @@ export interface Campaign {
  *
  * Modeled on real production-funnel usage, NOT the idealized "SDK fires the
  * canonical dl_* set" view. The field reality the block must express:
- *   - Events fire from three sources: SDK auto, SDK-blocked-then-manual
- *     (`blockedEvents` suppresses the SDK event, a side script re-fires it via
- *     raw fbq/gtag to control timing), and fully out-of-band pixels loaded via
- *     GTM (Everflow / TriplePixel / Northbeam / RudderStack) that never touch
- *     the dataLayer. So outbound pixel fires — not dataLayer events — are the
- *     QA source of truth.
+ *   - Events reach vendors four ways: SDK providers (`providers`: GTM, Meta,
+ *     RudderStack, a custom endpoint, configured through config.js);
+ *     SDK-blocked-then-manual (`blockedEvents` suppresses the SDK event, a
+ *     side script re-fires it via raw fbq/gtag to control timing); the starter
+ *     templates' vendor adapters (`vendors`: GA4, Axon, Taboola, Triple Whale,
+ *     TikTok, Northbeam, Snapchat, Pinterest, switched on by a campaigns.json
+ *     key, riding the SDK's dl_* stream through the template forwarder); and
+ *     out-of-band pixels a merchant loads some other way, typically through
+ *     their own GTM container (`out_of_band_pixels`, e.g. Everflow), which
+ *     never touch the dataLayer. So outbound pixel fires, not dataLayer
+ *     events, are the QA source of truth.
  *   - A custom provider may carry an endpoint + transform (cookie injection).
  *   - Querystring params split into two classes: CONTENT (param.* → visibility
  *     via data-next-hide) and TRACKING (utm params, gclid, fbclid, subN, click-ids that
@@ -549,8 +554,33 @@ export interface AnalyticsProvider {
     blockedEvents?: string[];
     [key: string]: unknown;
 }
-/** A pixel/tag fired OUTSIDE the SDK (via GTM or a raw snippet) — QA must still
- * expect it on a live run even though it never appears in the dataLayer. */
+/**
+ * One starter-template vendor adapter, keyed in `analytics.vendors` by the
+ * vendor key (ga4 | axon | taboola | triplewhale | tiktok | northbeam | snap |
+ * pinterest; registry: analytics-vendors.ts). This is the shape the Map
+ * Builder emits; its spec compiler writes the matching flat keys into the
+ * campaign's `_data/campaigns.json` entry, and `spec derive` mirrors the id
+ * back from there.
+ */
+export interface AnalyticsVendor {
+    /** false turns the vendor off (no campaigns.json key is compiled). */
+    enabled?: boolean;
+    /** The vendor id: the value of the vendor's campaigns.json id key (`ga4_id`, `triplewhale_name`, …). */
+    id?: string;
+    /** Triple Whale only: `triplewhale_platform` (e.g. SHOPIFY). The template default, custom-msp, is omitted. */
+    platform?: string;
+    /** Turns on the vendor's identity / advanced-matching flag (raw email and phone; the `*_enabled` key). */
+    identityEnabled?: boolean;
+    /** dl_* events the adapter forwards (`<vendor>_allowed_events`); absent means all. */
+    allowedEvents?: string[];
+    /** dl_* events the adapter drops (`<vendor>_blocked_events`), e.g. purchases on a Shop Sync store. */
+    blockedEvents?: string[];
+    [key: string]: unknown;
+}
+/** A pixel/tag fired OUTSIDE the SDK and the template adapters (via the
+ * merchant's GTM container or a raw snippet). QA must still expect it on a
+ * live run even though it never appears in the dataLayer. A vendor the starter
+ * templates ship an adapter for belongs in `vendors`, not here. */
 export interface OutOfBandPixel {
     vendor: string;
     loaded_via?: 'gtm' | 'script' | (string & {});
@@ -595,9 +625,13 @@ export interface UtmTransfer {
     excludedDomains?: string[];
 }
 export interface AnalyticsContract {
+    /** false turns the whole contract off, as mode "disabled" does. */
+    enabled?: boolean;
     mode?: AnalyticsMode;
-    /** Keyed by provider kind: gtm | facebook | rudderstack | custom | … */
+    /** SDK providers, keyed by provider kind: gtm | facebook | rudderstack | custom | … */
     providers?: Record<string, AnalyticsProvider>;
+    /** Starter-template vendor adapters, keyed by vendor key (see AnalyticsVendor). */
+    vendors?: Record<string, AnalyticsVendor>;
     out_of_band_pixels?: OutOfBandPixel[];
     manual_events?: ManualEvent[];
     utmTransfer?: UtmTransfer;

package/compatibility.json

@@ -1,6 +1,6 @@
 {
   "package": "@nextcommerce/campaigns-os",
-  "version": "1.60.0",
+  "version": "1.62.0",
   "status": "developer-preview",
   "contracts": {
     "campaign_spec": "4.2-5.0",

package/contracts/brand-theme-target-tokens.next-core.v0.json

@@ -24,42 +24,112 @@
     "--brand--color--rating-star",
     "--component--color--outline",
     "--system-colors--success",
-    "--system-colors--destructive"
+    "--system-colors--destructive",
+    "--_text---font-family--heading",
+    "--_text---font-family--primary",
+    "--radius-size--buttons"
   ],
   "source_mappings": {
-    "--brand-primary": ["--brand--color--primary"],
-    "--brand-accent": ["--brand--color--accent"],
-    "--brand-secondary": ["--brand--color--secondary"],
-    "--surface-bg": ["--brand--color--background"],
-    "--surface-card": ["--brand--color--surface"],
-    "--text-primary": ["--brand--color--text-primary", "--brand--color--foreground"],
-    "--text-secondary": ["--brand--color--text-secondary"],
-    "--border-default": ["--brand--color--border", "--component--color--outline"],
-    "--rating-star": ["--brand--color--rating-star"],
-    "--state-success": ["--system-colors--success"],
-    "--ui-success": ["--system-colors--success"],
-    "--state-error": ["--system-colors--destructive"],
-    "--ui-danger": ["--system-colors--destructive"],
-    "--brand-cta": ["--brand--color--cta-primary"],
-    "--cta-primary": ["--brand--color--cta-primary"],
-    "--button-primary-bg": ["--brand--color--cta-primary"]
+    "--brand-primary": [
+      "--brand--color--primary"
+    ],
+    "--brand-accent": [
+      "--brand--color--accent"
+    ],
+    "--brand-secondary": [
+      "--brand--color--secondary"
+    ],
+    "--surface-bg": [
+      "--brand--color--background"
+    ],
+    "--surface-card": [
+      "--brand--color--surface"
+    ],
+    "--text-primary": [
+      "--brand--color--text-primary",
+      "--brand--color--foreground"
+    ],
+    "--text-secondary": [
+      "--brand--color--text-secondary"
+    ],
+    "--border-default": [
+      "--brand--color--border",
+      "--component--color--outline"
+    ],
+    "--rating-star": [
+      "--brand--color--rating-star"
+    ],
+    "--state-success": [
+      "--system-colors--success"
+    ],
+    "--ui-success": [
+      "--system-colors--success"
+    ],
+    "--state-error": [
+      "--system-colors--destructive"
+    ],
+    "--ui-danger": [
+      "--system-colors--destructive"
+    ],
+    "--brand-cta": [
+      "--brand--color--cta-primary"
+    ],
+    "--cta-primary": [
+      "--brand--color--cta-primary"
+    ],
+    "--button-primary-bg": [
+      "--brand--color--cta-primary"
+    ]
   },
   "derived_mappings": {
     "--brand-primary": {
-      "--brand--color--primary-dark": { "method": "mix-black", "amount": 0.18 },
-      "--brand--color--primary-light": { "method": "mix-white", "amount": 0.2 },
-      "--brand--color--primary-lighter": { "method": "mix-white", "amount": 0.86 }
+      "--brand--color--primary-dark": {
+        "method": "mix-black",
+        "amount": 0.18
+      },
+      "--brand--color--primary-light": {
+        "method": "mix-white",
+        "amount": 0.2
+      },
+      "--brand--color--primary-lighter": {
+        "method": "mix-white",
+        "amount": 0.86
+      }
     }
   },
   "foreground_derivations": {
     "description": "Foreground/on-color tokens are derived from the luminance of the background they sit on, never copied blindly from a source --text-inverse token (which defaults to white and renders illegible on a light brand, e.g. white-on-yellow CTAs). Each foreground target picks the first paired background that was mapped and emits the readable choice from foreground_choices. next-core .button/.submit-button render their label with --brand--color--text-inverse, so text-inverse pairs with the CTA background first.",
-    "foreground_choices": { "dark": "#0a0a0a", "light": "#ffffff" },
+    "foreground_choices": {
+      "dark": "#0a0a0a",
+      "light": "#ffffff"
+    },
     "min_contrast_ratio": 4.5,
     "derivations": {
-      "--brand--color--cta-foreground": ["--brand--color--cta-primary"],
-      "--brand--color--text-inverse": ["--brand--color--cta-primary", "--brand--color--primary"],
-      "--brand--color--primary-foreground": ["--brand--color--primary"],
-      "--brand--color--accent-foreground": ["--brand--color--accent"]
+      "--brand--color--cta-foreground": [
+        "--brand--color--cta-primary"
+      ],
+      "--brand--color--text-inverse": [
+        "--brand--color--cta-primary",
+        "--brand--color--primary"
+      ],
+      "--brand--color--primary-foreground": [
+        "--brand--color--primary"
+      ],
+      "--brand--color--accent-foreground": [
+        "--brand--color--accent"
+      ]
     }
+  },
+  "typography": {
+    "description": "Typography targets. Font families are mapped only when the design source ships an @font-face for the family; the faces are written to brand-fonts.css beside brand-theme.css. next-core re-declares the font-family tokens on body inside its 991px, 767px and 479px media queries, so those tokens are emitted on `:root, body` to hold at every width.",
+    "targets": {
+      "heading_family": "--_text---font-family--heading",
+      "body_family": "--_text---font-family--primary",
+      "button_radius": "--radius-size--buttons"
+    },
+    "body_scoped_tokens": [
+      "--_text---font-family--heading",
+      "--_text---font-family--primary"
+    ]
   }
 }

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.42",
-    "captured_at": "2026-10-09"
+    "latest_known_release": "0.4.43",
+    "captured_at": "2026-10-22"
   },
   "source": "contracts/campaign-cart-sdk-support-policy.v0.json",
   "minimum_supported": "0.4.20",