Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

21.9 KB
Raw Blame
import { MakeLogicType, actions, connect, events, kea, key, listeners, path, props, reducers, selectors } from 'kea'

import { eventUsageLogic } from 'lib/utils/eventUsageLogic'

import type { Experiment, FeatureFlagType } from '~/types'

import { NEW_EXPERIMENT } from 'products/experiments/frontend/constants'
import { selectExistingFeatureFlagModalLogic } from 'products/experiments/frontend/modals/SelectExistingFeatureFlagModal/selectExistingFeatureFlagModalLogic'
import {
    type MetricDataSources,
    getMetricDataSources,
    getWarehouseNativeExposure,
    getWarehouseNativeExposureError,
    getWarehouseNativeMismatchError,
} from 'products/experiments/frontend/warehouseNative/warehouseNativeSources'

import type {
    ExperimentExposureCriteria,
    ExperimentMetric,
    ExperimentMetricUnion,
} from '../../../queries/schema/schema-general'
import type { FeatureFlagFilters, MultivariateFlagVariant } from '../../../types'
import { createExperimentLogic } from '../ExperimentForm/createExperimentLogic'
import type { FeatureFlagKeyValidation } from '../ExperimentForm/variantsPanelLogic'
import { variantsPanelLogic } from '../ExperimentForm/variantsPanelLogic'
import { type ExposureSource, getExposureSource } from '../exposureContract'
import { getExperimentVariants, getFlagVariants } from '../utils'

export type ExperimentWizardStep = 'about' | 'variants' | 'analytics'

/** How someone reached a step: opening the wizard on its first step, reopening it on a later one, or moving within it */
export type ExperimentWizardStepNavigation = 'start' | 'resume' | 'continue' | 'back' | 'stepper'

const WIZARD_STEPS: ExperimentWizardStep[] = ['about', 'variants', 'analytics']

export function stepStorageKey(): string {
    return 'experiment-wizard-step'
}

function readStoredStep(): ExperimentWizardStep {
    try {
        const stored = sessionStorage.getItem(stepStorageKey())
        if (stored && WIZARD_STEPS.includes(stored as ExperimentWizardStep)) {
            return stored as ExperimentWizardStep
        }
    } catch {
        // ignore
    }
    return 'about'
}

export const STEP_ORDER: Record<ExperimentWizardStep, number> = {
    about: 0,
    variants: 1,
    analytics: 2,
}

export interface ExperimentWizardLogicProps {}

// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface experimentWizardLogicValues {
    createReplayVisionScanner: boolean // createExperimentLogic
    experiment: Experiment & {
        feature_flag_filters?: FeatureFlagFilters
    } // createExperimentLogic
    featureFlagKeyValidation: FeatureFlagKeyValidation | null // createExperimentLogic
    featureFlagKeyValidationLoading: boolean // createExperimentLogic
    isExperimentSubmitting: boolean // createExperimentLogic
    sharedMetrics: {
        primary: ExperimentMetric[]
        secondary: ExperimentMetric[]
    } // createExperimentLogic
    currentStep: ExperimentWizardStep
    currentStepHasErrors: boolean
    departedSteps: Record<string, boolean>
    hasFormErrors: boolean
    initialFlagCheckDone: boolean
    isFirstStep: boolean
    isLastStep: boolean
    linkedFeatureFlag: FeatureFlagType | null
    metricDataSources: MetricDataSources
    saveDisabledReason: string | undefined
    stepNumber: number
    stepValidationErrors: Record<ExperimentWizardStep, string[]>
    warehouseNativeSourcesError: string | null
}

// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface experimentWizardLogicActions {
    saveExperiment: () => {
        value: true
    } // createExperimentLogic
    saveExperimentSuccess: () => {
        value: true
    } // createExperimentLogic
    setCreateReplayVisionScanner: (enabled: boolean) => {
        enabled: boolean
    } // createExperimentLogic
    setExperiment: (experiment: Experiment) => {
        experiment: Experiment
    } // createExperimentLogic
    setExperimentValue: (
        name: string,
        value: any
    ) => {
        name: string
        value: any
    } // createExperimentLogic
    setExposureCriteria: (criteria: ExperimentExposureCriteria) => {
        criteria: ExperimentExposureCriteria
    } // createExperimentLogic
    setFeatureFlagConfig: (config: {
        ensure_experience_continuity?: boolean
        feature_flag_key?: string
        rollout_percentage?: number
        variants?: MultivariateFlagVariant[]
    }) => {
        config: {
            ensure_experience_continuity?: boolean | undefined
            feature_flag_key?: string | undefined
            rollout_percentage?: number | undefined
            variants?: MultivariateFlagVariant[] | undefined
        }
    } // createExperimentLogic
    setSharedMetrics: (sharedMetrics: { primary: ExperimentMetric[]; secondary: ExperimentMetric[] }) => {
        sharedMetrics: {
            primary: ExperimentMetricUnion[]
            secondary: ExperimentMetricUnion[]
        }
    } // createExperimentLogic
    reportExperimentWizardExposureSourceSelected: (exposureSource: ExposureSource) => {
        exposureSource: ExposureSource
    } // eventUsageLogic
    reportExperimentWizardStarted: () => {
        value: true
    } // eventUsageLogic
    reportExperimentWizardStepViewed: (
        step: string,
        stepNumber: number,
        previousStep: string | null,
        navigation: ExperimentWizardStepNavigation
    ) => {
        navigation: ExperimentWizardStepNavigation
        previousStep: string | null
        step: string
        stepNumber: number
    } // eventUsageLogic
    loadFeatureFlagsForAutocomplete: () => {
        value: true
    } // selectExistingFeatureFlagModalLogic
    loadFeatureFlagsSuccess: (
        featureFlags: {
            count: number
            results: FeatureFlagType[]
        },
        payload?: any
    ) => {
        featureFlags: {
            count: number
            results: FeatureFlagType[]
        }
        payload?: any
    } // selectExistingFeatureFlagModalLogic
    clearFeatureFlagKeyValidation: () => {
        value: true
    } // variantsPanelLogic
    validateFeatureFlagKey: (key: string) => {
        key: string
    } // variantsPanelLogic
    _applyStep: (
        step: ExperimentWizardStep,
        navigation: ExperimentWizardStepNavigation
    ) => {
        navigation: ExperimentWizardStepNavigation
        step: ExperimentWizardStep
    }
    markStepDeparted: (step: ExperimentWizardStep) => {
        step: ExperimentWizardStep
    }
    nextStep: () => {
        value: true
    }
    prevStep: () => {
        value: true
    }
    resetWizard: () => {
        value: true
    }
    setLinkedFeatureFlag: (flag: FeatureFlagType | null) => {
        flag: FeatureFlagType | null
    }
    setStep: (step: ExperimentWizardStep) => {
        step: ExperimentWizardStep
    }
}

// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface experimentWizardLogicMeta {
    key: string
    __keaTypeGenInternalSelectorTypes: {
        stepNumber: (currentStep: ExperimentWizardStep) => number
        isLastStep: (currentStep: ExperimentWizardStep) => boolean
        isFirstStep: (currentStep: ExperimentWizardStep) => boolean
        metricDataSources: (
            experiment: Experiment & {
                feature_flag_filters?: FeatureFlagFilters
            },
            sharedMetrics: {
                primary: ExperimentMetric[]
                secondary: ExperimentMetric[]
            }
        ) => MetricDataSources
        warehouseNativeSourcesError: (
            experiment: Experiment & {
                feature_flag_filters?: FeatureFlagFilters
            },
            sharedMetrics: {
                primary: ExperimentMetric[]
                secondary: ExperimentMetric[]
            },
            metricDataSources: MetricDataSources
        ) => string | null
        stepValidationErrors: (
            experiment: Experiment & {
                feature_flag_filters?: FeatureFlagFilters
            },
            featureFlagKeyValidation: FeatureFlagKeyValidation | null,
            linkedFeatureFlag: FeatureFlagType | null,
            departedSteps: Record<string, boolean>,
            warehouseNativeSourcesError: string | null
        ) => Record<ExperimentWizardStep, string[]>
        currentStepHasErrors: (
            stepValidationErrors: Record<ExperimentWizardStep, string[]>,
            currentStep: ExperimentWizardStep
        ) => boolean
        hasFormErrors: (stepValidationErrors: Record<ExperimentWizardStep, string[]>) => boolean
        saveDisabledReason: (warehouseNativeSourcesError: string | null, hasFormErrors: boolean) => string | undefined
    }
}

