@tagadapay/plugin-sdk 3.1.11 → 3.1.22

package/dist/v2/react/hooks/useShippingRatesQuery.d.ts

@@ -18,5 +18,11 @@ export interface UseShippingRatesQueryResult {
     error: Error | null;
     clearError: () => void;
     refetch: () => Promise<void>;
+    /** Preview shipping rates for a country without updating session */
+    previewRates: (countryCode: string, stateCode?: string) => Promise<ShippingRate[]>;
+    /** Rates from the last previewRates call */
+    previewedRates: ShippingRate[] | undefined;
+    /** Loading state for previewRates */
+    isPreviewLoading: boolean;
 }
 export declare function useShippingRatesQuery(options?: UseShippingRatesQueryOptions): UseShippingRatesQueryResult;

package/dist/v2/react/hooks/useShippingRatesQuery.js

@@ -3,7 +3,7 @@
  * Simplified shipping rates management with automatic cache invalidation
  */
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
-import { useCallback, useEffect, useMemo, useRef } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { ShippingRatesResource } from '../../core/resources/shippingRates';
 import { getGlobalApiClient } from './useApiQuery';
 export function useShippingRatesQuery(options = {}) {
@@ -23,10 +23,17 @@ export function useShippingRatesQuery(options = {}) {
     const effectiveSessionId = sessionId || checkout?.checkoutSession?.id;
     // Track if we've synced the initial selection from checkout
     const hasSyncedInitialSelectionRef = useRef(false);
+    // Preview rates state
+    const [previewedRates, setPreviewedRates] = useState();
+    const [isPreviewLoading, setIsPreviewLoading] = useState(false);
     // Main shipping rates query
     const { data: shippingRatesData, isLoading: isFetching, error: fetchError, refetch: refetchRates, } = useQuery({
         queryKey: ['shipping-rates', effectiveSessionId],
-        queryFn: () => shippingRatesResource.getShippingRates(effectiveSessionId),
+        queryFn: () => {
+            if (!enabled)
+                return Promise.resolve({ rates: [] });
+            return shippingRatesResource.getShippingRates(effectiveSessionId);
+        },
         enabled: enabled && !!effectiveSessionId,
         staleTime: 30000, // 30 seconds
         refetchOnWindowFocus: false,
@@ -73,8 +80,10 @@ export function useShippingRatesQuery(options = {}) {
     });
     // Select rate function
     const selectRate = useCallback(async (rateId) => {
+        if (!enabled)
+            return;
         await setShippingRateMutation.mutateAsync({ rateId });
-    }, [setShippingRateMutation]);
+    }, [enabled, setShippingRateMutation]);
     // Auto-select cheapest rate when:
     // 1. Rates are loaded
     // 2. No rate is currently selected in checkout
@@ -114,14 +123,45 @@ export function useShippingRatesQuery(options = {}) {
     }, [shippingRates, checkoutSelectedRateId]);
     // Refetch function
     const refetch = useCallback(async () => {
+        if (!enabled)
+            return;
         await refetchRates();
-    }, [refetchRates]);
+    }, [enabled, refetchRates]);
     // Clear error function
     const clearError = useCallback(() => {
         // TanStack Query doesn't provide a direct way to clear errors
         // We can trigger a refetch which will clear the error
         void refetch();
     }, [refetch]);
+    // Preview shipping rates for a country without updating session
+    const previewRates = useCallback(async (countryCode, stateCode) => {
+        if (!enabled || !effectiveSessionId)
+            return [];
+        try {
+            setIsPreviewLoading(true);
+            const response = await shippingRatesResource.previewShippingRates(effectiveSessionId, {
+                countryCode,
+                stateCode,
+            });
+            // Sort rates: free first, then by ascending amount
+            const sortedRates = [...response.rates].sort((a, b) => {
+                if (a.isFree && !b.isFree)
+                    return -1;
+                if (!a.isFree && b.isFree)
+                    return 1;
+                return (a.amount ?? 0) - (b.amount ?? 0);
+            });
+            setPreviewedRates(sortedRates);
+            return sortedRates;
+        }
+        catch (error) {
+            console.error('[useShippingRatesQuery] Error previewing shipping rates:', error);
+            return [];
+        }
+        finally {
+            setIsPreviewLoading(false);
+        }
+    }, [enabled, effectiveSessionId, shippingRatesResource]);
     return {
         shippingRates,
         selectedRate,
@@ -130,5 +170,8 @@ export function useShippingRatesQuery(options = {}) {
         error: (fetchError || setShippingRateMutation.error),
         clearError,
         refetch,
+        previewRates,
+        previewedRates,
+        isPreviewLoading,
     };
 }

