@nextcommerce/campaigns-os 1.33.0

package/campaign-spec/dist/rules/upsell-has-packages.js

@@ -0,0 +1,35 @@
+/**
+ * UpsellHasPackages — upsell and downsell pages must declare at least one
+ * package, since the runtime renders a bundle/offer selector for these page
+ * types and an empty packages array has nothing to show.
+ *
+ * Message text inherited verbatim from the pre-#110 validator at migration time.
+ */
+function needsPackages(page) {
+    return page.type === 'upsell' || page.type === 'downsell';
+}
+export const UpsellHasPackages = {
+    id: 'UpsellHasPackages',
+    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 (!needsPackages(page))
+                    return;
+                if (page.packages && page.packages.length > 0)
+                    return;
+                violations.push({
+                    ruleId: 'UpsellHasPackages',
+                    severity: 'error',
+                    message: `"${page.label}" has no packages assigned.`,
+                    path: `/funnels/${funnelIdx}/pages/${pageIdx}/packages`,
+                    data: { pageId: page.id, pageType: page.type },
+                });
+            });
+        });
+        return violations;
+    },
+};

package/campaign-spec/dist/rules/upsell-routing-complete.d.ts

@@ -0,0 +1,10 @@
+/**
+ * UpsellRoutingComplete — upsell and downsell pages must declare both
+ * on_accept and on_decline routes. A missing route means the funnel
+ * topology has a dead-end at the offer.
+ *
+ * One rule, two potential violations per offending page. Message text
+ * inherited verbatim from the pre-#110 validator at migration time.
+ */
+import type { Rule } from '../types.ts';
+export declare const UpsellRoutingComplete: Rule;

package/campaign-spec/dist/rules/upsell-routing-complete.js

@@ -0,0 +1,45 @@
+/**
+ * UpsellRoutingComplete — upsell and downsell pages must declare both
+ * on_accept and on_decline routes. A missing route means the funnel
+ * topology has a dead-end at the offer.
+ *
+ * One rule, two potential violations per offending page. Message text
+ * inherited verbatim from the pre-#110 validator at migration time.
+ */
+function needsAcceptDecline(page) {
+    return page.type === 'upsell' || page.type === 'downsell';
+}
+export const UpsellRoutingComplete = {
+    id: 'UpsellRoutingComplete',
+    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 (!needsAcceptDecline(page))
+                    return;
+                if (!page.on_accept) {
+                    violations.push({
+                        ruleId: 'UpsellRoutingComplete',
+                        severity: 'error',
+                        message: `"${page.label}" — Accept path not set.`,
+                        path: `/funnels/${funnelIdx}/pages/${pageIdx}/on_accept`,
+                        data: { pageId: page.id, missing: 'on_accept' },
+                    });
+                }
+                if (!page.on_decline) {
+                    violations.push({
+                        ruleId: 'UpsellRoutingComplete',
+                        severity: 'error',
+                        message: `"${page.label}" — Decline path not set.`,
+                        path: `/funnels/${funnelIdx}/pages/${pageIdx}/on_decline`,
+                        data: { pageId: page.id, missing: 'on_decline' },
+                    });
+                }
+            });
+        });
+        return violations;
+    },
+};

package/campaign-spec/dist/rules/upsell-without-checkout.d.ts

@@ -0,0 +1,11 @@
+/**
+ * UpsellWithoutCheckout — if the spec has upsell pages, it must also have a
+ * checkout page. Otherwise nothing routes into the upsell flow.
+ *
+ * Severity downgrades to warning when build_scope.mode === 'partial', because
+ * partial-upsell builds may legitimately ship a standalone upsell that an
+ * existing downstream campaign routes into. Message text and severity rule
+ * inherited verbatim from the pre-#110 validator at migration time.
+ */
+import type { Rule } from '../types.ts';
+export declare const UpsellWithoutCheckout: Rule;

package/campaign-spec/dist/rules/upsell-without-checkout.js

