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

package/lib/typescript/index.d.ts

@@ -1,15 +1,21 @@
+/**
+ * Main Module
+ * @module PayEngine SDK
+ */
 import PayEngine from './components/PayEngine';
 import type { IPayEngineConfig } from './interfaces/index';
 import { PayProvider } from './interfaces/index';
-import { PECreditCardView, PECreditCardViewMethods } from './components/v2/SecureFields/CreditCardView';
-import { PEBankAccountView, PEBankAccountViewMethods } from './components/v2/SecureFields/BankAccountView';
+import type ITokenizationData from './components/v2/SecureFields/ITokenizationData';
+import { PECreditCardView, type PECreditCardViewProps, type PECreditCardViewMethods } from './components/v2/SecureFields/CreditCardView';
+import { PEBankAccountView, type PEBankAccountViewProps, type PEBankAccountViewMethods } from './components/v2/SecureFields/BankAccountView';
 import type IPEField from './components/v2/SecureFields/IPEField';
 import type PECard from './components/v2/SecureFields/PECard';
 import type PEBankAccount from './components/v2/SecureFields/PEBankAccount';
 import { PayEngineProvider } from './components/v2/PayEngineProvider';
 import PayEngineNative from './components/v2/PayEngineNative';
-import { PEApplePayButton } from './components/v2/ApplePay/PEApplePayButton';
-import { PEGooglePayButton } from './components/v2/GooglePay/PEGooglePayButton';
+import { FetchAccessTokenCallback, AccessToken } from './components/v2/PayEngineNative';
+import { PEApplePayButton, type PEApplePayButtonProps, type PEApplePayButtonMethods } from './components/v2/ApplePay/PEApplePayButton';
+import { PEGooglePayButton, type PEGooglePayButtonProps, type PEGooglePayButtonMethods } from './components/v2/GooglePay/PEGooglePayButton';
 import * as PayEngineUtils from './utils/index';
 import PEKeyboardType from './components/v2/SecureFields/PEKeyboardType';
 import type { PEGooglePayAddress } from './components/v2/GooglePay/PEGooglePayAddress';
@@ -17,4 +23,4 @@ import type { PEApplePayContact } from './components/v2/ApplePay/PEApplePayInter
 export * from './components/v2/PEPaymentRequest';
 export * from './components/v2/ApplePay/PEApplePayInterfaces';
 declare const PayEngineStatic: any;
-export { PayEngineStatic, PayEngine, IPayEngineConfig, PayProvider, PayEngineUtils, PayEngineProvider, PayEngineNative, PEKeyboardType, IPEField, PECreditCardView, PECreditCardViewMethods, PECard, PEBankAccountView, PEBankAccountViewMethods, PEBankAccount, PEApplePayButton, PEApplePayContact, PEGooglePayButton, PEGooglePayAddress };
+export { PayEngineStatic, PayEngine, IPayEngineConfig, PayProvider, PayEngineUtils, PayEngineProvider, PayEngineNative, AccessToken, FetchAccessTokenCallback, PEKeyboardType, IPEField, ITokenizationData, PECreditCardView, PECreditCardViewProps, PECreditCardViewMethods, PECard, PEBankAccountView, PEBankAccountViewProps, PEBankAccountViewMethods, PEBankAccount, PEApplePayButton, PEApplePayButtonProps, PEApplePayButtonMethods, PEApplePayContact, PEGooglePayButton, PEGooglePayAddress, PEGooglePayButtonProps, PEGooglePayButtonMethods };

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

@@ -1,10 +1,44 @@
+/**
+ * Represents the configuration settings for PayEngine.
+ *
+ * The [IPayEngineConfig] interface holds essential details such as the public key,
+ * script version, and logging level. It is used to configure the PayEngine integration
+ * for API interactions.
+ *
+ */
 export interface IPayEngineConfig {
+    /**
+     * The public key associated with the PayEngine account.
+     * This key is required for authentication when making API requests.
+     */
     publicKey: string;
+    /**
+     * The version of the PayEngine integration.
+     * If provided, this specifies the version of the script or API being used.
+     */
     version?: string;
+    /**
+     * The script URL for loading the PayEngine JavaScript library.
+     * If provided, this URL is used instead of the default script URL.
+     */
     scriptURL?: string;
+    /**
+     * The log level for debugging.
+     * Higher values enable more detailed logging.
+     */
     logLevel?: number;
 }
+/**
+ * Enum representing supported payment providers.
+ *
+ * @remarks
+ * This enum specifies the available payment providers supported by the PayEngine SDK.
+ * It is used to check which payment method (Apple Pay or Google Pay) is available for use.
+ *
+ * @enum {string}
+ * @category PayEngine
+ */
 export declare enum PayProvider {
-    googlePay = 0,
+    googlePay = 0,// Google Pay payment provider.
     applePay = 1
 }

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

