@tagadapay/plugin-sdk 4.0.0 → 4.0.2

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/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/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;

package/dist/v2/core/utils/clickIdResolver.js

@@ -0,0 +1,169 @@
+/**
+ * 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.
+ */
+// -----------------------------------------------------------------------------
+// Configuration — explicit allow-lists
+// -----------------------------------------------------------------------------
+/** 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 const CLICK_ID_URL_PARAMS = Object.freeze([
+    // Postback ad-trackers (most specific first)
+    'cf_click_id', // ClickFlare canonical
+    'cid', // Voluum canonical (also: ClickFlare receiving-side)
+    'rtkclickid', // RedTrack canonical
+    'cmc_tid', // ClickMagick canonical (replaces legacy #S2#)
+    'cmc_id', // ClickMagick legacy
+    'cmcid', // ClickMagick alt
+    'clickid', // Generic affiliate-network token (Binom, RedTrack, Voluum, …)
+    'click_id', // Generic snake_case (ClickFlare, ClickMagick, …)
+    // Ad-platform native click ids
+    'gclid', // Google Ads
+    'gbraid', // Google Ads (iOS app)
+    'wbraid', // Google Ads (web→app)
+    'fbclid', // Meta
+    'msclkid', // Microsoft Ads
+    'ttclid', // TikTok
+    'twclid', // X / Twitter
+    'li_fat_id', // LinkedIn
+    'epik', // Pinterest
+    'dclid', // Display & Video 360
+    'yclid', // Yandex
+    'irclickid', // Impact
+]);
+/** 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 const CLICK_ID_COOKIES = Object.freeze([
+    // ClickFlare
+    'cf_click_id',
+    'cfclid',
+    // RedTrack — `rtkclickid-store` is the canonical first-party cookie
+    // set by RedTrack's Universal Tracking Script.
+    'rtkclickid-store',
+    '_rtkclickid',
+    'rtkclickid',
+    // Voluum
+    '_voluum',
+    '_voluumclickid',
+    // Binom
+    '_binom',
+    '_binomclickid',
+    // ClickMagick
+    '_mck',
+    'cmcid',
+    // Other
+    'skro-click-id', // Skro
+    'click_id', // generic catch-all (last)
+]);
+// -----------------------------------------------------------------------------
+// Pure resolution
+// -----------------------------------------------------------------------------
+function readCookie(name) {
+    if (typeof document === 'undefined' || !document.cookie)
+        return null;
+    const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const m = document.cookie.match(new RegExp('(?:^|; )' + escaped + '=([^;]*)'));
+    if (!m)
+        return null;
+    try {
+        return decodeURIComponent(m[1]);
+    }
+    catch {
+        return m[1];
+    }
+}
+function readUrlParam(search, name) {
+    if (!search)
+        return null;
+    try {
+        return new URLSearchParams(search).get(name);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 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 function resolveClickId() {
+    const all = {};
+    let clickId = null;
+    let source = null;
+    let key = null;
+    const search = typeof window !== 'undefined' ? window.location?.search ?? '' : '';
+    for (const name of CLICK_ID_URL_PARAMS) {
+        const v = readUrlParam(search, name);
+        if (v) {
+            all[`url:${name}`] = v;
+            if (clickId === null) {
+                clickId = v;
+                source = 'url';
+                key = name;
+            }
+        }
+    }
+    for (const name of CLICK_ID_COOKIES) {
+        const v = readCookie(name);
+        if (v) {
+            all[`cookie:${name}`] = v;
+            if (clickId === null) {
+                clickId = v;
+                source = 'cookie';
+                key = name;
+            }
+        }
+    }
+    return { clickId, source, key, all };
+}
+// -----------------------------------------------------------------------------
+// Browser-side publication
+// -----------------------------------------------------------------------------
+/**
+ * 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 function publishTrackingGlobal() {
+    if (typeof window === 'undefined')
+        return null;
+    const resolved = resolveClickId();
+    const tracking = { ...resolved, resolvedAt: Date.now() };
+    window.TagadaPay = { ...(window.TagadaPay ?? {}), tracking };
+    return tracking;
+}

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

@@ -13,3 +13,5 @@ export * from './orderBump';
 export * from './sessionStorage';
 export * from './funnelQueryKeys';
 export * from './configHotReload';
+export * from './metaEventId';
+export * from './clickIdResolver';

package/dist/v2/core/utils/index.js

@@ -14,3 +14,7 @@ export * from './sessionStorage';
 export * from './funnelQueryKeys';
 // Config hot reload for live preview editing
 export * from './configHotReload';
+// Meta CAPI / browser pixel deduplication helper.
+export * from './metaEventId';
+// Click-id resolver for ad-tracker integrations (ClickFlare, Voluum, Binom, …)
+export * from './clickIdResolver';

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

@@ -0,0 +1,14 @@
+/**
+ * Stable event_id helper for Meta CAPI / browser pixel deduplication.
+ *
+ * The browser side (`fbq('track', name, params, { eventID })`) and the server
+ * side (`ServerEvent.setEventId(...)`) must publish the same value to let Meta
+ * dedup. This helper is the single source of truth for the formula, mirrored
+ * on the server in `src/app/services/meta/meta-event-id.ts`. A parity test in
+ * the server package keeps them byte-identical.
+ *
+ * Convention: `${eventName}_${entityId}`. Different event names get different
+ * IDs even when fired for the same entity (e.g. a Purchase + Subscribe pair on
+ * the same order), so each dedups independently.
+ */
+export declare function makeMetaEventId(eventName: string, entityId: string): string;

package/dist/v2/core/utils/metaEventId.js

@@ -0,0 +1,16 @@
+/**
+ * Stable event_id helper for Meta CAPI / browser pixel deduplication.
+ *
+ * The browser side (`fbq('track', name, params, { eventID })`) and the server
+ * side (`ServerEvent.setEventId(...)`) must publish the same value to let Meta
+ * dedup. This helper is the single source of truth for the formula, mirrored
+ * on the server in `src/app/services/meta/meta-event-id.ts`. A parity test in
+ * the server package keeps them byte-identical.
+ *
+ * Convention: `${eventName}_${entityId}`. Different event names get different
+ * IDs even when fired for the same entity (e.g. a Purchase + Subscribe pair on
+ * the same order), so each dedups independently.
+ */
+export function makeMetaEventId(eventName, entityId) {
+    return `${eventName}_${entityId}`;
+}