@appfunnel-dev/sdk 0.5.0 → 0.7.0

package/dist/internal-C7seLJBr.d.ts

@@ -0,0 +1,516 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+type VariableType = 'string' | 'number' | 'boolean' | 'stringArray';
+type VariableValue = string | number | boolean | string[] | null | undefined;
+interface AppFunnelConfig {
+    projectId?: string;
+    /** Funnel ID — set automatically on first publish. */
+    funnelId?: string;
+    name: string;
+    /** Page key to start on. Defaults to first entry in `pages`. */
+    initialPageKey?: string;
+    /**
+     * Response variables — user answers to quiz/survey questions.
+     * Stored internally as `answers.<key>`.
+     *
+     * ```ts
+     * responses: {
+     *   goal: { type: 'string', default: '' },
+     *   age_range: { type: 'string' },
+     *   interests: { type: 'stringArray', default: [] },
+     * }
+     * ```
+     */
+    responses?: Record<string, VariableConfig>;
+    /**
+     * Query param variables — captured from the URL at runtime.
+     * Stored internally as `query.<key>`.
+     * Listed here so the CLI build can emit them for analytics/database.
+     *
+     * ```ts
+     * queryParams: {
+     *   utm_source: { type: 'string' },
+     *   utm_medium: { type: 'string' },
+     *   ref: { type: 'string' },
+     * }
+     * ```
+     */
+    queryParams?: Record<string, VariableConfig>;
+    /**
+     * Data variables — arbitrary runtime state (not user answers or query params).
+     * Stored internally as `data.<key>`.
+     *
+     * ```ts
+     * data: {
+     *   selectedPlanTier: { type: 'string', default: 'free' },
+     *   hasSeenOnboarding: { type: 'boolean', default: false },
+     * }
+     * ```
+     */
+    data?: Record<string, VariableConfig>;
+    /** Default locale for translations. Defaults to 'en'. */
+    defaultLocale?: string;
+    products?: ProductsConfig;
+    settings?: FunnelSettings;
+    /**
+     * Integration configs (Meta Pixel, GTM, Clarity, etc.).
+     * Loaded from the API at runtime — the CLI build injects these
+     * from the project's dashboard settings.
+     */
+    integrations?: Record<string, Record<string, unknown>>;
+    /**
+     * Pages and routes can be defined here OR via `definePage()` in each page file.
+     * When using `definePage()`, the CLI build collects page definitions from the
+     * filesystem and merges them into the final config. These fields are populated
+     * by the build step — you don't need to set them manually.
+     */
+    pages?: Record<string, PageConfig>;
+    routes?: Record<string, RouteConfig[]>;
+}
+type PageType = 'default' | 'checkout' | 'finish' | 'auth' | 'paywall' | 'upsell';
+interface PageConfig {
+    name: string;
+    type: PageType;
+    /** URL slug for this page. Used for deep links, browser history, and reload persistence.
+     *  Defaults to the page key (filename) if not specified. */
+    slug?: string;
+}
+interface RouteConfig {
+    to: string;
+    when?: ConditionConfig | ConditionGroupConfig;
+}
+interface PageDefinition {
+    /** Display name shown in analytics and dashboard */
+    name: string;
+    /** Page type — determines behavior (e.g. checkout pages trigger payment flow) */
+    type?: PageType;
+    /** URL slug for this page. Defaults to the page key (filename) if not specified.
+     *  Used for deep links, browser history (pushState), and reload persistence. */
+    slug?: string;
+    /** Routes from this page. Evaluated in order; first match wins. */
+    routes?: RouteConfig[];
+}
+interface ConditionConfig {
+    variable: string;
+    equals?: VariableValue;
+    notEquals?: VariableValue;
+    contains?: string;
+    greaterThan?: number;
+    lessThan?: number;
+    exists?: boolean;
+    isEmpty?: boolean;
+    includes?: string;
+}
+interface ConditionGroupConfig {
+    operator: 'AND' | 'OR';
+    rules: (ConditionConfig | ConditionGroupConfig)[];
+}
+interface VariableConfig {
+    type: VariableType;
+    default?: VariableValue;
+    persist?: boolean;
+}
+interface ProductsConfig {
+    items: ProductConfig[];
+    defaultId?: string;
+}
+interface ProductConfig {
+    id: string;
+    name: string;
+    storePriceId: string;
+    trialDays?: number;
+    trialStorePriceId?: string;
+}
+interface FunnelSettings {
+    [key: string]: unknown;
+}
+interface RuntimeProduct {
+    id: string;
+    name: string;
+    price: string;
+    rawPrice: number;
+    monthlyPrice: string;
+    dailyPrice: string;
+    weeklyPrice: string;
+    yearlyPrice: string;
+    period: string;
+    periodly: string;
+    currencyCode: string;
+    currencySymbol: string;
+    hasTrial: boolean;
+    trialDays: number;
+    trialPrice: string;
+    paidTrial: boolean;
+    trialRawPrice: number;
+    trialDailyPrice: string;
+    trialCurrencyCode: string;
+    trialStorePriceId: string;
+    storePriceId: string;
+    stripePriceId: string;
+    stripeProductId: string;
+    paddlePriceId: string;
+    paddleProductId: string;
+    displayName: string;
+    periodDays: number;
+    periodMonths: number;
+    periodWeeks: number;
+}
+interface PageState {
+    key: string;
+    name: string;
+    type: string;
+    slug: string;
+    index: number;
+}
+interface Progress {
+    current: number;
+    total: number;
+    percentage: number;
+}
+/** Enriched price data from API (matches getFunnelByIdentifier response) */
+interface EnrichedPriceData {
+    amount: number;
+    currency: string;
+    interval: string | null;
+    intervalCount: number | null;
+    stripePriceId?: string;
+    stripeProductId?: string;
+    paddlePriceId?: string;
+    paddleProductId?: string;
+    displayName?: string;
+    priceName?: string;
+    name?: string;
+}
+/** Hook return types */
+interface TranslationState {
+    /** Translate a key, with optional interpolation: t('welcome', { name: 'John' }) */
+    t: (key: string, params?: Record<string, string | number>) => string;
+    /** Current locale code */
+    locale: string;
+    /** Switch locale at runtime */
+    setLocale: (locale: string) => void;
+    /** List of locales that have translations loaded */
+    availableLocales: string[];
+}
+interface LocaleState {
+    /** Full locale string, e.g. 'en-US' */
+    locale: string;
+    /** Language code, e.g. 'en' */
+    language: string;
+    /** Region code, e.g. 'US' */
+    region: string;
+    /** All preferred languages from navigator.languages */
+    languages: string[];
+    /** IANA timezone, e.g. 'America/New_York' */
+    timeZone: string;
+    /** Whether the locale uses 24-hour clock */
+    is24Hour: boolean;
+}
+interface UserState {
+    email: string;
+    name: string;
+    stripeCustomerId: string;
+    paddleCustomerId: string;
+    dateOfBirth: string;
+    /** Set email (does NOT fire identify — use tracking.identify() explicitly) */
+    setEmail: (email: string) => void;
+    setName: (name: string) => void;
+    setDateOfBirth: (dateOfBirth: string) => void;
+}
+interface NavigationState {
+    goToNextPage: () => void;
+    goBack: () => void;
+    goToPage: (pageKey: string) => void;
+    currentPage: PageState | null;
+    pageHistory: string[];
+    progress: Progress;
+}
+interface ProductsState {
+    products: RuntimeProduct[];
+    selected: RuntimeProduct | null;
+    select: (productId: string) => void;
+}
+interface TrackingState {
+    track: (eventName: string, data?: Record<string, unknown>) => void;
+    identify: (email: string) => void;
+}
+interface PaymentState {
+    customerId: string | null;
+    isAuthorized: boolean;
+    loading: boolean;
+    error: string | null;
+    cardDetails: {
+        last4: string;
+        brand: string;
+        expMonth: number;
+        expYear: number;
+    } | null;
+}
+interface DeviceInfo {
+    os: {
+        name: string;
+        timezone: string;
+    };
+    device: {
+        type: string;
+        isMobile: boolean;
+        isTablet: boolean;
+        screenWidth: number;
+        screenHeight: number;
+        viewportWidth: number;
+        viewportHeight: number;
+        colorDepth: number;
+        pixelRatio: number;
+    };
+    browser: {
+        name: string;
+        version: string;
+        userAgent: string;
+        cookieEnabled: boolean;
+        online: boolean;
+        language: string;
+    };
+}
+interface PageData {
+    currentId: string;
+    currentIndex: number;
+    current: number;
+    total: number;
+    progressPercentage: number;
+    startedAt: number;
+}
+interface FunnelState {
+    funnelId: string;
+    campaignId: string;
+    sessionId: string | null;
+    variables: Record<string, VariableValue>;
+    user: UserState;
+    responses: Record<string, VariableValue>;
+    queryParams: Record<string, string>;
+    navigation: NavigationState;
+    products: ProductsState;
+    tracking: TrackingState;
+    payment: PaymentState;
+}
+
+declare class VariableStore {
+    private state;
+    private listeners;
+    /** Tracks which keys changed in the last mutation — used by scoped notify */
+    private changedKeys;
+    constructor(initial: Record<string, VariableValue>);
+    getState(): Record<string, VariableValue>;
+    get(key: string): VariableValue;
+    set(key: string, value: VariableValue): void;
+    setState(updater: (prev: Record<string, VariableValue>) => Record<string, VariableValue>): void;
+    /** Batch set multiple variables at once */
+    setMany(updates: Record<string, VariableValue>): void;
+    /**
+     * Subscribe to store changes.
+     *
+     * @param listener - callback fired when relevant keys change
+     * @param scope - optional scope to limit notifications:
+     *   - `{ keys: ['data.x', 'user.email'] }` — only fire when these exact keys change
+     *   - `{ prefix: 'answers.' }` — only fire when any key starting with this prefix changes
+     *   - omit or `{}` — fire on every change (global listener)
+     */
+    subscribe(listener: () => void, scope?: {
+        keys?: string[];
+        prefix?: string;
+    }): () => void;
+    private notify;
+}
+
+interface RouterOptions {
+    config: AppFunnelConfig;
+    /** Override the initial page (from URL deep link or config) */
+    initialPage?: string;
+    /** Base path for URL updates, e.g. '/f/my-campaign' */
+    basePath?: string;
+    /** Campaign slug — used to check session cookies for deep-link gating */
+    campaignSlug?: string;
+}
+/**
+ * Router — observable page state machine for funnel navigation.
+ *
+ * Subscribable so React components can re-render on page changes
+ * via useSyncExternalStore.
+ */
+declare class Router {
+    private config;
+    private pageKeys;
+    private history;
+    private currentKey;
+    private initialKey;
+    private listeners;
+    readonly basePath: string;
+    constructor(options: RouterOptions);
+    private hasSessionCookie;
+    subscribe(listener: () => void): () => void;
+    private notify;
+    /** Snapshot key for useSyncExternalStore — changes on every navigation. */
+    getSnapshot(): string;
+    getCurrentPage(): PageState | null;
+    /** Build the full URL path for a page key. */
+    getPageUrl(pageKey: string): string;
+    /** Resolve a page key from a URL slug. */
+    resolveSlug(slug: string): string | null;
+    getPageHistory(): string[];
+    getProgress(): Progress;
+    /**
+     * Evaluate routes for the current page and navigate to the first matching target.
+     * Returns the new page key, or null if no route matched.
+     */
+    goToNextPage(variables: Record<string, VariableValue>): string | null;
+    /** Navigate to a specific page by key. */
+    goToPage(pageKey: string): string | null;
+    /** Go back to the previous page in history. */
+    goBack(): string | null;
+    /** Set the current page directly (used for deep-link/reload restore). */
+    setCurrentPage(pageKey: string): void;
+    private navigateTo;
+    private calculateExpectedPathLength;
+}
+
+/**
+ * Funnel Tracker — handles event tracking, session management, and attribution.
+ * Forked from admin/lib/funnel/tracking.ts — simplified for headless SDK.
+ */
+interface FunnelEventDataMap {
+    'funnel.start': Record<string, never>;
+    'page.view': {
+        pageId: string;
+        pageKey?: string;
+        pageName?: string;
+        isInitial?: boolean;
+    };
+    'page.exit': {
+        pageId: string;
+        durationMs: number;
+        activeMs: number;
+    };
+    'user.registered': {
+        email: string;
+    };
+    'checkout.start': {
+        productId?: string;
+        priceId: string;
+        productName?: string;
+    };
+    'checkout.payment_added': Record<string, never>;
+    'purchase.complete': {
+        amount?: number;
+        currency?: string;
+        email?: string;
+    };
+}
+type KnownFunnelEvent = keyof FunnelEventDataMap;
+declare class FunnelTracker {
+    private campaignId;
+    private funnelId;
+    private campaignSlug;
+    private sessionId;
+    private experimentId;
+    private initialized;
+    private customerId;
+    private adAttribution;
+    private currentPageId;
+    private pageStartTime;
+    private pageActiveTime;
+    private lastActiveStart;
+    private isPageVisible;
+    private variablePersistence;
+    constructor();
+    init(campaignId: string, funnelId: string, campaignSlug?: string, experimentId?: string | null): void;
+    getSessionId(): string | null;
+    getCustomerId(): string | null;
+    setSessionId(sessionId: string): void;
+    private persistSessionId;
+    track<E extends KnownFunnelEvent>(event: E, data?: FunnelEventDataMap[E], userData?: Record<string, unknown>): Promise<string>;
+    track(event: string, data?: Record<string, unknown>, userData?: Record<string, unknown>): Promise<string>;
+    /** Identify a user by email — fires user.registered event */
+    identify(email: string): Promise<void>;
+    updateUserData(userData: Record<string, unknown>): Promise<void>;
+    setCurrentVariables(variables: Record<string, unknown>): void;
+    flushVariables(): Promise<void>;
+    startPageTracking(pageId: string): void;
+    stopPageTracking(): void;
+    private calculateActiveTime;
+    private handleVisibilityChange;
+    private handleBeforeUnload;
+    private cleanupPageTracking;
+    reset(): void;
+}
+
+/**
+ * Lightweight i18n runtime.
+ *
+ * Translations are flat or nested JSON objects per locale:
+ *   { "en": { "welcome": "Hello, {{name}}" }, "de": { "welcome": "Hallo, {{name}}" } }
+ *
+ * The CLI build reads `locales/*.json` and passes them to FunnelProvider.
+ */
+type TranslationMap = Record<string, Record<string, string>>;
+declare class I18n {
+    private translations;
+    private locale;
+    private fallbackLocale;
+    private listeners;
+    constructor(defaultLocale?: string);
+    /** Load all translations at once */
+    load(translations: TranslationMap): void;
+    getLocale(): string;
+    setLocale(locale: string): void;
+    getAvailableLocales(): string[];
+    /**
+     * Translate a key with optional interpolation.
+     *
+     * Supports dot notation for nested keys and `{{var}}` interpolation:
+     *   t('checkout.title')
+     *   t('welcome', { name: 'John' })  → "Hello, John"
+     */
+    t(key: string, params?: Record<string, string | number>): string;
+    subscribe(listener: () => void): () => void;
+    private resolve;
+    private notify;
+}
+
+interface FunnelContextValue {
+    config: AppFunnelConfig;
+    variableStore: VariableStore;
+    router: Router;
+    tracker: FunnelTracker;
+    i18n: I18n;
+    products: RuntimeProduct[];
+    selectedProductId: string | null;
+    selectProduct: (productId: string) => void;
+    funnelId: string;
+    campaignId: string;
+    sessionId: string | null;
+}
+interface FunnelProviderProps {
+    config: AppFunnelConfig;
+    children: React.ReactNode;
+    /** Pre-fetched session data (from API) */
+    sessionData?: {
+        sessionId?: string;
+        campaignId: string;
+        funnelId: string;
+        variables?: Record<string, VariableValue>;
+        customerId?: string;
+        experimentId?: string | null;
+    };
+    /** Pre-fetched enriched price data map: storePriceId → price data */
+    priceData?: Map<string, EnrichedPriceData>;
+    /** Campaign slug for session cookies and URL routing */
+    campaignSlug?: string;
+    /** Base path for URL updates, e.g. '/f/my-campaign' */
+    basePath?: string;
+    /** Override the initial page (e.g. from URL slug on reload/deep link) */
+    initialPage?: string;
+    /** Translations map: { "en": { "key": "value" }, "de": { "key": "wert" } } */
+    translations?: TranslationMap;
+}
+declare function FunnelProvider({ config, children, sessionData, priceData, campaignSlug, basePath, initialPage, translations, }: FunnelProviderProps): react_jsx_runtime.JSX.Element;
+
+export { type AppFunnelConfig as A, type ConditionConfig as C, type DeviceInfo as D, type FunnelState as F, type LocaleState as L, type NavigationState as N, type PageDefinition as P, type RouteConfig as R, type TranslationState as T, type UserState as U, type VariableValue as V, type ProductsState as a, type TrackingState as b, type PaymentState as c, type PageData as d, type ConditionGroupConfig as e, FunnelProvider as f, type FunnelProviderProps as g, type FunnelSettings as h, type PageConfig as i, type PageState as j, type PageType as k, type ProductConfig as l, type ProductsConfig as m, type Progress as n, type RuntimeProduct as o, type VariableConfig as p, type VariableType as q, type FunnelContextValue as r, type TranslationMap as s };