@appfunnel-dev/sdk 0.5.0 → 0.7.0

package/dist/index.d.cts

@@ -1,7 +1,8 @@
-import { A as AppFunnelConfig, P as PageDefinition, V as VariableValue, U as UserState, L as LocaleState, T as TranslationState, N as NavigationState, a as ProductsState, b as TrackingState, c as PaymentState, F as FunnelState } from './types-ChorYUCl.cjs';
-export { C as ConditionConfig, d as ConditionGroupConfig, e as FunnelSettings, f as PageConfig, g as PageState, h as PageType, i as ProductConfig, j as ProductsConfig, k as Progress, R as RouteConfig, l as RuntimeProduct, m as VariableConfig, n as VariableType } from './types-ChorYUCl.cjs';
-import * as react_jsx_runtime from 'react/jsx-runtime';
+import { A as AppFunnelConfig, P as PageDefinition, V as VariableValue, U as UserState, L as LocaleState, T as TranslationState, N as NavigationState, a as ProductsState, b as TrackingState, c as PaymentState, D as DeviceInfo, d as PageData, F as FunnelState } from './internal-C7seLJBr.cjs';
+export { C as ConditionConfig, e as ConditionGroupConfig, f as FunnelProvider, g as FunnelProviderProps, h as FunnelSettings, i as PageConfig, j as PageState, k as PageType, l as ProductConfig, m as ProductsConfig, n as Progress, R as RouteConfig, o as RuntimeProduct, p as VariableConfig, q as VariableType } from './internal-C7seLJBr.cjs';
+import * as react from 'react';
 import { Appearance } from '@stripe/stripe-js';
+import * as react_jsx_runtime from 'react/jsx-runtime';
 
 /**
  * Type helper for appfunnel.config.ts.
@@ -39,6 +40,9 @@ declare function definePage(definition: PageDefinition): PageDefinition;
 /**
  * Read/write a single variable.
  *
+ * **Advanced** — this hook is not intended for normal page usage.
+ * Prefer accessing variables through the standard page props instead.
+ *
  * ```tsx
  * const [email, setEmail] = useVariable<string>('email')
  * const [count, setCount] = useVariable<number>('count')
@@ -51,12 +55,21 @@ declare function useVariable<T extends VariableValue>(id: string): [T, (value: T
 /**
  * Read all variables (including system variables). Read-only.
  * Use useVariable() to write individual variables.
+ *
+ * **Advanced** — this hook is not intended for normal page usage.
+ * Prefer accessing variables through the standard page props instead.
+ *
+ * Warning: this hook subscribes to ALL variable changes, so the
+ * component will re-render on every single variable update.
  */
 declare function useVariables(): Record<string, VariableValue>;
 
+type DateFormat = 'MM/DD/YYYY' | 'DD/MM/YYYY' | 'YYYY-MM-DD';
+
 /**
  * Read built-in user state (email, name, customerId).
  *
+ * Only re-renders when a `user.*` variable changes.
  * For reading/writing arbitrary user fields, use `useUserProperty('fieldName')`.
  */
 declare function useUser(): UserState;
@@ -70,6 +83,21 @@ declare function useUser(): UserState;
  * ```
  */
 declare function useUserProperty(field: string): [string, (value: string) => void];
+/**
+ * Read/write the user's date of birth.
+ * Always stores the value as YYYY-MM-DD regardless of input format.
+ *
+ * @param format - How the input string should be interpreted (default: MM/DD/YYYY).
+ *
+ * ```tsx
+ * const [dob, setDob] = useDateOfBirth()              // defaults to MM/DD/YYYY
+ * const [dob, setDob] = useDateOfBirth('DD/MM/YYYY')  // explicit EU format
+ *
+ * setDob('03/15/1990')  // stored as "1990-03-15"
+ * setDob('03151990')    // stored as "1990-03-15"
+ * ```
+ */
+declare function useDateOfBirth(format?: DateFormat): [string, (value: string) => void];
 
 /**
  * Read/write a single response variable (answers.*).
@@ -83,6 +111,8 @@ declare function useResponse<T extends VariableValue>(key: string): [T, (value:
 /**
  * Read all response variables as a flat object (without the `answers.` prefix).
  *
+ * Only re-renders when an `answers.*` variable changes.
+ *
  * ```tsx
  * const responses = useResponses()
  * // { goal: 'weight_loss', interests: ['yoga', 'running'] }
