react-native-payengine 2.0.16 → 2.0.18-alpha.1

package/src/components/v2/ApplePay/PEApplePayInterfaces.ts

@@ -1,63 +1,276 @@
+/**
+ * A model representing a contact associated with Apple Pay.
+ *
+ * This interface defines the contact details that can be associated with an Apple Pay transaction,
+ * including personal and address information such as the contact's name, address, email, and phone number.
+ * The fields are optional, meaning not all fields need to be provided when creating an instance.
+ *
+ * ## Example Usage:
+ * ```ts
+ * const contact: PEApplePayContact = {
+ *   givenName: 'John',
+ *   familyName: 'Doe',
+ *   addressLines: ['123 Main St', 'Suite 400'],
+ *   locality: 'Anytown',
+ *   administrativeArea: 'CA',
+ *   postalCode: '12345',
+ *   country: 'USA',
+ *   countryCode: 'US',
+ *   subAdministrativeArea: 'SubArea',
+ *   subLocality: 'Locality',
+ *   emailAddress: 'john.doe@example.com',
+ *   phoneNumber: '+1234567890',
+ * };
+ * ```
+ *
+ * @category Apple Pay
+ */
 export interface PEApplePayContact {
+  /**
+   * The given (first) name of the contact.
+   * 
+   * Example: "John"
+   */
   givenName?: string;
+
+  /**
+   * The family (last) name of the contact.
+   * 
+   * Example: "Doe"
+   */
   familyName?: string;
+
+  /**
+   * The contact's address lines, typically representing street addresses.
+   * 
+   * Example: ["123 Main St", "Suite 400"]
+   */
   addressLines?: string[];
+
+  /**
+   * The city or locality of the contact's address.
+   * 
+   * Example: "Anytown"
+   */
   locality?: string;
+
+  /**
+   * The state, province, or administrative area of the contact's address.
+   * 
+   * Example: "CA"
+   */
   administrativeArea?: string;
+
+  /**
+   * The postal code (ZIP code) of the contact's address.
+   * 
+   * Example: "12345"
+   */
   postalCode?: string;
+
+  /**
+   * The full country name of the contact's address.
+   * 
+   * Example: "USA"
+   */
   country?: string;
+
+  /**
+   * The ISO country code (e.g., "US" for the United States).
+   * 
+   * Example: "US"
+   */
   countryCode?: string;
+
+  /**
+   * A more specific administrative area within the main administrative area.
+   * 
+   * Example: "SubArea"
+   */
   subAdministrativeArea?: string;
+
+  /**
+   * A more specific locality within the main locality.
+   * 
+   * Example: "Locality"
+   */
   subLocality?: string;
+
+  /**
+   * The contact's email address.
+   * 
+   * Example: "john.doe@example.com"
+   */
   emailAddress?: string;
+
+  /**
+   * The contact's phone number.
+   * 
+   * Example: "+1234567890"
+   */
   phoneNumber?: string;
 }
 
+
+/**
+ * A model representing the selected Apple Pay payment method.
+ *
+ * This interface provides details about the payment method chosen by the user
+ * during an Apple Pay transaction. It includes the method's display name,
+ * payment network (e.g., Visa, MasterCard), and the type of payment method.
+ *
+ * ## Example Usage:
+ * ```ts
+ * const paymentMethod: PEApplePayPaymentMethod = {
+ *   displayName: 'Visa 1234',
+ *   network: 'Visa',
+ *   type: 'credit', // or 'debit', depending on your enum or string literal type
+ * };
+ * ```
+ *
+ * @category Apple Pay
+ */
 export interface PEApplePayPaymentMethod {
+  /**
+   * A user-facing description of the payment method.
+   * 
+   * This typically includes the card type and last few digits, e.g., "Visa 1234".
+   */
   displayName?: string;
+
+  /**
+   * The network associated with the payment method.
+   * 
+   * Common examples include "Visa", "MasterCard", "Amex", etc.
+   */
   network?: string;
+
+  /**
+   * The type of payment method.
+   * 
+   * This is a required field indicating whether the method is a credit card, debit card, etc.
+   */
   type: PEApplePayPaymentMethodType;
 }
 