package/dist/v2/react/hooks/useStepConfig.d.ts

@@ -21,7 +21,7 @@
  * const offerId = staticResources?.offer;
  * ```
  */
-import { GTMTrackingConfig, MetaConversionTrackingConfig, PixelTrackingConfig, RuntimeStepConfig, SnapchatTrackingConfig, TrackingProvider } from '../../core/funnelClient';
+import { PixelsConfig, RuntimeStepConfig } from '../../core/funnelClient';
 export interface UseStepConfigResult {
     /**
      * Full step configuration object
@@ -45,13 +45,7 @@ export interface UseStepConfigResult {
      * @param position - Where the scripts should be injected
      */
     getScripts: (position?: 'head-start' | 'head-end' | 'body-start' | 'body-end') => RuntimeStepConfig['scripts'];
-    pixels: {
-        [TrackingProvider.FACEBOOK]?: PixelTrackingConfig[];
-        [TrackingProvider.TIKTOK]?: PixelTrackingConfig[];
-        [TrackingProvider.SNAPCHAT]?: SnapchatTrackingConfig[];
-        [TrackingProvider.META_CONVERSION]?: MetaConversionTrackingConfig[];
-        [TrackingProvider.GTM]?: GTMTrackingConfig[];
-    } | undefined;
+    pixels: PixelsConfig | undefined;
 }
 /**
  * Hook to access runtime step configuration injected via HTML

package/dist/v2/react/hooks/useStepConfig.js

@@ -22,7 +22,7 @@
  * ```
  */
 import { useMemo } from 'react';
