@tagadapay/plugin-sdk 3.1.12 → 3.1.24

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.d.ts

@@ -1,11 +1,11 @@
 import { FunnelClient } from './funnelClient';
 import { ApiClient } from './resources/apiClient';
-import { AuthState, Currency, Customer, Environment, EnvironmentConfig, Locale, Session, Store } from './types';
+import { AuthState, Currency, Customer, DeepPartial, Environment, EnvironmentConfig, Locale, Session, Store } from './types';
 import { EventBus } from './utils/eventBus';
 import { PluginConfig, RawPluginConfig } from './utils/pluginConfig';
 export interface TagadaClientConfig {
     environment?: Environment;
-    customApiConfig?: Partial<EnvironmentConfig>;
+    customApiConfig?: DeepPartial<EnvironmentConfig>;
     debugMode?: boolean;
     localConfig?: string;
     rawPluginConfig?: RawPluginConfig;
@@ -22,6 +22,8 @@ export interface TagadaClientConfig {
          */
         funnel?: boolean | {
             autoRedirect?: boolean;
+            /** Skip automatic funnel initialization (use when caller handles init explicitly) */
+            skipAutoInit?: boolean;
         };
     };
 }

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
@@ -620,9 +620,10 @@ export class TagadaClient {
             customer: response.customer ?? null,
             auth: authState
         });
