@tagadapay/plugin-sdk 3.0.3 → 3.0.9

package/dist/v2/core/funnelClient.js

@@ -1,7 +1,62 @@
-import { FunnelResource } from './resources/funnel';
+import { FunnelResource, FunnelActionType } from './resources/funnel';
 import { EventDispatcher } from './utils/eventDispatcher';
 import { getFunnelSessionCookie, setFunnelSessionCookie } from './utils/sessionStorage';
 import { detectEnvironment } from './config/environment';
+import { getSDKParams } from './utils/previewMode';
+/**
+ * Get the funnel ID from the injected HTML
+ * Returns undefined if not available
+ */
+function getAssignedFunnelId() {
+    if (typeof window === 'undefined')
+        return undefined;
+    // Method 1: Window variable (preferred - synchronous, fast)
+    if (window.__TGD_FUNNEL_ID__) {
+        return window.__TGD_FUNNEL_ID__;
+    }
+    // Method 2: Meta tag fallback
+    if (typeof document !== 'undefined') {
+        const meta = document.querySelector('meta[name="x-funnel-id"]');
+        return meta?.getAttribute('content') || undefined;
+    }
+    return undefined;
+}
+/**
+ * Get the assigned A/B test variant ID from the injected HTML
+ * Returns undefined if not in an A/B test
+ */
+function getAssignedFunnelVariant() {
+    if (typeof window === 'undefined')
+        return undefined;
+    // Method 1: Window variable (preferred - synchronous, fast)
+    if (window.__TGD_FUNNEL_VARIANT_ID__) {
+        return window.__TGD_FUNNEL_VARIANT_ID__;
+    }
+    // Method 2: Meta tag fallback
+    if (typeof document !== 'undefined') {
+        const meta = document.querySelector('meta[name="x-funnel-variant-id"]');
+        return meta?.getAttribute('content') || undefined;
+    }
+    return undefined;
+}
+/**
+ * Get the funnel step ID from the injected HTML
+ * Returns undefined if not available
+ */
+function getAssignedFunnelStep() {
+    if (typeof window === 'undefined')
+        return undefined;
+    // Method 1: Window variable (preferred - synchronous, fast)
+    if (window.__TGD_FUNNEL_STEP_ID__) {
+        return window.__TGD_FUNNEL_STEP_ID__;
+    }
+    // Method 2: Meta tag fallback
+    if (typeof document !== 'undefined') {
+        const meta = document.querySelector('meta[name="x-funnel-step-id"]');
+        return meta?.getAttribute('content') || undefined;
+    }
+    return undefined;
+}
 export class FunnelClient {
     constructor(config) {
         this.eventDispatcher = new EventDispatcher();
@@ -60,8 +115,23 @@ export class FunnelClient {
             if (!existingSessionId) {
                 existingSessionId = getFunnelSessionCookie() || null;
             }
+            // 🎯 Read funnel tracking data from injected HTML
+            const injectedFunnelId = getAssignedFunnelId(); // Funnel ID from server
+            const funnelVariantId = getAssignedFunnelVariant(); // A/B test variant ID
+            const funnelStepId = getAssignedFunnelStep(); // Current step ID
+            // 🎯 Get SDK override parameters (draft, funnelTracking, etc.)
+            const sdkParams = getSDKParams();
+            // Prefer injected funnelId over URL/prop funnelId (more reliable)
+            const finalFunnelId = injectedFunnelId || effectiveFunnelId;
             if (this.config.debugMode) {
-                console.log('🚀 [FunnelClient] Auto-initializing...', { existingSessionId, effectiveFunnelId });
+                console.log('🚀 [FunnelClient] Auto-initializing...', {
+                    existingSessionId,
+                    effectiveFunnelId: finalFunnelId,
+                    funnelVariantId, // 🎯 Log variant ID for debugging
+                    funnelStepId, // 🎯 Log step ID for debugging
+                    draft: sdkParams.draft, // 🎯 Log draft mode
+                    funnelTracking: sdkParams.funnelTracking, // 🎯 Log tracking flag
+                });
             }
             // Note: We proceed even without funnelId/sessionId - the backend will create a new anonymous session if needed
             const response = await this.resource.initialize({
@@ -71,9 +141,13 @@ export class FunnelClient {
                     storeId: store.id,
                     accountId: store.accountId,
                 },
-                funnelId: effectiveFunnelId,
+                funnelId: finalFunnelId,
                 existingSessionId: existingSessionId || undefined,
                 currentUrl: typeof window !== 'undefined' ? window.location.href : undefined,
+                funnelVariantId, // 🎯 Pass A/B test variant ID to backend
+                funnelStepId, // 🎯 Pass step ID to backend
+                draft: sdkParams.draft, // 🎯 Pass draft mode explicitly (more robust than URL parsing)
+                funnelTracking: sdkParams.funnelTracking, // 🎯 Pass funnel tracking flag explicitly
             });
             if (response.success && response.context) {
                 const enriched = this.enrichContext(response.context);
@@ -102,6 +176,15 @@ export class FunnelClient {
     async initialize(authSession, store, funnelId, entryStepId) {
         this.updateState({ isLoading: true, error: null });
         try {
+            // 🎯 Read A/B test variant ID and step ID from injected HTML
+            const funnelVariantId = getAssignedFunnelVariant();
+            const funnelStepId = getAssignedFunnelStep();
+            if (this.config.debugMode) {
+                if (funnelVariantId)
+                    console.log('🎯 [FunnelClient] Detected A/B test variant:', funnelVariantId);
+                if (funnelStepId)
+                    console.log('🎯 [FunnelClient] Detected step ID:', funnelStepId);
+            }
             const response = await this.resource.initialize({
                 cmsSession: {
                     customerId: authSession.customerId,
@@ -112,6 +195,8 @@ export class FunnelClient {
                 funnelId: funnelId,
                 entryStepId,
                 currentUrl: typeof window !== 'undefined' ? window.location.href : undefined,
+                funnelVariantId, // 🎯 Pass A/B test variant ID to backend
+                funnelStepId, // 🎯 Pass step ID to backend
             });
             if (response.success && response.context) {
                 const enriched = this.enrichContext(response.context);
@@ -163,6 +248,15 @@ export class FunnelClient {
             throw err;
         }
     }
+    /**
+     * Go to a specific step (direct navigation)
+     */
+    async goToStep(stepId) {
+        return this.navigate({
+            type: FunnelActionType.DIRECT_NAVIGATION,
+            data: { targetStepId: stepId },
+        });
+    }
     /**
      * Refresh session data
      */
@@ -241,11 +335,19 @@ export class FunnelClient {
         const localResources = this.config.pluginConfig?.staticResources || {};
         if (Object.keys(localResources).length === 0)
             return ctx;
+        // 🎯 Check if context already has the same static resources
+        // This prevents creating new objects unnecessarily, which would trigger React re-renders
+        const existingStatic = ctx.static || {};
+        const hasAllResources = Object.keys(localResources).every(key => existingStatic[key] === localResources[key]);
+        // If context already has all static resources with same references, don't recreate
+        if (hasAllResources && Object.keys(existingStatic).length === Object.keys(localResources).length) {
+            return ctx;
+        }
         return {
             ...ctx,
             static: {
                 ...localResources,
-                ...(ctx.static || {})
+                ...existingStatic
             }
         };
     }

package/dist/v2/core/resources/funnel.d.ts

@@ -438,6 +438,28 @@ export interface FunnelInitializeRequest {
      * @example '/checkout', 'https://store.com/payment'
      */
     currentUrl?: string;
+    /**
+     * A/B test variant ID extracted from injected HTML
+     * Used to track which variant the user is seeing in an A/B test
+     * @example 'step_1765015842897_variant_1'
+     */
+    funnelVariantId?: string;
+    /**
+     * Funnel step ID extracted from injected HTML
+     * Used to track which step the user is on
+     * @example 'step_1765015842897'
+     */
+    funnelStepId?: string;
+    /**
+     * 🎯 Draft/preview mode flag (explicit from SDK, more robust than URL parsing)
+     * When true, uses draft/staging data instead of production data
+     */
+    draft?: boolean;
+    /**
+     * 🎯 Funnel tracking enable/disable flag (explicit from SDK, more robust than URL parsing)
+     * When false, disables all funnel tracking events (useful for iframed previews in config editor)
+     */
+    funnelTracking?: boolean;
 }
 export interface FunnelInitializeResponse {
     success: boolean;

package/dist/v2/core/resources/offers.d.ts

@@ -204,16 +204,77 @@ export declare class OffersResource {
     getOfferById(offerId: string): Promise<Offer>;
     /**
      * Get offers for a store
+     * @param storeId - Store ID
+     * @param offerIds - Optional array of offer IDs to filter by
      */
-    getOffers(storeId: string): Promise<Offer[]>;
+    getOffers(storeId: string, offerIds?: string[]): Promise<Offer[]>;
     /**
-     * Get offers by IDs
+     * Get offers by IDs (now uses backend filtering for better performance)
      */
     getOffersByIds(storeId: string, offerIds: string[]): Promise<Offer[]>;
+    /**
+     * Preview an offer with calculated summary (no checkout session creation)
+     * @param offerId - Offer ID
+     * @param currency - Currency code
+     * @param lineItems - Optional line items with variant/quantity selections
+     *   - Use lineItemId for precise updates (same product, different variants)
+     *   - Use productId for simple updates (all items with this product)
+     */
+    previewOffer(offerId: string, currency?: string, lineItems?: Array<{
+        lineItemId?: string;
+        productId?: string;
+        variantId: string;
+        quantity: number;
+    }>): Promise<any>;
+    /**
+     * Preview and pay for an offer with variant selections
+     * Combines preview + checkout session creation in one call
+     * @param offerId - Offer ID
+     * @param currency - Currency code
+     * @param lineItems - Line items with variant/quantity selections
+     * @param returnUrl - Optional return URL for checkout
+     * @param mainOrderId - Optional main order ID (for upsells)
+     */
+    payPreviewedOffer(offerId: string, currency?: string, lineItems?: Array<{
+        lineItemId?: string;
+        productId?: string;
+        variantId: string;
+        quantity: number;
+    }>, returnUrl?: string, mainOrderId?: string): Promise<{
+        preview: any;
+        checkout: {
+            checkoutUrl: string;
+            customerId?: string;
+            checkoutSessionId?: string;
+        };
+    }>;
+    /**
+     * Create checkout session from previewed offer WITHOUT paying
+     * Used for landing pages to prepare checkout before actual payment
+     * @param offerId - Offer ID
+     * @param currency - Currency code
+     * @param lineItems - Line items with variant/quantity selections
+     * @param returnUrl - Optional return URL for checkout
+     * @param mainOrderId - Optional main order ID
+     */
+    toCheckout(offerId: string, currency?: string, lineItems?: Array<{
+        lineItemId?: string;
+        productId?: string;
+        variantId: string;
+        quantity: number;
+    }>, returnUrl?: string, mainOrderId?: string): Promise<{
+        checkoutSessionId?: string;
+        checkoutToken?: string;
+        customerId?: string;
+        checkoutUrl: string;
+    }>;
     /**
      * Initialize checkout session for an offer
+     * @param offerId - Offer ID (required)
+     * @param orderId - Order ID (optional - used for post-purchase upsells)
+     * @param customerId - Customer ID (optional)
      */
-    initCheckoutSession(offerId: string, orderId: string, customerId?: string): Promise<{
+    initCheckoutSession(offerId: string, orderId?: string, customerId?: string): Promise<{
         checkoutSessionId: string;
     }>;
     /**

package/dist/v2/core/resources/offers.js

@@ -2,6 +2,7 @@
  * Offers Resource Client
  * Axios-based API client for offers endpoints
  */
+import { isDraftMode } from '../utils/previewMode';
 export class OffersResource {
     constructor(apiClient) {
         this.apiClient = apiClient;
@@ -15,28 +16,125 @@ export class OffersResource {
     }
     /**
      * Get offers for a store
+     * @param storeId - Store ID
+     * @param offerIds - Optional array of offer IDs to filter by
      */
-    async getOffers(storeId) {
-        const response = await this.apiClient.get(`/api/v1/stores/${storeId}/offers`);
+    async getOffers(storeId, offerIds) {
+        let url = `/api/v1/stores/${storeId}/offers`;
+        // Add ids query parameter if provided (backend filtering for performance)
+        if (offerIds && offerIds.length > 0) {
+            const idsParam = offerIds.map(id => `ids=${encodeURIComponent(id)}`).join('&');
+            url += `?${idsParam}`;
+        }
+        const response = await this.apiClient.get(url);
         return response.offers || [];
     }
     /**
-     * Get offers by IDs
+     * Get offers by IDs (now uses backend filtering for better performance)
      */
     async getOffersByIds(storeId, offerIds) {
-        const allOffers = await this.getOffers(storeId);
-        return allOffers.filter(offer => offerIds.includes(offer.id));
+        // Use backend filtering instead of fetching all and filtering client-side
+        return await this.getOffers(storeId, offerIds);
+    }
+    /**
+     * Preview an offer with calculated summary (no checkout session creation)
+     * @param offerId - Offer ID
+     * @param currency - Currency code
+     * @param lineItems - Optional line items with variant/quantity selections
+     *   - Use lineItemId for precise updates (same product, different variants)
+     *   - Use productId for simple updates (all items with this product)
+     */
+    async previewOffer(offerId, currency = 'USD', lineItems) {
+        console.log('📡 [OffersResource] Calling preview API:', {
+            offerId,
+            currency,
+            lineItems,
+            endpoint: `/api/v1/offers/${offerId}/preview`,
+        });
+        const response = await this.apiClient.post(`/api/v1/offers/${offerId}/preview`, {
+            offerId,
+            currency,
+            lineItems,
+        });
+        console.log('📥 [OffersResource] Preview API response:', response);
+        return response;
+    }
+    /**
+     * Preview and pay for an offer with variant selections
+     * Combines preview + checkout session creation in one call
+     * @param offerId - Offer ID
+     * @param currency - Currency code
+     * @param lineItems - Line items with variant/quantity selections
+     * @param returnUrl - Optional return URL for checkout
+     * @param mainOrderId - Optional main order ID (for upsells)
+     */
+    async payPreviewedOffer(offerId, currency = 'USD', lineItems, returnUrl, mainOrderId) {
+        console.log('💳 [OffersResource] Calling pay-preview API:', {
+            offerId,
+            currency,
+            lineItems,
+            returnUrl,
+            mainOrderId,
+            endpoint: `/api/v1/offers/${offerId}/pay-preview`,
+        });
+        const response = await this.apiClient.post(`/api/v1/offers/${offerId}/pay-preview`, {
+            offerId,
+            currency,
+            lineItems,
+            returnUrl: returnUrl || (typeof window !== 'undefined' ? window.location.href : ''),
+            mainOrderId,
+        });
+        console.log('📥 [OffersResource] Pay-preview API response:', response);
+        return response;
+    }
+    /**
+     * Create checkout session from previewed offer WITHOUT paying
+     * Used for landing pages to prepare checkout before actual payment
+     * @param offerId - Offer ID
+     * @param currency - Currency code
+     * @param lineItems - Line items with variant/quantity selections
+     * @param returnUrl - Optional return URL for checkout
+     * @param mainOrderId - Optional main order ID
+     */
+    async toCheckout(offerId, currency = 'USD', lineItems, returnUrl, mainOrderId) {
+        console.log('🛒 [OffersResource] Calling to-checkout API:', {
+            offerId,
+            currency,
+            lineItems,
+            returnUrl,
+            mainOrderId,
+            endpoint: `/api/v1/offers/${offerId}/to-checkout`,
+        });
+        const response = await this.apiClient.post(`/api/v1/offers/${offerId}/to-checkout`, {
+            offerId,
+            currency,
+            lineItems,
+            returnUrl: returnUrl || (typeof window !== 'undefined' ? window.location.href : ''),
+            mainOrderId,
+        });
+        console.log('📥 [OffersResource] To-checkout API response:', response);
+        return response;
     }
     /**
      * Initialize checkout session for an offer
+     * @param offerId - Offer ID (required)
+     * @param orderId - Order ID (optional - used for post-purchase upsells)
+     * @param customerId - Customer ID (optional)
      */
     async initCheckoutSession(offerId, orderId, customerId) {
-        const response = await this.apiClient.post('/api/v1/checkout/offer/init', {
+        // 🎯 Check draft mode from URL, localStorage, or cookie
+        const draft = isDraftMode();
+        const payload = {
             offerId,
             returnUrl: typeof window !== 'undefined' ? window.location.href : '',
             customerId: customerId || '',
-            orderId,
-        });
+            draft, // 🎯 Pass draft mode
+        };
+        // Only include orderId if provided (used for post-purchase upsells)
+        if (orderId) {
+            payload.orderId = orderId;
+        }
+        const response = await this.apiClient.post('/api/v1/checkout/offer/init', payload);
         return { checkoutSessionId: response.checkoutSessionId };
     }
     /**
@@ -52,9 +150,11 @@ export class OffersResource {
      * Pay with checkout session
      */
     async payWithCheckoutSession(checkoutSessionId, orderId) {
+        // 🎯 Check draft mode from URL, localStorage, or cookie
+        const draft = isDraftMode();
         await this.apiClient.post(`/api/v1/checkout-sessions/${checkoutSessionId}/pay`, {
             checkoutSessionId,
-            draft: false,
+            draft, // 🎯 Use dynamic draft mode instead of hardcoded false
             returnUrl: typeof window !== 'undefined' ? window.location.href : '',
             metadata: {
                 comingFromPostPurchase: true,
@@ -68,9 +168,11 @@ export class OffersResource {
      * Pay for an offer directly
      */
     async payOffer(offerId, orderId) {
+        // 🎯 Check draft mode from URL, localStorage, or cookie
+        const draft = isDraftMode();
         return this.apiClient.post(`/api/v1/offers/${offerId}/pay`, {
             offerId,
-            draft: false,
+            draft, // 🎯 Use dynamic draft mode instead of hardcoded false
             returnUrl: typeof window !== 'undefined' ? window.location.href : '',
             metadata: orderId ? {
                 comingFromPostPurchase: true,

package/dist/v2/core/resources/postPurchases.js

@@ -2,6 +2,7 @@
  * Post Purchases Resource Client
  * Axios-based API client for post-purchase endpoints
  */
+import { isDraftMode } from '../utils/previewMode';
 export class PostPurchasesResource {
     constructor(apiClient) {
         this.apiClient = apiClient;
@@ -85,9 +86,11 @@ export class PostPurchasesResource {
      * Pay with a checkout session for a post-purchase offer
      */
     async payWithCheckoutSession(checkoutSessionId, orderId) {
+        // 🎯 Check draft mode from URL, localStorage, or cookie
+        const draft = isDraftMode();
         await this.apiClient.post(`/api/v1/checkout-sessions/${checkoutSessionId}/pay`, {
             checkoutSessionId,
-            draft: false,
+            draft, // 🎯 Use dynamic draft mode instead of hardcoded false
             returnUrl: typeof window !== 'undefined' ? window.location.href : '',
             metadata: {
                 comingFromPostPurchase: true,

package/dist/v2/core/utils/configHotReload.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Config Hot Reload Utilities
+ *
+ * Enables live config editing without page reload.
+ * Used by the config editor to push updates to preview iframes.
+ */
+export interface ConfigUpdateMessage {
+    type: 'TAGADAPAY_CONFIG_UPDATE';
+    config: Record<string, any>;
+    timestamp?: number;
+}
+/**
+ * Send config update to target window (iframe, popup, etc.)
+ *
+ * @param targetWindow - Window to send update to (e.g., iframe.contentWindow)
+ * @param config - Updated config object
+ * @param targetOrigin - Target origin (default: '*' for same-origin)
+ */
+export declare function sendConfigUpdate(targetWindow: Window, config: Record<string, any>, targetOrigin?: string): void;
+/**
+ * Send config update to all iframes on the page
+ * Useful for config editor with multiple preview panes
+ *
+ * @param config - Updated config object
+ * @param selector - CSS selector for iframes (default: 'iframe')
+ */
+export declare function broadcastConfigUpdate(config: Record<string, any>, selector?: string): void;
+/**
+ * Setup a listener for config updates
+ * Returns cleanup function
+ *
+ * @param callback - Function to call when config is updated
+ */
+export declare function onConfigUpdate(callback: (config: Record<string, any>) => void): () => void;
+/**
+ * Debounce helper for config updates
+ * Prevents too many updates in quick succession
+ */
+export declare function debounceConfigUpdate(fn: (config: Record<string, any>) => void, delay?: number): (config: Record<string, any>) => void;

package/dist/v2/core/utils/configHotReload.js

@@ -0,0 +1,75 @@
+/**
+ * Config Hot Reload Utilities
+ *
+ * Enables live config editing without page reload.
+ * Used by the config editor to push updates to preview iframes.
+ */
+/**
+ * Send config update to target window (iframe, popup, etc.)
+ *
+ * @param targetWindow - Window to send update to (e.g., iframe.contentWindow)
+ * @param config - Updated config object
+ * @param targetOrigin - Target origin (default: '*' for same-origin)
+ */
+export function sendConfigUpdate(targetWindow, config, targetOrigin = '*') {
+    const message = {
+        type: 'TAGADAPAY_CONFIG_UPDATE',
+        config,
+        timestamp: Date.now(),
+    };
+    targetWindow.postMessage(message, targetOrigin);
+}
+/**
+ * Send config update to all iframes on the page
+ * Useful for config editor with multiple preview panes
+ *
+ * @param config - Updated config object
+ * @param selector - CSS selector for iframes (default: 'iframe')
+ */
+export function broadcastConfigUpdate(config, selector = 'iframe') {
+    if (typeof document === 'undefined')
+        return;
+    const iframes = document.querySelectorAll(selector);
+    iframes.forEach((iframe) => {
+        if (iframe.contentWindow) {
+            sendConfigUpdate(iframe.contentWindow, config);
+        }
+    });
+    console.log(`[ConfigHotReload] Broadcasted config update to ${iframes.length} iframe(s)`);
+}
+/**
+ * Setup a listener for config updates
+ * Returns cleanup function
+ *
+ * @param callback - Function to call when config is updated
+ */
+export function onConfigUpdate(callback) {
+    if (typeof window === 'undefined') {
+        return () => { };
+    }
+    const handleMessage = (event) => {
+        if (event.data?.type === 'TAGADAPAY_CONFIG_UPDATE') {
+            callback(event.data.config);
+        }
+    };
+    window.addEventListener('message', handleMessage);
+    return () => {
+        window.removeEventListener('message', handleMessage);
+    };
+}
+/**
+ * Debounce helper for config updates
+ * Prevents too many updates in quick succession
+ */
+export function debounceConfigUpdate(fn, delay = 150) {
+    let timeoutId = null;
+    return (config) => {
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+        timeoutId = setTimeout(() => {
+            fn(config);
+            timeoutId = null;
+        }, delay);
+    };
+}

package/dist/v2/core/utils/eventBus.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Event Bus for handling domain events and coordination
+ */
+export type EventCallback<T = any> = (data: T) => void | Promise<void>;
+export declare class EventBus {
+    private listeners;
+    on<T = any>(event: string, callback: EventCallback<T>): () => void;
+    off<T = any>(event: string, callback: EventCallback<T>): void;
+    emit<T = any>(event: string, data?: T): Promise<void>;
+    clear(): void;
+}

package/dist/v2/core/utils/eventBus.js

@@ -0,0 +1,34 @@
+export class EventBus {
+    constructor() {
+        this.listeners = new Map();
+    }
+    on(event, callback) {
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, new Set());
+        }
+        this.listeners.get(event).add(callback);
+        return () => this.off(event, callback);
+    }
+    off(event, callback) {
+        if (this.listeners.has(event)) {
+            this.listeners.get(event).delete(callback);
+        }
+    }
+    async emit(event, data) {
+        if (this.listeners.has(event)) {
+            const callbacks = Array.from(this.listeners.get(event));
+            await Promise.all(callbacks.map(cb => {
+                try {
+                    return Promise.resolve(cb(data));
+                }
+                catch (e) {
+                    console.error(`[EventBus] Error in listener for event "${event}":`, e);
+                    return Promise.resolve();
+                }
+            }));
+        }
+    }
+    clear() {
+        this.listeners.clear();
+    }
+}

package/dist/v2/core/utils/pluginConfig.d.ts

@@ -15,7 +15,6 @@ export type PluginConfig<TConfig = Record<string, any>> = {
     hidePriceId?: string;
     upsellId?: string;
     googleApiKey?: string;
-    branding?: any;
 } & TConfig;
 export type RawPluginConfig<TConfig = Record<string, any>> = {
     storeId?: string;
@@ -25,7 +24,13 @@ export type RawPluginConfig<TConfig = Record<string, any>> = {
 } & TConfig;
 /**
  * Core plugin config loading function
- * Handles local dev, production, and raw config
+ *
+ * PRIORITY ORDER (highest to lowest):
+ * 1. Injected meta tags (runtime config) - ALWAYS CHECK FIRST
+ * 2. Raw config parameter (programmatic override)
+ * 3. Environment variables (build-time config)
+ * 4. Local dev files (.local.json + config files)
+ * 5. Defaults
  */
 export declare const loadPluginConfig: (configVariant?: string, rawConfig?: RawPluginConfig) => Promise<PluginConfig>;
 /**
@@ -34,9 +39,13 @@ export declare const loadPluginConfig: (configVariant?: string, rawConfig?: RawP
  */
 export declare function loadLocalConfig(configName?: string, defaultConfig?: any): Promise<Record<string, unknown> | null>;
 /**
- * Creates a RawPluginConfig object from provided options
- * @param options - Configuration options including storeId, accountId, basePath, configName, or a direct config object
- * @returns A RawPluginConfig object or undefined if required fields are missing
+ * Creates a RawPluginConfig from environment variables (build-time config)
+ *
+ * This should ONLY be used when:
+ * 1. Running in localhost development
+ * 2. Meta tags are not present (not a deployed plugin)
+ *
+ * @returns A RawPluginConfig object or undefined if not applicable
  */
 export declare function createRawPluginConfig(): Promise<RawPluginConfig | undefined>;
 export declare class PluginConfigUtils {