@@ -0,0 +1,44 @@
+/**
+ * UpsellWithoutCheckout — if the spec has upsell pages, it must also have a
+ * checkout page. Otherwise nothing routes into the upsell flow.
+ *
+ * Severity downgrades to warning when build_scope.mode === 'partial', because
+ * partial-upsell builds may legitimately ship a standalone upsell that an
+ * existing downstream campaign routes into. Message text and severity rule
+ * inherited verbatim from the pre-#110 validator at migration time.
+ */
+export const UpsellWithoutCheckout = {
+    id: 'UpsellWithoutCheckout',
+    severity: 'error',
+    tags: ['fast', 'structure', 'spec-only'],
+    check(spec) {
+        let hasUpsell = false;
+        let hasCheckout = false;
+        for (const funnel of spec.funnels) {
+            for (const page of funnel.pages ?? []) {
+                if (page.type === 'upsell')
+                    hasUpsell = true;
+                else if (page.type === 'checkout')
+                    hasCheckout = true;
+                if (hasUpsell && hasCheckout)
+                    return [];
+            }
+        }
+        if (!hasUpsell)
+            return [];
+        if (hasCheckout)
+            return [];
+        const isPartialScope = spec.build_scope?.mode === 'partial';
+        return [
+            {
+                ruleId: 'UpsellWithoutCheckout',
+                severity: isPartialScope ? 'warning' : 'error',
+                message: isPartialScope
+                    ? 'Upsells are present without an active Checkout page. Valid for partial upsell builds when an existing checkout routes into this page.'
+                    : 'Upsells require an active Checkout page.',
+                path: '/funnels',
+                data: { isPartialScope },
+            },
+        ];
+    },
+};

package/campaign-spec/dist/rules/variant-labels-shape.d.ts

@@ -0,0 +1,28 @@
+/**
+ * VariantLabelsShape — validates per-page `variant_labels` introduced in
+ * Slice 4e.
+ *
+ * Multi-variant upsell templates (olympus-mv-single-step tier-cards, etc.)
+ * render columns for product attributes like size, color, flavor. The
+ * starter HTML often assumes two columns; single-attribute products
+ * (size-only, color-only) ship with empty second columns.
+ *
+ * Author-time hint: declare `{primary: "Size"}` on the upsell page and
+ * the build drops the second column; declare `{primary: "Size",
+ * secondary: "Color"}` and both columns render with the spec-declared
+ * labels. CLI/operator overrides at build time still win.
+ *
+ * Validation surface:
+ *   - set on non-upsell page (placement warning, mirrors the
+ *     pattern-on-non-upsell check in AssemblyHintsShape)
+ *   - bad outer shape (array, null, scalar)
+ *   - missing/empty primary
+ *   - non-string primary or secondary
+ *
+ * Pattern reference: AssemblyHintsShape.upsell_template_pattern is the
+ * canonical 4a per-page hint check this rule mirrors. Slice 4b
+ * (upsell_mv_tiers) ships without a dedicated shape rule today — its
+ * shape is enforced consumer-side in campaigns-os normalizedMvTiers().
+ */
+import type { Rule } from '../types.ts';
+export declare const VariantLabelsShape: Rule;

package/campaign-spec/dist/rules/variant-labels-shape.js