+
+/**
+ * Enum representing the different types of payment methods supported by Apple Pay.
+ * Each value corresponds to a specific payment method category.
+ * 
+ * @category Apple Pay
+ */
 export enum PEApplePayPaymentMethodType {
+  /** Unknown payment method type. */
   unknown = 0,
+
+  /** Debit card payment method. */
   debit = 1,
+
+  /** Credit card payment method. */
   credit = 2,
+
+  /** Prepaid card payment method. */
   prepaid = 3,
+
+  /** Store card payment method. */
   store = 4,
+
+  /** Electronic money (e-money) payment method. */
   eMoney = 5
 }
 
+
+/**
+ * Represents a shipping method available during Apple Pay checkout.
+ *
+ * Includes label, amount, and identifier.
+ *
+ * @category Apple Pay
+ */
 export interface PEApplePayShippingMethod {
+  /** Unique identifier for the shipping method. */
   identifier: string;
+
+  /** Cost associated with this shipping method. */
   amount: number;
+
+  /** Display label (e.g., "Express Delivery"). */
   label: string;
 }
 
+/**
+ * Type representing the possible errors that can occur during the Apple Pay
+ * sheet process. This includes issues related to invalid or unserviceable
+ * shipping addresses.
+ * 
+ * * @category Apple Pay
+ */
 export type PEApplePaySheetError =
   | {
-      errorType: PEApplePaySheetErrorType.InvalidShippingAddress;
-      field: PEApplePayInvalidShippingField;
-      message?: string;
-    }
+    /** The error occurs due to an invalid shipping address. */
+    errorType: PEApplePaySheetErrorType.InvalidShippingAddress;
+
+    /** The specific field in the shipping address that caused the error. */
+    field: PEApplePayInvalidShippingField;
+
+    /** An optional message providing more details about the error. */
+    message?: string;
+  }
   | {
-      errorType:
-        | PEApplePaySheetErrorType.UnserviceableShippingAddress
-      message?: string;
-    };
+    /** The error occurs due to an unserviceable shipping address. */
+    errorType: PEApplePaySheetErrorType.UnserviceableShippingAddress;
 
+    /** An optional message providing more details about the error. */
+    message?: string;
+  };
+
+/**
+ * Enum representing the types of errors that can occur during the Apple Pay 
+ * sheet process. These errors typically relate to issues with the shipping 
+ * address provided by the user.
+ * 
+ * @category Apple Pay
+ */
 export enum PEApplePaySheetErrorType {
+  /** The shipping address provided is invalid. */
   InvalidShippingAddress = 'InvalidShippingAddress',
+
+  /** The shipping address provided is unserviceable (e.g., the address cannot be delivered to). */
   UnserviceableShippingAddress = 'UnserviceableShippingAddress',
 }
 
+/**
+ * 
+ * Enum representing the fields of shipping address that may be invalid
+ * during Apple Pay transactions. These values can be used to identify 
+ * which part of the shipping address is incorrect or missing.
+ * 
+ * @category Apple Pay
+ */
 export enum PEApplePayInvalidShippingField {
+  /** The street address is invalid or missing. */
   Street = 'street',
+
+  /** The city is invalid or missing. */
   City = 'city',
+
+  /** The sub-administrative area (e.g., district) is invalid or missing. */
   SubAdministrativeArea = 'subAdministrativeArea',
+
+  /** The state or province is invalid or missing. */
   State = 'state',
+
+  /** The postal code is invalid or missing. */
   PostalCode = 'postalCode',
+
+  /** The country is invalid or missing. */
   Country = 'country',
+
+  /** The country code is invalid or missing. */
   CountryCode = 'countryCode',
+
+  /** The sub-locality (e.g., neighborhood) is invalid or missing. */
   SubLocality = 'subLocality',
 }
+

package/src/components/v2/GooglePay/PEGooglePayAddress.ts

