npm - recur-tw - Versions diffs - 0.9.13 → 0.10.1 - Mend

recur-tw 0.9.13 → 0.10.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.md CHANGED Viewed

@@ -1,896 +1,384 @@
-# Recur SDK (Taiwan)
+# Recur SDK
-A React & Vanilla JS SDK for embedding subscription checkout flows with PAYUNi payment integration.
-**專為台灣市場設計** - 透過 PAYUNi 金流服務處理訂閱式付款。
+台灣訂閱制金流 SDK - 透過 PAYUNi 金流處理訂閱式與一次性付款。
-Taiwan-specific subscription checkout SDK with embedded payment forms powered by Web Components.
+A React & Vanilla JS SDK for embedding subscription checkout flows with PAYUNi payment integration.
-## 🚀 Features
+## Features
-- ✅ **Hosted Checkout** - Zero-backend integration with `<recur-checkout>` Web Component
-- ✅ **React SDK** - Full React integration with hooks (`useProducts`, `useRecur`)
-- ✅ **Vanilla JS** - Use with plain HTML/JavaScript (no framework required)
-- ✅ **Embedded Checkout** - Native payment forms with PAYUNi credit card fields
-- ✅ **Web Components** - Modern, encapsulated UI components
-- ✅ **Custom Styling** - Fully customizable with shadcn/ui compatibility
-- ✅ **TypeScript** - Full type definitions included
-- ✅ **SSR Safe** - Works with Next.js, Remix, and other SSR frameworks
-- ✅ **Taiwan-focused** - PAYUNi payment integration
+- **Zero-config 嵌入** - 一行程式碼即可嵌入付款按鈕
+- **React SDK** - 完整 React 整合 (`useProducts`, `useRecur`)
+- **Vanilla JS** - 純 JavaScript，無框架依賴
+- **Web Components** - 現代化、封裝良好的 UI 元件
+- **TypeScript** - 完整型別定義
+- **SSR Safe** - 支援 Next.js、Remix 等 SSR 框架
 ---
-## 📦 Installation
+## 快速開始
-### For React Projects
-```bash
-npm install recur-tw
-# or
-pnpm add recur-tw
-# or
-yarn add recur-tw
-```
+### 方式一：Checkout Button（最簡單）
-### For Static HTML/JavaScript
+像 Gumroad 一樣，只需一個 script 和一個連結：
 ```html
-<!-- Via CDN (unpkg) -->
-<script src="https://unpkg.com/recur-tw@latest/dist/recur.umd.js"></script>
+<script src="https://unpkg.com/recur-tw/dist/checkout.js"></script>
-<!-- Via CDN (jsdelivr) -->
-<script src="https://cdn.jsdelivr.net/npm/recur-tw@latest/dist/recur.umd.js"></script>
+<a class="recur-button"
+   href="https://recur.tw/buy/prod_xxx"
+   data-key="pk_live_xxx">
+  訂閱方案
+</a>
 ```
