react-native-fincra-checkout 1.0.0

package/lib/commonjs/components/FincraWebViewCheckout.js

@@ -0,0 +1,300 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FincraWebViewCheckout = FincraWebViewCheckout;
+const react_1 = __importStar(require("react"));
+const react_native_1 = require("react-native");
+const react_native_safe_area_context_1 = require("react-native-safe-area-context");
+const react_native_webview_1 = require("react-native-webview");
+const UrlHandler_1 = require("../utils/UrlHandler");
+/**
+ * A full-screen WebView that loads a backend-generated Fincra checkout URL.
+ *
+ * @example
+ * ```tsx
+ * <FincraWebViewCheckout
+ *   checkoutUrl="https://checkout.fincra.com/pay/..."
+ *   redirectUrl="https://your-backend.com/payment/callback"
+ *   onSuccess={(res) => console.log('Paid:', res.reference)}
+ *   onFailed={(err) => console.log('Failed:', err.message)}
+ *   onCancelled={() => navigation.goBack()}
+ * />
+ * ```
+ */
+function FincraWebViewCheckout({ checkoutUrl, redirectUrl, headerTitle = 'Secure Checkout', headerBackgroundColor = '#FFFFFF', headerTintColor = '#000000', showCancelConfirmationDialog = false, loadingComponent, closeIcon, renderError, onSuccess, onFailed, onCancelled, }) {
+    const [isLoading, setIsLoading] = (0, react_1.useState)(true);
+    const [errorState, setErrorState] = (0, react_1.useState)(null);
+    const [reloadKey, setReloadKey] = (0, react_1.useState)(0);
+    const webViewRef = (0, react_1.useRef)(null);
+    const hasCompleted = (0, react_1.useRef)(false);
+    // Fix #10: Stable ref for handleCancellation — the BackHandler effect
+    // always calls through this ref, never capturing a stale closure.
+    const handleCancellationRef = (0, react_1.useRef)(() => { });
+    // ── Back handler (Android) ──────────────────────────────────────────────────
+    (0, react_1.useEffect)(() => {
+        if (react_native_1.Platform.OS !== 'android')
+            return;
+        const subscription = react_native_1.BackHandler.addEventListener('hardwareBackPress', () => {
+            handleCancellationRef.current();
+            return true; // consume the event
+        });
+        return () => subscription.remove();
+    }, []); // safe: always calls through the ref
+    // ── Completion handler ──────────────────────────────────────────────────────
+    const handleCompletion = (0, react_1.useCallback)((url) => {
+        if (hasCompleted.current)
+            return;
+        hasCompleted.current = true;
+        const params = UrlHandler_1.UrlHandler.extractResponseParams(url);
+        // Safely assume success if status is missing (matches Flutter behaviour)
+        const rawStatus = params['status']?.toLowerCase() ?? 'success';
+        if (UrlHandler_1.UrlHandler.isSuccessStatus(rawStatus)) {
+            const response = UrlHandler_1.UrlHandler.parsePaymentResponse(params);
+            onSuccess?.(response);
+        }
+        else {
+            const err = {
+                code: rawStatus,
+                message: params['message'] ?? 'Payment failed',
+            };
+            onFailed?.(err);
+        }
+    }, [onSuccess, onFailed]);
+    // ── URL interception ────────────────────────────────────────────────────────
+    const onShouldStartLoadWithRequest = (0, react_1.useCallback)((request) => {
+        if (UrlHandler_1.UrlHandler.isCompletionUrl(request.url, redirectUrl)) {
+            handleCompletion(request.url);
+            return false; // prevent navigation — mirrors NavigationDecision.prevent
+        }
+        return true;
+    }, [redirectUrl, handleCompletion]);
+    // ── Cancellation ────────────────────────────────────────────────────────────
+    const handleCancellation = (0, react_1.useCallback)(() => {
+        if (hasCompleted.current)
+            return;
+        if (showCancelConfirmationDialog) {
+            react_native_1.Alert.alert('Cancel Payment?', 'Are you sure you want to cancel this payment?', [
+                { text: 'No', style: 'cancel' },
+                {
+                    text: 'Yes',
+                    style: 'destructive',
+                    onPress: () => {
+                        if (!hasCompleted.current) {
+                            hasCompleted.current = true;
+                            onCancelled?.();
+                        }
+                    },
+                },
+            ]);
+        }
+        else {
+            hasCompleted.current = true;
+            onCancelled?.();
+        }
+    }, [showCancelConfirmationDialog, onCancelled]);
+    // Keep the ref in sync after every render (Fix #10)
+    (0, react_1.useEffect)(() => {
+        handleCancellationRef.current = handleCancellation;
+    });
+    // ── WebView error ───────────────────────────────────────────────────────────
+    const handleError = (0, react_1.useCallback)((syntheticEvent) => {
+        if (hasCompleted.current)
+            return;
+        const { nativeEvent } = syntheticEvent;
+        const err = {
+            code: String(nativeEvent.code ?? 'webview_error'),
+            message: nativeEvent.description ?? 'A WebView error occurred.',
+        };
+        setErrorState(err);
+        setIsLoading(false);
+    }, []);
+    // ── HTTP error (non-completion URLs only) ───────────────────────────────────
+    const handleHttpError = (0, react_1.useCallback)((e) => {
+        if (!UrlHandler_1.UrlHandler.isCompletionUrl(e.nativeEvent.url, redirectUrl)) {
+            handleError(e);
+        }
+    }, [redirectUrl, handleError]);
+    // ── Retry handler ───────────────────────────────────────────────────────────
+    const handleRetry = (0, react_1.useCallback)(() => {
+        setErrorState(null);
+        setIsLoading(true);
+        setReloadKey((key) => key + 1);
+    }, []);
+    // ── Navigation state change (iOS fallback) ──────────────────────────────────
+    // Fix #2: guard setIsLoading — don't flip loading state after completion.
+    const onNavigationStateChange = (0, react_1.useCallback)((navState) => {
+        if (hasCompleted.current)
+            return;
+        if (navState.url &&
+            UrlHandler_1.UrlHandler.isCompletionUrl(navState.url, redirectUrl)) {
+            handleCompletion(navState.url);
+        }
+    }, [redirectUrl, handleCompletion]);
+    // ── Computed status bar style (Fix #11) ─────────────────────────────────────
+    const statusBarStyle = headerTintColor === '#000000' ? 'dark-content' : 'light-content';
+    // ── Render ──────────────────────────────────────────────────────────────────
+    return (react_1.default.createElement(react_native_safe_area_context_1.SafeAreaView, { style: styles.container },
+        react_1.default.createElement(react_native_1.StatusBar, { barStyle: statusBarStyle, backgroundColor: headerBackgroundColor }),
+        react_1.default.createElement(react_native_1.View, { style: [styles.header, { backgroundColor: headerBackgroundColor }] },
+            react_1.default.createElement(react_native_1.TouchableOpacity, { style: styles.closeButton, onPress: handleCancellation, accessibilityLabel: "Close checkout", accessibilityRole: "button", hitSlop: { top: 10, bottom: 10, left: 10, right: 10 } }, closeIcon ?? (react_1.default.createElement(react_native_1.Text, { style: [styles.closeIcon, { color: headerTintColor }] }, "\u2715"))),
+            react_1.default.createElement(react_native_1.Text, { style: [styles.headerTitle, { color: headerTintColor }], numberOfLines: 1 }, headerTitle),
+            react_1.default.createElement(react_native_1.View, { style: styles.closeButton })),
+        react_1.default.createElement(react_native_1.View, { style: styles.webViewContainer },
+            react_1.default.createElement(react_native_webview_1.WebView, { key: reloadKey, ref: webViewRef, source: { uri: checkoutUrl }, style: styles.webView, javaScriptEnabled: true, domStorageEnabled: true, startInLoadingState: false, onLoadStart: () => {
+                    if (!hasCompleted.current)
+                        setIsLoading(true);
+                }, onLoadEnd: () => {
+                    if (!hasCompleted.current)
+                        setIsLoading(false);
+                }, onError: handleError, onHttpError: handleHttpError, onShouldStartLoadWithRequest: onShouldStartLoadWithRequest, onNavigationStateChange: onNavigationStateChange, 
+                // Fix #14: restrict to HTTPS + about:blank — prevents intent:// and
+                // other dangerous scheme navigations in a payment context.
+                originWhitelist: ['https://*', 'about:blank'] }),
+            isLoading && !errorState && (react_1.default.createElement(react_native_1.View, { style: styles.loadingOverlay, pointerEvents: "none" }, loadingComponent ?? (react_1.default.createElement(react_native_1.ActivityIndicator, { size: "large", color: "#0066FF" })))),
+            errorState && (react_1.default.createElement(react_native_1.View, { style: styles.errorOverlay }, renderError ? (renderError(errorState, handleRetry)) : (react_1.default.createElement(react_native_1.View, { style: styles.errorContainer },
+                react_1.default.createElement(react_native_1.Text, { style: styles.errorIcon }, "\u26A0\uFE0F"),
+                react_1.default.createElement(react_native_1.Text, { style: styles.errorTitle }, "Connection Error"),
+                react_1.default.createElement(react_native_1.Text, { style: styles.errorMessage }, errorState.message),
+                react_1.default.createElement(react_native_1.TouchableOpacity, { style: styles.retryButton, onPress: handleRetry, accessibilityRole: "button", accessibilityLabel: "Retry loading checkout" },
+                    react_1.default.createElement(react_native_1.Text, { style: styles.retryButtonText }, "Retry")),
+                react_1.default.createElement(react_native_1.TouchableOpacity, { style: styles.cancelButton, onPress: handleCancellation, accessibilityRole: "button", accessibilityLabel: "Cancel checkout" },
+                    react_1.default.createElement(react_native_1.Text, { style: styles.cancelButtonText }, "Cancel")))))))));
+}
+// ─── Styles ────────────────────────────────────────────────────────────────────
+const styles = react_native_1.StyleSheet.create({
+    container: {
+        flex: 1,
+        backgroundColor: '#FFFFFF',
+    },
+    header: {
+        flexDirection: 'row',
+        alignItems: 'center',
+        justifyContent: 'space-between',
+        height: 56,
+        paddingHorizontal: 12,
+        borderBottomWidth: react_native_1.StyleSheet.hairlineWidth,
+        borderBottomColor: '#E5E7EB',
+        elevation: 2,
+        shadowColor: '#000',
+        shadowOffset: { width: 0, height: 1 },
+        shadowOpacity: 0.08,
+        shadowRadius: 2,
+    },
+    closeButton: {
+        width: 40,
+        height: 40,
+        alignItems: 'center',
+        justifyContent: 'center',
+    },
+    closeIcon: {
+        fontSize: 18,
+        fontWeight: '600',
+    },
+    headerTitle: {
+        flex: 1,
+        textAlign: 'center',
+        fontSize: 16,
+        fontWeight: '600',
+        letterSpacing: 0.2,
+    },
+    webViewContainer: {
+        flex: 1,
+    },
+    webView: {
+        flex: 1,
+        backgroundColor: 'transparent',
+    },
+    loadingOverlay: {
+        ...react_native_1.StyleSheet.absoluteFillObject,
+        alignItems: 'center',
+        justifyContent: 'center',
+        backgroundColor: 'rgba(255,255,255,0.85)',
+    },
+    errorOverlay: {
+        ...react_native_1.StyleSheet.absoluteFillObject,
+        backgroundColor: '#FFFFFF',
+        alignItems: 'center',
+        justifyContent: 'center',
+        padding: 24,
+    },
+    errorContainer: {
+        alignItems: 'center',
+        maxWidth: 320,
+        width: '100%',
+    },
+    errorIcon: {
+        fontSize: 48,
+        marginBottom: 16,
+    },
+    errorTitle: {
+        fontSize: 20,
+        fontWeight: '700',
+        color: '#1F2937',
+        marginBottom: 8,
+        textAlign: 'center',
+    },
+    errorMessage: {
+        fontSize: 14,
+        color: '#6B7280',
+        textAlign: 'center',
+        marginBottom: 24,
+        lineHeight: 20,
+    },
+    retryButton: {
+        backgroundColor: '#0066FF',
+        paddingVertical: 12,
+        paddingHorizontal: 32,
+        borderRadius: 8,
+        width: '100%',
+        alignItems: 'center',
+        marginBottom: 12,
+    },
+    retryButtonText: {
+        color: '#FFFFFF',
+        fontSize: 16,
+        fontWeight: '600',
+    },
+    cancelButton: {
+        paddingVertical: 12,
+        paddingHorizontal: 32,
+        width: '100%',
+        alignItems: 'center',
+    },
+    cancelButtonText: {
+        color: '#6B7280',
+        fontSize: 15,
+        fontWeight: '500',
+    },
+});

