recur-tw 0.10.7 → 0.11.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

@@ -247,7 +247,7 @@ var init_error_display = __esm({
   "src/components/base/error-display.ts"() {
     RecurErrorDisplay = class extends HTMLElement {
       static get observedAttributes() {
-        return ["error", "dismissible"];
+        return ["error", "error-title", "dismissible"];
       }
       constructor() {
         super();
@@ -264,6 +264,9 @@ var init_error_display = __esm({
       get error() {
         return this.getAttribute("error") || "";
       }
+      get errorTitle() {
+        return this.getAttribute("error-title") || "";
+      }
       get isDismissible() {
         return this.getAttribute("dismissible") === "true";
       }
@@ -308,6 +311,14 @@ var init_error_display = __esm({
           flex: 1;
         }
 
+        .recur-sdk__error-title {
+          margin: 0 0 4px 0;
+          font-size: 14px;
+          font-weight: 600;
+          color: var(--recur-error-text, #991b1b);
+          line-height: 1.4;
+        }
+
         .recur-sdk__error-message {
           margin: 0;
           font-size: 14px;
@@ -359,6 +370,7 @@ var init_error_display = __esm({
           <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
         </svg>
         <div class="recur-sdk__error-content">
+          ${this.errorTitle ? `<p class="recur-sdk__error-title">${this.errorTitle}</p>` : ""}
           <p class="recur-sdk__error-message">${this.error}</p>
         </div>
         ${this.isDismissible ? `
@@ -1968,7 +1980,13 @@ var init_payment_form = __esm({
           this.setButtonLoading(false);
         }
       }
-      showError(message) {
+      /**
+       * Show error message in the form
+       * @param options - Either a string message or an object with title and message
+       */
+      showError(options) {
+        const message = typeof options === "string" ? options : options.message;
+        const title = typeof options === "object" ? options.title : void 0;
         let errorContainer = this.querySelector(".recur-sdk__error-container");
         if (!errorContainer) {
           errorContainer = document.createElement("div");
@@ -1978,6 +1996,9 @@ var init_payment_form = __esm({
         }
         const errorDisplay = document.createElement("recur-error-display");
         errorDisplay.setAttribute("error", message);
+        if (title) {
+          errorDisplay.setAttribute("error-title", title);
+        }
         errorDisplay.setAttribute("dismissible", "true");
         errorContainer.innerHTML = "";
         errorContainer.appendChild(errorDisplay);
@@ -2653,16 +2674,27 @@ function toCamelCase(obj) {
 
 // package.json
 var package_default = {
-  version: "0.10.6"};
+  version: "0.11.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",
@@ -2672,6 +2704,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 }));
   }, []);
@@ -3051,6 +3166,46 @@ function RecurProvider({ children, config: initialConfig = {} }) {
             const rawPaymentResult = await paymentResponse.json();
             const paymentResult = toCamelCase(rawPaymentResult);
             console.log("[Recur SDK] Payment executed:", paymentResult);
+            if (paymentResult.success === false && paymentResult.failure) {
+              console.log("[Recur SDK] Payment failed:", paymentResult.failure);
+              const failureError = {
+                code: "PAYMENT_FAILED",
+                message: paymentResult.failure.message || "\u4ED8\u6B3E\u5931\u6557",
+                details: {
+                  failure_code: paymentResult.failure.code,
+                  failure_message: paymentResult.failure.message,
+                  can_retry: paymentResult.failure.canRetry
+                }
+              };
+              let action;
+              if (options.onPaymentFailed) {
+                action = options.onPaymentFailed(failureError);
+              }
+              if (!action) {
+                action = paymentResult.failure.canRetry ? { action: "retry" } : { action: "retry" };
+              }
+              if (action.action === "close") {
+                options.onError?.(failureError);
+                paymentForm.resetButton?.();
+                closeDialog();
+                setIsCheckingOut(false);
+                return;
+              } else if (action.action === "custom") {
+                paymentForm.showError?.({
+                  title: action.customTitle || "\u4ED8\u6B3E\u5931\u6557",
+                  message: action.customMessage || failureError.message
+                });
+                paymentForm.resetButton?.();
+                return;
+              } else {
+                paymentForm.showError?.({
+                  title: "\u4ED8\u6B3E\u5931\u6557",
+                  message: failureError.details?.failure_message || failureError.message
+                });
+                paymentForm.resetButton?.();
+                return;
+              }
+            }
             if (paymentResult.requires3D && paymentResult.redirectUrl) {
               console.log("[Recur SDK] 3D verification required");
               const isMobileOrWebView = /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent) || // Detect common WebView user agents
@@ -3359,7 +3514,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);
@@ -3401,7 +3556,7 @@ function useProducts(options = {}) {
   };
 }
 function useSubscribe(options = {}) {
-  const { onSuccess, onError, onPaymentComplete, onPaymentCancel } = options;
+  const { onSuccess, onError, onPaymentComplete, onPaymentCancel, onPaymentFailed } = options;
   const { checkout, isCheckingOut } = useRecur();
   const [error, setError] = React.useState(null);
   const mutate = React.useCallback(
@@ -3420,6 +3575,9 @@ function useSubscribe(options = {}) {
             setError(err);
             onError?.(err);
           },
+          onPaymentFailed: (err) => {
+            return onPaymentFailed?.(err);
+          },
           onPaymentCancel: () => {
             onPaymentCancel?.();
           }
@@ -3433,7 +3591,7 @@ function useSubscribe(options = {}) {
         onError?.(checkoutError);
       }
     },
-    [checkout, onSuccess, onError, onPaymentComplete, onPaymentCancel]
+    [checkout, onSuccess, onError, onPaymentComplete, onPaymentCancel, onPaymentFailed]
   );
   const reset = React.useCallback(() => {
     setError(null);
@@ -3446,8 +3604,47 @@ 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 check = React.useCallback(
+    (options) => {
+      if (!customer) {
+        return { allowed: false, reason: "no_customer" };
+      }
+      if (entitlements.length === 0) {
+        return { allowed: false, reason: "no_subscription" };
+      }
+      const entitlement = entitlements.find(
+        (e) => e.product === options.product || e.productId === options.product
+      );
+      if (!entitlement) {
+        return { allowed: false, reason: "wrong_product" };
+      }
+      let matchingSubscription;
+      if (subscription && (subscription.product.slug === options.product || subscription.product.id === options.product)) {
+        matchingSubscription = subscription;
+      }
+      return { allowed: true, subscription: matchingSubscription };
+    },
+    [customer, entitlements, subscription]
+  );
+  return {
+    customer,
+    subscription,
+    entitlements,
+    check,
+    refetch,
+    isLoading: isLoading2,
+    error
+  };
+}
 
 exports.RecurProvider = RecurProvider;
+exports.useCustomer = useCustomer;
 exports.usePlans = useProducts;
 exports.useProducts = useProducts;
 exports.useRecur = useRecur;