@fat-zebra/sdk 2.0.6-beta.1 → 2.0.6

package/CHANGELOG.md

@@ -1,6 +1,63 @@
-# Fat Zebra SDK
+# Changelog
 
-## Change log
+All notable changes to the Fat Zebra JS SDK will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.0.6] - 2026-05-27
+
+### Added
+- Improved reliability of the ThreeDSecure flow to prevent duplicate processing when a payment is retried or initiated more than once
+
+### Changed
+- React SDK ThreeDSecure flow brought to parity with the core SDK
+
+## [2.0.5] - 2026-05-21
+
+### Fixed
+- Fixed an issue where the device profiling step in the ThreeDSecure flow could trigger card enrollment multiple times if the device profile event fired more than once
+
+## [2.0.4] - 2026-05-20
+
+### Fixed
+- Fixed an issue where triggering the ThreeDSecure flow multiple times (e.g. in a single-page application) could register duplicate event listeners, leading to multiple enrollment attempts
+
+## [2.0.3] - 2026-05-19
+
+### Fixed
+- Fixed an issue in SPA environments where the Cardinal SCA `payments.validated` handler could accumulate across payment flows, causing stale callbacks to fire on subsequent transactions
+
+## [2.0.2] - 2026-05-14
+
+### Changed
+- Default ThreeDSecure challenge window size changed from full-page to 500×600px
+
+### Fixed
+- ThreeDSecure challenge window iframe errors are now correctly reported rather than silently ignored
+
+## [2.0.1] - 2026-05-11
+
+### Fixed
+- Resolved an issue causing delayed rendering of the payment form in `renderPaymentsPage`
+- Payment source is now correctly included in SDK tokenisation request events
+
+### Security
+- Bumped axios from 1.13.5 to 1.16.0 to address known vulnerabilities
+
+## [2.0.0] - 2026-04-02
+
+### Changed
+- **Upgraded 3DS2 authentication flow** — replaced the previous CyberSource Cardinal/Songbird library with a new SDK-native implementation backed directly by Fat Zebra's infrastructure. The new flow supports a configurable challenge window (250×400, 390×400, 500×600, 600×400, or full-page) and handles device fingerprinting internally. No changes are required to existing integrations; the correct flow is selected automatically.
+
+### Security
+- Bumped handlebars from 4.7.8 to 4.7.9 to address known vulnerabilities
+- Bumped axios to 1.15.0
+
+## [1.5.14] - 2026-03-10
+
+### Security
+- Addressed known vulnerabilities in transitive dependencies (axios, minimatch, glob)
 
 ## [1.5.12] - 2025-10-14
 ## Updated
@@ -48,4 +105,3 @@ Support for 3-D Secure 2.x PARes Status: CHALLENGED
 
 ### Security
 - Patched routine package updates
-

package/dist/logging/instrument.js

@@ -1,5 +1,5 @@
 import axios from "axios";
