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

package/lib/typescript/components/v2/ApplePay/PEApplePayInterfaces.d.ts

@@ -1,54 +1,233 @@
+/**
+ * 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 declare 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;
 }
-export declare type PEApplePaySheetError = {
+/**
+ * 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 = {
+    /** 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;
 } | {
+    /** 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 declare 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 declare 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/lib/typescript/components/v2/GooglePay/PEGooglePayAddress.d.ts

@@ -1,11 +1,41 @@
+/**
+ * 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/lib/typescript/components/v2/GooglePay/PEGooglePayButton.d.ts

@@ -2,12 +2,111 @@ import * as React from 'react';
 import { ViewProps } from 'react-native';
 import type { PEPaymentRequest } from '../PEPaymentRequest';
 import type { PEGooglePayAddress } from './PEGooglePayAddress';
+/**
+ * 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;
+    /**
+     * 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;
+    /**
+     * 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 declare const PEGooglePayButton: React.ForwardRefExoticComponent<PEGooglePayButtonProps & React.RefAttributes<PEGooglePayButtonMethods>>;

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

@@ -1,30 +1,103 @@
 import type { PEApplePayShippingMethod } from "./ApplePay/PEApplePayInterfaces";
-declare 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 declare 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';
+    /**
+     * 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;
-    constructor(merchantId: string, paymentAmount: number, currencyCode?: 'USD' | 'CAD', paymentItems?: {
-        amount: number;
-        label: string;
-    }[], 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', paymentItems?: PESummaryItem[], platformOptions?: RNPEPaymentOptions);
 }
+/**
+ * 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 declare 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 declare 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: {
         requiredBillingContactFields: RNPEContactField[];
@@ -32,19 +105,68 @@ export declare class RNPEApplePayOptions {
         shippingMethods: PEApplePayShippingMethod[];
     });
 }
+/**
+ * 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 declare class RNPEGooglePayBillingAddressParameters {
+    /**
+     * The format of the billing address.
+     *
+     * - `'FULL'`: Includes street, city, state, and postal code.
+     * - `'MIN'`: Minimal format with limited address details.
+     */
     format: 'FULL' | 'MIN';
+    /**
+     * Whether a phone number is required in the billing address.
+     */
     phoneNumberRequired: boolean;
 }
+/**
+ * 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 declare class RNPEGooglePayShippingAddressParameters {
+    /**
+     * A list of allowed country codes for shipping (e.g., `["US", "CA"]`).
+     */
     allowedCountryCodes?: string[];
+    /**
+     * Whether a phone number is required in the shipping address.
+     */
     phoneNumberRequired: boolean;
 }
+/**
+ * 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 declare 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;
@@ -52,4 +174,3 @@ export declare class RNPEGooglePayOptions {
         shippingAddressParameters?: RNPEGooglePayShippingAddressParameters;
     });
 }
-export {};