@@ -1,11 +1,49 @@
+/**
+ * Represents a Google Pay address containing structured user information.
+ *
+ * This model holds address details returned from Google Pay, including
+ * name, street address lines, locality, country code, phone number, and postal code.
+ *
+ * ## Example Usage:
+ * ```ts
+ * const address: PEGooglePayAddress = {
+ *   address1: "1600 Amphitheatre Parkway",
+ *   administrativeArea: "CA",
+ *   countryCode: "US",
+ *   locality: "Mountain View",
+ *   name: "John Doe",
+ *   phoneNumber: "+1 123-456-7890",
+ *   postalCode: "94043",
+ * };
+ * ```
+ *
+ * @category Google Pay
+ */
 export interface PEGooglePayAddress {
+  /** The first line of the street address (e.g., "123 Main St"). */
   address1?: string;
+
+  /** The second line of the street address (e.g., apartment, suite, or unit number). */
   address2?: string;
+
+  /** The third line of the street address (if applicable). */
   address3?: string;
+
+  /** The state, province, or region of the address. */
   administrativeArea?: string;
+
+  /** The two-letter country code in ISO 3166-1 alpha-2 format (e.g., "US", "CA"). */
   countryCode?: string;
+
+  /** The city or town of the address. */
   locality?: string;
+
+  /** The full name of the recipient. */
   name?: string;
+
+  /** The phone number associated with the address. */
   phoneNumber?: string;
+
+  /** The ZIP or postal code. */
   postalCode?: string;
-}
+}

package/src/components/v2/GooglePay/PEGooglePayButton.tsx