-import { getFlowId, getLoggerUsername, getTransactionReference } from "./logger-context";
+import { getFlowId, getIsReactSdk, getLoggerUsername, getTransactionReference } from "./logger-context";
 let loggerConfig = {};
 export function configureLogger(config) {
     loggerConfig = config;
@@ -40,6 +40,7 @@ export function instrumentFunction(methodName, fn, opts = {}) {
                 username: getLoggerUsername(),
                 reference: getTransactionReference(),
                 flowId: getFlowId(),
+                reactSdk: getIsReactSdk(),
                 className: opts.className,
                 method: methodName,
                 arguments: mappedArgs,

package/dist/logging/logger-context.d.ts

@@ -4,3 +4,5 @@ export declare function getLoggerUsername(): string | undefined;
 export declare function getTransactionReference(): string | undefined;
 export declare function getFlowId(): string | undefined;
 export declare function setFlowId(flowId: string | undefined): void;
+export declare function setIsReactSdk(value: boolean): void;
+export declare function getIsReactSdk(): boolean;

package/dist/logging/logger-context.js

@@ -1,6 +1,7 @@
 let globalLoggerUsername;
 let globalTransactionReference;
 let globalFlowId;
+let globalIsReactSdk = false;
 export function setLoggerUsername(username) {
     globalLoggerUsername = username;
 }
@@ -19,3 +20,9 @@ export function getFlowId() {
 export function setFlowId(flowId) {
     globalFlowId = flowId;
 }
+export function setIsReactSdk(value) {
+    globalIsReactSdk = value;
+}
+export function getIsReactSdk() {
+    return globalIsReactSdk;
+}

package/dist/main.js

@@ -367,6 +367,18 @@ __decorate([
 __decorate([
     logMethod()
 ], FatZebra.prototype, "renderClickToPay", null);
+__decorate([
+    logMethod({
+        mapArgs: (args) => {
+            return [
+                {
+                    data: args[0],
+                    payment_intent: args[1]
+                },
+            ];
+        },
+    })
+], FatZebra.prototype, "reportThreeDSecureFetched", null);
 __decorate([
     logMethod({
         mapArgs: (args) => {

package/dist/react/logging.d.ts

@@ -0,0 +1,13 @@
+import { Environment } from "../shared/env";
+import type { TokenizeCardResponse, PaymentIntent } from "../shared/types";
+type UseFatZebraLogMeta = {
+    environment: Environment;
+    reference: string;
+    username: string;
+    react_sdk: boolean;
+};
+declare const logUseFatZebra: (args_0: UseFatZebraLogMeta) => UseFatZebraLogMeta;
+declare const logReportTokenizeCardResponse: (args_0: TokenizeCardResponse) => void;
+declare const logReportThreeDSecureFetched: (data: boolean, paymentIntent?: PaymentIntent) => void;
+declare const logReportRequestThreedsEnabledTimeout: (paymentIntent?: PaymentIntent) => void;
+export { logUseFatZebra, logReportTokenizeCardResponse, logReportThreeDSecureFetched, logReportRequestThreedsEnabledTimeout, };

package/dist/react/logging.js

@@ -0,0 +1,36 @@
+import { instrumentFunction } from "../logging/instrument";
+import { setLoggerUsername, setTransactionReference, setFlowId, setIsReactSdk, } from "../logging/logger-context";
+import env from "../shared/env";
+const logUseFatZebra = instrumentFunction("useFatZebra", (meta) => meta, {
+    mapArgs: ([meta]) => {
+        setLoggerUsername(meta.username);
+        setTransactionReference(meta.reference);
+        setFlowId(undefined);
+        setIsReactSdk(true);
+        return meta;
+    },
+    className: "useFatZebra",
+    endpoint: (meta) => `${env[meta.environment].payNowUrl}/log_sdk`,
+});
+const logReportTokenizeCardResponse = instrumentFunction("reportTokenizeCardResponse", () => {
+    console.log("Tokenize card response received");
+}, {
+    mapArgs: ([data]) => ({ token: data.token, bin: data.bin }),
+    className: "useMessage",
+});
+const logReportThreeDSecureFetched = instrumentFunction("reportThreeDSecureFetched", (data) => {
+    console.log("three_d_secure fetched", data);
+}, {
+    mapArgs: ([data, paymentIntent]) => ({
+        data,
+        payment_intent: paymentIntent,
+    }),
+    className: "useMessage",
+});
+const logReportRequestThreedsEnabledTimeout = instrumentFunction("reportRequestThreedsEnabledTimeout", () => {
+    console.log("3DS enabled check timed out");
+}, {
+    mapArgs: ([paymentIntent]) => ({ payment_intent: paymentIntent }),
+    className: "useMessage",
+});
+export { logUseFatZebra, logReportTokenizeCardResponse, logReportThreeDSecureFetched, logReportRequestThreedsEnabledTimeout, };

package/dist/react/useFatZebra.js

@@ -5,12 +5,9 @@ import Sca from "../sca";
 import GatewayClient from "../shared/api-gateway-client";
 import { generateVerifyURL } from "./verifyUrl";
 import useMessage from "./useMessage";
-import { configureLogger, instrumentFunction } from "../logging/instrument";
+import { configureLogger } from "../logging/instrument";
 import env from "../shared/env";
-const logUseFatZebra = instrumentFunction("useFatZebra", (meta) => meta, {
-    mapArgs: ([meta]) => meta,
-    endpoint: (meta) => `${env[meta.environment].payNowUrl}/log_sdk`,
-});
+import { logUseFatZebra } from "./logging";
 const useFatZebra = ({ config, handlers, cardToken }) => {
     const { options, accessToken, paymentIntent, username } = config;
     const sca = useMemo(() => {

package/dist/react/useMessage.js

@@ -7,17 +7,34 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import { useEffect, useRef, useState } from 'react';
+import { useEffect, useRef } from 'react';
 import * as FatZebra from "../shared/types";
 import ThreeDSecure from "../three_d_secure";
 import * as bridge from "../shared/bridge-client";
 import env, { Environment } from "../shared/env";
+import { PostMessageClient } from "../shared/post-message-client";
 import { BridgeEvent } from "../shared/types";
+import { setFlowId } from '../logging/logger-context';
+import { LocalStorageAccessTokenKey } from '../shared/constants';
+import { logReportRequestThreedsEnabledTimeout, logReportThreeDSecureFetched, logReportTokenizeCardResponse } from './logging';
 const useMessage = ({ paymentIntent, options, handlers, sca, config }) => {
-    const [threeDSecureEnabled, setThreeDSecureEnabled] = useState(false);
+    const isThreeDSecureEnabled = useRef(false);
     const threeDSecureRef = useRef(null);
-    const successCallback = handlers[FatZebra.PublicEvent.SCA_SUCCESS];
-    const failureCallback = handlers[FatZebra.PublicEvent.SCA_ERROR];
+    const headlessRef = useRef(null);
+    const initAuthClientRef = useRef(null);
+    const listenersClientRef = useRef(null);
+    // defaults to a resolved promise so handleTokenizeCardResponse doesn't hang if initAuth never runs (no config)
+    const authReadyRef = useRef(Promise.resolve());
+    // ThreeDSecure is instantiated once in a [] useEffect, so it would capture stale handler
+    // references if callbacks were passed directly. Instead we keep refs that are updated on
+    // every render, and pass stable wrapper functions so ThreeDSecure always invokes the
+    // latest callbacks without needing to be recreated.
+    const successCallbackRef = useRef(handlers[FatZebra.PublicEvent.SCA_SUCCESS]);
+    const failureCallbackRef = useRef(handlers[FatZebra.PublicEvent.SCA_ERROR]);
+    successCallbackRef.current = handlers[FatZebra.PublicEvent.SCA_SUCCESS];
+    failureCallbackRef.current = handlers[FatZebra.PublicEvent.SCA_ERROR];
+    const successCallback = (e) => { var _a; return (_a = successCallbackRef.current) === null || _a === void 0 ? void 0 : _a.call(successCallbackRef, e); };
+    const failureCallback = (e) => { var _a; return (_a = failureCallbackRef.current) === null || _a === void 0 ? void 0 : _a.call(failureCallbackRef, e); };
     const emit = (event, data) => {
         const handler = handlers[event];
         if (handler) {
@@ -33,28 +50,29 @@ const useMessage = ({ paymentIntent, options, handlers, sca, config }) => {
             });
             return;
         }
-        else {
-            emit(FatZebra.PublicEvent.TOKENIZATION_SUCCESS, {
-                message: "Card tokenization success.",
-                data,
-            });
-        }
-        if (options && options.sca_enabled && threeDSecureRef.current && threeDSecureEnabled) {
-            const iframe = document.querySelector('[name="renderIframe"]');
-            const flowId = crypto.randomUUID();
-            threeDSecureRef.current.run({
-                paymentIntent,
-                cardToken: data.token,
-                merchantUsername: config.username,
-                test: config.environment !== Environment.production,
-                tokenizeOnly: true,
-                iframe: iframe,
-                flowId
-            });
-            return;
-        }
-        if (options && sca && options.sca_enabled) {
-            yield sca.run({ paymentIntent, bin: data.bin, cardToken: data.token });
+        emit(FatZebra.PublicEvent.TOKENIZATION_SUCCESS, {
+            message: "Card tokenization success.",
+            data,
+        });
+        if (options && options.sca_enabled) {
+            yield authReadyRef.current;
+            if (threeDSecureRef.current && isThreeDSecureEnabled.current && config) {
+                const iframe = document.querySelector('[name="renderIframe"]');
+                const flowId = crypto.randomUUID();
+                setFlowId(flowId);
+                threeDSecureRef.current.run({
+                    paymentIntent,
+                    cardToken: data.token,
+                    merchantUsername: config.username,
+                    test: config.environment !== Environment.production,
+                    tokenizeOnly: true,
+                    iframe: iframe,
+                    flowId
+                });
+            }
+            else if (sca) {
+                yield sca.run({ paymentIntent, bin: data.bin, cardToken: data.token });
+            }
         }
     });
     const messageHandler = (event) => __awaiter(void 0, void 0, void 0, function* () {
@@ -64,35 +82,6 @@ const useMessage = ({ paymentIntent, options, handlers, sca, config }) => {
             return;
         if (event.data.subject === FatZebra.BridgeEvent.BIN_LOOKUP)
             return;
-        if (event.data.subject === FatZebra.BridgeEvent.THREE_D_SECURE_ENABLED) {
-            setThreeDSecureEnabled(event.data.data);
-            if (event.data.data) {
-                const { el } = bridge.load2(env[config.environment].bridgeUrl);
-                const headless = el;
-                let onMessage;
-                headless.onload = () => {
-                    const threeDS = new ThreeDSecure({
-                        successCallback,
-                        failureCallback,
-                        bridge: headless,
-                        environment: config.environment,
-                    });
-                    threeDSecureRef.current = threeDS;
-                    const messages = threeDS.messageHandlers(); // { [subject]: (payload) => void }
-                    onMessage = (ev) => {
-                        var _a, _b;
-                        const subject = (_a = ev === null || ev === void 0 ? void 0 : ev.data) === null || _a === void 0 ? void 0 : _a.subject;
-                        const payload = (_b = ev === null || ev === void 0 ? void 0 : ev.data) === null || _b === void 0 ? void 0 : _b.data;
-                        if (!subject)
-                            return;
-                        const handler = messages[subject];
-                        if (handler)
-                            handler(payload);
-                    };
-                    window.addEventListener("message", onMessage);
-                };
-            }
-        }
         if (event.data.subject === FatZebra.BridgeEvent.FORM_VALIDATION_ERROR) {
             emit(FatZebra.PublicEvent.FORM_VALIDATION_ERROR, {
                 errors: event.data.data,
@@ -108,20 +97,92 @@ const useMessage = ({ paymentIntent, options, handlers, sca, config }) => {
             return;
         }
         if (event.data.subject === FatZebra.BridgeEvent.TOKENIZE_CARD_RESPONSE) {
+            logReportTokenizeCardResponse(event.data.data);
             yield handleTokenizeCardResponse(event.data.data);
         }
     });
     useEffect(() => {
-        const message = {
+        if (!config)
+            return;
+        const { el, isExisting } = bridge.load2(env[config.environment].bridgeUrl);
+        headlessRef.current = el;
+        const initAuth = () => {
+            const postMessageClient = new PostMessageClient({
+                channel: 'sca',
+                target: el,
+                environment: config.environment,
+            });
+            initAuthClientRef.current = postMessageClient;
+            let resolved = false;
+            let resolveAuthReady;
+            authReadyRef.current = new Promise((resolve) => { resolveAuthReady = resolve; });
+            postMessageClient.setEventListeners({
+                [BridgeEvent.THREE_D_SECURE_ENABLED]: (data) => {
+                    const enabled = typeof data === 'boolean' ? data : false;
+                    if (!resolved) {
+                        logReportThreeDSecureFetched(enabled, paymentIntent);
+                        resolved = true;
+                        isThreeDSecureEnabled.current = enabled;
+                        resolveAuthReady();
+                        if (enabled) {
+                            const threeDS = new ThreeDSecure({
+                                successCallback,
+                                failureCallback,
+                                bridge: el,
+                                environment: config.environment,
+                            });
+                            threeDSecureRef.current = threeDS;
+                            const listenersClient = new PostMessageClient({
+                                channel: 'sca',
+                                target: el,
+                                environment: config.environment,
+                            });
+                            listenersClient.setEventListeners(threeDS.messageHandlers());
+                            listenersClientRef.current = listenersClient;
+                        }
+                    }
+                },
+            }, { once: true });
+            const message = {
+                channel: 'sca',
+                subject: 'fzi.is-enabled-three-d-secure-req',
+                data: {
+                    merchant: config.username,
+                    access_token: window.localStorage.getItem(LocalStorageAccessTokenKey),
+                },
+            };
+            postMessageClient.send(message);
+            window.setTimeout(() => {
+                if (!resolved) {
+                    logReportRequestThreedsEnabledTimeout(paymentIntent);
+                    resolved = true;
+                    resolveAuthReady();
+                }
+            }, 500);
+        };
+        if (isExisting) {
+            initAuth();
+        }
+        else {
+            el.addEventListener('load', initAuth, { once: true });
+        }
+        const readyMessage = {
             channel: 'sca',
             subject: BridgeEvent.READY,
             data: {}
         };
         const iframe = document.querySelector('[name="renderIframe"]');
-        if (!iframe)
-            return;
-        iframe.onload = () => {
-            iframe.contentWindow.postMessage(message, '*');
+        if (iframe) {
+            iframe.onload = () => {
+                var _a;
+                (_a = iframe.contentWindow) === null || _a === void 0 ? void 0 : _a.postMessage(readyMessage, '*');
+            };
+        }
+        return () => {
+            var _a, _b;
+            el.removeEventListener('load', initAuth);
+            (_a = initAuthClientRef.current) === null || _a === void 0 ? void 0 : _a.removeEventListeners();
+            (_b = listenersClientRef.current) === null || _b === void 0 ? void 0 : _b.removeEventListeners();
         };
     }, []);
     useEffect(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fat-zebra/sdk",
-  "version": "2.0.6-beta.1",
+  "version": "2.0.6",
   "description": "",
   "main": "index.js",
   "scripts": {