@tagadapay/plugin-sdk 3.1.25 → 4.0.2

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

@@ -1,15 +1,20 @@
 /**
  * usePixelTracking Hook & Provider
  *
- * SDK-level pixel tracking based on runtime stepConfig.pixels injected
- * by the CRM. Uses core/pixelMapping for event mapping and gating,
- * keeping browser-specific init/fire logic here.
+ * Thin React adapter over `core/pixelTracker`. The provider creates a tracker
+ * for the current `stepConfig.pixels`, exposes `{ track, pixelsInitialized }`
+ * via context, and disposes/recreates the tracker when pixels change.
+ *
+ * Init + fire logic lives in `core/pixelTracker` so non-React entries (Studio
+ * islands, full-SPA runtime) can fire pixels without mounting a provider.
  */
 import React from 'react';
-import { type StandardPixelEvent } from '../../core/pixelMapping';
+import { type TrackOptions } from '../../core/pixelTracker';
+import type { StandardPixelEvent } from '../../core/pixelMapping';
 export type { StandardPixelEvent } from '../../core/pixelMapping';
+export type { TrackOptions } from '../../core/pixelTracker';
 export interface PixelTrackingContextValue {
-    track: (eventName: StandardPixelEvent, parameters?: Record<string, unknown>) => void;
+    track: (eventName: StandardPixelEvent, parameters?: Record<string, unknown>, options?: TrackOptions) => void;
     pixelsInitialized: boolean;
 }
 export declare function PixelTrackingProvider({ children }: {

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

@@ -3,114 +3,46 @@ import { jsx as _jsx } from "react/jsx-runtime";
 /**
  * usePixelTracking Hook & Provider
  *
- * SDK-level pixel tracking based on runtime stepConfig.pixels injected
- * by the CRM. Uses core/pixelMapping for event mapping and gating,
- * keeping browser-specific init/fire logic here.
+ * Thin React adapter over `core/pixelTracker`. The provider creates a tracker
+ * for the current `stepConfig.pixels`, exposes `{ track, pixelsInitialized }`
+ * via context, and disposes/recreates the tracker when pixels change.
+ *
+ * Init + fire logic lives in `core/pixelTracker` so non-React entries (Studio
+ * islands, full-SPA runtime) can fire pixels without mounting a provider.
  */
-import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, } from 'react';
-import { resolvePixelEvents, } from '../../core/pixelMapping';
+import { createContext, useContext, useEffect, useMemo, useRef, useState, } from 'react';
+import { createPixelTracker, } from '../../core/pixelTracker';
 import { useStepConfig } from './useStepConfig';
 const PixelTrackingContext = createContext(null);
-// ---------------------------------------------------------------------------
-// Duplicate guard (time-window based)
-// ---------------------------------------------------------------------------
-function createDuplicateGuard(windowMs) {
-    const lastEvents = new Map();
-    return (eventName, parameters) => {
-        try {
-            const key = JSON.stringify({ eventName, parameters });
-            const now = Date.now();
-            const last = lastEvents.get(key);
-            if (last && now - last < windowMs)
-                return false;
-            lastEvents.set(key, now);
-            return true;
-        }
-        catch {
-            return true;
-        }
-    };
-}
-const shouldTrackEvent = createDuplicateGuard(5000);
-// ---------------------------------------------------------------------------
-// Provider
-// ---------------------------------------------------------------------------
 export function PixelTrackingProvider({ children }) {
     const { pixels } = useStepConfig();
+    const trackerRef = useRef(null);
     const [pixelsInitialized, setPixelsInitialized] = useState(false);
-    const isMountedRef = useRef(true);
-    useEffect(() => {
-        isMountedRef.current = true;
-        return () => { isMountedRef.current = false; };
-    }, []);
-    // ---- Initialize pixel scripts once ----
-    // Wait for all external scripts to actually load before marking initialized,
-    // so that pixel helpers (TikTok, etc.) can intercept events properly.
+    // Recreate the tracker when `pixels` changes. The underlying init helpers
+    // are idempotent — base scripts and per-pixel `init` calls de-duplicate
+    // themselves so a rebuild won't double-load scripts.
     useEffect(() => {
-        if (!pixels || pixelsInitialized || !isMountedRef.current)
+        if (!pixels)
             return;
-        const loadPromises = [];
-        try {
-            pixels.facebook?.forEach((px) => { if (px.enabled && px.pixelId)
-                loadPromises.push(initMetaPixel(px.pixelId)); });
-            pixels.tiktok?.forEach((px) => { if (px.enabled && px.pixelId)
-                loadPromises.push(initTikTokPixel(px.pixelId)); });
-            pixels.snapchat?.forEach((px) => { if (px.enabled && px.pixelId)
-                loadPromises.push(initSnapchatPixel(px.pixelId)); });
-            pixels.pinterest?.forEach((px) => { if (px.enabled && px.pixelId)
-                loadPromises.push(initPinterestPixel(px.pixelId)); });
-            pixels.gtm?.forEach((px) => { if (px.enabled && px.containerId)
-                loadPromises.push(initGTM(px.containerId)); });
-            Promise.all(loadPromises).then(() => {
-                if (isMountedRef.current)
-                    setPixelsInitialized(true);
-            });
-        }
-        catch (error) {
-            console.error('[SDK Pixels] Initialization error:', error);
-        }
-    }, [pixels, pixelsInitialized]);
-    // ---- Track function ----
-    const track = useCallback((eventName, parameters = {}) => {
-        if (!pixels || !pixelsInitialized || !isMountedRef.current)
-            return;
-        if (!shouldTrackEvent(eventName, parameters))
-            return;
-        try {
-            const events = resolvePixelEvents(pixels, eventName, parameters);
-            // Deduplicate by provider: Meta/Snapchat/Pinterest SDKs broadcast
-            // to all registered pixel IDs internally, so we only need to fire once per
-            // provider. GTM and TikTok need per-pixel firing (GTM for Google Ads
-            // send_to targeting, TikTok because ttq.instance() targets a specific pixel).
-            const firedProviders = new Set();
-            for (const { provider, mapped, pixel } of events) {
-                if (provider === 'gtm' || provider === 'tiktok') {
-                    fire(provider, mapped.name, mapped.params, pixel);
-                }
-                else {
-                    if (!firedProviders.has(provider)) {
-                        fire(provider, mapped.name, mapped.params);
-                        firedProviders.add(provider);
-                    }
-                }
-            }
-        }
-        catch (error) {
-            console.error('[SDK Pixels] Tracking error:', error);
-        }
-    }, [pixels, pixelsInitialized]);
-    // ---- Auto page-view ----
-    useEffect(() => {
-        if (!pixelsInitialized || !isMountedRef.current)
-            return;
-        const id = setTimeout(() => {
-            if (isMountedRef.current) {
-                track('PageView', { path: typeof window !== 'undefined' ? window.location.pathname : '' });
-            }
-        }, 0);
-        return () => clearTimeout(id);
-    }, [pixelsInitialized, track]);
-    const value = useMemo(() => ({ track, pixelsInitialized }), [track, pixelsInitialized]);
+        const tracker = createPixelTracker(pixels);
+        trackerRef.current = tracker;
+        setPixelsInitialized(false);
+        let cancelled = false;
+        tracker.initPromise.then(() => {
+            if (!cancelled)
+                setPixelsInitialized(true);
+        });
+        return () => {
+            cancelled = true;
+            trackerRef.current = null;
+        };
+    }, [pixels]);
+    const value = useMemo(() => ({
+        track: (eventName, parameters, options) => {
+            trackerRef.current?.track(eventName, parameters, options);
+        },
+        pixelsInitialized,
+    }), [pixelsInitialized]);
     return _jsx(PixelTrackingContext.Provider, { value: value, children: children });
 }
 export function usePixelTracking() {
@@ -119,277 +51,3 @@ export function usePixelTracking() {
         throw new Error('usePixelTracking must be used within a PixelTrackingProvider');
     return context;
 }
-// ---------------------------------------------------------------------------
-// Browser-specific: fire an event to the correct global pixel function
-// ---------------------------------------------------------------------------
-/* eslint-disable @typescript-eslint/no-explicit-any */
-function fire(provider, name, params, pixel) {
-    if (typeof window === 'undefined')
-        return;
-    const w = window;
-    switch (provider) {
-        case 'facebook':
-            w.fbq?.('track', name, params);
-            break;
-        case 'tiktok': {
-            // Use ttq.instance(pixelId) to target each pixel individually,
-            // since the global ttq.track() only fires for the sdkid pixel.
-            const pixelId = pixel && 'pixelId' in pixel ? pixel.pixelId : null;
-            const target = pixelId && w.ttq?.instance ? w.ttq.instance(pixelId) : w.ttq;
-            if (name === 'Pageview') {
-                target?.page?.();
-            }
-            else {
-                target?.track?.(name, params);
-            }
-            break;
-        }
-        case 'snapchat':
-            w.snaptr?.('track', name, params);
-            break;
-        case 'pinterest':
-            // Pinterest handles page views via pintrk('page'), not pintrk('track', 'pagevisit')
-            if (name === 'pagevisit') {
-                w.pintrk?.('page');
-            }
-            else {
-                w.pintrk?.('track', name, params);
-            }
-            break;
-        case 'gtm':
-            fireGTM(name, params);
-            break;
-    }
-}
-function fireGTM(event, params) {
-    try {
-        const w = window;
-        if (w.gtag) {
-            w.gtag('event', event, params);
-        }
-        else if (w.dataLayer) {
-            w.dataLayer.push({ event, ...params });
-        }
-    }
-    catch (error) {
-        console.error('[SDK GTM] Error:', error);
-    }
-}
-/* eslint-enable @typescript-eslint/no-explicit-any */
-// ===========================================================================
-// Pixel initialization (browser-only)
-// All pixel globals are accessed via `win` typed as `any` to avoid
-// `declare global` augmentation issues across tsconfig scopes.
-// ===========================================================================
-/* eslint-disable @typescript-eslint/no-explicit-any */
-const win = (typeof window !== 'undefined' ? window : undefined);
-const SCRIPT_LOAD_TIMEOUT_MS = 5000;
-function waitForScriptLoad(script) {
-    // If the script has already loaded, resolve immediately
-    if (script.dataset.loaded)
-        return Promise.resolve();
-    return new Promise((resolve) => {
-        const done = () => { script.dataset.loaded = '1'; clearTimeout(timer); resolve(); };
-        const timer = setTimeout(done, SCRIPT_LOAD_TIMEOUT_MS);
-        script.addEventListener('load', done, { once: true });
-        script.addEventListener('error', done, { once: true });
-    });
-}
-let _metaScriptEl = null;
-function initMetaPixel(pixelId) {
-    if (!win)
-        return Promise.resolve();
-    // Initialize Meta base code once
-    if (!win.fbq) {
-        const n = function (...args) {
-            if (n.callMethod)
-                n.callMethod(...args);
-            else
-                n.queue.push(args);
-        };
-        n.queue = [];
-        n.loaded = true;
-        n.version = '2.0';
-        win.fbq = n;
-        if (!win._fbq)
-            win._fbq = n;
-        const t = document.createElement('script');
-        t.async = true;
-        t.src = 'https://connect.facebook.net/en_US/fbevents.js';
-        const s = document.getElementsByTagName('script')[0];
-        s?.parentNode?.insertBefore(t, s);
-        _metaScriptEl = t;
-    }
-    // Register each pixel ID (fbq supports multiple pixels via multiple init calls)
-    win.fbq('init', pixelId);
-    return _metaScriptEl ? waitForScriptLoad(_metaScriptEl) : Promise.resolve();
-}
-let _tiktokBaseInitialized = false;
-function initTikTokPixel(pixelId) {
-    if (!win)
-        return Promise.resolve();
-    // Initialize TikTok base code once
-    if (!_tiktokBaseInitialized) {
-        _tiktokBaseInitialized = true;
-        win.TiktokAnalyticsObject = 'ttq';
-        const ttq = (win.ttq = win.ttq || []);
-        ttq.methods = [
-            'page', 'track', 'identify', 'instances', 'debug', 'on', 'off',
-            'once', 'ready', 'alias', 'group', 'enableCookie', 'disableCookie',
-            'holdConsent', 'revokeConsent', 'grantConsent',
-        ];
-        ttq.setAndDefer = function (t, e) {
-            t[e] = function (...args) { t.push([e, ...args]); };
-        };
-        for (const method of ttq.methods) {
-            ttq.setAndDefer(ttq, method);
-        }
-        ttq.instance = function (t) {
-            const e = ttq._i[t] || [];
-            for (const method of ttq.methods) {
-                ttq.setAndDefer(e, method);
-            }
-            return e;
-        };
-        ttq.load = function (e, n) {
-            const r = 'https://analytics.tiktok.com/i18n/pixel/events.js';
-            ttq._i = ttq._i || {};
-            ttq._i[e] = [];
-            ttq._i[e]._u = r;
-            ttq._t = ttq._t || {};
-            ttq._t[e] = +new Date();
-            ttq._o = ttq._o || {};
-            ttq._o[e] = n || {};
-            const s = document.createElement('script');
-            s.type = 'text/javascript';
-            s.async = true;
-            s.src = r + '?sdkid=' + e + '&lib=ttq';
-            const p = document.getElementsByTagName('script')[0];
-            p?.parentNode?.insertBefore(s, p);
-        };
-    }
-    // Skip if this specific pixel ID is already registered
-    if (win.ttq._i?.[pixelId])
-        return Promise.resolve();
-    // Register pixel and load its script
-    win.ttq.load(pixelId);
-    // Find the script we just created and wait for it
-    const scripts = document.querySelectorAll('script[src*="analytics.tiktok.com/i18n/pixel/events.js"]');
-    const lastScript = scripts[scripts.length - 1];
-    return lastScript ? waitForScriptLoad(lastScript) : Promise.resolve();
-}
-let _snapchatScriptEl = null;
-function initSnapchatPixel(pixelId) {
-    if (!win)
-        return Promise.resolve();
-    // Initialize Snapchat base code once
-    if (!win.snaptr) {
-        const a = function (...args) {
-            if (a.handleRequest)
-                a.handleRequest(...args);
-            else
-                a.queue.push(args);
-        };
-        a.queue = [];
-        win.snaptr = a;
-        const r = document.createElement('script');
-        r.async = true;
-        r.src = 'https://sc-static.net/scevent.min.js';
-        const u = document.getElementsByTagName('script')[0];
-        u?.parentNode?.insertBefore(r, u);
-        _snapchatScriptEl = r;
-    }
-    // Register each pixel ID (snaptr supports multiple pixels via multiple init calls)
-    win.snaptr('init', pixelId);
-    return _snapchatScriptEl ? waitForScriptLoad(_snapchatScriptEl) : Promise.resolve();
-}
-let _pinterestScriptEl = null;
-function initPinterestPixel(pixelId) {
-    if (!win)
-        return Promise.resolve();
-    // Initialize Pinterest base code once
-    if (!win.pintrk) {
-        const a = function (...args) { a.queue.push(args); };
-        a.queue = [];
-        win.pintrk = a;
-        const s = document.createElement('script');
-        s.async = true;
-        s.src = 'https://s.pinimg.com/ct/core.js';
-        const u = document.getElementsByTagName('script')[0];
-        u?.parentNode?.insertBefore(s, u);
-        _pinterestScriptEl = s;
-    }
-    // Register each pixel ID (pintrk supports multiple pixels via multiple load calls)
-    win.pintrk('load', pixelId);
-    // Note: pintrk('page') is NOT called here — the Provider's auto page-view
-    // effect handles it via fire(). Calling both would double-count page views.
-    return _pinterestScriptEl ? waitForScriptLoad(_pinterestScriptEl) : Promise.resolve();
-}
-function initGTM(containerId) {
-    if (!win || !containerId)
-        return Promise.resolve();
-    const isGtmContainer = containerId.startsWith('GTM-');
-    const scriptUrlPart = isGtmContainer
-        ? `googletagmanager.com/gtm.js?id=${containerId}`
-        : `googletagmanager.com/gtag/js?id=${containerId}`;
-    if (document.querySelector(`script[src*="${scriptUrlPart}"]`))
-        return Promise.resolve();
-    win.dataLayer = win.dataLayer || [];
-    // Push referrer domain context into dataLayer before GTM loads, so tags
-    // inside the container can use it for cross-domain tracking configuration.
-    try {
-        const ref = document.referrer && new URL(document.referrer).hostname;
-        if (ref && ref !== window.location.hostname) {
-            win.dataLayer.push({ tagada_referrer_domain: ref });
-        }
-    }
-    catch { /* ignore invalid referrer */ }
-    if (isGtmContainer) {
-        win.dataLayer.push({ 'gtm.start': new Date().getTime(), event: 'gtm.js' });
-        const f = document.getElementsByTagName('script')[0];
-        const j = document.createElement('script');
-        j.async = true;
-        j.src = 'https://www.googletagmanager.com/gtm.js?id=' + containerId;
-        if (f?.parentNode)
-            f.parentNode.insertBefore(j, f);
-        else
-            (document.head || document.getElementsByTagName('head')[0])?.appendChild(j);
-        const noscript = document.createElement('noscript');
-        const iframe = document.createElement('iframe');
-        iframe.src = `https://www.googletagmanager.com/ns.html?id=${containerId}`;
-        iframe.height = '0';
-        iframe.width = '0';
-        iframe.style.display = 'none';
-        iframe.style.visibility = 'hidden';
-        noscript.appendChild(iframe);
-        (document.body || document.getElementsByTagName('body')[0])?.insertBefore(noscript, document.body?.firstChild ?? null);
-        return waitForScriptLoad(j);
-    }
-    else {
-        if (!win.gtag) {
-            win.gtag = function (..._args) { win.dataLayer.push(arguments); };
-        }
-        win.gtag('js', new Date());
-        // Enable cross-domain tracking: accept incoming _gl parameter from referring
-        // domains (e.g. Shopify store → TagadaPay checkout) so Google preserves the
-        // client-id/session across the redirect.
-        const linkerConfig = { accept_incoming: true };
-        try {
-            const ref = document.referrer && new URL(document.referrer).hostname;
-            if (ref && ref !== window.location.hostname) {
-                linkerConfig.domains = [ref, window.location.hostname];
-            }
-        }
-        catch { /* ignore invalid referrer */ }
-        win.gtag('config', containerId, { linker: linkerConfig });
-        const script = document.createElement('script');
-        script.async = true;
-        script.src = 'https://www.googletagmanager.com/gtag/js?id=' + containerId;
-        const firstScript = document.getElementsByTagName('script')[0];
-        if (firstScript?.parentNode)
-            firstScript.parentNode.insertBefore(script, firstScript);
-        else
-            (document.head || document.getElementsByTagName('head')[0])?.appendChild(script);
-        return waitForScriptLoad(script);
-    }
-}

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

@@ -72,7 +72,9 @@ export interface UsePreviewOfferResult {
         unitAmount: number;
         currency: string;
     }>;
-    pay: (mainOrderId?: string) => Promise<{
+    pay: (mainOrderId?: string, options?: {
+        initiatedBy?: 'merchant' | 'customer';
+    }) => Promise<{
         checkoutUrl: string;
     }>;
     toCheckout: (mainOrderId?: string) => Promise<{

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

@@ -10,6 +10,7 @@
 import { useQuery } from '@tanstack/react-query';
 import { useCallback, useEffect, useMemo, useState } from 'react';
 import { OffersResource } from '../../core/resources/offers';
+import { getAssignedPaymentInitiator } from '../../core/funnelClient';
 import { getGlobalApiClient } from './useApiQuery';
 export function usePreviewOffer(options) {
     const { offerId, currency: requestedCurrency = '', initialSelections = {} } = options;
@@ -228,13 +229,18 @@ export function usePreviewOffer(options) {
         });
     }, [summary, effectiveCurrency]);
     // Pay for the offer with current selections
-    const pay = useCallback(async (mainOrderId) => {
+    const pay = useCallback(async (mainOrderId, payOptions) => {
         if (isPaying) {
             throw new Error('Payment already in progress');
         }
         setIsPaying(true);
         try {
-            const result = await offersResource.payPreviewedOffer(offerId, effectiveCurrency, lineItemsForPreview, typeof window !== 'undefined' ? window.location.href : undefined, mainOrderId);
+            // Auto-pickup: stepConfig.paymentInitiator from the funnel client is
+            // applied when the caller does not pass an explicit override. This
+            // way the MIT/CIT toggle in the CRM step config takes effect for
+            // every consumer of usePreviewOffer without per-template wiring.
+            const initiatedBy = payOptions?.initiatedBy ?? getAssignedPaymentInitiator();
+            const result = await offersResource.payPreviewedOffer(offerId, effectiveCurrency, lineItemsForPreview, typeof window !== 'undefined' ? window.location.href : undefined, mainOrderId, initiatedBy);
             console.log('[usePreviewOffer] Payment initiated:', result);
             return {
                 checkoutUrl: result.checkout.checkoutUrl,

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

@@ -6,19 +6,21 @@ import { useMemo } from 'react';
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
 import { PromotionsResource } from '../../core/resources/promotions';
 import { getGlobalApiClient } from './useApiQuery';
+import { useTagadaContext } from '../providers/TagadaProvider';
 export function usePromotionsQuery(options = {}) {
     const { checkoutSessionId, enabled = true } = options;
     const queryClient = useQueryClient();
-    const client = getGlobalApiClient();
+    const apiClient = getGlobalApiClient();
+    const { client } = useTagadaContext();
     // Create resource client
     const promotionsResource = useMemo(() => {
         try {
-            return new PromotionsResource(client);
+            return new PromotionsResource(apiClient, client.bus);
         }
         catch (error) {
             throw new Error('Failed to initialize promotions resource: ' + (error instanceof Error ? error.message : 'Unknown error'));
         }
-    }, [client]);
+    }, [apiClient, client.bus]);
     // Main promotions query
     const { data: appliedPromotions = [], isLoading, error, refetch, } = useQuery({
         queryKey: ['promotions', checkoutSessionId],
@@ -40,6 +42,8 @@ export function usePromotionsQuery(options = {}) {
             if (checkoutSessionId) {
                 void queryClient.invalidateQueries({ queryKey: ['promotions', checkoutSessionId] });
                 void queryClient.invalidateQueries({ queryKey: ['checkout', checkoutSessionId] });
+                void queryClient.invalidateQueries({ queryKey: ['shipping-rates', checkoutSessionId] });
+                void queryClient.invalidateQueries({ queryKey: ['shipping-rates-preview', checkoutSessionId] });
             }
         },
     });
@@ -56,6 +60,8 @@ export function usePromotionsQuery(options = {}) {
             if (checkoutSessionId) {
                 void queryClient.invalidateQueries({ queryKey: ['promotions', checkoutSessionId] });
                 void queryClient.invalidateQueries({ queryKey: ['checkout', checkoutSessionId] });
+                void queryClient.invalidateQueries({ queryKey: ['shipping-rates', checkoutSessionId] });
+                void queryClient.invalidateQueries({ queryKey: ['shipping-rates-preview', checkoutSessionId] });
             }
         },
     });

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

@@ -23,9 +23,8 @@ 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);
+    // Preview rates params - triggers preview query when set
+    const [previewParams, setPreviewParams] = useState(null);
     // Main shipping rates query
     const { data: shippingRatesData, isLoading: isFetching, error: fetchError, refetch: refetchRates, } = useQuery({
         queryKey: ['shipping-rates', effectiveSessionId],
@@ -54,6 +53,23 @@ export function useShippingRatesQuery(options = {}) {
     });
     // Get sorted shipping rates from query data
     const shippingRates = shippingRatesData?.rates;
+    // Preview shipping rates query - invalidated by promotions mutations
+    const { data: previewedRates, isLoading: isPreviewLoading, } = useQuery({
+        queryKey: ['shipping-rates-preview', effectiveSessionId, previewParams?.countryCode, previewParams?.stateCode],
+        queryFn: async () => {
+            const response = await shippingRatesResource.previewShippingRates(effectiveSessionId, previewParams);
+            return [...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);
+            });
+        },
+        enabled: !!effectiveSessionId && !!previewParams,
+        staleTime: 30000,
+        refetchOnWindowFocus: false,
+    });
     // Get selected rate from checkout data
     const checkoutSelectedRateId = checkout?.checkoutSession?.shippingRate?.id;
     // Set shipping rate mutation
@@ -137,31 +153,30 @@ export function useShippingRatesQuery(options = {}) {
     const previewRates = useCallback(async (countryCode, stateCode) => {
         if (!enabled || !effectiveSessionId)
             return [];
+        setPreviewParams({ countryCode, stateCode });
         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);
+            return await queryClient.fetchQuery({
+                queryKey: ['shipping-rates-preview', effectiveSessionId, countryCode, stateCode],
+                queryFn: async () => {
+                    const response = await shippingRatesResource.previewShippingRates(effectiveSessionId, {
+                        countryCode,
+                        stateCode,
+                    });
+                    return [...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]);
+    }, [enabled, effectiveSessionId, queryClient, shippingRatesResource]);
     return {
         shippingRates,
         selectedRate,

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

@@ -63,6 +63,15 @@ export interface UseStepConfigResult {
      * undefined = inherit all store upsells, string[] = only these IDs.
      */
     upsellOfferIds: string[] | undefined;
+    /**
+     * Enabled in-step checkout-offer upsell IDs (tiered selector).
+     * undefined = inherit all store upsells of type='upsell'.
+     */
+    checkoutOfferIds: string[] | undefined;
+    /**
+     * Default checkout-offer upsell ID configured for this step (if any).
+     */
+    checkoutOfferDefaultId: string | 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 { getAssignedOrderBumpOfferIds, getAssignedPaymentFlowId, getAssignedPixels, getAssignedResources, getAssignedScripts, getAssignedStepConfig, getAssignedUpsellOfferIds, } from '../../core/funnelClient';
+import { getAssignedCheckoutOfferDefault, getAssignedCheckoutOfferIds, getAssignedOrderBumpOfferIds, getAssignedPaymentFlowId, getAssignedPixels, getAssignedResources, getAssignedScripts, getAssignedStepConfig, getAssignedUpsellOfferIds, } from '../../core/funnelClient';
 /**
  * Hook to access runtime step configuration injected via HTML
  *
@@ -46,6 +46,8 @@ export function useStepConfig() {
     const paymentSetupConfig = useMemo(() => stepConfig?.paymentSetupConfig, [stepConfig]);
     const orderBumpOfferIds = useMemo(() => getAssignedOrderBumpOfferIds(), []);
     const upsellOfferIds = useMemo(() => getAssignedUpsellOfferIds(), []);
+    const checkoutOfferIds = useMemo(() => getAssignedCheckoutOfferIds(), []);
+    const checkoutOfferDefaultId = useMemo(() => getAssignedCheckoutOfferDefault(), []);
     return {
         stepConfig,
         paymentFlowId,
@@ -56,5 +58,7 @@ export function useStepConfig() {
         paymentSetupConfig,
         orderBumpOfferIds,
         upsellOfferIds,
+        checkoutOfferIds,
+        checkoutOfferDefaultId,
     };
 }