pay-rehearsal 0.1.0 → 0.2.0

package/README.md

@@ -1,23 +1,24 @@
 # Pay Rehearsal React
 
-[한국어](./README.ko.md)
+[한국어](https://github.com/Librariann/pay-rehearsal/blob/main/README.ko.md)
 
-A TypeScript payment UI SDK for React and Next.js that lets you build the complete flow from checkout to payment completion while waiting for your payment gateway contract and approval.
+A TypeScript Mock checkout UI SDK for React and Next.js that lets you build domestic payment gateway and PayPal-style payment flows before connecting a live payment provider.
 
-> The Mock adapter does not perform real authorizations, charges, or card-data collection. In production, always connect a real payment gateway adapter and verify payments on your server.
+> The Mock adapter does not perform real authorizations, charges, or card-data collection. For production, replace the simulated authentication UI with the payment provider's official checkout experience and verify every payment on your server.
 
 ## Features
 
 - Responsive payment modal with baseline accessibility support
-- UI flows for cards, bank transfers, virtual accounts, and mobile payments
+- UI flows for cards, bank transfers, virtual accounts, mobile payments, and PayPal
 - Card issuer selection for KB Kookmin, Shinhan, Samsung, Hyundai, Lotte, Hana, Woori, NH Nonghyup, and BC
 - One-time and installment payment selection with card issuer authentication simulation
 - Major bank selection with bank transfer authentication simulation
 - Virtual account details with a deposit-pending (`pending`) result
+- A PayPal-inspired checkout theme with order creation, buyer approval, and capture stages
 - Success, failure, cancellation, and random test scenarios
 - Promise-based `requestPayment()` API
 - Prebuilt `PaymentButton`
-- A replaceable `PaymentAdapter` interface for real payment gateway integrations
+- A replaceable `PaymentAdapter` interface for custom test and integration experiments
 - Theme configuration for color, border radius, and font family
 - Compatible with React 18/19 and the Next.js App Router
 
@@ -55,7 +56,7 @@ export function AppPaymentProvider({ children }: { children: ReactNode }) {
     <MockPaymentProvider
       result="success"
       delayMs={900}
-      paymentMethods={["card", "bank-transfer", "virtual-account"]}
+      paymentMethods={["card", "bank-transfer", "virtual-account", "paypal"]}
       defaultPaymentMethod="card"
       theme={{ accentColor: "#4f46e5", borderRadius: 24 }}
     >
@@ -71,7 +72,11 @@ Add the provider to your root layout.
 // app/layout.tsx
 import { AppPaymentProvider } from "./payment-provider";
 
-export default function RootLayout({ children }: { children: React.ReactNode }) {
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
   return (
     <html lang="en">
       <body>
@@ -136,7 +141,7 @@ For simpler use cases, you can use `PaymentButton`.
 
 ## Configuring Payment Methods and Their Order
 
-Use the provider's `paymentMethods` property to choose which methods appear in the modal and in what order. When omitted, cards, bank transfers, virtual accounts, and mobile payments are all displayed.
+Use the provider's `paymentMethods` property to choose which methods appear in the modal and in what order. When omitted, cards, bank transfers, virtual accounts, mobile payments, and PayPal are all displayed.
 
 ```tsx
 <MockPaymentProvider
@@ -165,6 +170,54 @@ requestPayment(order, {
 
 Configuration precedence is request-level `paymentMethod` → request-level `paymentMethods` → provider-level `paymentMethods`. Array order determines display order. In production, your server must verify that a selected payment method is enabled under your gateway contract regardless of whether the method appears in the UI.
 
+## Rehearsing PayPal Checkout
+
+Add `paypal` to the provider's payment method list:
+
+```tsx
+<MockPaymentProvider
+  paymentMethods={["paypal", "card"]}
+  defaultPaymentMethod="paypal"
+>
+  {children}
+</MockPaymentProvider>
+```
+
+You can also lock an individual request to PayPal:
+
+```ts
+requestPayment(
+  {
+    orderId: "ORDER-PAYPAL-1001",
+    orderName: "Global Pro Plan",
+    amount: 29,
+    currency: "USD",
+  },
+  { paymentMethod: "paypal" },
+);
+```
+
+When PayPal is active, the modal automatically switches to a PayPal-inspired navy and yellow theme. It returns to the configured provider theme when another payment method is selected.
+
+The Mock PayPal flow reproduces these stages:
+
+1. **Create order** — displays a short server-order creation state and generates a `PAYPAL-MOCK-*` order ID.
+2. **Buyer approval** — displays the simulated PayPal login and approval step.
+3. **Capture payment** — uses the configured Mock adapter to process the approved order.
+4. **Show result** — returns `success`, `failed`, or `cancelled` according to the selected test scenario.
+
+```text
+Select PayPal
+  → Create a Mock order
+  → Simulate buyer approval
+  → Capture and verify
+  → Return the payment result
+```
+
+The progress indicator and Mock order ID are UI simulation data. The final `PaymentResult` continues to use the adapter-generated `paymentId`.
+
+This package does not load the PayPal JavaScript SDK, open a real PayPal window, create a PayPal order, capture funds, or require PayPal credentials. For a live integration, your server must create the order and capture it after buyer approval. Validate supported currencies, buyer country availability, amount, merchant account, and the final capture status on your server.
+
 ## Test Scenarios
 
 ```tsx
@@ -216,12 +269,13 @@ const result = await requestPayment(
 - Bank transfer: select withdrawal bank → simulate bank app or BankPay authentication → confirm transfer → `success`
 - Virtual account: select deposit bank → issue account → display account number and deposit deadline → `pending`
 - Mobile payment: simulate authorization → `success`
+- PayPal: simulate server-side order creation → simulate buyer approval → simulate capture and verification → `success`
 
 A real virtual account payment is not complete when the account is issued. The order should be marked as paid only after your server verifies the payment gateway's webhook following the deposit. `pay-rehearsal` reproduces this distinction by returning `pending` when a virtual account is issued.
 
-## Replacing the Mock Adapter with a Real Payment Gateway
+## Custom Adapters and Production Boundaries
 
-Keep the UI and consumer code unchanged and replace only the `PaymentAdapter` implementation.
+The adapter interface can be used as a starting point for connecting a payment gateway. The included modal remains a rehearsal UI; a production integration must replace simulated authentication with the provider's official checkout experience and verify the result on the server.
 
 ```ts
 import type { PaymentAdapter } from "pay-rehearsal";
@@ -230,10 +284,7 @@ export const realPgAdapter: PaymentAdapter = {
   name: "My Payment Gateway",
   testMode: false,
 
-  async pay(
-    { request, method, cardIssuer, installmentMonths, bank },
-    signal,
-  ) {
+  async pay({ request, method, cardIssuer, installmentMonths, bank }, signal) {
     // 1. Open the payment gateway SDK checkout UI.
     // 2. Send paymentKey, orderId, and amount to your application server.
     // 3. Have the server call the gateway's confirmation API and verify the amount.

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import * as react from 'react';
 import { ReactNode, ButtonHTMLAttributes } from 'react';
 
 type Currency = "KRW" | "USD" | "JPY" | "EUR";
-type PaymentMethod = "card" | "bank-transfer" | "virtual-account" | "mobile";
+type PaymentMethod = "card" | "bank-transfer" | "virtual-account" | "mobile" | "paypal";
 type CardIssuer = "kb-kookmin" | "shinhan" | "samsung" | "hyundai" | "lotte" | "hana" | "woori" | "nh-nonghyup" | "bc";
 type BankCode = "kb-kookmin" | "shinhan" | "woori" | "hana" | "nh-nonghyup" | "ibk" | "kakaobank" | "tossbank";
 type MockPaymentScenario = "success" | "failure" | "cancelled" | "random";