@tagadapay/plugin-sdk 3.1.22 → 3.1.25

package/dist/v2/cdn-react-minimal.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Minimal React SDK for CDN
+ *
+ * This is a slim bundle for use with TagadaStudio's esbuild mode.
+ * Only includes essential hooks needed for checkout pages.
+ *
+ * Full SDK is much larger due to TanStack Query, ISO data, etc.
+ * This minimal version keeps the bundle small (~100KB vs ~9MB).
+ */
+export { TagadaProvider, useTagadaContext } from './react/providers/TagadaProvider';
+export { useCheckoutQuery as useCheckout } from './react/hooks/useCheckoutQuery';
+export { useShippingRatesQuery as useShippingRates } from './react/hooks/useShippingRatesQuery';
+export { useDiscountsQuery as useDiscounts } from './react/hooks/useDiscountsQuery';
+export { useOrderBumpQuery as useOrderBump } from './react/hooks/useOrderBumpQuery';
+export { useOrderQuery as useOrder } from './react/hooks/useOrderQuery';
+export { usePostPurchasesQuery as usePostPurchases } from './react/hooks/usePostPurchasesQuery';
+export { usePaymentQuery as usePayment } from './react/hooks/usePaymentQuery';
+export { useThreeds } from './react/hooks/useThreeds';
+export { useCurrency } from './react/hooks/useCurrency';
+export { usePluginConfig } from './react/hooks/usePluginConfig';
+export { useFunnel } from './react/hooks/useFunnel';
+export { formatMoney } from './core/utils/currency';
+export type { FunnelContextValue } from './react/hooks/useFunnel';

package/dist/v2/cdn-react-minimal.js

@@ -0,0 +1,26 @@
+/**
+ * Minimal React SDK for CDN
+ *
+ * This is a slim bundle for use with TagadaStudio's esbuild mode.
+ * Only includes essential hooks needed for checkout pages.
+ *
+ * Full SDK is much larger due to TanStack Query, ISO data, etc.
+ * This minimal version keeps the bundle small (~100KB vs ~9MB).
+ */
+// Provider (essential)
+export { TagadaProvider, useTagadaContext } from './react/providers/TagadaProvider';
+// Core checkout hooks (essential for commerce)
+export { useCheckoutQuery as useCheckout } from './react/hooks/useCheckoutQuery';
+export { useShippingRatesQuery as useShippingRates } from './react/hooks/useShippingRatesQuery';
+export { useDiscountsQuery as useDiscounts } from './react/hooks/useDiscountsQuery';
+export { useOrderBumpQuery as useOrderBump } from './react/hooks/useOrderBumpQuery';
+export { useOrderQuery as useOrder } from './react/hooks/useOrderQuery';
+export { usePostPurchasesQuery as usePostPurchases } from './react/hooks/usePostPurchasesQuery';
+export { usePaymentQuery as usePayment } from './react/hooks/usePaymentQuery';
+export { useThreeds } from './react/hooks/useThreeds';
+// Utility hooks (commonly used)
+export { useCurrency } from './react/hooks/useCurrency';
+export { usePluginConfig } from './react/hooks/usePluginConfig';
+export { useFunnel } from './react/hooks/useFunnel';
+// Essential utilities
+export { formatMoney } from './core/utils/currency';

package/dist/v2/core/client.js