package/lib/commonjs/index.js

@@ -0,0 +1,23 @@
+"use strict";
+// ─── Public API ───────────────────────────────────────────────────────────────
+//
+// This is the single entry point for react-native-fincra-checkout.
+// Import only what you need:
+//
+//   import { FincraCheckout, FincraCheckoutHost } from 'react-native-fincra-checkout';
+//   import type { FincraCheckoutResult, WebViewCheckoutConfig } from 'react-native-fincra-checkout';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FeeBearer = exports.FincraCurrency = exports.FincraInlineCheckout = exports.FincraWebViewCheckout = exports.FincraCheckoutHost = exports.FincraCheckout = void 0;
+// ── Imperative API & Host ──────────────────────────────────────────────────────
+var FincraCheckout_1 = require("./checkout/FincraCheckout");
+Object.defineProperty(exports, "FincraCheckout", { enumerable: true, get: function () { return FincraCheckout_1.FincraCheckout; } });
+Object.defineProperty(exports, "FincraCheckoutHost", { enumerable: true, get: function () { return FincraCheckout_1.FincraCheckoutHostRegistrar; } });
+// ── Declarative Components ─────────────────────────────────────────────────────
+var FincraWebViewCheckout_1 = require("./components/FincraWebViewCheckout");
+Object.defineProperty(exports, "FincraWebViewCheckout", { enumerable: true, get: function () { return FincraWebViewCheckout_1.FincraWebViewCheckout; } });
+var FincraInlineCheckout_1 = require("./components/FincraInlineCheckout");
+Object.defineProperty(exports, "FincraInlineCheckout", { enumerable: true, get: function () { return FincraInlineCheckout_1.FincraInlineCheckout; } });
+// ── Primitives & Types ─────────────────────────────────────────────────────────
+var types_1 = require("./types");
+Object.defineProperty(exports, "FincraCurrency", { enumerable: true, get: function () { return types_1.FincraCurrency; } });
+Object.defineProperty(exports, "FeeBearer", { enumerable: true, get: function () { return types_1.FeeBearer; } });

