chore(docs): Add jsdoc/tsdoc to methods

client/components/fastlane/html/src/fastlane.js

@@ -1,3 +1,10 @@
+/**
+ * Initializes the Fastlane SDK, sets up event listeners for email submission,
+ * handles authentication flow, and renders the appropriate user experience.
+ * @async
+ * @function
+ * @returns {Promise<void>}
+ */
 async function setupFastlaneSdk() {
   fastlane.setLocale("en_us");
 
@@ -41,6 +48,17 @@ async function setupFastlaneSdk() {
   });
 }
 
+/**
+ * Displays the shipping address information in the UI.
+ * @param {Object} shippingAddress - The shipping address object.
+ * @param {Object} shippingAddress.name - Name object containing fullName.
+ * @param {string} shippingAddress.name.fullName - Full name of the recipient.
+ * @param {Object} shippingAddress.address - Address object.
+ * @param {string} shippingAddress.address.addressLine1 - Street address.
+ * @param {string} shippingAddress.address.adminArea2 - City or locality.
+ * @param {string} shippingAddress.address.adminArea1 - State or region.
+ * @param {string} shippingAddress.address.postalCode - Postal or ZIP code.
+ */
 function setShippingAddressDisplay(shippingAddress) {
   const {
     name: { fullName },
@@ -53,6 +71,15 @@ function setShippingAddressDisplay(shippingAddress) {
   shippingDisplayContainer.innerHTML = `<b>${fullName}</b><br><b>${adminArea2}</b><br><b>${adminArea1}</b><br><b>${postalCode}</b>`;
 }
 
+/**
+ * Renders the Fastlane member checkout experience, including shipping address,
+ * payment component, and order submission.
+ * @async
+ * @function
+ * @param {Object} profileData - The user's profile data.
+ * @param {Object} profileData.shippingAddress - The user's shipping address.
+ * @returns {Promise<void>}
+ */
 async function renderFastlaneMemberExperience(profileData) {
   if (profileData.shippingAddress) {
     setShippingAddressDisplay(profileData.shippingAddress);
@@ -97,6 +124,13 @@ async function renderFastlaneMemberExperience(profileData) {
   }
 }
 
+/**
+ * Renders the Fastlane guest checkout experience, including payment component
+ * and order submission.
+ * @async
+ * @function
+ * @returns {Promise<void>}
+ */
 async function renderFastlaneGuestExperience() {
   const cardTestingInfo = document.getElementById("card-testing-info");
   cardTestingInfo.removeAttribute("hidden");
@@ -119,6 +153,13 @@ async function renderFastlaneGuestExperience() {
   });
 }
 
+/**
+ * Creates an order by sending a request to the server with the payment token.
+ * @async
+ * @function
+ * @param {string} paymentToken - The payment token from Fastlane.
+ * @returns {Promise<Object>} The response from the order creation API.
+ */
 async function createOrder(paymentToken) {
   const response = await fetch("/paypal-api/checkout/orders/create", {
     method: "POST",

client/components/fastlane/html/src/fastlaneSdkComponent.js

@@ -1,4 +1,16 @@
+/**
+ * Global variable to hold the Fastlane SDK instance.
+ * @type {Object}
+ */
 let fastlane;
+
+/**
+ * Initializes the PayPal Web SDK, creates a Fastlane instance,
+ * and sets up the Fastlane SDK experience.
+ * @async
+ * @function
+ * @returns {Promise<void>}
+ */
 async function onPayPalWebSdkLoaded() {
   const clientToken = await getBrowserSafeClientToken();
 
@@ -13,6 +25,12 @@ async function onPayPalWebSdkLoaded() {
   setupFastlaneSdk();
 }
 
+/**
+ * Fetches a browser-safe client token from the server for PayPal SDK initialization.
+ * @async
+ * @function
+ * @returns {Promise<string>} The browser-safe client access token.
+ */
 async function getBrowserSafeClientToken() {
   const response = await fetch("/paypal-api/auth/browser-safe-client-token", {
     method: "GET",

client/components/googlePayPayments/oneTimePayment/html/src/app.js

@@ -1,3 +1,10 @@
+/**
+ * Initializes the PayPal Web SDK, creates a Google Pay Payments instance,
+ * and sets up the Google Pay button.
+ * @async
+ * @function
+ * @returns {Promise<void>}
+ */
 async function onPayPalWebSdkLoaded() {
   try {
     const clientToken = await getBrowserSafeClientToken();
@@ -13,6 +20,12 @@ async function onPayPalWebSdkLoaded() {
   }
 }
 
+/**
+ * Generates the PayPal order payload for a given purchase amount.
+ * @function
+ * @param {string} purchaseAmount - The total purchase amount.
+ * @returns {Object} The PayPal order payload.
+ */
 function getPayPalOrderPayload(purchaseAmount) {
   return {
     intent: "CAPTURE",
@@ -42,6 +55,13 @@ function getPayPalOrderPayload(purchaseAmount) {
   };
 }
 
+/**
+ * Generates the Google Pay transaction info object.
+ * @function
+ * @param {string} purchaseAmount - The total purchase amount.
+ * @param {string} countryCode - The country code (e.g., "US").
+ * @returns {Object} The Google Pay transaction info.
+ */
 function getGoogleTransactionInfo(purchaseAmount, countryCode) {
   const totalAmount = parseFloat(purchaseAmount);
   const subtotal = (totalAmount * 0.9).toFixed(2);
@@ -68,6 +88,14 @@ function getGoogleTransactionInfo(purchaseAmount, countryCode) {
   };
 }
 
+/**
+ * Builds the Google PaymentDataRequest object for Google Pay API.
+ * @async
+ * @function
+ * @param {string} purchaseAmount - The total purchase amount.
+ * @param {Object} googlePayConfig - The Google Pay configuration object.
+ * @returns {Promise<Object>} The PaymentDataRequest object.
+ */
 async function getGooglePaymentDataRequest(purchaseAmount, googlePayConfig) {
   const {
     allowedPaymentMethods,
@@ -95,6 +123,16 @@ async function getGooglePaymentDataRequest(purchaseAmount, googlePayConfig) {
   return paymentDataRequest;
 }
 
+/**
+ * Handles the payment authorization callback from Google Pay.
+ * Creates and confirms the PayPal order, and captures it if possible.
+ * @async
+ * @function
+ * @param {string} purchaseAmount - The total purchase amount.
+ * @param {Object} paymentData - The payment data from Google Pay.
+ * @param {Object} googlePaySession - The Google Pay session instance.
+ * @returns {Promise<Object>} The transaction state result.
+ */
 async function onPaymentAuthorized(
   purchaseAmount,
   paymentData,
@@ -126,6 +164,16 @@ async function onPaymentAuthorized(
   }
 }
 
+/**
+ * Handles the Google Pay button click event.
+ * Loads the payment data request using the PaymentsClient.
+ * @async
+ * @function
+ * @param {string} purchaseAmount - The total purchase amount.
+ * @param {Object} paymentsClient - The Google PaymentsClient instance.
+ * @param {Object} googlePayConfig - The Google Pay configuration object.
+ * @returns {Promise<void>}
+ */
 async function onGooglePayButtonClick(
   purchaseAmount,
   paymentsClient,
@@ -143,6 +191,13 @@ async function onGooglePayButtonClick(
   }
 }
 
+/**
+ * Sets up the Google Pay button and session, and appends the button to the DOM if ready.
+ * @async
+ * @function
+ * @param {Object} sdkInstance - The PayPal SDK instance.
+ * @returns {Promise<void>}
+ */
 async function setupGooglePayButton(sdkInstance) {
   const googlePaySession = sdkInstance.createGooglePayOneTimePaymentSession();
   const purchaseAmount = "10.00";
@@ -181,6 +236,12 @@ async function setupGooglePayButton(sdkInstance) {
   }
 }
 
+/**
+ * Fetches a browser-safe client token from the server for PayPal SDK initialization.
+ * @async
+ * @function
+ * @returns {Promise<string>} The browser-safe client access token.
+ */
 async function getBrowserSafeClientToken() {
   const response = await fetch("/paypal-api/auth/browser-safe-client-token", {
     method: "GET",
@@ -193,6 +254,13 @@ async function getBrowserSafeClientToken() {
   return accessToken;
 }
 
+/**
+ * Creates a PayPal order by sending the order payload to the server.
+ * @async
+ * @function
+ * @param {Object} orderPayload - The PayPal order payload.
+ * @returns {Promise<string>} The created order ID.
+ */
 async function createOrder(orderPayload) {
   const response = await fetch("/paypal-api/checkout/orders/create", {
     method: "POST",
@@ -206,6 +274,14 @@ async function createOrder(orderPayload) {
   return id;
 }
 
+/**
+ * Captures a PayPal order by order ID.
+ * @async
+ * @function
+ * @param {Object} params - The parameters object.
+ * @param {string} params.orderId - The PayPal order ID.
+ * @returns {Promise<Object>} The capture order response data.
+ */
 async function captureOrder({ orderId }) {
   const response = await fetch(
     `/paypal-api/checkout/orders/${orderId}/capture`,

client/components/paypalMessages/html/src/advanced/app.js

@@ -1,3 +1,10 @@
+/**
+ * Initializes the PayPal Web SDK, creates a PayPal Messages instance,
+ * and renders the PayPal message on the page.
+ * @async
+ * @function
+ * @returns {Promise<void>}
+ */
 async function onPayPalWebSdkLoaded() {
   try {
     const clientToken = await getBrowserSafeClientToken();
@@ -11,6 +18,12 @@ async function onPayPalWebSdkLoaded() {
   }
 }
 
+/**
+ * Fetches a browser-safe client token from the server for PayPal SDK initialization.
+ * @async
+ * @function
+ * @returns {Promise<string>} The browser-safe client access token.
+ */
 async function getBrowserSafeClientToken() {
   const response = await fetch("/paypal-api/auth/browser-safe-client-token", {
     method: "GET",
@@ -23,6 +36,13 @@ async function getBrowserSafeClientToken() {
   return accessToken;
 }
 
+/**
+ * Creates and renders a PayPal message using the SDK instance.
+ * @async
+ * @function
+ * @param {Object} sdkInstance - The PayPal SDK instance.
+ * @returns {Promise<Object>} The fetched message content.
+ */
 async function createMessage(sdkInstance) {
   const messagesInstance = sdkInstance.createPayPalMessages();
   const messageElement = document.querySelector("#paypal-message");

client/components/paypalMessages/html/src/recommended/app.js

@@ -1,3 +1,10 @@
+/**
+ * Initializes the PayPal Web SDK, creates a PayPal Messages instance,
+ * and sets up the product interaction event listener.
+ * @async
+ * @function
+ * @returns {Promise<void>}
+ */
 async function onPayPalWebSdkLoaded() {
   try {
     const clientToken = await getBrowserSafeClientToken();
@@ -12,6 +19,12 @@ async function onPayPalWebSdkLoaded() {
   }
 }
 
+/**
+ * Fetches a browser-safe client token from the server for PayPal SDK initialization.
+ * @async
+ * @function
+ * @returns {Promise<string>} The browser-safe client access token.
+ */
 async function getBrowserSafeClientToken() {
   const response = await fetch("/paypal-api/auth/browser-safe-client-token", {
     method: "GET",
@@ -24,7 +37,12 @@ async function getBrowserSafeClientToken() {
   return accessToken;
 }
 
-// basic example product interaction
+/**
+ * Adds an event listener to update the displayed quantity, total amount,
+ * and PayPal message amount when the product quantity input changes.
+ * @function
+ * @returns {void}
+ */
 function addAmountEventListener() {
   const messageElement = document.querySelector("#paypal-message");
   const quantityInput = document.querySelector("#quantity-input");

client/components/paypalPayments/oneTimePayment/html/src/advanced/paymentHandler/app.js

@@ -1,3 +1,10 @@
+/**
+ * Initializes the PayPal Web SDK, creates a PayPal Payments instance,
+ * and sets up the PayPal button.
+ * @async
+ * @function
+ * @returns {Promise<void>}
+ */
 async function onPayPalWebSdkLoaded() {
   try {
     const clientToken = await getBrowserSafeClientToken();
@@ -13,6 +20,14 @@ async function onPayPalWebSdkLoaded() {
   }
 }
 
+/**
+ * Sets up the PayPal button, handles payment session events,
+ * and manages presentation modes for the payment flow.
+ * @async
+ * @function
+ * @param {Object} sdkInstance - The PayPal SDK instance.
+ * @returns {Promise<void>}
+ */
 async function setupPayPalButton(sdkInstance) {
   const paymentSessionOptions = {
     async onApprove(data) {
@@ -76,6 +91,12 @@ async function setupPayPalButton(sdkInstance) {
   });
 }
 
+/**
+ * Fetches a browser-safe client token from the server for PayPal SDK initialization.
+ * @async
+ * @function
+ * @returns {Promise<string>} The browser-safe client access token.
+ */
 async function getBrowserSafeClientToken() {
   const response = await fetch("/paypal-api/auth/browser-safe-client-token", {
     method: "GET",
@@ -88,6 +109,12 @@ async function getBrowserSafeClientToken() {
   return accessToken;
 }
 
+/**
+ * Creates a PayPal order by sending a request to the server.
+ * @async
+ * @function
+ * @returns {Promise<Object>} The created order object containing the order ID.
+ */
 async function createOrder() {
   const response = await fetch(
     "/paypal-api/checkout/orders/create-with-sample-data",
@@ -103,6 +130,14 @@ async function createOrder() {
   return { orderId: id };
 }
 
+/**
+ * Captures a PayPal order by order ID.
+ * @async
+ * @function
+ * @param {Object} params - The parameters object.
+ * @param {string} params.orderId - The PayPal order ID.
+ * @returns {Promise<Object>} The capture order response data.
+ */
 async function captureOrder({ orderId }) {
   const response = await fetch(
     `/paypal-api/checkout/orders/${orderId}/capture`,