----
-## 🎯 Quick Start
-### Option 1: React/Next.js
+點擊連結會開啟 modal 結帳視窗，完成後觸發事件：
-Full framework integration with React hooks and embedded checkout:
-```tsx
-'use client';
-import { RecurProvider, useProducts, useRecur } from 'recur-tw';
-// 1. Wrap your app with RecurProvider
-export default function App() {
-  return (
-    <RecurProvider
-      config={{
-        publishableKey: 'pk_test_xxx',
-        containerElementId: 'recur-payment-container' // For embedded checkout
-      }}
-    >
-      <ProductsPage />
-    </RecurProvider>
-  );
-}
-// 2. Fetch products and checkout
-function ProductsPage() {
-  // Fetch all products (or filter by type: 'SUBSCRIPTION', 'ONE_TIME', etc.)
-  const { data: products, isLoading } = useProducts();
-  const { checkout, isCheckingOut } = useRecur();
-  if (isLoading) return <div>Loading products...</div>;
-  return (
-    <div>
-      {products?.map((product) => (
-        <button
-          key={product.id}
-          onClick={() => checkout({
-            planId: product.id,
-            customerEmail: 'user@example.com',
-            customerName: 'John Doe',
-          })}
-          disabled={isCheckingOut}
-        >
-          {/* product.type: 'SUBSCRIPTION' | 'ONE_TIME' | 'CREDITS' | 'DONATION' */}
-          {product.type === 'SUBSCRIPTION' ? 'Subscribe to' : 'Buy'} {product.name} - NT${product.price}
-        </button>
-      ))}
-      {/* Embedded payment form will appear here */}
-      <div id="recur-payment-container"></div>
-    </div>
-  );
-}
-```
-### Option 2: Vanilla JavaScript (Static HTML)
-Perfect for landing pages, marketing sites, or any static HTML:
-```html
-<!DOCTYPE html>
-<html>
-<body>
-  <button id="checkout-btn">訂閱方案</button>
-  <script src="https://unpkg.com/recur-tw@latest/dist/recur.umd.js"></script>
-  <script>
-    // Initialize SDK
-    const recur = RecurCheckout.init({
-      publishableKey: 'pk_test_your_key_here'
-    });
-    // Checkout on button click
-    document.getElementById('checkout-btn').addEventListener('click', async () => {
-      await recur.checkout({
-        planId: 'plan_xxx',
-        customerName: '王小明',
-        customerEmail: 'user@example.com',
-        mode: 'redirect' // 'redirect' or 'embedded'
-      });
-    });
-  </script>
-</body>
-</html>
-```
-### Option 3: Hosted Checkout (Zero Backend)
+```javascript
+window.addEventListener('recur:success', (e) => {
+  console.log('付款成功！', e.detail);
+});
-**NEW!** The simplest integration - redirect to Recur's hosted checkout page:
+window.addEventListener('recur:error', (e) => {
+  console.error('付款失敗', e.detail);
+});
-```html
-<!DOCTYPE html>
-<html>
-<body>
-  <!-- Drop-in checkout button - no JavaScript required! -->
-  <recur-checkout
-    publishable-key="pk_test_xxx"
-    product-id="prod_xxx"
-    success-url="https://yoursite.com/success"
-    cancel-url="https://yoursite.com/cancel">
-    訂閱方案
-  </recur-checkout>
-  <script src="https://unpkg.com/recur-tw@latest/dist/recur.umd.js"></script>
-</body>
-</html>
+window.addEventListener('recur:close', () => {
+  console.log('使用者關閉視窗');
+});
 ```
-Or use the JavaScript API:
+**JavaScript API：**
 ```javascript
