react-native-fincra-checkout 1.0.0

package/README.md

@@ -0,0 +1,309 @@
+# react-native-fincra-checkout
+
+<p align="center">
+  <img src="https://img.shields.io/npm/v/react-native-fincra-checkout?color=0066FF&style=flat-square" alt="npm version" />
+  <img src="https://img.shields.io/badge/TypeScript-100%25-blue?style=flat-square" alt="TypeScript" />
+  <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="license" />
+  <img src="https://img.shields.io/badge/platform-iOS%20%7C%20Android-lightgrey?style=flat-square" alt="platforms" />
+</p>
+
+A **production-ready**, **100% TypeScript** React Native SDK for [Fincra Checkout](https://fincra.com/checkout), with full feature and architectural parity with the official `flutter_fincra_checkout` package.
+
+---
+
+## Features
+
+- ✅ **Two checkout modes**: WebView (recommended) and Inline JavaScript
+- ✅ **Imperative API**: `await FincraCheckout.openWebView({...})` from anywhere
+- ✅ **Declarative API**: `<FincraWebViewCheckout />` and `<FincraInlineCheckout />`
+- ✅ **Strongly-typed result**: Discriminated union — `success | error | cancelled`
+- ✅ **URL interception**: Redirect URL prefix match + query-param fallback
+- ✅ **15-second init timeout** for the Inline mode
+- ✅ **Modern SafeAreaView** via `react-native-safe-area-context`
+- ✅ **Built-in Error Recovery & Offline Retry UI** with custom `renderError` prop support
+- ✅ **Android back button** support
+- ✅ **Cancellation confirmation dialog** (optional)
+- ✅ **XSS-safe** HTML generation (all inputs JSON-encoded)
+
+---
+
+## Installation
+
+```bash
+npm install react-native-fincra-checkout react-native-webview react-native-safe-area-context
+# or
+yarn add react-native-fincra-checkout react-native-webview react-native-safe-area-context
+```
+
+### iOS — link native modules
+
+```bash
+cd ios && pod install
+```
+
+### Android — no extra steps needed
+
+`react-native-webview` auto-links on Android.
+
+---
+
+## ⚠️ Security Notice
+
+> **Never store your Fincra Secret Key in your mobile app bundle.**
+>
+> - For **WebView Checkout**: Generate the `checkoutUrl` server-side using your secret key via the Fincra API, then pass the URL to the SDK.
+> - For **Inline Checkout**: Only your **public key** (`pk_...`) is used. This is safe to bundle.
+>
+> Storing secret keys in client code exposes them to reverse engineering and can lead to fraudulent transactions.
+
+---
+
+## Setup — Add the Host Component
+
+Add `<FincraCheckoutHost />` **once** at your app root. This enables the imperative `FincraCheckout.open*()` API:
+
+```tsx
+// App.tsx
+import { FincraCheckoutHost } from 'react-native-fincra-checkout';
+
+export default function App() {
+  return (
+    <>
+      <NavigationContainer>
+        <RootNavigator />
+      </NavigationContainer>
+
+      {/* ← Add this once at the end of your root component */}
+      <FincraCheckoutHost />
+    </>
+  );
+}
+```
+
+> **Note**: The host renders nothing until a checkout is opened. It must be inside a rendered component tree (not a provider).
+
+---
+
+## WebView vs. Inline — Comparison
+
+| Feature | WebView Checkout | Inline JS Checkout |
+|---|---|---|
+| **Trigger** | Backend-generated URL | Public key + params |
+| **Key required** | Secret key *(server-side only)* | Public key *(client-safe)* |
+| **Payment flow** | Full Fincra-hosted page | Embedded Fincra JS widget |
+| **URL interception** | ✅ Redirect URL or query params | ❌ N/A (JS bridge events) |
+| **Init timeout** | ❌ N/A | ✅ 15 seconds |
+| **Recommended for** | Production (most secure) | Frontend-only prototypes |
+
+---
+
+## Usage
+
+### A. Imperative API (Promise / async-await)
+
+#### WebView Mode — recommended
+
+```tsx
+import { FincraCheckout } from 'react-native-fincra-checkout';
+
+async function handlePayment() {
+  const result = await FincraCheckout.openWebView({
+    // Generated by your backend using Fincra API + secret key
+    checkoutUrl: 'https://checkout.fincra.com/pay/abc123',
+    // Your backend redirect URL — intercepted by the SDK
+    redirectUrl: 'https://api.yourapp.com/payment/callback',
+    headerTitle: 'Complete Payment',
+    showCancelConfirmationDialog: true,
+  });
+
+  switch (result.type) {
+    case 'success':
+      console.log('Payment successful:', result.response.reference);
+      break;
+    case 'error':
+      console.error('Payment failed:', result.error.message);
+      break;
+    case 'cancelled':
+      console.log('User cancelled the payment');
+      break;
+  }
+}
+```
+
+#### Inline Mode
+
+```tsx
+import { FincraCheckout } from 'react-native-fincra-checkout';
+
+async function handleInlinePayment() {
+  const result = await FincraCheckout.openInline({
+    publicKey: 'pk_live_xxxxxxxxxxxx',
+    amount: 5000,          // in smallest currency unit (e.g., kobo for NGN)
+    currency: 'NGN',
+    customerEmail: 'customer@example.com',
+    customerName: 'Jane Doe',
+    customerPhoneNumber: '08012345678',
+    feeBearer: 'customer',
+    reference: 'ORDER-001', // optional — Fincra generates one if omitted
+    paymentMethods: ['card', 'bank_transfer'], // optional
+  });
+
+  if (result.type === 'success') {
+    const { reference, transactionId, status } = result.response;
+    console.log({ reference, transactionId, status });
+  }
+}
+```
+
+---
+
+### B. Declarative Component API
+
+Embed checkout views directly inside your own modals, bottom sheets, or navigation screens:
+
+#### `<FincraWebViewCheckout />`
+
+```tsx
+import { FincraWebViewCheckout } from 'react-native-fincra-checkout';
+
+function PaymentScreen() {
+  return (
+    <FincraWebViewCheckout
+      checkoutUrl="https://checkout.fincra.com/pay/abc123"
+      redirectUrl="https://api.yourapp.com/payment/callback"
+      headerTitle="Secure Payment"
+      headerBackgroundColor="#0066FF"
+      headerTintColor="#FFFFFF"
+      showCancelConfirmationDialog
+      onSuccess={(response) => {
+        console.log('Success:', response.reference);
+        navigation.navigate('PaymentSuccess');
+      }}
+      onFailed={(error) => {
+        console.error('Error:', error.message);
+      }}
+      onCancelled={() => {
+        navigation.goBack();
+      }}
+    />
+  );
+}
+```
+
+#### `<FincraInlineCheckout />`
+
+```tsx
+import { FincraInlineCheckout } from 'react-native-fincra-checkout';
+
+function InlinePaymentScreen() {
+  return (
+    <FincraInlineCheckout
+      publicKey="pk_live_xxxxxxxxxxxx"
+      amount={10000}
+      currency="NGN"
+      customerEmail="customer@example.com"
+      customerName="John Doe"
+      customerPhoneNumber="08099887766"
+      feeBearer="business"
+      onSuccess={(response) => console.log(response)}
+      onFailed={(error) => console.error(error)}
+      onCancelled={() => navigation.goBack()}
+    />
+  );
+}
+```
+
+---
+
+## TypeScript Types
+
+```typescript
+import type {
+  FincraCheckoutResult,
+  FincraPaymentResponse,
+  FincraPaymentError,
+  WebViewCheckoutConfig,
+  InlineCheckoutConfig,
+  FincraCurrency,
+  FeeBearer,
+} from 'react-native-fincra-checkout';
+
+// Discriminated union result
+const result: FincraCheckoutResult =
+  | { type: 'success'; response: FincraPaymentResponse }
+  | { type: 'error';   error: FincraPaymentError }
+  | { type: 'cancelled' };
+```
+
+### Supported Currencies
+
+`NGN` · `USD` · `GBP` · `EUR` · `GHS` · `KES` · `ZAR` · `UGX` · `XAF` · `XOF`
+
+---
+
+## Props Reference
+
+### Shared (`BaseCheckoutProps`)
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `onSuccess` | `(response) => void` | — | Called on successful payment |
+| `onFailed` | `(error) => void` | — | Called on payment error |
+| `onCancelled` | `() => void` | — | Called when user cancels |
+| `headerTitle` | `string` | `'Secure Checkout'` | Navigation bar title |
+| `headerBackgroundColor` | `string` | `'#FFFFFF'` | Nav bar background color |
+| `headerTintColor` | `string` | `'#000000'` | Nav bar text/icon color |
+| `showCancelConfirmationDialog` | `boolean` | `false` | Show Alert before closing |
+| `loadingComponent` | `ReactNode` | `ActivityIndicator` | Custom loading spinner |
+| `closeIcon` | `ReactNode` | `✕` text | Custom close button content |
+
+### `WebViewCheckoutConfig`
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `checkoutUrl` | `string` | ✅ | Backend-generated Fincra checkout URL |
+| `redirectUrl` | `string` | — | Redirect URL to intercept for completion |
+
+### `InlineCheckoutConfig`
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `publicKey` | `string` | ✅ | Your Fincra public key (`pk_...`) |
+| `amount` | `number` | ✅ | Amount in smallest currency unit |
+| `currency` | `FincraCurrency` | ✅ | Payment currency |
+| `customerEmail` | `string` | ✅ | Customer email |
+| `customerName` | `string` | ✅ | Customer full name |
+| `customerPhoneNumber` | `string` | ✅ | Customer phone number |
+| `feeBearer` | `FeeBearer` | ✅ | `'business'` or `'customer'` |
+| `reference` | `string` | — | Custom transaction reference |
+| `paymentMethods` | `string[]` | — | Restrict to specific methods |
+
+---
+
+## How URL Interception Works
+
+The WebView mode intercepts navigation requests:
+
+1. **If `redirectUrl` is set**: Any URL starting with `redirectUrl` triggers completion (prefix match — mirrors Flutter's `url.startsWith(redirectUrl)`).
+2. **Fallback** (no `redirectUrl`): Completion is detected when both `status` (or `payment_status`) **and** `reference` query params are present.
+
+Response parameters are normalized:
+- `customerReference` → `reference` (preferred)
+- `merchantReference` → `reference` (fallback)
+- `transactionReference` → `transactionId`
+
+---
+
+## Running Tests
+
+```bash
+npm test
+```
+
+Tests cover `UrlHandler` (URL detection, param extraction, reference normalization) and `JsBridge` (event parsing, data coercion, malformed input handling) — no device or emulator required.
+
+---
+
+## License
+
+MIT © [Fincra](https://fincra.com)

package/lib/commonjs/checkout/FincraCheckout.js

@@ -0,0 +1,249 @@
+"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.FincraCheckout = exports.FincraCheckoutHost = void 0;
+exports._registerHostRef = _registerHostRef;
+exports._unregisterHostRef = _unregisterHostRef;
+exports.FincraCheckoutHostRegistrar = FincraCheckoutHostRegistrar;
+const react_1 = __importStar(require("react"));
+const react_native_1 = require("react-native");
+const FincraWebViewCheckout_1 = require("../components/FincraWebViewCheckout");
+const FincraInlineCheckout_1 = require("../components/FincraInlineCheckout");
+/**
+ * Place this component once at your app root (inside your root view, after
+ * your navigator/providers). It renders nothing until `FincraCheckout.open*()`
+ * is called — then it mounts a full-screen `Modal` over the current UI.
+ *
+ * @example
+ * ```tsx
+ * // App.tsx
+ * export default function App() {
+ *   return (
+ *     <NavigationContainer>
+ *       <RootNavigator />
+ *       <FincraCheckoutHost />  {/* ← add this once *\/}
+ *     </NavigationContainer>
+ *   );
+ * }
+ * ```
+ */
+exports.FincraCheckoutHost = (0, react_1.forwardRef)(function FincraCheckoutHost(_props, ref) {
+    const [modalState, setModalState] = (0, react_1.useState)({ mode: null });
+    const resolveRef = (0, react_1.useRef)(null);
+    // ── Resolve and dismiss ────────────────────────────────────────────────────
+    const resolve = (0, react_1.useCallback)((result) => {
+        setModalState({ mode: null });
+        resolveRef.current?.(result);
+        resolveRef.current = null;
+    }, []);
+    // ── Expose imperative methods via ref ──────────────────────────────────────
+    (0, react_1.useImperativeHandle)(ref, () => ({
+        // Fix #1: guard against double-open — reject instead of orphaning the
+        // pending Promise and silently clobbering resolveRef.
+        _openWebView(config) {
+            if (resolveRef.current) {
+                return Promise.reject(new Error('[FincraCheckout] A checkout session is already open. ' +
+                    'Await the current session before opening another.'));
+            }
+            return new Promise((res) => {
+                resolveRef.current = res;
+                setModalState({ mode: 'webview', webViewConfig: config });
+            });
+        },
+        _openInline(config) {
+            if (resolveRef.current) {
+                return Promise.reject(new Error('[FincraCheckout] A checkout session is already open. ' +
+                    'Await the current session before opening another.'));
+            }
+            return new Promise((res) => {
+                resolveRef.current = res;
+                setModalState({ mode: 'inline', inlineConfig: config });
+            });
+        },
+    }), [ /* resolve not needed — used via resolveRef */]);
+    const isVisible = modalState.mode !== null;
+    // ── Shared callback builders ───────────────────────────────────────────────
+    const buildCallbacks = (0, react_1.useCallback)((config) => ({
+        onSuccess: (response) => {
+            config.onSuccess?.(response);
+            resolve({ type: 'success', response });
+        },
+        onFailed: (error) => {
+            config.onFailed?.(error);
+            resolve({ type: 'error', error });
+        },
+        onCancelled: () => {
+            config.onCancelled?.();
+            resolve({ type: 'cancelled' });
+        },
+    }), [resolve]);
+    return (react_1.default.createElement(react_native_1.Modal, { visible: isVisible, animationType: "slide", presentationStyle: "fullScreen", statusBarTranslucent: true, onRequestClose: () => {
+            // Android hardware back — treat as cancellation
+            const cfg = modalState.webViewConfig ?? modalState.inlineConfig;
+            if (cfg) {
+                cfg.onCancelled?.();
+            }
+            resolve({ type: 'cancelled' });
+        } },
+        react_1.default.createElement(react_native_1.View, { style: styles.fullscreen },
+            modalState.mode === 'webview' && modalState.webViewConfig && (react_1.default.createElement(FincraWebViewCheckout_1.FincraWebViewCheckout, { ...modalState.webViewConfig, ...buildCallbacks(modalState.webViewConfig) })),
+            modalState.mode === 'inline' && modalState.inlineConfig && (react_1.default.createElement(FincraInlineCheckout_1.FincraInlineCheckout, { ...modalState.inlineConfig, ...buildCallbacks(modalState.inlineConfig) })))));
+});
+// ─── Singleton Ref ─────────────────────────────────────────────────────────────
+// A module-level ref that FincraCheckout.open*() calls are routed through.
+// Set by the first <FincraCheckoutHost /> that mounts.
+let _hostRef = null;
+/**
+ * @internal
+ * Called by `<FincraCheckoutHostRegistrar />` to register the singleton ref.
+ * Not part of the public API — do not call this directly.
+ */
+function _registerHostRef(ref) {
+    _hostRef = ref;
+}
+/**
+ * @internal
+ * Clears the singleton ref when the host unmounts.
+ * Not part of the public API — do not call this directly.
+ */
+function _unregisterHostRef() {
+    _hostRef = null;
+}
+// ─── Public FincraCheckout Static API ─────────────────────────────────────────
+/**
+ * Imperative static API for opening Fincra Checkout modals from anywhere
+ * in your app — no navigation prop or context required.
+ *
+ * **Prerequisite**: `<FincraCheckoutHost />` must be mounted at your app root.
+ *
+ * @example
+ * ```typescript
+ * // WebView mode (recommended — backend-generated URL)
+ * const result = await FincraCheckout.openWebView({
+ *   checkoutUrl: 'https://checkout.fincra.com/pay/...',
+ *   redirectUrl: 'https://api.yourapp.com/payment/callback',
+ * });
+ *
+ * // Inline mode (frontend-initiated)
+ * const result = await FincraCheckout.openInline({
+ *   publicKey: 'pk_live_...',
+ *   amount: 5000,
+ *   currency: 'NGN',
+ *   customerEmail: 'user@example.com',
+ *   customerName: 'Jane Doe',
+ *   customerPhoneNumber: '08012345678',
+ *   feeBearer: 'customer',
+ * });
+ *
+ * switch (result.type) {
+ *   case 'success':   console.log(result.response.reference); break;
+ *   case 'error':     console.error(result.error.message);    break;
+ *   case 'cancelled': console.log('User cancelled');          break;
+ * }
+ * ```
+ */
+class FincraCheckout {
+    /**
+     * Opens the WebView checkout in a full-screen modal.
+     *
+     * This is the **recommended** flow — your backend generates the `checkoutUrl`
+     * using the Fincra API with your **secret key** (never in the app).
+     *
+     * @param config - WebView checkout configuration.
+     * @returns A promise resolving to a `FincraCheckoutResult` discriminated union.
+     * @throws Error if `<FincraCheckoutHost />` is not mounted.
+     * @throws Error if a checkout session is already open.
+     */
+    static openWebView(config) {
+        FincraCheckout._assertHostMounted();
+        return _hostRef.current._openWebView(config);
+    }
+    /**
+     * Opens the Inline JavaScript checkout in a full-screen modal.
+     *
+     * Uses only the Fincra **public key** (`pk_...`).
+     * The Fincra JS SDK is loaded from the CDN at runtime.
+     *
+     * @param config - Inline checkout configuration.
+     * @returns A promise resolving to a `FincraCheckoutResult` discriminated union.
+     * @throws Error if `<FincraCheckoutHost />` is not mounted.
+     * @throws Error if a checkout session is already open.
+     */
+    static openInline(config) {
+        FincraCheckout._assertHostMounted();
+        return _hostRef.current._openInline(config);
+    }
+    static _assertHostMounted() {
+        if (!_hostRef?.current) {
+            throw new Error('[react-native-fincra-checkout] FincraCheckoutHost is not mounted. ' +
+                'Add <FincraCheckoutHost /> to your App root before calling FincraCheckout.open*().');
+        }
+    }
+}
+exports.FincraCheckout = FincraCheckout;
+// ─── Self-registering Host wrapper ────────────────────────────────────────────
+/**
+ * The component you add to your app root.
+ * It self-registers as the singleton checkout host.
+ *
+ * @example
+ * ```tsx
+ * // App.tsx
+ * import { FincraCheckoutHost } from 'react-native-fincra-checkout';
+ *
+ * export default function App() {
+ *   return (
+ *     <>
+ *       <YourApp />
+ *       <FincraCheckoutHost />
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+function FincraCheckoutHostRegistrar() {
+    const ref = (0, react_1.useRef)(null);
+    (0, react_1.useEffect)(() => {
+        _registerHostRef(ref);
+        return () => _unregisterHostRef();
+    }, []);
+    return react_1.default.createElement(exports.FincraCheckoutHost, { ref: ref });
+}
+// ─── Styles ────────────────────────────────────────────────────────────────────
+const styles = react_native_1.StyleSheet.create({
+    fullscreen: {
+        flex: 1,
+    },
+});