recur-tw 0.10.8 → 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

@@ -2674,16 +2674,27 @@ function toCamelCase(obj) {
 
 // package.json
 var package_default = {
-  version: "0.10.8"};
+  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",
@@ -2693,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 }));
   }, []);
@@ -3420,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);
@@ -3510,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;

package/dist/index.d.cts

@@ -551,6 +551,173 @@ interface UniPaymentInstance {
     }) => Promise<any>;
     onUpdate?: (callback: (data: any) => void) => void;
 }
+/**
+ * Customer identifier for entitlements lookup
+ * At least one identifier must be provided
+ */
+interface CustomerIdentifier {
+    /**
+     * Customer's email address
+     */
+    email?: string;
+    /**
+     * Customer's external ID from your system
+     */
+    externalId?: string;
+    /**
+     * Customer's internal ID in Recur
+     */
+    id?: string;
+}
+/**
+ * Entitlement status derived from subscription status
+ */
+type EntitlementStatus = 'active' | 'trialing' | 'past_due' | 'canceled';
+/**
+ * An entitlement represents a customer's access to a product
+ * Computed from active subscriptions
+ */
+interface Entitlement {
+    /**
+     * Product slug (URL-friendly identifier)
+     * @example 'pro-plan'
+     */
+    product: string;
+    /**
+     * Product ID
+     * @example 'prod_abc123'
+     */
+    productId: string;
+    /**
+     * Current status of the entitlement
+     */
+    status: EntitlementStatus;
+    /**
+     * Associated subscription ID
+     * @example 'sub_xyz789'
+     */
+    subscriptionId: string;
+}
+/**
+ * Options for the check() method
+ */
+interface CheckOptions {
+    /**
+     * Product slug or ID to check access for
+     * @example 'pro-plan' or 'prod_abc123'
+     */
+    product: string;
+}
+/**
+ * Reason why access was denied
+ */
+type CheckDeniedReason = 'no_customer' | 'no_subscription' | 'expired' | 'wrong_product';
+/**
+ * Result of the check() method
+ */
+interface CheckResult {
+    /**
+     * Whether the customer has access to the product
+     */
+    allowed: boolean;
+    /**
+     * Reason for denial (only present when allowed is false)
+     */
+    reason?: CheckDeniedReason;
+    /**
+     * Associated subscription (only present when allowed is true)
+     */
+    subscription?: EntitlementSubscription;
+}
+/**
+ * Simplified subscription info returned in check result
+ */
+interface EntitlementSubscription {
+    /**
+     * Subscription ID
+     */
+    id: string;
+    /**
+     * Subscription status
+     */
+    status: string;
+    /**
+     * Product information
+     */
+    product: {
+        id: string;
+        slug: string;
+        name: string;
+    };
+    /**
+     * End of current billing period (ISO 8601)
+     */
+    currentPeriodEnd: string;
+}
+/**
+ * Customer info returned from entitlements API
+ */
+interface EntitlementCustomer {
+    /**
+     * Customer ID
+     */
+    id: string;
+    /**
+     * Customer email
+     */
+    email: string;
+    /**
+     * Customer name
+     */
+    name?: string | null;
+    /**
+     * External ID from your system
+     */
+    externalId?: string | null;
+}
+/**
+ * Return type of the useCustomer hook
+ */
+interface UseCustomerResult {
+    /**
+     * Customer information (null if not found or loading)
+     */
+    customer: EntitlementCustomer | null;
+    /**
+     * The most recent active subscription (null if none)
+     */
+    subscription: EntitlementSubscription | null;
+    /**
+     * All active entitlements for this customer
+     */
+    entitlements: Entitlement[];
+    /**
+     * Check if customer has access to a specific product
+     * Synchronous - reads from local cache
+     *
+     * @example
+     * const { allowed } = check({ product: 'pro-plan' });
+     * if (!allowed) return <UpgradePrompt />;
+     */
+    check: (options: CheckOptions) => CheckResult;
+    /**
+     * Manually refresh entitlements from the API
+     * Call this after checkout to update permissions
+     *
+     * @example
+     * await checkout({ productId: 'prod_xxx' });
+     * await refetch(); // Update entitlements
+     */
+    refetch: () => Promise<void>;
+    /**
+     * Whether entitlements are currently being fetched
+     */
+    isLoading: boolean;
+    /**
+     * Error if the last fetch failed
+     */
+    error: Error | null;
+}
 
 /**
  * Recur Payment Form Web Component (混合模式)
@@ -747,6 +914,21 @@ declare global {
 interface RecurProviderProps {
     children: React.ReactNode;
     config?: RecurConfig;
+    /**
+     * Customer identifier for entitlements lookup
+     * When provided, the SDK will fetch the customer's entitlements on mount
+     *
+     * @example
+     * ```tsx
+     * <RecurProvider
+     *   config={{ publishableKey: 'pk_test_xxx' }}
+     *   customer={{ email: user?.email }}
+     * >
+     *   <App />
+     * </RecurProvider>
+     * ```
+     */
+    customer?: CustomerIdentifier;
 }
 /**
  * RecurProvider
@@ -760,7 +942,7 @@ interface RecurProviderProps {
  * </RecurProvider>
  * ```
  */
