diff --git a/.changeset/smooth-dolphins-approve.md b/.changeset/smooth-dolphins-approve.md new file mode 100644 index 00000000..9106af37 --- /dev/null +++ b/.changeset/smooth-dolphins-approve.md @@ -0,0 +1,5 @@ +--- +"@paypal/paypal-js": patch +--- + +feat: add jsdoc comments to v6 public interface types diff --git a/packages/paypal-js/types/v6/components/paypal-legacy-billing-agreements.d.ts b/packages/paypal-js/types/v6/components/paypal-legacy-billing-agreements.d.ts index 516ac64d..3dcd0ee1 100644 --- a/packages/paypal-js/types/v6/components/paypal-legacy-billing-agreements.d.ts +++ b/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; }; +/** + * 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, diff --git a/packages/paypal-js/types/v6/components/paypal-payments.d.ts b/packages/paypal-js/types/v6/components/paypal-payments.d.ts index 38c9e87c..2477cadf 100644 --- a/packages/paypal-js/types/v6/components/paypal-payments.d.ts +++ b/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; diff --git a/packages/paypal-js/types/v6/components/venmo-payments.d.ts b/packages/paypal-js/types/v6/components/venmo-payments.d.ts index d425aea0..09986ab5 100644 --- a/packages/paypal-js/types/v6/components/venmo-payments.d.ts +++ b/packages/paypal-js/types/v6/components/venmo-payments.d.ts @@ -26,7 +26,40 @@ export type VenmoOneTimePaymentSession = Omit & { ) => Promise; }; +/** + * 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; diff --git a/packages/paypal-js/types/v6/index.d.ts b/packages/paypal-js/types/v6/index.d.ts index 0cd7bd91..f3fecef5 100644 --- a/packages/paypal-js/types/v6/index.d.ts +++ b/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>} - 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: ( createInstanceOptions: CreateInstanceOptions, ) => Promise>; @@ -81,9 +100,42 @@ export type SdkInstance = : 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} - 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; + /** + * 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; }