react-native-fincra-checkout 1.0.0

package/lib/typescript/checkout/FincraCheckout.d.ts

@@ -0,0 +1,121 @@
+import React from 'react';
+import type { WebViewCheckoutConfig, InlineCheckoutConfig, FincraCheckoutResult } from '../types';
+/**
+ * @internal
+ * Imperative handle for the FincraCheckoutHost ref.
+ * Do not call `_openWebView` / `_openInline` directly — use `FincraCheckout.open*()`.
+ */
+export interface FincraCheckoutHostHandle {
+    _openWebView(config: WebViewCheckoutConfig): Promise<FincraCheckoutResult>;
+    _openInline(config: InlineCheckoutConfig): Promise<FincraCheckoutResult>;
+}
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
+export declare const FincraCheckoutHost: React.ForwardRefExoticComponent<React.RefAttributes<FincraCheckoutHostHandle>>;
+/**
+ * @internal
+ * Called by `<FincraCheckoutHostRegistrar />` to register the singleton ref.
+ * Not part of the public API — do not call this directly.
+ */
+export declare function _registerHostRef(ref: React.RefObject<FincraCheckoutHostHandle | null>): void;
+/**
+ * @internal
+ * Clears the singleton ref when the host unmounts.
+ * Not part of the public API — do not call this directly.
+ */
+export declare function _unregisterHostRef(): void;
+/**
+ * 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;
+ * }
+ * ```
+ */
+export declare 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: WebViewCheckoutConfig): Promise<FincraCheckoutResult>;
+    /**
+     * 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: InlineCheckoutConfig): Promise<FincraCheckoutResult>;
+    private static _assertHostMounted;
+}
+/**
+ * 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 />
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export declare function FincraCheckoutHostRegistrar(): React.JSX.Element;

package/lib/typescript/components/FincraInlineCheckout.d.ts

@@ -0,0 +1,21 @@
+import React from 'react';
+import type { InlineCheckoutConfig } from '../types';
+/**
+ * A transparent WebView that runs the Fincra inline JavaScript SDK.
+ *
+ * @example
+ * ```tsx
+ * <FincraInlineCheckout
+ *   publicKey="pk_live_xxxx"
+ *   amount={5000}
+ *   currency="NGN"
+ *   customerEmail="user@example.com"
+ *   customerName="John Doe"
+ *   customerPhoneNumber="08012345678"
+ *   feeBearer="customer"
+ *   onSuccess={(res) => console.log(res.reference)}
+ *   onCancelled={() => navigation.goBack()}
+ * />
+ * ```
+ */
+export declare function FincraInlineCheckout({ headerTitle, headerBackgroundColor, headerTintColor, showCancelConfirmationDialog, loadingComponent, closeIcon, renderError, onSuccess, onFailed, onCancelled, ...paymentConfig }: InlineCheckoutConfig): React.JSX.Element;

package/lib/typescript/components/FincraWebViewCheckout.d.ts

@@ -0,0 +1,18 @@
+import React from 'react';
+import type { WebViewCheckoutConfig } from '../types';
+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 declare function FincraWebViewCheckout({ checkoutUrl, redirectUrl, headerTitle, headerBackgroundColor, headerTintColor, showCancelConfirmationDialog, loadingComponent, closeIcon, renderError, onSuccess, onFailed, onCancelled, }: FincraWebViewCheckoutProps): React.JSX.Element;

package/lib/typescript/index.d.ts

@@ -0,0 +1,5 @@
+export { FincraCheckout, FincraCheckoutHostRegistrar as FincraCheckoutHost, } from './checkout/FincraCheckout';
+export { FincraWebViewCheckout } from './components/FincraWebViewCheckout';
+export { FincraInlineCheckout } from './components/FincraInlineCheckout';
+export { FincraCurrency, FeeBearer } from './types';
+export type { FincraPaymentResponse, FincraPaymentError, FincraCheckoutResult, BaseCheckoutProps, WebViewCheckoutConfig, InlineCheckoutConfig, } from './types';

package/lib/typescript/inline/JsBridge.d.ts

@@ -0,0 +1,33 @@
+import type { FincraPaymentResponse } from '../types';
+/** Events that can be posted from the Fincra inline JavaScript SDK. */
+export declare 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 declare function parseMessage(jsonString: string): FincraBridgeMessage;

package/lib/typescript/inline/htmlGenerator.d.ts