-import { getAssignedPaymentFlowId, getAssignedPixels, getAssignedScripts, getAssignedStaticResources, getAssignedStepConfig, TrackingProvider } from '../../core/funnelClient';
+import { getAssignedPaymentFlowId, getAssignedPixels, getAssignedScripts, getAssignedStaticResources, getAssignedStepConfig, } from '../../core/funnelClient';
 /**
  * Hook to access runtime step configuration injected via HTML
  *

package/dist/v2/react/hooks/useWhopPaymentPolling.d.ts

@@ -0,0 +1,30 @@
+export interface WhopPayment {
+    id: string;
+    status: 'succeeded' | 'declined' | 'pending';
+    requireAction: 'none' | 'redirect' | 'error';
+    orderId: string;
+    amount: number;
+    currency: string;
+    order?: {
+        id: string;
+        amount: number;
+        currency: string;
+    };
+}
+export interface UseWhopPaymentPollingOptions {
+    apiService: {
+        fetch: <T>(url: string, options: any) => Promise<T>;
+    };
+    checkoutSessionId: string;
+    maxAttempts?: number;
+    intervalMs?: number;
+    onSuccess?: (payment: WhopPayment) => void;
+    onMaxAttemptsReached?: () => void;
+    onError?: (error: Error) => void;
+}
+export interface UseWhopPaymentPollingReturn {
+    startPolling: (receiptId: string, orderId: string) => void;
+    stopPolling: () => void;
+    isPolling: boolean;
+}
+export declare const useWhopPaymentPolling: ({ apiService, checkoutSessionId, maxAttempts, intervalMs, onSuccess, onMaxAttemptsReached, onError, }: UseWhopPaymentPollingOptions) => UseWhopPaymentPollingReturn;

package/dist/v2/react/hooks/useWhopPaymentPolling.js

@@ -0,0 +1,61 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+export const useWhopPaymentPolling = ({ apiService, checkoutSessionId, maxAttempts = 60, intervalMs = 2000, onSuccess, onMaxAttemptsReached, onError, }) => {
+    const pollIntervalRef = useRef(null);
+    const attemptsRef = useRef(0);
+    const currentParamsRef = useRef(null);
+    const [isPolling, setIsPolling] = useState(false);
+    const stopPolling = useCallback(() => {
+        if (pollIntervalRef.current) {
+            clearInterval(pollIntervalRef.current);
+            pollIntervalRef.current = null;
+        }
+        setIsPolling(false);
+        attemptsRef.current = 0;
+        currentParamsRef.current = null;
+    }, []);
+    const startPolling = useCallback((receiptId, orderId) => {
+        stopPolling();
+        attemptsRef.current = 0;
+        currentParamsRef.current = { receiptId, orderId };
+        setIsPolling(true);
+        pollIntervalRef.current = setInterval(async () => {
+            if (!currentParamsRef.current)
+                return;
+            try {
+                attemptsRef.current++;
+                console.log(`Whop payment polling attempt ${attemptsRef.current}/${maxAttempts}...`);
+                const data = await apiService.fetch(`/api/v1/checkout-sessions/${checkoutSessionId}/whop-payment-status`, {
+                    method: 'POST',
+                    body: JSON.stringify(currentParamsRef.current),
+                    headers: { 'Content-Type': 'application/json' },
+                });
+                if (data && (data.status === 'succeeded' || data.status === 'declined')) {
+                    stopPolling();
+                    onSuccess?.(data);
+                }
+                else if (attemptsRef.current >= maxAttempts) {
+                    stopPolling();
+                    onMaxAttemptsReached?.();
+                }
+            }
+            catch (error) {
+                console.warn(`Whop polling attempt ${attemptsRef.current} failed:`, error);
+                if (attemptsRef.current >= maxAttempts) {
+                    stopPolling();
+                    onError?.(error instanceof Error ? error : new Error(String(error)));
+                }
+                // Otherwise keep polling through transient errors
+            }
+        }, intervalMs);
+    }, [apiService, checkoutSessionId, maxAttempts, intervalMs, onSuccess, onMaxAttemptsReached, onError, stopPolling]);
+    useEffect(() => {
+        return () => {
+            stopPolling();
+        };
+    }, [stopPolling]);
+    return {
+        startPolling,
+        stopPolling,
+        isPolling,
+    };
+};

package/dist/v2/react/index.d.ts

@@ -8,6 +8,7 @@ export type { DebugScript } from './providers/TagadaProvider';
 export { ApplePayButton } from './components/ApplePayButton';
 export { GooglePayButton } from './components/GooglePayButton';
 export { PreviewModeIndicator } from './components/PreviewModeIndicator';
+export { WhopCheckout } from './components/WhopCheckout';
 export { useApplePayCheckout } from './hooks/useApplePayCheckout';
 export { useAuth } from './hooks/useAuth';
 export { useCheckoutToken } from './hooks/useCheckoutToken';
@@ -46,6 +47,7 @@ export { useThreeds } from './hooks/useThreeds';
 export { useThreedsModal } from './hooks/useThreedsModal';
 export { useTranslation } from './hooks/useTranslation';
 export { useVipOffersQuery as useVipOffers } from './hooks/useVipOffersQuery';
+export { useWhopPaymentPolling } from './hooks/useWhopPaymentPolling';
 export { useFunnel } from './hooks/useFunnel';
 export { useStepConfig } from './hooks/useStepConfig';
 export { useFunnel as useFunnelLegacy, useSimpleFunnel } from './hooks/useFunnelLegacy';
@@ -63,6 +65,8 @@ export type { UseLoginOptions, UseLoginResult } from './hooks/useLogin';
 export type { ApplePayButtonProps } from './components/ApplePayButton';
 export type { GooglePayButtonProps } from './components/GooglePayButton';
 export type { PreviewModeIndicatorProps } from './components/PreviewModeIndicator';
+export type { WhopCheckoutHandle, WhopCheckoutProps } from './components/WhopCheckout';
+export type { WhopPayment, UseWhopPaymentPollingOptions, UseWhopPaymentPollingReturn } from './hooks/useWhopPaymentPolling';
 export type { GeoLocationData, UseGeoLocationOptions, UseGeoLocationReturn } from './hooks/useGeoLocation';
 export type { ExtractedAddress, GooglePlaceDetails, GooglePrediction, UseGoogleAutocompleteOptions, UseGoogleAutocompleteResult } from './hooks/useGoogleAutocomplete';
 export type { ISOCountry, ISORegion, UseISODataResult } from './hooks/useISOData';
@@ -89,4 +93,7 @@ export type { UseStoreConfigQueryOptions as UseStoreConfigOptions, UseStoreConfi
 export type { PaymentInstrument, ThreedsChallenge, ThreedsHook, ThreedsOptions, ThreedsProvider, ThreedsSession } from './hooks/useThreeds';
 export type { UseVipOffersQueryOptions as UseVipOffersOptions, UseVipOffersQueryResult as UseVipOffersResult } from './hooks/useVipOffersQuery';
 export { formatMoney } from '../../react/utils/money';
+export { TagadaError, TagadaApiError, TagadaNetworkError, TagadaAuthError, TagadaValidationError, TagadaCircuitBreakerError, TagadaErrorCode, } from '../core/errors';
+export type { TagadaErrorOptions, TagadaErrorCodeValue } from '../core/errors';
+export type { Order, OrderItem as CoreOrderItem, OrderAddress, OrderSummary, OrderWithRelations, PaymentSummary, PromotionSummary, Subscription, DeviceInfo, PromotionCode, Customer, Store, PickupPoint, } from '../core/types';
 export type OrderItem = import('../core/utils/order').OrderLineItem;

package/dist/v2/react/index.js

@@ -9,6 +9,7 @@ export { TagadaProvider, useTagadaContext } from './providers/TagadaProvider';
 export { ApplePayButton } from './components/ApplePayButton';
 export { GooglePayButton } from './components/GooglePayButton';
 export { PreviewModeIndicator } from './components/PreviewModeIndicator';
+export { WhopCheckout } from './components/WhopCheckout';
 // Hooks
 export { useApplePayCheckout } from './hooks/useApplePayCheckout';
 export { useAuth } from './hooks/useAuth';
@@ -48,6 +49,7 @@ export { useThreeds } from './hooks/useThreeds';
 export { useThreedsModal } from './hooks/useThreedsModal';
 export { useTranslation } from './hooks/useTranslation';
 export { useVipOffersQuery as useVipOffers } from './hooks/useVipOffersQuery';
+export { useWhopPaymentPolling } from './hooks/useWhopPaymentPolling';
 // Funnel hooks
 export { useFunnel } from './hooks/useFunnel';
 // Step config hook (access runtime configuration from HTML injection)
@@ -58,3 +60,5 @@ export { useFunnel as useFunnelLegacy, useSimpleFunnel } from './hooks/useFunnel
 export { FunnelActionType } from '../core/resources/funnel';
 // Re-export utilities from main react
 export { formatMoney } from '../../react/utils/money';
+// Error types
+export { TagadaError, TagadaApiError, TagadaNetworkError, TagadaAuthError, TagadaValidationError, TagadaCircuitBreakerError, TagadaErrorCode, } from '../core/errors';

package/dist/v2/react/providers/ExpressPaymentMethodsProvider.d.ts

@@ -3,6 +3,7 @@
  * Manages express payment methods (Apple Pay, Google Pay, PayPal, Klarna)
  */
 import React, { ReactNode } from 'react';