@@ -506,7 +506,7 @@ export class TagadaClient {
             if (this.state.debugMode) {
                 console.log(`[TagadaClient ${this.instanceId}] Initializing session...`, { sessionId: sessionData.sessionId });
             }
-            const deviceInfo = collectDeviceInfo();
+            const deviceInfo = await collectDeviceInfo();
             const urlParams = getUrlParams();
             const browserLocale = getBrowserLocale();
             // 🎯 Check draft mode from URL, localStorage, or cookie
@@ -527,6 +527,7 @@ export class TagadaClient {
                 utmSource: urlParams.utmSource,
                 utmMedium: urlParams.utmMedium,
                 utmCampaign: urlParams.utmCampaign,
+                gclid: urlParams.gclid,
                 browser: deviceInfo.userAgent.browser.name,
                 browserVersion: deviceInfo.userAgent.browser.version,
                 os: deviceInfo.userAgent.os.name,

package/dist/v2/core/config/environment.js

@@ -199,7 +199,8 @@ export function detectEnvironment() {
         hostname.includes('ngrok-free.dev') ||
         hostname.includes('ngrok-free.app') ||
         hostname.includes('ngrok.io') ||
-        hostname.includes('ngrok.app')) {
+        hostname.includes('ngrok.app') ||
+        hostname.includes('.loclx.io')) {
         console.log('[SDK] detectEnvironment() - returning LOCAL');
         // For local development, allow override via window.__TAGADA_ENV__ (injected by dev server)
         if (typeof window !== 'undefined' && window?.__TAGADA_ENV__?.TAGADA_ENVIRONMENT) {

package/dist/v2/core/funnelClient.d.ts

@@ -85,14 +85,87 @@ export type PixelsConfig = {
     [TrackingProvider.GTM]?: GTMTrackingConfig[];
 };
 /**
- * Runtime step configuration injected from the CRM
- * Contains payment flows, static resources, scripts, and tracking configs
+ * Payment method configuration entry.
+ *
+ * Key pattern in paymentSetupConfig:
+ *   "{method}" or "{method}:{provider}"
+ *   e.g. "card", "apple_pay:stripe", "paypal:tagada", "klarna:stripe"
+ *
+ * `method`   = what (universal payment method: card, apple_pay, klarna, ideal...)
+ * `provider` = who (processor family: tagada, stripe, airwallex, adyen...)
+ *
+ * @deprecated PaymentSetupMethod — use PaymentMethodConfig instead
  */
+export interface ExpressMethodState {
+    enabled: boolean;
+}
+export type PaymentSetupMethod = PaymentMethodConfig;
+export interface PaymentMethodConfig {
+    enabled: boolean;
+    /** Universal payment method identifier */
+    method: string;
+    /** Provider / processor family */
+    provider: string;
+    /** e.g. 'apm' for alternative payment methods, 'card', etc. */
+    type?: string;
+    /** Display label for the payment method */
+    label?: string;
+    /** URL to the payment method's logo */
+    logoUrl?: string;
+    /** Human-readable description shown to the customer */
+    description?: string;
+    /** Render as express checkout button above the form */
+    express?: boolean;
+    /** Card routing via payment flow (cascade, fraud, processor selection) */
+    paymentFlowId?: string;
+    /** Direct processor routing for APMs and express methods */
+    processorId?: string;
+    /** Tagada integration record ID for native integrations */
+    integrationId?: string;
+    supportedCountries?: string[];
+    presentmentCurrencies?: string[];
+    recurring?: boolean;
+    /** Present only on express_checkout:proc_id entries */
+    publishableKey?: string;
+    /** Present only on express_checkout:proc_id entries — map of apmKey → state */
+    methods?: Record<string, ExpressMethodState>;
+    /** Present only on crypto integration entries — map of providerId → provider state */
+    providers?: Record<string, {
+        enabled?: boolean;
+        label?: string;
+        min?: number;
+        note?: string;
+    }>;
+    metadata?: Record<string, any>;
+}
+export type PaymentSetupConfig = Record<string, PaymentMethodConfig>;
+/** Get all enabled entries from a paymentSetupConfig */
+export declare function getEnabledMethods(config: PaymentSetupConfig | undefined): PaymentMethodConfig[];
+/** Get all express methods (for rendering above the payment form) */
+export declare function getExpressMethods(config: PaymentSetupConfig | undefined): PaymentMethodConfig[];
+/** Group enabled express methods by processorId (one Express Element per processor) */
+export declare function getExpressMethodsByProcessor(config: PaymentSetupConfig | undefined): Record<string, PaymentMethodConfig[]>;
+/** Find a specific method entry by method name (returns first match) */
+export declare function findMethod(config: PaymentSetupConfig | undefined, method: string): PaymentMethodConfig | undefined;
+/** Check if a specific method is enabled (any provider) */
+export declare function isMethodEnabled(config: PaymentSetupConfig | undefined, method: string): boolean;
 export interface RuntimeStepConfig {
     payment?: {
         paymentFlowId?: string;
     };
+    paymentSetupConfig?: PaymentSetupConfig;
+    orderBumps?: {
+        mode: 'inherit' | 'custom';
+        enabledOfferIds?: string[];
+    };
+    upsellOffers?: {
+        mode: 'inherit' | 'custom';
+        enabledUpsellIds?: string[];
+    };
+    /** @deprecated Use `resources` instead */
     staticResources?: Record<string, string>;
+    /** Typed resource bindings (replaces staticResources) */
+    resources?: Record<string, string>;
     scripts?: Array<{
         name: string;
         enabled: boolean;
@@ -110,14 +183,20 @@ export interface LocalFunnelConfig {
     funnelId?: string;
     /** Step ID to simulate */
     stepId?: string;
-    /** Static resources (offer ID, product ID, etc.) */
+    /** @deprecated Use `resources` instead */
     staticResources?: Record<string, string>;
+    /** Resource bindings (offer ID, product ID, etc.) */
+    resources?: Record<string, string>;
     /** Payment flow ID override */
     paymentFlowId?: string;
     /** Custom scripts for local testing */
     scripts?: RuntimeStepConfig['scripts'];
     /** Pixel tracking config */
     pixels?: RuntimeStepConfig['pixels'];
+    /** Order bump filtering config for local testing */
+    orderBumps?: RuntimeStepConfig['orderBumps'];
+    /** Upsell offer filtering config for local testing */
+    upsellOffers?: RuntimeStepConfig['upsellOffers'];
 }
 /**
  * Load local funnel config from /config/funnel.local.json (for local dev only)
@@ -154,13 +233,22 @@ export declare function getLocalFunnelConfig(): LocalFunnelConfig | null;
  */
 export declare function getAssignedStepConfig(): RuntimeStepConfig | undefined;
 /**
- * Get the assigned payment flow ID from step config or legacy injection
- * Returns undefined if not available
+ * Get the assigned payment flow ID from step config or legacy injection.
+ * Resolution order:
+ *   1. paymentSetupConfig.card.paymentFlowId  (per-method, most specific)
+ *   2. stepConfig.payment.paymentFlowId        (per-step level)
+ *   3. window.__TGD_PAYMENT_FLOW_ID__          (legacy injection)
+ *   4. meta[name="x-payment-flow-id"]          (legacy meta tag)
  */
 export declare function getAssignedPaymentFlowId(): string | undefined;
 /**
- * Get the assigned static resources from step config
- * Returns undefined if not available
+ * Get resource bindings from step config.
+ * Reads from `resources` (new) with `staticResources` (legacy) as fallback, merged.
+ */
+export declare function getAssignedResources(): Record<string, string> | undefined;
+/**
+ * @deprecated Use `getAssignedResources()` instead.
+ * Kept for backward compatibility — reads from both `resources` and `staticResources`.
  */
 export declare function getAssignedStaticResources(): Record<string, string> | undefined;
 /**
@@ -168,11 +256,19 @@ export declare function getAssignedStaticResources(): Record<string, string> | u
  * Returns only enabled scripts, filtered by position if specified
  */
 export declare function getAssignedScripts(position?: 'head-start' | 'head-end' | 'body-start' | 'body-end'): RuntimeStepConfig['scripts'];
+export declare function getAssignedPixels(): PixelsConfig | undefined;
 /**
- * Get assigned pixel tracking configuration (normalized to arrays)
- * Always returns arrays of PixelConfig for consistent consumption.
+ * Get the enabled order bump offer IDs from step config.
+ * Returns undefined when mode is 'inherit' (use all store bumps).
+ * Returns the explicit list when mode is 'custom'.
  */
-export declare function getAssignedPixels(): PixelsConfig | undefined;
+export declare function getAssignedOrderBumpOfferIds(): string[] | undefined;
+/**
+ * Get the enabled upsell offer IDs from step config.
+ * Returns undefined when mode is 'inherit' (use all store upsells).
+ * Returns the explicit list when mode is 'custom'.
+ */
+export declare function getAssignedUpsellOfferIds(): string[] | undefined;
 export interface FunnelClientConfig {
     apiClient: ApiClient;
     debugMode?: boolean;

package/dist/v2/core/funnelClient.js

@@ -2,7 +2,7 @@ import { detectEnvironment } from './config/environment';
 import { FunnelActionType, FunnelResource } from './resources/funnel';
 import { EventDispatcher } from './utils/eventDispatcher';
 import { getSDKParams } from './utils/previewMode';
-import { injectPreviewModeIndicator } from './utils/previewModeIndicator';
+const lazyInjectPreviewIndicator = () => import('./utils/previewModeIndicator').then(m => m.injectPreviewModeIndicator());
 import { getFunnelSessionCookie, setFunnelSessionCookie } from './utils/sessionStorage';
 /**
  * Tracking providers supported by the SDK.
@@ -16,6 +16,41 @@ export var TrackingProvider;
     TrackingProvider["PINTEREST"] = "pinterest";
     TrackingProvider["GTM"] = "gtm";
 })(TrackingProvider || (TrackingProvider = {}));
+/** Get all enabled entries from a paymentSetupConfig */
+export function getEnabledMethods(config) {
+    if (!config)
+        return [];
+    return Object.values(config).filter(m => m.enabled);
+}
+/** Get all express methods (for rendering above the payment form) */
+export function getExpressMethods(config) {
+    return getEnabledMethods(config).filter(m => m.express);
+}
+/** Group enabled express methods by processorId (one Express Element per processor) */
+export function getExpressMethodsByProcessor(config) {
+    const groups = {};
+    for (const m of getExpressMethods(config)) {
+        const key = m.processorId || m.integrationId || m.provider;
+        if (!groups[key])
+            groups[key] = [];
+        groups[key].push(m);
+    }
+    return groups;
+}
+/** Find a specific method entry by method name (returns first match) */
+export function findMethod(config, method) {
+    if (!config)
+        return undefined;
+    for (const entry of Object.values(config)) {
+        if (entry.method === method && entry.enabled)
+            return entry;
+    }
+    return undefined;
+}
+/** Check if a specific method is enabled (any provider) */
+export function isMethodEnabled(config, method) {
+    return !!findMethod(config, method);
+}
 /**
  * Get the funnel ID from the injected HTML
  * Returns undefined if not available
@@ -183,11 +218,14 @@ export function getLocalFunnelConfig() {
  * Convert LocalFunnelConfig to RuntimeStepConfig
  */
 function localConfigToStepConfig(local) {
+    const merged = { ...local.staticResources, ...local.resources };
     return {
         payment: local.paymentFlowId ? { paymentFlowId: local.paymentFlowId } : undefined,
-        staticResources: local.staticResources,
+        resources: Object.keys(merged).length > 0 ? merged : undefined,
         scripts: local.scripts,
         pixels: local.pixels,
+        orderBumps: local.orderBumps,
+        upsellOffers: local.upsellOffers,
     };
 }
 /**
@@ -207,7 +245,6 @@ export function getAssignedStepConfig() {
     if (typeof window === 'undefined')
         return undefined;
     // Method 1: Local dev override (HIGHEST PRIORITY in local dev)
-    // Allows developers to test different configurations without redeploying
     const localConfig = getLocalFunnelConfig();
     if (localConfig) {
         console.log('🛠️ [SDK] Using local funnel.local.json (overrides injected)');
@@ -233,22 +270,29 @@ export function getAssignedStepConfig() {
     return undefined;
 }
 /**
- * Get the assigned payment flow ID from step config or legacy injection
- * Returns undefined if not available
+ * Get the assigned payment flow ID from step config or legacy injection.
+ * Resolution order:
+ *   1. paymentSetupConfig.card.paymentFlowId  (per-method, most specific)
+ *   2. stepConfig.payment.paymentFlowId        (per-step level)
+ *   3. window.__TGD_PAYMENT_FLOW_ID__          (legacy injection)
+ *   4. meta[name="x-payment-flow-id"]          (legacy meta tag)
  */
 export function getAssignedPaymentFlowId() {
-    // Method 1: New stepConfig (preferred)
     const stepConfig = getAssignedStepConfig();
+    // Method 1: Per-method config — card entry in paymentSetupConfig
+    const cardConfig = stepConfig?.paymentSetupConfig?.card;
+    if (cardConfig?.paymentFlowId) {
+        return cardConfig.paymentFlowId;
+    }
+    // Method 2: Per-step config (legacy but still supported)
     if (stepConfig?.payment?.paymentFlowId) {
         return stepConfig.payment.paymentFlowId;
     }
-    // Method 2: Legacy direct injection (backward compatibility)
+    // Method 3: Legacy direct injection (backward compatibility)
     if (typeof window !== 'undefined') {
-        // Legacy window variable
         if (window.__TGD_PAYMENT_FLOW_ID__) {
             return window.__TGD_PAYMENT_FLOW_ID__;
         }
-        // Legacy meta tag
         if (typeof document !== 'undefined') {
             const meta = document.querySelector('meta[name="x-payment-flow-id"]');
             return meta?.getAttribute('content') || undefined;
@@ -257,12 +301,23 @@ export function getAssignedPaymentFlowId() {
     return undefined;
 }
 /**
- * Get the assigned static resources from step config
- * Returns undefined if not available
+ * Get resource bindings from step config.
+ * Reads from `resources` (new) with `staticResources` (legacy) as fallback, merged.
  */
-export function getAssignedStaticResources() {
+export function getAssignedResources() {
     const stepConfig = getAssignedStepConfig();
-    return stepConfig?.staticResources;
+    const legacy = stepConfig?.staticResources;
+    const current = stepConfig?.resources;
+    if (!legacy && !current)
+        return undefined;
+    return { ...legacy, ...current };
+}
+/**
+ * @deprecated Use `getAssignedResources()` instead.
+ * Kept for backward compatibility — reads from both `resources` and `staticResources`.
+ */
+export function getAssignedStaticResources() {
+    return getAssignedResources();
 }
 /**
  * Get the assigned scripts from step config
@@ -284,6 +339,21 @@ export function getAssignedScripts(position) {
  * Get assigned pixel tracking configuration (normalized to arrays)
  * Always returns arrays of PixelConfig for consistent consumption.
  */
+/**
+ * Split a pixel config with semicolon/comma-separated IDs into individual configs.
+ * Handles cases where the CRM stores "ID1; ID2; ID3" as a single pixelId or containerId.
+ */
+function splitPixelConfig(px) {
+    // GTM configs use containerId
+    const idField = 'containerId' in px ? 'containerId' : 'pixelId';
+    const rawId = px[idField];
+    if (!rawId || !rawId.includes(';') && !rawId.includes(','))
+        return [px];
+    const ids = rawId.split(/[;,]/).map((id) => id.trim()).filter((id) => id.length > 0);
+    if (ids.length <= 1)
+        return [px];
+    return ids.map((id) => ({ ...px, [idField]: id }));
+}
 export function getAssignedPixels() {
     const stepConfig = getAssignedStepConfig();
     const rawPixels = stepConfig?.pixels;
@@ -294,17 +364,43 @@ export function getAssignedPixels() {
         if (!value)
             continue;
         if (Array.isArray(value)) {
-            // Already an array
-            normalized[key] = value;
+            // Expand any entries with semicolon/comma-separated pixelIds into separate configs
+            normalized[key] = value.flatMap((px) => splitPixelConfig(px));
         }
         else if (typeof value === 'object') {
-            // Single object - wrap in array
-            normalized[key] = [value];
+            // Single object - wrap in array, splitting if needed
+            normalized[key] = splitPixelConfig(value);
         }
         // Skip invalid entries
     }
     return Object.keys(normalized).length > 0 ? normalized : undefined;
 }
+/**
+ * Get the enabled order bump offer IDs from step config.
+ * Returns undefined when mode is 'inherit' (use all store bumps).
+ * Returns the explicit list when mode is 'custom'.
+ */
+export function getAssignedOrderBumpOfferIds() {
+    const stepConfig = getAssignedStepConfig();
+    if (!stepConfig?.orderBumps)
+        return undefined;
+    if (stepConfig.orderBumps.mode !== 'custom')
+        return undefined;
+    return stepConfig.orderBumps.enabledOfferIds;
+}
+/**
+ * Get the enabled upsell offer IDs from step config.
+ * Returns undefined when mode is 'inherit' (use all store upsells).
+ * Returns the explicit list when mode is 'custom'.
+ */
+export function getAssignedUpsellOfferIds() {
+    const stepConfig = getAssignedStepConfig();
+    if (!stepConfig?.upsellOffers)
+        return undefined;
+    if (stepConfig.upsellOffers.mode !== 'custom')
+        return undefined;
+    return stepConfig.upsellOffers.enabledUpsellIds;
+}
 export class FunnelClient {
     constructor(config) {
         this.eventDispatcher = new EventDispatcher();
@@ -444,8 +540,7 @@ export class FunnelClient {
             if (response.success && response.context) {
                 const enriched = this.enrichContext(response.context);
                 this.handleSessionSuccess(enriched);
-                // 🔍 Auto-inject preview mode indicator if in preview/dev mode
-                injectPreviewModeIndicator();
+                lazyInjectPreviewIndicator();
                 return enriched;
             }
             else {
@@ -495,8 +590,7 @@ export class FunnelClient {
             if (response.success && response.context) {
                 const enriched = this.enrichContext(response.context);
                 this.handleSessionSuccess(enriched);
-                // 🔍 Auto-inject preview mode indicator if in preview/dev mode
-                injectPreviewModeIndicator();
+                lazyInjectPreviewIndicator();
                 return enriched;
             }
             else {
@@ -608,19 +702,19 @@ export class FunnelClient {
                 : this.config.autoRedirect !== false; // Default to true
             // Skip refreshSession if auto-redirecting (next page will initialize with fresh state)
             // Only refresh if staying on same page (autoRedirect: false)
-            if (!shouldAutoRedirect) {
-                if (this.config.debugMode) {
-                    console.log('🔄 [FunnelClient] Refreshing session (no auto-redirect)');
-                }
-                await this.refreshSession();
-            }
+            // if (!shouldAutoRedirect) {
+            //   if (this.config.debugMode) {
+            //     console.log('🔄 [FunnelClient] Refreshing session (no auto-redirect)');
+            //   }
+            //   await this.refreshSession();
+            // }
             this.updateState({ isNavigating: false, isLoading: false });
             // Auto-redirect if enabled and result has a URL
             if (shouldAutoRedirect && result?.url && typeof window !== 'undefined') {
                 if (this.config.debugMode) {
                     console.log('🚀 [FunnelClient] Auto-redirecting to:', result.url, '(skipped session refresh - next page will initialize)');
                 }
-                window.location.href = result.url;
+                window.location.replace(result.url);
             }
             return result;
         }

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

@@ -7,6 +7,5 @@ export * from './resources';
 export * from './client';
 export * from './funnelClient';
 export * from './pathRemapping';
-export * from './pixelMapping';
 export * from './googleAutocomplete';
 export * from './isoData';

package/dist/v2/core/index.js

@@ -11,8 +11,6 @@ export * from './client';
 export * from './funnelClient';
 // Export path remapping helpers (framework-agnostic)
 export * from './pathRemapping';
-// Export pixel mapping (framework-agnostic, shared by React + standalone)
-export * from './pixelMapping';
 // Export legacy files that are still needed
 export * from './googleAutocomplete';
 export * from './isoData';

package/dist/v2/core/isoData.d.ts

@@ -1,7 +1,6 @@
 /**
- * ISO Data Core
- * Pure functions for country and region data management
- * Uses the existing iso3166 data functions
+ * ISO Data Core — CDN-backed country/region data (pure functions, no React).
+ * Call ensureLoaded() before using synchronous getters.
  */
 import { type SupportedLanguage } from '../../data/iso3166';
 export interface ISOCountry {
@@ -44,7 +43,8 @@ export declare class ISODataCore {
      */
     static importLanguage(language: SupportedLanguage): Promise<void>;
     /**
-     * Get available languages for ISO data
+     * Fetch countries + regions from CDN for a language (call before sync getters)
      */
+    static ensureLoaded(language?: SupportedLanguage): Promise<void>;
     static getAvailableLanguages(): SupportedLanguage[];
 }

package/dist/v2/core/isoData.js

@@ -1,10 +1,8 @@
 /**
- * ISO Data Core
- * Pure functions for country and region data management
- * Uses the existing iso3166 data functions
+ * ISO Data Core — CDN-backed country/region data (pure functions, no React).
+ * Call ensureLoaded() before using synchronous getters.
  */
-// Import the pre-built ISO data functions
-import { getCountries, getStatesForCountry, importLanguage, isLanguageRegistered, getRegisteredLanguages } from '../../data/iso3166';
+import { getCountries, getStatesForCountry, ensureGeoDataLoaded, importLanguage, isLanguageRegistered, getRegisteredLanguages } from '../../data/iso3166';
 export class ISODataCore {
     /**
      * Get countries data for a specific language
@@ -94,10 +92,12 @@ export class ISODataCore {
         return importLanguage(language);
     }
     /**
-     * Get available languages for ISO data
+     * Fetch countries + regions from CDN for a language (call before sync getters)
      */
+    static async ensureLoaded(language = 'en') {
+        return ensureGeoDataLoaded(language);
+    }
     static getAvailableLanguages() {
-        // Return all available languages (not just registered ones)
         return ['en', 'ru', 'de', 'fr', 'es', 'zh', 'hi', 'pt', 'ja', 'ar', 'it', 'he'];
     }
 }