export type experimentWizardLogicType = MakeLogicType<
    experimentWizardLogicValues,
    experimentWizardLogicActions,
    ExperimentWizardLogicProps,
    experimentWizardLogicMeta
>

export const experimentWizardLogic = kea<experimentWizardLogicType>([
    path(['scenes', 'experiments', 'wizard', 'experimentWizardLogic']),

    props({} as ExperimentWizardLogicProps),

    key(() => 'create-experiment'),

    connect(() => ({
        values: [
            createExperimentLogic(),
            [
                'experiment',
                'sharedMetrics',
                'isExperimentSubmitting',
                'featureFlagKeyValidation',
                'featureFlagKeyValidationLoading',
                'createReplayVisionScanner',
            ],
        ],
        actions: [
            createExperimentLogic(),
            [
                'setExperiment',
                'setExperimentValue',
                'setFeatureFlagConfig',
                'setExposureCriteria',
                'setCreateReplayVisionScanner',
                'setSharedMetrics',
                'saveExperiment',
                'saveExperimentSuccess',
            ],
            variantsPanelLogic({ experiment: { ...NEW_EXPERIMENT }, disabled: false }),
            ['validateFeatureFlagKey', 'clearFeatureFlagKeyValidation'],
            selectExistingFeatureFlagModalLogic,
            ['loadFeatureFlagsForAutocomplete', 'loadFeatureFlagsSuccess'],
            eventUsageLogic,
            [
                'reportExperimentWizardStarted',
                'reportExperimentWizardStepViewed',
                'reportExperimentWizardExposureSourceSelected',
            ],
        ],
    })),

    actions({
        // Public navigation actions — handled in listeners so we can
        // capture the departing step before changing it.
        setStep: (step: ExperimentWizardStep) => ({ step }),
        nextStep: true,
        prevStep: true,
        // Internal: applies the step change after departure logic runs.
        _applyStep: (step: ExperimentWizardStep, navigation: ExperimentWizardStepNavigation) => ({ step, navigation }),
        markStepDeparted: (step: ExperimentWizardStep) => ({ step }),
        resetWizard: true,
        setLinkedFeatureFlag: (flag: FeatureFlagType | null) => ({ flag }),
    }),

    reducers(() => ({
        // Tracks whether the initial flag auto-link check has been performed.
        // Prevents repeated auto-linking when loadFeatureFlagsSuccess fires again
        // on the shared selectExistingFeatureFlagModalLogic singleton.
        initialFlagCheckDone: [
            false,
            {
                loadFeatureFlagsSuccess: () => true,
                resetWizard: () => false,
                saveExperimentSuccess: () => false,
            },
        ],
        currentStep: [
            readStoredStep(),
            {
                _applyStep: (_, { step }) => step,
                resetWizard: () => 'about',
                saveExperimentSuccess: () => 'about',
            },
        ],
        linkedFeatureFlag: [
            null as FeatureFlagType | null,
            {
                setLinkedFeatureFlag: (_, { flag }) => flag,
                resetWizard: () => null,
                saveExperimentSuccess: () => null,
            },
        ],
        departedSteps: [
            {} as Record<string, boolean>,
            {
                markStepDeparted: (state, { step }) => ({ ...state, [step]: true }),
                resetWizard: () => ({}),
                saveExperimentSuccess: () => ({}),
            },
        ],
    })),

    selectors({
        stepNumber: [(s) => [s.currentStep], (currentStep: ExperimentWizardStep): number => STEP_ORDER[currentStep]],
        isLastStep: [
            (s) => [s.currentStep],
            (currentStep: ExperimentWizardStep): boolean => currentStep === WIZARD_STEPS[WIZARD_STEPS.length - 1],
        ],
        isFirstStep: [
            (s) => [s.currentStep],
            (currentStep: ExperimentWizardStep): boolean => currentStep === WIZARD_STEPS[0],
        ],
        // The draft keeps shared metrics outside `experiment`, as ids only
        metricDataSources: [
            (s) => [s.experiment, s.sharedMetrics],
            (
                experiment: Experiment,
                sharedMetrics: { primary: ExperimentMetric[]; secondary: ExperimentMetric[] }
            ): MetricDataSources =>
                getMetricDataSources([
                    ...(experiment.metrics ?? []),
                    ...(experiment.metrics_secondary ?? []),
                    ...sharedMetrics.primary,
                    ...sharedMetrics.secondary,
                ]),
        ],
        // Why the API would reject the exposure and the metrics of the draft, or null
        warehouseNativeSourcesError: [
            (s) => [s.experiment, s.sharedMetrics, s.metricDataSources],
            (
                experiment: Experiment,
                sharedMetrics: { primary: ExperimentMetric[]; secondary: ExperimentMetric[] },
                metricDataSources: MetricDataSources
            ): string | null => {
                const warehouseExposure = getWarehouseNativeExposure(experiment.exposure_criteria)
                return (
                    (warehouseExposure && getWarehouseNativeExposureError(warehouseExposure)) ??
                    getWarehouseNativeMismatchError(warehouseExposure, metricDataSources, [
                        ...sharedMetrics.primary,
                        ...sharedMetrics.secondary,
                    ])
                )
            },
        ],
        stepValidationErrors: [
            (s) => [
                s.experiment,
                s.featureFlagKeyValidation,
                s.linkedFeatureFlag,
                s.departedSteps,
                s.warehouseNativeSourcesError,
            ],
            (
                experiment: Experiment,
                featureFlagKeyValidation: FeatureFlagKeyValidation | null,
                linkedFeatureFlag: FeatureFlagType | null,
                departedSteps: Record<string, boolean>,
                warehouseNativeSourcesError: string | null
            ): Record<ExperimentWizardStep, string[]> => {
                const errors: Record<ExperimentWizardStep, string[]> = {
                    about: [],
                    variants: [],
                    analytics: [],
                }

                // Required field errors — only shown after the user has navigated
                // away from the step, so the form isn't red on first load.
                if (departedSteps.about) {
                    if (!experiment.name?.trim()) {
                        errors.about.push('Name is required')
                    }
                    if (!experiment.feature_flag_key?.trim()) {
                        errors.about.push('Feature flag key is required')
                    }
                }

                if (departedSteps.analytics && warehouseNativeSourcesError) {
                    errors.analytics.push(warehouseNativeSourcesError)
                }

                if ((experiment.description?.length ?? 0) > 3000) {
                    errors.about.push('Hypothesis must be 3000 characters or fewer')
                }

                // Active validation errors — always shown once triggered
                if (!linkedFeatureFlag && featureFlagKeyValidation?.valid === false && featureFlagKeyValidation.error) {
                    errors.about.push(featureFlagKeyValidation.error)
                }

                // Linked feature flags show variants read-only so we skip validations
                if (!linkedFeatureFlag) {
                    const variants = getExperimentVariants(experiment)
                    const variantKeys = variants.map((v) => v.key)
                    const hasDuplicateKeys = variantKeys.length !== new Set(variantKeys).size
                    const hasEmptyKeys = variants.some((v) => !v.key || v.key.trim().length === 0)

                    if (hasEmptyKeys) {
                        errors.variants.push('All variants must have a key')
                    }
                    if (hasDuplicateKeys) {
                        errors.variants.push('Variant keys must be unique')
                    }

                    const totalRollout = variants.reduce((sum, v) => sum + (v.rollout_percentage ?? 0), 0)
                    if (variants.length >= 2 && totalRollout !== 100) {
                        errors.variants.push('Variant percentages must sum to 100%')
                    }
                }

                return errors
            },
        ],
        currentStepHasErrors: [
            (s) => [s.stepValidationErrors, s.currentStep],
            (errors: Record<ExperimentWizardStep, string[]>, currentStep: ExperimentWizardStep): boolean => {
                return errors[currentStep]?.length > 0
            },
        ],
        hasFormErrors: [
            (s) => [s.stepValidationErrors],
            (errors: Record<ExperimentWizardStep, string[]>): boolean =>
                WIZARD_STEPS.some((step) => errors[step]?.length > 0),
        ],
        // An exposure that the API rejects blocks the save before the stepper marks the step
        saveDisabledReason: [
            (s) => [s.warehouseNativeSourcesError, s.hasFormErrors],
            (warehouseNativeSourcesError: string | null, hasFormErrors: boolean): string | undefined =>
                warehouseNativeSourcesError ?? (hasFormErrors ? 'Please fix all errors before saving' : undefined),
        ],
    }),

    listeners(({ actions, values, selectors }) => ({
        setExposureCriteria: (_, __, ___, previousState) => {
            const exposureSource = getExposureSource(values.experiment.exposure_criteria)
            if (exposureSource !== getExposureSource(selectors.experiment(previousState).exposure_criteria)) {
                actions.reportExperimentWizardExposureSourceSelected(exposureSource)
            }
        },
        _applyStep: ({ step, navigation }, _, __, previousState) => {
            try {
                sessionStorage.setItem(stepStorageKey(), step)
            } catch {
                // ignore
            }
            const previousStep = selectors.currentStep(previousState)
            if (step !== previousStep) {
                actions.reportExperimentWizardStepViewed(step, STEP_ORDER[step] + 1, previousStep, navigation)
            }
        },
        resetWizard: () => {
            try {
                sessionStorage.removeItem(stepStorageKey())
            } catch {
                // ignore
            }
        },
        saveExperimentSuccess: () => {
            try {
                sessionStorage.removeItem(stepStorageKey())
            } catch {
                // ignore
            }
        },
        loadFeatureFlagsSuccess: ({
            featureFlags,
        }: {
            featureFlags: { results: FeatureFlagType[]; count: number }
        }) => {
            // Only auto-link on the first load. The
            // selectExistingFeatureFlagModalLogic is a shared singleton, so a
            // later flag load elsewhere would otherwise trigger auto-linking here.
            if (values.initialFlagCheckDone) {
                return
            }
            const key = values.experiment?.feature_flag_key
            if (key && !values.linkedFeatureFlag && featureFlags.results?.length) {
                const match = featureFlags.results.find((f) => f.key === key)
                if (match) {
                    actions.setLinkedFeatureFlag(match)
                    actions.setFeatureFlagConfig({
                        feature_flag_key: match.key,
                        variants: getFlagVariants(match),
                    })
                }
            }
        },
        nextStep: () => {
            actions.markStepDeparted(values.currentStep)
            const currentIndex = WIZARD_STEPS.indexOf(values.currentStep)
            actions._applyStep(WIZARD_STEPS[Math.min(currentIndex + 1, WIZARD_STEPS.length - 1)], 'continue')

            const key = values.experiment?.feature_flag_key
            if (key && !values.linkedFeatureFlag && values.featureFlagKeyValidation === null) {
                actions.validateFeatureFlagKey(key)
            }
        },
        prevStep: () => {
            actions.markStepDeparted(values.currentStep)
            const currentIndex = WIZARD_STEPS.indexOf(values.currentStep)
            actions._applyStep(WIZARD_STEPS[Math.max(currentIndex - 1, 0)], 'back')
        },
        setStep: ({ step }) => {
            actions.markStepDeparted(values.currentStep)
            actions._applyStep(step, 'stepper')

            const key = values.experiment?.feature_flag_key
            if (key && !values.linkedFeatureFlag && values.featureFlagKeyValidation === null) {
                actions.validateFeatureFlagKey(key)
            }
        },
        saveExperiment: () => {
            for (const step of WIZARD_STEPS) {
                actions.markStepDeparted(step)
            }
        },
    })),

    events(({ actions, values }) => ({
        afterMount: () => {
            actions.reportExperimentWizardStarted()
            // The wizard reopens on the step saved earlier in the session, so the first view can be a later step
            actions.reportExperimentWizardStepViewed(
                values.currentStep,
                STEP_ORDER[values.currentStep] + 1,
                null,
                values.isFirstStep ? 'start' : 'resume'
            )
            actions.loadFeatureFlagsForAutocomplete()
        },
    })),
])