react-native-fincra-checkout 1.0.0

package/src/components/FincraWebViewCheckout.tsx

@@ -0,0 +1,415 @@
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import {
+  ActivityIndicator,
+  Alert,
+  BackHandler,
+  Platform,
+  StatusBar,
+  StyleSheet,
+  Text,
+  TouchableOpacity,
+  View,
+} from 'react-native';
+import { SafeAreaView } from 'react-native-safe-area-context';
+import type {
+  WebViewNavigation,
+  WebViewErrorEvent,
+  WebViewHttpErrorEvent,
+  ShouldStartLoadRequest,
+} from 'react-native-webview/lib/WebViewTypes';
+import { WebView } from 'react-native-webview';
+import type { WebViewCheckoutConfig, FincraPaymentError } from '../types';
+import { UrlHandler } from '../utils/UrlHandler';
+
+// ─── FincraWebViewCheckout ────────────────────────────────────────────────────
+//
+// Declarative component for the WebView-based checkout flow.
+// Mirrors CheckoutWebView widget in checkout_webview.dart
+//
+// Renders a backend-generated Fincra checkout URL inside react-native-webview,
+// intercepts navigation to the redirect URL (or status+reference query params),
+// and fires the appropriate callback.
+
+export type FincraWebViewCheckoutProps = WebViewCheckoutConfig;
+
+/**
+ * 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()}
+ * />
+ * ```
+ */
+export function FincraWebViewCheckout({
+  checkoutUrl,
+  redirectUrl,
+  headerTitle = 'Secure Checkout',
+  headerBackgroundColor = '#FFFFFF',
+  headerTintColor = '#000000',
+  showCancelConfirmationDialog = false,
+  loadingComponent,
+  closeIcon,
+  renderError,
+  onSuccess,
+  onFailed,
+  onCancelled,
+}: FincraWebViewCheckoutProps) {
+  const [isLoading, setIsLoading] = useState(true);
+  const [errorState, setErrorState] = useState<FincraPaymentError | null>(null);
+  const [reloadKey, setReloadKey] = useState(0);
+  const webViewRef = useRef<WebView<object> | null>(null);
+  const hasCompleted = useRef(false);
+
+  // Fix #10: Stable ref for handleCancellation — the BackHandler effect
+  // always calls through this ref, never capturing a stale closure.
+  const handleCancellationRef = useRef<() => void>(() => {});
+
+  // ── Back handler (Android) ──────────────────────────────────────────────────
+  useEffect(() => {
+    if (Platform.OS !== 'android') return;
+    const subscription = BackHandler.addEventListener(
+      'hardwareBackPress',
+      () => {
+        handleCancellationRef.current();
+        return true; // consume the event
+      }
+    );
+    return () => subscription.remove();
+  }, []); // safe: always calls through the ref
+
+  // ── Completion handler ──────────────────────────────────────────────────────
+  const handleCompletion = useCallback(
+    (url: string) => {
+      if (hasCompleted.current) return;
+      hasCompleted.current = true;
+
+      const params = UrlHandler.extractResponseParams(url);
+      // Safely assume success if status is missing (matches Flutter behaviour)
+      const rawStatus = params['status']?.toLowerCase() ?? 'success';
+
+      if (UrlHandler.isSuccessStatus(rawStatus)) {
+        const response = UrlHandler.parsePaymentResponse(params);
+        onSuccess?.(response);
+      } else {
+        const err: FincraPaymentError = {
+          code: rawStatus,
+          message: params['message'] ?? 'Payment failed',
+        };
+        onFailed?.(err);
+      }
+    },
+    [onSuccess, onFailed]
+  );
+
+  // ── URL interception ────────────────────────────────────────────────────────
+  const onShouldStartLoadWithRequest = useCallback(
+    (request: ShouldStartLoadRequest): boolean => {
+      if (UrlHandler.isCompletionUrl(request.url, redirectUrl)) {
+        handleCompletion(request.url);
+        return false; // prevent navigation — mirrors NavigationDecision.prevent
+      }
+      return true;
+    },
+    [redirectUrl, handleCompletion]
+  );
+
+  // ── Cancellation ────────────────────────────────────────────────────────────
+  const handleCancellation = useCallback(() => {
+    if (hasCompleted.current) return;
+
+    if (showCancelConfirmationDialog) {
+      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)
+  useEffect(() => {
+    handleCancellationRef.current = handleCancellation;
+  });
+
+  // ── WebView error ───────────────────────────────────────────────────────────
+  const handleError = useCallback(
+    (syntheticEvent: WebViewErrorEvent): void => {
+      if (hasCompleted.current) return;
+      const { nativeEvent } = syntheticEvent;
+      const err: FincraPaymentError = {
+        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 = useCallback(
+    (e: WebViewHttpErrorEvent): void => {
+      if (!UrlHandler.isCompletionUrl(e.nativeEvent.url, redirectUrl)) {
+        handleError(e as unknown as WebViewErrorEvent);
+      }
+    },
+    [redirectUrl, handleError]
+  );
+
+  // ── Retry handler ───────────────────────────────────────────────────────────
+  const handleRetry = 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 = useCallback(
+    (navState: WebViewNavigation) => {
+      if (hasCompleted.current) return;
+      if (
+        navState.url &&
+        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 (
+    <SafeAreaView style={styles.container}>
+      <StatusBar
+        barStyle={statusBarStyle}
+        backgroundColor={headerBackgroundColor}
+      />
+      {/* ── Header bar ── */}
+      <View
+        style={[styles.header, { backgroundColor: headerBackgroundColor }]}
+      >
+        <TouchableOpacity
+          style={styles.closeButton}
+          onPress={handleCancellation}
+          accessibilityLabel="Close checkout"
+          accessibilityRole="button"
+          hitSlop={{ top: 10, bottom: 10, left: 10, right: 10 }}
+        >
+          {closeIcon ?? (
+            <Text style={[styles.closeIcon, { color: headerTintColor }]}>
+              ✕
+            </Text>
+          )}
+        </TouchableOpacity>
+        <Text
+          style={[styles.headerTitle, { color: headerTintColor }]}
+          numberOfLines={1}
+        >
+          {headerTitle}
+        </Text>
+        {/* Spacer to centre the title */}
+        <View style={styles.closeButton} />
+      </View>
+
+      {/* ── WebView ── */}
+      <View style={styles.webViewContainer}>
+        <WebView
+          key={reloadKey}
+          ref={webViewRef}
+          source={{ uri: checkoutUrl }}
+          style={styles.webView}
+          javaScriptEnabled
+          domStorageEnabled
+          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']}
+        />
+
+        {/* ── Loading overlay ── */}
+        {isLoading && !errorState && (
+          <View style={styles.loadingOverlay} pointerEvents="none">
+            {loadingComponent ?? (
+              <ActivityIndicator size="large" color="#0066FF" />
+            )}
+          </View>
+        )}
+
+        {/* ── Error Recovery overlay ── */}
+        {errorState && (
+          <View style={styles.errorOverlay}>
+            {renderError ? (
+              renderError(errorState, handleRetry)
+            ) : (
+              <View style={styles.errorContainer}>
+                <Text style={styles.errorIcon}>⚠️</Text>
+                <Text style={styles.errorTitle}>Connection Error</Text>
+                <Text style={styles.errorMessage}>{errorState.message}</Text>
+                <TouchableOpacity
+                  style={styles.retryButton}
+                  onPress={handleRetry}
+                  accessibilityRole="button"
+                  accessibilityLabel="Retry loading checkout"
+                >
+                  <Text style={styles.retryButtonText}>Retry</Text>
+                </TouchableOpacity>
+                <TouchableOpacity
+                  style={styles.cancelButton}
+                  onPress={handleCancellation}
+                  accessibilityRole="button"
+                  accessibilityLabel="Cancel checkout"
+                >
+                  <Text style={styles.cancelButtonText}>Cancel</Text>
+                </TouchableOpacity>
+              </View>
+            )}
+          </View>
+        )}
+      </View>
+    </SafeAreaView>
+  );
+}
+
+// ─── Styles ────────────────────────────────────────────────────────────────────
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    backgroundColor: '#FFFFFF',
+  },
+  header: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    height: 56,
+    paddingHorizontal: 12,
+    borderBottomWidth: 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: {
+    ...StyleSheet.absoluteFillObject,
+    alignItems: 'center',
+    justifyContent: 'center',
+    backgroundColor: 'rgba(255,255,255,0.85)',
+  },
+  errorOverlay: {
+    ...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/src/index.ts

@@ -0,0 +1,31 @@
+// ─── 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';
+
+// ── Imperative API & Host ──────────────────────────────────────────────────────
+export {
+  FincraCheckout,
+  FincraCheckoutHostRegistrar as FincraCheckoutHost,
+} from './checkout/FincraCheckout';
+
+// ── Declarative Components ─────────────────────────────────────────────────────
+export { FincraWebViewCheckout } from './components/FincraWebViewCheckout';
+export { FincraInlineCheckout } from './components/FincraInlineCheckout';
+
+// ── Primitives & Types ─────────────────────────────────────────────────────────
+export { FincraCurrency, FeeBearer } from './types';
+export type {
+  // Data models
+  FincraPaymentResponse,
+  FincraPaymentError,
+  // Result discriminated union
+  FincraCheckoutResult,
+  // Component props / config
+  BaseCheckoutProps,
+  WebViewCheckoutConfig,
+  InlineCheckoutConfig,
+} from './types';

package/src/inline/JsBridge.ts

@@ -0,0 +1,108 @@
+import type { FincraPaymentResponse } from '../types';
+import { UrlHandler } from '../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. */
+export enum FincraBridgeEvent {
+  /** The Fincra SDK has loaded and is ready — hide the loader. */
+  Ready = 'ready',
+  /** Payment completed successfully. */
+  Success = 'success',
+  /** The user closed the Fincra checkout modal. */
+  Closed = 'closed',
+  /** The Fincra SDK emitted an error (e.g., load failure). */
+  Error = 'error',
+  /** Unrecognized or malformed event — should be ignored. */
+  Unknown = 'unknown',
+}
+
+/** A parsed message posted by the Fincra JS SDK via `postMessage`. */
+export interface FincraBridgeMessage {
+  event: FincraBridgeEvent;
+  /** Populated only for `success` and `error` events. */
+  data?: FincraPaymentResponse | { message: string };
+}
+
+/**
+ * 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).
+ */
+export function parseMessage(jsonString: string): FincraBridgeMessage {
+  try {
+    const map = JSON.parse(jsonString) as Record<string, unknown>;
+    // 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'] as Record<string, unknown>;
+      const dataMap: Record<string, unknown> = { ...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: Record<string, string> = {};
+      for (const [k, v] of Object.entries(dataMap)) {
+        params[k] = String(v);
+      }
+      return { event, data: UrlHandler.parsePaymentResponse(params) };
+    }
+
+    if (
+      event === FincraBridgeEvent.Error &&
+      map['data'] != null &&
+      typeof map['data'] === 'object' &&
+      !Array.isArray(map['data'])
+    ) {
+      const dataMap = map['data'] as Record<string, unknown>;
+      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: string | null): FincraBridgeEvent {
+  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/src/inline/htmlGenerator.ts

@@ -0,0 +1,138 @@
+import type { InlineCheckoutConfig } from '../types';
+
+// ─── 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';
+
+/**
+ * Narrowed config type: only the payment fields needed to generate the HTML.
+ * Deliberately excludes UI props (`onSuccess`, `loadingComponent`, etc.) so
+ * the generator can never accidentally embed callbacks as JS values.
+ *
+ * Fix #8: use a Pick instead of the full InlineCheckoutConfig.
+ */
+export type InlinePaymentConfig = Pick<
+  InlineCheckoutConfig,
+  | 'publicKey'
+  | 'amount'
+  | 'currency'
+  | 'customerName'
+  | 'customerEmail'
+  | 'customerPhoneNumber'
+  | 'feeBearer'
+  | 'reference'
+  | 'paymentMethods'
+>;
+
+/**
+ * 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.
+ */
+export function generateInlineHtml(config: InlinePaymentConfig): string {
+  // ── 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>`;
+}