@@ -0,0 +1,21 @@
+import type { InlineCheckoutConfig } from '../types';
+/**
+ * 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 declare function generateInlineHtml(config: InlinePaymentConfig): string;

package/lib/typescript/types/index.d.ts

@@ -0,0 +1,142 @@
+import type { ReactNode } from 'react';
+/**
+ * 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.
+ */
+export declare const FincraCurrency: {
+    readonly NGN: "NGN";
+    readonly USD: "USD";
+    readonly GBP: "GBP";
+    readonly EUR: "EUR";
+    readonly GHS: "GHS";
+    readonly KES: "KES";
+    readonly ZAR: "ZAR";
+    readonly UGX: "UGX";
+    readonly XAF: "XAF";
+    readonly XOF: "XOF";
+};
+export type FincraCurrency = 'NGN' | 'USD' | 'GBP' | 'EUR' | 'GHS' | 'KES' | 'ZAR' | 'UGX' | 'XAF' | 'XOF';
+export declare const FeeBearer: {
+    readonly Business: "business";
+    readonly Customer: "customer";
+    readonly business: "business";
+    readonly customer: "customer";
+};
+export type FeeBearer = 'business' | 'customer';
+/** Normalized successful payment response. */
+export interface FincraPaymentResponse {
+    /** Merchant/customer reference — mirrors Flutter's `FincraPaymentResponse.reference`. */
+    reference: string;
+    /** Fincra internal transaction ID. */
+    transactionId: string;
+    /** Payment status string (e.g., 'success', 'failed'). */
+    status: string;
+    /** Optional human-readable message from Fincra. */
+    message?: string;
+    /**
+     * 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.
+     */
+    rawResponse: Record<string, string>;
+}
+/** Structured payment error. */
+export interface FincraPaymentError {
+    /** Error code string (e.g., 'timeout', 'cancelled', HTTP status code). */
+    code: string;
+    /** Human-readable error description. */
+    message: string;
+}
+/**
+ * All possible outcomes of a Fincra Checkout session.
+ * Use `result.type` to discriminate:
+ *
+ * @example
+ * ```typescript
+ * switch (result.type) {
+ *   case 'success':   handleSuccess(result.response); break;
+ *   case 'error':     handleError(result.error);       break;
+ *   case 'cancelled': handleCancelled();               break;
+ * }
+ * ```
+ */
+export type FincraCheckoutResult = {
+    type: 'success';
+    response: FincraPaymentResponse;
+} | {
+    type: 'error';
+    error: FincraPaymentError;
+} | {
+    type: 'cancelled';
+};
+/** Shared props across both checkout modes. */
+export interface BaseCheckoutProps {
+    /** Called when payment is successfully completed. */
+    onSuccess?: (response: FincraPaymentResponse) => void;
+    /** Called when the payment fails or encounters an error. */
+    onFailed?: (error: FincraPaymentError) => void;
+    /** Called when the user cancels/closes the checkout. */
+    onCancelled?: () => void;
+    /** Title shown in the navigation header. Defaults to 'Secure Checkout'. */
+    headerTitle?: string;
+    /** Background color of the navigation header bar. */
+    headerBackgroundColor?: string;
+    /**
+     * Text/icon color inside the navigation header.
+     * Also determines the status bar style:
+     * - `'#000000'` (default) → `dark-content` status bar icons
+     * - Any other value → `light-content` status bar icons
+     */
+    headerTintColor?: string;
+    /** If true, shows a confirmation dialog before dismissing. Default: false. */
+    showCancelConfirmationDialog?: boolean;
+    /** Custom loading indicator to display while the WebView is loading. */
+    loadingComponent?: ReactNode;
+    /** Custom close icon/element for the header. */
+    closeIcon?: ReactNode;
+    /** Custom error screen renderer for network/loading recovery. */
+    renderError?: (error: {
+        code: string;
+        message: string;
+    }, retry: () => void) => ReactNode;
+}
+/** Configuration for the WebView-based checkout (backend-generated URL). */
+export interface WebViewCheckoutConfig extends BaseCheckoutProps {
+    /**
+     * The backend-generated Fincra checkout URL.
+     * Generate this server-side using the Fincra API with your **secret key**.
+     * Never generate this on the client.
+     */
+    checkoutUrl: string;
+    /**
+     * Your backend redirect URL. When Fincra navigates to this URL,
+     * the SDK intercepts and resolves the payment result.
+     * If omitted, the SDK falls back to detecting `status` + `reference` query params.
+     */
+    redirectUrl?: string;
+}
+/** Configuration for the Inline JavaScript checkout (frontend-initiated). */
+export interface InlineCheckoutConfig extends BaseCheckoutProps {
+    /**
+     * Your Fincra **public key** (starts with `pk_`).
+     * @security Never use your secret key in mobile app code.
+     */
+    publicKey: string;
+    /** Amount to charge in the smallest currency unit (e.g., kobo for NGN). */
+    amount: number;
+    /** Currency for the transaction. */
+    currency: FincraCurrency;
+    /** Customer's email address. */
+    customerEmail: string;
+    /** Customer's full name. */
+    customerName: string;
+    /** Customer's phone number. */
+    customerPhoneNumber: string;
+    /** Who bears the Fincra processing fee. */
+    feeBearer: FeeBearer;
+    /** Optional unique transaction reference. Fincra generates one if omitted. */
+    reference?: string;
+    /** Restrict checkout to specific payment methods (e.g., ['card', 'bank_transfer']). */
+    paymentMethods?: string[];
+}