package/lib/commonjs/inline/JsBridge.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FincraBridgeEvent = void 0;
+exports.parseMessage = parseMessage;
+const UrlHandler_1 = require("../utils/UrlHandler");
+// ─── JS Bridge ────────────────────────────────────────────────────────────────
+//
+// Direct TypeScript port of flutter_fincra_checkout/lib/src/inline/javascript_bridge.dart
+// Handles parsing of postMessage events from the Fincra inline JS SDK.
+/** Events that can be posted from the Fincra inline JavaScript SDK. */
+var FincraBridgeEvent;
+(function (FincraBridgeEvent) {
+    /** The Fincra SDK has loaded and is ready — hide the loader. */
+    FincraBridgeEvent["Ready"] = "ready";
+    /** Payment completed successfully. */
+    FincraBridgeEvent["Success"] = "success";
+    /** The user closed the Fincra checkout modal. */
+    FincraBridgeEvent["Closed"] = "closed";
+    /** The Fincra SDK emitted an error (e.g., load failure). */
+    FincraBridgeEvent["Error"] = "error";
+    /** Unrecognized or malformed event — should be ignored. */
+    FincraBridgeEvent["Unknown"] = "unknown";
+})(FincraBridgeEvent || (exports.FincraBridgeEvent = FincraBridgeEvent = {}));
+/**
+ * Parses a raw `postMessage` JSON string into a `FincraBridgeMessage`.
+ *
+ * Expected format from the HTML template:
+ * ```json
+ * { "event": "success", "data": { "reference": "...", ... } }
+ * ```
+ *
+ * On any parse failure, returns an `Unknown` event (mirrors Flutter's catch block).
+ */
+function parseMessage(jsonString) {
+    try {
+        const map = JSON.parse(jsonString);
+        // Guard: JSON.parse('null') returns null, not an object
+        if (map == null || typeof map !== 'object') {
+            return { event: FincraBridgeEvent.Unknown };
+        }
+        const eventStr = typeof map['event'] === 'string' ? map['event'] : null;
+        const event = _parseEvent(eventStr);
+        if (event === FincraBridgeEvent.Success &&
+            map['data'] != null &&
+            typeof map['data'] === 'object' &&
+            !Array.isArray(map['data'])) {
+            // Fix #5: use a spread copy instead of mutating the JSON.parse result
+            const rawData = map['data'];
+            const dataMap = { ...rawData };
+            // Ensure status is always set for the response
+            if (!dataMap['status']) {
+                dataMap['status'] = 'success';
+            }
+            // Coerce all values to strings (mirrors Flutter's `.map((k,v) => MapEntry(k, v.toString()))`)
+            const params = {};
+            for (const [k, v] of Object.entries(dataMap)) {
+                params[k] = String(v);
+            }
+            return { event, data: UrlHandler_1.UrlHandler.parsePaymentResponse(params) };
+        }
+        if (event === FincraBridgeEvent.Error &&
+            map['data'] != null &&
+            typeof map['data'] === 'object' &&
+            !Array.isArray(map['data'])) {
+            const dataMap = map['data'];
+            const errorMessage = typeof dataMap['message'] === 'string'
+                ? dataMap['message']
+                : 'An unknown error occurred';
+            return { event, data: { message: errorMessage } };
+        }
+        return { event };
+    }
+    catch {
+        return { event: FincraBridgeEvent.Unknown };
+    }
+}
+// ── Internal ──────────────────────────────────────────────────────────────────
+function _parseEvent(eventStr) {
+    switch (eventStr) {
+        case 'ready':
+            return FincraBridgeEvent.Ready;
+        case 'success':
+            return FincraBridgeEvent.Success;
+        case 'closed':
+            return FincraBridgeEvent.Closed;
+        case 'error':
+            return FincraBridgeEvent.Error;
+        default:
+            return FincraBridgeEvent.Unknown;
+    }
+}

