@funnelsgrove/runtime 0.1.55 → 0.1.59

package/dist/runtime/use-step-choices.d.ts

@@ -0,0 +1,58 @@
+import { type ReactNode } from 'react';
+import { type FunnelChoiceCompletion } from '../steps/choice-contract.js';
+import { type FunnelChoiceOption, type FunnelEmojiChoiceOption } from '../steps/step-contract.js';
+import type { FunnelStepMeta } from '../steps/types.js';
+import { type FunnelContractDiagnostic } from '../validation/funnel-contract-diagnostics.js';
+type ChoiceOptions = readonly (FunnelChoiceOption | FunnelEmojiChoiceOption)[];
+type ChoiceResult = FunnelChoiceCompletion | FunnelContractDiagnostic;
+type ChoiceCommit = (stepMeta: FunnelStepMeta, result: ChoiceResult) => void;
+export type FunnelStepChoices = {
+    selectSingle: (optionId: string) => void;
+    completeMulti: (optionIds: readonly string[]) => void;
+};
+export declare const createStepChoiceActions: (stepMeta: FunnelStepMeta, options: ChoiceOptions, commit: ChoiceCommit) => FunnelStepChoices;
+export declare const registerInternalChoiceCommit: (carrier: object, commit: ChoiceCommit) => void;
+export declare const FunnelChoiceCommitProvider: ({ carrier, children, }: {
+    carrier: object;
+    children: ReactNode;
+}) => import("react").FunctionComponentElement<import("react").ProviderProps<ChoiceCommit | null>>;
+export declare const useStepChoices: (stepMeta: FunnelStepMeta, options: ChoiceOptions) => FunnelStepChoices;
+export type AtomicChoiceCommitResult = 'committed' | 'ignored' | 'quarantined' | 'record-failed';
+export declare const consumeChoiceCompletionMarker: (marker: string | null, previousStepId: string) => {
+    consumed: boolean;
+    nextMarker: string | null;
+};
+type AtomicChoiceCommitInput<StepId extends string> = {
+    activeStepId: StepId;
+    activeStepMeta: FunnelStepMeta | undefined;
+    stepMeta: FunnelStepMeta;
+    result: ChoiceResult;
+    environment: 'development' | 'production' | 'test';
+    getAttributes: () => Record<string, unknown>;
+    writeAttributes: (attributes: Record<string, unknown>) => void;
+    isInFlight: () => boolean;
+    beginCommit: () => void;
+    cancelCommit: () => void;
+    recordCompletion: (input: {
+        selected?: Record<string, unknown>;
+        metadata?: Record<string, unknown>;
+    }) => boolean;
+    markCompletedBeforeNavigation: () => void;
+    clearCompletedBeforeNavigation: (markerWasInstalled: boolean) => void;
+    resolveNext: (attributes: Record<string, unknown>) => StepId;
+    navigate: (stepId: StepId) => void;
+    reportDiagnostic: (diagnostic: FunnelContractDiagnostic) => void;
+};
+export declare const runAtomicChoiceCommit: <StepId extends string>(input: AtomicChoiceCommitInput<StepId>) => AtomicChoiceCommitResult;
+type ChoiceBypassOperation = 'setAnswer' | 'setAttribute' | 'goChoice' | 'completeStep';
+export declare const enforceChoiceBypassGuard: (input: {
+    operation: ChoiceBypassOperation;
+    activeStepId: string;
+    sourceStepId?: string;
+    key?: string;
+    stepById: Record<string, FunnelStepMeta>;
+    stepContractVersion: number;
+    environment: "development" | "production" | "test";
+    reportDiagnostic: (diagnostic: FunnelContractDiagnostic) => void;
+}) => boolean;
+export {};

package/dist/runtime/use-step-choices.js

