@funnelsgrove/runtime 0.1.56 → 0.1.59

package/dist/runtime/funnel-manifest.validation.d.ts

@@ -1,2 +1,7 @@
-import type { FunnelManifest } from '../config/funnel.manifest.types.js';
-export declare const validateFunnelManifest: <T extends FunnelManifest>(manifest: T) => T;
+import { type FunnelManifestContractInput } from '../validation/funnel-contract-validator.js';
+export type LegacyReadableFunnelManifest = FunnelManifestContractInput;
+export declare const normalizeLegacyFunnelManifestForRead: <T extends LegacyReadableFunnelManifest>(manifest: T) => T & {
+    stepContractVersion: number;
+};
+export declare const validateFunnelManifest: <T extends LegacyReadableFunnelManifest>(manifest: T) => T;
+export declare const validateAuthoringFunnelManifest: <T extends LegacyReadableFunnelManifest>(manifest: T) => T;

package/dist/runtime/funnel-manifest.validation.js

@@ -1,75 +1,31 @@
-const isDefinedString = (value) => {
-    return typeof value === 'string' && value.trim().length > 0;
-};
-const pushDuplicateErrors = (label, values, errors) => {
-    const seen = new Set();
-    const duplicates = new Set();
-    for (const value of values) {
-        if (seen.has(value)) {
-            duplicates.add(value);
-            continue;
-        }
-        seen.add(value);
-    }
-    if (duplicates.size > 0) {
-        errors.push(`duplicate ${label}: ${Array.from(duplicates).join(', ')}`);
+import { LEGACY_UNVERSIONED_STEP_CONTRACT_VERSION, } from '../steps/step-contract.js';
+import { validateFunnelManifestContract, } from '../validation/funnel-contract-validator.js';
+export const normalizeLegacyFunnelManifestForRead = (manifest) => {
+    if (manifest.stepContractVersion !== undefined) {
+        return manifest;
     }
+    return Object.assign(Object.assign({}, manifest), { stepContractVersion: LEGACY_UNVERSIONED_STEP_CONTRACT_VERSION });
 };
-const assertValidReference = (label, value, validIds, errors) => {
-    if (!isDefinedString(value) || !validIds.has(value)) {
-        errors.push(`${label} references missing step "${value || ''}"`);
+const formatDiagnosticValue = (value) => {
+    var _a;
+    if (typeof value === 'string') {
+        return value;
     }
+    return (_a = JSON.stringify(value)) !== null && _a !== void 0 ? _a : String(value);
 };
-export const validateFunnelManifest = (manifest) => {
-    const errors = [];
-    if (!Number.isInteger(manifest.templateArchitectureVersion) || manifest.templateArchitectureVersion < 1) {
-        errors.push('templateArchitectureVersion must be a positive integer');
-    }
-    if (manifest.steps.length === 0) {
-        errors.push('manifest must declare at least one step');
-    }
-    const stepIds = manifest.steps.map((step) => step.id);
-    const stepPaths = manifest.steps.map((step) => step.path);
-    const filePaths = manifest.steps.map((step) => step.filePath);
-    const componentKeys = manifest.steps.map((step) => step.componentKey);
-    const validStepIds = new Set(stepIds);
-    pushDuplicateErrors('step ids', stepIds, errors);
-    pushDuplicateErrors('step paths', stepPaths, errors);
-    pushDuplicateErrors('step file paths', filePaths, errors);
-    pushDuplicateErrors('step component keys', componentKeys, errors);
-    for (const entryPoint of manifest.entryPoints || []) {
-        assertValidReference(`entry point "${entryPoint.id}"`, entryPoint.stepId, validStepIds, errors);
-    }
-    for (const [stepId, edges] of Object.entries(manifest.edgesByStepId)) {
-        assertValidReference(`edge source "${stepId}"`, stepId, validStepIds, errors);
-        for (const edge of edges || []) {
-            assertValidReference(`edge from "${stepId}"`, edge.toStepId, validStepIds, errors);
-        }
-    }
-    pushDuplicateErrors('branch ids', (manifest.branches || []).map((branch) => branch.id), errors);
-    for (const branch of manifest.branches || []) {
-        if (!isDefinedString(branch.id)) {
-            errors.push('branch id is required');
-        }
-        if (!isDefinedString(branch.name)) {
-            errors.push(`branch "${branch.id || ''}" name is required`);
-        }
-        assertValidReference(`branch "${branch.id}" source`, branch.sourceStepId, validStepIds, errors);
-        if (branch.stepIds.length === 0) {
-            errors.push(`branch "${branch.id}" must own at least one step`);
-        }
-        for (const stepId of branch.stepIds) {
-            assertValidReference(`branch "${branch.id}" step`, stepId, validStepIds, errors);
-        }
-    }
-    for (const experiment of manifest.experiments) {
-        assertValidReference(`experiment "${experiment.experimentId}"`, experiment.stepId, validStepIds, errors);
-        for (const variant of experiment.variants) {
-            assertValidReference(`experiment variant "${experiment.experimentId}:${variant.variantKey}"`, variant.routeToStepId, validStepIds, errors);
-        }
-    }
-    if (errors.length > 0) {
-        throw new Error(`Invalid funnel manifest:\n- ${errors.join('\n- ')}`);
+const validateAuthoringManifest = (manifest) => {
+    const diagnostics = validateFunnelManifestContract(manifest, { mode: 'authoring' });
+    if (diagnostics.length > 0) {
+        const details = diagnostics.map((item) => {
+            return `[${item.code}] ${item.reason} Expected ${formatDiagnosticValue(item.expected)}; received ${formatDiagnosticValue(item.received)}.`;
+        });
+        throw new Error(`Invalid funnel manifest:\n- ${details.join('\n- ')}`);
     }
     return manifest;
 };
+export const validateFunnelManifest = (manifest) => {
+    return validateAuthoringManifest(manifest);
+};
+export const validateAuthoringFunnelManifest = (manifest) => {
+    return validateAuthoringManifest(manifest);
+};

package/dist/runtime/funnel-step-lifecycle.d.ts

@@ -0,0 +1,35 @@
+export type FunnelStepExitReason = 'back' | 'replace' | 'cancel' | 'abandon';
+export type FunnelNavigationOutcome = {
+    type: 'complete';
+    selected?: Record<string, unknown>;
+} | {
+    type: 'exit';
+    reason: FunnelStepExitReason;
+};
+export type FunnelStepVisit = {
+    readonly visitId: number;
+    readonly stepId: string;
+    readonly startedAt: string;
+    readonly outcome: null | 'completed' | 'exited';
+};
+export type FunnelStepLifecycleIntent = {
+    readonly type: 'complete';
+    readonly selected?: Readonly<Record<string, unknown>>;
+    readonly visit: FunnelStepVisit;
+} | {
+    readonly type: 'exit';
+    readonly reason: FunnelStepExitReason;
+    readonly visit: FunnelStepVisit;
+};
+export type FunnelStepLifecycleStartIntent = {
+    readonly type: 'start';
+    readonly visit: FunnelStepVisit;
+};
+declare const funnelStepLifecycleStateBrand: unique symbol;
+export type FunnelStepLifecycleState = {
+    readonly [funnelStepLifecycleStateBrand]: true;
+};
+export declare const createFunnelStepLifecycleState: () => FunnelStepLifecycleState;
+export declare const startVisit: (state: FunnelStepLifecycleState, input: Pick<FunnelStepVisit, "stepId" | "startedAt">) => FunnelStepLifecycleStartIntent | null;
+export declare const finishVisit: (state: FunnelStepLifecycleState, visitId: FunnelStepVisit["visitId"], outcome: FunnelNavigationOutcome) => FunnelStepLifecycleIntent | null;
+export {};

package/dist/runtime/funnel-step-lifecycle.js

@@ -0,0 +1,49 @@
+const stateValues = new WeakMap();
+const readState = (state) => {
+    const value = stateValues.get(state);
+    if (!value) {
+        throw new Error('Invalid funnel step lifecycle state.');
+    }
+    return value;
+};
+const snapshotVisit = (visit) => Object.freeze(Object.assign({}, visit));
+export const createFunnelStepLifecycleState = () => {
+    const state = Object.freeze({});
+    stateValues.set(state, { activeVisit: null, nextVisitId: 1 });
+    return state;
+};
+export const startVisit = (state, input) => {
+    var _a;
+    const stateValue = readState(state);
+    if (((_a = stateValue.activeVisit) === null || _a === void 0 ? void 0 : _a.outcome) === null) {
+        return null;
+    }
+    const visit = {
+        visitId: stateValue.nextVisitId,
+        stepId: input.stepId,
+        startedAt: input.startedAt,
+        outcome: null,
+    };
+    stateValue.nextVisitId += 1;
+    stateValue.activeVisit = visit;
+    return Object.freeze({ type: 'start', visit: snapshotVisit(visit) });
+};
+export const finishVisit = (state, visitId, outcome) => {
+    const visit = readState(state).activeVisit;
+    if (!visit || visit.visitId !== visitId || visit.outcome !== null) {
+        return null;
+    }
+    visit.outcome = outcome.type === 'complete' ? 'completed' : 'exited';
+    const visitSnapshot = snapshotVisit(visit);
+    if (outcome.type === 'exit') {
+        return Object.freeze({ type: 'exit', reason: outcome.reason, visit: visitSnapshot });
+    }
+    if (outcome.selected === undefined) {
+        return Object.freeze({ type: 'complete', visit: visitSnapshot });
+    }
+    return Object.freeze({
+        type: 'complete',
+        selected: Object.freeze(Object.assign({}, outcome.selected)),
+        visit: visitSnapshot,
+    });
+};

package/dist/runtime/funnel-step-metadata.validation.d.ts

@@ -0,0 +1,7 @@
+import type { FunnelManifestStep } from '../config/funnel.manifest.types.js';
+import type { FunnelStepMeta } from '../steps/types.js';
+import { type FunnelContractDiagnostic } from '../validation/funnel-contract-diagnostics.js';
+export type FunnelStepMetadataParityOptions = {
+    file?: string;
+};
+export declare const validateFunnelStepMetadataParity: (manifestStep: FunnelManifestStep, componentMeta: FunnelStepMeta, options?: FunnelStepMetadataParityOptions) => FunnelContractDiagnostic[];

package/dist/runtime/funnel-step-metadata.validation.js

@@ -0,0 +1,88 @@
+import { createFunnelContractDiagnostic, } from '../validation/funnel-contract-diagnostics.js';
+const OMITTED_STEP_KIND = Symbol('omitted-step-kind');
+const normalizeKind = (kind) => {
+    return kind === undefined ? OMITTED_STEP_KIND : kind;
+};
+const isChoiceRecord = (value) => {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+};
+const normalizeChoice = (value) => {
+    if (!isChoiceRecord(value)) {
+        return null;
+    }
+    const keys = Object.keys(value);
+    if (!Object.prototype.hasOwnProperty.call(value, 'answerKey')
+        || keys.some((key) => key !== 'answerKey' && key !== 'allowEmpty')
+        || typeof value.answerKey !== 'string'
+        || (value.allowEmpty !== undefined && typeof value.allowEmpty !== 'boolean')) {
+        return null;
+    }
+    return {
+        answerKey: value.answerKey,
+        allowEmpty: value.allowEmpty,
+    };
+};
+const choicesMatch = (expected, received) => {
+    if (expected === undefined || received === undefined) {
+        return expected === received;
+    }
+    const normalizedExpected = normalizeChoice(expected);
+    const normalizedReceived = normalizeChoice(received);
+    if (normalizedExpected === null || normalizedReceived === null) {
+        return false;
+    }
+    return (normalizedExpected.answerKey === normalizedReceived.answerKey
+        && normalizedExpected.allowEmpty === normalizedReceived.allowEmpty);
+};
+export const validateFunnelStepMetadataParity = (manifestStep, componentMeta, options = {}) => {
+    var _a;
+    const diagnostics = [];
+    const comparisons = [
+        {
+            field: 'id',
+            expected: manifestStep.id,
+            received: componentMeta.id,
+            matches: manifestStep.id === componentMeta.id,
+        },
+        {
+            field: 'name',
+            expected: manifestStep.name,
+            received: componentMeta.name,
+            matches: manifestStep.name === componentMeta.name,
+        },
+        {
+            field: 'type',
+            expected: manifestStep.type,
+            received: componentMeta.type,
+            matches: manifestStep.type === componentMeta.type,
+        },
+        {
+            field: 'kind',
+            expected: manifestStep.kind,
+            received: componentMeta.kind,
+            matches: normalizeKind(manifestStep.kind) === normalizeKind(componentMeta.kind),
+        },
+        {
+            field: 'choice',
+            expected: manifestStep.choice,
+            received: componentMeta.choice,
+            matches: choicesMatch(manifestStep.choice, componentMeta.choice),
+        },
+    ];
+    for (const comparison of comparisons) {
+        if (comparison.matches) {
+            continue;
+        }
+        diagnostics.push(createFunnelContractDiagnostic({
+            code: 'FG-PARITY-001',
+            file: (_a = options.file) !== null && _a !== void 0 ? _a : manifestStep.filePath,
+            stepId: manifestStep.id,
+            expected: comparison.expected,
+            received: comparison.received,
+            reason: `Component metadata ${comparison.field} does not match the manifest step.`,
+            guide: 'docs/product-specs/funnel-template-step-authoring.md',
+            repair: `Update the component metadata ${comparison.field} to match the manifest step.`,
+        }));
+    }
+    return diagnostics;
+};

package/dist/runtime/submit-email-capture.d.ts

@@ -0,0 +1,23 @@
+export type EmailCapturePersistenceResult<User> = {
+    user: User;
+    eventId: string;
+    eventCreated: boolean;
+};
+export type EmailCaptureSingleFlight = {
+    current: Promise<void> | null;
+};
+export type SubmitEmailCaptureInput<User> = {
+    email: string;
+    isPreview: boolean;
+    singleFlight: EmailCaptureSingleFlight;
+    retryPendingNavigation?: () => boolean | Promise<boolean>;
+    persist: (email: string) => Promise<EmailCapturePersistenceResult<User>>;
+    applyUser: (user: User) => void;
+    applyPreviewEmail: (email: string) => void;
+    fanOutBrowserDestinations: (eventId: string) => void | Promise<void>;
+    completeVisit: () => boolean;
+    resolveNextStep: () => string | null;
+    navigate: (stepId: string) => void;
+};
+export declare const createEmailCaptureSingleFlight: () => EmailCaptureSingleFlight;
+export declare const submitEmailCapture: <User>(input: SubmitEmailCaptureInput<User>) => Promise<void>;

package/dist/runtime/submit-email-capture.js

@@ -0,0 +1,54 @@
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const MAX_EMAIL_LENGTH = 320;
+const normalizeEmail = (value) => {
+    const email = value.trim().toLowerCase();
+    if (!email || email.length > MAX_EMAIL_LENGTH || !EMAIL_PATTERN.test(email)) {
+        throw new Error('Invalid email address');
+    }
+    return email;
+};
+export const createEmailCaptureSingleFlight = () => ({
+    current: null,
+});
+const runEmailCapture = async (input) => {
+    if (input.retryPendingNavigation && await input.retryPendingNavigation()) {
+        return;
+    }
+    const email = normalizeEmail(input.email);
+    if (input.isPreview) {
+        input.applyPreviewEmail(email);
+    }
+    else {
+        const result = await input.persist(email);
+        input.applyUser(result.user);
+        if (result.eventCreated) {
+            try {
+                await input.fanOutBrowserDestinations(result.eventId);
+            }
+            catch (_a) {
+                // The server already committed the logical conversion. Browser delivery is best effort.
+            }
+        }
+    }
+    if (!input.completeVisit()) {
+        return;
+    }
+    const nextStepId = input.resolveNextStep();
+    if (nextStepId) {
+        input.navigate(nextStepId);
+    }
+};
+export const submitEmailCapture = (input) => {
+    if (input.singleFlight.current) {
+        return input.singleFlight.current;
+    }
+    const operation = runEmailCapture(input);
+    input.singleFlight.current = operation;
+    const clearSingleFlight = () => {
+        if (input.singleFlight.current === operation) {
+            input.singleFlight.current = null;
+        }
+    };
+    void operation.then(clearSingleFlight, clearSingleFlight);
+    return operation;
+};

package/dist/runtime/use-funnel-flow-controller.d.ts

@@ -2,8 +2,10 @@ import { type Dispatch, type SetStateAction } from 'react';
 import type { FunnelContextValue } from '../components/FunnelContext.js';
 import type { FunnelManifestExperiment } from '../config/funnel.manifest.types.js';
 import type { FunnelUserAnswers } from '../sdk/userAnswers.js';
+import { apiService } from '../services/api.service.js';
 import { type FunnelUserAttribution } from './funnel-attribution.js';
-import type { FunnelStepMeta } from '../steps/types.js';
+import type { FunnelStepMeta, FunnelStepType } from '../steps/types.js';
+import { type FunnelStepLifecycleIntent } from './funnel-step-lifecycle.js';
 export type FunnelFlowControllerExperiment<StepId extends string> = FunnelManifestExperiment & {
     stepId: StepId;
     variants: readonly (FunnelManifestExperiment['variants'][number] & {
@@ -12,13 +14,21 @@ export type FunnelFlowControllerExperiment<StepId extends string> = FunnelManife
 };
 type StepComponentRegistry = Record<string, unknown>;
 type FunnelFlowAnalyticsAdapter = {
+    flush?: () => unknown | Promise<unknown>;
+    trackEmailCapturedBrowserDestinations?: (input: {
+        eventId: string;
+        stepId: string;
+        stepName: string;
+        stepType: FunnelStepType;
+    }) => void;
     trackStepStarted?: (input: {
         userId?: string;
         environment?: 'test' | 'live';
         stepId: string;
         stepName: string;
-        stepType?: string;
+        stepType: FunnelStepType;
         startedAt: string;
+        stepContractVersion: number;
         metadata?: Record<string, unknown>;
         featureFlags?: Record<string, string>;
     }) => string | null;
@@ -27,19 +37,47 @@ type FunnelFlowAnalyticsAdapter = {
         environment?: 'test' | 'live';
         stepId: string;
         stepName: string;
-        stepType?: string;
+        stepType: FunnelStepType;
         startedAt: string;
         endedAt: string;
+        stepContractVersion: number;
         selected?: Record<string, unknown>;
         metadata?: Record<string, unknown>;
         featureFlags?: Record<string, string>;
     }) => string | null;
+    trackStepExited?: (input: {
+        userId?: string;
+        environment?: 'test' | 'live';
+        stepId: string;
+        stepName: string;
+        stepType: FunnelStepType;
+        startedAt: string;
+        endedAt: string;
+        exitReason: Extract<FunnelStepLifecycleIntent, {
+            type: 'exit';
+        }>['reason'];
+        stepContractVersion: number;
+        metadata?: Record<string, unknown>;
+        featureFlags?: Record<string, string>;
+    }) => string | null;
     trackFunnelStarted?: (input: {
         userId?: string;
         environment?: 'test' | 'live';
         stepId: string;
         stepName: string;
         stepType?: string;
+        stepContractVersion: number;
+        occurredAt: string;
+        metadata?: Record<string, unknown>;
+        featureFlags?: Record<string, string>;
+    }) => string | null;
+    trackFunnelCompleted?: (input: {
+        userId?: string;
+        environment?: 'test' | 'live';
+        stepId: string;
+        stepName: string;
+        stepType: FunnelStepType;
+        stepContractVersion: number;
         occurredAt: string;
         metadata?: Record<string, unknown>;
         featureFlags?: Record<string, string>;
@@ -49,14 +87,29 @@ type FunnelFlowAnalyticsAdapter = {
         environment?: 'test' | 'live';
         stepId: string;
         stepName: string;
-        stepType?: string;
+        stepType: FunnelStepType;
+        stepContractVersion: number;
+        occurredAt: string;
+        metadata?: Record<string, unknown>;
+        featureFlags?: Record<string, string>;
+    }) => string | null;
+    trackFirstStepClicked?: (input: {
+        userId?: string;
+        environment?: 'test' | 'live';
+        stepId: string;
+        stepName: string;
+        stepType: FunnelStepType;
+        stepContractVersion: number;
         occurredAt: string;
         metadata?: Record<string, unknown>;
         featureFlags?: Record<string, string>;
     }) => string | null;
 };
+export type FunnelFlowApiAdapter = Pick<typeof apiService, 'getOrCreateClientUserId' | 'getBootstrapCandidateUserId' | 'bootstrapSession' | 'pingUserContext' | 'updateUser' | 'captureEmail'>;
 type UseFunnelFlowControllerInput<StepId extends string> = {
+    api?: FunnelFlowApiAdapter;
     analytics?: FunnelFlowAnalyticsAdapter;
+    stepContractVersion: number;
     initialStepId?: StepId;
     initialAttributes?: FunnelUserAnswers;
     lockToInitialStep?: boolean;
@@ -127,5 +180,5 @@ export declare function resolveRenderedExperimentStepId(input: {
     resolveRenderableStepId: (stepId: string | null | undefined) => string | null;
     safeActiveStepId: string;
 }): string;
-export declare function useFunnelFlowController<StepId extends string>({ analytics, initialStepId, initialAttributes, lockToInitialStep, defaultStepId, stepSequence, stepById, stepComponentById, funnelExperiments, getPathForStep, getStepIdFromPath, getSequentialNextStepId, getChoiceTargetsForStep, isFunnelStepId, resolveConfiguredNextStep, resolveRuntimeInitialStepId, }: UseFunnelFlowControllerInput<StepId>): UseFunnelFlowControllerResult<StepId>;
+export declare function useFunnelFlowController<StepId extends string>({ api, analytics, stepContractVersion, initialStepId, initialAttributes, lockToInitialStep, defaultStepId, stepSequence, stepById, stepComponentById, funnelExperiments, getPathForStep, getStepIdFromPath, getSequentialNextStepId, getChoiceTargetsForStep, isFunnelStepId, resolveConfiguredNextStep, resolveRuntimeInitialStepId, }: UseFunnelFlowControllerInput<StepId>): UseFunnelFlowControllerResult<StepId>;
 export {};