@tagadapay/plugin-sdk 3.1.11 → 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

@@ -9,7 +9,7 @@ export declare enum TrackingProvider {
     FACEBOOK = "facebook",
     TIKTOK = "tiktok",
     SNAPCHAT = "snapchat",
-    META_CONVERSION = "meta_conversion",
+    PINTEREST = "pinterest",
     GTM = "gtm"
 }
 /**
@@ -65,12 +65,25 @@ export interface GTMTrackingConfig extends BaseTrackingConfig {
         AddToCart: boolean;
         ViewContent: boolean;
     };
+    googleAdsConversionId?: string;
+    googleAdsConversionLabel?: string;
 }
 /**
  * Union of all tracking configs.
  * This mirrors `TrackingFormValues` from the CRM.
  */
 export type PixelConfig = PixelTrackingConfig | SnapchatTrackingConfig | MetaConversionTrackingConfig | GTMTrackingConfig;
+/**
+ * Pixels configuration keyed by provider.
+ * Used in RuntimeStepConfig and getAssignedPixels().
+ */
+export type PixelsConfig = {
+    [TrackingProvider.FACEBOOK]?: PixelTrackingConfig[];
+    [TrackingProvider.TIKTOK]?: PixelTrackingConfig[];
+    [TrackingProvider.SNAPCHAT]?: SnapchatTrackingConfig[];
+    [TrackingProvider.PINTEREST]?: PixelTrackingConfig[];
+    [TrackingProvider.GTM]?: GTMTrackingConfig[];
+};
 /**
  * Runtime step configuration injected from the CRM
  * Contains payment flows, static resources, scripts, and tracking configs
@@ -86,13 +99,7 @@ export interface RuntimeStepConfig {
         content: string;
         position?: 'head-start' | 'head-end' | 'body-start' | 'body-end';
     }>;
-    pixels?: {
-        [TrackingProvider.FACEBOOK]?: PixelTrackingConfig[];
-        [TrackingProvider.TIKTOK]?: PixelTrackingConfig[];
-        [TrackingProvider.SNAPCHAT]?: SnapchatTrackingConfig[];
-        [TrackingProvider.META_CONVERSION]?: MetaConversionTrackingConfig[];
-        [TrackingProvider.GTM]?: GTMTrackingConfig[];
-    };
+    pixels?: PixelsConfig;
 }
 /**
  * Local funnel configuration for development
@@ -165,13 +172,7 @@ export declare function getAssignedScripts(position?: 'head-start' | 'head-end'
  * Get assigned pixel tracking configuration (normalized to arrays)
  * Always returns arrays of PixelConfig for consistent consumption.
  */
-export declare function getAssignedPixels(): {
-    [TrackingProvider.FACEBOOK]?: PixelTrackingConfig[];
-    [TrackingProvider.TIKTOK]?: PixelTrackingConfig[];
-    [TrackingProvider.SNAPCHAT]?: SnapchatTrackingConfig[];
-    [TrackingProvider.META_CONVERSION]?: MetaConversionTrackingConfig[];
-    [TrackingProvider.GTM]?: GTMTrackingConfig[];
-} | undefined;
+export declare function getAssignedPixels(): PixelsConfig | undefined;
 export interface FunnelClientConfig {
     apiClient: ApiClient;
     debugMode?: boolean;

package/dist/v2/core/funnelClient.js

@@ -13,7 +13,7 @@ export var TrackingProvider;
     TrackingProvider["FACEBOOK"] = "facebook";
     TrackingProvider["TIKTOK"] = "tiktok";
     TrackingProvider["SNAPCHAT"] = "snapchat";
-    TrackingProvider["META_CONVERSION"] = "meta_conversion";
+    TrackingProvider["PINTEREST"] = "pinterest";
     TrackingProvider["GTM"] = "gtm";
 })(TrackingProvider || (TrackingProvider = {}));
 /**

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[];