@@ -1,11 +1,32 @@
 import type { IPayEngineConfig } from '../interfaces/index';
+/**
+ * Custom error thrown when an obsolete method is called.
+ *
+ * The `PEDeprecationError` indicates that the method being used is deprecated,
+ * and the user should check the package README for updated usage.
+ */
 export declare class PEDeprecationError extends Error {
     constructor();
 }
+/**
+ * @private
+ */
 export declare const getHttpHeaders: (config: IPayEngineConfig) => {
     Authorization: string;
 };
+/**
+ * @private
+ */
 export declare const getBaseURL: (config: IPayEngineConfig) => string;
+/**
+ * @private
+ */
 export declare const createHttpClient: (config: IPayEngineConfig) => import("axios").AxiosInstance;
+/**
+ * @private
+ */
 export declare function getScriptURL(config: IPayEngineConfig): string;
+/**
+ * @private
+ */
 export declare const debuggingScript = "\nconst consoleLog = (type, ...log) => window.ReactNativeWebView.postMessage(JSON.stringify({'type': 'Console', 'data': {'type': type, 'log': log}}));\nconsole = {\n    log: (...log) => consoleLog('log', ...log),\n    debug: (...log) => consoleLog('debug', ...log),\n    info: (...log) => consoleLog('info', ...log),\n    warn: (...log) => consoleLog('warn', ...log),\n    error: (...log) => consoleLog('error', ...log),\n    verbose: (...log) => consoleLog('verbose', ...log),\n};\n\nconst dispatchEvent_original = EventTarget.prototype.dispatchEvent;\nfunction dispatchEvent(event) {\n    if (event.type && !event.type.startsWith('react')) {\n      ReactNativeWebView.postMessage(JSON.stringify({\n        type: 'PayEngine',\n        event: {\n          type: event.type,\n          detail: event.detail\n        }\n      }))\n    }\n}\nEventTarget.prototype.dispatchEvent = dispatchEvent;\n";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-payengine",
-  "version": "2.0.17",
+  "version": "2.0.18-alpha.2",
   "description": "PayEngine SDK for React Native",
   "main": "lib/commonjs/index",
   "module": "lib/module/index",
@@ -32,7 +32,9 @@
     "update-release": "release-it --no-increment",
     "beta": "release-it major --preRelease=beta",
     "example": "yarn --cwd example",
-    "bootstrap": "yarn example && yarn && yarn example pods"
+    "bootstrap": "yarn example && yarn && yarn example pods",
+    "docs": "typedoc src/index.tsx --out docs-temp",
+    "docs-watch": "typedoc src/index.tsx --watch --out docs-temp"
   },
   "keywords": [
     "react-native",
@@ -65,7 +67,8 @@
     "react-native": "0.68.2",
     "react-native-builder-bob": "^0.18.3",
     "release-it": "^15.0.0",
-    "typescript": "^4.5.2"
+    "typedoc": "^0.28.1",
+    "typescript": "^5.8.2"
   },
   "resolutions": {
     "@types/react": "17.0.21"

package/src/components/PayEngine.tsx

@@ -1,7 +1,7 @@
 import React from 'react';
 import { Text } from 'react-native';
 
-const PayEngine = () => {
+const PayEngine = (_props: any) => {
   return <Text>Obsolete. Please check out the package readme</Text>;
 };
 

package/src/components/v2/ApplePay/PEApplePayButton.tsx

@@ -63,40 +63,94 @@ interface NativePEApplePayViewProps extends ViewProps {
   }) => void;
 }
 
