@funnelsgrove/runtime 0.7.6 → 0.7.8

package/dist/components/FunnelContext.d.ts

@@ -21,6 +21,7 @@ export type FunnelContextValue = {
     activeStepId: FunnelStepId;
     featureFlags: Record<string, string>;
     isBuilder: boolean;
+    isReturningSubscriber: boolean;
     goToStep: (stepId: string, outcome: FunnelNavigationOutcome) => void;
     goNext: () => void;
     goChoice: (choice: 'yes' | 'no', stepId?: string) => void;

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

@@ -2,6 +2,8 @@ export type EmailCapturePersistenceResult<User> = {
     user: User;
     eventId: string;
     eventCreated: boolean;
+    canonicalUser: User | null;
+    activeSubscription: boolean;
 };
 export type EmailCaptureSingleFlight = {
     current: Promise<void> | null;
@@ -13,10 +15,11 @@ export type SubmitEmailCaptureInput<User> = {
     retryPendingNavigation?: () => boolean | Promise<boolean>;
     persist: (email: string) => Promise<EmailCapturePersistenceResult<User>>;
     applyUser: (user: User) => void;
+    adoptCanonicalUser: (user: User) => void;
     applyPreviewEmail: (email: string) => void;
     fanOutBrowserDestinations: (eventId: string) => void | Promise<void>;
     completeVisit: () => boolean;
-    resolveNextStep: () => string | null;
+    resolveNextStep: (canonicalUser: User | null, activeSubscription: boolean) => string | null;
     navigate: (stepId: string) => void;
 };
 export declare const createEmailCaptureSingleFlight: () => EmailCaptureSingleFlight;

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

@@ -15,11 +15,15 @@ const runEmailCapture = async (input) => {
         return;
     }
     const email = normalizeEmail(input.email);
+    let canonicalUser = null;
+    let activeSubscription = false;
     if (input.isPreview) {
         input.applyPreviewEmail(email);
     }
     else {
         const result = await input.persist(email);
+        canonicalUser = result.canonicalUser;
+        activeSubscription = result.activeSubscription;
         input.applyUser(result.user);
         if (result.eventCreated) {
             try {
@@ -33,7 +37,10 @@ const runEmailCapture = async (input) => {
     if (!input.completeVisit()) {
         return;
     }
-    const nextStepId = input.resolveNextStep();
+    if (canonicalUser) {
+        input.adoptCanonicalUser(canonicalUser);
+    }
+    const nextStepId = input.resolveNextStep(canonicalUser, activeSubscription);
     if (nextStepId) {
         input.navigate(nextStepId);
     }

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

@@ -105,7 +105,7 @@ type FunnelFlowAnalyticsAdapter = {
         featureFlags?: Record<string, string>;
     }) => string | null;
 };
-export type FunnelFlowApiAdapter = Pick<typeof apiService, 'getOrCreateClientUserId' | 'getBootstrapCandidateUserId' | 'bootstrapSession' | 'pingUserContext' | 'updateUser' | 'captureEmail'>;
+export type FunnelFlowApiAdapter = Pick<typeof apiService, 'getOrCreateClientUserId' | 'getBootstrapCandidateUserId' | 'bootstrapSession' | 'pingUserContext' | 'persistCanonicalUserId' | 'updateUser' | 'captureEmail'>;
 type UseFunnelFlowControllerInput<StepId extends string> = {
     api?: FunnelFlowApiAdapter;
     analytics?: FunnelFlowAnalyticsAdapter;

package/dist/runtime/use-funnel-flow-controller.js

@@ -319,6 +319,7 @@ export function useFunnelFlowController({ api = apiService, analytics, stepContr
         completedSteps: [],
     }));
     const [userBootstrapped, setUserBootstrapped] = useState(isPreviewRuntime);
+    const [isReturningSubscriber, setIsReturningSubscriber] = useState(false);
     const [attributionReady, setAttributionReady] = useState(isPreviewRuntime);
     const attributesAtStepStart = useRef({});
     const attributesRef = useRef(attributes);
@@ -624,6 +625,7 @@ export function useFunnelFlowController({ api = apiService, analytics, stepContr
                     document: (_b = updatedUser.document) !== null && _b !== void 0 ? _b : {},
                 }, {
                     attribution: collectCurrentFunnelAttribution(),
+                    persistClientIdentity: false,
                 })
                     .catch((error) => {
                     logger.error('Failed to persist step completion:', error);
@@ -761,9 +763,15 @@ export function useFunnelFlowController({ api = apiService, analytics, stepContr
                 environment: getRuntimeMode(),
             }),
             applyUser: (capturedUser) => {
+                setIsReturningSubscriber(false);
                 currentUserIdRef.current = capturedUser.id;
                 setUser((prev) => (Object.assign(Object.assign(Object.assign({}, prev), capturedUser), { completedSteps: prev.completedSteps })));
             },
+            adoptCanonicalUser: (canonicalUser) => {
+                const canonicalUserId = api.persistCanonicalUserId(canonicalUser.id);
+                currentUserIdRef.current = canonicalUserId;
+                setUser((prev) => (Object.assign(Object.assign({}, prev), { id: canonicalUserId, email: canonicalUser.email, completedSteps: prev.completedSteps })));
+            },
             applyPreviewEmail: (normalizedEmail) => {
                 setUser((prev) => (Object.assign(Object.assign({}, prev), { email: normalizedEmail })));
             },
@@ -785,10 +793,21 @@ export function useFunnelFlowController({ api = apiService, analytics, stepContr
                     && ((_a = activeVisitTokenRef.current) === null || _a === void 0 ? void 0 : _a.visitId) === submittedVisitId
                     && claimActiveVisit(submittedStepId, { type: 'complete' }));
             },
-            resolveNextStep: () => {
-                const targetStepId = resolveNextStepId(submittedStepId, {
+            resolveNextStep: (_canonicalUser, activeSubscription) => {
+                var _a;
+                const manifestTargetStepId = resolveNextStepId(submittedStepId, {
                     ignoreExperiment: Boolean(activeExperimentForStep && submittedStepId === safeActiveStepId),
                 });
+                const handoffStepId = activeSubscription
+                    ? (_a = stepSequence.find((stepId) => {
+                        const step = stepById[stepId];
+                        return (step === null || step === void 0 ? void 0 : step.type) === 'purchase_completed'
+                            && step.kind === 'subscription-handoff'
+                            && Boolean(stepComponentById[stepId]);
+                    })) !== null && _a !== void 0 ? _a : null
+                    : null;
+                const targetStepId = handoffStepId || manifestTargetStepId;
+                setIsReturningSubscriber(Boolean(activeSubscription && handoffStepId));
                 if (submittedVisitId !== null) {
                     pendingEmailCaptureNavigationRef.current = {
                         visitId: submittedVisitId,
@@ -816,6 +835,8 @@ export function useFunnelFlowController({ api = apiService, analytics, stepContr
         resolveNextStepId,
         safeActiveStepId,
         stepById,
+        stepComponentById,
+        stepSequence,
     ]);
     useEffect(() => {
         const abandonCurrentVisit = (event) => {
@@ -1296,6 +1317,7 @@ export function useFunnelFlowController({ api = apiService, analytics, stepContr
             activeStepId: renderedStepId,
             featureFlags: postHogFeatureFlags,
             isBuilder: isPreviewRuntime,
+            isReturningSubscriber,
             goToStep: goToStepFromContext,
             goNext,
             goChoice,
@@ -1331,6 +1353,7 @@ export function useFunnelFlowController({ api = apiService, analytics, stepContr
         goNext,
         goToStepFromContext,
         isPreviewRuntime,
+        isReturningSubscriber,
         postHogFeatureFlags,
         renderedStepId,
         resolveRenderableStepId,

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

@@ -55,10 +55,13 @@ export type EmailCaptureResult = {
     user: AppUser;
     eventId: string;
     eventCreated: boolean;
+    canonicalUser: AppUser | null;
+    activeSubscription: boolean;
 };
 declare class ApiService {
     private readFileAsDataUrl;
     getOrCreateClientUserId(): string;
+    persistCanonicalUserId(userId: string): string;
     getSubscriptionManagementUserId(): string | null;
     getSubscriptionManagementStripeCustomerId(): string | null;
     getBootstrapCandidateUserId(fallbackUserId?: string | null): string | null;
@@ -72,6 +75,7 @@ declare class ApiService {
     }): Promise<AppUser>;
     updateUser(user: AppUser, options?: {
         attribution?: FunnelUserAttribution;
+        persistClientIdentity?: boolean;
     }): Promise<AppUser>;
     captureEmail(input: {
         userId: string;

package/dist/services/api.service.js

@@ -5,6 +5,7 @@ import { applyUrlUserAttributesToUser, hasUrlUserProfileAttributes, resolveUrlUs
 import { getRuntimeMode } from './runtime-mode.service.js';
 const DEFAULT_USER_ID_STORAGE_KEY = 'funnel:user-id';
 const DEFAULT_BOOTSTRAP_IDEMPOTENCY_KEY_STORAGE_KEY = 'funnel:bootstrap-idempotency-key';
+const SUBSCRIPTION_MANAGEMENT_LINK_ERROR = 'This subscription management link is invalid or has expired. Please request a new link or contact support.';
 const canUseDom = () => {
     return typeof window !== 'undefined';
 };
@@ -214,15 +215,15 @@ class ApiService {
         }
         return persistUserId(generateUserId(), FUNNEL_ID);
     }
-    getSubscriptionManagementUserId() {
-        const locationUserId = resolveUrlUserAttributes().userId;
-        if (locationUserId) {
-            return persistUserId(locationUserId, FUNNEL_ID);
-        }
-        if (this.getSubscriptionManagementStripeCustomerId()) {
-            return null;
+    persistCanonicalUserId(userId) {
+        const normalizedUserId = normalizeUserId(userId);
+        if (!normalizedUserId) {
+            throw new Error('Invalid canonical user id');
         }
-        return this.getOrCreateClientUserId();
+        return persistUserId(normalizedUserId, FUNNEL_ID);
+    }
+    getSubscriptionManagementUserId() {
+        return resolveUrlUserAttributes().userId;
     }
     getSubscriptionManagementStripeCustomerId() {
         return resolveUrlUserAttributes().stripeCustomerId;
@@ -313,7 +314,10 @@ class ApiService {
         });
     }
     async updateUser(user, options) {
-        const persistedUserId = persistUserId(user.id || this.getOrCreateClientUserId(), FUNNEL_ID);
+        const userId = normalizeUserId(user.id) || this.getOrCreateClientUserId();
+        const persistedUserId = (options === null || options === void 0 ? void 0 : options.persistClientIdentity) === false
+            ? userId
+            : persistUserId(userId, FUNNEL_ID);
         const publishableKey = getFunnelSdkPublishableKey();
         if (!publishableKey) {
             return toAppUser({
@@ -347,7 +351,7 @@ class ApiService {
         });
     }
     async captureEmail(input) {
-        var _a, _b;
+        var _a, _b, _c, _d;
         const userId = input.userId.trim();
         const email = input.email.trim().toLowerCase();
         const payload = await funnelSdkService.captureEmail({
@@ -359,15 +363,42 @@ class ApiService {
         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;
+        const canonicalUserValue = payload.canonicalUser;
+        const canonicalUserRecord = isRecord(canonicalUserValue)
+            ? canonicalUserValue
+            : null;
+        const canonicalUserId = asString(canonicalUserRecord === null || canonicalUserRecord === void 0 ? void 0 : canonicalUserRecord.user_id);
+        const canonicalUserEmail = (_d = (_c = asString(canonicalUserRecord === null || canonicalUserRecord === void 0 ? void 0 : canonicalUserRecord.email)) === null || _c === void 0 ? void 0 : _c.toLowerCase()) !== null && _d !== void 0 ? _d : null;
+        const hasCanonicalUser = canonicalUserValue !== undefined
+            && canonicalUserValue !== null;
+        const canonicalUserKeys = canonicalUserRecord
+            ? Object.keys(canonicalUserRecord)
+            : [];
         if (!eventId
             || typeof payload.eventCreated !== 'boolean'
+            || typeof payload.activeSubscription !== 'boolean'
             || !responseUser
             || typeof responseUserId !== 'string'
             || responseUserId !== userId
-            || responseEmail !== email) {
+            || responseEmail !== email
+            || (hasCanonicalUser
+                && (!canonicalUserRecord
+                    || !canonicalUserId
+                    || canonicalUserEmail !== email
+                    || canonicalUserKeys.length !== 2
+                    || canonicalUserKeys.some((key) => key !== 'user_id' && key !== 'email')))) {
             throw new Error('Invalid email capture response');
         }
         const persistedUserId = persistUserId(userId, FUNNEL_ID);
+        const canonicalUser = canonicalUserRecord && canonicalUserId
+            ? {
+                id: canonicalUserId,
+                name: '',
+                email,
+                attributes: {},
+                document: {},
+            }
+            : null;
         return {
             user: toAppUser({
                 apiUser: Object.assign(Object.assign({}, responseUser), { user_id: userId, email }),
@@ -376,6 +407,8 @@ class ApiService {
             }),
             eventId,
             eventCreated: payload.eventCreated,
+            canonicalUser,
+            activeSubscription: payload.activeSubscription,
         };
     }
     async syncUrlUserAttributes(input) {
@@ -468,15 +501,28 @@ class ApiService {
     async getManageSubscriptions() {
         const userId = this.getSubscriptionManagementUserId();
         const stripeCustomerId = this.getSubscriptionManagementStripeCustomerId();
-        return funnelSdkService.listSubscriptions({
+        if (!userId && !stripeCustomerId) {
+            throw new Error(SUBSCRIPTION_MANAGEMENT_LINK_ERROR);
+        }
+        const payload = await funnelSdkService.listSubscriptions({
             userId,
             stripeCustomerId,
             funnelId: FUNNEL_ID || undefined,
         });
+        if (!payload.user) {
+            throw new Error(SUBSCRIPTION_MANAGEMENT_LINK_ERROR);
+        }
+        if (userId) {
+            persistUserId(payload.user.user_id || userId, FUNNEL_ID);
+        }
+        return payload;
     }
     async updateSubscription(input) {
         const userId = this.getSubscriptionManagementUserId();
         const stripeCustomerId = this.getSubscriptionManagementStripeCustomerId();
+        if (!userId && !stripeCustomerId) {
+            throw new Error(SUBSCRIPTION_MANAGEMENT_LINK_ERROR);
+        }
         return funnelSdkService.updateSubscription({
             subscriptionId: input.subscriptionId,
             action: input.action,

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

@@ -36,6 +36,11 @@ export type FunnelSdkCaptureEmailResponse = {
         email?: unknown;
         document?: unknown;
     };
+    canonicalUser?: {
+        user_id?: unknown;
+        email?: unknown;
+    } | null;
+    activeSubscription: boolean;
     eventId: string;
     eventCreated: boolean;
 };

package/dist/testing/funnel-contract-journey-driver.js

@@ -193,6 +193,7 @@ export const runFunnelContractJourney = async (options) => {
         getBootstrapCandidateUserId: () => journeyUser.id,
         bootstrapSession: async () => journeyUser,
         pingUserContext: async () => null,
+        persistCanonicalUserId: (userId) => userId,
         updateUser: async (user) => user,
         captureEmail: async (captureInput) => {
             emailCaptureCalls.push(captureInput);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnelsgrove/runtime",
-  "version": "0.7.6",
+  "version": "0.7.8",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/The-Solid-Grove/funnelsgrove.git",