Merge pull request #700 from paypal/feature/DTPPCPSDK-3867-tsdoc

feat: tsdoc

Author: nbierdeman

.changeset/fuzzy-parrots-invent.md

@@ -0,0 +1,5 @@
+---
+"@paypal/paypal-js": patch
+---
+
+feat: use tsdoc for v6 public interface

package-lock.json

@@ -21,5 +21,14 @@
     },
     "settings": {
         "polyfills": ["Promise", "fetch"]
-    }
+    },
+    "overrides": [
+        {
+            "files": ["types/v6/**/*.d.ts"],
+            "plugins": ["eslint-plugin-tsdoc"],
+            "rules": {
+                "tsdoc/syntax": "warn"
+            }
+        }
+    ]
 }

packages/paypal-js/.eslintrc.json

@@ -69,6 +69,7 @@
         "@typescript-eslint/parser": "6.15.0",
         "@vitest/coverage-v8": "^1.1.0",
         "eslint": "8.56.0",
+        "eslint-plugin-tsdoc": "^0.4.0",
         "filesize": "10.1.0",
         "husky": "8.0.3",
         "jsdom": "^23.0.1",

packages/paypal-js/package.json

@@ -11,7 +11,7 @@ export type OnCompleteData = {
 export type OnErrorData = Error;
 
 /**
- * use Omit<BasePaymentSessionOptions, "onApprove"> to change the arguments for onApprove()
+ * use Omit\<BasePaymentSessionOptions, "onApprove"\> to change the arguments for onApprove()
  */
 export type BasePaymentSessionOptions = {
     onApprove: (data: OnApproveDataOneTimePayments) => Promise<void>;
@@ -47,7 +47,7 @@ export type PresentationModeOptionsForAuto = {
 export type BasePaymentSessionPromise = Promise<{ orderId: string }>;
 
 /**
- * use Omit<BasePaymentSession, "start"> to change the arguments for start()
+ * use Omit\<BasePaymentSession, "start"\> to change the arguments for start()
  */
 export type BasePaymentSession = {
     start: (

packages/paypal-js/types/v6/components/base-component.d.ts

@@ -49,8 +49,8 @@ export type PayPalLegacyBillingAgreementsSession = Omit<
  * @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.
+ * @remarks
+ * 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.
  *
@@ -81,14 +81,16 @@ export type PayPalLegacyBillingAgreementsSession = Omit<
 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
+     * @remarks
+     * This legacy method allows merchants to set up recurring payment agreements with customers
+     * that can be used for future transactions.
+     *
+     * @param paymentSessionOptions - Configuration options for the billing agreement session
+     * @returns A session object that can be used to start the billing agreement flow
      *
      * @example
      * ```typescript

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

@@ -124,6 +124,7 @@ export type PayPalCreditOneTimePaymentSessionOptions =
 /**
  * PayPal Payments Instance interface for creating and managing different types of PayPal payment sessions.
  *
+ * @remarks
  * This interface provides methods to create various PayPal payment flows including:
  * - One-time payments with standard PayPal
  * - Save payment methods for future use (vaulting)
@@ -133,8 +134,6 @@ export type PayPalCreditOneTimePaymentSessionOptions =
  * 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
@@ -151,12 +150,14 @@ export type PayPalCreditOneTimePaymentSessionOptions =
 export interface PayPalPaymentsInstance {
     /**
      * Creates a PayPal one-time payment session for processing single payments through PayPal.
+     *
+     * @remarks
      * 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
+     * @param paymentSessionOptions - Configuration options for the PayPal payment session
+     * @returns A session object that can be used to start the payment flow
      *
      * @example
      * ```typescript
@@ -184,11 +185,13 @@ export interface PayPalPaymentsInstance {
     ) => OneTimePaymentSession;
     /**
      * Creates a PayPal save payment session for storing payment methods for future use.
+     *
+     * @remarks
      * 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
+     * @param paymentSessionOptions - Configuration options for the save payment session
+     * @returns A session object that can be used to start the vault setup flow
      *
      * @example
      * ```typescript
@@ -211,11 +214,13 @@ export interface PayPalPaymentsInstance {
     ) => SavePaymentSession;
     /**
      * Creates a PayPal Pay Later one-time payment session for buy now, pay later transactions.
+     *
+     * @remarks
      * 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
+     * @param paymentSessionOptions - Configuration options for the Pay Later payment session
+     * @returns A session object that can be used to start the Pay Later flow
      *
      * @example
      * ```typescript
@@ -237,11 +242,13 @@ export interface PayPalPaymentsInstance {
     ) => OneTimePaymentSession;
     /**
      * Creates a PayPal Credit one-time payment session for credit-based transactions.
+     *
+     * @remarks
      * 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
+     * @param paymentSessionOptions - Configuration options for the PayPal Credit payment session
+     * @returns A session object that can be used to start the PayPal Credit flow
      *
      * @example
      * ```typescript

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

@@ -28,22 +28,24 @@ export type VenmoOneTimePaymentSession = Omit<BasePaymentSession, "start"> & {
 
 /**
  * Interface for managing Venmo payment operations within the PayPal SDK.
+ *
+ * @remarks
  * 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.
+     *
+     * @remarks
      * 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
+     * @param paymentSessionOptions - Configuration options for the Venmo payment session
+     * @returns A session object that can be used to start the payment flow
      *
      * @example
      * ```typescript

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

@@ -10,11 +10,12 @@ 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.
      *
+     * @remarks
      * 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
+     * @param createInstanceOptions - Configuration options for creating the SDK instance
+     * @returns A promise that resolves to an SDK instance with methods based on the specified components
      *
      * @example
      * ```typescript
@@ -59,6 +60,7 @@ export type CreateInstanceOptions<T extends readonly Components[]> = {
 /**
  * Dynamically typed SDK instance based on the components array provided to createInstance.
  *
+ * @remarks
  * The return type changes based on which components are specified in the components array.
  *
  * **Always includes:**
@@ -103,12 +105,13 @@ export interface BaseInstance {
     /**
      * Checks eligibility for specific payment methods.
      *
+     * @remarks
      * 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
+     * @param findEligibleMethodsOptions - Options for checking payment method eligibility
+     * @returns A promise that resolves to payment methods eligibility information
      *
      * @example
      * ```typescript
@@ -125,11 +128,12 @@ export interface BaseInstance {
     /**
      * Updates the locale for the SDK instance.
      *
+     * @remarks
      * 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}
+     * @param locale - The new locale to set, specified as a BCP-47 code (e.g., "en-US", "es-ES")
+     * @returns void
      *
      * @example
      * ```typescript