@funnelsgrove/runtime 0.4.0 → 0.5.0

package/dist/components/FunnelRuntimeConfigBoundary.d.ts

@@ -0,0 +1,17 @@
+import { type ReactNode } from 'react';
+import { type ResolvedFunnelRuntimeConfig } from '../services/funnel-runtime-config.js';
+export type FunnelRuntimeConfigState = {
+    status: 'loading' | 'published' | 'fallback';
+    config: ResolvedFunnelRuntimeConfig | null;
+    error: Error | null;
+};
+type FunnelRuntimeConfigBoundaryProps = {
+    funnelId: string;
+    funnelVersionId?: string;
+    children: ReactNode;
+    loadingFallback?: ReactNode;
+    disabled?: boolean;
+};
+export declare function FunnelRuntimeConfigBoundary({ disabled, ...props }: FunnelRuntimeConfigBoundaryProps): import("react/jsx-runtime").JSX.Element;
+export declare const useFunnelRuntimeConfig: () => FunnelRuntimeConfigState;
+export {};

package/dist/components/FunnelRuntimeConfigBoundary.js

@@ -0,0 +1,73 @@
+'use client';
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useEffect, useMemo, useState, } from 'react';
+import { loadFunnelRuntimeConfig, resolvePublishedFunnelRuntimeConfig, } from '../services/funnel-runtime-config.js';
+const FunnelRuntimeConfigContext = createContext({
+    status: 'fallback',
+    config: null,
+    error: null,
+});
+const toError = (value) => (value instanceof Error ? value : new Error('Unable to load funnel runtime config'));
+/**
+ * Loads the active publication once before the funnel mounts. The resolved
+ * snapshot is deeply frozen and stays fixed for the lifetime of this boundary,
+ * so one visitor can never switch experiments or prices mid-session.
+ *
+ * Missing, invalid, or temporarily unavailable publications fail open to the
+ * generated build-time config by exposing `config: null`.
+ */
+function ActiveFunnelRuntimeConfigBoundary({ funnelId, funnelVersionId, children, loadingFallback = null, }) {
+    const [state, setState] = useState({
+        status: 'loading',
+        config: null,
+        error: null,
+    });
+    useEffect(() => {
+        let active = true;
+        loadFunnelRuntimeConfig(funnelId)
+            .then((published) => resolvePublishedFunnelRuntimeConfig(published, {
+            expectedFunnelVersionId: funnelVersionId,
+        }))
+            .then((config) => {
+            if (active) {
+                setState({ status: 'published', config, error: null });
+            }
+        })
+            .catch((error) => {
+            if (active) {
+                setState({ status: 'fallback', config: null, error: toError(error) });
+            }
+        });
+        return () => {
+            active = false;
+        };
+    }, [funnelId, funnelVersionId]);
+    const contextValue = useMemo(() => state, [state]);
+    if (state.status === 'loading') {
+        return loadingFallback;
+    }
+    return (_jsx(FunnelRuntimeConfigContext.Provider, { value: contextValue, children: children }));
+}
+export function FunnelRuntimeConfigBoundary(_a) {
+    var { disabled = false } = _a, props = __rest(_a, ["disabled"]);
+    if (disabled) {
+        return (_jsx(FunnelRuntimeConfigContext.Provider, { value: {
+                status: 'fallback',
+                config: null,
+                error: null,
+            }, children: props.children }));
+    }
+    return _jsx(ActiveFunnelRuntimeConfigBoundary, Object.assign({}, props));
+}
+export const useFunnelRuntimeConfig = () => (useContext(FunnelRuntimeConfigContext));

package/dist/index.d.ts

@@ -37,9 +37,11 @@ export * from './services/project-env.js';
 export * from './services/public-env.js';
 export * from './services/runtime-api.config.js';
 export * from './services/runtime-mode.service.js';
