react-native-payengine 2.0.17 → 2.0.18-alpha.2

package/src/components/v2/PayEngineNative.tsx

@@ -1,23 +1,96 @@
-import { NativeModules, Platform } from "react-native";
+import { NativeEventEmitter, NativeModules, Platform } from "react-native";
 import { PayProvider } from "../../interfaces";
 
-const { RNPayEngineNative } = NativeModules;
+const { RNPayEngineNative, RNPEEventEmitter } = NativeModules;
 
+/**
+ * Represents an access token used for authenticating with the PayEngine SDK.
+ *
+ * @remarks
+ * The access token contains the actual token string and the duration (in seconds)
+ * for which the token remains valid. This is typically retrieved from your backend
+ * and used for making authenticated requests.
+ *
+ * @property accessToken - The access token string.
+ * @property expiresIn - The time (in seconds) until the token expires.
+ *  
+ * @category PayEngine
+ */
+export type AccessToken = {
+  accessToken: string;
+  expiresIn: number;
+};
+
+/**
+ * A callback function that provides an access token to the PayEngine SDK.
+ *
+ * @returns A promise resolving to a valid {@link AccessToken}.
+ * 
+ * @category PayEngine
+ */
+export type FetchAccessTokenCallback = () => Promise<AccessToken>;
+
+/**
+ * Provides an interface for interacting with the native PayEngine SDK.
+ *
+ * @remarks
+ * `PayEngineNative` acts as a bridge between your React Native JavaScript code and
+ * the native PayEngine SDKs on iOS and Android. It utilizes React Native's
+ * Native Modules and platform channels to enable core payment functionalities.
+ *
+ * These include:
+ * - Fraud monitoring
+ * - Browser/device info retrieval
+ * - Support detection for Apple Pay and Google Pay
+ *
+ *
+ * @category PayEngine
+ */
 export default class PayEngineNative {
-  static async createFraudMonitorSession(merchantId: string) { 
+  private static emitter = new NativeEventEmitter(RNPEEventEmitter);
+
+  private static isFetchCallbackListenerRegistered = false;
+
+  private static fetchAccessTokenCallback: FetchAccessTokenCallback | null = null;
+
+
+  private constructor() { }
+
+  /**
+   * Retrieves a fraud monitoring session ID from the native PayEngine SDK.
+   *
+   *
+   * @param merchantId - The unique identifier for the merchant.
+   * @returns A `Promise<string>` containing the fraud monitoring session ID.
+   */
+  static async createFraudMonitorSession(merchantId: string): Promise<string> {
     return RNPayEngineNative.createFraudMonitorSession(merchantId);
   }
 
-  static async getBrowserInfo() {
+  /**
+   * Retrieves browser-related information from the native PayEngine SDK.
+   *
+   * @returns A `Promise<string>` containing browser and device details.
+   *
+   */
+  static async getBrowserInfo(): Promise<string> {
     return RNPayEngineNative.getBrowserInfo();
   }
 
   /**
-   * @deprecated use userCanPay instead
-   * @param merchantId 
-   * @returns 
+   * @deprecated Use {@link PayEngineNative.userCanPay} instead.
+   *
+   * Checks if platform-native payments (Apple Pay or Google Pay) are supported on the current device.
+   *
+   * @remarks
+   * This method has been deprecated in favor of {@link PayEngineNative.userCanPay}, which allows specifying
+   * the payment provider explicitly.
+   *
+   * @param merchantId - The unique identifier for the merchant.
+   * @returns A `Promise<boolean>` indicating whether the platform-specific payment method is supported.
+   *
    */
-  static async isPlatformPaySupported(merchantId: string) {
+  static async isPlatformPaySupported(merchantId: string): Promise<boolean> {
     if (Platform.OS === 'ios') {
       return await RNPayEngineNative.isApplePaySupported(merchantId);
     } else if (Platform.OS === 'android') {
@@ -26,7 +99,22 @@ export default class PayEngineNative {
     return false;
   }
 
-  static async userCanPay(provider: PayProvider, merchantId: string) {
+  /**
+   * Checks if the user can make payments using Apple Pay (iOS) or Google Pay (Android).
+   *
+   * @remarks
+   * This method verifies whether the current device and platform support the selected payment provider.
+   * It performs a platform-specific check using the native PayEngine SDK for either Apple Pay or Google Pay.
+   *
+   * ## Supported Providers
+   * - `PayProvider.googlePay` (Android only)
+   * - `PayProvider.applePay` (iOS only)
+   *
+   * @param provider - The payment provider to check support for.
+   * @param merchantId - The unique identifier for the merchant.
+   * @returns A `Promise<boolean>` indicating whether the selected payment method is supported.
+   */
+  static async userCanPay(provider: PayProvider, merchantId: string): Promise<boolean> {
     if (provider == PayProvider.applePay && Platform.OS == 'ios') {
       return await RNPayEngineNative.isApplePaySupported(merchantId);
     } else if (provider === PayProvider.googlePay && Platform.OS === 'android') {
@@ -34,4 +122,103 @@ export default class PayEngineNative {
     }
     return false;
   }
+
+
+  /**
+   * Sets the callback function that provides an access token when required by PayEngine.
+   *
+   * @remarks
+   * When the PayEngine SDK needs an access token, it will call this callback function
+   * to request the host application to fetch a new token from its backend.
+   * 
+   * The SDK uses this token internally to make calls to merchant related APIs which require merchant's credentials.
+   *
+   * ## Important:
+   * - PayEngine will invoke this callback **whenever an access token is needed or needs to be refreshed**.
+   * - The integrator must ensure that the token retrieval logic is secure and efficient in their backend.
+   * - For more details on how to retrieve the access token from Payengine, refer to the official documentation:
+   *   [PayEngine Merchant Session](https://docs.payengine.co/merchant-session#obtaining-a-new-merchant-session)
+   *
+   * ## Example Usage
+   * ```ts
+   * const fetchAccessToken = async (): Promise<AccessToken> => {
+   *   try {
+   *     // Make a network request to your server to fetch the token
+   *     // Your server then makes a request to Payengine securely and returns the results back in response
+   *     const response = await fetch("https://yourserver.com/accessToken");
+   *     
+   *     if (!response.ok) {
+   *       throw new Error(`Server responded with status ${response.status}`);
+   *     }
+   *     
+   *     const data = await response.json();
+   *     
+   *     // Extract the token and expiration from your server's response
+   *     const token = data.access_token;
+   *     const expiresIn = data.expires_in;
+   *
+   *     return { accessToken: token, expiresIn };
+   *   } catch (e) {
+   *     throw new Error("Failed to fetch access token: " + e);
+   *   }
+   * };
+   * 
+   * // This is where you supply the callback to the SDK
+   * PayEngineNative.setFetchAccessTokenCallback(fetchAccessToken);
+   * ```
+   *
+   * @param callback - A function that returns a `Promise<AccessToken>`. The function must handle
+   * errors properly in case token retrieval fails.
+   */
+  static async setFetchAccessTokenCallback(callback: FetchAccessTokenCallback) {
+    PayEngineNative.fetchAccessTokenCallback = callback;
+
+    if (!PayEngineNative.isFetchCallbackListenerRegistered) {
+      PayEngineNative.emitter.addListener("fetchAccessToken", async () => {
+        try {
+          const result = await PayEngineNative.fetchAccessTokenCallback!();
+          RNPayEngineNative.provideFetchAccessTokenResult(result);
+        } catch (error) {
+          RNPayEngineNative.provideFetchAccessTokenResult(null);
+        }
+      });
+      PayEngineNative.isFetchCallbackListenerRegistered = true;
+    }
+
+
+    RNPayEngineNative.configureFetchAccessTokenCallback();
+  }
+
+  /**
+   * Logs out the current merchant by invalidating the access token.
+   *
+   * @remarks
+   * While access tokens automatically expire, it's **strongly recommended** to explicitly invalidate
+   * them when a merchant's session ends on the server.
+   *
+   * Relying solely on token expiration can introduce **security vulnerabilities** 
+   * and result in a **suboptimal user experience**.
+   *
+   * Calling this method ensures that the merchant's session is terminated, 
+   * preventing any further authenticated requests until a new login is performed.
+   *
+   * For more details, refer to the official documentation:  
+   * [PayEngine Merchant Session](https://docs.payengine.co/merchant-session)
+   *
+   * ## Example Usage
+   * ```ts
+   * const merchantId = "your_merchant_id_here";
+   * await PayEngineNative.logout(merchantId);
+   * console.log("Merchant session terminated.");
+   * ```
+   *
+   * This ensures that no further authenticated requests can be made
+   * until a new access token is fetched.
+   *
+   * @param merchantId - The unique identifier of the merchant whose session should be invalidated.
+   * @returns A `Promise` indicating the completion of the logout process.
+   */
+  static async logout(merchantId: string): Promise<void> {
+    return RNPayEngineNative.logout(merchantId);
+  }
 }

package/src/components/v2/PayEngineProvider.tsx

@@ -6,6 +6,57 @@ const { RNPayEngineNative } = NativeModules;
 
 const PayEngineContext = createContext<IPayEngineConfig | undefined>(undefined);
 
+/**
+ * A provider that initializes and manages PayEngine's configuration across the app.
+ *
+ * `PayEngineProvider` ensures that PayEngine's SDK is properly set up by loading
+ * the necessary configurations before rendering the app. It must wrap the root widget
+ * for the payment functionalities to work correctly.
+ *
+ * ## Usage
+ *
+ * Before using PayEngine in your application, wrap your app inside [PayEngineProvider]
+ * and pass an `IPayEngineConfig` instance containing your public key, script URL, and optional log level.
+ *
+ * ```tsx
+ * const PE_CONFIG: IPayEngineConfig = {
+ *   publicKey: PUBLIC_KEY,
+ *   scriptURL: "https://staging-sandbox.payengine.dev/",
+ *   logLevel: 1,
+ * };
+ *
+ * return (
+ *   <PayEngineProvider config={PE_CONFIG}>
+ *     <NavigationContainer>
+ *       <DrawerNavigator />
+ *     </NavigationContainer>
+ *   </PayEngineProvider>
+ * );
+ * ```
+ *
+ * ## How It Works
+ *
+ * 1. The `PayEngineProvider` component accepts a configuration object (`IPayEngineConfig`) containing 
+ *    the `publicKey`, `scriptURL`, and `logLevel`.
+ * 2. It initializes the PayEngine SDK with the `publicKey` 
+ *    and `scriptURL` from the configuration.
+ * 3. The provider uses the `React.useEffect` hook to ensure that the configuration is set up 
+ *    before rendering the children.
+ * 4. While loading the configuration, an `ActivityIndicator` is displayed. Once the SDK is set up, 
+ *    it renders the provided child components.
+ *
+ * ## Properties:
+ *
+ * - **`config`**: The configuration required for PayEngine (type: `IPayEngineConfig`).
+ *   - `publicKey`: The public key for authentication.
+ *   - `scriptURL`: The URL for the PayEngine script.
+ *   - `logLevel`: The log level for debugging (optional).
+ *
+ * - **`children`**: The child components or widgets to be rendered after PayEngine is initialized.
+ *
+ *
+ * @category SecureFields
+ */
 const PayEngineProvider = ({ config, children }: { config: IPayEngineConfig, children: React.ReactNode }) => {
   const [loading, setLoading] = React.useState(true);
 
@@ -22,7 +73,7 @@ const PayEngineProvider = ({ config, children }: { config: IPayEngineConfig, chi
   return <PayEngineContext.Provider value={config}>
     {loading ? <ActivityIndicator /> : children}
   </PayEngineContext.Provider>
-}
+};
 
 export {
   PayEngineContext,

package/src/components/v2/SecureFields/BankAccountView.tsx

@@ -1,6 +1,6 @@
 
 import * as React from 'react';
-import { requireNativeComponent, NativeModules, NativeEventEmitter, ViewProps, findNodeHandle, UIManager, ActivityIndicator, Platform } from 'react-native';
+import { requireNativeComponent, NativeModules, NativeEventEmitter, type ViewProps, findNodeHandle, UIManager, ActivityIndicator, Platform } from 'react-native';
 import type IPEField from './IPEField';
 import type PEBankAccount from './PEBankAccount';
 import type ITokenizationData from './ITokenizationData';
@@ -18,16 +18,123 @@ const RNPEBankAccountViewManager = UIManager[COMPONENT_NAME]
 
 const peEventEmitter = new NativeEventEmitter(RNPEEventEmitter);
 
+/**
+ * Props for the `PEBankAccountView` component.
+ *
+ * Allows optional configuration of additional input fields that can be rendered
+ * alongside the standard bank account fields.
+ *
+ * These fields can be used to collect extra information such as account holder type,
+ * billing address, or custom metadata required by the merchant.
+ *
+ * @category SecureFields
+ *
+ * @example
+ * ```ts
+ * const fields: IPEField[] = [
+ *   {
+ *     name: "accountHolderType",
+ *     type: "text",
+ *     placeholder: "Account Holder Type",
+ *     keyboardType: PEKeyboardType.Alphabet,
+ *     isRequired: false
+ *   }
+ * ];
+ *
+ * <PEBankAccountView additionalFields={fields} />
+ * ```
+ */
 export interface PEBankAccountViewProps {
+  /**
+   * (Optional) A list of additional fields to be displayed in the bank account form.
+   *
+   * These are rendered below the standard account number and routing number fields.
+   */
   additionalFields?: IPEField[];
 }
 
+
+/**
+ * Provides methods to control and interact with the PayEngine Bank Account input view.
+ *
+ * This interface defines methods for submitting bank account details for tokenization
+ * and managing keyboard visibility.
+ *
+ * @category SecureFields
+ */
 export interface PEBankAccountViewMethods {
+  /**
+   * Submits the entered bank account information to PayEngine for tokenization.
+   *
+   * @param data - Optional merchant info and additional metadata.
+   * @returns A promise that resolves to a tokenized bank account object (`PEBankAccount`).
+   *
+   * @example
+   * ```ts
+   * const result = await bankAccountRef.current?.submit({
+   *   merchantId: "merchant_456",
+   *   additionalData: { accountType: "checking" }
+   * });
+   * ```
+   */
   submit: (data: ITokenizationData) => Promise<PEBankAccount>;
+
+  /**
+   * Programmatically displays the keyboard for the bank account input fields.
+   */
   showKeyboard: () => void;
+
+  /**
+   * Programmatically hides the keyboard for the bank account input fields.
+   */
   hideKeyboard: () => void;
 }
 
+
+/**
+ * A secure form widget for entering a customer's bank account information.
+ *
+ * [PEBankAccountView] provides a UI component for securely collecting bank account details.
+ * It does not store data locally and instead tokenizes the information using PayEngine.
+ *
+ * ## Features:
+ * - Securely collects bank account details.
+ * - Supports additional customizable fields.
+ * - Provides methods to show/hide the keyboard.
+ * - Allows tokenizing the entered data for safe storage.
+ *
+ * ## Usage Example:
+ *
+ * ```tsx
+ * const formRef = React.createRef<PEBankAccountViewMethods>();
+ *
+ * return (
+ *   <View style={styles.container}>
+ *     <Text>Welcome to PayEngine React Native SDK example</Text>
+ *     <View style={{ width: '100%' }}>
+ *       <PEBankAccountView ref={formRef} />
+ *       <Button disabled={submitting} onPress={() => createBankAccount()} title="Create Bank Account" />
+ *     </View>
+ *     <ScrollView style={{ flex: 1, width: '100%', backgroundColor: 'lightyellow', padding: 10, marginVertical: 20 }}>
+ *       <Text>{JSON.stringify(secureFieldsResult, null, 4)}</Text>
+ *     </ScrollView>
+ *   </View>
+ * );
+ * ```
+ *
+ * ## How It Works:
+ * 1. Create an instance of [PEBankAccountView], optionally passing additional fields.
+ * 2. Display the form inside your widget tree.
+ * 3. Use [showKeyboard] and [hideKeyboard] to manage input focus.
+ * 4. Call [submit] to securely send the bank account data and receive a token.
+ *
+ * ## Methods:
+ * - **`showKeyboard()`**: Manually shows the on-screen keyboard.
+ * - **`hideKeyboard()`**: Hides the on-screen keyboard.
+ * - **`submit()`**: Submits the entered data and retrieves a tokenized version of the bank account data.
+ *
+ * @category SecureFields
+ */
 export const PEBankAccountView = React.forwardRef<
   PEBankAccountViewMethods,
   PEBankAccountViewProps

package/src/components/v2/SecureFields/CreditCardView.tsx

@@ -1,6 +1,6 @@
 
 import * as React from 'react';
-import { requireNativeComponent, NativeModules, NativeEventEmitter, ViewProps, Platform, findNodeHandle, UIManager, ActivityIndicator } from 'react-native';
+import { requireNativeComponent, NativeModules, NativeEventEmitter, type ViewProps, Platform, findNodeHandle, UIManager, ActivityIndicator } from 'react-native';
 import type IPEField from './IPEField';
 import type PECard from './PECard';
 import type ITokenizationData from './ITokenizationData';
@@ -17,16 +17,133 @@ const RNPECreditCardView = requireNativeComponent<NativePECreditCardViewProps>(C
 const RNPECreditCardViewManager = UIManager[COMPONENT_NAME]
 const peEventEmitter = new NativeEventEmitter(RNPEEventEmitter);
 
+/**
+ * Props for the `PECreditCardView` component.
+ *
+ * Allows optional configuration of additional input fields that can be rendered
+ * alongside the standard credit card fields.
+ *
+ * These fields can be used to collect extra information such as ZIP code, billing address,
+ * or custom metadata required by the merchant.
+ *
+ * @category SecureFields
+ *
+ * @example
+ * ```ts
+ * const fields: IPEField[] = [
+ *   {
+ *     name: "zipCode",
+ *     type: "text",
+ *     placeholder: "ZIP Code",
+ *     keyboardType: PEKeyboardType.Numeric,
+ *     isRequired: true
+ *   }
+ * ];
+ *
+ * <PECreditCardView additionalFields={fields} />
+ * ```
+ */
 export interface PECreditCardViewProps {
+  /**
+   * (Optional) A list of additional fields to be displayed in the credit card form.
+   *
+   * These are rendered below the standard card number, expiry, and CVV fields.
+   */
   additionalFields?: IPEField[];
 }
 
+
+/**
+ * Provides methods to control and interact with the PayEngine Credit Card input view.
+ *
+ * This interface defines methods for submitting credit card details for tokenization
+ * and managing keyboard visibility.
+ *
+ * @category SecureFields
+ */
 export interface PECreditCardViewMethods {
+  /**
+   * Submits the entered credit card information to PayEngine for tokenization.
+   *
+   * @param data - Optional merchant info and additional metadata.
+   * @returns A promise that resolves to a tokenized credit card object (`PECard`).
+   *
+   * @example
+   * ```ts
+   * const result = await creditCardRef.current?.submit({
+   *   merchantId: "merchant_123",
+   *   additionalData: { source: "checkout" }
+   * });
+   * ```
+   */
   submit: (data: ITokenizationData) => Promise<PECard>;
+
+  /**
+   * Programmatically displays the keyboard for the credit card input fields.
+   */
   showKeyboard: () => void;
+
+  /**
+   * Programmatically hides the keyboard for the credit card input fields.
+   */
   hideKeyboard: () => void;
 }
 
+/**
+ * A secure form for entering a customer's credit card information safely.
+ *
+ * [PECreditCardView] provides an interface for users to input their credit card details securely.
+ * It integrates with PayEngine to tokenize the card details and forward them to a PCI-compliant
+ * third party without storing sensitive information locally.
+ *
+ * ## How It Works
+ *
+ * 1. Create an instance of [PECreditCardView], optionally passing additional fields.
+ * 2. Display the form inside your UI.
+ * 3. Once the user enters their details, call [submit] to securely process and retrieve a tokenized version of the card.
+ * 4. Use [showKeyboard] and [hideKeyboard] to manually control the keyboard.
+ *
+ * ## Example Usage
+ *
+ * ```tsx
+ * const formRef = React.createRef<PECreditCardViewMethods>();
+ * 
+ * 
+ * const additionalFields = [
+ *    {
+ *      name: 'address_zip',
+ *      type: 'text',
+ *      placeholder: 'Zip code',
+ *      keyboardType: PEKeyboardType.alphabet,
+ *      isRequired: true,
+ *      pattern: '^(?:\\d{5}(?:-\\d{4})?|[ABCEGHJKLMNPRSTVXY]\\d[A-Z] ?\\d[A-Z]\\d)$'
+ *    }
+ * ]
+ *
+ * return (
+ *   <View style={styles.container}>
+ *     <Text>Welcome to PayEngine React Native SDK example</Text>
+ *     <View style={{ width: '100%' }}>
+ *       <PECreditCardView ref={formRef} additionalFields={additionalFields} />
+ *       <Button disabled={submitting} onPress={() => createCard()} title="Create Card" />
+ *       <Button onPress={() => formRef.current?.showKeyboard()} title="Show keyboard" />
+ *       <Button onPress={() => formRef.current?.hideKeyboard()} title="Hide keyboard" />
+ *     </View>
+ *     <ScrollView style={{ flex: 1, width: '100%', backgroundColor: 'lightyellow', padding: 10, marginVertical: 20 }}>
+ *       <Text>{JSON.stringify(secureFieldsResult, null, 4)}</Text>
+ *     </ScrollView>
+ *   </View>
+ * );
+ * ```
+ *
+ * ## Features:
+ * - Securely collects credit card details.
+ * - Supports additional customizable fields.
+ * - Provides methods to show/hide the keyboard.
+ * - Allows submitting the entered data for tokenization and safe storage.
+ * 
+ * @category SecureFields
+ */
 export const PECreditCardView = React.forwardRef<
   PECreditCardViewMethods,
   PECreditCardViewProps

package/src/components/v2/SecureFields/IPEField.ts

@@ -1,12 +1,67 @@
 import type PEKeyboardType from "./PEKeyboardType";
 
+/**
+ * Represents an input field in the PayEngine system.
+ *
+ * The `IPEField` interface defines a form field with properties such as
+ * its name, type, placeholder, keyboard type, whether it is required, and
+ * an optional validation pattern.
+ *
+ * @category SecureFields
+ *
+ * @example
+ * ```ts
+ * const emailField: IPEField = {
+ *   name: "email",
+ *   type: "text",
+ *   placeholder: "Enter your email",
+ *   keyboardType: PEKeyboardType.Alphabet,
+ *   isRequired: true,
+ *   pattern: "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
+ * };
+ * ```
+ */
 interface IPEField {
+  /**
+   * The unique identifier for the field.
+   *
+   * Typically used as the key when submitting form data.
+   */
   name: string;
+
+  /**
+   * The type of the field (e.g., "text", "password", "email").
+   *
+   * Defines how the field’s value should be interpreted.
+   */
   type: string;
+
+  /**
+   * The placeholder text shown when the field is empty.
+   */
   placeholder: string;
+
+  /**
+   * Specifies the type of keyboard to display for this field.
+   *
+   * Example: `PEKeyboardType.Numeric`, `PEKeyboardType.Alphabet`
+   */
   keyboardType: PEKeyboardType;
+
+  /**
+   * Indicates whether the field is required for form submission.
+   *
+   * If `true`, the field must be filled in with a valid value.
+   */
   isRequired: boolean;
+
+  /**
+   * Optional regular expression used to validate the field's value.
+   *
+   * If omitted, no validation is enforced.
+   */
   pattern?: string;
 }
 
+
 export default IPEField;

package/src/components/v2/SecureFields/ITokenizationData.ts

@@ -1,7 +1,22 @@
+/**
+ * Represents the data used for tokenizing a credit card or bank account.
+ *
+ * This interface allows passing additional metadata or specifying the merchant
+ * for whom the data is being tokenized.
+ *
+ * @category SecureFields
+ */
 interface ITokenizationData {
+  /**
+   * (Optional) The merchant ID on behalf of whom the tokenization is performed.
+   */
   merchantId?: string;
-  additionalData?: { 
-    [key: string]: string 
+
+  /**
+   * (Optional) A key-value map of additional metadata to include in the request.
+   */
+  additionalData?: {
+    [key: string]: string;
   };
 }