@easypayment/medusa-paypal-ui 1.0.44 → 1.0.45

package/README.md

@@ -1,89 +1,76 @@
-<div align="center">
+# PayPal for Medusa Frontend UI
 
-<h1>🅿 medusa-paypal-frontend</h1>
+**PayPal checkout UI for Medusa v2 storefronts — Smart Buttons, Advanced Card Fields**
 
-<p><strong>PayPal checkout UI for Medusa v2 storefronts</strong></p>
+[![npm version](https://img.shields.io/npm/v/@easypayment/medusa-paypal-ui?color=blue&label=npm)](https://www.npmjs.com/package/@easypayment/medusa-paypal-ui)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Medusa v2](https://img.shields.io/badge/Medusa-v2-9b59b6)](https://medusajs.com)
+[![Next.js](https://img.shields.io/badge/Next.js-14%2B-black)](https://nextjs.org)
 
-<p>
-  <a href="https://www.npmjs.com/package/@easypayment/medusa-paypal-ui"><img src="https://img.shields.io/npm/v/@easypayment/medusa-paypal-ui?color=blue&label=npm" alt="npm version" /></a>
-  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License: MIT" /></a>
-  <a href="https://medusajs.com"><img src="https://img.shields.io/badge/Medusa-v2-9b59b6" alt="Medusa v2" /></a>
-  <a href="https://nextjs.org"><img src="https://img.shields.io/badge/Next.js-14%2B-black" alt="Next.js" /></a>
-</p>
-
-<p>PayPal Smart Buttons · Advanced Card Fields · Built-in loading states · Admin-controlled settings</p>
+---
 
-</div>
+## 📋 Table of Contents
+
+- [📦 Overview](#-overview)
+- [✅ Requirements](#-requirements)
+- [🚀 Installation](#-installation)
+- [🔑 Environment Variables](#-environment-variables)
+- [🔗 Integration Guide](#-integration-guide)
+  - [Step 1 — Add the import](#step-1--add-the-import)
+  - [Step 2 — Add PayPal helpers and state](#step-2--add-paypal-helpers-and-state)
+  - [Step 3 — Load PayPal config](#step-3--load-paypal-config)
+  - [Step 4 — Update setPaymentMethod](#step-4--update-setpaymentmethod)
+  - [Step 5 — Filter the payment method list](#step-5--filter-the-payment-method-list)
+  - [Step 6 — Inject admin-configured titles](#step-6--inject-admin-configured-titles)
+  - [Step 7 — Render the PayPal UI](#step-7--render-the-paypal-ui)
+  - [Step 8 — Disable the Continue button](#step-8--disable-the-continue-button)
+  - [Step 9 — Fix the summary label](#step-9--fix-the-summary-label)
+- [📄 Complete File](#-complete-file)
+- [🧪 Testing](#-testing)
+- [📄 License](#-license)
 
 ---
 
-## Overview
+## 📦 Overview
 
-`@easypayment/medusa-paypal-ui` is a React UI package that connects your Next.js (App Router) storefront to the `medusa-paypal-backend` plugin. It ships the PayPal adapter used inside your checkout payment step — your storefront adds the adapter, provider filtering, and backend config handling to the existing Medusa payment UI.
+`@easypayment/medusa-paypal-ui` is the **storefront UI package** that connects your Next.js (App Router) storefront to the `@easypayment/medusa-paypal` backend plugin. It ships the PayPal adapter used inside your checkout payment step — your storefront adds the adapter, provider filtering, and backend config handling to the existing Medusa payment UI.
 
 | Feature | Details |
 |---|---|
-| **PayPal Smart Buttons** | Wallet-based checkout via `pp_paypal_paypal` |
-| **Advanced Card Fields** | Hosted PCI-compliant card inputs via `pp_paypal_card_paypal_card` |
-| **Admin-driven config** | Enable/disable providers and set labels from Medusa Admin |
-| **Built-in UX** | Smart Buttons and Advanced Card UI are rendered by `MedusaNextPayPalAdapter` |
-| **Storefront-controlled flow** | Your payment step controls session creation, loading states, and `placeOrder` |
-
----
-
-## Table of Contents
-
-- [Requirements](#requirements)
-- [Installation](#installation)
-- [Environment Variables](#environment-variables)
-- [Integration Guide](#integration-guide)
-  - [Step 1 - Add the import](#step-1---add-the-import)
-  - [Step 2 - Add PayPal helpers and state](#step-2---add-paypal-helpers-and-state)
-  - [Step 3 - Load config from /store/paypal/config](#step-3---load-config-from-storepaypalconfig)
-  - [Step 4 - Update setPaymentMethod](#step-4---update-setpaymentmethod)
-  - [Step 5 - Filter the payment method list](#step-5---filter-the-payment-method-list)
-  - [Step 6 - Inject admin-configured titles](#step-6---inject-admin-configured-titles)
-  - [Step 7 - Render the PayPal UI](#step-7---render-the-paypal-ui)
-  - [Step 8 - Disable the Continue button](#step-8---disable-the-continue-button)
-  - [Step 9 - Fix the summary label](#step-9---fix-the-summary-label)
-- [Complete File](#complete-file)
-- [Testing](#testing)
+| 🔵 **PayPal Smart Buttons** | Wallet-based checkout via `pp_paypal_paypal` |
+| 💳 **Advanced Card Fields** | Hosted PCI-compliant advanced credit card inputs via `pp_paypal_card_paypal_card` |
+| 🛠 **Admin-driven config** | Enable/disable providers and set labels from Medusa Admin |
+| ⚡ **Built-in UX** | Smart Buttons and Advanced Card UI rendered by `MedusaNextPayPalAdapter` |
+| 🔄 **Storefront-controlled flow** | Your payment step controls session creation, loading states, and `placeOrder` |
 
 ---
 
-## Requirements
+## ✅ Requirements
 
 - **Node.js** 18+
 - **Next.js** 14+ with App Router
-- **`medusa-paypal-backend`** installed and running on your Medusa server
-- A PayPal account connected in Medusa Admin → Settings → PayPal → PayPal Connection
+- **`@easypayment/medusa-paypal`** installed and running on your Medusa server
+- A PayPal account connected in **Medusa Admin → Settings → PayPal → PayPal Connection**
 
 ---
 
-## Installation
+## 🚀 Installation
 
-```bash
-npm install @easypayment/medusa-paypal-ui
-```
+**In your storefront directory**, run:
 
 ```bash
-yarn add @easypayment/medusa-paypal-ui
+npm install @easypayment/medusa-paypal-ui
 ```
 
 ---
 
-## Environment Variables
+## 🔑 Environment Variables
 
 Add the following to your storefront `.env.local`. Use separate values for development and production.
 
 ```env
-# Development
 NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://localhost:9000
 NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_...
-
-# Production
-NEXT_PUBLIC_MEDUSA_BACKEND_URL=https://your-medusa-server.com
-NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_...
 ```
 
 > **Where to get the publishable key:**
@@ -91,21 +78,23 @@ NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_...
 
 ---
 
-## Integration Guide
+## 🔗 Integration Guide
 
-All changes are made to a single file in your storefront:
+All changes in this guide are made to **one single file** in your storefront:
 
 ```
 src/modules/checkout/components/payment/index.tsx
 ```
 
-> **Prefer copy-paste?** Skip to [Complete File](#complete-file) for a ready-to-use drop-in replacement.
+Open that file and follow each step in order.
+
+> **Prefer to copy-paste the whole file?** Skip straight to [Complete File](#-complete-file) and replace the entire contents in one go. The complete file has all 9 steps already applied.
 
 ---
 
-### Step 1 - Add the import
+### Step 1 — Add the import
 
-Add this import alongside your existing imports at the top of the file:
+**Where:** At the very top of the file, alongside your other imports.
 
 ```tsx
 import { MedusaNextPayPalAdapter } from "@easypayment/medusa-paypal-ui"
@@ -113,17 +102,21 @@ import { MedusaNextPayPalAdapter } from "@easypayment/medusa-paypal-ui"
 
 ---
 
-### Step 2 - Add PayPal helpers and state
+### Step 2 — Add PayPal helpers and state
 
-Inside the file, add PayPal provider helpers and the local state used by the updated implementation:
+**Where:** At the top of the file, outside the component — add the constants. Inside the `Payment` component, add the `useState` lines alongside your other state declarations.
 
 ```tsx
+// Outside the component — add these constants
 const PAYPAL_PROVIDER_ID = "pp_paypal_paypal"
 const PAYPAL_CARD_PROVIDER_ID = "pp_paypal_card_paypal_card"
 const PAYPAL_PROVIDER_IDS = [PAYPAL_PROVIDER_ID, PAYPAL_CARD_PROVIDER_ID]
 
 const isPayPal = (id: string) => PAYPAL_PROVIDER_IDS.includes(id)
+```
 
+```tsx
+// Inside the Payment component — add alongside your other useState declarations
 const [paypalEnabled, setPaypalEnabled] = useState(true)
 const [paypalTitle, setPaypalTitle] = useState("PayPal")
 const [cardEnabled, setCardEnabled] = useState(true)
@@ -133,21 +126,18 @@ const [paypalLoading, setPaypalLoading] = useState(false)
 
 ---
 
-### Step 3 - Load config from /store/paypal/config
+### Step 3 — Load PayPal config
+
+**Where:** Inside the `Payment` component, alongside your other `useEffect` hooks.
 
-Instead of using a hook, fetch the PayPal config when the payment step is open:
+This fetches PayPal settings from your backend whenever the payment step is opened, so the UI always reflects the latest admin configuration.
 
 ```tsx
 useEffect(() => {
-  if (!isOpen) {
-    return
-  }
+  if (!isOpen) return
 
   const backendUrl = process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL
-
-  if (!backendUrl) {
-    return
-  }
+  if (!backendUrl) return
 
   const key = process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY
   const controller = new AbortController()
@@ -165,74 +155,56 @@ useEffect(() => {
         return
       }
 
-      if (!response.ok) {
-        return
-      }
+      if (!response.ok) return
 
       const config = await response.json()
 
-      if (typeof config?.paypal_enabled === "boolean") {
-        setPaypalEnabled(config.paypal_enabled)
-      }
-
-      if (typeof config?.paypal_title === "string" && config.paypal_title) {
-        setPaypalTitle(config.paypal_title)
-      }
-
-      if (typeof config?.card_enabled === "boolean") {
-        setCardEnabled(config.card_enabled)
-      }
-
-      if (typeof config?.card_title === "string" && config.card_title) {
-        setCardTitle(config.card_title)
-      }
+      if (typeof config?.paypal_enabled === "boolean") setPaypalEnabled(config.paypal_enabled)
+      if (typeof config?.paypal_title === "string" && config.paypal_title) setPaypalTitle(config.paypal_title)
+      if (typeof config?.card_enabled === "boolean") setCardEnabled(config.card_enabled)
+      if (typeof config?.card_title === "string" && config.card_title) setCardTitle(config.card_title)
     } catch (err) {
-      if ((err as Error).name !== "AbortError") {
-        setPaypalLoading(false)
-      }
+      if ((err as Error).name !== "AbortError") setPaypalLoading(false)
     }
   }
 
   void loadPayPalConfig()
-
   return () => controller.abort()
 }, [isOpen])
 ```
 
 ---
 
-### Step 4 - Update setPaymentMethod
+### Step 4 — Update setPaymentMethod
+
+**Where:** Inside the `Payment` component. Find your existing `setPaymentMethod` function and **replace it entirely** with the version below.
 
-Replace your existing `setPaymentMethod` function with the following. The key addition is setting `paypalLoading` while the PayPal session is being created:
+The key addition is `paypalLoading` — it shows a loading indicator while the PayPal payment session is being created in the background.
 
 ```tsx
 const setPaymentMethod = async (method: string) => {
   setError(null)
   setSelectedPaymentMethod(method)
 
-  if (!isStripeLike(method) && !isPayPal(method)) {
-    return
-  }
+  if (!isStripeLike(method) && !isPayPal(method)) return
 
-  if (isPayPal(method)) {
-    setPaypalLoading(true)
-  }
+  if (isPayPal(method)) setPaypalLoading(true)
 
   try {
     await initiatePaymentSession(cart, { provider_id: method })
   } finally {
-    if (isPayPal(method)) {
-      setPaypalLoading(false)
-    }
+    if (isPayPal(method)) setPaypalLoading(false)
   }
 }
 ```
 
 ---
 
-### Step 5 - Filter the payment method list
+### Step 5 — Filter the payment method list
 
-Add a filtered payment method list before your `RadioGroup` render:
+**Where:** Inside the `Payment` component, alongside your other `useMemo` declarations — add this before the `return` statement.
+
+This hides PayPal or Card from the list if they have been disabled in Medusa Admin.
 
 ```tsx
 const filteredPaymentMethods = useMemo(
@@ -246,33 +218,33 @@ const filteredPaymentMethods = useMemo(
 )
 ```
 
-Then use `filteredPaymentMethods.map(...)` instead of rendering `availablePaymentMethods` directly.
+Then in your JSX, find where you render `availablePaymentMethods.map(...)` and **replace** `availablePaymentMethods` with `filteredPaymentMethods`:
+
+```tsx
+// Before
+availablePaymentMethods.map((paymentMethod) => ( ... ))
+
+// After
+filteredPaymentMethods.map((paymentMethod) => ( ... ))
+```
 
 ---
 
-### Step 6 - Inject admin-configured titles
+### Step 6 — Inject admin-configured titles
+
+**Where:** Inside the `.map()` loop from Step 5, find your `<PaymentContainer>` component and **replace** its `paymentInfoMap` prop with the version below.
 
-Inside your `.map()`, pass an overridden `paymentInfoMap` to the `PaymentContainer` component so the radio button labels reflect the values set in Medusa Admin:
+This makes the radio button labels show the titles configured in Medusa Admin instead of hardcoded defaults.
 
 ```tsx
 <PaymentContainer
   paymentInfoMap={{
     ...paymentInfoMap,
     ...(paymentMethod.id === PAYPAL_PROVIDER_ID
-      ? {
-          [paymentMethod.id]: {
-            ...(paymentInfoMap[paymentMethod.id] || {}),
-            title: paypalTitle,
-          },
-        }
+      ? { [paymentMethod.id]: { ...(paymentInfoMap[paymentMethod.id] || {}), title: paypalTitle } }
       : {}),
     ...(paymentMethod.id === PAYPAL_CARD_PROVIDER_ID
-      ? {
-          [paymentMethod.id]: {
-            ...(paymentInfoMap[paymentMethod.id] || {}),
-            title: cardTitle,
-          },
-        }
+      ? { [paymentMethod.id]: { ...(paymentInfoMap[paymentMethod.id] || {}), title: cardTitle } }
       : {}),
   }}
   paymentProviderId={paymentMethod.id}
@@ -282,17 +254,19 @@ Inside your `.map()`, pass an overridden `paymentInfoMap` to the `PaymentContain
 
 ---
 
-### Step 7 - Render the PayPal UI
+### Step 7 — Render the PayPal UI
+
+**Where:** In the JSX, immediately after the closing `</RadioGroup>` tag.
 
-After the closing `</RadioGroup>` tag, render a loading state while the PayPal session is being prepared, then mount `MedusaNextPayPalAdapter`:
+The first block shows a loading spinner while the session is being set up. The second block renders the PayPal buttons or card fields once the session is ready.
 
 ```tsx
+{/* Loading state while PayPal session is being created */}
 {isPayPal(selectedPaymentMethod) && paypalLoading && (
-  <div>
-    <div>Setting up payment...</div>
-  </div>
+  <div>Setting up payment...</div>
 )}
 
+{/* PayPal buttons or card fields */}
 {isPayPal(selectedPaymentMethod) && !paypalLoading && (
   <MedusaNextPayPalAdapter
     cartId={cart.id}
@@ -307,17 +281,13 @@ After the closing `</RadioGroup>` tag, render a loading state while the PayPal s
 )}
 ```
 
-> **Critical — `onSuccess` must call `placeOrder`**
->
-> `placeOrder` is the Next.js Server Action exported from `@lib/data/cart`. It **must** run server-side — it is the only mechanism that can clear the httpOnly cart cookie set by the server. Replacing it with a client-side `fetch` to `/store/carts/:id/complete` will complete the order in Medusa but leave the cart cookie intact, breaking the storefront session.
-
 ---
 
-### Step 8 - Disable the Continue button
+### Step 8 — Disable the Continue button
 
-Because PayPal renders its own checkout action, the storefront's "Continue to review" button must be disabled when PayPal is selected.
+**Where:** In the JSX, find your existing `<Button>` with `data-testid="submit-payment-button"` and **add** `isPayPal(selectedPaymentMethod)` to its `disabled` prop.
 
-Add `isPayPal(selectedPaymentMethod)` to your `Button` component's `disabled` prop:
+PayPal handles its own checkout action, so the "Continue to review" button must be hidden from the flow when PayPal is selected.
 
 ```tsx
 <Button
@@ -328,7 +298,7 @@ Add `isPayPal(selectedPaymentMethod)` to your `Button` component's `disabled` pr
   disabled={
     (isStripeLike(selectedPaymentMethod) && !cardComplete) ||
     (!selectedPaymentMethod && !paidByGiftcard) ||
-    isPayPal(selectedPaymentMethod)
+    isPayPal(selectedPaymentMethod)   // 👈 add this line
   }
   data-testid="submit-payment-button"
 >
@@ -340,9 +310,11 @@ Add `isPayPal(selectedPaymentMethod)` to your `Button` component's `disabled` pr
 
 ---
 
-### Step 9 - Fix the summary label
+### Step 9 — Fix the summary label
 
-In the collapsed summary view (shown after the customer has selected a payment method), replace any hardcoded PayPal label with the admin-configured title:
+**Where:** In the collapsed summary view (shown after the customer has completed the payment step). Find the `<Text>` with `data-testid="payment-method-summary"` and **replace its content** with the version below.
+
+This shows the admin-configured title instead of a hardcoded or missing label.
 
 ```tsx
 <Text
@@ -360,9 +332,9 @@ In the collapsed summary view (shown after the customer has selected a payment m
 
 ---
 
-## Complete File
+## 📄 Complete File
 
-The following is a complete, working replacement for your payment step file with all changes from the guide above already applied. Copy and replace the entire contents of `src/modules/checkout/components/payment/index.tsx`.
+If you prefer to copy-paste the entire file at once, replace the full contents of `src/modules/checkout/components/payment/index.tsx` with the following:
 
 ```tsx
 "use client"
@@ -420,14 +392,8 @@ const Payment = ({
   const filteredPaymentMethods = useMemo(
     () =>
       availablePaymentMethods.filter((paymentMethod) => {
-        if (paymentMethod.id === PAYPAL_PROVIDER_ID) {
-          return paypalEnabled
-        }
-
-        if (paymentMethod.id === PAYPAL_CARD_PROVIDER_ID) {
-          return cardEnabled
-        }
-
+        if (paymentMethod.id === PAYPAL_PROVIDER_ID) return paypalEnabled
+        if (paymentMethod.id === PAYPAL_CARD_PROVIDER_ID) return cardEnabled
         return true
       }),
     [availablePaymentMethods, cardEnabled, paypalEnabled],
@@ -437,20 +403,14 @@ const Payment = ({
     setError(null)
     setSelectedPaymentMethod(method)
 
-    if (!isStripeLike(method) && !isPayPal(method)) {
-      return
-    }
+    if (!isStripeLike(method) && !isPayPal(method)) return
 
-    if (isPayPal(method)) {
-      setPaypalLoading(true)
-    }
+    if (isPayPal(method)) setPaypalLoading(true)
 
     try {
       await initiatePaymentSession(cart, { provider_id: method })
     } finally {
-      if (isPayPal(method)) {
-        setPaypalLoading(false)
-      }
+      if (isPayPal(method)) setPaypalLoading(false)
     }
   }
 
@@ -508,15 +468,10 @@ const Payment = ({
   }, [isOpen])
 
   useEffect(() => {
-    if (!isOpen) {
-      return
-    }
+    if (!isOpen) return
 
     const backendUrl = process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL
-
-    if (!backendUrl) {
-      return
-    }
+    if (!backendUrl) return
 
     const key = process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY
     const controller = new AbortController()
@@ -534,36 +489,20 @@ const Payment = ({
           return
         }
 
-        if (!response.ok) {
-          return
-        }
+        if (!response.ok) return
 
         const config = await response.json()
 
-        if (typeof config?.paypal_enabled === "boolean") {
-          setPaypalEnabled(config.paypal_enabled)
-        }
-
-        if (typeof config?.paypal_title === "string" && config.paypal_title) {
-          setPaypalTitle(config.paypal_title)
-        }
-
-        if (typeof config?.card_enabled === "boolean") {
-          setCardEnabled(config.card_enabled)
-        }
-
-        if (typeof config?.card_title === "string" && config.card_title) {
-          setCardTitle(config.card_title)
-        }
+        if (typeof config?.paypal_enabled === "boolean") setPaypalEnabled(config.paypal_enabled)
+        if (typeof config?.paypal_title === "string" && config.paypal_title) setPaypalTitle(config.paypal_title)
+        if (typeof config?.card_enabled === "boolean") setCardEnabled(config.card_enabled)
+        if (typeof config?.card_title === "string" && config.card_title) setCardTitle(config.card_title)
       } catch (err) {
-        if ((err as Error).name !== "AbortError") {
-          setPaypalLoading(false)
-        }
+        if ((err as Error).name !== "AbortError") setPaypalLoading(false)
       }
     }
 
     void loadPayPalConfig()
-
     return () => controller.abort()
   }, [isOpen])
 
@@ -684,14 +623,13 @@ const Payment = ({
                     </div>
                   </div>
                 )}
+
                 {isPayPal(selectedPaymentMethod) && !paypalLoading && (
                   <MedusaNextPayPalAdapter
                     cartId={cart.id}
                     selectedProviderId={selectedPaymentMethod}
                     baseUrl={process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL!}
-                    publishableApiKey={
-                      process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY
-                    }
+                    publishableApiKey={process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY}
                     onSuccess={async () => {
                       await placeOrder(cart.id)
                     }}
@@ -801,18 +739,22 @@ export default Payment
 
 ---
 
-## Testing
+## 🧪 Testing
 
-Toggle between sandbox and live in Medusa Admin → **Settings → PayPal → PayPal Connection → Environment**.
+Toggle between sandbox and live in **Medusa Admin → Settings → PayPal → PayPal Connection → Environment**.
 
-**Sandbox buyer account**
+**Sandbox buyer account** — log in at [developer.paypal.com](https://developer.paypal.com) → **Testing → Sandbox Accounts** to find your auto-generated buyer credentials. Sandbox payments do not charge real money.
 
-Log in at [developer.paypal.com](https://developer.paypal.com) → **Testing → Sandbox Accounts** to find your auto-generated buyer credentials. Sandbox payments do not charge real money.
-
-**Test card number for Advanced Card fields**
+**Test card for Advanced Card Fields:**
 
 ```
 Card number   4111 1111 1111 1111
 Expiry        Any future date
 CVV           Any 3 digits
-```
+```
+
+---
+
+## 📄 License
+
+MIT © [Easy Payment](https://www.npmjs.com/package/@easypayment/medusa-paypal-ui)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@easypayment/medusa-paypal-ui",
-  "version": "1.0.44",
+  "version": "1.0.45",
   "description": "Enterprise Gold PayPal UI module for Medusa v2 storefront (Next.js)",
   "license": "MIT",
   "type": "module",
@@ -46,5 +46,9 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/easypaymentplugins/medusa-paypal-ui"
   }
 }