Merge pull request #690 from paypal/feature/DTPPCPSDK-3708-add-jsdoc-comments-to-types

feat: add jsdoc comments to v6 public interface types

Author: nbierdeman

.changeset/smooth-dolphins-approve.md

@@ -0,0 +1,5 @@
+---
+"@paypal/paypal-js": patch
+---
+
+feat: add jsdoc comments to v6 public interface types

packages/paypal-js/types/v6/components/paypal-legacy-billing-agreements.d.ts

@@ -7,6 +7,9 @@ import {
     PresentationModeOptionsForPaymentHandler,
 } from "./base-component";
 
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { PayPalPaymentsInstance } from "./paypal-payments.d";
+
 export type OnApproveDataBillingAgreements = {
     billingToken: string;
     payerId?: string;
@@ -40,9 +43,68 @@ export type PayPalLegacyBillingAgreementsSession = Omit<
     ) => Promise<void>;
 };
 
+/**
+ * Interface for PayPal legacy billing agreement functionality.
+ *
+ * @deprecated This interface provides legacy billing agreement methods that should not be used for new implementations.
+ * Use the newer vault setup token approach with {@link PayPalPaymentsInstance.createPayPalSavePaymentSession} instead.
+ *
+ * @interface PayPalLegacyBillingInstance
+ * @description Provides methods for creating billing agreements without requiring an immediate purchase.
+ * This legacy interface allows merchants to set up recurring payment agreements with customers
+ * that can be used for future transactions.
+ *
+ * @example
+ * ```typescript
+ * // Legacy billing agreement setup (deprecated)
+ * const billingAgreementWithoutPurchaseSession = sdkInstance.createPayPalBillingAgreementWithoutPurchase({
+ *   billingToken: 'your-billing-token',
+ *   onApprove: (data) => {
+ *     console.log('Billing agreement approved:', data);
+ *   },
+ *   onCancel: () => {
+ *     console.log('Billing agreement canceled');
+ *   },
+ *   onError: (data) => {
+ *     console.error('Billing agreement error:', data);
+ *   }
+ * });
+ *
+ * // Start the billing agreement flow
+ * await billingAgreementWithoutPurchaseSession.start({
+ *   mode: 'popup'
+ * });
+ * ```
+ *
+ * @see {@link PayPalPaymentsInstance.createPayPalSavePaymentSession} For the recommended modern approach
+ */
 export interface PayPalLegacyBillingInstance {
     /**
+     * Creates a PayPal billing agreement session without requiring an immediate purchase.
+     * This legacy method allows merchants to set up recurring payment agreements with customers
+     * that can be used for future transactions.
+     *
      * @deprecated This method is legacy and should not be used for new implementations.
+     * Use the newer vault setup token approach with {@link PayPalPaymentsInstance.createPayPalSavePaymentSession} instead.
+     *
+     * @param {PayPalLegacyBillingAgreementsSessionOptions} paymentSessionOptions - Configuration options for the billing agreement session
+     * @returns {PayPalLegacyBillingAgreementsSession} - A session object that can be used to start the billing agreement flow
+     *
+     * @example
+     * ```typescript
+     * const billingSession = sdkInstance.createPayPalBillingAgreementWithoutPurchase({
+     *   billingToken: 'your-billing-token',
+     *   onApprove: (data) => {
+     *     console.log('Billing agreement approved:', data);
+     *   },
+     *   onCancel: () => {
+     *     console.log('Billing agreement canceled');
+     *   },
+     *   onError: (data) => {
+     *     console.error('Billing agreement error:', data);
+     *   }
+     * });
+     * ```
      */
     createPayPalBillingAgreementWithoutPurchase: (
         paymentSessionOptions: PayPalLegacyBillingAgreementsSessionOptions,

packages/paypal-js/types/v6/components/paypal-payments.d.ts

@@ -121,16 +121,143 @@ export type PayLaterOneTimePaymentSessionOptions =
 export type PayPalCreditOneTimePaymentSessionOptions =
     PayPalOneTimePaymentSessionOptions;
 
+/**
+ * PayPal Payments Instance interface for creating and managing different types of PayPal payment sessions.
+ *
+ * This interface provides methods to create various PayPal payment flows including:
+ * - One-time payments with standard PayPal
+ * - Save payment methods for future use (vaulting)
+ * - PayPal Pay Later financing options
+ * - PayPal Credit transactions
+ *
+ * Each method returns a payment session object that can be used to initiate the corresponding
+ * payment flow with different presentation modes (popup, modal, redirect, etc.).
+ *
+ * @interface PayPalPaymentsInstance
+ *
+ * @example
+ * ```typescript
+ * // Create a one-time payment session
+ * const paypalCheckout = sdkInstance.createPayPalOneTimePaymentSession({
+ *   onApprove: (data) => console.log('Payment approved:', data),
+ *   onCancel: () => console.log('Payment canceled'),
+ *   onError: (data) => console.error('Payment error:', data)
+ * });
+ *
+ * // Start the payment flow
+ * await paypalCheckout.start({ mode: 'auto' });
+ * ```
+ */
 export interface PayPalPaymentsInstance {
+    /**
+     * Creates a PayPal one-time payment session for processing single payments through PayPal.
+     * This method allows you to configure callback functions to handle different stages
+     * of the PayPal checkout process, including payment approval, shipping address changes,
+     * shipping option changes, cancelation, and errors.
+     *
+     * @param {PayPalOneTimePaymentSessionOptions} paymentSessionOptions - Configuration options for the PayPal payment session
+     * @returns {OneTimePaymentSession} - A session object that can be used to start the payment flow
+     *
+     * @example
+     * ```typescript
+     * const paypalSession = sdkInstance.createPayPalOneTimePaymentSession({
+     *   onApprove: (data) => {
+     *     console.log('PayPal payment approved:', data);
+     *   },
+     *   onShippingAddressChange: (data) => {
+     *     console.log('Shipping address changed:', data);
+     *   },
+     *   onShippingOptionsChange: (data) => {
+     *     console.log('Shipping options changed:', data);
+     *   },
+     *   onCancel: () => {
+     *     console.log('PayPal payment canceled');
+     *   },
+     *   onError: (data) => {
+     *     console.error('PayPal payment error:', data);
+     *   }
+     * });
+     * ```
+     */
     createPayPalOneTimePaymentSession: (
         paymentSessionOptions: PayPalOneTimePaymentSessionOptions,
     ) => OneTimePaymentSession;
+    /**
+     * Creates a PayPal save payment session for storing payment methods for future use.
+     * This method allows you to set up vault payment sessions where customers can save
+     * their PayPal payment method for future transactions without re-entering details.
+     *
+     * @param {SavePaymentSessionOptions} paymentSessionOptions - Configuration options for the save payment session
+     * @returns {SavePaymentSession} - A session object that can be used to start the vault setup flow
+     *
+     * @example
+     * ```typescript
+     * const savePaymentSession = sdkInstance.createPayPalSavePaymentSession({
+     *   vaultSetupToken: 'your-vault-setup-token',
+     *   onApprove: (data) => {
+     *     console.log('Payment method saved:', data);
+     *   },
+     *   onCancel: () => {
+     *     console.log('Save payment canceled');
+     *   },
+     *   onError: (data) => {
+     *     console.error('Save payment error:', data);
+     *   }
+     * });
+     * ```
+     */
     createPayPalSavePaymentSession: (
         paymentSessionOptions: SavePaymentSessionOptions,
     ) => SavePaymentSession;
+    /**
+     * Creates a PayPal Pay Later one-time payment session for buy now, pay later transactions.
+     * This method enables customers to make purchases and pay for them over time through
+     * PayPal's Pay Later financing options. Available in supported countries.
+     *
+     * @param {PayLaterOneTimePaymentSessionOptions} paymentSessionOptions - Configuration options for the Pay Later payment session
+     * @returns {OneTimePaymentSession} - A session object that can be used to start the Pay Later flow
+     *
+     * @example
+     * ```typescript
+     * const payLaterSession = sdkInstance.createPayLaterOneTimePaymentSession({
+     *   onApprove: (data) => {
+     *     console.log('Pay Later payment approved:', data);
+     *   },
+     *   onCancel: () => {
+     *     console.log('Pay Later payment canceled');
+     *   },
+     *   onError: (data) => {
+     *     console.error('Pay Later payment error:', data);
+     *   }
+     * });
+     * ```
+     */
     createPayLaterOneTimePaymentSession: (
         paymentSessionOptions: PayLaterOneTimePaymentSessionOptions,
     ) => OneTimePaymentSession;
+    /**
+     * Creates a PayPal Credit one-time payment session for credit-based transactions.
+     * This method enables customers to make purchases using PayPal Credit, allowing them
+     * to pay over time with financing options. Available in supported countries.
+     *
+     * @param {PayPalCreditOneTimePaymentSessionOptions} paymentSessionOptions - Configuration options for the PayPal Credit payment session
+     * @returns {OneTimePaymentSession} - A session object that can be used to start the PayPal Credit flow
+     *
+     * @example
+     * ```typescript
+     * const creditSession = sdkInstance.createPayPalCreditOneTimePaymentSession({
+     *   onApprove: (data) => {
+     *     console.log('PayPal Credit payment approved:', data);
+     *   },
+     *   onCancel: () => {
+     *     console.log('PayPal Credit payment canceled');
+     *   },
+     *   onError: (data) => {
+     *     console.error('PayPal Credit payment error:', data);
+     *   }
+     * });
+     * ```
+     */
     createPayPalCreditOneTimePaymentSession: (
         paymentSessionOptions: PayPalCreditOneTimePaymentSessionOptions,
     ) => OneTimePaymentSession;

packages/paypal-js/types/v6/components/venmo-payments.d.ts

@@ -26,7 +26,40 @@ export type VenmoOneTimePaymentSession = Omit<BasePaymentSession, "start"> & {
     ) => Promise<void>;
 };
 
+/**
+ * Interface for managing Venmo payment operations within the PayPal SDK.
+ * This interface provides methods for creating and managing Venmo payment sessions,
+ * allowing merchants to integrate Venmo as a payment method in their applications.
+ *
+ * The {@link VenmoPaymentsInstance} enables seamless integration with Venmo's payment flow,
+ * providing a secure and user-friendly way to process payments through the Venmo platform.
+ *
+ * @interface VenmoPaymentsInstance
+ */
 export interface VenmoPaymentsInstance {
+    /**
+     * Creates a Venmo one-time payment session for processing payments through Venmo.
+     * This method allows you to configure callback functions to handle different stages
+     * of the Venmo checkout process, including payment approval, cancelation, and errors.
+     *
+     * @param {VenmoOneTimePaymentSessionOptions} paymentSessionOptions - Configuration options for the Venmo payment session
+     * @returns {VenmoOneTimePaymentSession} - A session object that can be used to start the payment flow
+     *
+     * @example
+     * ```typescript
+     * const venmoSession = sdkInstance.createVenmoOneTimePaymentSession({
+     *   onApprove: (data) => {
+     *     console.log('Venmo payment approved:', data);
+     *   },
+     *   onCancel: () => {
+     *     console.log('Venmo payment canceled');
+     *   },
+     *   onError: (data) => {
+     *     console.error('Venmo payment error:', data);
+     *   }
+     * });
+     * ```
+     */
     createVenmoOneTimePaymentSession: (
         paymentSessionOptions: VenmoOneTimePaymentSessionOptions,
     ) => VenmoOneTimePaymentSession;

packages/paypal-js/types/v6/index.d.ts

@@ -7,6 +7,25 @@ import {
 } from "./components/find-eligible-methods";
 
 export interface PayPalV6Namespace {
+    /**
+     * Creates an SDK instance, which is the first step in an SDK integration. This instance serves as the base layer for all SDK components.
+     *
+     * This is an asynchronous method that initializes the PayPal SDK with the provided
+     * client token and components.
+     *
+     * @param {CreateInstanceOptions} createInstanceOptions - Configuration options for creating the SDK instance
+     * @returns {Promise<SdkInstance<Components[]>>} - A promise that resolves to an SDK instance with methods based on the specified components
+     *
+     * @example
+     * ```typescript
+     * const sdkInstance = await window.paypal.createInstance({
+     *   clientToken: "your-client-token",
+     *   components: ["paypal-payments"],
+     *   locale: "en-US",
+     *   pageType: "checkout"
+     * });
+     * ```
+     */
     createInstance: <T extends readonly [Components, ...Components[]]>(
         createInstanceOptions: CreateInstanceOptions<T>,
     ) => Promise<SdkInstance<T>>;
@@ -81,9 +100,42 @@ export type SdkInstance<T extends readonly [Components, ...Components[]]> =
             : unknown);
 
 export interface BaseInstance {
+    /**
+     * Checks eligibility for specific payment methods.
+     *
+     * This method verifies buyer and merchant eligibility by interacting with PayPal's
+     * public API to determine whether payment methods (such as PayPal or Venmo) can be used.
+     * Use this to conditionally render the appropriate payment buttons on your site.
+     *
+     * @param {FindEligibleMethodsOptions} findEligibleMethodsOptions - Options for checking payment method eligibility
+     * @returns {Promise<EligiblePaymentMethodsOutput>} - A promise that resolves to payment methods eligibility information
+     *
+     * @example
+     * ```typescript
+     * const paymentMethods = await sdkInstance.findEligibleMethods();
+     * const isPayPalEligible = paymentMethods.isEligible("paypal");
+     * if (isPayPalEligible) {
+     *   // Render PayPal button
+     * }
+     * ```
+     */
     findEligibleMethods: (
         findEligibleMethodsOptions: FindEligibleMethodsOptions,
     ) => Promise<EligiblePaymentMethodsOutput>;
+    /**
+     * Updates the locale for the SDK instance.
+     *
+     * This method allows you to dynamically change the locale of the SDK instance
+     * after it has been initialized. The locale should be specified using a BCP-47 code.
+     *
+     * @param {string} locale - The new locale to set, specified as a BCP-47 code (e.g., "en-US", "es-ES")
+     * @returns {void}
+     *
+     * @example
+     * ```typescript
+     * sdkInstance.updateLocale("es-ES");
+     * ```
+     */
     updateLocale: (locale: string) => void;
 }