+import { TagadaError } from '../../core/errors';
 import { CheckoutData } from '../../core/resources/checkout';
 import { Address, PaymentMethod } from '../../core/resources/expressPaymentMethods';
 type ExpressOrderLineItem = {
@@ -47,7 +48,7 @@ interface ExpressPaymentMethodsContextType {
         };
     }) => Promise<void>;
     loading?: boolean;
-    error: string | null;
+    error: TagadaError | null;
     setError: (error: string | null) => void;
 }
 interface ExpressPaymentMethodsProviderProps {

package/dist/v2/react/providers/ExpressPaymentMethodsProvider.js

@@ -5,6 +5,7 @@ import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
  */
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
 import { createContext, useCallback, useMemo, useState } from 'react';
+import { TagadaError, TagadaErrorCode } from '../../core/errors';
 import { ExpressPaymentMethodsResource, } from '../../core/resources/expressPaymentMethods';
 import { getGlobalApiClient } from '../hooks/useApiQuery';
 import { useShippingRatesQuery } from '../hooks/useShippingRatesQuery';
@@ -170,6 +171,7 @@ export const ExpressPaymentMethodsProvider = ({ children, customerId, checkout,
     const paypalPaymentMethod = useMemo(() => paymentMethods?.find((p) => p.type === 'paypal'), [paymentMethods]);
     const klarnaPaymentMethod = useMemo(() => paymentMethods?.find((p) => p.type === 'klarna'), [paymentMethods]);
     const loading = !paymentMethods || isLoadingPaymentMethods;
+    const tagadaError = useMemo(() => error ? new TagadaError(error, { code: TagadaErrorCode.PAYMENT_FAILED }) : null, [error]);
     const contextValue = {
         paymentMethods,
         availableExpressPaymentMethodIds,
@@ -185,7 +187,7 @@ export const ExpressPaymentMethodsProvider = ({ children, customerId, checkout,
         handleAddExpressId,
         updateCheckoutSessionValues,
         updateCustomerEmail,
-        error,
+        error: tagadaError,
         setError,
     };
     const hasAnyEnabled = Boolean(applePayPaymentMethod || googlePayPaymentMethod || paypalPaymentMethod || klarnaPaymentMethod);

package/dist/v2/react/providers/TagadaProvider.js

@@ -4,7 +4,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
  * TagadaProvider - Main provider component for the Tagada Pay React SDK
  */
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import { createContext, useCallback, useContext, useEffect, useMemo, useState } from 'react';
+import { Suspense, createContext, useCallback, useContext, useEffect, useMemo, useState } from 'react';
 import { ApiService } from '../../../react/services/apiService';
 import { convertCurrency, formatMoney, formatMoneyWithoutSymbol, formatSimpleMoney, getCurrencyInfo, minorUnitsToMajorUnits, moneyStringOrNumberToMinorUnits, } from '../../../react/utils/money';
 import { TagadaClient } from '../../core/client';
@@ -38,11 +38,11 @@ const InitializationLoader = () => (_jsxs("div", { style: {
                 borderTop: '1.5px solid #9ca3af',
                 borderRadius: '50%',
                 animation: 'tagada-spin 1s linear infinite',
-            } }), _jsx("span", { children: "Loading..." }), _jsx("style", { children: `
-        @keyframes tagada-spin {
-          0% { transform: rotate(0deg); }
-          100% { transform: rotate(360deg); }
-        }
+            } }), _jsx("span", { children: "Loading..." }), _jsx("style", { children: `
+        @keyframes tagada-spin {
+          0% { transform: rotate(0deg); }
+          100% { transform: rotate(360deg); }
+        }
       ` })] }));
 const TagadaContext = createContext(null);
 export function TagadaProvider({ children, environment, customApiConfig, debugMode, localConfig, blockUntilSessionReady = false, rawPluginConfig, features, funnelId, autoInitializeFunnel = true, onNavigate, onFunnelError, debugScripts = [], }) {
@@ -213,6 +213,75 @@ export function TagadaProvider({ children, environment, customApiConfig, debugMo
         formatSimpleMoney,
     }), []);
     const [isDebugDrawerOpen, setIsDebugDrawerOpen] = useState(false);
+    // Track last injected script to prevent duplicate execution
+    /**
+     * Editor Element Click Bridge (Iframe → Parent)
+     *
+     * When running inside the CRM config editor iframe, elements can declare an `editor-id`
+     * attribute (e.g. <h1 editor-id="config.texts.checkoutTitle">Title</h1>).
+     *
+     * This effect sets up a delegated click listener on `document` that:
+     * - Finds the closest ancestor with an `editor-id`
+     * - Sends a `postMessage` to `window.parent` with the editorId and text content
+     *
+     * The parent (ConfigEditor) can then map this back to the corresponding config field.
+     */
+    useEffect(() => {
+        if (typeof window === 'undefined' || typeof document === 'undefined') {
+            return;
+        }
+        const handleClick = (event) => {
+            if (!(event.target instanceof Element))
+                return;
+            const targetWithEditorId = event.target.closest('[editor-id]');
+            if (!targetWithEditorId)
+                return;
+            const editorId = targetWithEditorId.getAttribute('editor-id');
+            if (!editorId)
+                return;
+            const textContent = targetWithEditorId.textContent ?? '';
+            // Only attempt cross-window messaging when inside an iframe
+            const isInIframe = window.parent && window.parent !== window;
+            if (!isInIframe) {
+                return;
+            }
+            const message = {
+                type: 'TAGADAPAY_EDITOR_ELEMENT_CLICK',
+                editorId,
+                textContent,
+            };
+            try {
+                // Derive parent origin from document.referrer when possible; fall back to '*'
+                // This avoids postMessage origin mismatch errors in dev (e.g. 3001 ↔ 5173)
+                let targetOrigin = '*';
+                try {
+                    if (typeof document !== 'undefined' && document.referrer) {
+                        const url = new URL(document.referrer);
+                        targetOrigin = url.origin;
+                    }
+                }
+                catch {
+                    // Fallback to '*'
+                    targetOrigin = '*';
+                }
+                window.parent.postMessage(message, targetOrigin);
+                if (state.debugMode) {
+                    // eslint-disable-next-line no-console
+                    console.log('[TagadaProvider] Sent editor element click to parent:', message);
+                }
+            }
+            catch (error) {
+                if (state.debugMode) {
+                    // eslint-disable-next-line no-console
+                    console.error('[TagadaProvider] Failed to post editor element click message:', error);
+                }
+            }
+        };
+        document.addEventListener('click', handleClick, true);
+        return () => {
+            document.removeEventListener('click', handleClick, true);
+        };
+    }, [state.debugMode]);
     // Funnel Methods
     const funnelMethods = useMemo(() => {
         if (!client.funnel) {
@@ -335,7 +404,7 @@ export function TagadaProvider({ children, environment, customApiConfig, debugMo
                                     boxShadow: '0 4px 12px rgba(0, 0, 0, 0.3)',
                                     zIndex: 999997,
                                     transition: 'all 0.2s ease',
-                                }, title: "Open TagadaPay SDK Debug Panel", children: "\uD83D\uDC1B" }), _jsx(DebugDrawer, { isOpen: isDebugDrawerOpen, onClose: () => setIsDebugDrawerOpen(false) })] })), canRenderChildren && children] }) }) }));
+                                }, title: "Open TagadaPay SDK Debug Panel", children: "\uD83D\uDC1B" }), _jsx(Suspense, { fallback: null, children: _jsx(DebugDrawer, { isOpen: isDebugDrawerOpen, onClose: () => setIsDebugDrawerOpen(false) }) })] })), canRenderChildren && children] }) }) }));
 }
 export function useTagadaContext() {
     const context = useContext(TagadaContext);

package/dist/v2/standalone/external-tracker.d.ts

@@ -1,59 +1,48 @@
 /**
  * TagadaPay External Page Tracker
  *
- * A lightweight standalone script for tracking users on external pages
- * that are part of a Tagadapay funnel but not hosted on the Tagadapay platform.
+ * Standalone script for tracking users on external pages that are part of a
+ * TagadaPay funnel but not hosted on the TagadaPay platform.
  *
- * ARCHITECTURE:
- * - Reuses core SDK infrastructure (TagadaClient) for authentication and API handling
- * - All tracking handled automatically by funnelOrchestrator via autoInitialize() and navigate()
- * - No separate tracking endpoints needed - unified tracking through orchestrator
+ * Use cases:
+ *   - WooCommerce / WordPress storefronts
+ *   - Custom landing pages
+ *   - Any external page that is a funnel step
  *
- * Usage (via CDN):
+ * @example CDN usage
+ * ```html
  * <script src="https://cdn.jsdelivr.net/npm/@tagadapay/plugin-sdk/dist/external-tracker.min.js"></script>
  * <script>
  *   TagadaTracker.init({
  *     storeId: 'store_xxx',
  *     accountId: 'acc_xxx',
- *     funnelId: 'funnel_xxx',  // Optional: detected from URL
  *     stepId: 'step_xxx',
- *     stepName: 'External Offer Page',
- *     stepType: 'external'
- *   });
- *
- *   // Navigate to next step (tracking automatic)
- *   TagadaTracker.navigate({
- *     eventType: 'form.submitted',
- *     eventData: { email: 'user@example.com' }
  *   });
  * </script>
+ * ```
  */
 import type { TagadaClient } from '../core/client';
+export declare const TRACKER_VERSION = "1.0.0";
 export interface TagadaTrackerConfig {
     /** Store ID (required) */
     storeId: string;
-    /** Account ID (required for session init) */
-    accountId?: string;
-    /** Funnel ID (optional - can be extracted from URL param) */
+    /** Account ID (required — session init will fail without it) */
+    accountId: string;
+    /** Funnel ID (optional — can be extracted from URL param) */
     funnelId?: string;
-    /**
-     * Step ID (REQUIRED for external pages)
-     *
-     * External URLs cannot be mapped to steps via URL matching (only works for Tagadapay-hosted pages).
-     * You must explicitly specify which step this external page represents.
-     */
+    /** Step ID (required for external pages — URL-to-step mapping only works for TagadaPay-hosted pages) */
     stepId: string;
-    /** Step name (optional - for analytics/debugging) */
+    /** Step name (optional — for analytics/debugging) */
     stepName?: string;
-    /** Step type (optional - e.g., 'landing', 'offer', 'external') */
+    /** Step type (optional — e.g., 'landing', 'offer', 'external') */
     stepType?: string;
-    /** API base URL (defaults to production) */
+    /** API base URL (defaults to https://app.tagadapay.com) */
     apiBaseUrl?: string;
     /** Enable debug logging */
     debug?: boolean;
     /** Callback when session is ready */
     onReady?: (session: ExternalTrackerSession) => void;
-    /** Callback on error */
+    /** Callback on error — when provided, init() will NOT throw */
     onError?: (error: Error) => void;
 }
 export interface ExternalTrackerSession {
@@ -71,49 +60,66 @@ export interface NavigateOptions {
     eventData?: Record<string, unknown>;
     /** Override return URL */
     returnUrl?: string;
-    /** Disable auto-redirect to control navigation manually (default: true) */
+    /** Whether to auto-redirect after navigation (default: true) */
     autoRedirect?: boolean;
 }
+export interface TrackEventOptions {
+    /** Event name (e.g., 'button_click', 'scroll_depth', 'video_play') */
+    name: string;
+    /** Arbitrary event data */
+    data?: Record<string, unknown>;
+}
 declare class TagadaExternalTracker {
     private config;
     private client;
     private initialized;
     private initializing;
+    private unsubscribe;
+    /** Tracker version */
+    readonly version = "1.0.0";
     /**
-     * Initialize the tracker using SDK infrastructure
+     * Initialize the tracker.
+     * When `onError` is provided, errors are passed to the callback and init()
+     * resolves to `null` instead of throwing.
      */
     init(config: TagadaTrackerConfig): Promise<ExternalTrackerSession | null>;
-    /**
-     * Get current session from SDK state
-     */
+    /** Get current session data. */
     getSession(): ExternalTrackerSession | null;
-    /**
-     * Check if tracker is ready
-     */
+    /** Whether the tracker is fully initialized and ready. */
     isReady(): boolean;
     /**
-     * Navigate to next step in funnel using SDK's funnel client
+     * Navigate to the next step in the funnel.
+     * By default, auto-redirects the browser window.
      */
     navigate(options: NavigateOptions): Promise<{
         url: string;
     } | null>;
     /**
-     * Get customer ID (for identifying the user)
+     * Track a custom event (e.g., button click, scroll depth, video play).
+     * Events are sent through the funnel orchestrator for unified analytics.
      */
+    trackEvent(options: TrackEventOptions): Promise<void>;
+    /** Get customer ID. */
     getCustomerId(): string | null;
-    /**
-     * Get funnel session ID
-     */
+    /** Get funnel session ID. */
     getFunnelSessionId(): string | null;
     /**
-     * Build a URL with funnel context parameters
-     * Useful for linking to other external pages while preserving session
+     * Build a URL that preserves funnel session context.
+     * Use this to link to other external pages within the same funnel.
      */
     buildUrl(baseUrl: string, additionalParams?: Record<string, string>): string;
+    /** Get the underlying SDK client (advanced usage). */
+    getClient(): TagadaClient | null;
     /**
-     * Get the underlying SDK client (for advanced usage)
+     * Reset the tracker to a new step without re-creating the session.
+     * Useful for SPAs that navigate between funnel steps client-side.
      */
-    getClient(): TagadaClient | null;
+    reset(newStepId: string): Promise<ExternalTrackerSession | null>;
+    /**
+     * Destroy the tracker, clean up event listeners and state.
+     * Call this when the tracker is no longer needed (e.g., SPA teardown).
+     */
+    destroy(): void;
     private waitForClientReady;
     private initializeFunnel;
 }