@tagadapay/plugin-sdk 3.1.12 → 3.1.22

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

@@ -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/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.

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

@@ -7,5 +7,6 @@ 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,6 +11,8 @@ 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/pixelMapping.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Core pixel event mapping, parameter transformation, and event gating.
+ *
+ * This module is framework-agnostic (no React, no DOM) so it can be shared
+ * between the React `PixelTrackingProvider` and the standalone vanilla SDK.
+ *
+ * Official event name references (verified Feb 2026 against vendor docs):
+ *   Meta:      fbq('track', 'Purchase', { value, currency })       — developers.facebook.com/docs/meta-pixel/reference
+ *   TikTok:    ttq.track('Purchase', { value, currency })          — ads.tiktok.com/help/article/standard-events-parameters (Sep 2025)
+ *   Snapchat:  snaptr('track', 'PURCHASE', { price, currency })    — developers.snap.com/api/marketing-api/Conversions-API/Parameters
+ *   Pinterest: pintrk('track', 'checkout', { value, currency })    — help.pinterest.com/en/business/article/add-event-codes
+ *   GTM/GA4:   gtag('event', 'purchase', { value, currency, items })
+ */
+import type { GTMTrackingConfig, PixelConfig, PixelsConfig } from './funnelClient';
+export type StandardPixelEvent = 'PageView' | 'ViewContent' | 'AddToCart' | 'AddToWishlist' | 'Search' | 'InitiateCheckout' | 'AddPaymentInfo' | 'Purchase' | 'Lead' | 'CompleteRegistration' | 'Conversion';
+export type PixelProviderKey = 'facebook' | 'tiktok' | 'snapchat' | 'pinterest' | 'gtm';
+export interface MappedEvent {
+    name: string;
+    params: Record<string, unknown>;
+}
+/**
+ * Returns `true` if the given event is enabled on the pixel config.
+ * If the pixel has no `events` map (e.g. MetaConversionTrackingConfig) we allow all.
+ */
+export declare function isEventEnabled(pixel: PixelConfig, eventName: StandardPixelEvent): boolean;
+/**
+ * Filter an array of pixel configs to only those that are globally enabled
+ * AND have the specific event toggled on.
+ */
+export declare function getEligiblePixels<T extends PixelConfig>(pixels: T[] | undefined, eventName: StandardPixelEvent): T[];
+export declare function mapMetaEvent(eventName: StandardPixelEvent, parameters: Record<string, unknown>): MappedEvent;
+export declare function mapTikTokEvent(eventName: StandardPixelEvent, parameters: Record<string, unknown>): MappedEvent;
+export declare function mapSnapchatEvent(eventName: StandardPixelEvent, parameters: Record<string, unknown>): MappedEvent;
+export declare function mapPinterestEvent(eventName: StandardPixelEvent, parameters: Record<string, unknown>): MappedEvent;
+export declare function mapGTMEvent(eventName: StandardPixelEvent, parameters: Record<string, unknown>): MappedEvent;
+/**
+ * Append Google Ads `send_to` parameter when conversion tracking is configured.
+ */
+export declare function applyGoogleAdsConversion(params: Record<string, unknown>, eventName: StandardPixelEvent, pixel: GTMTrackingConfig): Record<string, unknown>;
+export interface ProviderEvent {
+    provider: PixelProviderKey;
+    mapped: MappedEvent;
+    pixel: PixelConfig;
+}
+/**
+ * Given a PixelsConfig and an event, return per-provider mapped events
+ * for every eligible (enabled + event-toggled-on) pixel.
+ */
+export declare function resolvePixelEvents(pixels: PixelsConfig, eventName: StandardPixelEvent, parameters: Record<string, unknown>): ProviderEvent[];

package/dist/v2/core/pixelMapping.js