-const recur = RecurCheckout.init({
-  publishableKey: 'pk_test_xxx'
-});
-// Redirect to hosted checkout
-await recur.redirectToCheckout({
+// 程式控制開啟結帳
+Recur.popup({
   productId: 'prod_xxx',
-  successUrl: 'https://yoursite.com/success',
-  cancelUrl: 'https://yoursite.com/cancel',
+  key: 'pk_live_xxx',
+  email: 'user@example.com',
+  name: '王小明'
 });
-```
----
-## 🔑 Get Your API Key
+// 關閉結帳視窗
+Recur.close();
+```
-1. Go to your Recur dashboard
-2. Navigate to **Settings** → **API Keys**
-3. Click **Create Publishable Key**
-4. Copy your `pk_test_...` or `pk_live_...` key
+**Data 屬性：**
-> ⚠️ **Never** use your secret key (`sk_*`) in client-side code!
+| 屬性 | 說明 |
+|------|------|
+| `data-key` | Publishable Key（必填） |
+| `data-email` | 預填 Email |
+| `data-name` | 預填姓名 |
 ---
-## 📖 Documentation
-### Checkout Modes
-#### Embedded Mode (Recommended)
+### 方式二：Floating Widget（浮動按鈕）
-Embed the full payment form directly in your page with PAYUNi credit card fields:
-```tsx
-const { checkout } = useRecur();
+像 Buy Me a Coffee 一樣的浮動按鈕：
-await checkout({
-  planId: 'plan_xxx',
-  customerEmail: 'user@example.com',
-  customerName: 'John Doe',
-  // mode: 'embedded' is default when containerElementId is configured
-});
+```html
+<script
+  src="https://unpkg.com/recur-tw/dist/widget.js"
+  data-key="pk_live_xxx"
+  data-product="prod_xxx"
+  data-text="訂閱支持"
+  data-color="#667eea"
+  data-position="right"
+></script>
 ```
-**Features:**
-- ✅ Native PAYUNi credit card input fields
-- ✅ No redirects - complete flow in your app
-- ✅ Fully customizable styling
-- ✅ Web Components based (modern, encapsulated)
+**Data 屬性：**
-#### Redirect Mode
+| 屬性 | 說明 | 預設值 |
+|------|------|--------|
+| `data-key` | Publishable Key（必填） | - |
+| `data-product` | 商品 ID（必填） | - |
+| `data-text` | 按鈕文字 | 訂閱支持 |
+| `data-color` | 按鈕顏色 | #667eea |
+| `data-text-color` | 文字顏色 | #ffffff |
+| `data-position` | 位置 (left/right) | right |
+| `data-x-margin` | 水平邊距 (px) | 18 |
+| `data-y-margin` | 垂直邊距 (px) | 18 |
-Redirect to a full-page checkout:
+**JavaScript API：**
-```tsx
-await checkout({
-  planId: 'plan_xxx',
-  mode: 'redirect',
-  successUrl: 'https://yoursite.com/success',
-  cancelUrl: 'https://yoursite.com/cancel',
-});
+```javascript
+RecurWidget.open();    // 開啟結帳視窗
+RecurWidget.close();   // 關閉結帳視窗
+RecurWidget.show();    // 顯示浮動按鈕
+RecurWidget.hide();    // 隱藏浮動按鈕
+RecurWidget.destroy(); // 移除 Widget
 ```
-#### Hosted Checkout Mode (NEW!)
+---
-The simplest integration - no iframe or embedded form needed:
+### 方式三：Vanilla JavaScript
-```tsx
+適合需要更多控制的場景：
+```html
+<script src="https://unpkg.com/recur-tw/dist/recur.umd.js"></script>
+<script>
 const recur = RecurCheckout.init({
-  publishableKey: 'pk_test_xxx'
+  publishableKey: 'pk_live_xxx'
 });
-// Method 1: Redirect to hosted checkout
-await recur.redirectToCheckout({
+// 取得商品列表
+const { products } = await recur.fetchProducts();
+// 開啟結帳（Modal 模式）
+await recur.checkout({
   productId: 'prod_xxx',
-  successUrl: 'https://yoursite.com/success?session_id={CHECKOUT_SESSION_ID}',
-  cancelUrl: 'https://yoursite.com/cancel',
-  customerEmail: 'user@example.com', // optional, pre-fill email
-  mode: 'SUBSCRIPTION', // PAYMENT, SUBSCRIPTION, or SETUP
+  customerEmail: 'user@example.com',
+  customerName: '王小明',
+  mode: 'modal',
+  onPaymentComplete: (result) => {
+    console.log('付款成功！', result);
+  },
+  onError: (error) => {
+    console.error('付款失敗', error);
+  }
 });
-// Method 2: Get session URL without redirecting
-const session = await recur.createCheckoutSession({
+// 或重導到 Hosted Checkout
+await recur.redirectToCheckout({
   productId: 'prod_xxx',
   successUrl: 'https://yoursite.com/success',
-  cancelUrl: 'https://yoursite.com/cancel',
+  cancelUrl: 'https://yoursite.com/cancel'
 });
-console.log(session.url); // https://checkout.recur.tw/cs_xxx
-console.log(session.expiresAt); // Session expires in 30 minutes
+</script>
 ```
-**Checkout Modes:**
-- `PAYMENT` - One-time payment
-- `SUBSCRIPTION` - Recurring subscription (default)
-- `SETUP` - Save card for future charges
----
+**Checkout 模式：**
-### `<recur-checkout>` Web Component
+| 模式 | 說明 |
+|------|------|
+| `modal` | 在 Modal 中開啟付款表單（預設） |
+| `iframe` | 嵌入到指定容器 |
+| `redirect` | 重導到 Hosted Checkout 頁面 |
-A drop-in checkout button that requires zero JavaScript:
-```html
-<recur-checkout
-  publishable-key="pk_test_xxx"
-  product-id="prod_xxx"
-  success-url="/success"
-  cancel-url="/cancel"
-  customer-email="user@example.com"
-  mode="SUBSCRIPTION"
-  button-text="Subscribe Now"
-  button-style="gradient">
-</recur-checkout>
-```
-**Attributes:**
-| Attribute | Required | Description |
-|-----------|----------|-------------|
-| `publishable-key` | Yes | Your Recur publishable key |
-| `product-id` | Yes | The product ID to purchase |
-| `success-url` | Yes | Redirect URL after successful payment |
-| `cancel-url` | Yes | Redirect URL if user cancels |
-| `customer-email` | No | Pre-fill customer email |
-| `mode` | No | `PAYMENT`, `SUBSCRIPTION`, or `SETUP` |
-| `button-text` | No | Button label (default: button content) |
-| `button-style` | No | `primary`, `outline`, or `gradient` |
-| `disabled` | No | Disable the button |
-| `api-base-url` | No | Custom API URL (for development) |
+---
-**Events:**
+### 方式四：React / Next.js
-```javascript
-document.querySelector('recur-checkout').addEventListener('checkout-started', (e) => {
-  console.log('Redirecting to:', e.detail.url);
-});
-document.querySelector('recur-checkout').addEventListener('checkout-error', (e) => {
-  console.error('Error:', e.detail.message);
-});
+```bash
+npm install recur-tw
 ```
----
-### React Hooks
-#### `useProducts()`
+```tsx
+'use client';
-Fetch available products with optional type filtering:
+import { RecurProvider, useProducts, useRecur } from 'recur-tw';
-```tsx
-import { useProducts } from 'recur-tw';
+// 1. 包裝 Provider
+export default function App() {
+  return (
+    <RecurProvider config={{ publishableKey: 'pk_live_xxx' }}>
+      <ProductsPage />
+    </RecurProvider>
+  );
+}
+// 2. 使用 Hooks
 function ProductsPage() {
-  // Fetch all products
-  const { data: products, isLoading, error } = useProducts();
-  // Or filter by type
-  // const { data: subscriptions } = useProducts({ type: 'SUBSCRIPTION' });
-  // const { data: oneTimeProducts } = useProducts({ type: 'ONE_TIME' });
+  const { data: products, isLoading } = useProducts();
+  const { checkout, isCheckingOut } = useRecur();
-  if (isLoading) return <div>Loading...</div>;
-  if (error) return <div>Error: {error.message}</div>;
+  if (isLoading) return <div>載入中...</div>;
   return (
     <div>
       {products?.map((product) => (
-        <div key={product.id}>
-          <span className="badge">
-            {product.type === 'SUBSCRIPTION' ? '訂閱' : '一次性'}
-          </span>
-          <h3>{product.name}</h3>
-          <p>NT${product.price} {product.billingPeriod && `/ ${product.billingPeriod}`}</p>
-          {product.trialDays && product.trialDays > 0 && <p>🎉 {product.trialDays} days free trial</p>}
-        </div>
+        <button
+          key={product.id}
+          onClick={() => checkout({
+            productId: product.id,
+            customerEmail: 'user@example.com',
+            mode: 'modal'
+          })}
+          disabled={isCheckingOut}
+        >
+          {product.name} - NT${product.price}
+        </button>
       ))}
     </div>
   );
 }
 ```
-**Product Types:**
-- `SUBSCRIPTION` - Recurring subscription products
-- `ONE_TIME` - One-time purchase products
-- `CREDITS` - Credit/token packages
-- `DONATION` - Donation products
-#### `useRecur()`
+**Hooks：**
-Access checkout functionality:
+- `useProducts(options?)` - 取得商品列表
+- `useRecur()` - 取得 checkout 函式與狀態
 ```tsx
-import { useRecur } from 'recur-tw';
-function CheckoutButton({ planId }: { planId: string }) {
-  const { checkout, isCheckingOut, config, updateConfig } = useRecur();
-  return (
-    <button
-      onClick={() => checkout({ planId })}
-      disabled={isCheckingOut}
-    >
-      {isCheckingOut ? 'Processing...' : 'Subscribe'}
-    </button>
-  );
-}
+// 篩選商品類型
+const { data: subscriptions } = useProducts({ type: 'SUBSCRIPTION' });
+const { data: oneTimeProducts } = useProducts({ type: 'ONE_TIME' });
 ```
-**Returns:**
-- `checkout(options)` - Initiate checkout flow
-- `isCheckingOut` - Boolean indicating if checkout is in progress
-- `config` - Current SDK configuration
-- `updateConfig(newConfig)` - Update configuration dynamically
-- `fetchProducts(options)` - Manually fetch products (optionally filter by type)
-- `fetchPlans()` - Fetch subscription products only (backward compat)
 ---
-### Configuration
+### 方式五：`<recur-checkout>` Web Component
-#### RecurProvider Props
+零 JavaScript 的結帳按鈕：
-```tsx
-interface RecurConfig {
-  // Required: Your publishable API key
-  publishableKey: string;
-  // Optional: API base URL (defaults to production)
-  baseUrl?: string;
-  // Optional: Container element ID for embedded checkout
-  containerElementId?: string;
-}
-```
-Example:
-```tsx
-<RecurProvider
-  config={{
-    publishableKey: process.env.NEXT_PUBLIC_RECUR_KEY!,
-    baseUrl: 'https://api.recur.tw', // optional
-    containerElementId: 'recur-payment-container',
-  }}
->
-  {children}
-</RecurProvider>
-```
-#### Checkout Options
-```tsx
-interface CheckoutOptions {
-  // Required: Plan ID to subscribe to
-  planId: string;
-  // Customer information (email is required)
-  customerEmail: string;   // Required: primary customer identifier
-  customerName?: string;
-  // External customer ID - link to your existing users (optional, immutable once set)
-  externalCustomerId?: string;
-  // Checkout mode
-  mode?: 'embedded' | 'redirect'; // Default: 'embedded' if containerElementId is set
-  // Redirect URLs (for redirect mode)
-  successUrl?: string;
-  cancelUrl?: string;
+```html
+<script src="https://unpkg.com/recur-tw/dist/recur.umd.js"></script>
-  // Callbacks
-  onPaymentComplete?: (subscription: Subscription) => void;
-  onError?: (error: CheckoutError) => void;
-}
+<recur-checkout
+  publishable-key="pk_live_xxx"
+  product-id="prod_xxx"
+  success-url="/success"
+  cancel-url="/cancel"
+  button-text="立即訂閱"
+  button-style="gradient">
+</recur-checkout>
 ```
 ---
-### Customer Identification
+## Server SDK
-The SDK uses email as the primary customer identifier, with optional external ID support.
+後端驗證與管理：
-#### Required Fields
+```typescript
+import { RecurServer } from 'recur-tw/server';
-- `customerEmail` - **Required**. Customer's email address (primary identifier)
-- `externalCustomerId` - Optional. Your system's user ID
-#### Using External Customer ID
-The `externalCustomerId` parameter allows you to link Recur subscriptions to your existing user database:
-```tsx
-// React
-await checkout({
-  planId: 'plan_xxx',
-  customerEmail: 'user@example.com',  // Required
-  customerName: 'John Doe',
-  externalCustomerId: 'user_12345',   // Optional: Your system's user ID
+const recur = new RecurServer({
+  secretKey: 'sk_live_xxx'
 });
-// Vanilla JS
-await recur.checkout({
-  planId: 'plan_xxx',
-  customerEmail: 'user@example.com',  // Required
-  externalCustomerId: 'cus_abc456',
+// 建立 Portal Session（讓客戶管理訂閱）
+const session = await recur.portalSessions.create({
+  customerId: 'cus_xxx',
+  returnUrl: 'https://yoursite.com/account'
 });
-// Hosted Checkout
-await recur.redirectToCheckout({
-  productId: 'prod_xxx',
-  successUrl: '/success',
-  cancelUrl: '/cancel',
-  customerEmail: 'user@example.com',  // Required
-  externalCustomerId: 'user_12345',
-});
+// 重導客戶到 Portal
+res.redirect(session.url);
 ```
-#### Customer Resolution Rules
-When processing a checkout:
-1. **externalCustomerId provided** - Looks up customer by external ID first
-   - If found, verifies email matches (throws error if mismatch)
-   - If not found, checks if email already exists
-2. **Email lookup** - If external ID not found or not provided
-   - If email exists and external ID was provided → Error (cannot add external ID to existing customer)
-   - If email exists without external ID → Returns existing customer
-3. **Create new** - Creates a new customer if neither found
-#### Important: External ID is Immutable
-The `externalCustomerId` can only be set when **creating** a customer. Once set:
-- It cannot be changed
-- It cannot be added to an existing customer
-- It cannot be transferred to another customer
-This design ensures data consistency and prevents accidental customer merges.
-#### Retrieving Customer by External ID
-Use the API to retrieve customers by their external ID:
-```bash
-GET /api/v1/subscribers/external/{externalCustomerId}
-```
-#### Best Practices
-- **Always provide email**: Email is required for all checkout operations
-- **Set external ID early**: Include `externalCustomerId` in the initial checkout request when creating customers
-- **Use consistent IDs**: Use your database primary key or UUID as the external ID
-- **Plan ahead**: Decide whether to use external IDs before your first customer signup
 ---
-### Custom Styling
-The SDK uses Web Components with customizable styles. You can override PAYUNi input styles to match your design system.
-#### Default Styling (shadcn/ui compatible)
-The SDK automatically applies shadcn-compatible focus rings:
-```css
-.form-input-focus {
-  border-color: var(--ring, hsl(215 16% 47%)) !important;
-  box-shadow: 0 0 0 3px color-mix(in oklch, var(--ring, hsl(215 16% 47%)) 50%, transparent) !important;
-}
-```
-#### Custom Styling
+## API Key
-Override styles by providing custom CSS:
+1. 前往 Recur Dashboard
+2. **Settings** → **API Keys**
+3. 建立 Publishable Key (`pk_*`) 用於前端
+4. 建立 Secret Key (`sk_*`) 用於後端
-```tsx
-const paymentForm = document.createElement('recur-payment-form');
-paymentForm.setAttribute('custom-styles', `
-  /* Custom focus style */
-  .form-input-focus {
-    border-color: #3b82f6 !important;
-    box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.2) !important;
-  }
-  /* Adjust container heights */
-  #recur-payment-container-card-no,
-  #recur-payment-container-card-exp,
-  #recur-payment-container-card-cvc {
-    height: 40px !important;
-  }
-`);
-```
-The custom styles are injected into the Light DOM, allowing them to affect PAYUNi's iframe elements while keeping other UI styles encapsulated.
+> **注意：** 永遠不要在前端使用 Secret Key！
 ---
-### Advanced Examples
-#### Embedded Checkout with Error Handling
-```tsx
-'use client';
-import { useState } from 'react';
-import { useRecur } from 'recur-tw';
-export function CheckoutForm({ planId }: { planId: string }) {
-  const { checkout, isCheckingOut } = useRecur();
-  const [error, setError] = useState<string | null>(null);
-  const handleCheckout = async () => {
-    setError(null);
-    await checkout({
-      planId,
-      customerEmail: 'user@example.com',
-      onPaymentComplete: (subscription) => {
-        console.log('Payment successful!', subscription);
-        // Redirect to success page or show confirmation
-      },
-      onError: (err) => {
-        setError(err.message);
-      },
-    });
-  };
-  return (
-    <div>
-      <button onClick={handleCheckout} disabled={isCheckingOut}>
-        {isCheckingOut ? 'Processing...' : 'Subscribe Now'}
-      </button>
-      {error && <div className="error">{error}</div>}
-      {/* Payment form will appear here */}
-      <div id="recur-payment-container"></div>
-    </div>
-  );
-}
-```
-#### Dynamic Product Selection
-```tsx
-'use client';
+## 商品類型
-import { useState } from 'react';
-import { useProducts, useRecur } from 'recur-tw';
+| 類型 | 說明 |
+|------|------|
+| `SUBSCRIPTION` | 訂閱制商品（週期性扣款） |
+| `ONE_TIME` | 一次性購買 |
+| `CREDITS` | 點數/代幣包 |
+| `DONATION` | 贊助/捐款 |
-export function PricingTable() {
-  // Filter to show only subscription products
-  const { data: products } = useProducts({ type: 'SUBSCRIPTION' });
-  const { checkout, isCheckingOut } = useRecur();
-  const [selectedProduct, setSelectedProduct] = useState<string | null>(null);
-  const handleSelectProduct = async (productId: string) => {
-    setSelectedProduct(productId);
-    await checkout({
-      planId: productId,
-      customerEmail: 'user@example.com',
-      customerName: 'John Doe',
-    });
-  };
-  return (
-    <div>
-      {!selectedProduct ? (
-        // Product selection
-        <div className="products-grid">
-          {products?.map((product) => (
-            <div key={product.id} className="product-card">
-              <h3>{product.name}</h3>
-              <p className="price">NT${product.price} / {product.billingPeriod}</p>
-              {product.trialDays && product.trialDays > 0 && (
-                <p className="trial">🎉 {product.trialDays} day free trial</p>
-              )}
-              <button onClick={() => handleSelectProduct(product.id)}>
-                Select Product
-              </button>
-            </div>
-          ))}
-        </div>
-      ) : (
-        // Payment form
-        <div>
-          <button onClick={() => setSelectedProduct(null)}>← Back to products</button>
-          <div id="recur-payment-container"></div>
-        </div>
-      )}
-    </div>
-  );
-}
-```
+---
-#### Update Config Dynamically
+## 事件
-```tsx
-const { config, updateConfig } = useRecur();
+所有嵌入方式都支援相同的事件：
-// Switch to different API endpoint
-updateConfig({
-  baseUrl: 'https://staging-api.recur.tw'
+```javascript
+// 付款成功
+window.addEventListener('recur:success', (e) => {
+  console.log(e.detail); // { subscriptionId, orderId, ... }
 });
-// Update publishable key
-updateConfig({
-  publishableKey: 'pk_live_xxx'
+// 付款失敗
+window.addEventListener('recur:error', (e) => {
+  console.log(e.detail); // { message, code }
 });
-```
----
-## Web Components Architecture
-The SDK uses modern Web Components for better encapsulation and reusability:
-### RecurPaymentForm Component
-The embedded payment form is a custom element:
-```html
-<recur-payment-form
-  container-id="recur-payment-container"
-  custom-styles="..."
-></recur-payment-form>
-```
-**Features:**
-- Shadow DOM for style isolation
-- Light DOM for PAYUNi iframe integration
-- Custom events for form submission
-- Attribute-based configuration
-**Events:**
-- `submit` - Fired when user submits payment
-- `error` - Fired when an error occurs
-**Custom Styling:**
-Styles are injected into Light DOM to affect PAYUNi iframes:
-```javascript
-paymentForm.setAttribute('custom-styles', `
-  .form-input-focus { /* PAYUNi focus styles */ }
-  #container-card-no { /* Card number field styles */ }
-`);
+// 使用者關閉視窗
+window.addEventListener('recur:close', () => {
+  console.log('Closed');
+});
 ```
 ---
-## TypeScript Support
-The SDK is written in TypeScript and provides full type definitions:
+## TypeScript
-```tsx
+```typescript
 import type {
   RecurConfig,
-  RecurContextValue,
+  Product,
+  ProductsResult,
   CheckoutOptions,
   CheckoutResult,
   CheckoutError,
-  Product,
-  ProductsResult,
-  FetchProductsOptions,
-  Subscription,
-  SubscriptionResult,
-  // Backward compatibility aliases
-  Plan,        // = Product
-  PlansResult, // = ProductsResult
+  Subscription
 } from 'recur-tw';
 ```
-### Type Definitions
-```tsx
-interface Product {
-  id: string;
-  name: string;
-  slug: string;
-  description: string | null;
-  // Product type distinguishes between recurring and one-time purchases
-  type: 'SUBSCRIPTION' | 'ONE_TIME' | 'CREDITS' | 'DONATION';
-  billingPeriod: 'WEEKLY' | 'MONTHLY' | 'YEARLY' | 'ONE_TIME' | 'CUSTOM' | null;
-  price: number;
-  currency: string;
-  trialDays: number | null;
-  metadata: ProductMetadata | null;
-  productFamily?: string | null;
-  displayOrder: number;
-}
-interface FetchProductsOptions {
-  type?: 'SUBSCRIPTION' | 'ONE_TIME' | 'CREDITS' | 'DONATION';
-}
-// Backward compatibility
-type Plan = Product;
-interface Subscription {
-  id: string;
-  status: string;
-  planId: string;
-  amount: number;
-  billingPeriod: string;
-  currentPeriodStart: string;
-  currentPeriodEnd: string;
-}
-interface CheckoutError {
-  code: string;
-  message: string;
-  details?: any;
-}
-```
 ---
-## Error Handling
+## CDN 連結
-All errors are caught and passed to callbacks:
+| 檔案 | 用途 | CDN |
+|------|------|-----|
+| `checkout.js` | Gumroad 風格按鈕 | `https://unpkg.com/recur-tw/dist/checkout.js` |
+| `widget.js` | 浮動按鈕 Widget | `https://unpkg.com/recur-tw/dist/widget.js` |
+| `recur.umd.js` | Vanilla JS 完整版 | `https://unpkg.com/recur-tw/dist/recur.umd.js` |
-```tsx
-await checkout({
-  planId: 'pro-monthly',
-  onError: (error) => {
-    console.error('Error code:', error.code);
-    console.error('Error message:', error.message);
-    // Handle specific errors
-    switch (error.code) {
-      case 'CHECKOUT_ERROR':
-        // Handle checkout initialization error
-        break;
-      case 'PAYMENT_FAILED':
-        // Handle payment failure
-        break;
-      default:
-        // Handle unknown error
-    }
-  },
-});
+或使用 jsDelivr：
+```
+https://cdn.jsdelivr.net/npm/recur-tw/dist/checkout.js
 ```
-Common error codes:
-- `CHECKOUT_ERROR` - Failed to initialize checkout
-- `PAYMENT_FAILED` - Payment processing failed
-- `INVALID_PLAN` - Plan ID not found
-- `API_ERROR` - API request failed
 ---
-## Browser Support
+## 瀏覽器支援
 - Chrome/Edge 90+
 - Firefox 88+
 - Safari 14+
-- Mobile browsers with Web Components support
-The SDK uses modern Web Components (Custom Elements) which are widely supported in modern browsers.
----
-## Examples
-Check out the `/examples` directory for complete working examples:
-- **Next.js Basic** - Full Next.js integration with App Router
-- **Vanilla JS** - Static HTML examples
-- **React SPA** - Create React App example
+- 支援 Web Components 的行動瀏覽器
 ---
-## Migration Guide
-### From v0.2.0 to v0.3.0
-**Breaking Changes:**
-- 移除 `/v1/checkout/init` 端點
-- Vanilla JS `createEmbeddedCheckout()` 改用 `/v1/checkouts` API
-- 付款執行改用 `/v1/checkouts/:id/pay`
-**New API Endpoints:**
-```
-POST   /v1/checkouts          → 建立 checkout session
-GET    /v1/checkouts/:id      → 取得狀態
-POST   /v1/checkouts/:id      → 刷新 SDK Token
-DELETE /v1/checkouts/:id      → 取消
-POST   /v1/checkouts/:id/pay  → 執行付款
-```
-**無需程式碼變更** - SDK 內部已自動遷移到新端點。
-### From v0.0.x to v0.1.0
+## 範例
-**Breaking Changes:**
-- `organizationId` → `publishableKey` in config
-- Checkout now uses Web Components instead of innerHTML
-- New `useProducts()` hook for fetching products (replaces `usePlans()`)
-- Embedded mode is now the default when `containerElementId` is set
+查看 `/examples` 目錄：
-**Migration:**
+- `checkout-button-test.html` - Checkout Button 測試
+- `widget-test.html` - Widget 測試
-```tsx
-// Before
-<RecurProvider config={{ organizationId: 'org_xxx' }}>
-// After
-<RecurProvider config={{ publishableKey: 'pk_test_xxx' }}>
+本地測試：
+```bash
+cd packages/recur-sdk
+pnpm examples
 ```
 ---
-## Contributing
-This is part of the Recur project. Please see the main repository for contribution guidelines.
----
 ## License
-This project is licensed under the [Elastic License 2.0](./LICENSE).
+[Elastic License 2.0](./LICENSE)
-**你可以：**
-- 在你的應用程式中使用此 SDK
+**可以：**
+- 在你的應用程式中免費使用此 SDK
 - 修改程式碼供自己使用
+- 分發修改後的版本（需附帶授權條款並標註修改）
-**你不可以：**
-- 將此 SDK 作為託管服務提供給第三方
+**不可以：**
+- 將此 SDK 作為託管/管理服務提供給第三方
 - 移除或規避授權機制
+- 移除版權聲明或授權資訊
 ---
 ## Support
-- Documentation: https://github.com/kaikhq/recur.tw
 - Issues: https://github.com/kaikhq/recur.tw/issues
 - Email: support@recur.tw