@funnelsgrove/runtime 0.1.0

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

@@ -0,0 +1,81 @@
+import type { FunnelUserAnswers } from '../sdk/userAnswers';
+export type AppUser = {
+    id: string;
+    name: string;
+    email: string;
+    attributes: FunnelUserAnswers;
+};
+export type FunnelEvent = {
+    userId: string;
+    eventType: string;
+    stepId?: string;
+    stepName?: string;
+    startedAt?: string;
+    endedAt?: string;
+    selected?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+};
+export type StepCompletionEvent = {
+    userId: string;
+    stepId: string;
+    stepName: string;
+    startedAt: string;
+    endedAt: string;
+    selected: Record<string, unknown>;
+};
+export type ManageSubscriptionsResponse = {
+    user: {
+        id: string;
+        externalUserId: string;
+        email: string | null;
+        fullName: string | null;
+        subscriptionStatus: string | null;
+    } | null;
+    subscriptions: Array<{
+        id: string;
+        status: string;
+        providerSubscriptionId: string;
+        cancelAtPeriodEnd: boolean;
+        currentPeriodEnd: string | null;
+        environment: 'test' | 'live';
+    }>;
+    eventsCount: number;
+};
+export type TempPhotoUploadResult = {
+    key: string;
+    publicUrl: string;
+    contentType: string;
+    sizeBytes: number;
+    uploadedAt: string;
+};
+declare class ApiService {
+    private readFileAsDataUrl;
+    getOrCreateClientUserId(): string;
+    bootstrapSession(input?: {
+        userId?: string;
+        email?: string;
+        name?: string;
+    }): Promise<AppUser>;
+    updateUser(user: AppUser): Promise<AppUser>;
+    uploadTempPhoto(input: {
+        file: File;
+        externalUserId?: string;
+        source?: 'camera' | 'upload';
+    }): Promise<TempPhotoUploadResult>;
+    private sendEventAsync;
+    trackFunnelEvent(event: FunnelEvent): void;
+    trackStepStarted(input: {
+        userId: string;
+        stepId: string;
+        stepName: string;
+        startedAt: string;
+    }): void;
+    trackStepCompleted(event: StepCompletionEvent): void;
+    getManageSubscriptions(): Promise<ManageSubscriptionsResponse>;
+    updateSubscription(input: {
+        subscriptionId: string;
+        action: 'cancel' | 'renew';
+    }): Promise<ManageSubscriptionsResponse>;
+}
+export declare const apiService: ApiService;
+export {};

package/dist/services/api.service.js