@@ -0,0 +1,325 @@
+/**
+ * Core pixel event mapping, parameter transformation, and event gating.
+ *
+ * This module is framework-agnostic (no React, no DOM) so it can be shared
+ * between the React `PixelTrackingProvider` and the standalone vanilla SDK.
+ *
+ * Official event name references (verified Feb 2026 against vendor docs):
+ *   Meta:      fbq('track', 'Purchase', { value, currency })       — developers.facebook.com/docs/meta-pixel/reference
+ *   TikTok:    ttq.track('Purchase', { value, currency })          — ads.tiktok.com/help/article/standard-events-parameters (Sep 2025)
+ *   Snapchat:  snaptr('track', 'PURCHASE', { price, currency })    — developers.snap.com/api/marketing-api/Conversions-API/Parameters
+ *   Pinterest: pintrk('track', 'checkout', { value, currency })    — help.pinterest.com/en/business/article/add-event-codes
+ *   GTM/GA4:   gtag('event', 'purchase', { value, currency, items })
+ */
+// ---------------------------------------------------------------------------
+// Currency conversion helper (inline, zero-dep)
+// ---------------------------------------------------------------------------
+/**
+ * Convert minor units (cents) to major units using ISO 4217 digit counts.
+ * Falls back to ÷100 for unknown currencies.
+ */
+const ZERO_DECIMAL_CURRENCIES = new Set([
+    'BIF', 'CLP', 'DJF', 'GNF', 'ISK', 'JPY', 'KMF', 'KRW',
+    'PYG', 'RWF', 'UGX', 'VND', 'VUV', 'XAF', 'XOF', 'XPF',
+]);
+const THREE_DECIMAL_CURRENCIES = new Set(['BHD', 'IQD', 'JOD', 'KWD', 'LYD', 'OMR', 'TND']);
+function minorToMajor(amount, currency) {
+    const code = currency.toUpperCase();
+    if (ZERO_DECIMAL_CURRENCIES.has(code))
+        return amount;
+    if (THREE_DECIMAL_CURRENCIES.has(code))
+        return amount / 1000;
+    return amount / 100;
+}
+// ---------------------------------------------------------------------------
+// Event gating – respects per-event toggles
+// ---------------------------------------------------------------------------
+/**
+ * Returns `true` if the given event is enabled on the pixel config.
+ * If the pixel has no `events` map (e.g. MetaConversionTrackingConfig) we allow all.
+ */
+export function isEventEnabled(pixel, eventName) {
+    if (!('events' in pixel) || !pixel.events)
+        return true;
+    const events = pixel.events;
+    if (!(eventName in events))
+        return true; // unknown event → allow
+    return events[eventName] === true;
+}
+/**
+ * Filter an array of pixel configs to only those that are globally enabled
+ * AND have the specific event toggled on.
+ */
+export function getEligiblePixels(pixels, eventName) {
+    if (!pixels)
+        return [];
+    return pixels.filter((p) => p.enabled && isEventEnabled(p, eventName));
+}
+// ---------------------------------------------------------------------------
+// Shared parameter transforms
+// ---------------------------------------------------------------------------
+function ensureCurrencyUppercase(params) {
+    if (params.currency && typeof params.currency === 'string') {
+        return { ...params, currency: params.currency.toUpperCase() };
+    }
+    return { ...params };
+}
+function convertValueToMajor(params) {
+    if (params.currency && params.value != null) {
+        const currency = String(params.currency);
+        const major = minorToMajor(Number(params.value), currency);
+        return { ...params, value: major };
+    }
+    return params;
+}
+function baseTransform(params) {
+    let p = ensureCurrencyUppercase(params);
+    p = convertValueToMajor(p);
+    return p;
+}
+// ---------------------------------------------------------------------------
+// Meta / Facebook
+// ---------------------------------------------------------------------------
+const META_EVENT_MAP = {
+    PageView: 'PageView',
+    ViewContent: 'ViewContent',
+    AddToCart: 'AddToCart',
+    AddToWishlist: 'AddToWishlist',
+    Search: 'Search',
+    InitiateCheckout: 'InitiateCheckout',
+    AddPaymentInfo: 'AddPaymentInfo',
+    Purchase: 'Purchase',
+    Lead: 'Lead',
+    CompleteRegistration: 'CompleteRegistration',
+};
+export function mapMetaEvent(eventName, parameters) {
+    const name = META_EVENT_MAP[eventName] ?? eventName;
+    const params = baseTransform(parameters);
+    if (params.contents && Array.isArray(params.contents)) {
+        params.content_ids = params.contents.map((i) => i.content_id).filter(Boolean);
+        params.content_type = params.content_type ?? 'product';
+    }
+    return { name, params };
+}
+// ---------------------------------------------------------------------------
+// TikTok
+// Official: ttq.track('Purchase', { value, currency })
+// Source: ads.tiktok.com/help/article/standard-events-parameters (Sep 2025)
+// Standard events use PascalCase. Note: TikTok has no standard PageView event
+// (page views use ttq.page()), so we pass it as-is for custom tracking.
+// TikTok has no Lead event; SubmitForm is the closest standard equivalent.
+// ---------------------------------------------------------------------------
+const TIKTOK_EVENT_MAP = {
+    PageView: 'Pageview',
+    ViewContent: 'ViewContent',
+    AddToCart: 'AddToCart',
+    AddToWishlist: 'AddToWishlist',
+    Search: 'Search',
+    InitiateCheckout: 'InitiateCheckout',
+    AddPaymentInfo: 'AddPaymentInfo',
+    Purchase: 'Purchase',
+    Lead: 'SubmitForm',
+    CompleteRegistration: 'CompleteRegistration',
+};
+export function mapTikTokEvent(eventName, parameters) {
+    const name = TIKTOK_EVENT_MAP[eventName] ?? eventName;
+    const params = baseTransform(parameters);
+    // Convert additional monetary fields from minor to major units
+    const currency = params.currency ? String(params.currency) : null;
+    if (currency) {
+        for (const field of ['shipping', 'tax', 'subtotal', 'total_discount']) {
+            if (params[field] != null) {
+                params[field] = minorToMajor(Number(params[field]), currency);
+            }
+        }
+    }
+    if (params.contents && Array.isArray(params.contents)) {
+        // Extract content_ids at top level for TikTok product matching
+        if (!params.content_ids) {
+            params.content_ids = params.contents
+                .map((i) => i.content_id)
+                .filter(Boolean);
+        }
+        params.contents = params.contents.map((item) => {
+            const itemCurrency = item.currency ? String(item.currency) : currency;
+            return {
+                content_id: item.content_id,
+                content_name: item.content_name,
+                content_type: item.content_type ?? 'product',
+                content_category: item.content_category,
+                price: item.price != null && itemCurrency ? minorToMajor(Number(item.price), itemCurrency) : item.price != null ? Number(item.price) : undefined,
+                original_price: item.original_price != null && itemCurrency ? minorToMajor(Number(item.original_price), itemCurrency) : item.original_price != null ? Number(item.original_price) : undefined,
+                quantity: item.quantity != null ? Number(item.quantity) : undefined,
+                description: item.description,
+            };
+        });
+    }
+    // Set required fields for InitiateCheckout
+    if (eventName === 'InitiateCheckout') {
+        params.content_type = params.content_type ?? 'product';
+        if (!params.delivery_category) {
+            params.delivery_category = 'home_delivery';
+        }
+    }
+    return { name, params };
+}
+// ---------------------------------------------------------------------------
+// Snapchat
+// Official: snaptr('track', 'PURCHASE', { price, currency })
+// Source: developers.snap.com/api/marketing-api/Conversions-API/Parameters
+// All event names are UPPER_SNAKE_CASE.
+// Note: Snapchat has no LEAD standard event; we pass it as-is (custom event).
+// ---------------------------------------------------------------------------
+const SNAPCHAT_EVENT_MAP = {
+    PageView: 'PAGE_VIEW',
+    ViewContent: 'VIEW_CONTENT',
+    AddToCart: 'ADD_CART',
+    AddToWishlist: 'ADD_TO_WISHLIST',
+    Search: 'SEARCH',
+    InitiateCheckout: 'START_CHECKOUT',
+    AddPaymentInfo: 'ADD_BILLING',
+    Purchase: 'PURCHASE',
+    Lead: 'LEAD',
+    CompleteRegistration: 'SIGN_UP',
+};
+export function mapSnapchatEvent(eventName, parameters) {
+    const name = SNAPCHAT_EVENT_MAP[eventName] ?? eventName;
+    let params = baseTransform(parameters);
+    // Snapchat uses `price` not `value`
+    if ('value' in params) {
+        params = { ...params, price: params.value };
+        delete params.value;
+    }
+    // Snapchat uses `number_items` not `num_items`
+    if ('num_items' in params) {
+        params = { ...params, number_items: params.num_items };
+        delete params.num_items;
+    }
+    if (params.contents && Array.isArray(params.contents)) {
+        params.item_ids = params.contents.map((i) => i.content_id).filter(Boolean);
+    }
+    return { name, params };
+}
+// ---------------------------------------------------------------------------
+// Pinterest
+// Official: pintrk('track', 'checkout', { value, currency, line_items })
+// Event names are all lowercase.
+// ---------------------------------------------------------------------------
+const PINTEREST_EVENT_MAP = {
+    PageView: 'pagevisit',
+    ViewContent: 'viewcontent',
+    AddToCart: 'addtocart',
+    AddToWishlist: 'addtowishlist',
+    Search: 'search',
+    InitiateCheckout: 'initiatecheckout',
+    AddPaymentInfo: 'addpaymentinfo',
+    Purchase: 'checkout',
+    Lead: 'lead',
+    CompleteRegistration: 'signup',
+};
+export function mapPinterestEvent(eventName, parameters) {
+    const name = PINTEREST_EVENT_MAP[eventName] ?? eventName.toLowerCase();
+    const params = baseTransform(parameters);
+    if (params.order_quantity !== undefined) {
+        params.order_quantity = Number(params.order_quantity);
+    }
+    if (params.contents && Array.isArray(params.contents)) {
+        params.line_items = params.contents.map((item) => ({
+            product_id: item.content_id,
+            product_name: item.content_name,
+            product_category: item.content_category,
+            product_price: item.price != null ? Number(item.price) : undefined,
+            product_quantity: item.quantity != null ? Number(item.quantity) : undefined,
+        }));
+    }
+    return { name, params };
+}
+// ---------------------------------------------------------------------------
+// GTM / GA4 / Google Ads
+// Official: gtag('event', 'purchase', { value, currency, items })
+// Event names are snake_case (GA4 convention).
+// ---------------------------------------------------------------------------
+const GTM_EVENT_MAP = {
+    PageView: 'page_view',
+    ViewContent: 'view_item',
+    AddToCart: 'add_to_cart',
+    AddToWishlist: 'add_to_wishlist',
+    Search: 'search',
+    InitiateCheckout: 'begin_checkout',
+    AddPaymentInfo: 'add_payment_info',
+    Purchase: 'purchase',
+    Lead: 'generate_lead',
+    CompleteRegistration: 'sign_up',
+    Conversion: 'conversion',
+};
+export function mapGTMEvent(eventName, parameters) {
+    const name = GTM_EVENT_MAP[eventName] ?? eventName.toLowerCase();
+    const params = baseTransform(parameters);
+    if (params.num_items !== undefined) {
+        params.num_items = Number(params.num_items);
+    }
+    if (params.contents && Array.isArray(params.contents)) {
+        params.items = params.contents.map((item) => ({
+            item_id: item.content_id,
+            item_name: item.content_name,
+            item_category: item.content_category,
+            price: item.price != null ? Number(item.price) : undefined,
+            quantity: item.quantity != null ? Number(item.quantity) : undefined,
+        }));
+        params.contents = params.contents.map((item) => ({
+            id: item.content_id,
+            name: item.content_name,
+            category: item.content_category,
+            price: item.price != null ? Number(item.price) : undefined,
+            quantity: item.quantity != null ? Number(item.quantity) : undefined,
+        }));
+    }
+    return { name, params };
+}
+/**
+ * Append Google Ads `send_to` parameter when conversion tracking is configured.
+ */
+export function applyGoogleAdsConversion(params, eventName, pixel) {
+    if ((eventName === 'Purchase' || eventName === 'Conversion') &&
+        pixel.googleAdsConversionId &&
+        pixel.googleAdsConversionLabel) {
+        return { ...params, send_to: `${pixel.googleAdsConversionId}/${pixel.googleAdsConversionLabel}` };
+    }
+    return params;
+}
+/**
+ * Given a PixelsConfig and an event, return per-provider mapped events
+ * for every eligible (enabled + event-toggled-on) pixel.
+ */
+export function resolvePixelEvents(pixels, eventName, parameters) {
+    const results = [];
+    const fb = getEligiblePixels(pixels.facebook, eventName);
+    if (fb.length > 0) {
+        const mapped = mapMetaEvent(eventName, parameters);
+        fb.forEach((pixel) => results.push({ provider: 'facebook', mapped, pixel }));
+    }
+    const tt = getEligiblePixels(pixels.tiktok, eventName);
+    if (tt.length > 0) {
+        const mapped = mapTikTokEvent(eventName, parameters);
+        tt.forEach((pixel) => results.push({ provider: 'tiktok', mapped, pixel }));
+    }
+    const sc = getEligiblePixels(pixels.snapchat, eventName);
+    if (sc.length > 0) {
+        const mapped = mapSnapchatEvent(eventName, parameters);
+        sc.forEach((pixel) => results.push({ provider: 'snapchat', mapped, pixel }));
+    }
+    const pt = getEligiblePixels(pixels.pinterest, eventName);
+    if (pt.length > 0) {
+        const mapped = mapPinterestEvent(eventName, parameters);
+        pt.forEach((pixel) => results.push({ provider: 'pinterest', mapped, pixel }));
+    }
+    const gtm = getEligiblePixels(pixels.gtm, eventName);
+    if (gtm.length > 0) {
+        const mapped = mapGTMEvent(eventName, parameters);
+        gtm.forEach((pixel) => {
+            const finalParams = applyGoogleAdsConversion(mapped.params, eventName, pixel);
+            results.push({ provider: 'gtm', mapped: { name: mapped.name, params: finalParams }, pixel });
+        });
+    }
+    return results;
+}

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

@@ -35,4 +35,6 @@ export declare class ApiClient {
     updateConfig(config: Partial<ApiClientConfig>): void;
     private checkRequestLimit;
     private cleanupHistory;
+    /** Convert an AxiosError into the appropriate TagadaError subclass. */
+    private toTagadaError;
 }