@@ -16,18 +16,122 @@ interface NativePEGooglePayViewProps extends ViewProps {
 
 const peEventEmitter = new NativeEventEmitter(RNPEEventEmitter);
 
+/**
+ * Props for rendering the Google Pay payment button.
+ *
+ * This interface defines the configuration and callback handlers
+ * used when initiating a Google Pay transaction.
+ *
+ * @category Google Pay
+ */
 export interface PEGooglePayButtonProps extends ViewProps {
+  /**
+   * The payment request containing merchant details, amount, currency,
+   * and optional payment item breakdown.
+   *
+   * This object defines the core transaction that will be processed.
+   */
   paymentRequest: PEPaymentRequest;
-  onTokenDidReturn?: (token: string, metadata?: any, billingAddress?: PEGooglePayAddress, shippingAddress?: PEGooglePayAddress) => void;
+
+  /**
+   * Callback triggered when a Google Pay token is successfully returned.
+   *
+   * @param token - The Google Pay payment token as a string.
+   * @param metadata - Additional transaction metadata (if available).
+   * @param billingAddress - The billing address provided by Google Pay (optional).
+   * @param shippingAddress - The shipping address provided by Google Pay (optional).
+   *
+   * Example usage:
+   * ```ts
+   * onTokenDidReturn: (token, metadata, billingAddress, shippingAddress) => {
+   *   console.log("Token:", token);
+   * }
+   * ```
+   */
+  onTokenDidReturn?: (
+    token: string,
+    metadata?: any,
+    billingAddress?: PEGooglePayAddress,
+    shippingAddress?: PEGooglePayAddress
+  ) => void;
+
+  /**
+   * Callback triggered when the Google Pay sheet is dismissed
+   * without completing the payment.
+   *
+   * Useful for UI updates or restoring state.
+   */
   onPaymentSheetDismissed?: () => void;
-  onPaymentFailed?: (error: Error) => void;
-}
 
-export interface PEGooglePayButtonMethods {
-  
+  /**
+   * Callback triggered when a payment fails during processing.
+   *
+   * @param error - An error object describing the cause of the failure.
+   *
+   * Example:
+   * ```ts
+   * onPaymentFailed: (error) => {
+   *   console.error("Payment failed:", error.message);
+   * }
+   * ```
+   */
+  onPaymentFailed?: (error: Error) => void;
 }
 
-
+/**
+ * Interface for defining methods related to the Google Pay button.
+ *
+ * Currently empty, this interface serves as a placeholder for any
+ * platform-specific Google Pay button methods that may be added in the future.
+ *
+ * @category Google Pay
+ */
+export interface PEGooglePayButtonMethods { }
+
+/**
+ * A React Native component for rendering a Google Pay button.
+ *
+ * This button allows users to initiate a Google Pay transaction using the
+ * provided `paymentRequest`. The component communicates with native code
+ * and emits events through a shared event emitter (`peEventEmitter`) to
+ * notify the JavaScript layer about the payment result.
+ *
+ * ## Example Usage:
+ * ```tsx
+ * const paymentRequest = {
+ *   merchantId: 'your-merchant-id',
+ *   paymentAmount: 10.00,
+ *   paymentItems: [
+ *     { label: 'Test Item', amount: 10.00 }
+ *   ],
+ *   platformOptions: {
+ *     billingAddressRequired: true,
+ *     shippingAddressRequired: true,
+ *   },
+ * };
+ * 
+ * <PEGooglePayButton
+ *   paymentRequest={paymentRequest}
+ *   onPaymentFailed={(error) => {
+ *     console.log("Payment failed", error);
+ *   }}
+ *   onPaymentSheetDismissed={() => {
+ *     console.log("Payment sheet dismissed");
+ *   }}
+ *   onTokenDidReturn={(token, metadata, billingAddress, shippingAddress) => {
+ *     console.log("Payment successful", token, metadata, billingAddress, shippingAddress);
+ *   }}
+ * />
+ * ```
+ *
+ * ## Platform Support:
+ * - **Android only**: On iOS, this component renders a fallback message.
+ *
+ * @param props - See {@link PEGooglePayButtonProps}
+ * @returns A Google Pay button on Android or a fallback message on iOS.
+ *
+ * @category Google Pay
+ */
 export const PEGooglePayButton = React.forwardRef<
   PEGooglePayButtonMethods,
   PEGooglePayButtonProps
@@ -68,10 +172,10 @@ export const PEGooglePayButton = React.forwardRef<
   if (Platform.OS !== 'android') {
     return <Text>Google Pay is not supported on this platform</Text>
   }
-  
+
   return (
-    <RNPEGooglePayButton 
-      style={{ height: 32, width: '100%', ...(props.style as object) }} 
+    <RNPEGooglePayButton
+      style={{ height: 32, width: '100%', ...(props.style as object) }}
       // amount={props.paymentRequest.paymentAmount}
       // merchantId={props.paymentRequest.merchantId} 
       paymentRequest={JSON.stringify({

package/src/components/v2/PEPaymentRequest.ts

@@ -1,22 +1,62 @@
 import type { PEApplePayShippingMethod } from "./ApplePay/PEApplePayInterfaces";
 
-type RNPEPaymentOptions = RNPEGooglePayOptions | RNPEApplePayOptions;
+/**
+ * A union type that represents platform-specific payment options.
+ * 
+ * This can either be `RNPEGooglePayOptions` or `RNPEApplePayOptions`, depending
+ * on the platform.
+ * 
+ */
+export type RNPEPaymentOptions = RNPEGooglePayOptions | RNPEApplePayOptions;
 
+/**
+ * A class representing a payment request containing all necessary transaction details.
+ *
+ * This includes merchant identifier, total payment amount, currency code,
+ * individual payment items, and optional platform-specific configurations
+ * such as Apple Pay or Google Pay options.
+ */
 export class PEPaymentRequest {
+  /**
+   * The unique identifier for the merchant initiating the transaction.
+   */
   merchantId: string;
+
+  /**
+   * The total amount to be charged for the transaction.
+   */
   paymentAmount: number;
+
+  /**
+   * The currency code used for the transaction. Defaults to `'USD'`.
+   */
   currencyCode?: 'USD' | 'CAD' = 'USD';
+
+  /**
+   * List of items representing the breakdown of the transaction.
+   */
   paymentItems?: PESummaryItem[] = [];
+
+  /**
+   * Platform-specific options for customizing the payment experience
+   * (e.g., Apple Pay or Google Pay settings).
+   */
   platformOptions?: RNPEPaymentOptions;
 
+  /**
+   * Constructs a new instance of [PEPaymentRequest].
+   *
+   * @param merchantId - The merchant's unique identifier.
+   * @param paymentAmount - The total transaction amount.
+   * @param currencyCode - The currency code (either `'USD'` or `'CAD'`).
+   * @param paymentItems - An array of individual summary items.
+   * @param platformOptions - Optional platform-specific payment configuration.
+   */
   constructor(
     merchantId: string,
     paymentAmount: number,
     currencyCode: 'USD' | 'CAD' = 'USD',
-    paymentItems: {
-      amount: number;
-      label: string;
-    }[] = [],
+    paymentItems: PESummaryItem[] = [],
     platformOptions?: RNPEPaymentOptions
   ) {
     this.merchantId = merchantId;
@@ -27,23 +67,67 @@ export class PEPaymentRequest {
   }
 }
 
+/**
+ * Represents an individual item in a payment transaction.
+ *
+ * Each item includes a label and an associated amount.
+ *
+ */
 export interface PESummaryItem {
-  amount: number;
+  /** A descriptive label for the payment item (e.g., "Item 1"). */
   label: string;
+
+  /** The monetary amount for this item. */
+  amount: number;
 }
 
+/**
+ * Contact fields that can be requested from the user during Apple Pay transactions.
+ *
+ * These fields specify what customer information (e.g., name, email, address) is required.
+ *
+ * @category Apple Pay
+ */
 export enum RNPEContactField {
+  /** The customer's full name. */
   name = 'name',
+
+  /** The customer's postal address. */
   postalAddress = 'postalAddress',
+
+  /** The customer's email address. */
   emailAddress = 'emailAddress',
+
+  /** The customer's phone number. */
   phoneNumber = 'phoneNumber',
+
+  /** The phonetic spelling of the customer's name. */
   phoneticName = 'phoneticName',
 }
 
 
+/**
+ * Options specific to Apple Pay payment flow.
+ *
+ * Includes configuration for required billing and shipping contact fields,
+ * as well as available shipping methods.
+ *
+ * @category Apple Pay
+ */
 export class RNPEApplePayOptions {
+  /**
+   * Contact fields required for billing (e.g., name, address).
+   */
   requiredBillingContactFields?: RNPEContactField[] = [];
+
+  /**
+   * Contact fields required for shipping (e.g., phone number, address).
+   */
   requiredShippingContactFields?: RNPEContactField[] = [];
+
+  /**
+   * List of available shipping methods shown to the user.
+   */
   shippingMethods?: PEApplePayShippingMethod[] = [];
 
   constructor(params: {
@@ -53,26 +137,80 @@ export class RNPEApplePayOptions {
   }) {
     this.requiredBillingContactFields = params.requiredBillingContactFields;
     this.requiredShippingContactFields = params.requiredShippingContactFields;
-    this.shippingMethods = params.shippingMethods
+    this.shippingMethods = params.shippingMethods;
   }
 }
 
+/**
+ * Represents the billing address parameters for Google Pay in React Native.
+ *
+ * Specifies the address format and whether a phone number is required.
+ *
+ * @category Google Pay
+ */
 export class RNPEGooglePayBillingAddressParameters {
-  format: 'FULL' | 'MIN' = 'FULL'
-  phoneNumberRequired: boolean = false
+  /**
+   * The format of the billing address.
+   * 
+   * - `'FULL'`: Includes street, city, state, and postal code.
+   * - `'MIN'`: Minimal format with limited address details.
+   */
+  format: 'FULL' | 'MIN' = 'FULL';
+
+  /**
+   * Whether a phone number is required in the billing address.
+   */
+  phoneNumberRequired: boolean = false;
 }
 
+/**
+ * Represents the shipping address parameters for Google Pay in React Native.
+ *
+ * Specifies the allowed countries and whether a phone number is required.
+ *
+ * @category Google Pay
+ */
 export class RNPEGooglePayShippingAddressParameters {
-  allowedCountryCodes?: string[] = undefined
-  phoneNumberRequired: boolean = false
+  /**
+   * A list of allowed country codes for shipping (e.g., `["US", "CA"]`).
+   */
+  allowedCountryCodes?: string[] = undefined;
+
+  /**
+   * Whether a phone number is required in the shipping address.
+   */
+  phoneNumberRequired: boolean = false;
 }
 
+/**
+ * A class representing Google Pay-specific payment options for React Native.
+ * 
+ * This includes flags and parameters for requiring billing and shipping addresses.
+ * 
+ * @category Google Pay
+ */
 export class RNPEGooglePayOptions {
+  /** Whether a billing address is required for the transaction. */
   billingAddressRequired: boolean;
-  billingAddressParameters?: any;
+
+  /** Additional parameters for billing address collection (platform-specific). */
+  billingAddressParameters?: RNPEGooglePayBillingAddressParameters;
+
+  /** Whether a shipping address is required for the transaction. */
   shippingAddressRequired: boolean;
-  shippingAddressParameters?: any;
 
+  /** Additional parameters for shipping address collection (platform-specific). */
+  shippingAddressParameters?: RNPEGooglePayShippingAddressParameters;
+
+  /**
+   * Creates a new instance of `RNPEGooglePayOptions`.
+   * 
+   * @param params - The configuration object for Google Pay options.
+   * @param params.billingAddressRequired - Whether billing address is required.
+   * @param params.shippingAddressRequired - Whether shipping address is required.
+   * @param params.billingAddressParameters - Optional parameters for billing address.
+   * @param params.shippingAddressParameters - Optional parameters for shipping address.
+   */
   constructor(params: {
     billingAddressRequired: boolean;
     shippingAddressRequired: boolean;