package/lib/commonjs/inline/htmlGenerator.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateInlineHtml = generateInlineHtml;
+// ─── HTML Generator ────────────────────────────────────────────────────────────
+//
+// Mirrors `_generateHtml()` in flutter_fincra_checkout/lib/src/inline/inline_checkout.dart
+//
+// Security: ALL user-supplied string values are encoded via JSON.stringify(),
+// which escapes special characters and wraps in double-quotes, preventing
+// HTML/JS injection attacks (same approach as the Flutter implementation).
+const FINCRA_CDN_URL = 'https://unpkg.com/@fincra-engineering/checkout@2.2.0/dist/inline.min.js';
+/**
+ * Generates the self-contained HTML page that loads the Fincra inline JS SDK,
+ * initializes it with the provided config, and posts lifecycle events back to
+ * the React Native app via `window.ReactNativeWebView.postMessage(...)`.
+ *
+ * This function is **pure** — given the same config it always returns the same
+ * string, making it safe to memoize with `useMemo`.
+ *
+ * @param config - The inline payment configuration (payment fields only).
+ * @returns A complete HTML string to be loaded into a WebView.
+ */
+function generateInlineHtml(config) {
+    // ── Safe encoding — all string values JSON-encoded to prevent injection ──
+    const key = JSON.stringify(config.publicKey);
+    const amount = config.amount; // numeric — safe to embed directly
+    const currency = JSON.stringify(config.currency.toUpperCase());
+    const name = JSON.stringify(config.customerName);
+    const email = JSON.stringify(config.customerEmail);
+    const phone = JSON.stringify(config.customerPhoneNumber);
+    const feeBearer = JSON.stringify(config.feeBearer);
+    // Optional fields — only emit the JS property if the value is present
+    const referenceLine = config.reference != null
+        ? `reference: ${JSON.stringify(config.reference)},`
+        : '';
+    const paymentMethodsLine = config.paymentMethods != null && config.paymentMethods.length > 0
+        ? `paymentMethods: ${JSON.stringify(config.paymentMethods)},`
+        : '';
+    return `<!DOCTYPE html>
+<html>
+<head>
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
+  <script src="${FINCRA_CDN_URL}"></script>
+  <style>
+    html, body {
+      margin: 0;
+      padding: 0;
+      background-color: transparent;
+      -webkit-overflow-scrolling: touch;
+    }
+  </style>
+</head>
+<body>
+  <script>
+    /**
+     * Posts a structured message to the React Native host.
+     * Uses window.ReactNativeWebView which is injected by react-native-webview.
+     */
+    function postToRN(event, data) {
+      if (window.ReactNativeWebView) {
+        window.ReactNativeWebView.postMessage(JSON.stringify({ event: event, data: data || null }));
+      }
+    }
+
+    /**
+     * Retry loop — waits up to 15 seconds (150 × 100ms) for window.Fincra to load.
+     * Mirrors the identical pattern in the Flutter package's _generateHtml().
+     */
+    function initFincra(attempts) {
+      if (attempts === undefined) attempts = 0;
+
+      if (typeof Fincra === 'undefined') {
+        if (attempts > 150) {
+          postToRN('error', { message: 'Fincra SDK failed to load. Check your internet connection.' });
+          return;
+        }
+        setTimeout(function() { initFincra(attempts + 1); }, 100);
+        return;
+      }
+
+      // SDK is available — signal "ready" so the host hides the loading spinner
+      postToRN('ready', null);
+
+      var options = {
+        key: ${key},
+        amount: ${amount},
+        currency: ${currency},
+        ${referenceLine}
+        ${paymentMethodsLine}
+        feeBearer: ${feeBearer},
+        customer: {
+          name: ${name},
+          email: ${email},
+          phoneNumber: ${phone},
+        },
+        onClose: function() {
+          postToRN('closed', null);
+        },
+        onSuccess: function(data) {
+          postToRN('success', data);
+        },
+      };
+
+      Fincra.initialize(options);
+    }
+
+    window.onload = function() { initFincra(0); };
+  </script>
+</body>
+</html>`;
+}

