@funnelsgrove/runtime 0.1.55 → 0.1.59

package/dist/steps/step-contract.d.ts

@@ -0,0 +1,498 @@
+import type { FunnelAnswerKey } from '../sdk/userAnswers.js';
+export declare const CURRENT_STEP_CONTRACT_VERSION: 3;
+export declare const PREVIOUS_STEP_CONTRACT_VERSION: 2;
+export declare const LEGACY_UNVERSIONED_STEP_CONTRACT_VERSION: 1;
+export declare const SUPPORTED_STEP_CONTRACT_VERSIONS: readonly [1, 2, 3];
+export type FunnelStepContractVersion = (typeof SUPPORTED_STEP_CONTRACT_VERSIONS)[number];
+export type FunnelStepKind = 'paywall' | 'upsell' | 'manage-subscription' | 'subscription-handoff' | 'cancellation';
+export type FunnelStepFamily = 'content' | 'choice' | 'form' | 'transition' | 'commerce' | 'terminal';
+export type FunnelStepActionOwner = 'shared-shell' | 'step' | 'either';
+export type FunnelStepCapability = 'choice-write' | 'email-capture' | 'checkout' | 'subscription-management' | 'subscription-handoff' | 'hardcoded-navigation' | 'provider-direct-analytics' | 'browser-registration-completed';
+export type FunnelAnalyticsEventName = 'funnel_started' | 'step_started' | 'step_completed' | 'step_exited' | 'first_step_viewed' | 'first_step_clicked' | 'step_engaged' | 'email_captured' | 'checkout_started' | 'add_payment_info' | 'checkout_completed' | 'funnel_completed' | 'purchase_completed' | 'registration_completed';
+export type FunnelChoiceDescriptor = {
+    answerKey: FunnelAnswerKey;
+    allowEmpty?: boolean;
+};
+export type FunnelChoiceOption = {
+    id: string;
+    label: string;
+    imageSrc?: string;
+    iconKey?: string;
+};
+export type FunnelEmojiChoiceOption = {
+    id: string;
+    label: string;
+    emoji: string;
+};
+export type FunnelStepChoiceContract = {
+    cardinality: 'one' | 'many';
+    presentation: 'standard' | 'emoji';
+    completion: 'selection' | 'explicit';
+    allowEmptyConfig: boolean;
+};
+export type FunnelStepContractDefinition = {
+    family: FunnelStepFamily;
+    description: string;
+    allowedKinds: readonly FunnelStepKind[];
+    requiredKind?: FunnelStepKind;
+    choice?: FunnelStepChoiceContract;
+    actionOwner: FunnelStepActionOwner;
+    allowedCustomEvents: readonly FunnelAnalyticsEventName[];
+    forbiddenCapabilities: readonly FunnelStepCapability[];
+    terminal: boolean;
+    analyticsRole?: 'paywall' | 'complete-registration' | 'purchase-completed';
+};
+export declare const FUNNEL_STEP_CONTRACTS: {
+    readonly intro_hero: {
+        readonly family: "content";
+        readonly description: "Opening promise or low-friction entry screen.";
+        readonly allowedKinds: readonly [];
+        readonly actionOwner: "shared-shell";
+        readonly allowedCustomEvents: readonly [];
+        readonly forbiddenCapabilities: readonly FunnelStepCapability[];
+        readonly terminal: false;
+    };
+    readonly value_prop_story: {
+        readonly family: "content";
+        readonly description: "Benefit, explanation, motivation, or narrative value screen.";
+        readonly allowedKinds: readonly [];
+        readonly actionOwner: "shared-shell";
+        readonly allowedCustomEvents: readonly [];
+        readonly forbiddenCapabilities: readonly FunnelStepCapability[];
+        readonly terminal: false;
+    };
+    readonly single_step_choice: {
+        readonly family: "choice";
+        readonly description: "Exactly one standard option is selected.";
+        readonly allowedKinds: readonly [];
+        readonly choice: {
+            readonly cardinality: "one";
+            readonly presentation: "standard";
+            readonly completion: "selection";
+            readonly allowEmptyConfig: false;
+        };
+        readonly actionOwner: "step";
+        readonly allowedCustomEvents: readonly [];
+        readonly forbiddenCapabilities: readonly FunnelStepCapability[];
+        readonly terminal: false;
+    };
+    readonly single_step_choice_emoji: {
+        readonly family: "choice";
+        readonly description: "Exactly one emoji-led option is selected.";
+        readonly allowedKinds: readonly [];
+        readonly choice: {
+            readonly cardinality: "one";
+            readonly presentation: "emoji";
+            readonly completion: "selection";
+            readonly allowEmptyConfig: false;
+        };
+        readonly actionOwner: "step";
+        readonly allowedCustomEvents: readonly [];
+        readonly forbiddenCapabilities: readonly FunnelStepCapability[];
+        readonly terminal: false;
+    };
+    readonly multi_select_choice: {
+        readonly family: "choice";
+        readonly description: "Multiple options are selected before explicit completion.";
+        readonly allowedKinds: readonly [];
+        readonly choice: {
+            readonly cardinality: "many";
+            readonly presentation: "standard";
+            readonly completion: "explicit";
+            readonly allowEmptyConfig: true;
+        };
+        readonly actionOwner: "either";
+        readonly allowedCustomEvents: readonly [];
+        readonly forbiddenCapabilities: readonly FunnelStepCapability[];
+        readonly terminal: false;
+    };
+    readonly form_input: {
+        readonly family: "form";
+        readonly description: "Non-choice structured input, including reserved email capture.";
+        readonly allowedKinds: readonly [];
+        readonly actionOwner: "either";
+        readonly allowedCustomEvents: readonly ["email_captured"];
+        readonly forbiddenCapabilities: readonly FunnelStepCapability[];
+        readonly terminal: false;
+    };
+    readonly social_proof: {
+        readonly family: "content";
+        readonly description: "Testimonials, reviews, credibility, or evidence.";
+        readonly allowedKinds: readonly [];
+        readonly actionOwner: "shared-shell";
+        readonly allowedCustomEvents: readonly [];
+        readonly forbiddenCapabilities: readonly FunnelStepCapability[];
+        readonly terminal: false;
+    };
+    readonly progress_interstitial: {
+        readonly family: "transition";
+        readonly description: "Progress, calculation, loading, reveal, or transition screen.";
+        readonly allowedKinds: readonly [];
+        readonly actionOwner: "either";
+        readonly allowedCustomEvents: readonly [];
+        readonly forbiddenCapabilities: readonly FunnelStepCapability[];
+        readonly terminal: false;
+    };
+    readonly paywall_offer: {
+        readonly family: "commerce";
+        readonly description: "A monetization offer that presents purchasable plans.";
+        readonly allowedKinds: readonly ["paywall"];
+        readonly requiredKind: "paywall";
+        readonly actionOwner: "step";
+        readonly allowedCustomEvents: readonly ["checkout_started", "add_payment_info", "checkout_completed"];
+        readonly forbiddenCapabilities: readonly FunnelStepCapability[];
+        readonly terminal: false;
+        readonly analyticsRole: "paywall";
+    };
+    readonly upsell_offer: {
+        readonly family: "commerce";
+        readonly description: "A post-purchase or upgrade offer.";
+        readonly allowedKinds: readonly ["upsell"];
+        readonly requiredKind: "upsell";
+        readonly actionOwner: "step";
+        readonly allowedCustomEvents: readonly ["checkout_started", "add_payment_info", "checkout_completed"];
+        readonly forbiddenCapabilities: readonly FunnelStepCapability[];
+        readonly terminal: false;
+    };
+    readonly checkout: {
+        readonly family: "commerce";
+        readonly description: "A dedicated payment-entry screen.";
+        readonly allowedKinds: readonly [];
+        readonly actionOwner: "step";
+        readonly allowedCustomEvents: readonly ["checkout_started", "add_payment_info", "checkout_completed"];
+        readonly forbiddenCapabilities: readonly FunnelStepCapability[];
+        readonly terminal: false;
+    };
+    readonly subscription_management: {
+        readonly family: "commerce";
+        readonly description: "A screen for managing or inspecting an existing subscription.";
+        readonly allowedKinds: readonly ["manage-subscription"];
+        readonly requiredKind: "manage-subscription";
+        readonly actionOwner: "step";
+        readonly allowedCustomEvents: readonly [];
+        readonly forbiddenCapabilities: readonly FunnelStepCapability[];
+        readonly terminal: false;
+    };
+    readonly subscription_handoff: {
+        readonly family: "commerce";
+        readonly description: "A non-terminal app, store, or deep-link handoff.";
+        readonly allowedKinds: readonly ["subscription-handoff"];
+        readonly requiredKind: "subscription-handoff";
+        readonly actionOwner: "step";
+        readonly allowedCustomEvents: readonly [];
+        readonly forbiddenCapabilities: readonly FunnelStepCapability[];
+        readonly terminal: false;
+    };
+    readonly cancellation_offer: {
+        readonly family: "commerce";
+        readonly description: "A cancellation retention or downsell surface.";
+        readonly allowedKinds: readonly ["cancellation"];
+        readonly requiredKind: "cancellation";
+        readonly actionOwner: "step";
+        readonly allowedCustomEvents: readonly [];
+        readonly forbiddenCapabilities: readonly FunnelStepCapability[];
+        readonly terminal: false;
+    };
+    readonly summary_confirmation: {
+        readonly family: "content";
+        readonly description: "A summary, review, or confirmation before the next action.";
+        readonly allowedKinds: readonly [];
+        readonly actionOwner: "either";
+        readonly allowedCustomEvents: readonly [];
+        readonly forbiddenCapabilities: readonly FunnelStepCapability[];
+        readonly terminal: false;
+    };
+    readonly complete_registration: {
+        readonly family: "terminal";
+        readonly description: "The canonical post-purchase terminal that continues into the app.";
+        readonly allowedKinds: readonly ["subscription-handoff"];
+        readonly requiredKind: "subscription-handoff";
+        readonly actionOwner: "step";
+        readonly allowedCustomEvents: readonly ["funnel_completed"];
+        readonly forbiddenCapabilities: readonly FunnelStepCapability[];
+        readonly terminal: true;
+        readonly analyticsRole: "complete-registration";
+    };
+    readonly purchase_completed: {
+        readonly family: "terminal";
+        readonly description: "The canonical terminal shown after a verified initial purchase.";
+        readonly allowedKinds: readonly ["subscription-handoff"];
+        readonly requiredKind: "subscription-handoff";
+        readonly actionOwner: "step";
+        readonly allowedCustomEvents: readonly ["funnel_completed"];
+        readonly forbiddenCapabilities: readonly FunnelStepCapability[];
+        readonly terminal: true;
+        readonly analyticsRole: "purchase-completed";
+    };
+};
+export type FunnelStepType = keyof typeof FUNNEL_STEP_CONTRACTS;
+export declare const FUNNEL_STEP_TYPES: readonly ("intro_hero" | "purchase_completed" | "checkout" | "value_prop_story" | "single_step_choice" | "single_step_choice_emoji" | "multi_select_choice" | "form_input" | "social_proof" | "progress_interstitial" | "paywall_offer" | "upsell_offer" | "subscription_management" | "subscription_handoff" | "cancellation_offer" | "summary_confirmation" | "complete_registration")[];
+export type FunnelReservedStepExactContract = {
+    match: 'exact';
+    id: string;
+    name: string;
+    type: FunnelStepType;
+    kind?: FunnelStepKind;
+    unique: boolean;
+    primary?: boolean;
+};
+export type FunnelReservedStepPatternContract = {
+    match: 'pattern';
+    idPattern: string;
+    namePattern: string;
+    type: FunnelStepType;
+    kind?: FunnelStepKind;
+    unique: boolean;
+    primary?: boolean;
+};
+export type FunnelReservedStepContract = FunnelReservedStepExactContract | FunnelReservedStepPatternContract;
+export declare const FUNNEL_RESERVED_STEP_CONTRACTS: {
+    readonly 'email-capture': {
+        readonly match: "exact";
+        readonly id: "email-capture";
+        readonly name: "email-capture";
+        readonly type: "form_input";
+        readonly unique: true;
+    };
+    readonly paywall: {
+        readonly match: "exact";
+        readonly id: "paywall";
+        readonly name: "paywall";
+        readonly type: "paywall_offer";
+        readonly kind: "paywall";
+        readonly unique: true;
+        readonly primary: true;
+    };
+    readonly 'paywall-variant': {
+        readonly match: "pattern";
+        readonly idPattern: "^paywall-[a-z0-9-]+$";
+        readonly namePattern: "^paywall-[a-z0-9-]+$";
+        readonly type: "paywall_offer";
+        readonly kind: "paywall";
+        readonly unique: false;
+        readonly primary: false;
+    };
+    readonly 'subscription-started': {
+        readonly match: "exact";
+        readonly id: "subscription-started";
+        readonly name: "subscription-started";
+        readonly type: "purchase_completed";
+        readonly kind: "subscription-handoff";
+        readonly unique: true;
+    };
+    readonly 'manage-subscription': {
+        readonly match: "exact";
+        readonly id: "manage-subscription";
+        readonly name: "manage-subscription";
+        readonly type: "subscription_management";
+        readonly kind: "manage-subscription";
+        readonly unique: true;
+    };
+};
+export declare const resolveStepTypeContract: (version: number, type: string) => FunnelStepContractDefinition | undefined;
+export declare const resolveReservedStepContract: (version: number, identity: string) => FunnelReservedStepContract | undefined;
+export type FunnelStepTypeScope = readonly FunnelStepType[] | 'any';
+export type FunnelStepIdentityScope = readonly string[] | 'any';
+export type FunnelStepCapabilityRule = {
+    allowedStepTypes: FunnelStepTypeScope;
+    allowedStepIdentities: FunnelStepIdentityScope;
+    requiredOwner: string;
+};
+export declare const FUNNEL_STEP_CAPABILITY_RULES: {
+    readonly 'choice-write': {
+        readonly allowedStepTypes: readonly ["single_step_choice", "single_step_choice_emoji", "multi_select_choice"];
+        readonly allowedStepIdentities: "any";
+        readonly requiredOwner: "useStepChoices";
+    };
+    readonly 'email-capture': {
+        readonly allowedStepTypes: readonly ["form_input"];
+        readonly allowedStepIdentities: readonly ["email-capture"];
+        readonly requiredOwner: "submitEmailCapture";
+    };
+    readonly checkout: {
+        readonly allowedStepTypes: readonly ["paywall_offer", "upsell_offer", "checkout"];
+        readonly allowedStepIdentities: "any";
+        readonly requiredOwner: "named-payment-helpers";
+    };
+    readonly 'subscription-management': {
+        readonly allowedStepTypes: readonly ["subscription_management", "cancellation_offer"];
+        readonly allowedStepIdentities: "any";
+        readonly requiredOwner: "runtime-subscription-helpers";
+    };
+    readonly 'subscription-handoff': {
+        readonly allowedStepTypes: readonly ["subscription_handoff", "complete_registration", "purchase_completed"];
+        readonly allowedStepIdentities: "any";
+        readonly requiredOwner: "runtime-handoff-helper";
+    };
+    readonly 'hardcoded-navigation': {
+        readonly allowedStepTypes: readonly [];
+        readonly allowedStepIdentities: readonly [];
+        readonly requiredOwner: "manifest-flow-controller";
+    };
+    readonly 'provider-direct-analytics': {
+        readonly allowedStepTypes: readonly [];
+        readonly allowedStepIdentities: readonly [];
+        readonly requiredOwner: "analytics-adapter-outbox";
+    };
+    readonly 'browser-registration-completed': {
+        readonly allowedStepTypes: readonly [];
+        readonly allowedStepIdentities: readonly [];
+        readonly requiredOwner: "trusted-subscription-claim-server";
+    };
+};
+export type FunnelAnalyticsEventOwner = 'controller' | 'transactional-server' | 'named-helper' | 'terminal-helper' | 'trusted-server';
+export type FunnelAnalyticsEventDedupeScope = 'funnel-run' | 'step-visit' | 'logical-email-conversion' | 'event-id' | 'subscription-claim' | 'provider-payment';
+export type FunnelAnalyticsEventContract = {
+    rawName: string;
+    publicName: FunnelAnalyticsEventName;
+    owner: FunnelAnalyticsEventOwner;
+    automatic: boolean;
+    requiredMetadata: readonly string[];
+    allowedStepTypes: FunnelStepTypeScope;
+    allowedStepIdentities: FunnelStepIdentityScope;
+    dedupeScope: FunnelAnalyticsEventDedupeScope;
+};
+export declare const FUNNEL_ANALYTICS_EVENT_CONTRACTS: {
+    readonly funnel_started: {
+        readonly rawName: "funnel_start";
+        readonly publicName: "funnel_started";
+        readonly owner: "controller";
+        readonly automatic: true;
+        readonly requiredMetadata: readonly ["funnelId", "funnelVersionId", "environment", "stepContractVersion"];
+        readonly allowedStepTypes: "any";
+        readonly allowedStepIdentities: "any";
+        readonly dedupeScope: "funnel-run";
+    };
+    readonly step_started: {
+        readonly rawName: "step_start";
+        readonly publicName: "step_started";
+        readonly owner: "controller";
+        readonly automatic: true;
+        readonly requiredMetadata: readonly ["funnelId", "funnelVersionId", "environment", "stepContractVersion", "stepId", "stepName", "stepType"];
+        readonly allowedStepTypes: "any";
+        readonly allowedStepIdentities: "any";
+        readonly dedupeScope: "step-visit";
+    };
+    readonly step_completed: {
+        readonly rawName: "step_end";
+        readonly publicName: "step_completed";
+        readonly owner: "controller";
+        readonly automatic: true;
+        readonly requiredMetadata: readonly ["funnelId", "funnelVersionId", "environment", "stepContractVersion", "stepId", "stepName", "stepType"];
+        readonly allowedStepTypes: "any";
+        readonly allowedStepIdentities: "any";
+        readonly dedupeScope: "step-visit";
+    };
+    readonly step_exited: {
+        readonly rawName: "step_exit";
+        readonly publicName: "step_exited";
+        readonly owner: "controller";
+        readonly automatic: true;
+        readonly requiredMetadata: readonly ["funnelId", "funnelVersionId", "environment", "stepContractVersion", "stepId", "stepName", "stepType"];
+        readonly allowedStepTypes: "any";
+        readonly allowedStepIdentities: "any";
+        readonly dedupeScope: "step-visit";
+    };
+    readonly first_step_viewed: {
+        readonly rawName: "first_step_viewed";
+        readonly publicName: "first_step_viewed";
+        readonly owner: "controller";
+        readonly automatic: true;
+        readonly requiredMetadata: readonly ["funnelId", "funnelVersionId", "environment", "stepContractVersion", "stepId", "stepName", "stepType"];
+        readonly allowedStepTypes: "any";
+        readonly allowedStepIdentities: "any";
+        readonly dedupeScope: "step-visit";
+    };
+    readonly first_step_clicked: {
+        readonly rawName: "first_step_clicked";
+        readonly publicName: "first_step_clicked";
+        readonly owner: "controller";
+        readonly automatic: true;
+        readonly requiredMetadata: readonly ["funnelId", "funnelVersionId", "environment", "stepContractVersion", "stepId", "stepName", "stepType"];
+        readonly allowedStepTypes: "any";
+        readonly allowedStepIdentities: "any";
+        readonly dedupeScope: "step-visit";
+    };
+    readonly step_engaged: {
+        readonly rawName: "step_engaged";
+        readonly publicName: "step_engaged";
+        readonly owner: "controller";
+        readonly automatic: false;
+        readonly requiredMetadata: readonly ["funnelId", "funnelVersionId", "environment", "stepContractVersion", "stepId", "stepName", "stepType", "durationMs"];
+        readonly allowedStepTypes: "any";
+        readonly allowedStepIdentities: "any";
+        readonly dedupeScope: "step-visit";
+    };
+    readonly email_captured: {
+        readonly rawName: "email_captured";
+        readonly publicName: "email_captured";
+        readonly owner: "transactional-server";
+        readonly automatic: false;
+        readonly requiredMetadata: readonly ["funnelId", "funnelVersionId", "environment", "stepContractVersion", "stepId", "stepName", "stepType", "projectId", "funnelEndUserId", "eventId"];
+        readonly allowedStepTypes: readonly ["form_input"];
+        readonly allowedStepIdentities: readonly ["email-capture"];
+        readonly dedupeScope: "logical-email-conversion";
+    };
+    readonly checkout_started: {
+        readonly rawName: "checkout_started";
+        readonly publicName: "checkout_started";
+        readonly owner: "named-helper";
+        readonly automatic: false;
+        readonly requiredMetadata: readonly ["funnelId", "funnelVersionId", "environment", "stepContractVersion", "stepId", "stepName", "stepType", "eventId"];
+        readonly allowedStepTypes: readonly ["paywall_offer", "upsell_offer", "checkout"];
+        readonly allowedStepIdentities: "any";
+        readonly dedupeScope: "event-id";
+    };
+    readonly add_payment_info: {
+        readonly rawName: "add_payment_info";
+        readonly publicName: "add_payment_info";
+        readonly owner: "named-helper";
+        readonly automatic: false;
+        readonly requiredMetadata: readonly ["funnelId", "funnelVersionId", "environment", "stepContractVersion", "stepId", "stepName", "stepType", "eventId"];
+        readonly allowedStepTypes: readonly ["paywall_offer", "upsell_offer", "checkout"];
+        readonly allowedStepIdentities: "any";
+        readonly dedupeScope: "event-id";
+    };
+    readonly checkout_completed: {
+        readonly rawName: "checkout_completed";
+        readonly publicName: "checkout_completed";
+        readonly owner: "named-helper";
+        readonly automatic: false;
+        readonly requiredMetadata: readonly ["funnelId", "funnelVersionId", "environment", "stepContractVersion", "stepId", "stepName", "stepType", "eventId"];
+        readonly allowedStepTypes: readonly ["paywall_offer", "upsell_offer", "checkout"];
+        readonly allowedStepIdentities: "any";
+        readonly dedupeScope: "event-id";
+    };
+    readonly funnel_completed: {
+        readonly rawName: "funnel_completed";
+        readonly publicName: "funnel_completed";
+        readonly owner: "terminal-helper";
+        readonly automatic: false;
+        readonly requiredMetadata: readonly ["funnelId", "funnelVersionId", "environment", "stepContractVersion", "stepId", "stepName", "stepType", "eventId"];
+        readonly allowedStepTypes: readonly ["complete_registration", "purchase_completed"];
+        readonly allowedStepIdentities: "any";
+        readonly dedupeScope: "funnel-run";
+    };
+    readonly registration_completed: {
+        readonly rawName: "registration_completed";
+        readonly publicName: "registration_completed";
+        readonly owner: "trusted-server";
+        readonly automatic: false;
+        readonly requiredMetadata: readonly ["funnelId", "funnelVersionId", "environment", "stepContractVersion", "projectId", "funnelEndUserId", "eventId", "subscriptionClaimId"];
+        readonly allowedStepTypes: readonly [];
+        readonly allowedStepIdentities: readonly [];
+        readonly dedupeScope: "subscription-claim";
+    };
+    readonly purchase_completed: {
+        readonly rawName: "purchase_completed";
+        readonly publicName: "purchase_completed";
+        readonly owner: "trusted-server";
+        readonly automatic: false;
+        readonly requiredMetadata: readonly ["funnelId", "funnelVersionId", "environment", "stepContractVersion", "projectId", "funnelEndUserId", "eventId", "providerPaymentId", "purchaseKind"];
+        readonly allowedStepTypes: readonly [];
+        readonly allowedStepIdentities: readonly [];
+        readonly dedupeScope: "provider-payment";
+    };
+};
+export declare const DEFERRABLE_FUNNEL_CONTRACT_DIAGNOSTIC_CODES: readonly ["FG-PARITY-001", "FG-REGISTRY-001", "FG-CONTENT-001", "FG-FLOW-001"];
+export type DeferrableFunnelContractDiagnosticCode = (typeof DEFERRABLE_FUNNEL_CONTRACT_DIAGNOSTIC_CODES)[number];