package/lib/typescript/utils/UrlHandler.d.ts

@@ -0,0 +1,44 @@
+import type { FincraPaymentResponse } from '../types';
+/**
+ * Utilities for detecting Fincra payment completion URLs and
+ * extracting normalized response parameters.
+ */
+export declare 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: string, expectedRedirectUrl?: string): boolean;
+    /**
+     * Extracts all query parameters from the URL as a `Record<string, string>`.
+     *
+     * @param url - The completion URL from Fincra.
+     */
+    static extractResponseParams(url: string): Record<string, string>;
+    /**
+     * 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: Record<string, string>): FincraPaymentResponse;
+    /**
+     * Determines if a status string represents a successful payment.
+     *
+     * @param status - The raw status string from Fincra.
+     */
+    static isSuccessStatus(status: string): boolean;
+    /**
+     * Parses URL query string into a `URLSearchParams`-like `Map`.
+     * Works in React Native (no DOM `URL` API available).
+     */
+    private static _parseQueryParams;
+}

package/package.json

@@ -0,0 +1,113 @@
+{
+  "name": "react-native-fincra-checkout",
+  "version": "1.0.0",
+  "description": "Production-ready React Native SDK for Fincra Checkout — WebView and Inline JavaScript modes with full TypeScript support.",
+  "main": "lib/commonjs/index.js",
+  "module": "lib/commonjs/index.js",
+  "types": "lib/typescript/index.d.ts",
+  "react-native": "src/index.ts",
+  "source": "src/index.ts",
+  "exports": {
+    ".": {
+      "react-native": "./src/index.ts",
+      "import": {
+        "types": "./lib/typescript/index.d.ts",
+        "default": "./lib/commonjs/index.js"
+      },
+      "require": {
+        "types": "./lib/typescript/index.d.ts",
+        "default": "./lib/commonjs/index.js"
+      }
+    }
+  },
+  "files": [
+    "src",
+    "lib",
+    "!lib/typescript/example",
+    "!**/__tests__",
+    "!**/__fixtures__",
+    "!**/__mocks__",
+    "!**/.*"
+  ],
+  "scripts": {
+    "test": "jest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint \"**/*.{js,ts,tsx}\"",
+    "build": "tsc --project tsconfig.build.json",
+    "prepare": "tsc --project tsconfig.build.json"
+  },
+  "keywords": [
+    "react-native",
+    "fincra",
+    "checkout",
+    "payment",
+    "webview",
+    "sdk"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fincra/react-native-fincra-checkout.git"
+  },
+  "author": "Fincra",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/fincra/react-native-fincra-checkout/issues"
+  },
+  "homepage": "https://github.com/fincra/react-native-fincra-checkout#readme",
+  "peerDependencies": {
+    "react": ">=17.0.0",
+    "react-native": ">=0.68.0",
+    "react-native-safe-area-context": ">=4.0.0",
+    "react-native-webview": ">=13.0.0"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.24.0",
+    "@babel/preset-env": "^7.24.0",
+    "@babel/preset-react": "^7.24.0",
+    "@babel/preset-typescript": "^7.24.0",
+    "@react-native/babel-preset": "^0.73.0",
+    "@testing-library/react-native": "^12.4.5",
+    "@types/jest": "^29.5.0",
+    "@types/react": "^18.0.0",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "babel-jest": "^29.7.0",
+    "eslint": "^8.57.0",
+    "eslint-plugin-react": "^7.34.0",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-react-native": "^4.1.0",
+    "jest": "^29.7.0",
+    "react": "18.2.0",
+    "react-native": "0.73.0",
+    "react-native-safe-area-context": "^4.9.0",
+    "react-native-webview": "^14.0.1",
+    "react-test-renderer": "18.2.0",
+    "typescript": "^5.4.0"
+  },
+  "jest": {
+    "preset": "react-native",
+    "testEnvironment": "node",
+    "moduleFileExtensions": [
+      "ts",
+      "tsx",
+      "js",
+      "jsx",
+      "json"
+    ],
+    "testMatch": [
+      "**/__tests__/**/*.test.[jt]s?(x)"
+    ],
+    "transform": {
+      "^.+\\.(ts|tsx|js|jsx)$": "babel-jest"
+    },
+    "transformIgnorePatterns": [
+      "node_modules/(?!(react-native|@react-native|react-native-webview|@testing-library|react-native-safe-area-context)/)"
+    ],
+    "setupFiles": [
+      "./__tests__/setup.js"
+    ],
+    "moduleNameMapper": {
+      "^react-native$": "<rootDir>/node_modules/react-native"
+    }
+  }
+}