@@ -0,0 +1,86 @@
+/**
+ * VariantLabelsShape — validates per-page `variant_labels` introduced in
+ * Slice 4e.
+ *
+ * Multi-variant upsell templates (olympus-mv-single-step tier-cards, etc.)
+ * render columns for product attributes like size, color, flavor. The
+ * starter HTML often assumes two columns; single-attribute products
+ * (size-only, color-only) ship with empty second columns.
+ *
+ * Author-time hint: declare `{primary: "Size"}` on the upsell page and
+ * the build drops the second column; declare `{primary: "Size",
+ * secondary: "Color"}` and both columns render with the spec-declared
+ * labels. CLI/operator overrides at build time still win.
+ *
+ * Validation surface:
+ *   - set on non-upsell page (placement warning, mirrors the
+ *     pattern-on-non-upsell check in AssemblyHintsShape)
+ *   - bad outer shape (array, null, scalar)
+ *   - missing/empty primary
+ *   - non-string primary or secondary
+ *
+ * Pattern reference: AssemblyHintsShape.upsell_template_pattern is the
+ * canonical 4a per-page hint check this rule mirrors. Slice 4b
+ * (upsell_mv_tiers) ships without a dedicated shape rule today — its
+ * shape is enforced consumer-side in campaigns-os normalizedMvTiers().
+ */
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+export const VariantLabelsShape = {
+    id: 'VariantLabelsShape',
+    severity: 'warning',
+    tags: ['fast', 'spec-only'],
+    check(spec) {
+        const violations = [];
+        spec.funnels.forEach((funnel, funnelIdx) => {
+            const pages = funnel.pages ?? [];
+            pages.forEach((page, pageIdx) => {
+                const labels = page.variant_labels;
+                if (labels === undefined)
+                    return;
+                const path = `/funnels/${funnelIdx}/pages/${pageIdx}/variant_labels`;
+                const pageLabel = page.label || page.id || '(unnamed page)';
+                if (labels === null || typeof labels !== 'object' || Array.isArray(labels)) {
+                    violations.push({
+                        ruleId: 'VariantLabelsShape',
+                        severity: 'warning',
+                        message: `"${pageLabel}" — variant_labels must be an object with a "primary" string field; got ${Array.isArray(labels) ? 'array' : typeof labels}.`,
+                        path,
+                        data: { pageId: page.id, check: 'labels-bad-shape' },
+                    });
+                    return;
+                }
+                const labelsObj = labels;
+                if (page.type !== 'upsell') {
+                    violations.push({
+                        ruleId: 'VariantLabelsShape',
+                        severity: 'warning',
+                        message: `"${pageLabel}" — variant_labels is set on a non-upsell page (type=${page.type}). The hint is meaningful only on upsell pages; remove it or move it to an upsell page.`,
+                        path,
+                        data: { pageId: page.id, pageType: page.type, check: 'labels-on-non-upsell' },
+                    });
+                }
+                if (!isNonEmptyString(labelsObj.primary)) {
+                    violations.push({
+                        ruleId: 'VariantLabelsShape',
+                        severity: 'warning',
+                        message: `"${pageLabel}" — variant_labels.primary is required and must be a non-empty string (e.g. "Size").`,
+                        path: `${path}/primary`,
+                        data: { pageId: page.id, check: 'labels-primary-missing' },
+                    });
+                }
+                if (labelsObj.secondary !== undefined && labelsObj.secondary !== null && !isNonEmptyString(labelsObj.secondary)) {
+                    violations.push({
+                        ruleId: 'VariantLabelsShape',
+                        severity: 'warning',
+                        message: `"${pageLabel}" — variant_labels.secondary must be a non-empty string when set (omit the field for single-attribute products); got ${JSON.stringify(labelsObj.secondary)}.`,
+                        path: `${path}/secondary`,
+                        data: { pageId: page.id, check: 'labels-secondary-bad-type', value: labelsObj.secondary },
+                    });
+                }
+            });
+        });
+        return violations;
+    },
+};

package/campaign-spec/dist/sdk-version-parse.d.ts

@@ -0,0 +1,43 @@
+/**
+ * sdk-version-parse — the ONE strict released-SDK-version parser.
+ *
+ * Extracted from the Page Kit SDK-version checkpoint (src/page-kit-sdk-version.mjs)
+ * so authoring-time validation (the SdkVersion rule) and build-time gating
+ * (the checkpoint) reject exactly the same values. The acceptance predicate is
+ * the checkpoint's original one, unchanged: a plain string in canonical
+ * released `MAJOR.MINOR.PATCH` form — no leading zeros, no `v` prefix, no
+ * surrounding whitespace, no prerelease or build-metadata suffix, nothing but
+ * the three dot-separated numeric components.
+ *
+ * Dependency-free and browser-bundle-safe on purpose: the Map Builder bundles
+ * the campaign-spec module via esbuild, so nothing in here may import node
+ * builtins.
+ */
+/**
+ * Canonical released semver: MAJOR.MINOR.PATCH, each component `0` or a
+ * non-zero-leading integer. Identical to the pattern the Page Kit checkpoint
+ * shipped with — this constant is now its single home.
+ */
+export declare const RELEASED_SDK_VERSION_PATTERN: RegExp;
+/** Why a value was rejected. Diagnostic detail only — every reason is equally fatal. */
+export type SdkVersionRejectionReason = 'non-string' | 'empty' | 'padded' | 'prerelease-or-build' | 'non-canonical';
+export type SdkVersionParseResult = {
+    ok: true;
+    version: string;
+} | {
+    ok: false;
+    reason: SdkVersionRejectionReason;
+};
+/**
+ * Parse a candidate SDK version strictly. Never normalizes: a value either IS
+ * the canonical released form or it is rejected — the reason is diagnostic
+ * classification for error messages, not a repair hint the parser acts on.
+ */
+export declare function parseSdkVersion(value: unknown): SdkVersionParseResult;
+/**
+ * Boolean form of parseSdkVersion — drop-in for the checkpoint's original
+ * `isReleasedSemver` predicate.
+ */
+export declare function isReleasedSdkVersion(value: unknown): value is string;
+/** Human-readable fragment for a rejection reason, for composing error messages. */
+export declare function describeSdkVersionRejection(reason: SdkVersionRejectionReason): string;