@@ -93,10 +123,7 @@ declare function useResponses(): Record<string, VariableValue>;
 /**
  * Read all URL query parameters as a flat object (without the `query.` prefix).
  *
- * `query.*` variables are auto-populated from `window.location.search`.
- * e.g. `?utm_source=google&ref=abc` → `{ utm_source: 'google', ref: 'abc' }`.
- *
- * These are read-only from the developer's perspective — they come from the URL.
+ * Only re-renders when a `query.*` variable changes.
  */
 declare function useQueryParams(): Record<string, string>;
 /**
@@ -149,11 +176,16 @@ declare function useTranslation(): TranslationState;
 
 /**
  * Navigation hook — evaluates routes, navigates between pages, tracks progress.
+ *
+ * Only re-renders when the router's current page changes (not on variable changes).
+ * Variables are read lazily at navigation time — callbacks are referentially stable.
  */
 declare function useNavigation(): NavigationState;
 
 /**
  * Products hook — access product list, selected product, and selection handler.
+ *
+ * Only re-renders when `products.selectedProductId` changes.
  */
 declare function useProducts(): ProductsState;
 
@@ -163,33 +195,119 @@ declare function useProducts(): ProductsState;
 declare function useTracking(): TrackingState;
 
 /**
- * Payment hook — reads payment-related system variables.
+ * Payment hook — reads payment-related variables.
+ *
+ * Only re-renders when payment/card variables change.
  */
 declare function usePayment(): PaymentState;
 
