@funnelsgrove/runtime 0.1.3 → 0.1.5

package/dist/index.d.ts

@@ -16,6 +16,7 @@ export * from './runtime/preview-bridge.js';
 export * from './runtime/preview-definition-overrides.js';
 export * from './runtime/route-resolver.js';
 export * from './runtime/subscription-handoff.js';
+export * from './runtime/url-user-attributes.js';
 export * from './services/api.service.js';
 export * from './services/funnel-state.service.js';
 export * from './services/logger.js';

package/dist/index.js

@@ -16,6 +16,7 @@ export * from './runtime/preview-bridge.js';
 export * from './runtime/preview-definition-overrides.js';
 export * from './runtime/route-resolver.js';
 export * from './runtime/subscription-handoff.js';
+export * from './runtime/url-user-attributes.js';
 export * from './services/api.service.js';
 export * from './services/funnel-state.service.js';
 export * from './services/logger.js';

package/dist/runtime/url-user-attributes.d.ts

@@ -0,0 +1,17 @@
+import type { FunnelUserAnswers } from '../sdk/userAnswers.js';
+export type UrlUserAttributes = {
+    email: string | null;
+};
+export type UrlUserAttributeUser = {
+    email: string;
+    attributes?: FunnelUserAnswers;
+    document?: Record<string, unknown>;
+};
+export declare function normalizeUrlUserEmail(value: string | null | undefined): string | null;
+export declare function resolveUrlUserAttributes(search?: string): UrlUserAttributes;
+export declare function hasUrlUserAttributes(urlAttributes: UrlUserAttributes | null | undefined): boolean;
+export declare function applyUrlUserAttributesToUser<TUser extends UrlUserAttributeUser>(input: {
+    user: TUser;
+    attributes?: FunnelUserAnswers;
+    urlAttributes?: UrlUserAttributes | null;
+}): TUser;

package/dist/runtime/url-user-attributes.js

@@ -0,0 +1,38 @@
+const EMAIL_QUERY_KEY = 'email';
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+export function normalizeUrlUserEmail(value) {
+    const email = value === null || value === void 0 ? void 0 : value.trim();
+    if (!email || !EMAIL_PATTERN.test(email)) {
+        return null;
+    }
+    return email;
+}
+export function resolveUrlUserAttributes(search) {
+    if (typeof window === 'undefined' && typeof search !== 'string') {
+        return {
+            email: null,
+        };
+    }
+    try {
+        const params = new URLSearchParams(search !== null && search !== void 0 ? search : window.location.search);
+        return {
+            email: normalizeUrlUserEmail(params.get(EMAIL_QUERY_KEY)),
+        };
+    }
+    catch (_a) {
+        return {
+            email: null,
+        };
+    }
+}
+export function hasUrlUserAttributes(urlAttributes) {
+    return Boolean(urlAttributes === null || urlAttributes === void 0 ? void 0 : urlAttributes.email);
+}
+export function applyUrlUserAttributesToUser(input) {
+    var _a, _b, _c, _d;
+    const email = (_a = input.urlAttributes) === null || _a === void 0 ? void 0 : _a.email;
+    if (!email) {
+        return input.user;
+    }
+    return Object.assign(Object.assign({}, input.user), { email, attributes: Object.assign(Object.assign({}, ((_b = input.attributes) !== null && _b !== void 0 ? _b : {})), ((_c = input.user.attributes) !== null && _c !== void 0 ? _c : {})), document: (_d = input.user.document) !== null && _d !== void 0 ? _d : {} });
+}

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

@@ -12,6 +12,7 @@ import { collectCurrentFunnelAttribution } from './funnel-attribution.js';
 import { bootstrapPostHog, getPostHog, identifyPostHog, isPostHogReady, resolveExperimentVariant, } from './posthog-flags.js';
 import { isEditorEnabled, useRuntimeMode } from '../services/runtime-mode.service.js';
 import { isPreviewFrameRuntime } from '../services/preview-frame.service.js';
+const FIRST_STEP_ENGAGEMENT_THRESHOLD_MS = 1000;
 const buildFeatureFlagProperties = (featureFlags) => {
     return Object.fromEntries(Object.entries(featureFlags).map(([key, value]) => [`$feature/${key}`, value]));
 };
