@nextcommerce/campaigns-os 1.61.0 → 1.63.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,14 @@ 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 { PackageCurrencyPrices } from './package-currency-prices.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,14 @@ 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 { PackageCurrencyPrices } from "./package-currency-prices.js";
 import { PackagePricingSanity } from "./package-pricing-sanity.js";
 import { OfferRefIntegrity } from "./offer-ref-integrity.js";
 import { ExitIntentValidation } from "./exit-intent-validation.js";
@@ -69,11 +72,14 @@ 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 { PackageCurrencyPrices } from "./package-currency-prices.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 +120,14 @@ export const allRules = [
     PrePaymentForwardTarget,
     CheckoutStepReachesCheckout,
     OneCheckoutPerPath,
+    CheckoutPathHasPackages,
     UpsellWithoutCheckout,
     DownsellWithoutUpsell,
     PackagePricingSanity,
     ShippingMethodsPresent,
     ShippingCountriesShape,
+    CampaignCurrencies,
+    PackageCurrencyPrices,
     OfferRefIntegrity,
     ExitIntentValidation,
     PromoCodeInputValidation,

package/campaign-spec/dist/rules/package-currency-prices.d.ts

@@ -0,0 +1,29 @@
+/**
+ * PackageCurrencyPrices — checks each page package's price in every currency
+ * the campaign sells in (#714).
+ *
+ * A package row may carry `prices[]`: one `{ currency, price, price_retail?,
+ * price_recurring? }` per currency the Campaigns App has a price for, read
+ * from the Campaigns API (`GET /campaigns/?currency=<code>`). That read
+ * returns only the packages priced in the requested currency, so a package
+ * with no price in a listed currency is missing from the campaign for a
+ * shopper paying in it.
+ *
+ *   1. `prices`, when present, is an array of entries, each with a
+ *      three-letter upper-case ISO 4217 `currency` and a non-negative
+ *      numeric `price`, and no currency twice.
+ *   2. A row with `prices` has an entry for every currency in
+ *      campaign.available_currencies and for campaign.currency.
+ *
+ * A row without `prices` (absent or null) is silent: older Maps and
+ * hand-written specs carry the default currency's price only (`price`), and
+ * nothing is known about the others. Every finding is a warning, since a
+ * missing price is fixed in the Campaigns App, not in the spec.
+ *
+ * The selling currencies are the spec's own `campaign.currency` and
+ * `campaign.available_currencies`. The Campaigns App API's
+ * `additional_currencies` is not a CampaignSpec field (CampaignCurrencies), so
+ * it is not read here either.
+ */
+import type { Rule } from '../types.ts';
+export declare const PackageCurrencyPrices: Rule;

package/campaign-spec/dist/rules/package-currency-prices.js

