@funnelsgrove/runtime 0.1.55 → 0.1.59

package/dist/steps/step-contract.js

@@ -0,0 +1,506 @@
+const deepFreezeContract = (value) => {
+    if (value === null || typeof value !== 'object' || Object.isFrozen(value)) {
+        return value;
+    }
+    for (const nestedValue of Object.values(value)) {
+        deepFreezeContract(nestedValue);
+    }
+    Object.freeze(value);
+    return value;
+};
+export const CURRENT_STEP_CONTRACT_VERSION = 3;
+export const PREVIOUS_STEP_CONTRACT_VERSION = 2;
+export const LEGACY_UNVERSIONED_STEP_CONTRACT_VERSION = 1;
+export const SUPPORTED_STEP_CONTRACT_VERSIONS = Object.freeze([
+    LEGACY_UNVERSIONED_STEP_CONTRACT_VERSION,
+    PREVIOUS_STEP_CONTRACT_VERSION,
+    CURRENT_STEP_CONTRACT_VERSION,
+]);
+const GLOBALLY_FORBIDDEN_CAPABILITIES = [
+    'hardcoded-navigation',
+    'provider-direct-analytics',
+    'browser-registration-completed',
+];
+const capabilitiesExcept = (...allowed) => {
+    const scopedCapabilities = [
+        'choice-write',
+        'email-capture',
+        'checkout',
+        'subscription-management',
+        'subscription-handoff',
+    ];
+    return [
+        ...scopedCapabilities.filter((capability) => !allowed.includes(capability)),
+        ...GLOBALLY_FORBIDDEN_CAPABILITIES,
+    ];
+};
+export const FUNNEL_STEP_CONTRACTS = deepFreezeContract({
+    intro_hero: {
+        family: 'content',
+        description: 'Opening promise or low-friction entry screen.',
+        allowedKinds: [],
+        actionOwner: 'shared-shell',
+        allowedCustomEvents: [],
+        forbiddenCapabilities: capabilitiesExcept(),
+        terminal: false,
+    },
+    value_prop_story: {
+        family: 'content',
+        description: 'Benefit, explanation, motivation, or narrative value screen.',
+        allowedKinds: [],
+        actionOwner: 'shared-shell',
+        allowedCustomEvents: [],
+        forbiddenCapabilities: capabilitiesExcept(),
+        terminal: false,
+    },
+    single_step_choice: {
+        family: 'choice',
+        description: 'Exactly one standard option is selected.',
+        allowedKinds: [],
+        choice: {
+            cardinality: 'one',
+            presentation: 'standard',
+            completion: 'selection',
+            allowEmptyConfig: false,
+        },
+        actionOwner: 'step',
+        allowedCustomEvents: [],
+        forbiddenCapabilities: capabilitiesExcept('choice-write'),
+        terminal: false,
+    },
+    single_step_choice_emoji: {
+        family: 'choice',
+        description: 'Exactly one emoji-led option is selected.',
+        allowedKinds: [],
+        choice: {
+            cardinality: 'one',
+            presentation: 'emoji',
+            completion: 'selection',
+            allowEmptyConfig: false,
+        },
+        actionOwner: 'step',
+        allowedCustomEvents: [],
+        forbiddenCapabilities: capabilitiesExcept('choice-write'),
+        terminal: false,
+    },
+    multi_select_choice: {
+        family: 'choice',
+        description: 'Multiple options are selected before explicit completion.',
+        allowedKinds: [],
+        choice: {
+            cardinality: 'many',
+            presentation: 'standard',
+            completion: 'explicit',
+            allowEmptyConfig: true,
+        },
+        actionOwner: 'either',
+        allowedCustomEvents: [],
+        forbiddenCapabilities: capabilitiesExcept('choice-write'),
+        terminal: false,
+    },
+    form_input: {
+        family: 'form',
+        description: 'Non-choice structured input, including reserved email capture.',
+        allowedKinds: [],
+        actionOwner: 'either',
+        allowedCustomEvents: ['email_captured'],
+        forbiddenCapabilities: capabilitiesExcept('email-capture'),
+        terminal: false,
+    },
+    social_proof: {
+        family: 'content',
+        description: 'Testimonials, reviews, credibility, or evidence.',
+        allowedKinds: [],
+        actionOwner: 'shared-shell',
+        allowedCustomEvents: [],
+        forbiddenCapabilities: capabilitiesExcept(),
+        terminal: false,
+    },
+    progress_interstitial: {
+        family: 'transition',
+        description: 'Progress, calculation, loading, reveal, or transition screen.',
+        allowedKinds: [],
+        actionOwner: 'either',
+        allowedCustomEvents: [],
+        forbiddenCapabilities: capabilitiesExcept(),
+        terminal: false,
+    },
+    paywall_offer: {
+        family: 'commerce',
+        description: 'A monetization offer that presents purchasable plans.',
+        allowedKinds: ['paywall'],
+        requiredKind: 'paywall',
+        actionOwner: 'step',
+        allowedCustomEvents: ['checkout_started', 'add_payment_info', 'checkout_completed'],
+        forbiddenCapabilities: capabilitiesExcept('checkout'),
+        terminal: false,
+        analyticsRole: 'paywall',
+    },
+    upsell_offer: {
+        family: 'commerce',
+        description: 'A post-purchase or upgrade offer.',
+        allowedKinds: ['upsell'],
+        requiredKind: 'upsell',
+        actionOwner: 'step',
+        allowedCustomEvents: ['checkout_started', 'add_payment_info', 'checkout_completed'],
+        forbiddenCapabilities: capabilitiesExcept('checkout'),
+        terminal: false,
+    },
+    checkout: {
+        family: 'commerce',
+        description: 'A dedicated payment-entry screen.',
+        allowedKinds: [],
+        actionOwner: 'step',
+        allowedCustomEvents: ['checkout_started', 'add_payment_info', 'checkout_completed'],
+        forbiddenCapabilities: capabilitiesExcept('checkout'),
+        terminal: false,
+    },
+    subscription_management: {
+        family: 'commerce',
+        description: 'A screen for managing or inspecting an existing subscription.',
+        allowedKinds: ['manage-subscription'],
+        requiredKind: 'manage-subscription',
+        actionOwner: 'step',
+        allowedCustomEvents: [],
+        forbiddenCapabilities: capabilitiesExcept('subscription-management'),
+        terminal: false,
+    },
+    subscription_handoff: {
+        family: 'commerce',
+        description: 'A non-terminal app, store, or deep-link handoff.',
+        allowedKinds: ['subscription-handoff'],
+        requiredKind: 'subscription-handoff',
+        actionOwner: 'step',
+        allowedCustomEvents: [],
+        forbiddenCapabilities: capabilitiesExcept('subscription-handoff'),
+        terminal: false,
+    },
+    cancellation_offer: {
+        family: 'commerce',
+        description: 'A cancellation retention or downsell surface.',
+        allowedKinds: ['cancellation'],
+        requiredKind: 'cancellation',
+        actionOwner: 'step',
+        allowedCustomEvents: [],
+        forbiddenCapabilities: capabilitiesExcept('subscription-management'),
+        terminal: false,
+    },
+    summary_confirmation: {
+        family: 'content',
+        description: 'A summary, review, or confirmation before the next action.',
+        allowedKinds: [],
+        actionOwner: 'either',
+        allowedCustomEvents: [],
+        forbiddenCapabilities: capabilitiesExcept(),
+        terminal: false,
+    },
+    complete_registration: {
+        family: 'terminal',
+        description: 'The canonical post-purchase terminal that continues into the app.',
+        allowedKinds: ['subscription-handoff'],
+        requiredKind: 'subscription-handoff',
+        actionOwner: 'step',
+        allowedCustomEvents: ['funnel_completed'],
+        forbiddenCapabilities: capabilitiesExcept('subscription-handoff'),
+        terminal: true,
+        analyticsRole: 'complete-registration',
+    },
+    purchase_completed: {
+        family: 'terminal',
+        description: 'The canonical terminal shown after a verified initial purchase.',
+        allowedKinds: ['subscription-handoff'],
+        requiredKind: 'subscription-handoff',
+        actionOwner: 'step',
+        allowedCustomEvents: ['funnel_completed'],
+        forbiddenCapabilities: capabilitiesExcept('subscription-handoff'),
+        terminal: true,
+        analyticsRole: 'purchase-completed',
+    },
+});
+export const FUNNEL_STEP_TYPES = Object.freeze(Object.keys(FUNNEL_STEP_CONTRACTS));
+export const FUNNEL_RESERVED_STEP_CONTRACTS = deepFreezeContract({
+    'email-capture': {
+        match: 'exact',
+        id: 'email-capture',
+        name: 'email-capture',
+        type: 'form_input',
+        unique: true,
+    },
+    paywall: {
+        match: 'exact',
+        id: 'paywall',
+        name: 'paywall',
+        type: 'paywall_offer',
+        kind: 'paywall',
+        unique: true,
+        primary: true,
+    },
+    'paywall-variant': {
+        match: 'pattern',
+        idPattern: '^paywall-[a-z0-9-]+$',
+        namePattern: '^paywall-[a-z0-9-]+$',
+        type: 'paywall_offer',
+        kind: 'paywall',
+        unique: false,
+        primary: false,
+    },
+    'subscription-started': {
+        match: 'exact',
+        id: 'subscription-started',
+        name: 'subscription-started',
+        type: 'purchase_completed',
+        kind: 'subscription-handoff',
+        unique: true,
+    },
+    'manage-subscription': {
+        match: 'exact',
+        id: 'manage-subscription',
+        name: 'manage-subscription',
+        type: 'subscription_management',
+        kind: 'manage-subscription',
+        unique: true,
+    },
+});
+const PREVIOUS_SUBSCRIPTION_TERMINAL_CONTRACT = deepFreezeContract(Object.assign(Object.assign({}, FUNNEL_RESERVED_STEP_CONTRACTS['subscription-started']), { type: 'complete_registration' }));
+export const resolveStepTypeContract = (version, type) => {
+    if (!SUPPORTED_STEP_CONTRACT_VERSIONS.includes(version)) {
+        return undefined;
+    }
+    if ((version < CURRENT_STEP_CONTRACT_VERSION && type === 'purchase_completed')
+        || (version === CURRENT_STEP_CONTRACT_VERSION && type === 'complete_registration')) {
+        return undefined;
+    }
+    return Object.prototype.hasOwnProperty.call(FUNNEL_STEP_CONTRACTS, type)
+        ? FUNNEL_STEP_CONTRACTS[type]
+        : undefined;
+};
+export const resolveReservedStepContract = (version, identity) => {
+    if (!SUPPORTED_STEP_CONTRACT_VERSIONS.includes(version)) {
+        return undefined;
+    }
+    if (identity === 'subscription-started' && version < CURRENT_STEP_CONTRACT_VERSION) {
+        return PREVIOUS_SUBSCRIPTION_TERMINAL_CONTRACT;
+    }
+    return Object.prototype.hasOwnProperty.call(FUNNEL_RESERVED_STEP_CONTRACTS, identity)
+        ? FUNNEL_RESERVED_STEP_CONTRACTS[identity]
+        : undefined;
+};
+export const FUNNEL_STEP_CAPABILITY_RULES = deepFreezeContract({
+    'choice-write': {
+        allowedStepTypes: [
+            'single_step_choice',
+            'single_step_choice_emoji',
+            'multi_select_choice',
+        ],
+        allowedStepIdentities: 'any',
+        requiredOwner: 'useStepChoices',
+    },
+    'email-capture': {
+        allowedStepTypes: ['form_input'],
+        allowedStepIdentities: ['email-capture'],
+        requiredOwner: 'submitEmailCapture',
+    },
+    checkout: {
+        allowedStepTypes: ['paywall_offer', 'upsell_offer', 'checkout'],
+        allowedStepIdentities: 'any',
+        requiredOwner: 'named-payment-helpers',
+    },
+    'subscription-management': {
+        allowedStepTypes: ['subscription_management', 'cancellation_offer'],
+        allowedStepIdentities: 'any',
+        requiredOwner: 'runtime-subscription-helpers',
+    },
+    'subscription-handoff': {
+        allowedStepTypes: ['subscription_handoff', 'complete_registration', 'purchase_completed'],
+        allowedStepIdentities: 'any',
+        requiredOwner: 'runtime-handoff-helper',
+    },
+    'hardcoded-navigation': {
+        allowedStepTypes: [],
+        allowedStepIdentities: [],
+        requiredOwner: 'manifest-flow-controller',
+    },
+    'provider-direct-analytics': {
+        allowedStepTypes: [],
+        allowedStepIdentities: [],
+        requiredOwner: 'analytics-adapter-outbox',
+    },
+    'browser-registration-completed': {
+        allowedStepTypes: [],
+        allowedStepIdentities: [],
+        requiredOwner: 'trusted-subscription-claim-server',
+    },
+});
+const COMMON_FUNNEL_EVENT_METADATA = [
+    'funnelId',
+    'funnelVersionId',
+    'environment',
+    'stepContractVersion',
+];
+const COMMON_STEP_EVENT_METADATA = [
+    ...COMMON_FUNNEL_EVENT_METADATA,
+    'stepId',
+    'stepName',
+    'stepType',
+];
+export const FUNNEL_ANALYTICS_EVENT_CONTRACTS = deepFreezeContract({
+    funnel_started: {
+        rawName: 'funnel_start',
+        publicName: 'funnel_started',
+        owner: 'controller',
+        automatic: true,
+        requiredMetadata: COMMON_FUNNEL_EVENT_METADATA,
+        allowedStepTypes: 'any',
+        allowedStepIdentities: 'any',
+        dedupeScope: 'funnel-run',
+    },
+    step_started: {
+        rawName: 'step_start',
+        publicName: 'step_started',
+        owner: 'controller',
+        automatic: true,
+        requiredMetadata: COMMON_STEP_EVENT_METADATA,
+        allowedStepTypes: 'any',
+        allowedStepIdentities: 'any',
+        dedupeScope: 'step-visit',
+    },
+    step_completed: {
+        rawName: 'step_end',
+        publicName: 'step_completed',
+        owner: 'controller',
+        automatic: true,
+        requiredMetadata: COMMON_STEP_EVENT_METADATA,
+        allowedStepTypes: 'any',
+        allowedStepIdentities: 'any',
+        dedupeScope: 'step-visit',
+    },
+    step_exited: {
+        rawName: 'step_exit',
+        publicName: 'step_exited',
+        owner: 'controller',
+        automatic: true,
+        requiredMetadata: COMMON_STEP_EVENT_METADATA,
+        allowedStepTypes: 'any',
+        allowedStepIdentities: 'any',
+        dedupeScope: 'step-visit',
+    },
+    first_step_viewed: {
+        rawName: 'first_step_viewed',
+        publicName: 'first_step_viewed',
+        owner: 'controller',
+        automatic: true,
+        requiredMetadata: COMMON_STEP_EVENT_METADATA,
+        allowedStepTypes: 'any',
+        allowedStepIdentities: 'any',
+        dedupeScope: 'step-visit',
+    },
+    first_step_clicked: {
+        rawName: 'first_step_clicked',
+        publicName: 'first_step_clicked',
+        owner: 'controller',
+        automatic: true,
+        requiredMetadata: COMMON_STEP_EVENT_METADATA,
+        allowedStepTypes: 'any',
+        allowedStepIdentities: 'any',
+        dedupeScope: 'step-visit',
+    },
+    step_engaged: {
+        rawName: 'step_engaged',
+        publicName: 'step_engaged',
+        owner: 'controller',
+        automatic: false,
+        requiredMetadata: [...COMMON_STEP_EVENT_METADATA, 'durationMs'],
+        allowedStepTypes: 'any',
+        allowedStepIdentities: 'any',
+        dedupeScope: 'step-visit',
+    },
+    email_captured: {
+        rawName: 'email_captured',
+        publicName: 'email_captured',
+        owner: 'transactional-server',
+        automatic: false,
+        requiredMetadata: [
+            ...COMMON_STEP_EVENT_METADATA,
+            'projectId',
+            'funnelEndUserId',
+            'eventId',
+        ],
+        allowedStepTypes: ['form_input'],
+        allowedStepIdentities: ['email-capture'],
+        dedupeScope: 'logical-email-conversion',
+    },
+    checkout_started: {
+        rawName: 'checkout_started',
+        publicName: 'checkout_started',
+        owner: 'named-helper',
+        automatic: false,
+        requiredMetadata: [...COMMON_STEP_EVENT_METADATA, 'eventId'],
+        allowedStepTypes: ['paywall_offer', 'upsell_offer', 'checkout'],
+        allowedStepIdentities: 'any',
+        dedupeScope: 'event-id',
+    },
+    add_payment_info: {
+        rawName: 'add_payment_info',
+        publicName: 'add_payment_info',
+        owner: 'named-helper',
+        automatic: false,
+        requiredMetadata: [...COMMON_STEP_EVENT_METADATA, 'eventId'],
+        allowedStepTypes: ['paywall_offer', 'upsell_offer', 'checkout'],
+        allowedStepIdentities: 'any',
+        dedupeScope: 'event-id',
+    },
+    checkout_completed: {
+        rawName: 'checkout_completed',
+        publicName: 'checkout_completed',
+        owner: 'named-helper',
+        automatic: false,
+        requiredMetadata: [...COMMON_STEP_EVENT_METADATA, 'eventId'],
+        allowedStepTypes: ['paywall_offer', 'upsell_offer', 'checkout'],
+        allowedStepIdentities: 'any',
+        dedupeScope: 'event-id',
+    },
+    funnel_completed: {
+        rawName: 'funnel_completed',
+        publicName: 'funnel_completed',
+        owner: 'terminal-helper',
+        automatic: false,
+        requiredMetadata: [...COMMON_STEP_EVENT_METADATA, 'eventId'],
+        allowedStepTypes: ['complete_registration', 'purchase_completed'],
+        allowedStepIdentities: 'any',
+        dedupeScope: 'funnel-run',
+    },
+    registration_completed: {
+        rawName: 'registration_completed',
+        publicName: 'registration_completed',
+        owner: 'trusted-server',
+        automatic: false,
+        requiredMetadata: [
+            ...COMMON_FUNNEL_EVENT_METADATA,
+            'projectId',
+            'funnelEndUserId',
+            'eventId',
+            'subscriptionClaimId',
+        ],
+        allowedStepTypes: [],
+        allowedStepIdentities: [],
+        dedupeScope: 'subscription-claim',
+    },
+    purchase_completed: {
+        rawName: 'purchase_completed',
+        publicName: 'purchase_completed',
+        owner: 'trusted-server',
+        automatic: false,
+        requiredMetadata: [
+            ...COMMON_FUNNEL_EVENT_METADATA,
+            'projectId',
+            'funnelEndUserId',
+            'eventId',
+            'providerPaymentId',
+            'purchaseKind',
+        ],
+        allowedStepTypes: [],
+        allowedStepIdentities: [],
+        dedupeScope: 'provider-payment',
+    },
+});
+export const DEFERRABLE_FUNNEL_CONTRACT_DIAGNOSTIC_CODES = deepFreezeContract(['FG-PARITY-001', 'FG-REGISTRY-001', 'FG-CONTENT-001', 'FG-FLOW-001']);