+/**
+ * Read device, browser, and OS metadata.
+ *
+ * These values are set once on mount and don't change, so this hook
+ * will rarely (if ever) re-render.
+ *
+ * ```tsx
+ * const { device, browser, os } = useDeviceInfo()
+ * if (device.isMobile) { ... }
+ * ```
+ */
+declare function useDeviceInfo(): DeviceInfo;
+
+interface SafeAreaInsets {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/**
+ * Returns the current safe-area insets (in px) from `env(safe-area-inset-*)`.
+ *
+ * Useful for positioning fixed elements above the Safari home-indicator bar.
+ *
+ * ```tsx
+ * const { bottom } = useSafeArea()
+ * <div style={{ position: 'fixed', bottom: 0, paddingBottom: bottom }} />
+ * ```
+ */
+declare function useSafeArea(): SafeAreaInsets;
+
+interface KeyboardState {
+    /** Whether the virtual keyboard is currently visible */
+    isOpen: boolean;
+    /** Height of the keyboard in pixels (0 when closed) */
+    height: number;
+}
+/**
+ * Detects the virtual keyboard on mobile devices.
+ *
+ * Uses the VirtualKeyboard API where available, with a
+ * visualViewport fallback for Safari/older browsers.
+ *
+ * The visualViewport path follows the approach described at
+ * https://martijnhols.nl/blog/how-to-get-document-height-ios-safari-osk
+ * to handle iOS Safari's delayed viewport updates on keyboard close.
+ *
+ * ```tsx
+ * const { isOpen, height } = useKeyboard()
+ * <div style={{ position: 'fixed', bottom: isOpen ? height : 0 }} />
+ * ```
+ */
+declare function useKeyboard(): KeyboardState;
+
+/**
+ * Read page-level system variables.
+ *
+ * Re-renders when page variables change (e.g. on navigation).
+ *
+ * ```tsx
+ * const { currentId, progressPercentage, startedAt } = usePageData()
+ * ```
+ */
+declare function usePageData(): PageData;
+
 /**
  * Convenience hook that combines all SDK hooks.
  * Useful for simple funnels where you don't want multiple hook imports.
  */
 declare function useFunnel(): FunnelState;
 
-interface PaymentFormProps {
+interface StripePaymentHandle {
+    /** Programmatically submit the payment form */
+    submit: () => Promise<void>;
+}
+interface StripePaymentFormProps {
     /** Product ID override (default: currently selected product) */
     productId?: string;
     /** "checkout" for full payment, "validate-only" to just collect card */
     mode?: 'checkout' | 'validate-only';
+    /** "elements" for PaymentElement, "embedded" for Stripe Embedded Checkout */
+    variant?: 'elements' | 'embedded';
     /** Called on successful payment */
     onSuccess?: () => void;
     /** Called on payment error */
     onError?: (error: string) => void;
-    /** Allow Stripe promotion codes */
-    allowPromotionCodes?: boolean;
+    /** Called when the Stripe form is ready to accept submissions */
+    onReady?: () => void;
     /** Additional CSS class */
     className?: string;
-    /** Stripe Appearance override */
+    /** Stripe Appearance override (elements variant only) */
     appearance?: Appearance;
+    /** PaymentElement layout option (default: 'tabs') */
+    layout?: 'tabs' | 'accordion' | 'auto';
 }
-declare function PaymentForm({ productId, mode, onSuccess, onError, className, appearance, }: PaymentFormProps): react_jsx_runtime.JSX.Element;
+/**
+ * Stripe payment component supporting PaymentElement and Embedded Checkout.
+ *
+ * Use a ref to submit the form from an external button:
+ * ```tsx
+ * const paymentRef = useRef<StripePaymentHandle>(null)
+ *
+ * <StripePaymentForm ref={paymentRef} onSuccess={goToNextPage} />
+ * <button onClick={() => paymentRef.current?.submit()}>Pay Now</button>
+ * ```
+ */
+declare const StripePaymentForm: react.ForwardRefExoticComponent<StripePaymentFormProps & react.RefAttributes<StripePaymentHandle>>;
 
 interface PaddleCheckoutProps {
     /** Product ID to checkout (default: currently selected product) */
@@ -237,4 +355,4 @@ type IntegrationLoader = (config: Record<string, unknown>) => void;
  */
 declare function registerIntegration(id: string, loader: IntegrationLoader): void;
 
-export { AppFunnelConfig, FunnelState, type IntegrationConfigs, LocaleState, NavigationState, PaddleCheckout, type PaddleCheckoutProps, PageDefinition, PaymentForm, type PaymentFormProps, PaymentState, ProductsState, TrackingState, TranslationState, UserState, VariableValue, defineConfig, definePage, registerIntegration, useData, useFunnel, useLocale, useNavigation, usePayment, useProducts, useQueryParam, useQueryParams, useResponse, useResponses, useTracking, useTranslation, useUser, useUserProperty, useVariable, useVariables };
+export { AppFunnelConfig, type DateFormat, DeviceInfo, FunnelState, type IntegrationConfigs, type KeyboardState, LocaleState, NavigationState, PaddleCheckout, type PaddleCheckoutProps, PageData, PageDefinition, PaymentState, ProductsState, type SafeAreaInsets, StripePaymentForm, type StripePaymentFormProps, type StripePaymentHandle, TrackingState, TranslationState, UserState, VariableValue, defineConfig, definePage, registerIntegration, useData, useDateOfBirth, useDeviceInfo, useFunnel, useKeyboard, useLocale, useNavigation, usePageData, usePayment, useProducts, useQueryParam, useQueryParams, useResponse, useResponses, useSafeArea, useTracking, useTranslation, useUser, useUserProperty, useVariable, useVariables };

package/dist/index.d.ts

@@ -1,7 +1,8 @@
-import { A as AppFunnelConfig, P as PageDefinition, V as VariableValue, U as UserState, L as LocaleState, T as TranslationState, N as NavigationState, a as ProductsState, b as TrackingState, c as PaymentState, F as FunnelState } from './types-ChorYUCl.js';
-export { C as ConditionConfig, d as ConditionGroupConfig, e as FunnelSettings, f as PageConfig, g as PageState, h as PageType, i as ProductConfig, j as ProductsConfig, k as Progress, R as RouteConfig, l as RuntimeProduct, m as VariableConfig, n as VariableType } from './types-ChorYUCl.js';
-import * as react_jsx_runtime from 'react/jsx-runtime';
+import { A as AppFunnelConfig, P as PageDefinition, V as VariableValue, U as UserState, L as LocaleState, T as TranslationState, N as NavigationState, a as ProductsState, b as TrackingState, c as PaymentState, D as DeviceInfo, d as PageData, F as FunnelState } from './internal-C7seLJBr.js';
+export { C as ConditionConfig, e as ConditionGroupConfig, f as FunnelProvider, g as FunnelProviderProps, h as FunnelSettings, i as PageConfig, j as PageState, k as PageType, l as ProductConfig, m as ProductsConfig, n as Progress, R as RouteConfig, o as RuntimeProduct, p as VariableConfig, q as VariableType } from './internal-C7seLJBr.js';
+import * as react from 'react';
 import { Appearance } from '@stripe/stripe-js';
+import * as react_jsx_runtime from 'react/jsx-runtime';
 
 /**
  * Type helper for appfunnel.config.ts.
@@ -39,6 +40,9 @@ declare function definePage(definition: PageDefinition): PageDefinition;
 /**
  * Read/write a single variable.
  *
+ * **Advanced** — this hook is not intended for normal page usage.
+ * Prefer accessing variables through the standard page props instead.
+ *
  * ```tsx
  * const [email, setEmail] = useVariable<string>('email')
  * const [count, setCount] = useVariable<number>('count')
@@ -51,12 +55,21 @@ declare function useVariable<T extends VariableValue>(id: string): [T, (value: T
 /**
  * Read all variables (including system variables). Read-only.
  * Use useVariable() to write individual variables.
+ *
+ * **Advanced** — this hook is not intended for normal page usage.
+ * Prefer accessing variables through the standard page props instead.
+ *
+ * Warning: this hook subscribes to ALL variable changes, so the
+ * component will re-render on every single variable update.
  */
 declare function useVariables(): Record<string, VariableValue>;
 
+type DateFormat = 'MM/DD/YYYY' | 'DD/MM/YYYY' | 'YYYY-MM-DD';
+
 /**
  * Read built-in user state (email, name, customerId).
  *
+ * Only re-renders when a `user.*` variable changes.
  * For reading/writing arbitrary user fields, use `useUserProperty('fieldName')`.
  */
 declare function useUser(): UserState;
@@ -70,6 +83,21 @@ declare function useUser(): UserState;
  * ```
  */
 declare function useUserProperty(field: string): [string, (value: string) => void];
+/**
+ * Read/write the user's date of birth.
+ * Always stores the value as YYYY-MM-DD regardless of input format.
+ *
+ * @param format - How the input string should be interpreted (default: MM/DD/YYYY).
+ *
+ * ```tsx
+ * const [dob, setDob] = useDateOfBirth()              // defaults to MM/DD/YYYY
+ * const [dob, setDob] = useDateOfBirth('DD/MM/YYYY')  // explicit EU format
+ *
+ * setDob('03/15/1990')  // stored as "1990-03-15"
+ * setDob('03151990')    // stored as "1990-03-15"
+ * ```
+ */
+declare function useDateOfBirth(format?: DateFormat): [string, (value: string) => void];
 
 /**
  * Read/write a single response variable (answers.*).
@@ -83,6 +111,8 @@ declare function useResponse<T extends VariableValue>(key: string): [T, (value:
 /**
  * Read all response variables as a flat object (without the `answers.` prefix).
  *
+ * Only re-renders when an `answers.*` variable changes.
+ *
  * ```tsx
  * const responses = useResponses()
  * // { goal: 'weight_loss', interests: ['yoga', 'running'] }
@@ -93,10 +123,7 @@ declare function useResponses(): Record<string, VariableValue>;
 /**
  * Read all URL query parameters as a flat object (without the `query.` prefix).
  *
- * `query.*` variables are auto-populated from `window.location.search`.
- * e.g. `?utm_source=google&ref=abc` → `{ utm_source: 'google', ref: 'abc' }`.
- *
- * These are read-only from the developer's perspective — they come from the URL.
+ * Only re-renders when a `query.*` variable changes.
  */
 declare function useQueryParams(): Record<string, string>;
 /**
@@ -149,11 +176,16 @@ declare function useTranslation(): TranslationState;
 
 /**
  * Navigation hook — evaluates routes, navigates between pages, tracks progress.
+ *
+ * Only re-renders when the router's current page changes (not on variable changes).
+ * Variables are read lazily at navigation time — callbacks are referentially stable.
  */
 declare function useNavigation(): NavigationState;
 
 /**
  * Products hook — access product list, selected product, and selection handler.
+ *
+ * Only re-renders when `products.selectedProductId` changes.
  */
 declare function useProducts(): ProductsState;
 
@@ -163,33 +195,119 @@ declare function useProducts(): ProductsState;
 declare function useTracking(): TrackingState;
 
 /**
- * Payment hook — reads payment-related system variables.
+ * Payment hook — reads payment-related variables.
+ *
+ * Only re-renders when payment/card variables change.
  */
 declare function usePayment(): PaymentState;
 
+/**
+ * Read device, browser, and OS metadata.
+ *
+ * These values are set once on mount and don't change, so this hook
+ * will rarely (if ever) re-render.
+ *
+ * ```tsx
+ * const { device, browser, os } = useDeviceInfo()
+ * if (device.isMobile) { ... }
+ * ```
+ */
+declare function useDeviceInfo(): DeviceInfo;
+
+interface SafeAreaInsets {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/**
+ * Returns the current safe-area insets (in px) from `env(safe-area-inset-*)`.
+ *
+ * Useful for positioning fixed elements above the Safari home-indicator bar.
+ *
+ * ```tsx
+ * const { bottom } = useSafeArea()
+ * <div style={{ position: 'fixed', bottom: 0, paddingBottom: bottom }} />
+ * ```
+ */
+declare function useSafeArea(): SafeAreaInsets;
+
+interface KeyboardState {
+    /** Whether the virtual keyboard is currently visible */
+    isOpen: boolean;
+    /** Height of the keyboard in pixels (0 when closed) */
+    height: number;
+}
+/**
+ * Detects the virtual keyboard on mobile devices.
+ *
+ * Uses the VirtualKeyboard API where available, with a
+ * visualViewport fallback for Safari/older browsers.
+ *
+ * The visualViewport path follows the approach described at
+ * https://martijnhols.nl/blog/how-to-get-document-height-ios-safari-osk
+ * to handle iOS Safari's delayed viewport updates on keyboard close.
+ *
+ * ```tsx
+ * const { isOpen, height } = useKeyboard()
+ * <div style={{ position: 'fixed', bottom: isOpen ? height : 0 }} />
+ * ```
+ */
+declare function useKeyboard(): KeyboardState;
+
+/**
+ * Read page-level system variables.
+ *
+ * Re-renders when page variables change (e.g. on navigation).
+ *
+ * ```tsx
+ * const { currentId, progressPercentage, startedAt } = usePageData()
+ * ```
+ */
+declare function usePageData(): PageData;
+
 /**
  * Convenience hook that combines all SDK hooks.
  * Useful for simple funnels where you don't want multiple hook imports.
  */
 declare function useFunnel(): FunnelState;
 
-interface PaymentFormProps {
+interface StripePaymentHandle {
+    /** Programmatically submit the payment form */
+    submit: () => Promise<void>;
+}
+interface StripePaymentFormProps {
     /** Product ID override (default: currently selected product) */
     productId?: string;
     /** "checkout" for full payment, "validate-only" to just collect card */
     mode?: 'checkout' | 'validate-only';
+    /** "elements" for PaymentElement, "embedded" for Stripe Embedded Checkout */
+    variant?: 'elements' | 'embedded';
     /** Called on successful payment */
     onSuccess?: () => void;
     /** Called on payment error */
     onError?: (error: string) => void;
-    /** Allow Stripe promotion codes */
-    allowPromotionCodes?: boolean;
+    /** Called when the Stripe form is ready to accept submissions */
+    onReady?: () => void;
     /** Additional CSS class */
     className?: string;
-    /** Stripe Appearance override */
+    /** Stripe Appearance override (elements variant only) */
     appearance?: Appearance;
+    /** PaymentElement layout option (default: 'tabs') */
+    layout?: 'tabs' | 'accordion' | 'auto';
 }
-declare function PaymentForm({ productId, mode, onSuccess, onError, className, appearance, }: PaymentFormProps): react_jsx_runtime.JSX.Element;
+/**
+ * Stripe payment component supporting PaymentElement and Embedded Checkout.
+ *
+ * Use a ref to submit the form from an external button:
+ * ```tsx
+ * const paymentRef = useRef<StripePaymentHandle>(null)
+ *
+ * <StripePaymentForm ref={paymentRef} onSuccess={goToNextPage} />
+ * <button onClick={() => paymentRef.current?.submit()}>Pay Now</button>
+ * ```
+ */
+declare const StripePaymentForm: react.ForwardRefExoticComponent<StripePaymentFormProps & react.RefAttributes<StripePaymentHandle>>;
 
 interface PaddleCheckoutProps {
     /** Product ID to checkout (default: currently selected product) */
@@ -237,4 +355,4 @@ type IntegrationLoader = (config: Record<string, unknown>) => void;
  */
 declare function registerIntegration(id: string, loader: IntegrationLoader): void;
 
-export { AppFunnelConfig, FunnelState, type IntegrationConfigs, LocaleState, NavigationState, PaddleCheckout, type PaddleCheckoutProps, PageDefinition, PaymentForm, type PaymentFormProps, PaymentState, ProductsState, TrackingState, TranslationState, UserState, VariableValue, defineConfig, definePage, registerIntegration, useData, useFunnel, useLocale, useNavigation, usePayment, useProducts, useQueryParam, useQueryParams, useResponse, useResponses, useTracking, useTranslation, useUser, useUserProperty, useVariable, useVariables };
+export { AppFunnelConfig, type DateFormat, DeviceInfo, FunnelState, type IntegrationConfigs, type KeyboardState, LocaleState, NavigationState, PaddleCheckout, type PaddleCheckoutProps, PageData, PageDefinition, PaymentState, ProductsState, type SafeAreaInsets, StripePaymentForm, type StripePaymentFormProps, type StripePaymentHandle, TrackingState, TranslationState, UserState, VariableValue, defineConfig, definePage, registerIntegration, useData, useDateOfBirth, useDeviceInfo, useFunnel, useKeyboard, useLocale, useNavigation, usePageData, usePayment, useProducts, useQueryParam, useQueryParams, useResponse, useResponses, useSafeArea, useTracking, useTranslation, useUser, useUserProperty, useVariable, useVariables };