@@ -0,0 +1,137 @@
+/**
+ * PackageCurrencyPrices — checks each page package's price in every currency
+ * the campaign sells in (#714).
+ *
+ * A package row may carry `prices[]`: one `{ currency, price, price_retail?,
+ * price_recurring? }` per currency the Campaigns App has a price for, read
+ * from the Campaigns API (`GET /campaigns/?currency=<code>`). That read
+ * returns only the packages priced in the requested currency, so a package
+ * with no price in a listed currency is missing from the campaign for a
+ * shopper paying in it.
+ *
+ *   1. `prices`, when present, is an array of entries, each with a
+ *      three-letter upper-case ISO 4217 `currency` and a non-negative
+ *      numeric `price`, and no currency twice.
+ *   2. A row with `prices` has an entry for every currency in
+ *      campaign.available_currencies and for campaign.currency.
+ *
+ * A row without `prices` (absent or null) is silent: older Maps and
+ * hand-written specs carry the default currency's price only (`price`), and
+ * nothing is known about the others. Every finding is a warning, since a
+ * missing price is fixed in the Campaigns App, not in the spec.
+ *
+ * The selling currencies are the spec's own `campaign.currency` and
+ * `campaign.available_currencies`. The Campaigns App API's
+ * `additional_currencies` is not a CampaignSpec field (CampaignCurrencies), so
+ * it is not read here either.
+ */
+import { isCurrencyCode } from "./campaign-currencies.js";
+// A non-negative amount: a finite number, or a plain decimal string ("49.99").
+// Hex, binary and exponent strings ("0x10", "1e3") are not prices.
+function isPrice(value) {
+    if (typeof value === 'number')
+        return Number.isFinite(value) && value >= 0;
+    return typeof value === 'string' && /^\d+(\.\d+)?$/.test(value.trim());
+}
+// An optional amount: absent, null, or a price.
+function isOptionalPrice(value) {
+    return value === undefined || value === null || isPrice(value);
+}
+// What is wrong with one prices[] entry, or null when it is well formed.
+function entryDefect(entry) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+        return 'is not a { currency, price } object';
+    const row = entry;
+    const defects = [];
+    if (!isCurrencyCode(row.currency))
+        defects.push('a three-letter upper-case ISO 4217 currency');
+    if (!isPrice(row.price))
+        defects.push('a non-negative decimal price');
+    for (const field of ['price_retail', 'price_recurring']) {
+        if (!isOptionalPrice(row[field]))
+            defects.push(`a non-negative decimal ${field} (or none)`);
+    }
+    return defects.length ? `needs ${defects.join(' and ')}` : null;
+}
+// The currencies the campaign sells in: the valid listed codes and a valid
+// default. Malformed codes are CampaignCurrencies' to report.
+function sellingCurrencies(spec) {
+    const campaign = spec.campaign;
+    if (!campaign || typeof campaign !== 'object')
+        return [];
+    const listed = Array.isArray(campaign.available_currencies) ? campaign.available_currencies : [];
+    return [...new Set([campaign.currency, ...listed].filter(isCurrencyCode))];
+}
+export const PackageCurrencyPrices = {
+    id: 'PackageCurrencyPrices',
+    severity: 'warning',
+    tags: ['fast', 'spec-only'],
+    check(spec) {
+        const violations = [];
+        const selling = sellingCurrencies(spec);
+        spec.funnels.forEach((funnel, funnelIdx) => {
+            ;
+            (funnel.pages ?? []).forEach((page, pageIdx) => {
+                ;
+                (page.packages ?? []).forEach((pkg, pkgIdx) => {
+                    const prices = pkg.prices;
+                    if (prices === undefined || prices === null)
+                        return;
+                    const path = `/funnels/${funnelIdx}/pages/${pageIdx}/packages/${pkgIdx}/prices`;
+                    const name = pkg.name || pkg.ref_id;
+                    const label = `"${page.label || page.id}" — Package "${name}"`;
+                    if (!Array.isArray(prices)) {
+                        violations.push({
+                            ruleId: 'PackageCurrencyPrices',
+                            severity: 'warning',
+                            message: `${label}: prices must be an array of { currency, price } entries.`,
+                            path,
+                            data: { check: 'prices_shape', pageId: page.id, ref_id: pkg.ref_id, received: prices },
+                        });
+                        return;
+                    }
+                    const seen = new Set();
+                    prices.forEach((entry, index) => {
+                        const currency = entry && typeof entry === 'object' && !Array.isArray(entry) ? entry.currency : undefined;
+                        const defect = entryDefect(entry);
+                        // A malformed entry with a valid currency still counts that
+                        // currency as listed: the entry's own finding names the fix, and a
+                        // second "has no EUR price" finding would report it twice.
+                        if (defect) {
+                            violations.push({
+                                ruleId: 'PackageCurrencyPrices',
+                                severity: 'warning',
+                                message: `${label}: prices[${index}] ${defect}.`,
+                                path: `${path}/${index}`,
+                                data: { check: 'price_entry_shape', pageId: page.id, ref_id: pkg.ref_id, received: entry },
+                            });
+                        }
+                        else if (isCurrencyCode(currency) && seen.has(currency)) {
+                            violations.push({
+                                ruleId: 'PackageCurrencyPrices',
+                                severity: 'warning',
+                                message: `${label}: prices lists ${currency} more than once.`,
+                                path: `${path}/${index}`,
+                                data: { check: 'price_currency_repeated', pageId: page.id, ref_id: pkg.ref_id, currency },
+                            });
+                        }
+                        if (isCurrencyCode(currency))
+                            seen.add(currency);
+                    });
+                    const missing = selling.filter((code) => !seen.has(code));
+                    if (missing.length > 0) {
+                        const list = missing.length === 1 ? missing[0] : `${missing.slice(0, -1).join(', ')} or ${missing[missing.length - 1]}`;
+                        violations.push({
+                            ruleId: 'PackageCurrencyPrices',
+                            severity: 'warning',
+                            message: `${label} has no ${list} price, so the campaign leaves it out in ${missing.length === 1 ? 'that currency' : 'those currencies'}. Add the price in the Campaigns App, then refresh the Map.`,
+                            path,
+                            data: { check: 'price_currency_missing', pageId: page.id, ref_id: pkg.ref_id, missing },
+                        });
+                    }
+                });
+            });
+        });
+        return violations;
+    },
+};

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

@@ -108,6 +108,14 @@ export interface PageOffer {
     benefit?: OfferBenefit;
     [key: string]: unknown;
 }
+/** One currency's price for a page package (#714). */
+export interface PackageCurrencyPrice {
+    /** Three-letter upper-case ISO 4217 code. */
+    currency: string;
+    price: number | string;
+    price_retail?: number | string | null;
+    price_recurring?: number | string | null;
+}
 export interface PagePackage {
     ref_id?: string | number;
     /**
@@ -118,6 +126,14 @@ export interface PagePackage {
     name?: string | null;
     price?: number | string | null;
     price_retail?: number | string | null;
+    /**
+     * The package's price in each currency the Campaigns App prices it in,
+     * read from the Campaigns API (`GET /campaigns/?currency=<code>`). `price`
+     * and `price_retail` above stay the default currency's. Optional; a row
+     * that carries it should list every currency the campaign sells in
+     * (PackageCurrencyPrices).
+     */
+    prices?: PackageCurrencyPrice[];
     product_name?: string | null;
     product_sku?: string | null;
     product_variant_name?: string | null;
@@ -519,12 +535,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 +570,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 +641,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.61.0",
+  "version": "1.63.0",
   "status": "developer-preview",
   "contracts": {
     "campaign_spec": "4.2-5.0",