@tagadapay/plugin-sdk 3.1.12 → 3.1.24

package/dist/v2/core/pixelMapping.js

@@ -0,0 +1,363 @@
+/**
+ * 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;
+}
+/** Convert top-level monetary fields (shipping, tax, subtotal, total_discount) from minor → major units. */
+function convertMonetaryFieldsToMajor(params) {
+    const currency = params.currency ? String(params.currency) : null;
+    if (!currency)
+        return params;
+    const result = { ...params };
+    for (const field of ['shipping', 'tax', 'subtotal', 'total_discount']) {
+        if (result[field] != null) {
+            result[field] = minorToMajor(Number(result[field]), currency);
+        }
+    }
+    return result;
+}
+/** Convert price fields inside contents[] items from minor → major units. */
+function convertContentsPricesToMajor(params) {
+    if (!params.contents || !Array.isArray(params.contents))
+        return params;
+    const currency = params.currency ? String(params.currency) : null;
+    const result = { ...params };
+    result.contents = params.contents.map((item) => {
+        const itemCurrency = item.currency ? String(item.currency) : currency;
+        if (!itemCurrency)
+            return { ...item };
+        const converted = { ...item };
+        if (converted.price != null)
+            converted.price = minorToMajor(Number(converted.price), itemCurrency);
+        if (converted.original_price != null)
+            converted.original_price = minorToMajor(Number(converted.original_price), itemCurrency);
+        return converted;
+    });
+    return result;
+}
+function baseTransform(params) {
+    let p = ensureCurrencyUppercase(params);
+    p = convertValueToMajor(p);
+    p = convertMonetaryFieldsToMajor(p);
+    p = convertContentsPricesToMajor(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';
+        // Reshape contents to Meta's expected format (prices already converted by baseTransform)
+        params.contents = params.contents.map((item) => ({
+            id: item.content_id,
+            quantity: item.quantity != null ? Number(item.quantity) : undefined,
+            item_price: item.price != null ? Number(item.price) : undefined,
+            content_name: item.content_name,
+            content_category: item.content_category,
+        }));
+    }
+    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);
+    if (params.contents && Array.isArray(params.contents)) {
+        const ids = params.contents
+            .map((i) => i.content_id)
+            .filter(Boolean);
+        // TikTok requires content_id (singular) at the top level for VSA
+        if (!params.content_id && ids.length > 0) {
+            params.content_id = ids.length === 1 ? ids[0] : JSON.stringify(ids);
+        }
+        // Also keep content_ids for backwards compatibility
+        if (!params.content_ids) {
+            params.content_ids = ids;
+        }
+        // Reshape contents to TikTok's expected format (prices already converted by baseTransform)
+        params.contents = params.contents.map((item) => ({
+            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 ? Number(item.price) : undefined,
+            original_price: 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)) {
+        // Reshape to Pinterest line_items format (prices already converted by baseTransform)
+        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)) {
+        // Reshape to GA4 items format (prices already converted by baseTransform)
+        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;
 }

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

@@ -3,6 +3,7 @@
  * Shared between all resource clients
  */
 import axios from 'axios';
+import { TagadaApiError, TagadaAuthError, TagadaNetworkError, TagadaCircuitBreakerError, TagadaError, TagadaErrorCode, } from '../errors';
 export class ApiClient {
     constructor(config) {
         this.currentToken = null;
@@ -61,12 +62,15 @@ export class ApiClient {
             console.error('[SDK] Request error:', error);
             return Promise.reject(error instanceof Error ? error : new Error(String(error)));
         });
-        // Response interceptor for logging
-        this.axios.interceptors.response.use((response) => {
-            // console.log('[SDK] Response status:', response.status);
-            return response;
-        }, (error) => {
+        // Response interceptor — maps Axios errors to structured TagadaError subtypes
+        this.axios.interceptors.response.use((response) => response, (error) => {
             console.error('[SDK] Response error:', error.message);
+            if (error instanceof TagadaError) {
+                return Promise.reject(error);
+            }
+            if (axios.isAxiosError(error)) {
+                return Promise.reject(this.toTagadaError(error));
+            }
             return Promise.reject(error instanceof Error ? error : new Error(String(error)));
         });
     }
@@ -146,10 +150,7 @@ export class ApiClient {
         }
         history.count++;
         if (history.count > this.MAX_REQUESTS) {
-            const error = new Error(`Circuit Breaker: Too many requests to ${key} (${history.count} in ${this.WINDOW_MS}ms)`);
-            // Add a property to identify this as a circuit breaker error
-            error.isCircuitBreaker = true;
-            throw error;
+            throw new TagadaCircuitBreakerError(`Circuit Breaker: Too many requests to ${key} (${history.count} in ${this.WINDOW_MS}ms)`);
         }
     }
     cleanupHistory() {
@@ -160,4 +161,46 @@ export class ApiClient {
             }
         }
     }
+    /** Convert an AxiosError into the appropriate TagadaError subclass. */
+    toTagadaError(error) {
+        const status = error.response?.status;
+        const data = error.response?.data;
+        const serverMessage = data?.message ??
+            data?.error ??
+            error.message;
+        // No response at all → network-level failure
+        if (!error.response) {
+            if (error.code === 'ECONNABORTED') {
+                return new TagadaApiError('Request timed out', 0, {
+                    code: TagadaErrorCode.TIMEOUT,
+                    retryable: true,
+                });
+            }
+            return new TagadaNetworkError(serverMessage);
+        }
+        // Auth failures
+        if (status === 401 || status === 403) {
+            return new TagadaAuthError(serverMessage, status);
+        }
+        // Rate-limited
+        if (status === 429) {
+            return new TagadaApiError(serverMessage, 429, {
+                code: TagadaErrorCode.RATE_LIMITED,
+                retryable: true,
+            });
+        }
+        // Not found
+        if (status === 404) {
+            return new TagadaApiError(serverMessage, 404, {
+                code: TagadaErrorCode.NOT_FOUND,
+                retryable: false,
+            });
+        }
+        // Generic API error
+        return new TagadaApiError(serverMessage, status ?? 0, {
+            code: data?.code ?? TagadaErrorCode.API_ERROR,
+            details: data,
+            retryable: (status ?? 0) >= 500,
+        });
+    }
 }