@tagadapay/plugin-sdk 3.1.25 → 4.0.2

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

@@ -4,6 +4,7 @@
  */
 import type { OrderAddress } from '../types';
 import { ApiClient } from './apiClient';
+import { EventBus } from '../utils/eventBus';
 export type PaymentMethodName = 'card' | 'paypal' | 'klarna' | 'apple_pay' | 'google_pay' | 'link' | 'bridge' | 'whop' | 'zelle' | 'hipay' | 'crypto' | 'convesiopay' | 'oceanpayment' | 'afterpay' | 'ideal' | 'bancontact' | 'giropay' | 'sepa_debit' | (string & {});
 export interface CheckoutLineItem {
     externalProductId?: string | null;
@@ -86,6 +87,43 @@ export interface Upsell {
     triggers: UpsellTrigger[];
     orderBumpOffers: CheckoutOrderBumpOffer[];
 }
+export interface CheckoutOfferLineItem {
+    id: string;
+    productId: string;
+    variantId: string;
+    priceId: string;
+    quantity: number;
+    variant?: {
+        id: string;
+        name?: string | null;
+        imageUrl?: string | null;
+    } | null;
+    product?: {
+        id: string;
+        name?: string | null;
+    } | null;
+    price?: {
+        id: string;
+        currencyOptions?: Record<string, {
+            amount: number;
+        }> | null;
+    } | null;
+}
+/** Tiered checkout offer (offers row, type='checkout_offer'), nested into the
+ * checkout session response alongside store.upsells so the same fetch path
+ * delivers both. The CheckoutOfferSelector chunk consumes these. */
+export interface CheckoutOfferRecord {
+    id: string;
+    type: string;
+    titleTrans: Record<string, string>;
+    summaries?: Array<{
+        currency?: string;
+        totalAmount?: number;
+        totalAdjustedAmount?: number;
+        [key: string]: unknown;
+    }> | null;
+    offerLineItems: CheckoutOfferLineItem[];
+}
 export interface Store {
     id: string;
     accountId: string;
@@ -93,6 +131,7 @@ export interface Store {
     presentmentCurrencies: string[];
     chargeCurrencies: string[];
     upsells: Upsell[];
+    offers?: CheckoutOfferRecord[];
     emailDomains: string[];
     integrations: unknown[];
 }
@@ -302,7 +341,8 @@ export interface CheckoutData {
 }
 export declare class CheckoutResource {
     private apiClient;
-    constructor(apiClient: ApiClient);
+    private bus?;
+    constructor(apiClient: ApiClient, bus?: EventBus | undefined);
     /**
      * Initialize a new checkout session (sync mode)
      * Response time: 2-5 seconds (full processing)
@@ -505,6 +545,10 @@ export declare class CheckoutResource {
         shippingAddress: Partial<OrderAddress>;
         billingAddress?: Partial<OrderAddress>;
         differentBillingAddress?: boolean;
+        cartCustomAttributes?: Array<{
+            name: string;
+            value: string;
+        }>;
     }): Promise<{
         success: boolean;
         errors?: Record<string, {

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

@@ -2,9 +2,11 @@
  * Checkout Resource Client
  * Axios-based API client for checkout endpoints
  */
+import { PROMOTION_APPLIED, PROMOTION_REMOVED } from './promotionEvents';
 export class CheckoutResource {
-    constructor(apiClient) {
+    constructor(apiClient, bus) {
         this.apiClient = apiClient;
+        this.bus = bus;
     }
     /**
      * Initialize a new checkout session (sync mode)
@@ -131,15 +133,23 @@ export class CheckoutResource {
      * Apply promotion code
      */
     async applyPromotionCode(checkoutSessionId, code) {
-        return this.apiClient.post(`/api/v1/checkout-sessions/${checkoutSessionId}/promotions/apply`, {
+        const result = await this.apiClient.post(`/api/v1/checkout-sessions/${checkoutSessionId}/promotions/apply`, {
             code,
         });
+        if (result.success) {
+            void this.bus?.emit(PROMOTION_APPLIED, { checkoutSessionId });
+        }
+        return result;
     }
     /**
      * Remove promotion
      */
     async removePromotion(checkoutSessionId, promotionId) {
-        return this.apiClient.delete(`/api/v1/checkout-sessions/${checkoutSessionId}/promotions/${promotionId}`);
+        const result = await this.apiClient.delete(`/api/v1/checkout-sessions/${checkoutSessionId}/promotions/${promotionId}`);
+        if (result.success) {
+            void this.bus?.emit(PROMOTION_REMOVED, { checkoutSessionId });
+        }
+        return result;
     }
     /**
      * Get applied promotions

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

@@ -405,7 +405,7 @@ export interface SimpleFunnelContext<TCustom = {}> {
      * ✅ Environment context (staging or production)
      * - Determined at session initialization based on entry URL
      * - Ensures all navigation stays in the same environment
-     * - 'staging': Uses funnel.config (alias domains like funnel--store.cdn.tagadapay.com)
+     * - 'staging': Uses funnel.config (alias domains like funnel--store.cdn.tagada.io)
      * - 'production': Uses funnel.productionConfig (custom domains)
      */
     environment?: 'staging' | 'production';

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

@@ -0,0 +1,50 @@
+/**
+ * Geo Resource Client
+ * API client for IP geolocation endpoint
+ */
+import { ApiClient } from './apiClient';
+export interface GeoLocationData {
+    ip_address?: string | null;
+    city?: string | null;
+    region?: string | null;
+    region_iso_code?: string | null;
+    postal_code?: string | null;
+    country?: string | null;
+    country_code?: string | null;
+    country_is_eu?: boolean | null;
+    continent?: string | null;
+    continent_code?: string | null;
+    latitude?: number | null;
+    longitude?: number | null;
+    security?: {
+        is_vpn?: boolean | null;
+    } | null;
+    timezone?: {
+        name?: string | null;
+        abbreviation?: string | null;
+        gmt_offset?: number | null;
+        current_time?: string | null;
+        is_dst?: boolean | null;
+    } | null;
+    currency?: {
+        currency_name?: string | null;
+        currency_code?: string | null;
+    } | null;
+}
+export declare class GeoResource {
+    private apiClient;
+    constructor(apiClient: ApiClient);
+    /**
+     * Get geolocation data from the visitor's IP address
+     */
+    getGeoLocation(): Promise<GeoLocationData>;
+    /**
+     * Get geolocation data for a specific IP address
+     */
+    getGeoLocationByIp(ip: string): Promise<GeoLocationData>;
+    /**
+     * Convenience: get just the country code from IP geolocation
+     * Returns ISO 3166-1 alpha-2 code (e.g. 'US', 'FR') or null
+     */
+    detectCountry(): Promise<string | null>;
+}

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

@@ -0,0 +1,35 @@
+/**
+ * Geo Resource Client
+ * API client for IP geolocation endpoint
+ */
+export class GeoResource {
+    constructor(apiClient) {
+        this.apiClient = apiClient;
+    }
+    /**
+     * Get geolocation data from the visitor's IP address
+     */
+    async getGeoLocation() {
+        return this.apiClient.get('/api/v1/geo');
+    }
+    /**
+     * Get geolocation data for a specific IP address
+     */
+    async getGeoLocationByIp(ip) {
+        return this.apiClient.get(`/api/v1/geo?ip=${encodeURIComponent(ip)}`);
+    }
+    /**
+     * Convenience: get just the country code from IP geolocation
+     * Returns ISO 3166-1 alpha-2 code (e.g. 'US', 'FR') or null
+     */
+    async detectCountry() {
+        try {
+            const data = await this.getGeoLocation();
+            const code = data?.country_code;
+            return code && typeof code === 'string' && code.length === 2 ? code : null;
+        }
+        catch {
+            return null;
+        }
+    }
+}

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

@@ -240,7 +240,7 @@ export declare class OffersResource {
         productId?: string;
         variantId: string;
         quantity: number;
-    }>, returnUrl?: string, mainOrderId?: string): Promise<{
+    }>, returnUrl?: string, mainOrderId?: string, initiatedBy?: 'merchant' | 'customer'): Promise<{
         preview: any;
         checkout: {
             checkoutUrl: string;

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

@@ -68,13 +68,14 @@ export class OffersResource {
      * @param returnUrl - Optional return URL for checkout
      * @param mainOrderId - Optional main order ID (for upsells)
      */
-    async payPreviewedOffer(offerId, currency = '', lineItems, returnUrl, mainOrderId) {
+    async payPreviewedOffer(offerId, currency = '', lineItems, returnUrl, mainOrderId, initiatedBy) {
         console.log('💳 [OffersResource] Calling pay-preview API:', {
             offerId,
             currency,
             lineItems,
             returnUrl,
             mainOrderId,
+            initiatedBy,
             endpoint: `/api/v1/offers/${offerId}/pay-preview`,
         });
         const response = await this.apiClient.post(`/api/v1/offers/${offerId}/pay-preview`, {
@@ -83,6 +84,7 @@ export class OffersResource {
             lineItems,
             returnUrl: returnUrl || (typeof window !== 'undefined' ? window.location.href : ''),
             mainOrderId,
+            ...(initiatedBy ? { initiatedBy } : {}),
         });
         console.log('📥 [OffersResource] Pay-preview API response:', response);
         return response;

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

@@ -10,7 +10,7 @@ export interface Payment {
     subStatus: string;
     requireAction: 'none' | 'redirect' | 'redirect_to_payment' | 'error' | 'radar' | 'stripe_express_checkout';
     requireActionData?: {
-        type: 'redirect' | 'redirect_to_payment' | 'threeds_auth' | 'processor_auth' | 'error' | 'stripe_radar' | 'finix_radar' | 'radar' | 'kesspay_auth' | 'trustflow_auth' | 'mastercard_auth' | 'stripe_express_checkout';
+        type: 'redirect' | 'redirect_to_payment' | 'threeds_auth' | 'processor_auth' | 'error' | 'stripe_radar' | 'finix_radar' | 'radar' | 'kesspay_auth' | 'trustflow_auth' | 'mastercard_auth' | 'stripe_express_checkout' | 'ngenius_3ds';
         url?: string;
         processed: boolean;
         processorId?: string;
@@ -112,6 +112,14 @@ export interface PaymentOptions {
      * Payment method type (e.g., 'klarna', 'afterpay', 'paypal')
      */
     paymentMethod?: string;
+    /**
+     * Shipping rate selected by the customer at checkout. Forwarded to
+     * `processPaymentDirect` so the order is created with the right shipping
+     * even if the session's stored rate hasn't fully round-tripped or got
+     * cleared (race conditions). The backend treats this as authoritative
+     * when present, otherwise falls back to the session's stored rate.
+     */
+    shippingRateId?: string;
     /** @deprecated Use onPaymentSuccess instead - this will be removed in v3 */
     onSuccess?: (response: PaymentResponse) => void;
     /** @deprecated Use onPaymentFailed instead - this will be removed in v3 */
@@ -247,6 +255,7 @@ export declare class PaymentsResource {
         processorId?: string;
         paymentMethod?: string;
         isExpress?: boolean;
+        shippingRateId?: string;
     }): Promise<PaymentResponse>;
     /**
      * Get card payment instruments for customer
@@ -304,4 +313,13 @@ export declare class PaymentsResource {
         status: 'succeeded' | 'failed' | 'pending';
         paymentIntentId: string;
     }): Promise<Payment>;
+    /**
+     * Complete N-Genius payment after WebSDK 3DS flow finishes.
+     * Verifies state from N-Genius server-side and updates the payment record.
+     */
+    ngeniusThreedsComplete(data: {
+        paymentId: string;
+        orderReference: string;
+        paymentReference: string;
+    }): Promise<Payment>;
 }

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

@@ -148,6 +148,7 @@ export class PaymentsResource {
                 ...(options.processorId && { processorId: options.processorId }),
                 ...(options.paymentMethod && { paymentMethod: options.paymentMethod }),
                 ...(options.isExpress && { isExpress: options.isExpress }),
+                ...(options.shippingRateId && { shippingRateId: options.shippingRateId }),
             };
             console.log('[PaymentsResource] Request body being sent:', JSON.stringify(requestBody, null, 2));
             const response = await this.apiClient.post('/api/public/v1/checkout/pay-v2', requestBody);
@@ -206,4 +207,11 @@ export class PaymentsResource {
     async updateThreedsStatus(data) {
         return this.apiClient.post('/api/v1/threeds/status', data);
     }
+    /**
+     * Complete N-Genius payment after WebSDK 3DS flow finishes.
+     * Verifies state from N-Genius server-side and updates the payment record.
+     */
+    async ngeniusThreedsComplete(data) {
+        return this.apiClient.post('/api/v1/payments/ngenius/threeds-complete', data);
+    }
 }

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

@@ -0,0 +1,5 @@
+export declare const PROMOTION_APPLIED = "PROMOTION_APPLIED";
+export declare const PROMOTION_REMOVED = "PROMOTION_REMOVED";
+export interface PromotionEventPayload {
+    checkoutSessionId: string;
+}

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

@@ -0,0 +1,2 @@
+export const PROMOTION_APPLIED = 'PROMOTION_APPLIED';
+export const PROMOTION_REMOVED = 'PROMOTION_REMOVED';

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

@@ -4,6 +4,10 @@
  */
 import { ApiClient } from './apiClient';
 import { Promotion } from './checkout';
+import { EventBus } from '../utils/eventBus';
+import { PROMOTION_APPLIED, PROMOTION_REMOVED, PromotionEventPayload } from './promotionEvents';
+export { PROMOTION_APPLIED, PROMOTION_REMOVED };
+export type { PromotionEventPayload };
 export interface PromotionCodeValidation {
     isValid: boolean;
     code: string;
@@ -18,7 +22,8 @@ export interface PromotionCodeValidation {
 }
 export declare class PromotionsResource {
     private apiClient;
-    constructor(apiClient: ApiClient);
+    private bus?;
+    constructor(apiClient: ApiClient, bus?: EventBus | undefined);
     /**
      * Get applied promotions for a checkout session
      */

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

@@ -2,9 +2,12 @@
  * Promotions Resource Client
  * Axios-based API client for promotion endpoints
  */
+import { PROMOTION_APPLIED, PROMOTION_REMOVED } from './promotionEvents';
+export { PROMOTION_APPLIED, PROMOTION_REMOVED };
 export class PromotionsResource {
-    constructor(apiClient) {
+    constructor(apiClient, bus) {
         this.apiClient = apiClient;
+        this.bus = bus;
     }
     /**
      * Get applied promotions for a checkout session
@@ -19,6 +22,7 @@ export class PromotionsResource {
         try {
             const response = await this.apiClient.post(`/api/v1/checkout-sessions/${checkoutSessionId}/promotions/apply`, { code: code.trim() });
             if (response.success) {
+                void this.bus?.emit(PROMOTION_APPLIED, { checkoutSessionId });
                 return { success: true, promotion: response.promotion };
             }
             else {
@@ -47,6 +51,7 @@ export class PromotionsResource {
         try {
             const response = await this.apiClient.delete(`/api/v1/checkout-sessions/${checkoutSessionId}/promotions/${promotionId}`);
             if (response.success) {
+                void this.bus?.emit(PROMOTION_REMOVED, { checkoutSessionId });
                 return { success: true };
             }
             else {

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

@@ -29,6 +29,11 @@ export interface ShippingRatesPreviewResponse {
         apiKey: string | null;
     };
 }
+export interface SelectPreviewShippingRateResponse {
+    success: boolean;
+    selectedRateId: string | null;
+    rates: ShippingRate[];
+}
 export declare class ShippingRatesResource {
     private apiClient;
     constructor(apiClient: ApiClient);
@@ -48,4 +53,17 @@ export declare class ShippingRatesResource {
      * Useful for showing rates before user enters email
      */
     previewShippingRates(sessionId: string, params: ShippingRatesPreviewParams): Promise<ShippingRatesPreviewResponse>;
+    /**
+     * Preview shipping rates for a country AND persist the auto-selected rate on the session.
+     *
+     * Difference with `previewShippingRates` (which is read-only):
+     *   - the server picks the highlighted (or cheapest) rate for `countryCode`
+     *   - it writes `checkoutSession.shippingRateId` to the DB
+     *   - the next `getCheckout()` will return a summary that includes shipping cost
+     *
+     * Use this from the studio when geolocation (or any client-side hint) determines a country
+     * BEFORE the user submits the full address. Otherwise the wallet sheet (Apple Pay, etc.) will
+     * be opened with a stale total that doesn't include shipping fees.
+     */
+    selectPreviewShippingRate(sessionId: string, params: ShippingRatesPreviewParams): Promise<SelectPreviewShippingRateResponse>;
 }

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

@@ -31,4 +31,22 @@ export class ShippingRatesResource {
         }
         return this.apiClient.get(`/api/v1/checkout-sessions/${sessionId}/shipping-rates/preview?${queryParams.toString()}`);
     }
+    /**
+     * Preview shipping rates for a country AND persist the auto-selected rate on the session.
+     *
+     * Difference with `previewShippingRates` (which is read-only):
+     *   - the server picks the highlighted (or cheapest) rate for `countryCode`
+     *   - it writes `checkoutSession.shippingRateId` to the DB
+     *   - the next `getCheckout()` will return a summary that includes shipping cost
+     *
+     * Use this from the studio when geolocation (or any client-side hint) determines a country
+     * BEFORE the user submits the full address. Otherwise the wallet sheet (Apple Pay, etc.) will
+     * be opened with a stale total that doesn't include shipping fees.
+     */
+    async selectPreviewShippingRate(sessionId, params) {
+        return this.apiClient.post(`/api/v1/checkout-sessions/${sessionId}/shipping-rates/select-preview`, {
+            countryCode: params.countryCode,
+            ...(params.stateCode ? { stateCode: params.stateCode } : {}),
+        });
+    }
 }

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

@@ -0,0 +1,79 @@
+/**
+ * Click-ID resolver — pure, runtime-agnostic utility.
+ *
+ * Many ad-trackers (ClickFlare, Voluum, Binom, RedTrack, ClickMagick, …) all
+ * follow the same pattern: assign a `click_id` on the visitor's first ad-click
+ * on the lander, then expect that id to flow end-to-end (lander → checkout →
+ * thank-you) so they can match a server postback to the original visit.
+ *
+ * This module:
+ *   - Resolves the click id from URL query params (preferred — survives the
+ *     redirect chain) and first-party cookies (fallback — set by the tracker's
+ *     lander script).
+ *   - Publishes the resolved value to `window.TagadaPay.tracking` so merchant-
+ *     authored postback snippets in `stepConfig.scripts` can read it without
+ *     re-implementing URL/cookie scraping.
+ *
+ * No React, no SDK class dependencies — works from React provider, standalone
+ * SDK, the studio builder, the external-tracker bundle, or a raw <script>.
+ *
+ * The lists are intentionally explicit (not regexes) so we never accidentally
+ * promote a random param to a "click id" — they are the exact identifiers
+ * documented by each tracker / ad platform.
+ */
+/** URL query-param names ad trackers / ad platforms use for click ids.
+ *
+ * Order matters — the resolver returns the FIRST matching entry, so put
+ * tracker-specific canonical names BEFORE generic fallbacks like
+ * `click_id` or `clickid`. This is why ClickFlare's `cf_click_id` comes
+ * before `click_id`, and why the per-tracker canonical token (`cid` for
+ * Voluum, `rtkclickid` for RedTrack, `cmc_tid` for ClickMagick) comes
+ * first within its own block.
+ */
+export declare const CLICK_ID_URL_PARAMS: readonly ["cf_click_id", "cid", "rtkclickid", "cmc_tid", "cmc_id", "cmcid", "clickid", "click_id", "gclid", "gbraid", "wbraid", "fbclid", "msclkid", "ttclid", "twclid", "li_fat_id", "epik", "dclid", "yclid", "irclickid"];
+/** Cookie names ad trackers store their click ids under.
+ *
+ * Same ordering rule as URL params: canonical first-party cookies first
+ * (e.g. `rtkclickid-store` for RedTrack), legacy fallbacks last.
+ */
+export declare const CLICK_ID_COOKIES: readonly ["cf_click_id", "cfclid", "rtkclickid-store", "_rtkclickid", "rtkclickid", "_voluum", "_voluumclickid", "_binom", "_binomclickid", "_mck", "cmcid", "skro-click-id", "click_id"];
+export type ClickIdSource = 'url' | 'cookie';
+export interface ResolvedClickId {
+    /** The first matching click id, or null. */
+    clickId: string | null;
+    /** Where it was sourced from. */
+    source: ClickIdSource | null;
+    /** Which key (param name or cookie name) matched. */
+    key: string | null;
+    /** Every click-id-shaped value found, namespaced as `url:foo` / `cookie:bar`. */
+    all: Record<string, string>;
+}
+export interface TagadaTrackingGlobal extends ResolvedClickId {
+    /** ms since epoch when the resolver last ran. */
+    resolvedAt: number;
+}
+declare global {
+    interface Window {
+        TagadaPay?: {
+            tracking?: TagadaTrackingGlobal;
+            [key: string]: unknown;
+        };
+    }
+}
+/**
+ * Resolve the visitor's click id. Pure — no side effects, safe in SSR.
+ *
+ * Resolution order:
+ *   1. URL params (in CLICK_ID_URL_PARAMS order) — most authoritative.
+ *   2. Cookies   (in CLICK_ID_COOKIES order)     — fallback.
+ */
+export declare function resolveClickId(): ResolvedClickId;
+/**
+ * Resolve and merge tracking metadata into `window.TagadaPay.tracking`.
+ *
+ * Idempotent and namespace-safe: we only ever touch the `tracking` key, never
+ * other namespaces (e.g. `order` set by the thank-you page).
+ *
+ * Returns the published value, or `null` when called outside a browser.
+ */
+export declare function publishTrackingGlobal(): TagadaTrackingGlobal | null;