@easypayment/medusa-paypal-ui 1.0.32 → 1.0.34

package/README.md

@@ -1,138 +1,504 @@
-# @easypayment/medusa-paypal-ui
-
-Production-ready PayPal storefront UI package for **Medusa v2 + Next.js**.
-
-Includes:
-
-- `MedusaNextPayPalAdapter` for checkout integration
-- Smart Buttons support
-- Advanced Card Fields support
-- Runtime config loading from `/store/paypal/config`
-
----
-
-## Compatibility
-
-- Next.js `>=14`
-- React `>=18`
-- Medusa backend with `@easypayment/medusa-paypal`
-
----
-
-## Step-by-step setup (GitHub style)
-
-### 1) Install dependencies
-
-```bash
-npm install @easypayment/medusa-paypal-ui @paypal/react-paypal-js
-# or
-pnpm add @easypayment/medusa-paypal-ui @paypal/react-paypal-js
-# or
-yarn add @easypayment/medusa-paypal-ui @paypal/react-paypal-js
-```
-
-### 2) Add storefront environment variables
-
-In your storefront `.env.local`:
-
-```bash
-NEXT_PUBLIC_MEDUSA_BACKEND_URL=https://your-medusa-api.example.com
-NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_xxxxxxxxxxxxxxxxxxxxx
-```
-
-> Never expose secret keys (`sk_*`) in `NEXT_PUBLIC_*` vars.
-
-### 3) Ensure payment session uses PayPal provider IDs
-
-Common provider IDs:
-
-- `pp_paypal_paypal`
-- `pp_paypal_card_paypal_card`
-
-When the shopper selects a payment method, initialize a matching Medusa payment session.
-
-### 4) Render `MedusaNextPayPalAdapter` in checkout
-
-```tsx
-import { MedusaNextPayPalAdapter } from "@easypayment/medusa-paypal-ui"
-import { initiatePaymentSession, placeOrder } from "@lib/data/cart"
-
-const PAYPAL_IDS = ["pp_paypal_paypal", "pp_paypal_card_paypal_card"]
-
-// Example on payment selection
-async function setPaymentMethod(providerId: string) {
-  await initiatePaymentSession(cart, { provider_id: providerId })
-}
-
-<MedusaNextPayPalAdapter
-  cartId={cart.id}
-  selectedProviderId={selectedPaymentMethod}
-  baseUrl={process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL!}
-  publishableApiKey={process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY}
-  onSuccess={() => placeOrder(cart.id)}
-  onError={(message) => setError(message)}
-/>
-```
-
-### 5) Validate checkout flows
-
-- Test PayPal Wallet flow.
-- Test PayPal Advanced Card flow.
-- Confirm order placement callback (`onSuccess`) runs.
-- Confirm errors surface through `onError`.
-
----
-
-## Props
-
-| Prop | Required | Description |
-|---|---|---|
-| `cartId` | ✅ | Active cart ID |
-| `selectedProviderId` | ✅ | Currently selected provider ID |
-| `baseUrl` | ✅ | Medusa backend URL |
-| `publishableApiKey` | optional | Medusa publishable key |
-| `providerIds` | optional | Override default provider IDs |
-| `onSuccess` | optional | Called after successful PayPal capture/authorize |
-| `onError` | optional | Called on payment error |
-
----
-
-## Provider ID mapping
-
-Default adapter IDs:
-
-```ts
-paypal: "pp_paypal_paypal"
-paypalCard: "pp_paypal_card_paypal_card"
-```
-
-If backend IDs differ, pass `providerIds` explicitly.
-
----
-
-## Quick checklist
-
-- [ ] UI package installed
-- [ ] Storefront env vars set
-- [ ] Checkout initializes PayPal provider payment session
-- [ ] Adapter rendered with required props
-- [ ] Wallet + Card flows verified
-
----
-
-## Build and test (package development)
-
-```bash
-npm run build
-npm test
-```
-
----
-
-## License
-
-MIT
-
-## UI note
-
-The Advanced Card hosted fields (`Card number`, `Expiration date`, `Security code`) use `style={cardStyle}` on `PayPalCardFieldsProvider`, including `cardStyle.input.height: "46px"` (`fontSize: 16px`, `padding: 12px 14px`) so PayPal renders the iframe at the correct height and avoids clipping.
+# @easypayment/medusa-paypal-ui
+
+PayPal checkout UI for Medusa v2 storefronts.
+
+A React storefront package for integrating **PayPal Wallet** and **PayPal Advanced Card Payments** into a Medusa + Next.js checkout.
+
+---
+
+## Overview
+
+`@easypayment/medusa-paypal-ui` is used on the **storefront** side and works with the backend package:
+
+- `@easypayment/medusa-paypal`
+
+It is designed to plug into the Medusa Next.js starter checkout and adds:
+
+- PayPal Wallet rendering in checkout
+- PayPal Advanced Card rendering in checkout
+- runtime config loading from the Medusa backend
+- PayPal-specific payment session initialization
+- success and error callbacks for order placement
+
+---
+
+## Compatibility
+
+| Component | Version |
+|---|---|
+| Next.js | `15.3.9` |
+| React | `19.0.4` |
+| Storefront starter | `medusa-next@1.0.3` |
+| UI package | `@easypayment/medusa-paypal-ui@1.0.32` |
+
+---
+
+## Installation
+
+Install the UI package in your storefront:
+
+```bash
+npm install @easypayment/medusa-paypal-ui
+```
+
+If your project does not already include the PayPal React SDK, install it as well:
+
+```bash
+npm install @paypal/react-paypal-js
+```
+
+Or with pnpm:
+
+```bash
+pnpm add @easypayment/medusa-paypal-ui @paypal/react-paypal-js
+```
+
+Or with yarn:
+
+```bash
+yarn add @easypayment/medusa-paypal-ui @paypal/react-paypal-js
+```
+
+---
+
+## Storefront Environment Variables
+
+Add the required variables to your storefront `.env.local` or `.env` file:
+
+```env
+MEDUSA_BACKEND_URL=http://localhost:9000
+NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://localhost:9000
+NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_your_publishable_key
+NEXT_PUBLIC_BASE_URL=http://localhost:8000
+NEXT_PUBLIC_DEFAULT_REGION=us
+```
+
+Other storefront variables such as Stripe, revalidation, or cloud image settings are unrelated to this PayPal package and can stay as they are in the Medusa starter template.
+
+---
+
+## Backend Requirements
+
+Your Medusa backend must:
+
+- have `@easypayment/medusa-paypal` installed
+- register both PayPal providers
+- expose `/store/paypal/config`
+- have PayPal configured from Medusa Admin
+
+Typical backend provider IDs:
+
+```txt
+pp_paypal_paypal
+pp_paypal_card_paypal_card
+```
+
+---
+
+## What Changed in Checkout Integration
+
+Compared with the original Medusa starter payment step, the PayPal integration adds the following behavior:
+
+- imports `MedusaNextPayPalAdapter`
+- imports `placeOrder` for PayPal success completion
+- defines PayPal provider IDs
+- initializes payment sessions for PayPal methods
+- fetches runtime config from `/store/paypal/config`
+- hides PayPal methods when backend config disables them
+- uses backend titles for PayPal Wallet and Card
+- disables the default submit button for PayPal because PayPal handles its own submit flow
+
+---
+
+## Checkout Integration Example
+
+Below is the updated payment-step pattern based on the current storefront integration:
+
+```tsx
+"use client"
+
+import { RadioGroup } from "@headlessui/react"
+import { isStripeLike, paymentInfoMap } from "@lib/constants"
+import { initiatePaymentSession, placeOrder } from "@lib/data/cart"
+import { CheckCircleSolid, CreditCard } from "@medusajs/icons"
+import { Button, Container, Heading, Text, clx } from "@medusajs/ui"
+import { MedusaNextPayPalAdapter } from "@easypayment/medusa-paypal-ui"
+import ErrorMessage from "@modules/checkout/components/error-message"
+import PaymentContainer, {
+  StripeCardContainer,
+} from "@modules/checkout/components/payment-container"
+import Divider from "@modules/common/components/divider"
+import { usePathname, useRouter, useSearchParams } from "next/navigation"
+import { useCallback, useEffect, useState } from "react"
+
+const PAYPAL_IDS = ["pp_paypal_paypal", "pp_paypal_card_paypal_card"]
+const isPayPal = (id: string) => PAYPAL_IDS.includes(id)
+
+const Payment = ({
+  cart,
+  availablePaymentMethods,
+}: {
+  cart: any
+  availablePaymentMethods: any[]
+}) => {
+  const activeSession = cart.payment_collection?.payment_sessions?.find(
+    (paymentSession: any) => paymentSession.status === "pending"
+  )
+
+  const [isLoading, setIsLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const [cardBrand, setCardBrand] = useState<string | null>(null)
+  const [cardComplete, setCardComplete] = useState(false)
+  const [selectedPaymentMethod, setSelectedPaymentMethod] = useState(
+    activeSession?.provider_id ?? ""
+  )
+  const [paypalEnabled, setPaypalEnabled] = useState<boolean>(true)
+  const [paypalTitle, setPaypalTitle] = useState<string>("PayPal")
+  const [cardEnabled, setCardEnabled] = useState<boolean>(true)
+  const [cardTitle, setCardTitle] = useState<string>("Credit or Debit Card")
+
+  const searchParams = useSearchParams()
+  const router = useRouter()
+  const pathname = usePathname()
+
+  const isOpen = searchParams.get("step") === "payment"
+
+  const setPaymentMethod = async (method: string) => {
+    setError(null)
+    setSelectedPaymentMethod(method)
+
+    if (isStripeLike(method) || isPayPal(method)) {
+      await initiatePaymentSession(cart, { provider_id: method })
+    }
+  }
+
+  const paidByGiftcard =
+    cart?.gift_cards && cart?.gift_cards?.length > 0 && cart?.total === 0
+
+  const paymentReady =
+    (activeSession && cart?.shipping_methods.length !== 0) || paidByGiftcard
+
+  const createQueryString = useCallback(
+    (name: string, value: string) => {
+      const params = new URLSearchParams(searchParams)
+      params.set(name, value)
+      return params.toString()
+    },
+    [searchParams]
+  )
+
+  const handleEdit = () => {
+    router.push(pathname + "?" + createQueryString("step", "payment"), {
+      scroll: false,
+    })
+  }
+
+  const handleSubmit = async () => {
+    setIsLoading(true)
+    try {
+      const shouldInputCard =
+        isStripeLike(selectedPaymentMethod) && !activeSession
+
+      const checkActiveSession =
+        activeSession?.provider_id === selectedPaymentMethod
+
+      if (!checkActiveSession) {
+        await initiatePaymentSession(cart, {
+          provider_id: selectedPaymentMethod,
+        })
+      }
+
+      if (!shouldInputCard) {
+        return router.push(
+          pathname + "?" + createQueryString("step", "review"),
+          {
+            scroll: false,
+          }
+        )
+      }
+    } catch (err: any) {
+      setError(err.message)
+    } finally {
+      setIsLoading(false)
+    }
+  }
+
+  useEffect(() => {
+    setError(null)
+  }, [isOpen])
+
+  useEffect(() => {
+    if (!isOpen) return
+
+    const backendUrl = process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL
+    if (!backendUrl) return
+
+    const key = process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY
+
+    fetch(`${backendUrl}/store/paypal/config`, {
+      headers: key ? { "x-publishable-api-key": key } : {},
+    })
+      .then((r) => {
+        if (r.status === 403) {
+          setPaypalEnabled(false)
+          setCardEnabled(false)
+          return null
+        }
+
+        if (!r.ok) {
+          return null
+        }
+
+        return r.json()
+      })
+      .then((cfg) => {
+        if (!cfg) return
+
+        if (typeof cfg?.paypal_enabled === "boolean") {
+          setPaypalEnabled(cfg.paypal_enabled)
+        }
+
+        if (typeof cfg?.paypal_title === "string" && cfg.paypal_title) {
+          setPaypalTitle(cfg.paypal_title)
+        }
+
+        if (typeof cfg?.card_enabled === "boolean") {
+          setCardEnabled(cfg.card_enabled)
+        }
+
+        if (typeof cfg?.card_title === "string" && cfg.card_title) {
+          setCardTitle(cfg.card_title)
+        }
+      })
+      .catch(() => {})
+  }, [isOpen])
+
+  return (
+    <div className="bg-white">
+      <div className="flex flex-row items-center justify-between mb-6">
+        <Heading
+          level="h2"
+          className={clx(
+            "flex flex-row text-3xl-regular gap-x-2 items-baseline",
+            {
+              "opacity-50 pointer-events-none select-none":
+                !isOpen && !paymentReady,
+            }
+          )}
+        >
+          Payment
+          {!isOpen && paymentReady && <CheckCircleSolid />}
+        </Heading>
+
+        {!isOpen && paymentReady && (
+          <Text>
+            <button
+              onClick={handleEdit}
+              className="text-ui-fg-interactive hover:text-ui-fg-interactive-hover"
+              data-testid="edit-payment-button"
+            >
+              Edit
+            </button>
+          </Text>
+        )}
+      </div>
+
+      <div>
+        <div className={isOpen ? "block" : "hidden"}>
+          {!paidByGiftcard &&
+            availablePaymentMethods?.length &&
+            (paypalEnabled ||
+              cardEnabled ||
+              availablePaymentMethods.some((m) => !isPayPal(m.id))) && (
+              <>
+                <RadioGroup
+                  value={selectedPaymentMethod}
+                  onChange={(value: string) => setPaymentMethod(value)}
+                >
+                  {availablePaymentMethods
+                    .filter((m) => {
+                      if (m.id === "pp_paypal_paypal" && !paypalEnabled) return false
+                      if (m.id === "pp_paypal_card_paypal_card" && !cardEnabled) return false
+                      return true
+                    })
+                    .map((paymentMethod) => (
+                      <div key={paymentMethod.id}>
+                        {isStripeLike(paymentMethod.id) ? (
+                          <StripeCardContainer
+                            paymentProviderId={paymentMethod.id}
+                            selectedPaymentOptionId={selectedPaymentMethod}
+                            paymentInfoMap={paymentInfoMap}
+                            setCardBrand={setCardBrand}
+                            setError={setError}
+                            setCardComplete={setCardComplete}
+                          />
+                        ) : (
+                          <PaymentContainer
+                            paymentInfoMap={{
+                              ...paymentInfoMap,
+                              ...(isPayPal(paymentMethod.id)
+                                ? {
+                                    [paymentMethod.id]: {
+                                      ...(paymentInfoMap[paymentMethod.id] || {}),
+                                      title:
+                                        paymentMethod.id === "pp_paypal_card_paypal_card"
+                                          ? cardTitle
+                                          : paypalTitle,
+                                    },
+                                  }
+                                : {}),
+                            }}
+                            paymentProviderId={paymentMethod.id}
+                            selectedPaymentOptionId={selectedPaymentMethod}
+                          />
+                        )}
+                      </div>
+                    ))}
+                </RadioGroup>
+
+                {isPayPal(selectedPaymentMethod) && (
+                  <MedusaNextPayPalAdapter
+                    cartId={cart.id}
+                    selectedProviderId={selectedPaymentMethod}
+                    baseUrl={process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL!}
+                    publishableApiKey={process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY}
+                    onSuccess={() => placeOrder(cart.id)}
+                    onError={(msg) => setError(msg)}
+                  />
+                )}
+              </>
+            )}
+
+          <ErrorMessage
+            error={error}
+            data-testid="payment-method-error-message"
+          />
+
+          <Button
+            size="large"
+            className="mt-6"
+            onClick={handleSubmit}
+            isLoading={isLoading}
+            disabled={
+              (isStripeLike(selectedPaymentMethod) && !cardComplete) ||
+              (!selectedPaymentMethod && !paidByGiftcard) ||
+              isPayPal(selectedPaymentMethod)
+            }
+            data-testid="submit-payment-button"
+          >
+            {!activeSession && isStripeLike(selectedPaymentMethod)
+              ? " Enter card details"
+              : "Continue to review"}
+          </Button>
+        </div>
+      </div>
+
+      <Divider className="mt-8" />
+    </div>
+  )
+}
+
+export default Payment
+```
+
+---
+
+## Adapter Usage
+
+Render the adapter only when the selected payment method is a PayPal provider:
+
+```tsx
+{isPayPal(selectedPaymentMethod) && (
+  <MedusaNextPayPalAdapter
+    cartId={cart.id}
+    selectedProviderId={selectedPaymentMethod}
+    baseUrl={process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL!}
+    publishableApiKey={process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY}
+    onSuccess={() => placeOrder(cart.id)}
+    onError={(msg) => setError(msg)}
+  />
+)}
+```
+
+---
+
+## Runtime Config Endpoint
+
+The storefront reads PayPal runtime settings from:
+
+```txt
+/store/paypal/config
+```
+
+This endpoint is used to control:
+
+- `paypal_enabled`
+- `paypal_title`
+- `card_enabled`
+- `card_title`
+
+If the endpoint returns `403`, the storefront should treat both PayPal methods as disabled.
+
+---
+
+## Props
+
+| Prop | Required | Description |
+|---|---|---|
+| `cartId` | Yes | Active cart ID |
+| `selectedProviderId` | Yes | Currently selected payment provider ID |
+| `baseUrl` | Yes | Medusa backend base URL |
+| `publishableApiKey` | No | Publishable API key sent in config request |
+| `providerIds` | No | Override default PayPal provider IDs |
+| `onSuccess` | No | Called after successful PayPal checkout |
+| `onError` | No | Called when PayPal returns an error |
+
+---
+
+## Default Provider Mapping
+
+The UI package uses these default provider IDs:
+
+```ts
+{
+  paypal: "pp_paypal_paypal",
+  paypalCard: "pp_paypal_card_paypal_card"
+}
+```
+
+If your backend uses custom IDs, pass them through `providerIds`.
+
+---
+
+## Notes for Medusa Starter Users
+
+The original Medusa starter payment step only initialized Stripe-like sessions and used the default review-step submit flow.
+
+To support PayPal, your updated checkout should additionally:
+
+- initialize sessions for PayPal methods
+- render `MedusaNextPayPalAdapter`
+- call `placeOrder` after successful PayPal completion
+- disable the normal submit button while PayPal is selected
+- optionally fetch backend config to control PayPal method visibility and labels
+
+---
+
+## Validation Checklist
+
+- Install `@easypayment/medusa-paypal-ui`
+- Install `@paypal/react-paypal-js`
+- Set storefront environment variables
+- Configure backend PayPal package
+- Ensure provider IDs match backend configuration
+- Update checkout payment step
+- Verify PayPal Wallet flow
+- Verify PayPal Card flow
+- Verify order placement after successful payment
+- Verify error handling
+
+---
+
+## License
+
+MIT