@@ -108,6 +109,7 @@ export function useFunnelFlowController({ initialStepId, lockToInitialStep = fal
     const postHogFeatureFlagsRef = useRef({});
     const prevStepIdRef = useRef(null);
     const stepStartedAtByIdRef = useRef({});
+    const engagedStepIdsRef = useRef(new Set());
     const currentUserIdRef = useRef(user.id);
     const safeActiveStepId = useMemo(() => { var _a; return (_a = resolveRenderableStepId(activeStepId)) !== null && _a !== void 0 ? _a : safeInitialStepId; }, [activeStepId, resolveRenderableStepId, safeInitialStepId]);
     const activeStepMeta = stepById[safeActiveStepId];
@@ -312,6 +314,7 @@ export function useFunnelFlowController({ initialStepId, lockToInitialStep = fal
             choices,
         };
         const startedAt = stepStartedAtByIdRef.current[meta.id] || record.completedAt;
+        const durationMs = Math.max(0, new Date(record.completedAt).getTime() - new Date(startedAt).getTime());
         dispatchWindowCustomEvent('funnel:step-completed', record);
         if (!isPreviewRuntime) {
             apiService.trackStepCompleted({
@@ -322,7 +325,7 @@ export function useFunnelFlowController({ initialStepId, lockToInitialStep = fal
                 endedAt: record.completedAt,
                 selected: record.choices,
             });
-            capturePostHogStepEvent('step_completed', Object.assign({ distinct_id: currentUserIdRef.current, funnel_id: FUNNEL_ID || undefined, funnel_version_id: FUNNEL_VERSION_ID || undefined, project_id: PROJECT_ID || undefined, step_id: record.stepId, step_name: record.stepName, started_at: startedAt, ended_at: record.completedAt, selected: record.choices }, buildFeatureFlagProperties(postHogFeatureFlagsRef.current)));
+            capturePostHogStepEvent('step_completed', Object.assign({ distinct_id: currentUserIdRef.current, funnel_id: FUNNEL_ID || undefined, funnel_version_id: FUNNEL_VERSION_ID || undefined, project_id: PROJECT_ID || undefined, step_id: record.stepId, step_name: record.stepName, started_at: startedAt, ended_at: record.completedAt, duration_ms: Number.isFinite(durationMs) ? durationMs : undefined, selected: record.choices }, buildFeatureFlagProperties(postHogFeatureFlagsRef.current)));
         }
         setUser((prev) => {
             var _a, _b;
@@ -363,22 +366,53 @@ export function useFunnelFlowController({ initialStepId, lockToInitialStep = fal
             recordStepCompletion(prevId);
         }
         const startedAt = new Date().toISOString();
+        const stepName = (activeStepMeta === null || activeStepMeta === void 0 ? void 0 : activeStepMeta.name) || (activeStepMeta === null || activeStepMeta === void 0 ? void 0 : activeStepMeta.title) || safeActiveStepId;
         stepStartedAtByIdRef.current[safeActiveStepId] = startedAt;
         if (!isPreviewRuntime) {
             apiService.trackStepStarted({
                 userId: currentUserIdRef.current,
                 stepId: safeActiveStepId,
-                stepName: (activeStepMeta === null || activeStepMeta === void 0 ? void 0 : activeStepMeta.name) || (activeStepMeta === null || activeStepMeta === void 0 ? void 0 : activeStepMeta.title) || safeActiveStepId,
+                stepName,
                 startedAt,
             });
-            capturePostHogStepEvent('step_started', Object.assign({ distinct_id: currentUserIdRef.current, funnel_id: FUNNEL_ID || undefined, funnel_version_id: FUNNEL_VERSION_ID || undefined, project_id: PROJECT_ID || undefined, step_id: safeActiveStepId, step_name: (activeStepMeta === null || activeStepMeta === void 0 ? void 0 : activeStepMeta.name) || (activeStepMeta === null || activeStepMeta === void 0 ? void 0 : activeStepMeta.title) || safeActiveStepId, started_at: startedAt }, buildFeatureFlagProperties(postHogFeatureFlagsRef.current)));
+            capturePostHogStepEvent('step_started', Object.assign({ distinct_id: currentUserIdRef.current, funnel_id: FUNNEL_ID || undefined, funnel_version_id: FUNNEL_VERSION_ID || undefined, project_id: PROJECT_ID || undefined, step_id: safeActiveStepId, step_name: stepName, started_at: startedAt }, buildFeatureFlagProperties(postHogFeatureFlagsRef.current)));
         }
         attributesAtStepStart.current = Object.assign({}, attributesRef.current);
         prevStepIdRef.current = safeActiveStepId;
+        if (isPreviewRuntime ||
+            safeActiveStepId !== defaultStepId ||
+            engagedStepIdsRef.current.has(safeActiveStepId)) {
+            return;
+        }
+        const engagedStepId = safeActiveStepId;
+        const engagedStartedAt = startedAt;
+        const engagedStepName = stepName;
+        const timer = window.setTimeout(() => {
+            if (prevStepIdRef.current !== engagedStepId || engagedStepIdsRef.current.has(engagedStepId)) {
+                return;
+            }
+            engagedStepIdsRef.current.add(engagedStepId);
+            const engagedAt = new Date().toISOString();
+            apiService.trackFunnelEvent({
+                userId: currentUserIdRef.current,
+                eventType: 'step_engaged',
+                stepId: engagedStepId,
+                stepName: engagedStepName,
+                startedAt: engagedStartedAt,
+                endedAt: engagedAt,
+                metadata: {
+                    durationMs: FIRST_STEP_ENGAGEMENT_THRESHOLD_MS,
+                    engagementThresholdMs: FIRST_STEP_ENGAGEMENT_THRESHOLD_MS,
+                },
+            });
+            capturePostHogStepEvent('step_engaged', Object.assign({ distinct_id: currentUserIdRef.current, funnel_id: FUNNEL_ID || undefined, funnel_version_id: FUNNEL_VERSION_ID || undefined, project_id: PROJECT_ID || undefined, step_id: engagedStepId, step_name: engagedStepName, started_at: engagedStartedAt, ended_at: engagedAt, duration_ms: FIRST_STEP_ENGAGEMENT_THRESHOLD_MS, engagement_threshold_ms: FIRST_STEP_ENGAGEMENT_THRESHOLD_MS }, buildFeatureFlagProperties(postHogFeatureFlagsRef.current)));
+        }, FIRST_STEP_ENGAGEMENT_THRESHOLD_MS);
+        return () => window.clearTimeout(timer);
     }, [
         activeStepId,
         activeStepMeta === null || activeStepMeta === void 0 ? void 0 : activeStepMeta.name,
         activeStepMeta === null || activeStepMeta === void 0 ? void 0 : activeStepMeta.title,
+        defaultStepId,
         isPreviewRuntime,
         recordStepCompletion,
         renderSuspended,

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

@@ -1,5 +1,6 @@
 import type { FunnelUserAnswers } from '../sdk/userAnswers.js';
 import { type FunnelUserAttribution } from '../runtime/funnel-attribution.js';
+import { type UrlUserAttributes } from '../runtime/url-user-attributes.js';
 export type AppUser = {
     id: string;
     name: string;
@@ -7,6 +8,9 @@ export type AppUser = {
     attributes: FunnelUserAnswers;
     document: Record<string, unknown>;
 };
+type AppUserInput = Omit<AppUser, 'document'> & {
+    document?: Record<string, unknown>;
+};
 export type FunnelEvent = {
     userId: string;
     eventType: string;
@@ -74,6 +78,12 @@ declare class ApiService {
     updateUser(user: AppUser, options?: {
         attribution?: FunnelUserAttribution;
     }): Promise<AppUser>;
+    syncUrlUserAttributes(input: {
+        user: AppUserInput;
+        attributes?: FunnelUserAnswers;
+        urlAttributes?: UrlUserAttributes | null;
+        attribution?: FunnelUserAttribution;
+    }): Promise<AppUser | null>;
     uploadTempPhoto(input: {
         file: File;
         userId?: string;

package/dist/services/api.service.js

@@ -1,5 +1,6 @@
 import { buildMainApiUrl, buildSdkHeaders, FUNNEL_ID, FUNNEL_VERSION_ID, getFunnelSdkPublishableKey, } from './runtime-api.config.js';
 import { mergeFunnelUserAttribution, } from '../runtime/funnel-attribution.js';
+import { applyUrlUserAttributesToUser, hasUrlUserAttributes, } from '../runtime/url-user-attributes.js';
 const DEFAULT_USER_ID_STORAGE_KEY = 'funnel:user-id';
 const LOCATION_USER_ID_QUERY_KEYS = ['user_id'];
 const LOCATION_STRIPE_CUSTOMER_ID_QUERY_KEYS = ['stripe_customer_id'];
@@ -326,6 +327,25 @@ class ApiService {
             fallbackDocument: withMergedAttributionDocument(user.document, options === null || options === void 0 ? void 0 : options.attribution),
         });
     }
+    async syncUrlUserAttributes(input) {
+        var _a;
+        if (!hasUrlUserAttributes(input.urlAttributes)) {
+            return null;
+        }
+        const nextUser = applyUrlUserAttributesToUser({
+            user: input.user,
+            attributes: input.attributes,
+            urlAttributes: input.urlAttributes,
+        });
+        const updatedUser = await this.updateUser(Object.assign(Object.assign({}, nextUser), { document: (_a = nextUser.document) !== null && _a !== void 0 ? _a : {} }), {
+            attribution: input.attribution,
+        });
+        return applyUrlUserAttributesToUser({
+            user: updatedUser,
+            attributes: nextUser.attributes,
+            urlAttributes: input.urlAttributes,
+        });
+    }
     async uploadTempPhoto(input) {
         const userId = persistUserId(input.userId || this.getOrCreateClientUserId(), FUNNEL_ID);
         const publishableKey = getFunnelSdkPublishableKey();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnelsgrove/runtime",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "private": false,
   "main": "./dist/index.js",