@@ -0,0 +1,187 @@
+'use client';
+import { createContext, createElement, useContext, useMemo, } from 'react';
+import { buildChoiceCompletion, parseFunnelChoiceDescriptor, } from '../steps/choice-contract.js';
+import { LEGACY_UNVERSIONED_STEP_CONTRACT_VERSION, SUPPORTED_STEP_CONTRACT_VERSIONS, } from '../steps/step-contract.js';
+import { createFunnelContractDiagnostic, } from '../validation/funnel-contract-diagnostics.js';
+export const createStepChoiceActions = (stepMeta, options, commit) => ({
+    selectSingle: (optionId) => commit(stepMeta, buildChoiceCompletion(stepMeta, options, optionId)),
+    completeMulti: (optionIds) => commit(stepMeta, buildChoiceCompletion(stepMeta, options, optionIds)),
+});
+const FunnelChoiceCommitContext = createContext(null);
+const internalChoiceCommits = new WeakMap();
+export const registerInternalChoiceCommit = (carrier, commit) => {
+    internalChoiceCommits.set(carrier, commit);
+};
+export const FunnelChoiceCommitProvider = ({ carrier, children, }) => {
+    var _a;
+    return createElement(FunnelChoiceCommitContext.Provider, { value: (_a = internalChoiceCommits.get(carrier)) !== null && _a !== void 0 ? _a : null }, children);
+};
+export const useStepChoices = (stepMeta, options) => {
+    const commit = useContext(FunnelChoiceCommitContext);
+    if (!commit) {
+        throw new Error('useStepChoices must be used inside FunnelProvider');
+    }
+    return useMemo(() => createStepChoiceActions(stepMeta, options, commit), [commit, options, stepMeta]);
+};
+const isChoiceCompletion = (value) => {
+    try {
+        return typeof value === 'object'
+            && value !== null
+            && typeof value.answerKey === 'string'
+            && 'selected' in value
+            && 'value' in value;
+    }
+    catch (_a) {
+        return false;
+    }
+};
+const choiceIdentityMatches = (candidate, active) => {
+    if (!active) {
+        return false;
+    }
+    try {
+        const candidateDescriptor = parseFunnelChoiceDescriptor(candidate.type, candidate.choice);
+        const activeDescriptor = parseFunnelChoiceDescriptor(active.type, active.choice);
+        return candidate.id === active.id
+            && candidate.type === active.type
+            && candidateDescriptor.ok
+            && activeDescriptor.ok
+            && candidateDescriptor.descriptor.answerKey === activeDescriptor.descriptor.answerKey
+            && candidateDescriptor.descriptor.allowEmpty === activeDescriptor.descriptor.allowEmpty;
+    }
+    catch (_a) {
+        return false;
+    }
+};
+export const consumeChoiceCompletionMarker = (marker, previousStepId) => marker === previousStepId
+    ? { consumed: true, nextMarker: null }
+    : { consumed: false, nextMarker: marker };
+export const runAtomicChoiceCommit = (input) => {
+    if (input.isInFlight()) {
+        return 'ignored';
+    }
+    const completion = isChoiceCompletion(input.result) ? input.result : null;
+    if (completion === null) {
+        const diagnostic = input.result;
+        if (diagnostic.stepId !== input.activeStepId) {
+            input.reportDiagnostic(diagnostic);
+            return 'ignored';
+        }
+        if (input.environment !== 'production') {
+            throw new Error(`${diagnostic.code}: ${diagnostic.reason}`);
+        }
+        input.beginCommit();
+        const currentAttributes = input.getAttributes();
+        let abortStarted = false;
+        let markerInstallationStarted = false;
+        const abortCommit = () => {
+            if (abortStarted) {
+                return;
+            }
+            abortStarted = true;
+            try {
+                input.clearCompletedBeforeNavigation(markerInstallationStarted);
+            }
+            finally {
+                input.cancelCommit();
+            }
+        };
+        try {
+            input.reportDiagnostic(diagnostic);
+            const nextStepId = input.resolveNext(currentAttributes);
+            if (!input.recordCompletion({})) {
+                abortCommit();
+                return 'record-failed';
+            }
+            markerInstallationStarted = true;
+            input.markCompletedBeforeNavigation();
+            input.navigate(nextStepId);
+            return 'quarantined';
+        }
+        catch (error) {
+            abortCommit();
+            throw error;
+        }
+    }
+    if (input.activeStepId !== input.stepMeta.id
+        || !choiceIdentityMatches(input.stepMeta, input.activeStepMeta)) {
+        return 'ignored';
+    }
+    input.beginCommit();
+    const currentAttributes = input.getAttributes();
+    let abortStarted = false;
+    let attributesWritten = false;
+    let markerInstallationStarted = false;
+    const abortCommit = () => {
+        if (abortStarted) {
+            return;
+        }
+        abortStarted = true;
+        try {
+            if (attributesWritten) {
+                input.writeAttributes(currentAttributes);
+            }
+        }
+        finally {
+            try {
+                input.clearCompletedBeforeNavigation(markerInstallationStarted);
+            }
+            finally {
+                input.cancelCommit();
+            }
+        }
+    };
+    try {
+        const nextAttributes = Object.assign(Object.assign({}, currentAttributes), { [completion.answerKey]: completion.value });
+        const nextStepId = input.resolveNext(nextAttributes);
+        attributesWritten = true;
+        input.writeAttributes(nextAttributes);
+        if (!input.recordCompletion({
+            selected: completion.selected,
+            metadata: { choice_answer_key: completion.answerKey },
+        })) {
+            abortCommit();
+            return 'record-failed';
+        }
+        markerInstallationStarted = true;
+        input.markCompletedBeforeNavigation();
+        input.navigate(nextStepId);
+        return 'committed';
+    }
+    catch (error) {
+        abortCommit();
+        throw error;
+    }
+};
+export const enforceChoiceBypassGuard = (input) => {
+    var _a;
+    const enforcesTypedChoices = SUPPORTED_STEP_CONTRACT_VERSIONS.some((version) => (version !== LEGACY_UNVERSIONED_STEP_CONTRACT_VERSION
+        && version === input.stepContractVersion));
+    if (!enforcesTypedChoices) {
+        return true;
+    }
+    const sourceStepId = (_a = input.sourceStepId) !== null && _a !== void 0 ? _a : input.activeStepId;
+    const sourceMeta = input.stepById[sourceStepId];
+    const activeMeta = input.stepById[input.activeStepId];
+    const shouldReject = input.operation === 'setAnswer' || input.operation === 'setAttribute'
+        ? Boolean((activeMeta === null || activeMeta === void 0 ? void 0 : activeMeta.choice) && input.key === activeMeta.choice.answerKey)
+        : Boolean(sourceMeta === null || sourceMeta === void 0 ? void 0 : sourceMeta.choice);
+    if (!shouldReject) {
+        return true;
+    }
+    const diagnostic = createFunnelContractDiagnostic({
+        code: 'FG-CHOICE-006',
+        file: null,
+        stepId: sourceStepId,
+        expected: 'useStepChoices',
+        received: { operation: input.operation },
+        reason: 'A generic answer or completion API attempted to bypass the typed choice transaction.',
+        guide: 'docs/product-specs/funnel-template-step-authoring.md',
+        repair: 'Complete descriptor-bearing choice steps with useStepChoices.',
+    });
+    if (input.environment !== 'production') {
+        throw new Error(`${diagnostic.code}: ${diagnostic.reason}`);
+    }
+    input.reportDiagnostic(diagnostic);
+    return false;
+};