@@ -0,0 +1,346 @@
+import { buildMainApiUrl, buildSdkHeaders, FUNNEL_ID, getFunnelSdkPublishableKey, } from './runtime-api.config';
+const USER_ID_STORAGE_KEY = 'funnel:external-user-id';
+const canUseDom = () => {
+    return typeof window !== 'undefined';
+};
+const isRecord = (value) => {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+};
+const asRecord = (value) => {
+    return isRecord(value) ? value : {};
+};
+const asString = (value) => {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed || null;
+};
+const asNumber = (value) => {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        return null;
+    }
+    return value;
+};
+const normalizeUserId = (value) => {
+    if (!value || typeof value !== 'string') {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed || null;
+};
+const generateUserId = () => {
+    var _a;
+    if (canUseDom() && typeof ((_a = window.crypto) === null || _a === void 0 ? void 0 : _a.randomUUID) === 'function') {
+        return `sdk_user_${window.crypto.randomUUID().replace(/-/g, '')}`;
+    }
+    return `sdk_user_${Date.now()}_${Math.random().toString(16).slice(2, 10)}`;
+};
+const readStoredUserId = () => {
+    if (!canUseDom()) {
+        return null;
+    }
+    return normalizeUserId(window.localStorage.getItem(USER_ID_STORAGE_KEY));
+};
+const persistUserId = (value) => {
+    const normalized = normalizeUserId(value) || generateUserId();
+    if (canUseDom()) {
+        window.localStorage.setItem(USER_ID_STORAGE_KEY, normalized);
+    }
+    return normalized;
+};
+const buildSdkEvent = (event) => {
+    return {
+        eventType: event.eventType,
+        stepId: event.stepId || null,
+        stepName: event.stepName || null,
+        startedAt: event.startedAt || null,
+        endedAt: event.endedAt || null,
+        selected: event.selected || {},
+        metadata: event.metadata || {},
+    };
+};
+const toAppUser = (input) => {
+    var _a;
+    const apiUser = input.apiUser;
+    const apiDocument = asRecord(apiUser === null || apiUser === void 0 ? void 0 : apiUser.document);
+    const apiProgress = asRecord(apiDocument.progress);
+    const apiAttributes = asRecord(apiProgress.attributes);
+    return {
+        id: input.externalUserId,
+        name: asString(apiUser === null || apiUser === void 0 ? void 0 : apiUser.fullName) || input.fallbackName || '',
+        email: asString(apiUser === null || apiUser === void 0 ? void 0 : apiUser.email) || input.fallbackEmail || '',
+        attributes: Object.keys(apiAttributes).length > 0
+            ? apiAttributes
+            : ((_a = input.fallbackAttributes) !== null && _a !== void 0 ? _a : {}),
+    };
+};
+const parseErrorMessage = async (response, fallbackMessage) => {
+    try {
+        const payload = (await response.json());
+        const apiError = asString(payload.error);
+        if (apiError) {
+            return apiError;
+        }
+    }
+    catch (_a) {
+        // ignore JSON parsing errors
+    }
+    try {
+        const errorText = await response.text();
+        if (errorText.trim()) {
+            return errorText;
+        }
+    }
+    catch (_b) {
+        // ignore text parsing errors
+    }
+    return fallbackMessage;
+};
+class ApiService {
+    readFileAsDataUrl(file) {
+        return new Promise((resolve, reject) => {
+            const reader = new FileReader();
+            reader.onload = () => {
+                if (typeof reader.result !== 'string' || !reader.result.trim()) {
+                    reject(new Error('Failed to read image'));
+                    return;
+                }
+                resolve(reader.result);
+            };
+            reader.onerror = () => reject(new Error('Failed to read image'));
+            reader.readAsDataURL(file);
+        });
+    }
+    getOrCreateClientUserId() {
+        const existing = readStoredUserId();
+        if (existing) {
+            return existing;
+        }
+        return persistUserId(generateUserId());
+    }
+    async bootstrapSession(input) {
+        var _a;
+        const externalUserId = persistUserId((input === null || input === void 0 ? void 0 : input.userId) || this.getOrCreateClientUserId());
+        const publishableKey = getFunnelSdkPublishableKey();
+        if (!publishableKey) {
+            return toAppUser({
+                externalUserId,
+                fallbackName: input === null || input === void 0 ? void 0 : input.name,
+                fallbackEmail: input === null || input === void 0 ? void 0 : input.email,
+            });
+        }
+        const response = await fetch(buildMainApiUrl('/sdk/public/users/bootstrap'), {
+            method: 'POST',
+            headers: buildSdkHeaders({
+                'Content-Type': 'application/json',
+            }),
+            body: JSON.stringify({
+                publishableKey,
+                funnelId: FUNNEL_ID || undefined,
+                externalUserId,
+                email: (input === null || input === void 0 ? void 0 : input.email) || undefined,
+                fullName: (input === null || input === void 0 ? void 0 : input.name) || undefined,
+                metadata: {
+                    source: 'funnel-session',
+                },
+            }),
+        });
+        if (!response.ok) {
+            const errorMessage = await parseErrorMessage(response, 'Failed to bootstrap user session');
+            throw new Error(errorMessage);
+        }
+        const payload = (await response.json());
+        const persistedUserId = persistUserId(asString((_a = payload.user) === null || _a === void 0 ? void 0 : _a.externalUserId) ||
+            asString(payload.externalUserId) ||
+            externalUserId) || externalUserId;
+        return toAppUser({
+            apiUser: payload.user,
+            externalUserId: persistedUserId,
+            fallbackName: input === null || input === void 0 ? void 0 : input.name,
+            fallbackEmail: input === null || input === void 0 ? void 0 : input.email,
+        });
+    }
+    async updateUser(user) {
+        const persistedUserId = persistUserId(user.id || this.getOrCreateClientUserId());
+        const publishableKey = getFunnelSdkPublishableKey();
+        if (!publishableKey) {
+            return toAppUser({
+                externalUserId: persistedUserId,
+                fallbackName: user.name,
+                fallbackEmail: user.email,
+                fallbackAttributes: user.attributes,
+            });
+        }
+        const response = await fetch(buildMainApiUrl('/public/funnel-users/upsert'), {
+            method: 'POST',
+            headers: buildSdkHeaders({
+                'Content-Type': 'application/json',
+            }),
+            body: JSON.stringify({
+                publishableKey,
+                funnelId: FUNNEL_ID || undefined,
+                externalUserId: persistedUserId,
+                email: user.email || undefined,
+                fullName: user.name || undefined,
+                progress: {
+                    attributes: user.attributes || {},
+                },
+                metadata: {
+                    source: 'funnel',
+                },
+            }),
+        });
+        if (!response.ok) {
+            const errorMessage = await parseErrorMessage(response, 'Failed to update user');
+            throw new Error(errorMessage);
+        }
+        const payload = (await response.json());
+        return toAppUser({
+            apiUser: payload.user,
+            externalUserId: persistedUserId,
+            fallbackName: user.name,
+            fallbackEmail: user.email,
+            fallbackAttributes: user.attributes,
+        });
+    }
+    async uploadTempPhoto(input) {
+        const externalUserId = persistUserId(input.externalUserId || this.getOrCreateClientUserId());
+        const publishableKey = getFunnelSdkPublishableKey();
+        const imageDataUrl = await this.readFileAsDataUrl(input.file);
+        if (!publishableKey) {
+            return {
+                key: `local_${externalUserId}_${Date.now()}`,
+                publicUrl: imageDataUrl,
+                contentType: input.file.type || 'image/jpeg',
+                sizeBytes: input.file.size || 0,
+                uploadedAt: new Date().toISOString(),
+            };
+        }
+        const response = await fetch(buildMainApiUrl('/sdk/public/uploads/photos'), {
+            method: 'POST',
+            headers: buildSdkHeaders({
+                'Content-Type': 'application/json',
+            }),
+            body: JSON.stringify({
+                publishableKey,
+                funnelId: FUNNEL_ID || undefined,
+                externalUserId,
+                fileName: input.file.name || 'capture.jpg',
+                mimeType: input.file.type || undefined,
+                imageDataUrl,
+                source: input.source || 'upload',
+            }),
+        });
+        if (!response.ok) {
+            const errorMessage = await parseErrorMessage(response, 'Failed to upload photo');
+            throw new Error(errorMessage);
+        }
+        const payload = (await response.json());
+        const publicUrl = asString(payload.publicUrl);
+        const key = asString(payload.key);
+        const contentType = asString(payload.contentType) || input.file.type || 'image/jpeg';
+        const sizeBytes = asNumber(payload.sizeBytes) || input.file.size || 0;
+        const uploadedAt = asString(payload.uploadedAt) || new Date().toISOString();
+        if (!publicUrl || !key) {
+            throw new Error('Invalid photo upload response');
+        }
+        return {
+            key,
+            publicUrl,
+            contentType,
+            sizeBytes,
+            uploadedAt,
+        };
+    }
+    sendEventAsync(event) {
+        const publishableKey = getFunnelSdkPublishableKey();
+        if (!publishableKey) {
+            return;
+        }
+        const payload = JSON.stringify({
+            publishableKey,
+            funnelId: FUNNEL_ID || undefined,
+            externalUserId: event.userId,
+            events: [buildSdkEvent(event)],
+        });
+        const endpoint = buildMainApiUrl('/sdk/public/events');
+        if (canUseDom() && typeof navigator.sendBeacon === 'function') {
+            const blob = new Blob([payload], { type: 'application/json' });
+            const accepted = navigator.sendBeacon(endpoint, blob);
+            if (accepted) {
+                return;
+            }
+        }
+        void fetch(endpoint, {
+            method: 'POST',
+            headers: buildSdkHeaders({ 'Content-Type': 'application/json' }),
+            body: payload,
+            keepalive: true,
+        }).catch(() => {
+            // Never block UI if analytics delivery fails.
+        });
+    }
+    trackFunnelEvent(event) {
+        const userId = persistUserId(event.userId || this.getOrCreateClientUserId());
+        this.sendEventAsync(Object.assign(Object.assign({}, event), { userId }));
+    }
+    trackStepStarted(input) {
+        this.trackFunnelEvent({
+            userId: input.userId,
+            eventType: 'step_start',
+            stepId: input.stepId,
+            stepName: input.stepName,
+            startedAt: input.startedAt,
+        });
+    }
+    trackStepCompleted(event) {
+        this.trackFunnelEvent({
+            userId: event.userId,
+            eventType: 'step_end',
+            stepId: event.stepId,
+            stepName: event.stepName,
+            startedAt: event.startedAt,
+            endedAt: event.endedAt,
+            selected: event.selected,
+        });
+    }
+    async getManageSubscriptions() {
+        const externalUserId = this.getOrCreateClientUserId();
+        const query = new URLSearchParams({
+            externalUserId,
+        });
+        if (FUNNEL_ID) {
+            query.set('funnelId', FUNNEL_ID);
+        }
+        const response = await fetch(buildMainApiUrl(`/sdk/public/subscriptions?${query.toString()}`), {
+            method: 'GET',
+            cache: 'no-store',
+            headers: buildSdkHeaders(),
+        });
+        if (!response.ok) {
+            const errorMessage = await parseErrorMessage(response, 'Failed to load subscriptions');
+            throw new Error(errorMessage);
+        }
+        return (await response.json());
+    }
+    async updateSubscription(input) {
+        const externalUserId = this.getOrCreateClientUserId();
+        const response = await fetch(buildMainApiUrl(`/sdk/public/subscriptions/${encodeURIComponent(input.subscriptionId)}/${input.action}`), {
+            method: 'POST',
+            headers: buildSdkHeaders({
+                'Content-Type': 'application/json',
+            }),
+            body: JSON.stringify({
+                externalUserId,
+                funnelId: FUNNEL_ID || undefined,
+            }),
+        });
+        if (!response.ok) {
+            const errorMessage = await parseErrorMessage(response, 'Failed to update subscription');
+            throw new Error(errorMessage);
+        }
+        return (await response.json());
+    }
+}
+export const apiService = new ApiService();

package/dist/services/logger.d.ts

@@ -0,0 +1,8 @@
+type LogMethod = (...args: unknown[]) => void;
+export declare const logger: {
+    debug: LogMethod;
+    error: LogMethod;
+    info: LogMethod;
+    warn: LogMethod;
+};
+export {};

package/dist/services/logger.js

@@ -0,0 +1,16 @@
+const makeLoggerMethod = (method) => {
+    return (...args) => {
+        const consoleMethod = console[method];
+        if (typeof consoleMethod === 'function') {
+            consoleMethod(...args);
+            return;
+        }
+        console.log(...args);
+    };
+};
+export const logger = {
+    debug: makeLoggerMethod('debug'),
+    error: makeLoggerMethod('error'),
+    info: makeLoggerMethod('info'),
+    warn: makeLoggerMethod('warn'),
+};

package/dist/services/preview-frame.service.d.ts

@@ -0,0 +1,4 @@
+import type { ManageSubscriptionsResponse } from './api.service';
+export declare const isPreviewFrameRuntimeSearch: (search: string) => boolean;
+export declare const isPreviewFrameRuntime: () => boolean;
+export declare const buildPreviewManageSubscriptionsFallback: (externalUserId: string) => ManageSubscriptionsResponse;

package/dist/services/preview-frame.service.js

@@ -0,0 +1,31 @@
+'use client';
+const canUseDom = () => {
+    return typeof window !== 'undefined';
+};
+export const isPreviewFrameRuntimeSearch = (search) => {
+    try {
+        return new URLSearchParams(search).get('previewFrame') === '1';
+    }
+    catch (_a) {
+        return false;
+    }
+};
+export const isPreviewFrameRuntime = () => {
+    if (!canUseDom()) {
+        return false;
+    }
+    return isPreviewFrameRuntimeSearch(window.location.search);
+};
+export const buildPreviewManageSubscriptionsFallback = (externalUserId) => {
+    return {
+        user: {
+            id: 'preview-user',
+            externalUserId,
+            email: null,
+            fullName: 'Preview user',
+            subscriptionStatus: null,
+        },
+        subscriptions: [],
+        eventsCount: 0,
+    };
+};

package/dist/services/runtime-api.config.d.ts

@@ -0,0 +1,7 @@
+export declare const APP_DEALS_API_BASE_URL: string;
+export declare const FUNNEL_SDK_PUBLISHABLE_KEY: string;
+export declare const FUNNEL_ID: string;
+export declare const hasRealFunnelSdkPublishableKey: (value?: string) => boolean;
+export declare const getFunnelSdkPublishableKey: () => string | null;
+export declare const buildMainApiUrl: (path: string) => string;
+export declare const buildSdkHeaders: (headers?: Record<string, string>) => Record<string, string>;

package/dist/services/runtime-api.config.js

@@ -0,0 +1,40 @@
+var _a, _b, _c, _d;
+const DEFAULT_API_BASE_URL = 'https://sdk-api.funnelsgrove.com';
+const DEFAULT_FUNNEL_SDK_PUBLISHABLE_KEY = 'pk_test_app_deals_seed_public';
+const trimTrailingSlash = (value) => {
+    return value.replace(/\/+$/, '');
+};
+const toNormalizedPath = (path) => {
+    return path.startsWith('/') ? path : `/${path}`;
+};
+const isPreviewFrameRuntime = () => {
+    if (typeof window === 'undefined') {
+        return false;
+    }
+    try {
+        return new URLSearchParams(window.location.search).get('previewFrame') === '1';
+    }
+    catch (_a) {
+        return false;
+    }
+};
+export const APP_DEALS_API_BASE_URL = trimTrailingSlash((_a = process.env.NEXT_PUBLIC_APP_DEALS_API_BASE_URL) !== null && _a !== void 0 ? _a : DEFAULT_API_BASE_URL);
+export const FUNNEL_SDK_PUBLISHABLE_KEY = ((_c = (_b = process.env.NEXT_PUBLIC_FUNNEL_SDK_PUBLISHABLE_KEY) !== null && _b !== void 0 ? _b : process.env.NEXT_PUBLIC_FUNNEL_PUBLISHABLE_KEY) !== null && _c !== void 0 ? _c : DEFAULT_FUNNEL_SDK_PUBLISHABLE_KEY).trim();
+export const FUNNEL_ID = ((_d = process.env.NEXT_PUBLIC_FUNNEL_ID) !== null && _d !== void 0 ? _d : '').trim();
+export const hasRealFunnelSdkPublishableKey = (value = FUNNEL_SDK_PUBLISHABLE_KEY) => {
+    const normalized = value.trim();
+    return Boolean(normalized) && normalized !== DEFAULT_FUNNEL_SDK_PUBLISHABLE_KEY;
+};
+export const getFunnelSdkPublishableKey = () => {
+    if (isPreviewFrameRuntime()) {
+        return null;
+    }
+    return hasRealFunnelSdkPublishableKey() ? FUNNEL_SDK_PUBLISHABLE_KEY : null;
+};
+export const buildMainApiUrl = (path) => {
+    return `${APP_DEALS_API_BASE_URL}${toNormalizedPath(path)}`;
+};
+export const buildSdkHeaders = (headers) => {
+    const publishableKey = getFunnelSdkPublishableKey();
+    return Object.assign(Object.assign({}, (publishableKey ? { 'x-sdk-publishable-key': publishableKey } : {})), (headers !== null && headers !== void 0 ? headers : {}));
+};

package/dist/services/runtime-mode.service.d.ts

@@ -0,0 +1,5 @@
+export type RuntimeMode = 'test' | 'live';
+export declare const isEditorEnabled: () => boolean;
+export declare const getRuntimeMode: () => RuntimeMode;
+export declare const setRuntimeMode: (mode: RuntimeMode) => void;
+export declare const useRuntimeMode: () => [RuntimeMode, (mode: RuntimeMode) => void];

package/dist/services/runtime-mode.service.js

@@ -0,0 +1,113 @@
+'use client';
+import { useCallback, useEffect, useState } from 'react';
+const EDITOR_MODE_STORAGE_KEY = 'funnel:editor:mode';
+const MODE_CHANGE_EVENT = 'funnel:editor-mode-changed';
+const canUseDom = () => {
+    return typeof window !== 'undefined';
+};
+const toRuntimeMode = (value) => {
+    return value === 'live' ? 'live' : 'test';
+};
+export const isEditorEnabled = () => {
+    if (!canUseDom()) {
+        return false;
+    }
+    try {
+        return new URLSearchParams(window.location.search).get('editor') === 'true';
+    }
+    catch (_a) {
+        return false;
+    }
+};
+const readStoredEditorMode = () => {
+    if (!canUseDom()) {
+        return null;
+    }
+    try {
+        const storedValue = window.localStorage.getItem(EDITOR_MODE_STORAGE_KEY);
+        if (!storedValue) {
+            return null;
+        }
+        return toRuntimeMode(storedValue);
+    }
+    catch (_a) {
+        return null;
+    }
+};
+const emitModeChange = (mode) => {
+    if (!canUseDom()) {
+        return;
+    }
+    window.dispatchEvent(new CustomEvent(MODE_CHANGE_EVENT, {
+        detail: {
+            mode,
+        },
+    }));
+};
+export const getRuntimeMode = () => {
+    if (!canUseDom()) {
+        return 'live';
+    }
+    if (!isEditorEnabled()) {
+        return 'live';
+    }
+    return readStoredEditorMode() || 'test';
+};
+export const setRuntimeMode = (mode) => {
+    if (!canUseDom()) {
+        return;
+    }
+    const normalizedMode = toRuntimeMode(mode);
+    try {
+        window.localStorage.setItem(EDITOR_MODE_STORAGE_KEY, normalizedMode);
+    }
+    catch (_a) {
+        // ignore storage failures
+    }
+    emitModeChange(normalizedMode);
+};
+const subscribeRuntimeMode = (listener) => {
+    if (!canUseDom()) {
+        return () => undefined;
+    }
+    const onModeChanged = (event) => {
+        var _a;
+        const customEvent = event;
+        listener(toRuntimeMode((_a = customEvent.detail) === null || _a === void 0 ? void 0 : _a.mode));
+    };
+    const onStorageChanged = (event) => {
+        if (event.key !== EDITOR_MODE_STORAGE_KEY) {
+            return;
+        }
+        listener(getRuntimeMode());
+    };
+    window.addEventListener(MODE_CHANGE_EVENT, onModeChanged);
+    window.addEventListener('storage', onStorageChanged);
+    return () => {
+        window.removeEventListener(MODE_CHANGE_EVENT, onModeChanged);
+        window.removeEventListener('storage', onStorageChanged);
+    };
+};
+export const useRuntimeMode = () => {
+    const [mode, setMode] = useState('live');
+    useEffect(() => {
+        const syncMode = () => {
+            setMode(getRuntimeMode());
+        };
+        syncMode();
+        const unsubscribe = subscribeRuntimeMode((nextMode) => {
+            setMode(nextMode);
+        });
+        window.addEventListener('popstate', syncMode);
+        return () => {
+            unsubscribe();
+            window.removeEventListener('popstate', syncMode);
+        };
+    }, []);
+    const updateMode = useCallback((nextMode) => {
+        const normalizedMode = toRuntimeMode(nextMode);
+        setRuntimeMode(normalizedMode);
+        setMode(normalizedMode);
+    }, []);
+    return [mode, updateMode];
+};

package/dist/steps/types.d.ts

@@ -0,0 +1,22 @@
+export declare const FUNNEL_STEP_TYPES: readonly ["intro_hero", "value_prop_story", "single_step_choice", "single_step_choice_emoji", "multi_select_choice", "form_input", "social_proof", "progress_interstitial", "paywall_offer", "upsell_offer", "checkout", "subscription_management", "subscription_handoff", "cancellation_offer", "summary_confirmation"];
+export type FunnelStepType = (typeof FUNNEL_STEP_TYPES)[number];
+export type FunnelStepActionBar = {
+    hidden?: boolean;
+    buttonText?: string;
+    buttonVariant?: 'muted';
+    autoAdvanceMs?: number;
+};
+export type FunnelStepKind = 'default' | 'paywall' | 'upsell' | 'manage-subscription' | 'subscription-handoff' | 'cancellation';
+export type FunnelStepMeta = {
+    id: string;
+    /** Optional short name to make step intent obvious for non-engineers. */
+    name?: string;
+    /** Canonical structural taxonomy used across planning, runtime, and RAG examples. */
+    type: FunnelStepType;
+    /** Optional semantic class used by tooling (e.g. paywall detection). */
+    kind?: FunnelStepKind;
+    figmaNodeId: string;
+    title: string;
+    description: string;
+    actionBar?: FunnelStepActionBar;
+};