package/campaign-spec/dist/sdk-version-parse.js

@@ -0,0 +1,62 @@
+/**
+ * sdk-version-parse — the ONE strict released-SDK-version parser.
+ *
+ * Extracted from the Page Kit SDK-version checkpoint (src/page-kit-sdk-version.mjs)
+ * so authoring-time validation (the SdkVersion rule) and build-time gating
+ * (the checkpoint) reject exactly the same values. The acceptance predicate is
+ * the checkpoint's original one, unchanged: a plain string in canonical
+ * released `MAJOR.MINOR.PATCH` form — no leading zeros, no `v` prefix, no
+ * surrounding whitespace, no prerelease or build-metadata suffix, nothing but
+ * the three dot-separated numeric components.
+ *
+ * Dependency-free and browser-bundle-safe on purpose: the Map Builder bundles
+ * the campaign-spec module via esbuild, so nothing in here may import node
+ * builtins.
+ */
+/**
+ * Canonical released semver: MAJOR.MINOR.PATCH, each component `0` or a
+ * non-zero-leading integer. Identical to the pattern the Page Kit checkpoint
+ * shipped with — this constant is now its single home.
+ */
+export const RELEASED_SDK_VERSION_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+/**
+ * Parse a candidate SDK version strictly. Never normalizes: a value either IS
+ * the canonical released form or it is rejected — the reason is diagnostic
+ * classification for error messages, not a repair hint the parser acts on.
+ */
+export function parseSdkVersion(value) {
+    if (typeof value !== 'string')
+        return { ok: false, reason: 'non-string' };
+    const trimmed = value.trim();
+    if (trimmed === '')
+        return { ok: false, reason: 'empty' };
+    if (RELEASED_SDK_VERSION_PATTERN.test(value))
+        return { ok: true, version: value };
+    if (value !== trimmed && RELEASED_SDK_VERSION_PATTERN.test(trimmed)) {
+        return { ok: false, reason: 'padded' };
+    }
+    // Classify against the trimmed form so a padded prerelease ("  0.4.37-beta.1 ")
+    // reports the substantive rejection (the suffix) rather than 'non-canonical'.
+    if (/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)[-+]/.test(trimmed)) {
+        return { ok: false, reason: 'prerelease-or-build' };
+    }
+    return { ok: false, reason: 'non-canonical' };
+}
+/**
+ * Boolean form of parseSdkVersion — drop-in for the checkpoint's original
+ * `isReleasedSemver` predicate.
+ */
+export function isReleasedSdkVersion(value) {
+    return typeof value === 'string' && RELEASED_SDK_VERSION_PATTERN.test(value);
+}
+const REJECTION_DETAIL = {
+    'non-string': 'value is not a string',
+    empty: 'value is empty',
+    padded: 'value has surrounding whitespace',
+    'prerelease-or-build': 'prerelease/build suffixes are not released versions',
+    'non-canonical': 'value is not in canonical released form',
+};
+/** Human-readable fragment for a rejection reason, for composing error messages. */
+export function describeSdkVersionRejection(reason) {
+    return REJECTION_DETAIL[reason];
+}