package/dist/sdk/userAnswers.d.ts

@@ -1,4 +1,5 @@
 import type { FunnelStepId } from '../runtime/funnel-runtime.js';
+export type FunnelAnswerKey = string;
 export type FunnelBinaryChoice = 'yes' | 'no';
 export type FunnelBirthDate = {
     year: number;

package/dist/services/api.service.d.ts

@@ -51,6 +51,11 @@ export type TempPhotoUploadResult = {
     sizeBytes: number;
     uploadedAt: string;
 };
+export type EmailCaptureResult = {
+    user: AppUser;
+    eventId: string;
+    eventCreated: boolean;
+};
 declare class ApiService {
     private readFileAsDataUrl;
     getOrCreateClientUserId(): string;
@@ -68,6 +73,11 @@ declare class ApiService {
     updateUser(user: AppUser, options?: {
         attribution?: FunnelUserAttribution;
     }): Promise<AppUser>;
+    captureEmail(input: {
+        userId: string;
+        email: string;
+        environment: 'test' | 'live';
+    }): Promise<EmailCaptureResult>;
     syncUrlUserAttributes(input: {
         user: AppUserInput;
         attributes?: FunnelUserAnswers;

package/dist/services/api.service.js

@@ -286,6 +286,38 @@ class ApiService {
             fallbackDocument: withMergedAttributionDocument(user.document, options === null || options === void 0 ? void 0 : options.attribution),
         });
     }
+    async captureEmail(input) {
+        var _a, _b;
+        const userId = input.userId.trim();
+        const email = input.email.trim().toLowerCase();
+        const payload = await funnelSdkService.captureEmail({
+            userId,
+            email,
+            environment: input.environment,
+        });
+        const eventId = asString(payload.eventId);
+        const responseUser = isRecord(payload.user) ? payload.user : null;
+        const responseUserId = responseUser === null || responseUser === void 0 ? void 0 : responseUser.user_id;
+        const responseEmail = (_b = (_a = asString(responseUser === null || responseUser === void 0 ? void 0 : responseUser.email)) === null || _a === void 0 ? void 0 : _a.toLowerCase()) !== null && _b !== void 0 ? _b : null;
+        if (!eventId
+            || typeof payload.eventCreated !== 'boolean'
+            || !responseUser
+            || typeof responseUserId !== 'string'
+            || responseUserId !== userId
+            || responseEmail !== email) {
+            throw new Error('Invalid email capture response');
+        }
+        const persistedUserId = persistUserId(userId, FUNNEL_ID);
+        return {
+            user: toAppUser({
+                apiUser: Object.assign(Object.assign({}, responseUser), { user_id: userId, email }),
+                userId: persistedUserId,
+                fallbackEmail: email,
+            }),
+            eventId,
+            eventCreated: payload.eventCreated,
+        };
+    }
     async syncUrlUserAttributes(input) {
         var _a;
         if (!hasUrlUserProfileAttributes(input.urlAttributes)) {

package/dist/services/funnel-sdk.service.d.ts

@@ -20,6 +20,22 @@ export type FunnelSdkBootstrapUserInput = {
     attribution?: FunnelSdkJsonObject | null;
     runtimeConfig?: FunnelSdkRuntimeConfigOverrides;
 };
+export type FunnelSdkCaptureEmailInput = {
+    userId: string;
+    email: string;
+    environment: FunnelSdkRuntimeMode;
+    runtimeConfig?: FunnelSdkRuntimeConfigOverrides;
+};
+export type FunnelSdkCaptureEmailResponse = {
+    user: {
+        user_id?: unknown;
+        fullName?: unknown;
+        email?: unknown;
+        document?: unknown;
+    };
+    eventId: string;
+    eventCreated: boolean;
+};
 export type FunnelSdkGetCurrentUserInput = {
     userId: string;
     runtimeConfig?: FunnelSdkRuntimeConfigOverrides;
@@ -211,6 +227,7 @@ declare class FunnelSdkService {
     private getJson;
     private postJson;
     bootstrapUser<ResponsePayload = FunnelSdkJsonObject>(input?: FunnelSdkBootstrapUserInput): Promise<ResponsePayload>;
+    captureEmail(input: FunnelSdkCaptureEmailInput): Promise<FunnelSdkCaptureEmailResponse>;
     getCurrentUser<ResponsePayload = FunnelSdkJsonObject>(input: FunnelSdkGetCurrentUserInput): Promise<ResponsePayload>;
     getUserSubscriptionStatus<ResponsePayload = FunnelSdkJsonObject>(input?: FunnelSdkGetUserSubscriptionStatusInput): Promise<ResponsePayload>;
     claimUserSubscription<ResponsePayload = FunnelSdkJsonObject>(input: FunnelSdkClaimUserSubscriptionInput): Promise<ResponsePayload>;

package/dist/services/funnel-sdk.service.js

@@ -1,5 +1,6 @@
 import { buildMainApiUrl, FUNNEL_ID, FUNNEL_SDK_PUBLISHABLE_KEY, FUNNEL_VERSION_ID, } from './runtime-api.config.js';
 import { resolvePreviewPaymentPublishableKey } from './public-env.js';
+import { CURRENT_STEP_CONTRACT_VERSION } from '../steps/step-contract.js';
 const trimTrailingSlash = (value) => value.replace(/\/+$/, '');
 const toNormalizedPath = (path) => (path.startsWith('/') ? path : `/${path}`);
 const asTrimmedStringOrNull = (value) => {
@@ -113,6 +114,18 @@ class FunnelSdkService {
             errorMessage: 'Failed to bootstrap user session',
         });
     }
+    async captureEmail(input) {
+        return this.postJson('/sdk/public/users/email-capture', {
+            runtimeConfig: input.runtimeConfig,
+            body: {
+                user_id: input.userId,
+                email: input.email,
+                environment: input.environment,
+                stepContractVersion: CURRENT_STEP_CONTRACT_VERSION,
+            },
+            errorMessage: 'Failed to capture email',
+        });
+    }
     async getCurrentUser(input) {
         const { funnelId } = resolveRuntimeConfig(input.runtimeConfig);
         return this.getJson('/sdk/public/users/me', {

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

@@ -0,0 +1,33 @@
+import type { FunnelAnswerKey } from '../sdk/userAnswers.js';
+import { type FunnelContractDiagnostic } from '../validation/funnel-contract-diagnostics.js';
+import { FUNNEL_STEP_CONTRACTS, type FunnelChoiceDescriptor, type FunnelChoiceOption, type FunnelEmojiChoiceOption, type FunnelStepChoiceContract, type FunnelStepType } from './step-contract.js';
+import type { FunnelStepMeta } from './types.js';
+export type FunnelChoiceStepType = {
+    [Type in FunnelStepType]: (typeof FUNNEL_STEP_CONTRACTS)[Type] extends {
+        readonly choice: FunnelStepChoiceContract;
+    } ? Type : never;
+}[FunnelStepType];
+export declare const FUNNEL_CHOICE_STEP_TYPES: readonly FunnelChoiceStepType[];
+export type FunnelChoiceValue = string | string[];
+export type FunnelChoiceCompletion = {
+    answerKey: FunnelAnswerKey;
+    value: FunnelChoiceValue;
+    selected: Record<string, FunnelChoiceValue>;
+};
+type FunnelChoiceStepMeta = Pick<FunnelStepMeta, 'id' | 'type' | 'choice'>;
+type FunnelChoiceOptions = readonly (FunnelChoiceOption | FunnelEmojiChoiceOption)[];
+export declare const MAX_FUNNEL_CHOICE_ITEMS = 4096;
+export declare const MAX_FUNNEL_CHOICE_IDENTIFIER_LENGTH = 256;
+export declare const MAX_FUNNEL_CHOICE_CONTENT_STRING_LENGTH = 4096;
+export type FunnelChoiceDescriptorParseResult = {
+    ok: true;
+    descriptor: FunnelChoiceDescriptor;
+    contract: FunnelStepChoiceContract;
+    stepType: FunnelChoiceStepType;
+} | {
+    ok: false;
+    issue: 'not-choice-step-type' | 'invalid-descriptor-shape' | 'invalid-answer-key' | 'invalid-allow-empty';
+};
+export declare const parseFunnelChoiceDescriptor: (stepType: unknown, choice: unknown) => FunnelChoiceDescriptorParseResult;
+export declare const buildChoiceCompletion: (stepMeta: FunnelChoiceStepMeta, options: FunnelChoiceOptions, ids: string | readonly string[]) => FunnelChoiceCompletion | FunnelContractDiagnostic;
+export {};