package/dist/steps/types.d.ts

@@ -1,20 +1,22 @@
-export declare const FUNNEL_STEP_TYPES: readonly ["intro_hero", "value_prop_story", "single_step_choice", "single_step_choice_emoji", "multi_select_choice", "form_input", "social_proof", "progress_interstitial", "paywall_offer", "upsell_offer", "checkout", "subscription_management", "subscription_handoff", "cancellation_offer", "summary_confirmation", "complete_registration"];
-export type FunnelStepType = (typeof FUNNEL_STEP_TYPES)[number];
+import type { FunnelChoiceDescriptor, FunnelStepKind, FunnelStepType } from './step-contract.js';
+export { FUNNEL_STEP_TYPES } from './step-contract.js';
+export type { FunnelChoiceDescriptor, FunnelChoiceOption, FunnelEmojiChoiceOption, FunnelStepKind, FunnelStepType, } from './step-contract.js';
 export type FunnelStepActionBar = {
     hidden?: boolean;
     buttonText?: string;
     buttonVariant?: 'muted';
     autoAdvanceMs?: number;
 };
-export type FunnelStepKind = 'default' | 'paywall' | 'upsell' | 'manage-subscription' | 'subscription-handoff' | 'cancellation';
 export type FunnelStepMeta = {
     id: string;
-    /** Optional short name to make step intent obvious for non-engineers. */
-    name?: string;
+    /** Stable kebab-case analytics slug. */
+    name: string;
     /** Canonical structural taxonomy used across planning, runtime, and RAG examples. */
     type: FunnelStepType;
     /** Optional semantic class used by tooling (e.g. paywall detection). */
     kind?: FunnelStepKind;
+    /** Stable answer field configuration for choice steps. */
+    choice?: FunnelChoiceDescriptor;
     figmaNodeId: string;
     title: string;
     description: string;

package/dist/steps/types.js

@@ -1,18 +1 @@
-export const FUNNEL_STEP_TYPES = [
-    'intro_hero',
-    'value_prop_story',
-    'single_step_choice',
-    'single_step_choice_emoji',
-    'multi_select_choice',
-    'form_input',
-    'social_proof',
-    'progress_interstitial',
-    'paywall_offer',
-    'upsell_offer',
-    'checkout',
-    'subscription_management',
-    'subscription_handoff',
-    'cancellation_offer',
-    'summary_confirmation',
-    'complete_registration',
-];
+export { FUNNEL_STEP_TYPES } from './step-contract.js';

package/dist/testing/funnel-contract-journey-driver.d.ts

@@ -0,0 +1,35 @@
+import type { FunnelFlowApiAdapter } from '../runtime/use-funnel-flow-controller.js';
+export type FunnelContractJourneyEnvelope = {
+    eventType: string;
+    eventId: string;
+    userId?: string;
+    environment?: 'test' | 'live';
+    occurredAt?: string;
+    stepId?: string;
+    stepName?: string;
+    stepType?: string;
+    startedAt?: string;
+    endedAt?: string;
+    stepContractVersion?: number;
+    selected?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    featureFlags?: Record<string, string>;
+};
+export type FunnelContractJourneyResult = {
+    envelopes: FunnelContractJourneyEnvelope[];
+    emailCaptureCalls: Array<{
+        userId: string;
+        email: string;
+        environment: 'test' | 'live';
+    }>;
+    browserEmailEvents: Array<{
+        eventId: string;
+        stepId: string;
+        stepName: string;
+        stepType: string;
+    }>;
+    visitedStepIds: string[];
+};
+export declare const runFunnelContractJourney: (options: {
+    captureEmail: FunnelFlowApiAdapter["captureEmail"];
+}) => Promise<FunnelContractJourneyResult>;