package/lib/commonjs/types/index.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FeeBearer = exports.FincraCurrency = void 0;
+// ─── Primitives ───────────────────────────────────────────────────────────────
+/**
+ * Currencies supported by the Fincra platform.
+ * Expands the Flutter enum (ngn, kes, ugx, ghs, zar, xaf, xof) with
+ * additional global currencies from the prompt spec.
+ */
+exports.FincraCurrency = {
+    NGN: 'NGN',
+    USD: 'USD',
+    GBP: 'GBP',
+    EUR: 'EUR',
+    GHS: 'GHS',
+    KES: 'KES',
+    ZAR: 'ZAR',
+    UGX: 'UGX',
+    XAF: 'XAF',
+    XOF: 'XOF',
+};
+exports.FeeBearer = {
+    Business: 'business',
+    Customer: 'customer',
+    business: 'business',
+    customer: 'customer',
+};

package/lib/commonjs/utils/UrlHandler.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UrlHandler = void 0;
+// ─── URL Handler ──────────────────────────────────────────────────────────────
+//
+// Direct TypeScript port of flutter_fincra_checkout/lib/src/utils/url_handler.dart
+// Mirrors UrlHandler.isCompletionUrl() and UrlHandler.extractResponseParams()
+/**
+ * Utilities for detecting Fincra payment completion URLs and
+ * extracting normalized response parameters.
+ */
+class UrlHandler {
+    /**
+     * Returns `true` if the given URL signals a Fincra payment completion.
+     *
+     * Logic (mirrors Flutter):
+     * 1. If `expectedRedirectUrl` is provided, check `url.startsWith(expectedRedirectUrl)`.
+     * 2. Fallback: Fincra appends `status` (or `payment_status`) AND `reference` as query params.
+     *
+     * @param url - The URL being navigated to.
+     * @param expectedRedirectUrl - The redirect URL you registered on your backend.
+     */
+    static isCompletionUrl(url, expectedRedirectUrl) {
+        if (!url)
+            return false;
+        if (expectedRedirectUrl && expectedRedirectUrl.length > 0) {
+            return url.startsWith(expectedRedirectUrl);
+        }
+        // Fallback: detect via query parameters
+        try {
+            const params = UrlHandler._parseQueryParams(url);
+            const hasStatus = params.has('status') || params.has('payment_status');
+            const hasReference = params.has('reference');
+            return hasStatus && hasReference;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Extracts all query parameters from the URL as a `Record<string, string>`.
+     *
+     * @param url - The completion URL from Fincra.
+     */
+    static extractResponseParams(url) {
+        try {
+            const params = UrlHandler._parseQueryParams(url);
+            const result = {};
+            params.forEach((value, key) => {
+                result[key] = value;
+            });
+            return result;
+        }
+        catch {
+            return {};
+        }
+    }
+    /**
+     * Builds a normalized `FincraPaymentResponse` from URL query parameters.
+     *
+     * Mirrors `FincraPaymentResponse.fromUrlParams()` in Flutter, including
+     * the reference normalization logic (customerReference → merchantReference → reference).
+     *
+     * @param params - Raw query params extracted from the completion URL.
+     */
+    static parsePaymentResponse(params) {
+        // Fincra sometimes returns the merchant ref under different keys
+        const customRef = params['customerReference'] ?? params['merchantReference'];
+        const internalRef = params['transactionReference'] ?? params['transactionId'];
+        const finalRef = customRef ?? params['reference'] ?? '';
+        const finalTxId = internalRef ?? (customRef != null ? params['reference'] ?? '' : '');
+        return {
+            reference: finalRef,
+            transactionId: finalTxId ?? '',
+            status: params['status'] ?? 'unknown',
+            message: params['message'],
+            rawResponse: params,
+        };
+    }
+    /**
+     * Determines if a status string represents a successful payment.
+     *
+     * @param status - The raw status string from Fincra.
+     */
+    static isSuccessStatus(status) {
+        const normalized = status.toLowerCase().trim();
+        return normalized === 'success' || normalized === 'successful';
+    }
+    // ── Internal ────────────────────────────────────────────────────────────────
+    /**
+     * Parses URL query string into a `URLSearchParams`-like `Map`.
+     * Works in React Native (no DOM `URL` API available).
+     */
+    static _parseQueryParams(url) {
+        const map = new Map();
+        const queryStart = url.indexOf('?');
+        if (queryStart === -1)
+            return map;
+        const queryString = url.slice(queryStart + 1);
+        const pairs = queryString.split('&');
+        for (const pair of pairs) {
+            const eqIdx = pair.indexOf('=');
+            if (eqIdx === -1)
+                continue;
+            const key = decodeURIComponent(pair.slice(0, eqIdx).replace(/\+/g, ' '));
+            const val = decodeURIComponent(pair.slice(eqIdx + 1).replace(/\+/g, ' '));
+            if (key)
+                map.set(key, val);
+        }
+        return map;
+    }
+}
+exports.UrlHandler = UrlHandler;