-        // Auto-initialize funnel if enabled
-        // This runs after we have all required data: auth.session, store, accountId
-        if (this.funnel && sessionData.customerId && response.store?.id) {
+        // Auto-initialize funnel if enabled (skip when caller handles init explicitly)
+        const funnelFeature = this.config.features?.funnel;
+        const skipAutoInit = typeof funnelFeature === 'object' && funnelFeature.skipAutoInit;
+        if (this.funnel && !skipAutoInit && sessionData.customerId && response.store?.id) {
             const accountId = response.store.accountId || this.state.pluginConfig?.accountId || sessionData.accountId || '';
             if (accountId) {
                 // Get funnelId from URL or config

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/errors.d.ts

@@ -0,0 +1,75 @@
+/**
+ * TagadaPay SDK Error Types
+ *
+ * Structured error hierarchy for programmatic error handling.
+ * All SDK errors extend TagadaError, which extends native Error.
+ */
+export declare const TagadaErrorCode: {
+    readonly NETWORK_ERROR: "network_error";
+    readonly API_ERROR: "api_error";
+    readonly AUTH_REQUIRED: "auth_required";
+    readonly TOKEN_EXPIRED: "token_expired";
+    readonly NOT_FOUND: "not_found";
+    readonly VALIDATION_ERROR: "validation_error";
+    readonly CIRCUIT_BREAKER: "circuit_breaker";
+    readonly PAYMENT_FAILED: "payment_failed";
+    readonly CARD_DECLINED: "card_declined";
+    readonly SESSION_EXPIRED: "session_expired";
+    readonly RATE_LIMITED: "rate_limited";
+    readonly TIMEOUT: "timeout";
+    readonly UNKNOWN: "unknown";
+};
+export type TagadaErrorCodeValue = typeof TagadaErrorCode[keyof typeof TagadaErrorCode];
+export interface TagadaErrorOptions {
+    code: TagadaErrorCodeValue | string;
+    statusCode?: number;
+    retryable?: boolean;
+    details?: Record<string, unknown>;
+}
+/**
+ * Base error class for all TagadaPay SDK errors.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await checkout.applyPromotionCode(sessionId, 'SAVE10');
+ * } catch (err) {
+ *   if (err instanceof TagadaError) {
+ *     console.log(err.code);       // 'not_found'
+ *     console.log(err.statusCode);  // 404
+ *     console.log(err.retryable);   // false
+ *   }
+ * }
+ * ```
+ */
+export declare class TagadaError extends Error {
+    readonly code: string;
+    readonly statusCode?: number;
+    readonly retryable: boolean;
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, options: TagadaErrorOptions);
+}
+/** API returned a non-2xx response with an error body. */
+export declare class TagadaApiError extends TagadaError {
+    constructor(message: string, statusCode: number, options?: {
+        code?: string;
+        details?: Record<string, unknown>;
+        retryable?: boolean;
+    });
+}
+/** Network-level failure (no response received). */
+export declare class TagadaNetworkError extends TagadaError {
+    constructor(message?: string);
+}
+/** 401/403 — authentication or authorization failure. */
+export declare class TagadaAuthError extends TagadaError {
+    constructor(message?: string, statusCode?: number);
+}
+/** Input validation failed (client-side or 400 from server). */
+export declare class TagadaValidationError extends TagadaError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/** Circuit breaker tripped — too many requests in a short window. */
+export declare class TagadaCircuitBreakerError extends TagadaError {
+    constructor(message: string);
+}

package/dist/v2/core/errors.js

@@ -0,0 +1,104 @@
+/**
+ * TagadaPay SDK Error Types
+ *
+ * Structured error hierarchy for programmatic error handling.
+ * All SDK errors extend TagadaError, which extends native Error.
+ */
+export const TagadaErrorCode = {
+    NETWORK_ERROR: 'network_error',
+    API_ERROR: 'api_error',
+    AUTH_REQUIRED: 'auth_required',
+    TOKEN_EXPIRED: 'token_expired',
+    NOT_FOUND: 'not_found',
+    VALIDATION_ERROR: 'validation_error',
+    CIRCUIT_BREAKER: 'circuit_breaker',
+    PAYMENT_FAILED: 'payment_failed',
+    CARD_DECLINED: 'card_declined',
+    SESSION_EXPIRED: 'session_expired',
+    RATE_LIMITED: 'rate_limited',
+    TIMEOUT: 'timeout',
+    UNKNOWN: 'unknown',
+};
+/**
+ * Base error class for all TagadaPay SDK errors.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await checkout.applyPromotionCode(sessionId, 'SAVE10');
+ * } catch (err) {
+ *   if (err instanceof TagadaError) {
+ *     console.log(err.code);       // 'not_found'
+ *     console.log(err.statusCode);  // 404
+ *     console.log(err.retryable);   // false
+ *   }
+ * }
+ * ```
+ */
+export class TagadaError extends Error {
+    constructor(message, options) {
+        super(message);
+        this.name = 'TagadaError';
+        this.code = options.code;
+        this.statusCode = options.statusCode;
+        this.retryable = options.retryable ?? false;
+        this.details = options.details;
+        // Maintain proper prototype chain for instanceof checks
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** API returned a non-2xx response with an error body. */
+export class TagadaApiError extends TagadaError {
+    constructor(message, statusCode, options) {
+        super(message, {
+            code: options?.code ?? TagadaErrorCode.API_ERROR,
+            statusCode,
+            retryable: options?.retryable ?? (statusCode >= 500),
+            details: options?.details,
+        });
+        this.name = 'TagadaApiError';
+    }
+}
+/** Network-level failure (no response received). */
+export class TagadaNetworkError extends TagadaError {
+    constructor(message = 'Network request failed') {
+        super(message, {
+            code: TagadaErrorCode.NETWORK_ERROR,
+            retryable: true,
+        });
+        this.name = 'TagadaNetworkError';
+    }
+}
+/** 401/403 — authentication or authorization failure. */
+export class TagadaAuthError extends TagadaError {
+    constructor(message = 'Authentication required', statusCode = 401) {
+        super(message, {
+            code: TagadaErrorCode.AUTH_REQUIRED,
+            statusCode,
+            retryable: false,
+        });
+        this.name = 'TagadaAuthError';
+    }
+}
+/** Input validation failed (client-side or 400 from server). */
+export class TagadaValidationError extends TagadaError {
+    constructor(message, details) {
+        super(message, {
+            code: TagadaErrorCode.VALIDATION_ERROR,
+            statusCode: 400,
+            retryable: false,
+            details,
+        });
+        this.name = 'TagadaValidationError';
+    }
+}
+/** Circuit breaker tripped — too many requests in a short window. */
+export class TagadaCircuitBreakerError extends TagadaError {
+    constructor(message) {
+        super(message, {
+            code: TagadaErrorCode.CIRCUIT_BREAKER,
+            retryable: false,
+        });
+        this.name = 'TagadaCircuitBreakerError';
+    }
+}

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

@@ -65,6 +65,8 @@ export interface GTMTrackingConfig extends BaseTrackingConfig {
         AddToCart: boolean;
         ViewContent: boolean;
     };
+    googleAdsConversionId?: string;
+    googleAdsConversionLabel?: string;
 }
 /**
  * Union of all tracking configs.
@@ -83,14 +85,79 @@ 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;
+    /** 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;
@@ -108,14 +175,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)
@@ -152,13 +225,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;
 /**
@@ -166,11 +248,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;