react-native-fincra-checkout 1.0.0 → 1.0.2

package/src/components/FincraWebViewCheckout.tsx

@@ -10,7 +10,10 @@ import {
   TouchableOpacity,
   View,
 } from 'react-native';
-import { SafeAreaView } from 'react-native-safe-area-context';
+import {
+  SafeAreaProvider,
+  SafeAreaView,
+} from 'react-native-safe-area-context';
 import type {
   WebViewNavigation,
   WebViewErrorEvent,
@@ -53,6 +56,7 @@ export function FincraWebViewCheckout({
   headerBackgroundColor = '#FFFFFF',
   headerTintColor = '#000000',
   showCancelConfirmationDialog = false,
+  showCloseButton = true,
   loadingComponent,
   closeIcon,
   renderError,
@@ -64,7 +68,30 @@ export function FincraWebViewCheckout({
   const [errorState, setErrorState] = useState<FincraPaymentError | null>(null);
   const [reloadKey, setReloadKey] = useState(0);
   const webViewRef = useRef<WebView<object> | null>(null);
-  const hasCompleted = useRef(false);
+  // `settledRef`: a result (success / error / cancel) has been delivered.
+  // `isMountedRef`: late native callbacks after unmount must be ignored.
+  const settledRef = useRef(false);
+  const isMountedRef = useRef(false);
+
+  useEffect(() => {
+    isMountedRef.current = true;
+    return () => {
+      isMountedRef.current = false;
+    };
+  }, []);
+
+  /** True while callbacks may still update state or deliver a result. */
+  const isActive = useCallback(
+    () => isMountedRef.current && !settledRef.current,
+    []
+  );
+
+  /** Single exit point — delivers at most one result per session. */
+  const settle = useCallback((deliver: () => void) => {
+    if (!isMountedRef.current || settledRef.current) return;
+    settledRef.current = true;
+    deliver();
+  }, []);
 
   // Fix #10: Stable ref for handleCancellation — the BackHandler effect
   // always calls through this ref, never capturing a stale closure.
@@ -86,25 +113,24 @@ export function FincraWebViewCheckout({
   // ── 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';
+      // `status` or `payment_status`; missing → success (sandbox omits it).
+      // Merchants must verify every payment server-side.
+      const rawStatus = UrlHandler.extractStatus(params);
 
-      if (UrlHandler.isSuccessStatus(rawStatus)) {
-        const response = UrlHandler.parsePaymentResponse(params);
-        onSuccess?.(response);
-      } else {
-        const err: FincraPaymentError = {
-          code: rawStatus,
-          message: params['message'] ?? 'Payment failed',
-        };
-        onFailed?.(err);
-      }
+      settle(() => {
+        if (UrlHandler.isSuccessStatus(rawStatus)) {
+          onSuccess?.(UrlHandler.parsePaymentResponse(params));
+        } else {
+          const err: FincraPaymentError = {
+            code: rawStatus,
+            message: params['message'] ?? 'Payment failed',
+          };
+          onFailed?.(err);
+        }
+      });
     },
-    [onSuccess, onFailed]
+    [settle, onSuccess, onFailed]
   );
 
   // ── URL interception ────────────────────────────────────────────────────────
@@ -121,7 +147,7 @@ export function FincraWebViewCheckout({
 
   // ── Cancellation ────────────────────────────────────────────────────────────
   const handleCancellation = useCallback(() => {
-    if (hasCompleted.current) return;
+    if (!isActive()) return;
 
     if (showCancelConfirmationDialog) {
       Alert.alert(
@@ -132,49 +158,55 @@ export function FincraWebViewCheckout({
           {
             text: 'Yes',
             style: 'destructive',
-            onPress: () => {
-              if (!hasCompleted.current) {
-                hasCompleted.current = true;
-                onCancelled?.();
-              }
-            },
+            // May fire after unmount — settle() ignores it then.
+            onPress: () => settle(() => onCancelled?.()),
           },
         ]
       );
     } else {
-      hasCompleted.current = true;
-      onCancelled?.();
+      settle(() => onCancelled?.());
     }
-  }, [showCancelConfirmationDialog, onCancelled]);
+  }, [isActive, showCancelConfirmationDialog, settle, onCancelled]);
 
   // Keep the ref in sync after every render (Fix #10)
   useEffect(() => {
     handleCancellationRef.current = handleCancellation;
   });
 
-  // ── WebView error ───────────────────────────────────────────────────────────
+  // ── Load errors ─────────────────────────────────────────────────────────────
+  // react-native-webview only reports main-frame failures via onError /
+  // onHttpError (sub-resource errors are filtered natively). Load errors never
+  // settle the payment: they show the recoverable Retry/Cancel overlay.
+  // Errors for the redirect URL are expected (we block that navigation).
+  const showLoadError = useCallback(
+    (url: string | undefined, err: FincraPaymentError): void => {
+      if (!isActive()) return;
+      if (url && UrlHandler.isCompletionUrl(url, redirectUrl)) return;
+      setErrorState(err);
+      setIsLoading(false);
+    },
+    [isActive, redirectUrl]
+  );
+
   const handleError = useCallback(
-    (syntheticEvent: WebViewErrorEvent): void => {
-      if (hasCompleted.current) return;
-      const { nativeEvent } = syntheticEvent;
-      const err: FincraPaymentError = {
+    ({ nativeEvent }: WebViewErrorEvent): void => {
+      showLoadError(nativeEvent.url, {
         code: String(nativeEvent.code ?? 'webview_error'),
         message: nativeEvent.description ?? 'A WebView error occurred.',
-      };
-      setErrorState(err);
-      setIsLoading(false);
+      });
     },
-    []
+    [showLoadError]
   );
 
-  // ── 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);
-      }
+    ({ nativeEvent }: WebViewHttpErrorEvent): void => {
+      showLoadError(nativeEvent.url, {
+        code: String(nativeEvent.statusCode ?? 'http_error'),
+        message:
+          nativeEvent.description || `HTTP error ${nativeEvent.statusCode}`,
+      });
     },
-    [redirectUrl, handleError]
+    [showLoadError]
   );
 
   // ── Retry handler ───────────────────────────────────────────────────────────
@@ -188,7 +220,7 @@ export function FincraWebViewCheckout({
   // Fix #2: guard setIsLoading — don't flip loading state after completion.
   const onNavigationStateChange = useCallback(
     (navState: WebViewNavigation) => {
-      if (hasCompleted.current) return;
+      if (!isActive()) return;
       if (
         navState.url &&
         UrlHandler.isCompletionUrl(navState.url, redirectUrl)
@@ -196,7 +228,7 @@ export function FincraWebViewCheckout({
         handleCompletion(navState.url);
       }
     },
-    [redirectUrl, handleCompletion]
+    [isActive, redirectUrl, handleCompletion]
   );
 
   // ── Computed status bar style (Fix #11) ─────────────────────────────────────
@@ -204,111 +236,125 @@ export function FincraWebViewCheckout({
     headerTintColor === '#000000' ? 'dark-content' : 'light-content';
 
   // ── Render ──────────────────────────────────────────────────────────────────
+  // Own SafeAreaProvider: SafeAreaView reads insets from the nearest provider,
+  // and a Modal (FincraCheckoutHost) is a separate native tree. Without one the
+  // insets are 0 and the header sits under the status bar / Dynamic Island,
+  // where iOS swallows taps. Nested providers are fine if the app has its own.
   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 }}
+    <SafeAreaProvider style={styles.provider}>
+      <SafeAreaView style={styles.container}>
+        <StatusBar
+          barStyle={statusBarStyle}
+          backgroundColor={headerBackgroundColor}
+        />
+        {/* ── Header bar ── */}
+        <View
+          style={[styles.header, { backgroundColor: headerBackgroundColor }]}
         >
-          {closeIcon ?? (
-            <Text style={[styles.closeIcon, { color: headerTintColor }]}>
-              ✕
-            </Text>
+          {/* Spacer keeps the title centred when the close button is hidden */}
+          {showCloseButton ? (
+            <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>
+          ) : (
+            <View style={styles.closeButton} />
           )}
-        </TouchableOpacity>
-        <Text
-          style={[styles.headerTitle, { color: headerTintColor }]}
-          numberOfLines={1}
-        >
-          {headerTitle}
-        </Text>
-        {/* Spacer to centre the title */}
-        <View style={styles.closeButton} />
-      </View>
+          <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']}
-        />
+        {/* ── WebView ── */}
+        <View style={styles.webViewContainer}>
+          <WebView
+            key={reloadKey}
+            ref={webViewRef}
+            source={{ uri: checkoutUrl }}
+            style={styles.webView}
+            javaScriptEnabled
+            domStorageEnabled
+            startInLoadingState={false}
+            onLoadStart={() => {
+              if (isActive()) setIsLoading(true);
+            }}
+            onLoadEnd={() => {
+              if (isActive()) 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>
-        )}
+          {/* ── 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>
+          {/* ── 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>
+    </SafeAreaProvider>
   );
 }
 
 // ─── Styles ────────────────────────────────────────────────────────────────────
 
 const styles = StyleSheet.create({
+  provider: {
+    flex: 1,
+  },
   container: {
     flex: 1,
     backgroundColor: '#FFFFFF',

package/src/inline/JsBridge.ts

@@ -23,7 +23,10 @@ export enum FincraBridgeEvent {
 /** A parsed message posted by the Fincra JS SDK via `postMessage`. */
 export interface FincraBridgeMessage {
   event: FincraBridgeEvent;
-  /** Populated only for `success` and `error` events. */
+  /**
+   * Always populated for `success` events; populated for `error` events
+   * that carry a data object.
+   */
   data?: FincraPaymentResponse | { message: string };
 }
 
@@ -48,25 +51,15 @@ export function parseMessage(jsonString: string): FincraBridgeMessage {
     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);
-      }
+    if (event === FincraBridgeEvent.Success) {
+      // A success event is always a success — even with missing/malformed
+      // data (empty references), so a real payment is never hidden.
+      const rawData = map['data'];
+      const params =
+        rawData != null && typeof rawData === 'object' && !Array.isArray(rawData)
+          ? normalizeSuccessData(rawData as Record<string, unknown>)
+          : {};
+      if (!params['status']) params['status'] = 'success';
       return { event, data: UrlHandler.parsePaymentResponse(params) };
     }
 
@@ -92,6 +85,21 @@ export function parseMessage(jsonString: string): FincraBridgeMessage {
 
 // ── Internal ──────────────────────────────────────────────────────────────────
 
+/**
+ * Converts success data to a string map: objects/arrays are JSON-encoded,
+ * other values stringified, and `null`/`undefined` values dropped.
+ */
+function normalizeSuccessData(
+  data: Record<string, unknown>
+): Record<string, string> {
+  const params: Record<string, string> = {};
+  for (const [k, v] of Object.entries(data)) {
+    if (v == null) continue;
+    params[k] = typeof v === 'object' ? JSON.stringify(v) : String(v);
+  }
+  return params;
+}
+
 function _parseEvent(eventStr: string | null): FincraBridgeEvent {
   switch (eventStr) {
     case 'ready':

package/src/inline/htmlGenerator.ts

@@ -4,9 +4,9 @@ import type { InlineCheckoutConfig } from '../types';
 //
 // 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).
+// Security: the whole options object is encoded via toScriptJson() — JSON
+// plus escaping of `<`, `>`, `&`, U+2028 and U+2029 — so no input value can
+// inject JS or close the surrounding <script> element.
 
 const FINCRA_CDN_URL =
   'https://unpkg.com/@fincra-engineering/checkout@2.2.0/dist/inline.min.js';
@@ -31,6 +31,64 @@ export type InlinePaymentConfig = Pick<
   | 'paymentMethods'
 >;
 
+/** Options passed to `Fincra.initialize()` (callbacks are added in the page). */
+export interface InlineSdkOptions {
+  key: string;
+  amount: number;
+  currency: string;
+  feeBearer: string;
+  reference?: string;
+  paymentMethods?: string[];
+  customer: { name: string; email: string; phoneNumber?: string };
+}
+
+/**
+ * Builds the plain options object for `Fincra.initialize()`.
+ *
+ * Optional fields are omitted entirely when absent. `customer.phoneNumber`
+ * is optional in Fincra's API: it is trimmed, and left out when blank.
+ *
+ * Pure function — internal, not part of the package's public API.
+ */
+export function buildInlineOptions(
+  config: InlinePaymentConfig
+): InlineSdkOptions {
+  const customer: InlineSdkOptions['customer'] = {
+    name: config.customerName,
+    email: config.customerEmail,
+  };
+  const phone = config.customerPhoneNumber?.trim();
+  if (phone) customer.phoneNumber = phone;
+
+  const options: InlineSdkOptions = {
+    key: config.publicKey,
+    amount: config.amount,
+    currency: config.currency.toUpperCase(),
+    feeBearer: config.feeBearer,
+    customer,
+  };
+  if (config.reference != null) options.reference = config.reference;
+  if (config.paymentMethods != null && config.paymentMethods.length > 0) {
+    options.paymentMethods = config.paymentMethods;
+  }
+  return options;
+}
+
+/**
+ * JSON-encodes a value for embedding inside an inline `<script>` block.
+ * Besides JSON escaping, `<`, `>` and `&` are escaped so a value containing
+ * `</script>` or `<!--` cannot break out of the script element, and
+ * U+2028/U+2029 are escaped for older JS engines.
+ */
+export function toScriptJson(value: unknown): string {
+  return JSON.stringify(value)
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/&/g, '\\u0026')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+}
+
 /**
  * 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
@@ -43,25 +101,8 @@ export type InlinePaymentConfig = Pick<
  * @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)},`
-      : '';
+  // ── Safe encoding — every value goes through toScriptJson() ──
+  const optionsJson = toScriptJson(buildInlineOptions(config));
 
   return `<!DOCTYPE html>
 <html>
@@ -108,25 +149,14 @@ export function generateInlineHtml(config: InlinePaymentConfig): string {
       // 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},
-        },
+      var options = Object.assign(${optionsJson}, {
         onClose: function() {
           postToRN('closed', null);
         },
         onSuccess: function(data) {
           postToRN('success', data);
         },
-      };
+      });
 
       Fincra.initialize(options);
     }

package/src/types/index.ts

@@ -56,7 +56,8 @@ export interface FincraPaymentResponse {
   /**
    * Full raw response map. All values are strings.
    * For inline mode, numeric/boolean fields from Fincra (e.g. `amount`) are
-   * coerced to strings to match the URL-params format used in WebView mode.
+   * coerced to strings to match the URL-params format used in WebView mode;
+   * nested objects/arrays are JSON-encoded and `null` values are dropped.
    */
   rawResponse: Record<string, string>;
 }
@@ -114,6 +115,13 @@ export interface BaseCheckoutProps {
   showCancelConfirmationDialog?: boolean;
   /** Custom loading indicator to display while the WebView is loading. */
   loadingComponent?: ReactNode;
+  /**
+   * Show the ✕ close button in the header. Default: true.
+   * If you hide it, users can still leave via the error screen's Cancel
+   * button and the Android back button — but on iOS there is no other way to
+   * leave while the page is loading, or if it hangs.
+   */
+  showCloseButton?: boolean;
   /** Custom close icon/element for the header. */
   closeIcon?: ReactNode;
   /** Custom error screen renderer for network/loading recovery. */
@@ -154,8 +162,11 @@ export interface InlineCheckoutConfig extends BaseCheckoutProps {
   customerEmail: string;
   /** Customer's full name. */
   customerName: string;
-  /** Customer's phone number. */
-  customerPhoneNumber: string;
+  /**
+   * Customer's phone number (optional in Fincra's API). Trimmed; when blank
+   * it is not sent to Fincra at all.
+   */
+  customerPhoneNumber?: string;
   /** Who bears the Fincra processing fee. */
   feeBearer: FeeBearer;
   /** Optional unique transaction reference. Fincra generates one if omitted. */