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

package/lib/typescript/components/v2/PayEngineNative.d.ts

@@ -1,12 +1,170 @@
 import { PayProvider } from "../../interfaces";
+/**
+ * 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 createFraudMonitorSession(merchantId: string): Promise<any>;
-    static getBrowserInfo(): Promise<any>;
+    private static emitter;
+    private static isFetchCallbackListenerRegistered;
+    private static fetchAccessTokenCallback;
+    private constructor();
     /**
-     * @deprecated use userCanPay instead
-     * @param merchantId
-     * @returns
+     * 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 isPlatformPaySupported(merchantId: string): Promise<any>;
-    static userCanPay(provider: PayProvider, merchantId: string): Promise<any>;
+    static createFraudMonitorSession(merchantId: string): Promise<string>;
+    /**
+     * Retrieves browser-related information from the native PayEngine SDK.
+     *
+     * @returns A `Promise<string>` containing browser and device details.
+     *
+     */
+    static getBrowserInfo(): Promise<string>;
+    /**
+     * @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 isPlatformPaySupported(merchantId: string): Promise<boolean>;
+    /**
+     * 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 userCanPay(provider: PayProvider, merchantId: string): Promise<boolean>;
+    /**
+     * 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 setFetchAccessTokenCallback(callback: FetchAccessTokenCallback): Promise<void>;
+    /**
+     * 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 logout(merchantId: string): Promise<void>;
 }

package/lib/typescript/components/v2/PayEngineProvider.d.ts

@@ -1,6 +1,57 @@
 import React from "react";
 import type { IPayEngineConfig } from "../../interfaces";
 declare const PayEngineContext: React.Context<IPayEngineConfig | 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
+ */
 declare const PayEngineProvider: ({ config, children }: {
     config: IPayEngineConfig;
     children: React.ReactNode;

package/lib/typescript/components/v2/SecureFields/BankAccountView.d.ts

@@ -2,12 +2,115 @@ import * as React from 'react';
 import type IPEField from './IPEField';
 import type PEBankAccount from './PEBankAccount';
 import type ITokenizationData from './ITokenizationData';
+/**
+ * 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 declare const PEBankAccountView: React.ForwardRefExoticComponent<PEBankAccountViewProps & React.RefAttributes<PEBankAccountViewMethods>>;

package/lib/typescript/components/v2/SecureFields/CreditCardView.d.ts

@@ -2,12 +2,126 @@ import * as React from 'react';
 import type IPEField from './IPEField';
 import type PECard from './PECard';
 import type ITokenizationData from './ITokenizationData';
+/**
+ * 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 declare const PECreditCardView: React.ForwardRefExoticComponent<PECreditCardViewProps & React.RefAttributes<PECreditCardViewMethods>>;

package/lib/typescript/components/v2/SecureFields/IPEField.d.ts

@@ -1,10 +1,59 @@
 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/lib/typescript/components/v2/SecureFields/ITokenizationData.d.ts

@@ -1,5 +1,19 @@
+/**
+ * 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;
+    /**
+     * (Optional) A key-value map of additional metadata to include in the request.
+     */
     additionalData?: {
         [key: string]: string;
     };

package/lib/typescript/components/v2/SecureFields/PEBankAccount.d.ts

@@ -1,10 +1,46 @@
+/**
+ * Represents a bank account stored within PayEngine.
+ *
+ * This interface contains a secure token and account details, ensuring sensitive banking
+ * information is securely managed within the system.
+ *
+ * @category SecureFields
+ */
 interface PEBankAccount {
+    /**
+     * A unique identifier for the bank account.
+     *
+     * This may be used internally to reference the bank account object.
+     */
     id: string;
+    /**
+     * A secure token representing the bank account.
+     *
+     * This token is used for referencing the account in API operations without exposing raw bank details.
+     */
     token: string;
+    /**
+     * The associated bank account details.
+     *
+     * Includes essential information such as the account holder's name,
+     * the routing number, and the last four digits of the account number.
+     */
     account_data: {
+        /**
+         * The first name of the account holder.
+         */
         first_name: string;
+        /**
+         * The last name of the account holder.
+         */
         last_name: string;
+        /**
+         * The bank's routing number.
+         */
         routing_number: string;
+        /**
+         * The last four digits of the bank account number.
+         */
         last_4: string;
     };
 }

package/lib/typescript/components/v2/SecureFields/PECard.d.ts

@@ -1,12 +1,56 @@
+/**
+ * Represents a payment card stored with PayEngine.
+ *
+ * This interface contains a secure token and associated card details,
+ * ensuring sensitive payment information is securely managed within the system.
+ *
+ * @category SecureFields
+ */
 interface PECard {
+    /**
+     * A secure token representing the card.
+     *
+     * This token is used to safely reference the card in API operations without exposing raw card data.
+     */
     token: string;
+    /**
+     * The associated card details.
+     *
+     * Includes essential information such as brand, expiration date,
+     * the last four digits, cardholder name, and optional billing ZIP code.
+     */
     card_data: {
+        /**
+         * A unique identifier for the card.
+         *
+         * This ID is typically used to reference the card object in system operations.
+         */
         id: string;
+        /**
+         * The brand of the card (e.g., Visa, MasterCard).
+         */
         brand: string;
+        /**
+         * The last four digits of the card number.
+         *
+         * Useful for displaying or confirming the card to the user.
+         */
         last_4: string;
+        /**
+         * The expiration year of the card.
+         */
         exp_year: string;
+        /**
+         * The expiration month of the card.
+         */
         exp_month: string;
+        /**
+         * The name of the cardholder.
+         */
         name: string;
+        /**
+         * The ZIP code associated with the card's billing address (optional).
+         */
         address_zip?: string;
     };
 }

package/lib/typescript/components/v2/SecureFields/PEKeyboardType.d.ts

@@ -1,4 +1,19 @@
-declare enum PEKeyboardType {
+/**
+ * Defines the keyboard type for a PayEngine secure input field.
+ *
+ * @remarks
+ * This enum is used in {@link IPEField.keyboardType} to control the keyboard layout
+ * shown to the user based on the input field's context.
+ *
+ * The available keyboard types are:
+ * - {@link PEKeyboardType.alphabet} — Optimized for alphabetic characters.
+ * - {@link PEKeyboardType.number} — Optimized for numeric input.
+ * - {@link PEKeyboardType.phone} — Designed for entering phone numbers.
+ * - {@link PEKeyboardType.normal} — Standard keyboard with alphanumeric characters.
+ *
+ * @category SecureFields
+ */
+export declare enum PEKeyboardType {
     alphabet = "alphabet",
     number = "number",
     phone = "phone",