+export * from './services/funnel-runtime-config.js';
 export * from './sdk/userAnswers.js';
 export * from './components/FunnelContext.js';
 export * from './components/FunnelEditorPanel.js';
+export * from './components/FunnelRuntimeConfigBoundary.js';
 export * from './components/ManageSubscriptionScreen.js';
 export * from './components/PaymentRuntimeBoundary.js';
 export * from './components/RuntimeDevInfoBox.js';

package/dist/index.js

@@ -39,10 +39,12 @@ export * from './services/project-env.js';
 export * from './services/public-env.js';
 export * from './services/runtime-api.config.js';
 export * from './services/runtime-mode.service.js';
+export * from './services/funnel-runtime-config.js';
 // SDK and generic runtime UI.
 export * from './sdk/userAnswers.js';
 export * from './components/FunnelContext.js';
 export * from './components/FunnelEditorPanel.js';
+export * from './components/FunnelRuntimeConfigBoundary.js';
 export * from './components/ManageSubscriptionScreen.js';
 export * from './components/PaymentRuntimeBoundary.js';
 export * from './components/RuntimeDevInfoBox.js';

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

@@ -0,0 +1,36 @@
+import type { FunnelExperimentDefinition } from '../config/funnel.experiments.types.js';
+import type { GeneratedOfferSet } from '../runtime/offer-set-runtime.js';
+export type FunnelRuntimeConfig = {
+    schemaVersion: number;
+    funnelId: string;
+    projectId: string;
+    plans: unknown[];
+    offerSets: unknown[];
+    experiments: unknown[];
+};
+export type ResolvedFunnelRuntimeConfig = {
+    revisionId: string;
+    sourceDeploymentId: string;
+    sourceVersionId: string;
+    publishedAt: string;
+    offerSets: readonly GeneratedOfferSet[];
+    experiments: readonly FunnelExperimentDefinition[];
+};
+export type PublishedFunnelRuntimeConfig = {
+    revisionId: string;
+    sourceDeploymentId: string;
+    sourceVersionId: string;
+    schemaVersion: number;
+    publishedAt: string;
+    config: FunnelRuntimeConfig;
+};
+type RuntimeConfigFetcher = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+export declare const resolvePublishedFunnelRuntimeConfig: (published: PublishedFunnelRuntimeConfig, options?: {
+    expectedFunnelVersionId?: string;
+}) => ResolvedFunnelRuntimeConfig;
+export declare const loadFunnelRuntimeConfig: (funnelId: string, options?: {
+    fetcher?: RuntimeConfigFetcher;
+    basePath?: string;
+}) => Promise<PublishedFunnelRuntimeConfig>;
+export declare const clearFunnelRuntimeConfigInflight: () => void;
+export {};

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