-declare function RecurProvider({ children, config: initialConfig }: RecurProviderProps): react_jsx_runtime.JSX.Element;
+declare function RecurProvider({ children, config: initialConfig, customer: customerIdentifier }: RecurProviderProps): react_jsx_runtime.JSX.Element;
 
 /**
  * useRecur Hook
@@ -946,4 +1128,111 @@ interface UseSubscribeResult {
  */
 declare function useSubscribe(options?: UseSubscribeOptions): UseSubscribeResult;
 
-export { type CheckoutError, type CheckoutOptions, type CheckoutResult, type Plan, type PlansResult, type Product, type ProductMetadata, type ProductsResult, type RecurConfig, type RecurContextValue, RecurProvider, type RecurProviderProps, type SubscriptionResult, type UseProductsOptions as UsePlansOptions, type UseProductsResult as UsePlansResult, type UseProductsOptions, type UseProductsResult, type UseSubscribeOptions, type UseSubscribeResult, useProducts as usePlans, useProducts, useRecur, useSubscribe };
+/**
+ * useCustomer Hook
+ *
+ * Access customer entitlements and check product access without requiring
+ * your own database or webhook integration. The hook fetches entitlements
+ * from Recur on mount and provides synchronous access via the check() method.
+ *
+ * Must be used within a RecurProvider with a customer identifier:
+ * ```tsx
+ * <RecurProvider
+ *   config={{ publishableKey: 'pk_xxx' }}
+ *   customer={{ email: user?.email }}
+ * >
+ *   <App />
+ * </RecurProvider>
+ * ```
+ *
+ * ## Basic Usage - Permission Check
+ * @example
+ * ```tsx
+ * function PremiumFeature() {
+ *   const { check, isLoading } = useCustomer();
+ *
+ *   if (isLoading) return <Spinner />;
+ *
+ *   const { allowed } = check({ product: 'pro-plan' });
+ *
+ *   if (!allowed) {
+ *     return <UpgradePrompt />;
+ *   }
+ *
+ *   return <PremiumContent />;
+ * }
+ * ```
+ *
+ * ## Display Subscription Status
+ * @example
+ * ```tsx
+ * function AccountPage() {
+ *   const { customer, subscription, entitlements, isLoading } = useCustomer();
+ *
+ *   if (isLoading) return <Spinner />;
+ *
+ *   return (
+ *     <div>
+ *       <h1>Hi, {customer?.name}</h1>
+ *       {subscription ? (
+ *         <>
+ *           <p>Plan: {subscription.product.name}</p>
+ *           <p>Renews: {new Date(subscription.currentPeriodEnd).toLocaleDateString()}</p>
+ *         </>
+ *       ) : (
+ *         <p>No active subscription</p>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * ## Refresh After Checkout
+ * @example
+ * ```tsx
+ * function CheckoutButton({ productId }) {
+ *   const { checkout } = useRecur();
+ *   const { refetch } = useCustomer();
+ *
+ *   const handleCheckout = async () => {
+ *     await checkout({
+ *       productId,
+ *       onPaymentComplete: async () => {
+ *         await refetch(); // Update entitlements after purchase
+ *       },
+ *     });
+ *   };
+ *
+ *   return <button onClick={handleCheckout}>Upgrade</button>;
+ * }
+ * ```
+ *
+ * ## Security Note
+ *
+ * The check() method reads from a local cache and can be bypassed client-side.
+ * Use it only for UI gating. For secure access control, always verify
+ * permissions on your backend using the Server SDK:
+ *
+ * ```typescript
+ * // Backend API route
+ * const { allowed } = await recur.entitlements.check({
+ *   product: 'pro-plan',
+ *   customer: { email: user.email },
+ * });
+ * if (!allowed) return Response.json({ error: 'Forbidden' }, { status: 403 });
+ * ```
+ *
+ * @returns {UseCustomerResult} Object containing:
+ *   - `customer` - Customer info (null if not found)
+ *   - `subscription` - Most recent active subscription (null if none)
+ *   - `entitlements` - Array of all active entitlements
+ *   - `check(options)` - Synchronous permission check
+ *   - `refetch()` - Manual refresh (debounced)
+ *   - `isLoading` - Whether data is being fetched
+ *   - `error` - Error from last fetch attempt
+ *
+ * @throws {Error} If used outside of RecurProvider
+ */
+declare function useCustomer(): UseCustomerResult;
+
+export { type CheckDeniedReason, type CheckOptions, type CheckResult, type CheckoutError, type CheckoutOptions, type CheckoutResult, type CustomerIdentifier, type Entitlement, type EntitlementCustomer, type EntitlementStatus, type EntitlementSubscription, type Plan, type PlansResult, type Product, type ProductMetadata, type ProductsResult, type RecurConfig, type RecurContextValue, RecurProvider, type RecurProviderProps, type SubscriptionResult, type UseCustomerResult, type UseProductsOptions as UsePlansOptions, type UseProductsResult as UsePlansResult, type UseProductsOptions, type UseProductsResult, type UseSubscribeOptions, type UseSubscribeResult, useCustomer, useProducts as usePlans, useProducts, useRecur, useSubscribe };