add jsdoc comments to interfaces

Author: nbierdeman

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

@@ -43,6 +43,41 @@ 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.

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

@@ -121,6 +121,33 @@ 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.

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

@@ -26,6 +26,16 @@ 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.