@appfunnel-dev/sdk 0.6.0 → 0.8.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-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-BlgQ9C2d.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-BlgQ9C2d.cjs';
+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-C9MOEdND.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-C9MOEdND.cjs';
 import * as react from 'react';
 import { Appearance } from '@stripe/stripe-js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
@@ -40,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')
@@ -52,9 +55,17 @@ 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).
  *
@@ -72,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.*).
@@ -164,12 +190,12 @@ declare function useNavigation(): NavigationState;
 declare function useProducts(): ProductsState;
 
 /**
- * Tracking hook — fire events and identify users.
+ * Tracking hook — fire custom events.
  */
 declare function useTracking(): TrackingState;
 
 /**
- * Payment hook — reads payment-related variables.
+ * Payment hook — reads payment-related variables and provides a purchase action.
  *
  * Only re-renders when payment/card variables change.
  */
@@ -188,6 +214,47 @@ declare function usePayment(): PaymentState;
  */
 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.
  *
@@ -232,6 +299,9 @@ interface StripePaymentFormProps {
 /**
  * Stripe payment component supporting PaymentElement and Embedded Checkout.
  *
+ * In dev mode (`globalThis.__APPFUNNEL_DEV__`), renders a demo form that
+ * simulates Stripe UI and emulates purchases without real Stripe calls.
+ *
  * Use a ref to submit the form from an external button:
  * ```tsx
  * const paymentRef = useRef<StripePaymentHandle>(null)
@@ -288,4 +358,4 @@ type IntegrationLoader = (config: Record<string, unknown>) => void;
  */
 declare function registerIntegration(id: string, loader: IntegrationLoader): void;
 
-export { AppFunnelConfig, DeviceInfo, FunnelState, type IntegrationConfigs, LocaleState, NavigationState, PaddleCheckout, type PaddleCheckoutProps, PageData, PageDefinition, PaymentState, ProductsState, StripePaymentForm, type StripePaymentFormProps, type StripePaymentHandle, TrackingState, TranslationState, UserState, VariableValue, defineConfig, definePage, registerIntegration, useData, useDeviceInfo, useFunnel, useLocale, useNavigation, usePageData, 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,5 +1,5 @@
-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-BlgQ9C2d.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-BlgQ9C2d.js';
+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-C9MOEdND.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-C9MOEdND.js';
 import * as react from 'react';
 import { Appearance } from '@stripe/stripe-js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
@@ -40,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')
@@ -52,9 +55,17 @@ 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).
  *
@@ -72,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.*).
@@ -164,12 +190,12 @@ declare function useNavigation(): NavigationState;
 declare function useProducts(): ProductsState;
 
 /**
- * Tracking hook — fire events and identify users.
+ * Tracking hook — fire custom events.
  */
 declare function useTracking(): TrackingState;
 
 /**
- * Payment hook — reads payment-related variables.
+ * Payment hook — reads payment-related variables and provides a purchase action.
  *
  * Only re-renders when payment/card variables change.
  */
@@ -188,6 +214,47 @@ declare function usePayment(): PaymentState;
  */
 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.
  *
@@ -232,6 +299,9 @@ interface StripePaymentFormProps {
 /**
  * Stripe payment component supporting PaymentElement and Embedded Checkout.
  *
+ * In dev mode (`globalThis.__APPFUNNEL_DEV__`), renders a demo form that
+ * simulates Stripe UI and emulates purchases without real Stripe calls.
+ *
  * Use a ref to submit the form from an external button:
  * ```tsx
  * const paymentRef = useRef<StripePaymentHandle>(null)
@@ -288,4 +358,4 @@ type IntegrationLoader = (config: Record<string, unknown>) => void;
  */
 declare function registerIntegration(id: string, loader: IntegrationLoader): void;
 
-export { AppFunnelConfig, DeviceInfo, FunnelState, type IntegrationConfigs, LocaleState, NavigationState, PaddleCheckout, type PaddleCheckoutProps, PageData, PageDefinition, PaymentState, ProductsState, StripePaymentForm, type StripePaymentFormProps, type StripePaymentHandle, TrackingState, TranslationState, UserState, VariableValue, defineConfig, definePage, registerIntegration, useData, useDeviceInfo, useFunnel, useLocale, useNavigation, usePageData, 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 };