@@ -0,0 +1,276 @@
+const inflightByFunnelId = new Map();
+const isRecord = (value) => (value !== null && typeof value === 'object' && !Array.isArray(value));
+const readString = (value) => (typeof value === 'string' && value.trim() ? value.trim() : null);
+const readNumber = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : null);
+const readBoolean = (value) => (typeof value === 'boolean' ? value : null);
+const readRecordArray = (value) => (Array.isArray(value) ? value.filter(isRecord) : []);
+const pick = (record, ...keys) => {
+    for (const key of keys) {
+        if (record[key] !== undefined && record[key] !== null) {
+            return record[key];
+        }
+    }
+    return undefined;
+};
+const pickString = (record, ...keys) => (readString(pick(record, ...keys)));
+const pickNumber = (record, ...keys) => (readNumber(pick(record, ...keys)));
+const pickBoolean = (record, ...keys) => (readBoolean(pick(record, ...keys)));
+const deepFreeze = (value) => {
+    if (!value || typeof value !== 'object' || Object.isFrozen(value)) {
+        return value;
+    }
+    Object.freeze(value);
+    for (const nested of Object.values(value)) {
+        deepFreeze(nested);
+    }
+    return value;
+};
+const getPlanById = (plans, projectBillingPlanId) => {
+    var _a;
+    return (projectBillingPlanId
+        ? (_a = plans.find((plan) => pickString(plan, 'id') === projectBillingPlanId)) !== null && _a !== void 0 ? _a : null
+        : null);
+};
+const getProviderMapping = (plan, mode) => {
+    var _a;
+    return ((_a = readRecordArray(plan === null || plan === void 0 ? void 0 : plan.providerMappings)
+        .find((mapping) => (pickString(mapping, 'environment') === mode
+        && pickBoolean(mapping, 'isActive', 'is_active') !== false))) !== null && _a !== void 0 ? _a : null);
+};
+const buildPlanModeConfig = (item, plan, mode) => {
+    var _a, _b;
+    const metadata = isRecord(item.metadata) ? item.metadata : {};
+    const metadataMappings = isRecord(metadata.providerMappingsByMode)
+        ? metadata.providerMappingsByMode
+        : {};
+    const metadataMapping = isRecord(metadataMappings[mode]) ? metadataMappings[mode] : {};
+    const planMapping = getProviderMapping(plan, mode);
+    const prefix = mode === 'test' ? 'test' : 'live';
+    const providerPlanId = (pickString(item, `${prefix}ProviderPlanId`, `${prefix}_provider_plan_id`)
+        || pickString(metadataMapping, 'providerPlanId')
+        || (planMapping ? pickString(planMapping, 'providerPlanId', 'provider_plan_id') : null));
+    if (!providerPlanId) {
+        return null;
+    }
+    const amountMinor = (_a = pickNumber(metadataMapping, 'amountCents')) !== null && _a !== void 0 ? _a : (planMapping ? pickNumber(planMapping, 'amountMinor', 'amount_minor') : null);
+    const interval = pickString(metadataMapping, 'billingInterval')
+        || (planMapping ? pickString(planMapping, 'interval') : null);
+    const intervalCount = (_b = pickNumber(metadataMapping, 'billingIntervalCount')) !== null && _b !== void 0 ? _b : (planMapping ? pickNumber(planMapping, 'intervalCount', 'interval_count') : null);
+    const currency = planMapping ? pickString(planMapping, 'currency') : null;
+    const amountMajor = amountMinor === null ? null : amountMinor / 100;
+    const priceLabel = pickString(metadataMapping, 'priceLabel') || (amountMajor === null
+        ? null
+        : new Intl.NumberFormat('en-US', {
+            style: 'currency',
+            currency: (currency === null || currency === void 0 ? void 0 : currency.toUpperCase()) || 'USD',
+            minimumFractionDigits: 2,
+            maximumFractionDigits: 2,
+        }).format(amountMajor) + (interval ? `/${interval}` : ''));
+    return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ providerPlanId }, (priceLabel ? { priceLabel } : {})), (pickString(metadataMapping, 'perDayAmount')
+        ? { perDayAmount: pickString(metadataMapping, 'perDayAmount') }
+        : {})), (pickString(metadataMapping, 'perDayLabel')
+        ? { perDayLabel: pickString(metadataMapping, 'perDayLabel') }
+        : {})), (amountMinor === null ? {} : { amountCents: amountMinor })), (pickString(metadataMapping, 'checkoutSummaryLabel')
+        ? { checkoutSummaryLabel: pickString(metadataMapping, 'checkoutSummaryLabel') }
+        : amountMajor === null
+            ? {}
+            : { checkoutSummaryLabel: `${new Intl.NumberFormat('en-US', {
+                    style: 'currency',
+                    currency: (currency === null || currency === void 0 ? void 0 : currency.toUpperCase()) || 'USD',
+                    minimumFractionDigits: 2,
+                    maximumFractionDigits: 2,
+                }).format(amountMajor)} today` })), (interval ? { billingInterval: interval } : {})), (intervalCount === null ? {} : { billingIntervalCount: intervalCount }));
+};
+const normalizePublishedOfferSets = (config) => {
+    const plans = readRecordArray(config.plans);
+    return readRecordArray(config.offerSets).map((offerSet) => {
+        var _a;
+        const key = pickString(offerSet, 'key');
+        if (!key) {
+            throw new Error('Published runtime offer set is missing its key');
+        }
+        const items = readRecordArray(offerSet.items).map((item) => {
+            var _a;
+            const metadata = isRecord(item.metadata) ? item.metadata : {};
+            const funnelPlanKey = pickString(item, 'funnelPlanKey', 'funnel_plan_key');
+            if (!funnelPlanKey) {
+                throw new Error(`Published runtime offer set "${key}" has an item without a plan key`);
+            }
+            const projectBillingPlanId = pickString(item, 'projectBillingPlanId', 'project_billing_plan_id');
+            const plan = getPlanById(plans, projectBillingPlanId);
+            const testMapping = buildPlanModeConfig(item, plan, 'test');
+            const liveMapping = buildPlanModeConfig(item, plan, 'live');
+            const title = pickString(item, 'title', 'displayNameOverride', 'display_name_override')
+                || pickString(metadata, 'title', 'publicPlanName', 'public_plan_name')
+                || (plan ? pickString(plan, 'displayName', 'display_name') : null);
+            const description = pickString(item, 'description')
+                || pickString(metadata, 'description')
+                || (plan ? pickString(plan, 'description') : null);
+            return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ funnelPlanKey }, (pickString(metadata, 'runtimePlanKey', 'planKey', 'billingPlanKey')
+                ? { runtimePlanKey: pickString(metadata, 'runtimePlanKey', 'planKey', 'billingPlanKey') }
+                : {})), (projectBillingPlanId ? { projectBillingPlanId } : {})), (pickString(item, 'testProviderPlanId', 'test_provider_plan_id')
+                ? { testProviderPlanId: pickString(item, 'testProviderPlanId', 'test_provider_plan_id') }
+                : {})), (pickString(item, 'liveProviderPlanId', 'live_provider_plan_id')
+                ? { liveProviderPlanId: pickString(item, 'liveProviderPlanId', 'live_provider_plan_id') }
+                : {})), (pickString(item, 'followUpTestProviderPlanId', 'follow_up_test_provider_plan_id')
+                ? { followUpTestProviderPlanId: pickString(item, 'followUpTestProviderPlanId', 'follow_up_test_provider_plan_id') }
+                : {})), (pickString(item, 'followUpLiveProviderPlanId', 'follow_up_live_provider_plan_id')
+                ? { followUpLiveProviderPlanId: pickString(item, 'followUpLiveProviderPlanId', 'follow_up_live_provider_plan_id') }
+                : {})), (pickString(item, 'followUpTitle', 'follow_up_title')
+                ? { followUpTitle: pickString(item, 'followUpTitle', 'follow_up_title') }
+                : {})), (pickString(item, 'followUpBillingInterval', 'follow_up_billing_interval')
+                ? { followUpBillingInterval: pickString(item, 'followUpBillingInterval', 'follow_up_billing_interval') }
+                : {})), (pickNumber(item, 'followUpBillingIntervalCount', 'follow_up_billing_interval_count') === null
+                ? {}
+                : { followUpBillingIntervalCount: pickNumber(item, 'followUpBillingIntervalCount', 'follow_up_billing_interval_count') })), (pickNumber(item, 'introIterations', 'intro_iterations') === null
+                ? {}
+                : { introIterations: pickNumber(item, 'introIterations', 'intro_iterations') })), (pickNumber(item, 'analyticsPurchaseValue', 'analytics_purchase_value') === null
+                ? {}
+                : { analyticsPurchaseValue: pickNumber(item, 'analyticsPurchaseValue', 'analytics_purchase_value') })), (title ? { title } : {})), (description ? { description } : {})), (pickString(item, 'featuredTag', 'featured_tag')
+                ? { featuredTag: pickString(item, 'featuredTag', 'featured_tag') }
+                : {})), (pickString(item, 'oldPriceLabel', 'old_price_label')
+                ? { oldPriceLabel: pickString(item, 'oldPriceLabel', 'old_price_label') }
+                : {})), { isDefault: (_a = pickBoolean(item, 'isDefault', 'is_default')) !== null && _a !== void 0 ? _a : false, providerMappingsByMode: Object.assign(Object.assign({}, (testMapping ? { test: testMapping } : {})), (liveMapping ? { live: liveMapping } : {})), metadata });
+        });
+        return Object.assign(Object.assign({}, (pickString(offerSet, 'id') ? { id: pickString(offerSet, 'id') } : {})), { key, isActive: (_a = pickBoolean(offerSet, 'isActive', 'is_active')) !== null && _a !== void 0 ? _a : true, metadata: isRecord(offerSet.metadata) ? offerSet.metadata : {}, items });
+    });
+};
+const normalizePublishedExperiments = (config, publishedAt) => readRecordArray(config.experiments).map((experiment) => {
+    const conversionConfig = isRecord(experiment.conversionConfig)
+        ? experiment.conversionConfig
+        : isRecord(experiment.conversion_config)
+            ? experiment.conversion_config
+            : {};
+    const id = pickString(experiment, 'posthogFlagKey', 'posthog_flag_key', 'id');
+    const name = pickString(experiment, 'name');
+    const stepId = pickString(conversionConfig, 'stepId', 'paywallStepId')
+        || pickString(experiment, 'stepId', 'step_id');
+    const rawStatus = pickString(experiment, 'status') || 'draft';
+    const status = rawStatus === 'running' || rawStatus === 'paused' || rawStatus === 'stopped'
+        ? rawStatus
+        : 'draft';
+    const type = pickString(conversionConfig, 'type') || 'step';
+    const variants = readRecordArray(experiment.variants);
+    if (!id || !name || !stepId || variants.length < 2) {
+        throw new Error('Published runtime experiment is incomplete');
+    }
+    const normalizedVariants = variants.map((variant, index) => {
+        var _a;
+        return ({
+            variantKey: pickString(variant, 'variantKey', 'variant_key', 'key')
+                || (index === 0 ? 'control' : `variant_${String.fromCharCode(96 + index)}`),
+            label: pickString(variant, 'label') || undefined,
+            trafficPercent: (_a = pickNumber(variant, 'trafficPercent', 'traffic_percent')) !== null && _a !== void 0 ? _a : 0,
+            routeToStepId: pickString(variant, 'routeToStepId', 'route_to_step_id') || stepId,
+        });
+    });
+    if (normalizedVariants.reduce((sum, variant) => sum + variant.trafficPercent, 0) !== 100) {
+        throw new Error(`Published runtime experiment "${id}" traffic must sum to 100`);
+    }
+    const launchDate = (pickString(conversionConfig, 'launchDate')
+        || pickString(experiment, 'startedAt', 'started_at')
+        || publishedAt).slice(0, 10);
+    if (type === 'pricing') {
+        const configuredKeys = Array.isArray(conversionConfig.offerSetKeys)
+            ? conversionConfig.offerSetKeys.map(readString).filter((value) => Boolean(value))
+            : [
+                pickString(conversionConfig, 'controlOfferSetKey'),
+                pickString(conversionConfig, 'variantOfferSetKey'),
+            ].filter((value) => Boolean(value));
+        if (configuredKeys.length !== normalizedVariants.length) {
+            throw new Error(`Published pricing experiment "${id}" does not map every variant to an offer set`);
+        }
+        const pricingVariants = normalizedVariants.map((variant, index) => (Object.assign(Object.assign({ variantKey: variant.variantKey }, (variant.label ? { label: variant.label } : {})), { trafficPercent: variant.trafficPercent, offerSetKey: configuredKeys[index] })));
+        return {
+            id,
+            name,
+            type: 'pricing',
+            status,
+            launchDate,
+            paywallStepId: stepId,
+            control: pricingVariants[0],
+            variant: pricingVariants[1],
+            variants: pricingVariants,
+        };
+    }
+    if (type !== 'step' && type !== 'paywall') {
+        throw new Error(`Published runtime experiment "${id}" has an unsupported type`);
+    }
+    const routeVariants = normalizedVariants.map((variant) => (Object.assign(Object.assign({ variantKey: variant.variantKey }, (variant.label ? { label: variant.label } : {})), { trafficPercent: variant.trafficPercent, stepId: variant.routeToStepId })));
+    return {
+        id,
+        name,
+        type,
+        status,
+        launchDate,
+        stepId,
+        control: routeVariants[0],
+        variant: routeVariants[1],
+        variants: routeVariants,
+    };
+});
+export const resolvePublishedFunnelRuntimeConfig = (published, options = {}) => {
+    if (options.expectedFunnelVersionId
+        && published.sourceVersionId !== options.expectedFunnelVersionId) {
+        throw new Error('Published runtime config belongs to a different funnel version');
+    }
+    return deepFreeze({
+        revisionId: published.revisionId,
+        sourceDeploymentId: published.sourceDeploymentId,
+        sourceVersionId: published.sourceVersionId,
+        publishedAt: published.publishedAt,
+        offerSets: normalizePublishedOfferSets(published.config),
+        experiments: normalizePublishedExperiments(published.config, published.publishedAt),
+    });
+};
+const parsePublishedRuntimeConfig = (value) => {
+    if (!isRecord(value) || !isRecord(value.config)) {
+        throw new Error('Funnel runtime config response is invalid');
+    }
+    const config = value.config;
+    if (typeof value.revisionId !== 'string'
+        || typeof value.sourceDeploymentId !== 'string'
+        || typeof value.sourceVersionId !== 'string'
+        || typeof value.schemaVersion !== 'number'
+        || typeof value.publishedAt !== 'string'
+        || typeof config.schemaVersion !== 'number'
+        || typeof config.funnelId !== 'string'
+        || typeof config.projectId !== 'string'
+        || !Array.isArray(config.plans)
+        || !Array.isArray(config.offerSets)
+        || !Array.isArray(config.experiments)) {
+        throw new Error('Funnel runtime config response is invalid');
+    }
+    return value;
+};
+export const loadFunnelRuntimeConfig = (funnelId, options = {}) => {
+    const normalizedFunnelId = funnelId.trim();
+    if (!normalizedFunnelId) {
+        return Promise.reject(new Error('funnelId is required'));
+    }
+    const cachedInflight = inflightByFunnelId.get(normalizedFunnelId);
+    if (cachedInflight) {
+        return cachedInflight;
+    }
+    const fetcher = options.fetcher || globalThis.fetch;
+    const basePath = (options.basePath || '/api/funnel-config').replace(/\/$/, '');
+    const request = fetcher(`${basePath}/${encodeURIComponent(normalizedFunnelId)}`, {
+        headers: { accept: 'application/json' },
+    }).then(async (response) => {
+        if (!response.ok) {
+            throw new Error(`Unable to load funnel runtime config (${response.status})`);
+        }
+        const published = parsePublishedRuntimeConfig(await response.json());
+        if (published.config.funnelId !== normalizedFunnelId) {
+            throw new Error('Funnel runtime config belongs to a different funnel');
+        }
+        return published;
+    }).finally(() => {
+        inflightByFunnelId.delete(normalizedFunnelId);
+    });
+    inflightByFunnelId.set(normalizedFunnelId, request);
+    return request;
+};
+export const clearFunnelRuntimeConfigInflight = () => {
+    inflightByFunnelId.clear();
+};

package/package.json

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