+/**
+ * Props for the Apple Pay button component.
+ *
+ * This interface defines the properties you can pass to the Apple Pay button,
+ * including the payment request and various event callbacks triggered throughout
+ * the Apple Pay flow.
+ *
+ * @category Apple Pay
+ */
 export interface PEApplePayButtonProps extends ViewProps {
+  /**
+   * The payment request containing transaction details such as the total amount,
+   * currency, supported networks, and required contact fields.
+   */
   paymentRequest: PEPaymentRequest;
+
+  /**
+   * Callback triggered when the Apple Pay token is successfully generated.
+   *
+   * @param token - A string representing the Apple Pay payment token.
+   * @param metadata - Optional metadata related to the transaction.
+   * @param billingContact - The billing contact information (if available).
+   * @param shippingContact - The shipping contact information (if available).
+   *
+   * Example:
+   * ```ts
+   * onTokenDidReturn: (token, metadata, billing, shipping) => {
+   *   console.log('Token:', token);
+   *   console.log('Billing contact:', billing?.givenName);
+   *   console.log('Shipping contact:', shipping?.givenName);
+   * }
+   * ```
+   */
   onTokenDidReturn?: (
     token: string,
     metadata?: any,
     billingContact?: PEApplePayContact,
     shippingContact?: PEApplePayContact
   ) => void;
+
+  /**
+   * Callback triggered when the Apple Pay sheet is dismissed,
+   * either by completing the payment or canceling it.
+   */
   onPaymentSheetDismissed?: () => void;
+
+  /**
+   * Callback triggered when the Apple Pay process fails.
+   *
+   * @param error - The error that occurred during the payment flow.
+   */
   onPaymentFailed?: (error: Error) => void;
+
   /**
-   * This callback is triggered whenever the payment method changes in the Apple Pay sheet.
-   * You MUST update the Apple Pay sheet in your callback using the updatePaymentSheet function,
-   * otherwise the Apple Pay sheet will hang and the payment flow will automatically cancel.
+   * Callback triggered when the user selects or changes the payment method
+   * within the Apple Pay sheet.
+   *
+   * You MUST call `updatePaymentSheet` in response to this callback to update
+   * the Apple Pay sheet. Failing to do so will cause the sheet to hang
+   * and the transaction will automatically cancel.
    */
   onPaymentMethodSelected?: (event: {
     nativeEvent: {
       paymentMethod: PEApplePayPaymentMethod;
     };
   }) => void;
+
   /**
-   * This callback is triggered whenever the user selects a shipping method in the Apple Pay sheet.
-   * You MUST update the Apple Pay sheet in your callback using the updatePaymentSheet function,
-   * otherwise the Apple Pay sheet will hang and the payment flow will automatically cancel.
+   * Callback triggered when the user selects a shipping contact
+   * (e.g., their shipping address) within the Apple Pay sheet.
+   *
+   * You MUST call `updatePaymentSheet` in response to this callback to update
+   * shipping methods, summary items, or errors. Failure to do so will hang the
+   * sheet and cancel the transaction automatically.
    */
   onShippingContactSelected?: (event: {
     nativeEvent: {
       contact: PEApplePayContact;
     };
   }) => void;
+
   /**
-   * This callback is triggered whenever the user selects a shipping contact in the Apple Pay sheet.
-   * You MUST update the Apple Pay sheet in your callback using the updatePaymentSheet function,
-   * otherwise the Apple Pay sheet will hang and the payment flow will automatically cancel.
+   * Callback triggered when the user selects a shipping method (e.g., standard or express)
+   * in the Apple Pay sheet.
+   *
+   * You MUST call `updatePaymentSheet` in response to this callback to reflect
+   * any changes in pricing or available options. If you don't, the Apple Pay sheet
+   * will hang and the payment will be canceled.
    */
   onShippingMethodSelected?: (event: {
     nativeEvent: {
@@ -105,11 +159,46 @@ export interface PEApplePayButtonProps extends ViewProps {
   }) => void;
 }
 
+
+/**
+ * Exposes imperative methods for controlling the Apple Pay payment sheet.
+ *
+ * This interface is typically used via a `ref` to programmatically update
+ * the state of the Apple Pay sheet after certain user interactions.
+ *
+ * Specifically, the `updatePaymentSheet` method should be called in response to
+ * any of the following events:
+ * - `onPaymentMethodSelected`
+ * - `onShippingContactSelected`
+ * - `onShippingMethodSelected`
+ *
+ * @category Apple Pay
+ */
 export interface PEApplePayButtonMethods {
   /**
-   * This method must be called after either onPaymentMethodSelected, onShippingContactSelected or
-   * onShippingMethodSelected callbacks are triggered.
-   * `shippingMethods` and `errors` are only applicable for onShippingContactSelected callback
+   * Updates the Apple Pay payment sheet with new summary items, shipping methods, and validation errors.
+   *
+   * This method should be called in response to user selections made on the Apple Pay sheet,
+   * such as selecting a new payment method, shipping contact, or shipping method.
+   *
+   * ### Parameters:
+   * - `summaryItems`: The updated list of items summarizing the total payment amount (e.g., subtotal, tax, total).
+   * - `shippingMethods`: A list of available shipping methods based on the selected shipping contact.
+   *   - Only applicable when the `onShippingContactSelected` callback is triggered.
+   * - `errors`: A list of validation errors (e.g., invalid address or unsupported shipping region).
+   *   - Also only applicable for `onShippingContactSelected`.
+   *
+   * ### Returns:
+   * - A `Promise<boolean>` indicating whether the update was successful.
+   *
+   * ### Example:
+   * ```ts
+   * await ref.current?.updatePaymentSheet(
+   *   updatedSummaryItems,
+   *   availableShippingMethods,
+   *   validationErrors
+   * );
+   * ```
    */
   updatePaymentSheet: (
     summaryItems: PESummaryItem[],
@@ -118,6 +207,130 @@ export interface PEApplePayButtonMethods {
   ) => Promise<boolean>;
 }
 
+
+/**
+ * A React component for initiating an Apple Pay transaction.
+ *
+ * This button wraps the Apple Pay experience, including presenting the Apple Pay sheet,
+ * handling user interactions, processing the payment, and managing callbacks such as
+ * payment success, failure, and contact/method selection.
+ *
+ * It exposes imperative methods via `ref` to allow control over the Apple Pay sheet,
+ * such as updating summary items or shipping options in response to user input.
+ *
+ * ## Example Usage:
+ *
+ * ```tsx
+ * const paymentRequest = {
+ *   merchantId: "merchant.com.example",
+ *   countryCode: "US",
+ *   currencyCode: "USD",
+ *   paymentAmount: 10.00,
+ *   paymentSummaryItems: [
+ *     { label: "Test Item", amount: "10.00" }
+ *   ],
+ *   requiredShippingContactFields: ["name", "postalAddress"]
+ * };
+ *
+ * <PEApplePayButton
+ *   paymentRequest={paymentRequest}
+ *
+ *   // Triggered when payment fails
+ *   onPaymentFailed={(error) => console.error("Payment failed:", error)}
+ *
+ *   // Triggered when Apple Pay sheet is dismissed by the user
+ *   onPaymentSheetDismissed={() => console.log("Payment sheet dismissed")}
+ *
+ *   // Triggered when a valid token is generated after successful Apple Pay authorization
+ *   onTokenDidReturn={(token, metadata, billingContact, shippingContact) => {
+ *     console.log('Apple Pay token:', token, metadata, billingContact, shippingContact);
+ *     // TODO: Send token to your server for processing
+ *     purchaseWithToken(token);
+ *   }}
+ *
+ *   // Triggered when user selects or updates their shipping contact info
+ *   onShippingContactSelected={(event) => {
+ *     console.log('onShippingContactSelected', event.nativeEvent);
+ *
+ *     if (!event.nativeEvent.contact.postalCode) {
+ *       // Invalid postal code — update Apple Pay sheet with an error
+ *       buttonRef?.current?.updatePaymentSheet([], [], [{
+ *         errorType: PEApplePaySheetErrorType.InvalidShippingAddress,
+ *         field: PEApplePayInvalidShippingField.PostalCode,
+ *         message: 'Please update postal code to continue'
+ *       }]);
+ *     } else {
+ *       // Provide updated shipping methods if contact is valid
+ *       buttonRef?.current?.updatePaymentSheet([], [
+ *         {
+ *           identifier: 'new-shipping1',
+ *           label: 'Updated shipping 1',
+ *           amount: 3.99
+ *         },
+ *         {
+ *           identifier: 'new-shipping2',
+ *           label: 'Updated shipping 2',
+ *           amount: 5.99
+ *         }
+ *       ], []);
+ *     }
+ *   }}
+ *
+ *   // Triggered when user selects a shipping method
+ *   onShippingMethodSelected={(event) => {
+ *     console.log('onShippingMethodSelected', event.nativeEvent);
+ *
+ *     const shippingFee = event.nativeEvent.shippingMethod.amount;
+ *     const items = [
+ *       {
+ *         label: 'Product price',
+ *         amount: paymentRequest.paymentAmount
+ *       },
+ *       ...(shippingFee > 0 ? [{
+ *         label: 'Shipping Fee',
+ *         amount: shippingFee
+ *       }] : []),
+ *       {
+ *         label: 'Total',
+ *         amount: paymentRequest.paymentAmount + shippingFee
+ *       }
+ *     ];
+ *
+ *     buttonRef?.current?.updatePaymentSheet(items, [], []);
+ *   }}
+ *
+ *   // Triggered when user selects a payment method (e.g., credit, debit)
+ *   onPaymentMethodSelected={(event) => {
+ *     console.log('onPaymentMethodSelected', event.nativeEvent);
+ *
+ *     const isCredit = event.nativeEvent.paymentMethod.type === PEApplePayPaymentMethodType.credit;
+ *     const items = [
+ *       {
+ *         label: 'Product price',
+ *         amount: paymentRequest.paymentAmount
+ *       },
+ *       ...(isCredit ? [{
+ *         label: 'Credit discount',
+ *         amount: 10
+ *       }] : []),
+ *       {
+ *         label: 'Total',
+ *         amount: paymentRequest.paymentAmount - (isCredit ? 1.00 : 0.00)
+ *       }
+ *     ];
+ *
+ *     buttonRef?.current?.updatePaymentSheet(items, [], []);
+ *   }}
+ *
+ *   ref={applePayRef}
+ * />
+ * ```
+ *
+ * @param props - The props for configuring the Apple Pay button behavior.
+ * @param ref - A ref to access Apple Pay sheet update methods imperatively.
+ *
+ * @category Apple Pay
+ */
 export const PEApplePayButton = React.forwardRef<
   PEApplePayButtonMethods,
   PEApplePayButtonProps