recur-tw 0.10.8 → 0.12.0

package/README.md

@@ -211,6 +211,7 @@ function ProductsPage() {
 
 - `useProducts(options?)` - 取得商品列表
 - `useRecur()` - 取得 checkout 函式與狀態
+- `useCustomer()` - 檢查客戶權限與訂閱狀態
 
 ```tsx
 // 篩選商品類型
@@ -218,6 +219,57 @@ const { data: subscriptions } = useProducts({ type: 'SUBSCRIPTION' });
 const { data: oneTimeProducts } = useProducts({ type: 'ONE_TIME' });
 ```
 
+#### 權限檢查（useCustomer）
+
+檢查客戶是否有特定產品的訂閱權限，無需自建資料庫或處理 Webhook：
+
+```tsx
+import { RecurProvider, useCustomer } from 'recur-tw';
+
+// 1. Provider 需傳入 customer 識別資訊
+function App() {
+  const user = useAuth(); // 你的認證系統
+  return (
+    <RecurProvider
+      config={{ publishableKey: 'pk_live_xxx' }}
+      customer={{ email: user?.email }}
+    >
+      <PremiumFeature />
+    </RecurProvider>
+  );
+}
+
+// 2. 使用 check() 檢查權限
+function PremiumFeature() {
+  const { check, isLoading } = useCustomer();
+
+  if (isLoading) return <Spinner />;
+
+  const { allowed } = check({ product: 'pro-plan' });
+
+  if (!allowed) {
+    return <UpgradePrompt />;
+  }
+
+  return <PremiumContent />;
+}
+
+// 3. 顯示訂閱狀態
+function AccountPage() {
+  const { customer, subscription, entitlements } = useCustomer();
+
+  return (
+    <div>
+      <p>方案：{subscription?.product.name}</p>
+      <p>到期日：{subscription?.currentPeriodEnd}</p>
+      <p>擁有權限：{entitlements.map(e => e.product).join(', ')}</p>
+    </div>
+  );
+}
+```
+
+> **安全提醒：** `check()` 從本地快取讀取，可被繞過。僅用於 UI 控制，敏感操作請在後端驗證。
+
 ---
 
 ### 方式五：`<recur-checkout>` Web Component
@@ -244,15 +296,13 @@ const { data: oneTimeProducts } = useProducts({ type: 'ONE_TIME' });
 後端驗證與管理：
 
 ```typescript
-import { RecurServer } from 'recur-tw/server';
+import { Recur } from 'recur-tw/server';
 
-const recur = new RecurServer({
-  secretKey: 'sk_live_xxx'
-});
+const recur = new Recur(process.env.RECUR_SECRET_KEY!);
 
 // 建立 Portal Session（讓客戶管理訂閱）
-const session = await recur.portalSessions.create({
-  customerId: 'cus_xxx',
+const session = await recur.portal.sessions.create({
+  customer: 'cus_xxx',
   returnUrl: 'https://yoursite.com/account'
 });
 
@@ -260,6 +310,60 @@ const session = await recur.portalSessions.create({
 res.redirect(session.url);
 ```
 
+### 權限檢查（Server-side）
+
+在 API 路由中驗證客戶權限，確保安全：
+
+```typescript
+import { Recur } from 'recur-tw/server';
+
+const recur = new Recur(process.env.RECUR_SECRET_KEY!);
+
+// API 路由範例
+export async function GET(request: Request) {
+  const user = await getUser(request);
+
+  // 檢查單一產品權限
+  const { allowed } = await recur.entitlements.check({
+    product: 'pro-plan',
+    customer: { email: user.email },
+  });
+
+  if (!allowed) {
+    return Response.json(
+      { error: '請升級到 Pro 方案' },
+      { status: 403 }
+    );
+  }
+
+  return Response.json(protectedData);
+}
+
+// 列出所有權限
+const { entitlements } = await recur.entitlements.list({
+  customer: { email: 'user@example.com' },
+});
+
+console.log(entitlements);
+// [
+//   { product: 'pro-plan', status: 'active', subscriptionId: 'sub_xxx' },
+//   { product: 'addon-ai', status: 'active', subscriptionId: 'sub_yyy' },
+// ]
+```
+
+**客戶識別方式（擇一）：**
+
+```typescript
+// 方式一：Email（推薦）
+customer: { email: 'user@example.com' }
+
+// 方式二：External ID（你的系統 User ID）
+customer: { externalId: 'usr_12345' }
+
+// 方式三：Recur Customer ID
+customer: { id: 'cus_xxx' }
+```
+
 ---
 
 ## API Key

package/dist/index.cjs

@@ -1048,7 +1048,7 @@ var init_payment_form_shadow = __esm({
 var payment_form_light_default;
 var init_payment_form_light = __esm({
   "src/components/styles/payment-form-light.css"() {
-    payment_form_light_default = "/**\n * Payment Form - Light DOM Styles\n * These styles are applied to slotted content in the Light DOM\n * Using BEM naming convention with 'recur-' prefix for isolation\n */\n\n/* ============================================\n * Order Summary Styles\n * ============================================ */\n.recur-order-summary {\n  background: #f7fafc;\n  border: 1px solid #e2e8f0;\n  border-radius: 8px;\n  padding: 16px;\n}\n\n.recur-order-summary__row {\n  display: flex;\n  justify-content: space-between;\n  align-items: center;\n  margin-bottom: 8px;\n}\n\n.recur-order-summary__row--total {\n  margin-bottom: 0;\n  padding-top: 12px;\n  border-top: 1px solid #e2e8f0;\n}\n\n.recur-order-summary__label {\n  font-size: 14px;\n  color: #4a5568;\n}\n\n.recur-order-summary__value {\n  font-size: 14px;\n  line-height: 20px;\n  font-weight: 500;\n  color: #2d3748;\n  text-align: right;\n  font-variant-numeric: tabular-nums;\n}\n\n.recur-order-summary__total {\n  font-size: 18px;\n  line-height: 26px;\n  font-weight: 700;\n  color: #1a202c;\n  text-align: right;\n  font-variant-numeric: tabular-nums;\n}\n\n/* ============================================\n * Coupon Section Styles\n * ============================================ */\n.recur-coupon {\n  padding: 12px 0;\n  border-top: 1px solid #e2e8f0;\n  margin-top: 12px;\n  min-height: 36px;\n  display: flex;\n  align-items: center;\n}\n\n.recur-coupon__trigger {\n  display: flex;\n  align-items: center;\n  gap: 6px;\n  width: 100%;\n  height: 36px;\n  background: none;\n  border: none;\n  padding: 0;\n  font-size: 14px;\n  line-height: 1;\n  color: #718096;\n  cursor: pointer;\n  transition: color 0.2s;\n}\n\n.recur-coupon__trigger:hover {\n  color: #4a5568;\n}\n\n.recur-coupon__trigger-icon {\n  width: 16px;\n  height: 16px;\n}\n\n.recur-coupon__input-row {\n  display: flex;\n  align-items: center;\n  gap: 8px;\n  width: 100%;\n  height: 36px;\n}\n\n.recur-coupon__input-wrapper {\n  position: relative;\n  flex: 1;\n  min-width: 0;\n}\n\n.recur-coupon__input {\n  width: 100%;\n  height: 36px;\n  padding: 0 32px 0 12px;\n  font-size: 14px;\n  text-transform: uppercase;\n  background-color: #ffffff;\n  border: 1px solid #d1d5db;\n  border-radius: 6px;\n  outline: none;\n  transition: border-color 0.2s, box-shadow 0.2s;\n}\n\n.recur-coupon__input::placeholder {\n  text-transform: none;\n}\n\n.recur-coupon__input:hover:not(:focus) {\n  border-color: #9ca3af;\n}\n\n.recur-coupon__input:focus {\n  border-color: var(--ring, hsl(215 16% 47%));\n  outline: 0;\n  box-shadow: 0 0 0 3px color-mix(in oklch, var(--ring, hsl(215 16% 47%)) 50%, transparent);\n  transition: border-color 0.15s ease-in-out, box-shadow 0.15s ease-in-out;\n}\n\n.recur-coupon__clear {\n  position: absolute;\n  right: 8px;\n  top: 50%;\n  transform: translateY(-50%);\n  background: none;\n  border: none;\n  padding: 4px;\n  cursor: pointer;\n  color: #9ca3af;\n  border-radius: 4px;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  transition: color 0.2s;\n}\n\n.recur-coupon__clear:hover {\n  color: #6b7280;\n}\n\n.recur-coupon__clear-icon {\n  width: 16px;\n  height: 16px;\n}\n\n.recur-coupon__btn {\n  height: 36px;\n  padding: 0 12px;\n  font-size: 14px;\n  font-weight: 500;\n  border-radius: 6px;\n  cursor: pointer;\n  transition: background-color 0.2s, opacity 0.2s;\n  white-space: nowrap;\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n}\n\n.recur-coupon__btn--apply {\n  background: #18181b;\n  color: white;\n  border: none;\n  min-width: 52px;\n}\n\n.recur-coupon__btn--apply .recur-coupon__spinner {\n  width: 14px;\n  height: 14px;\n}\n\n.recur-coupon__btn--apply:hover:not(:disabled) {\n  background: #27272a;\n}\n\n.recur-coupon__btn--apply:disabled {\n  opacity: 0.5;\n  cursor: not-allowed;\n}\n\n.recur-coupon__error {\n  width: 100%;\n  margin-top: 8px;\n  font-size: 13px;\n  color: #dc2626;\n}\n\n.recur-coupon__applied-wrapper {\n  width: 100%;\n}\n\n.recur-coupon__description {\n  font-size: 12px;\n  color: #6b7280;\n  margin: 4px 0 0 22px;\n}\n\n.recur-coupon__bonus {\n  display: flex;\n  align-items: center;\n  gap: 6px;\n  background: #dcfce7;\n  border-radius: 6px;\n  padding: 8px 12px;\n  margin-top: 8px;\n  font-size: 12px;\n  color: #15803d;\n}\n\n.recur-coupon__applied {\n  display: flex;\n  align-items: center;\n  gap: 8px;\n  width: 100%;\n  height: 36px;\n}\n\n.recur-coupon__applied-info {\n  display: flex;\n  align-items: center;\n  gap: 6px;\n  min-width: 0;\n  flex: 1;\n}\n\n.recur-coupon__applied-icon {\n  width: 16px;\n  height: 16px;\n  color: #dc2626;\n  flex-shrink: 0;\n}\n\n.recur-coupon__applied-name {\n  font-size: 14px;\n  font-weight: 500;\n  color: #dc2626;\n  white-space: nowrap;\n}\n\n.recur-coupon__applied-code {\n  font-size: 14px;\n  color: #9ca3af;\n  white-space: nowrap;\n  margin-right: 2px;\n}\n\n.recur-coupon__applied-amount {\n  font-size: 14px;\n  font-weight: 500;\n  color: #dc2626;\n  white-space: nowrap;\n  font-variant-numeric: tabular-nums;\n  flex-shrink: 0;\n  margin-left: auto;\n}\n\n.recur-coupon__remove {\n  background: none;\n  border: none;\n  padding: 4px;\n  cursor: pointer;\n  color: #9ca3af;\n  border-radius: 4px;\n  transition: color 0.2s, background-color 0.2s;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  flex-shrink: 0;\n}\n\n.recur-coupon__remove:hover {\n  color: #6b7280;\n  background: rgba(0, 0, 0, 0.05);\n}\n\n.recur-coupon__remove-icon {\n  width: 14px;\n  height: 14px;\n}\n\n.recur-coupon__spinner {\n  width: 14px;\n  height: 14px;\n  border: 2px solid currentColor;\n  border-top-color: transparent;\n  border-radius: 50%;\n  animation: recur-spin 0.6s linear infinite;\n}\n\n/* Discount Row */\n.recur-order-summary__row--discount {\n  color: #16a34a;\n}\n\n.recur-order-summary__row--discount .recur-order-summary__value {\n  color: #16a34a;\n  font-weight: 500;\n}\n\n/* ============================================\n * Customer Info Styles\n * ============================================ */\n.recur-info-display {\n  background: #f7fafc;\n  border: 1px solid #e2e8f0;\n  border-radius: 6px;\n  padding: 12px;\n  margin-bottom: 8px;\n}\n\n.recur-info-row {\n  margin-bottom: 12px;\n}\n\n.recur-info-row:last-child {\n  margin-bottom: 0;\n}\n\n.recur-info-label {\n  display: block;\n  font-size: 12px;\n  line-height: 16px;\n  color: #718096;\n  margin-bottom: 2px;\n}\n\n.recur-info-value {\n  display: block;\n  font-size: 14px;\n  line-height: 20px;\n  min-height: 20px;\n  color: #2d3748;\n  font-weight: 500;\n  word-break: break-all;\n}\n\n.recur-form-group {\n  margin-bottom: 16px;\n}\n\n.recur-form-label {\n  display: block;\n  font-size: 14px;\n  font-weight: 500;\n  color: #2d3748;\n  margin-bottom: 6px;\n}\n\n.recur-form-input {\n  width: 100%;\n  height: 36px;\n  padding: 0 12px;\n  font-size: 14px;\n  border: 1px solid #d1d5db;\n  border-radius: 6px;\n  transition: border-color 0.2s;\n  box-sizing: border-box;\n}\n\n.recur-form-input:focus {\n  border-color: var(--ring, hsl(215 16% 47%));\n  outline: 0;\n  box-shadow: 0 0 0 3px color-mix(in oklch, var(--ring, hsl(215 16% 47%)) 50%, transparent);\n  transition: border-color 0.15s ease-in-out, box-shadow 0.15s ease-in-out;\n}\n\n.recur-form-input:hover:not(:focus) {\n  border-color: #9ca3af;\n}\n\n/* ============================================\n * Card Fields Styles\n * ============================================ */\n.recur-card-field {\n  margin-bottom: 16px;\n}\n\n.recur-card-field-label {\n  display: block;\n  font-size: 14px;\n  font-weight: 500;\n  color: #2d3748;\n  margin-bottom: 6px;\n}\n\n.recur-payuni-iframe {\n  height: 36px;\n  width: 100%;\n  max-width: 100%;\n  box-sizing: border-box;\n  touch-action: manipulation;\n}\n\n.recur-card-row {\n  display: grid;\n  grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));\n  column-gap: 16px;\n  max-width: 100%;\n  box-sizing: border-box;\n}\n\n.recur-card-field-container {\n  position: relative;\n  touch-action: manipulation;\n}\n\n.recur-card-skeleton {\n  position: absolute;\n  top: 0;\n  left: 0;\n  height: 36px;\n  width: 100%;\n  background: linear-gradient(90deg, #f0f0f0 0%, #e8e8e8 50%, #f0f0f0 100%);\n  background-size: 200% 100%;\n  animation: recur-skeleton-loading 1.5s ease-in-out infinite;\n  border-radius: 4px;\n  z-index: 1;\n  pointer-events: none;\n}\n\n.recur-card-skeleton.hidden {\n  display: none;\n}\n\n@keyframes recur-skeleton-loading {\n  0% { background-position: 200% 0; }\n  100% { background-position: -200% 0; }\n}\n\n/* ============================================\n * Submit Button Styles\n * ============================================ */\n.recur-submit-button {\n  width: 100%;\n  padding: 14px 20px;\n  font-size: 16px;\n  font-weight: 500;\n  color: #ffffff;\n  background: #18181b;\n  border: none;\n  border-radius: 6px;\n  cursor: pointer;\n  transition: background-color 0.2s;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  gap: 8px;\n  box-sizing: border-box;\n}\n\n.recur-submit-button:hover:not(:disabled) {\n  background: #27272a;\n}\n\n.recur-submit-button:disabled {\n  opacity: 0.6;\n  cursor: not-allowed;\n}\n\n.recur-submit-button.loading {\n  cursor: wait;\n}\n\n.recur-loading-spinner {\n  width: 16px;\n  height: 16px;\n  border: 2px solid currentColor;\n  border-top-color: transparent;\n  border-radius: 50%;\n  animation: recur-spin 0.6s linear infinite;\n}\n\n@keyframes recur-spin {\n  to { transform: rotate(360deg); }\n}\n\n/* ============================================\n * Skeleton Loading Styles\n * ============================================ */\n.recur-skeleton {\n  display: inline-block;\n  background: linear-gradient(90deg, #f0f0f0 0%, #e8e8e8 50%, #f0f0f0 100%);\n  background-size: 200% 100%;\n  animation: recur-skeleton-loading 1.5s ease-in-out infinite;\n  border-radius: 4px;\n}\n";
+    payment_form_light_default = "/**\n * Payment Form - Light DOM Styles\n * These styles are applied to slotted content in the Light DOM\n * Using BEM naming convention with 'recur-' prefix for isolation\n */\n\n/* ============================================\n * Order Summary Styles\n * ============================================ */\n.recur-order-summary {\n  background: #f7fafc;\n  border: 1px solid #e2e8f0;\n  border-radius: 8px;\n  padding: 16px;\n}\n\n.recur-order-summary__row {\n  display: flex;\n  justify-content: space-between;\n  align-items: center;\n  margin-bottom: 8px;\n}\n\n.recur-order-summary__row--total {\n  margin-bottom: 0;\n  padding-top: 12px;\n  border-top: 1px solid #e2e8f0;\n}\n\n.recur-order-summary__label {\n  font-size: 14px;\n  color: #4a5568;\n}\n\n.recur-order-summary__value {\n  font-size: 14px;\n  line-height: 20px;\n  font-weight: 500;\n  color: #2d3748;\n  text-align: right;\n  font-variant-numeric: tabular-nums;\n}\n\n.recur-order-summary__total {\n  font-size: 18px;\n  line-height: 26px;\n  font-weight: 700;\n  color: #1a202c;\n  text-align: right;\n  font-variant-numeric: tabular-nums;\n}\n\n/* ============================================\n * Coupon Section Styles\n * ============================================ */\n.recur-coupon {\n  padding: 12px 0;\n  border-top: 1px solid #e2e8f0;\n  margin-top: 12px;\n  min-height: 36px;\n  display: flex;\n  align-items: center;\n}\n\n.recur-coupon__trigger {\n  display: flex;\n  align-items: center;\n  gap: 6px;\n  width: 100%;\n  height: 36px;\n  background: none;\n  border: none;\n  padding: 0;\n  font-size: 14px;\n  line-height: 1;\n  color: #718096;\n  cursor: pointer;\n  transition: color 0.2s;\n}\n\n.recur-coupon__trigger:hover {\n  color: #4a5568;\n}\n\n.recur-coupon__trigger-icon {\n  width: 16px;\n  height: 16px;\n}\n\n.recur-coupon__input-row {\n  display: flex;\n  align-items: center;\n  gap: 8px;\n  width: 100%;\n  height: 36px;\n}\n\n.recur-coupon__input-wrapper {\n  position: relative;\n  flex: 1;\n  min-width: 0;\n}\n\n.recur-coupon__input {\n  width: 100%;\n  height: 36px;\n  padding: 0 32px 0 12px;\n  font-size: 14px;\n  text-transform: uppercase;\n  background-color: #ffffff;\n  border: 1px solid #d1d5db;\n  border-radius: 6px;\n  outline: none;\n  transition: border-color 0.2s, box-shadow 0.2s;\n}\n\n.recur-coupon__input::placeholder {\n  text-transform: none;\n}\n\n.recur-coupon__input:hover:not(:focus) {\n  border-color: #9ca3af;\n}\n\n.recur-coupon__input:focus {\n  border-color: var(--ring, hsl(215 16% 47%));\n  outline: 0;\n  box-shadow: 0 0 0 3px color-mix(in oklch, var(--ring, hsl(215 16% 47%)) 50%, transparent);\n  transition: border-color 0.15s ease-in-out, box-shadow 0.15s ease-in-out;\n}\n\n.recur-coupon__clear {\n  position: absolute;\n  right: 8px;\n  top: 50%;\n  transform: translateY(-50%);\n  background: none;\n  border: none;\n  padding: 4px;\n  cursor: pointer;\n  color: #9ca3af;\n  border-radius: 4px;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  transition: color 0.2s;\n}\n\n.recur-coupon__clear:hover {\n  color: #6b7280;\n}\n\n.recur-coupon__clear-icon {\n  width: 16px;\n  height: 16px;\n}\n\n.recur-coupon__btn {\n  height: 36px;\n  padding: 0 12px;\n  font-size: 14px;\n  font-weight: 500;\n  border-radius: 6px;\n  cursor: pointer;\n  transition: background-color 0.2s, opacity 0.2s;\n  white-space: nowrap;\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n}\n\n.recur-coupon__btn--apply {\n  background: #18181b;\n  color: white;\n  border: none;\n  min-width: 52px;\n}\n\n.recur-coupon__btn--apply .recur-coupon__spinner {\n  width: 14px;\n  height: 14px;\n}\n\n.recur-coupon__btn--apply:hover:not(:disabled) {\n  background: #27272a;\n}\n\n.recur-coupon__btn--apply:disabled {\n  opacity: 0.5;\n  cursor: not-allowed;\n}\n\n.recur-coupon__error {\n  width: 100%;\n  margin-top: 8px;\n  font-size: 13px;\n  color: #dc2626;\n}\n\n.recur-coupon__applied-wrapper {\n  width: 100%;\n}\n\n.recur-coupon__description {\n  font-size: 12px;\n  color: #6b7280;\n  margin: 4px 0 0 22px;\n}\n\n.recur-coupon__bonus {\n  display: flex;\n  align-items: center;\n  gap: 6px;\n  background: #dcfce7;\n  border-radius: 6px;\n  padding: 8px 12px;\n  margin-top: 8px;\n  font-size: 12px;\n  color: #15803d;\n}\n\n.recur-coupon__applied {\n  display: flex;\n  align-items: center;\n  gap: 8px;\n  width: 100%;\n  height: 36px;\n}\n\n.recur-coupon__applied-info {\n  display: flex;\n  align-items: center;\n  gap: 6px;\n  min-width: 0;\n  flex: 1;\n}\n\n.recur-coupon__applied-icon {\n  width: 16px;\n  height: 16px;\n  color: #dc2626;\n  flex-shrink: 0;\n}\n\n.recur-coupon__applied-name {\n  font-size: 14px;\n  font-weight: 500;\n  color: #dc2626;\n  white-space: nowrap;\n}\n\n.recur-coupon__applied-code {\n  font-size: 14px;\n  color: #9ca3af;\n  white-space: nowrap;\n  margin-right: 2px;\n}\n\n.recur-coupon__applied-amount {\n  font-size: 14px;\n  font-weight: 500;\n  color: #dc2626;\n  white-space: nowrap;\n  font-variant-numeric: tabular-nums;\n  flex-shrink: 0;\n  margin-left: auto;\n}\n\n.recur-coupon__remove {\n  background: none;\n  border: none;\n  padding: 4px;\n  cursor: pointer;\n  color: #9ca3af;\n  border-radius: 4px;\n  transition: color 0.2s, background-color 0.2s;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  flex-shrink: 0;\n}\n\n.recur-coupon__remove:hover {\n  color: #6b7280;\n  background: rgba(0, 0, 0, 0.05);\n}\n\n.recur-coupon__remove-icon {\n  width: 14px;\n  height: 14px;\n}\n\n.recur-coupon__spinner {\n  width: 14px;\n  height: 14px;\n  border: 2px solid currentColor;\n  border-top-color: transparent;\n  border-radius: 50%;\n  animation: recur-spin 0.6s linear infinite;\n}\n\n/* Discount Row */\n.recur-order-summary__row--discount {\n  color: #16a34a;\n}\n\n.recur-order-summary__row--discount .recur-order-summary__value {\n  color: #16a34a;\n  font-weight: 500;\n}\n\n/* ============================================\n * Customer Info Styles\n * ============================================ */\n.recur-info-display {\n  background: #f7fafc;\n  border: 1px solid #e2e8f0;\n  border-radius: 6px;\n  padding: 12px;\n  margin-bottom: 8px;\n}\n\n.recur-info-row {\n  margin-bottom: 12px;\n}\n\n.recur-info-row:last-child {\n  margin-bottom: 0;\n}\n\n.recur-info-label {\n  display: block;\n  font-size: 12px;\n  line-height: 16px;\n  color: #718096;\n  margin-bottom: 2px;\n}\n\n.recur-info-value {\n  display: block;\n  font-size: 14px;\n  line-height: 20px;\n  min-height: 20px;\n  color: #2d3748;\n  font-weight: 500;\n  word-break: break-all;\n}\n\n.recur-form-group {\n  margin-bottom: 16px;\n}\n\n.recur-form-label {\n  display: block;\n  font-size: 14px;\n  font-weight: 500;\n  color: #2d3748;\n  margin-bottom: 6px;\n}\n\n.recur-form-input {\n  width: 100%;\n  height: 36px;\n  padding: 0 12px;\n  font-size: 14px;\n  border: 1px solid #d1d5db;\n  border-radius: 6px;\n  transition: border-color 0.2s;\n  box-sizing: border-box;\n}\n\n.recur-form-input:focus {\n  border-color: var(--ring, hsl(215 16% 47%));\n  outline: 0;\n  box-shadow: 0 0 0 3px color-mix(in oklch, var(--ring, hsl(215 16% 47%)) 50%, transparent);\n  transition: border-color 0.15s ease-in-out, box-shadow 0.15s ease-in-out;\n}\n\n.recur-form-input:hover:not(:focus) {\n  border-color: #9ca3af;\n}\n\n/* ============================================\n * Card Fields Styles\n * ============================================ */\n.recur-card-field {\n  margin-bottom: 16px;\n}\n\n.recur-card-field-label {\n  display: block;\n  font-size: 14px;\n  font-weight: 500;\n  color: #2d3748;\n  margin-bottom: 6px;\n}\n\n.recur-payuni-iframe {\n  height: 36px;\n  width: 100%;\n  max-width: 100%;\n  box-sizing: border-box;\n  touch-action: manipulation;\n}\n\n.recur-card-row {\n  display: grid;\n  grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));\n  column-gap: 16px;\n  max-width: 100%;\n  box-sizing: border-box;\n}\n\n.recur-card-field-container {\n  position: relative;\n  touch-action: manipulation;\n}\n\n.recur-card-skeleton {\n  position: absolute;\n  top: 0;\n  left: 0;\n  height: 36px;\n  width: 100%;\n  background: linear-gradient(90deg, #f0f0f0 0%, #e8e8e8 50%, #f0f0f0 100%);\n  background-size: 200% 100%;\n  animation: recur-skeleton-loading 1.5s ease-in-out infinite;\n  border-radius: 4px;\n  z-index: 1;\n  pointer-events: none;\n}\n\n.recur-card-skeleton.hidden {\n  display: none;\n}\n\n@keyframes recur-skeleton-loading {\n  0% { background-position: 200% 0; }\n  100% { background-position: -200% 0; }\n}\n\n/* ============================================\n * Submit Button Styles\n * ============================================ */\n.recur-submit-button {\n  width: 100%;\n  padding: 14px 20px;\n  font-size: 16px;\n  font-weight: 500;\n  color: #ffffff;\n  background: #18181b;\n  border: none;\n  border-radius: 6px;\n  cursor: pointer;\n  transition: background-color 0.2s;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  gap: 8px;\n  box-sizing: border-box;\n}\n\n.recur-submit-button:hover:not(:disabled) {\n  background: #27272a;\n}\n\n.recur-submit-button:disabled {\n  opacity: 0.6;\n  cursor: not-allowed;\n}\n\n.recur-submit-button.loading {\n  cursor: wait;\n}\n\n.recur-loading-spinner {\n  width: 16px;\n  height: 16px;\n  border: 2px solid currentColor;\n  border-top-color: transparent;\n  border-radius: 50%;\n  animation: recur-spin 0.6s linear infinite;\n}\n\n@keyframes recur-spin {\n  to { transform: rotate(360deg); }\n}\n\n/* ============================================\n * Skeleton Loading Styles\n * ============================================ */\n.recur-skeleton {\n  display: inline-block;\n  background: linear-gradient(90deg, #f0f0f0 0%, #e8e8e8 50%, #f0f0f0 100%);\n  background-size: 200% 100%;\n  animation: recur-skeleton-loading 1.5s ease-in-out infinite;\n  border-radius: 4px;\n}\n\n/* ============================================\n * Test Mode Banner Styles\n * ============================================ */\n.recur-test-mode-banner {\n  background: linear-gradient(135deg, #fef3c7 0%, #fde68a 100%);\n  border: 1px solid #f59e0b;\n  border-radius: 8px;\n  margin-bottom: 16px;\n  overflow: hidden;\n}\n\n.recur-test-mode-header {\n  display: flex;\n  justify-content: space-between;\n  align-items: center;\n  padding: 10px 14px;\n  cursor: pointer;\n  user-select: none;\n  transition: background 0.2s;\n}\n\n.recur-test-mode-header:hover {\n  background: rgba(245, 158, 11, 0.1);\n}\n\n.recur-test-mode-badge {\n  font-size: 13px;\n  font-weight: 600;\n  color: #92400e;\n}\n\n.recur-test-mode-toggle {\n  font-size: 12px;\n  color: #b45309;\n}\n\n.recur-test-cards {\n  background: rgba(255, 255, 255, 0.7);\n  padding: 12px 14px;\n  border-top: 1px solid rgba(245, 158, 11, 0.3);\n}\n\n.recur-test-cards-info {\n  font-size: 12px;\n  color: #78350f;\n  margin: 0 0 10px 0;\n}\n\n.recur-test-card {\n  background: white;\n  border: 1px solid #e5e7eb;\n  border-radius: 6px;\n  padding: 10px 12px;\n  margin-bottom: 8px;\n}\n\n.recur-test-card:last-child {\n  margin-bottom: 0;\n}\n\n.recur-test-card-row {\n  display: flex;\n  justify-content: space-between;\n  align-items: center;\n  margin-bottom: 4px;\n}\n\n.recur-test-card-number {\n  font-family: 'SF Mono', 'Monaco', 'Consolas', monospace;\n  font-size: 14px;\n  font-weight: 600;\n  color: #1f2937;\n  letter-spacing: 0.5px;\n}\n\n.recur-test-card-copy {\n  font-size: 11px;\n  font-weight: 500;\n  color: #3b82f6;\n  background: #eff6ff;\n  border: 1px solid #bfdbfe;\n  border-radius: 4px;\n  padding: 3px 8px;\n  cursor: pointer;\n  transition: all 0.2s;\n}\n\n.recur-test-card-copy:hover {\n  background: #dbeafe;\n  border-color: #93c5fd;\n}\n\n.recur-test-card-copy.copied {\n  background: #dcfce7;\n  border-color: #86efac;\n  color: #16a34a;\n}\n\n.recur-test-card-details {\n  display: flex;\n  flex-wrap: wrap;\n  gap: 8px;\n  font-size: 11px;\n  color: #6b7280;\n}\n\n.recur-test-card-desc {\n  color: #374151;\n  font-weight: 500;\n}\n\n.recur-test-card-meta {\n  color: #9ca3af;\n}\n";
   }
 });
 
@@ -1097,6 +1097,8 @@ var init_payment_form = __esm({
         __publicField(this, "customStyles");
         __publicField(this, "_isInitializing", false);
         __publicField(this, "_initializationAborted", false);
+        // Test mode state
+        __publicField(this, "_showTestCardHints", false);
         // Coupon state
         __publicField(this, "_showCouponInput", false);
         __publicField(this, "_couponCode", "");
@@ -1163,6 +1165,8 @@ var init_payment_form = __esm({
       <style>${this.getShadowDOMStyles()}</style>
 
       <div class="payment-form-wrapper">
+        <slot name="test-mode-banner"></slot>
+
         <div class="form-header">
           <h2 class="form-title">訂閱付款</h2>
         </div>
@@ -1199,6 +1203,10 @@ var init_payment_form = __esm({
         ${this.getCustomStyles()}
       </style>
 
+      <div slot="test-mode-banner">
+        ${this.renderTestCardHints()}
+      </div>
+
       <div slot="order-summary">
         ${this.renderOrderSummary()}
       </div>
@@ -1235,6 +1243,63 @@ var init_payment_form = __esm({
         }
       }
       // ============================================
+      // Test Mode Helpers
+      // ============================================
+      isTestMode() {
+        const publishableKey = this.getAttribute("publishable-key") || "";
+        return publishableKey.startsWith("pk_test_");
+      }
+      renderTestCardHints() {
+        if (!this.isTestMode()) {
+          return litHtml.html``;
+        }
+        const testCards = [
+          { number: "4147 6310 0000 0001", desc: "VISA \u6E2C\u8A66\u5361\uFF08\u6388\u6B0A\u6210\u529F\uFF09", expiry: "\u4EFB\u610F\u672A\u4F86\u65E5\u671F", cvc: "\u4EFB\u610F3\u78BC" },
+          { number: "3560 5110 0000 0001", desc: "JCB \u6E2C\u8A66\u5361\uFF08\u6388\u6B0A\u6210\u529F\uFF09", expiry: "\u4EFB\u610F\u672A\u4F86\u65E5\u671F", cvc: "\u4EFB\u610F3\u78BC" },
+          { number: "4147 6310 0000 0002", desc: "VISA \u6E2C\u8A66\u5361\uFF083D\u9A57\u8B49\u5931\u6557\uFF09", expiry: "\u4EFB\u610F\u672A\u4F86\u65E5\u671F", cvc: "\u4EFB\u610F3\u78BC" }
+        ];
+        const copyToClipboard = (text, event) => {
+          const btn = event.currentTarget;
+          navigator.clipboard.writeText(text.replace(/\s/g, "")).then(() => {
+            const originalText = btn.textContent;
+            btn.textContent = "\u5DF2\u8907\u88FD!";
+            btn.classList.add("copied");
+            setTimeout(() => {
+              btn.textContent = originalText;
+              btn.classList.remove("copied");
+            }, 1500);
+          });
+        };
+        return litHtml.html`
+      <div class="recur-test-mode-banner">
+        <div class="recur-test-mode-header" @click=${() => {
+          this._showTestCardHints = !this._showTestCardHints;
+          this.renderLightDOM();
+        }}>
+          <span class="recur-test-mode-badge">🧪 測試模式</span>
+          <span class="recur-test-mode-toggle">${this._showTestCardHints ? "\u6536\u5408 \u25B2" : "\u5C55\u958B\u6E2C\u8A66\u5361\u865F \u25BC"}</span>
+        </div>
+        ${this._showTestCardHints ? litHtml.html`
+          <div class="recur-test-cards">
+            <p class="recur-test-cards-info">使用以下測試卡號進行測試付款：</p>
+            ${testCards.map((card) => litHtml.html`
+              <div class="recur-test-card">
+                <div class="recur-test-card-row">
+                  <span class="recur-test-card-number">${card.number}</span>
+                  <button type="button" class="recur-test-card-copy" @click=${(e) => copyToClipboard(card.number, e)}>複製</button>
+                </div>
+                <div class="recur-test-card-details">
+                  <span class="recur-test-card-desc">${card.desc}</span>
+                  <span class="recur-test-card-meta">到期日: ${card.expiry} / CVC: ${card.cvc}</span>
+                </div>
+              </div>
+            `)}
+          </div>
+        ` : litHtml.nothing}
+      </div>
+    `;
+      }
+      // ============================================
       // Section Renderers (lit-html)
       // ============================================
       renderOrderSummary() {
@@ -1648,16 +1713,16 @@ var init_payment_form = __esm({
           }
           this._appliedCoupon = {
             code: data.discount.code,
-            couponName: data.discount.couponName,
-            discountType: data.discount.discountType,
-            discountAmount: data.discount.discountAmount,
+            couponName: data.discount.coupon_name,
+            discountType: data.discount.discount_type,
+            discountAmount: data.discount.discount_amount,
             duration: data.discount.duration,
-            durationMonths: data.discount.durationMonths,
-            bonusTrialDays: data.discount.bonusTrialDays,
-            bonusMonths: data.discount.bonusMonths,
-            productInterval: data.discount.productInterval,
-            productIntervalCount: data.discount.productIntervalCount,
-            productPrice: data.discount.productPrice
+            durationMonths: data.discount.duration_months,
+            bonusTrialDays: data.discount.bonus_trial_days,
+            bonusMonths: data.discount.bonus_months,
+            productInterval: data.discount.product_interval,
+            productIntervalCount: data.discount.product_interval_count,
+            productPrice: data.discount.product_price
           };
           this._showCouponInput = false;
           this._couponCode = "";
@@ -2674,16 +2739,27 @@ function toCamelCase(obj) {
 
 // package.json
 var package_default = {
-  version: "0.10.8"};
+  version: "0.12.0"};
 var SDK_VERSION = package_default.version;
 var SDK_TYPE = "react";
 var RecurContext = React.createContext(null);
-function RecurProvider({ children, config: initialConfig = {} }) {
+var CustomerContext = React.createContext(null);
+function RecurProvider({ children, config: initialConfig = {}, customer: customerIdentifier }) {
   const [config, setConfig] = React.useState({
     checkoutMode: "embedded",
     ...initialConfig
   });
   const [isCheckingOut, setIsCheckingOut] = React.useState(false);
+  const [customerData, setCustomerData] = React.useState({
+    customer: null,
+    subscription: null,
+    entitlements: []
+  });
+  const [customerIsLoading, setCustomerIsLoading] = React.useState(false);
+  const [customerError, setCustomerError] = React.useState(null);
+  const lastSuccessfulCache = React__default.default.useRef(null);
+  const isRefetching = React__default.default.useRef(false);
+  const refetchDebounceTimer = React__default.default.useRef(null);
   React__default.default.useEffect(() => {
     setConfig({
       checkoutMode: "embedded",
@@ -2693,6 +2769,89 @@ function RecurProvider({ children, config: initialConfig = {} }) {
   React__default.default.useEffect(() => {
     setIsCheckingOut(false);
   }, [config.checkoutMode]);
+  const fetchEntitlements = React.useCallback(async () => {
+    if (!config.publishableKey) {
+      console.warn("[Recur SDK] Cannot fetch entitlements: publishableKey is required");
+      return;
+    }
+    if (!customerIdentifier?.email && !customerIdentifier?.externalId && !customerIdentifier?.id) {
+      setCustomerData({ customer: null, subscription: null, entitlements: [] });
+      return;
+    }
+    setCustomerIsLoading(true);
+    setCustomerError(null);
+    try {
+      const baseUrl = config.baseUrl || "https://api.recur.tw";
+      const params = new URLSearchParams();
+      if (customerIdentifier.email) params.set("email", customerIdentifier.email);
+      if (customerIdentifier.externalId) params.set("external_id", customerIdentifier.externalId);
+      if (customerIdentifier.id) params.set("customer_id", customerIdentifier.id);
+      const response = await fetch(`${baseUrl}/v1/customers/entitlements?${params.toString()}`, {
+        method: "GET",
+        headers: {
+          "X-Recur-Publishable-Key": config.publishableKey,
+          "X-Recur-SDK-Type": SDK_TYPE,
+          "X-Recur-SDK-Version": SDK_VERSION
+        }
+      });
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        throw new Error(errorData.error?.message || "Failed to fetch entitlements");
+      }
+      const rawResult = await response.json();
+      const result = toCamelCase(rawResult);
+      const newData = {
+        customer: result.customer || null,
+        subscription: result.subscription || null,
+        entitlements: result.entitlements || []
+      };
+      setCustomerData(newData);
+      lastSuccessfulCache.current = newData;
+    } catch (error) {
+      console.error("[Recur SDK] Failed to fetch entitlements:", error);
+      setCustomerError(error instanceof Error ? error : new Error("Failed to fetch entitlements"));
+      if (lastSuccessfulCache.current) {
+        setCustomerData(lastSuccessfulCache.current);
+      }
+    } finally {
+      setCustomerIsLoading(false);
+    }
+  }, [config.publishableKey, config.baseUrl, customerIdentifier?.email, customerIdentifier?.externalId, customerIdentifier?.id]);
+  React__default.default.useEffect(() => {
+    fetchEntitlements();
+  }, [fetchEntitlements]);
+  const refetch = React.useCallback(async () => {
+    if (isRefetching.current) {
+      console.log("[Recur SDK] Refetch skipped - already in progress");
+      return;
+    }
+    if (refetchDebounceTimer.current) {
+      clearTimeout(refetchDebounceTimer.current);
+    }
+    isRefetching.current = true;
+    try {
+      await fetchEntitlements();
+    } finally {
+      refetchDebounceTimer.current = setTimeout(() => {
+        isRefetching.current = false;
+      }, 300);
+    }
+  }, [fetchEntitlements]);
+  React__default.default.useEffect(() => {
+    return () => {
+      if (refetchDebounceTimer.current) {
+        clearTimeout(refetchDebounceTimer.current);
+      }
+    };
+  }, []);
+  const customerContextValue = React.useMemo(() => ({
+    customer: customerData.customer,
+    subscription: customerData.subscription,
+    entitlements: customerData.entitlements,
+    isLoading: customerIsLoading,
+    error: customerError,
+    refetch
+  }), [customerData, customerIsLoading, customerError, refetch]);
   const updateConfig = React.useCallback((newConfig) => {
     setConfig((prev) => ({ ...prev, ...newConfig }));
   }, []);
@@ -2894,14 +3053,14 @@ function RecurProvider({ children, config: initialConfig = {} }) {
         }
         console.log("[Recur SDK] Step 1: Creating checkout session...");
         const checkoutRequestBody = {
-          customerName: options.customerName,
-          customerEmail: options.customerEmail
+          customer_name: options.customerName,
+          customer_email: options.customerEmail
         };
-        if (productId) checkoutRequestBody.productId = productId;
-        if (productSlug) checkoutRequestBody.productSlug = productSlug;
-        if (options.externalCustomerId) checkoutRequestBody.externalCustomerId = options.externalCustomerId;
-        if (options.successUrl) checkoutRequestBody.successUrl = options.successUrl;
-        if (options.cancelUrl) checkoutRequestBody.cancelUrl = options.cancelUrl;
+        if (productId) checkoutRequestBody.product_id = productId;
+        if (productSlug) checkoutRequestBody.product_slug = productSlug;
+        if (options.externalCustomerId) checkoutRequestBody.external_customer_id = options.externalCustomerId;
+        if (options.successUrl) checkoutRequestBody.success_url = options.successUrl;
+        if (options.cancelUrl) checkoutRequestBody.cancel_url = options.cancelUrl;
         const checkoutResponse = await fetch(`${baseUrl}/v1/checkouts`, {
           method: "POST",
           headers,
@@ -3420,7 +3579,7 @@ function RecurProvider({ children, config: initialConfig = {} }) {
     }),
     [config, checkout, fetchProducts, fetchPlans, isCheckingOut, updateConfig, getCheckoutStatus]
   );
-  return /* @__PURE__ */ jsxRuntime.jsx(RecurContext.Provider, { value, children });
+  return /* @__PURE__ */ jsxRuntime.jsx(RecurContext.Provider, { value, children: /* @__PURE__ */ jsxRuntime.jsx(CustomerContext.Provider, { value: customerContextValue, children }) });
 }
 function useRecur() {
   const context = React.useContext(RecurContext);
@@ -3510,8 +3669,84 @@ function useSubscribe(options = {}) {
     reset
   };
 }
+function useCustomer() {
+  const context = React.useContext(CustomerContext);
+  if (!context) {
+    throw new Error("useCustomer must be used within a RecurProvider");
+  }
+  const { customer, subscription, entitlements, isLoading: isLoading2, error, refetch } = context;
+  const resolveProduct = (target) => {
+    if (typeof target === "string") {
+      return target;
+    }
+    if ("product" in target) {
+      return target.product;
+    }
+    if ("feature" in target) {
+      throw new Error("Feature-based checks are not yet supported. Coming in Phase 2.");
+    }
+    if ("benefit" in target) {
+      throw new Error("Benefit-based checks are not yet supported. Coming in Phase 2.");
+    }
+    throw new Error("Invalid check target");
+  };
+  const checkSync = React.useCallback(
+    (target) => {
+      const product = resolveProduct(target);
+      if (!customer) {
+        return { allowed: false, reason: "no_customer" };
+      }
+      if (entitlements.length === 0) {
+        return { allowed: false, reason: "no_entitlement" };
+      }
+      const matchedEntitlement = entitlements.find(
+        (e) => e.product === product || e.productId === product
+      );
+      if (!matchedEntitlement) {
+        return { allowed: false, reason: "not_found" };
+      }
+      let matchingSubscription;
+      if (subscription && (subscription.product.slug === product || subscription.product.id === product)) {
+        matchingSubscription = subscription;
+      }
+      return {
+        allowed: true,
+        entitlement: matchedEntitlement,
+        // Backward compatibility
+        subscription: matchingSubscription
+      };
+    },
+    [customer, entitlements, subscription]
+  );
+  const checkLive = React.useCallback(
+    async (target) => {
+      await refetch();
+      return checkSync(target);
+    },
+    [refetch, checkSync]
+  );
+  const check = React.useCallback(
+    (target, options) => {
+      if (options?.live) {
+        return checkLive(target);
+      }
+      return checkSync(target);
+    },
+    [checkSync, checkLive]
+  );
+  return {
+    customer,
+    subscription,
+    entitlements,
+    check,
+    refetch,
+    isLoading: isLoading2,
+    error
+  };
+}
 
 exports.RecurProvider = RecurProvider;
+exports.useCustomer = useCustomer;
 exports.usePlans = useProducts;
 exports.useProducts = useProducts;
 exports.useRecur = useRecur;