recur-tw 0.5.0 → 0.7.0

package/README.md

@@ -9,7 +9,7 @@ Taiwan-specific subscription checkout SDK with embedded payment forms powered by
 ## 🚀 Features
 
 - ✅ **Hosted Checkout** - Zero-backend integration with `<recur-checkout>` Web Component
-- ✅ **React SDK** - Full React integration with hooks (`usePlans`, `useRecur`)
+- ✅ **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
@@ -53,7 +53,7 @@ Full framework integration with React hooks and embedded checkout:
 ```tsx
 'use client';
 
-import { RecurProvider, usePlans, useRecur } from 'recur-tw';
+import { RecurProvider, useProducts, useRecur } from 'recur-tw';
 
 // 1. Wrap your app with RecurProvider
 export default function App() {
@@ -64,31 +64,33 @@ export default function App() {
         containerElementId: 'recur-payment-container' // For embedded checkout
       }}
     >
-      <SubscriptionPage />
+      <ProductsPage />
     </RecurProvider>
   );
 }
 
-// 2. Fetch plans and checkout
-function SubscriptionPage() {
-  const { data: plans, isLoading } = usePlans();
+// 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 plans...</div>;
+  if (isLoading) return <div>Loading products...</div>;
 
   return (
     <div>
-      {plans?.map((plan) => (
+      {products?.map((product) => (
         <button
-          key={plan.id}
+          key={product.id}
           onClick={() => checkout({
-            planId: plan.id,
+            planId: product.id,
             customerEmail: 'user@example.com',
             customerName: 'John Doe',
           })}
           disabled={isCheckingOut}
         >
-          Subscribe to {plan.name} - NT${plan.price}
+          {/* product.type: 'SUBSCRIPTION' | 'ONE_TIME' | 'CREDITS' | 'DONATION' */}
+          {product.type === 'SUBSCRIPTION' ? 'Subscribe to' : 'Buy'} {product.name} - NT${product.price}
         </button>
       ))}
 
@@ -301,26 +303,34 @@ document.querySelector('recur-checkout').addEventListener('checkout-error', (e)
 
 ### React Hooks
 
-#### `usePlans()`
+#### `useProducts()`
 
-Fetch available subscription plans:
+Fetch available products with optional type filtering:
 
 ```tsx
-import { usePlans } from 'recur-tw';
+import { useProducts } from 'recur-tw';
 
-function PlansPage() {
-  const { data: plans, isLoading, error } = usePlans();
+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' });
 
   if (isLoading) return <div>Loading...</div>;
   if (error) return <div>Error: {error.message}</div>;
 
   return (
     <div>
-      {plans?.map((plan) => (
-        <div key={plan.id}>
-          <h3>{plan.name}</h3>
-          <p>NT${plan.price} / {plan.billingPeriod}</p>
-          {plan.trialDays > 0 && <p>🎉 {plan.trialDays} days free trial</p>}
+      {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>
       ))}
     </div>
@@ -328,6 +338,12 @@ function PlansPage() {
 }
 ```
 
+**Product Types:**
+- `SUBSCRIPTION` - Recurring subscription products
+- `ONE_TIME` - One-time purchase products
+- `CREDITS` - Credit/token packages
+- `DONATION` - Donation products
+
 #### `useRecur()`
 
 Access checkout functionality:
@@ -354,7 +370,8 @@ function CheckoutButton({ planId }: { planId: string }) {
 - `isCheckingOut` - Boolean indicating if checkout is in progress
 - `config` - Current SDK configuration
 - `updateConfig(newConfig)` - Update configuration dynamically
-- `fetchPlans()` - Manually fetch plans
+- `fetchProducts(options)` - Manually fetch products (optionally filter by type)
+- `fetchPlans()` - Fetch subscription products only (backward compat)
 
 ---
 
@@ -581,24 +598,25 @@ export function CheckoutForm({ planId }: { planId: string }) {
 }
 ```
 
-#### Dynamic Plan Selection
+#### Dynamic Product Selection
 
 ```tsx
 'use client';
 
 import { useState } from 'react';
-import { usePlans, useRecur } from 'recur-tw';
+import { useProducts, useRecur } from 'recur-tw';
 
 export function PricingTable() {
-  const { data: plans } = usePlans();
+  // Filter to show only subscription products
+  const { data: products } = useProducts({ type: 'SUBSCRIPTION' });
   const { checkout, isCheckingOut } = useRecur();
-  const [selectedPlan, setSelectedPlan] = useState<string | null>(null);
+  const [selectedProduct, setSelectedProduct] = useState<string | null>(null);
 
-  const handleSelectPlan = async (planId: string) => {
-    setSelectedPlan(planId);
+  const handleSelectProduct = async (productId: string) => {
+    setSelectedProduct(productId);
 
     await checkout({
-      planId,
+      planId: productId,
       customerEmail: 'user@example.com',
       customerName: 'John Doe',
     });
@@ -606,18 +624,18 @@ export function PricingTable() {
 
   return (
     <div>
-      {!selectedPlan ? (
-        // Plan selection
-        <div className="plans-grid">
-          {plans?.map((plan) => (
-            <div key={plan.id} className="plan-card">
-              <h3>{plan.name}</h3>
-              <p className="price">NT${plan.price} / {plan.billingPeriod}</p>
-              {plan.trialDays > 0 && (
-                <p className="trial">🎉 {plan.trialDays} day free trial</p>
+      {!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={() => handleSelectPlan(plan.id)}>
-                Select Plan
+              <button onClick={() => handleSelectProduct(product.id)}>
+                Select Product
               </button>
             </div>
           ))}
@@ -625,7 +643,7 @@ export function PricingTable() {
       ) : (
         // Payment form
         <div>
-          <button onClick={() => setSelectedPlan(null)}>← Back to plans</button>
+          <button onClick={() => setSelectedProduct(null)}>← Back to products</button>
           <div id="recur-payment-container"></div>
         </div>
       )}
@@ -700,26 +718,43 @@ import type {
   CheckoutOptions,
   CheckoutResult,
   CheckoutError,
-  Plan,
-  PlansResult,
+  Product,
+  ProductsResult,
+  FetchProductsOptions,
   Subscription,
   SubscriptionResult,
+  // Backward compatibility aliases
+  Plan,        // = Product
+  PlansResult, // = ProductsResult
 } from 'recur-tw';
 ```
 
 ### Type Definitions
 
 ```tsx
-interface Plan {
+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;
-  billingPeriod: 'WEEKLY' | 'MONTHLY' | 'YEARLY' | 'CUSTOM';
-  trialDays: number;
-  description?: string;
-  features?: Record<string, any>;
+  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;
@@ -819,7 +854,7 @@ POST   /v1/checkouts/:id/pay  → 執行付款
 **Breaking Changes:**
 - `organizationId` → `publishableKey` in config
 - Checkout now uses Web Components instead of innerHTML
-- New `usePlans()` hook for fetching plans
+- New `useProducts()` hook for fetching products (replaces `usePlans()`)
 - Embedded mode is now the default when `containerElementId` is set
 
 **Migration:**

package/dist/index.cjs

@@ -2695,13 +2695,17 @@ function RecurProvider({ children, config: initialConfig = {} }) {
     },
     [config]
   );
-  const fetchPlans = React.useCallback(
-    async () => {
+  const fetchProducts = React.useCallback(
+    async (options) => {
       if (!config.publishableKey) {
         throw new Error("publishableKey is required");
       }
       const baseUrl = config.baseUrl || "https://api.recur.tw";
-      const response = await fetch(`${baseUrl}/v1/plans`, {
+      const url = new URL(`${baseUrl}/v1/products`);
+      if (options?.type) {
+        url.searchParams.set("type", options.type);
+      }
+      const response = await fetch(url.toString(), {
         method: "GET",
         headers: {
           "Content-Type": "application/json",
@@ -2710,21 +2714,29 @@ function RecurProvider({ children, config: initialConfig = {} }) {
       });
       if (!response.ok) {
         const errorData = await response.json().catch(() => ({}));
-        throw new Error(errorData.error || "Failed to fetch plans");
+        throw new Error(errorData.error || "Failed to fetch products");
       }
       return await response.json();
     },
     [config]
   );
+  const fetchPlans = React.useCallback(
+    async () => {
+      const result = await fetchProducts({ type: "SUBSCRIPTION" });
+      return { plans: result.products };
+    },
+    [fetchProducts]
+  );
   const value = React.useMemo(
     () => ({
       config,
       checkout,
+      fetchProducts,
       fetchPlans,
       isCheckingOut,
       updateConfig
     }),
-    [config, checkout, fetchPlans, isCheckingOut, updateConfig]
+    [config, checkout, fetchProducts, fetchPlans, isCheckingOut, updateConfig]
   );
   return /* @__PURE__ */ jsxRuntime.jsx(RecurContext.Provider, { value, children });
 }
@@ -2735,9 +2747,9 @@ function useRecur() {
   }
   return context;
 }
-function usePlans(options = {}) {
-  const { enabled = true, onSuccess, onError } = options;
-  const { fetchPlans } = useRecur();
+function useProducts(options = {}) {
+  const { enabled = true, type, onSuccess, onError } = options;
+  const { fetchProducts } = useRecur();
   const [data, setData] = React.useState(void 0);
   const [isLoading2, setIsLoading] = React.useState(false);
   const [error, setError] = React.useState(null);
@@ -2746,17 +2758,17 @@ function usePlans(options = {}) {
     setIsLoading(true);
     setError(null);
     try {
-      const result = await fetchPlans();
-      setData(result.plans);
-      onSuccess?.(result.plans);
+      const result = await fetchProducts({ type });
+      setData(result.products);
+      onSuccess?.(result.products);
     } catch (err) {
-      const error2 = err instanceof Error ? err : new Error("Failed to fetch plans");
+      const error2 = err instanceof Error ? err : new Error("Failed to fetch products");
       setError(error2);
       onError?.(error2);
     } finally {
       setIsLoading(false);
     }
-  }, [enabled, fetchPlans, onSuccess, onError]);
+  }, [enabled, type, fetchProducts, onSuccess, onError]);
   React.useEffect(() => {
     fetchData();
   }, [fetchData]);
@@ -2815,6 +2827,7 @@ function useSubscribe(options = {}) {
 }
 
 exports.RecurProvider = RecurProvider;
-exports.usePlans = usePlans;
+exports.usePlans = useProducts;
+exports.useProducts = useProducts;
 exports.useRecur = useRecur;
 exports.useSubscribe = useSubscribe;

package/dist/index.d.cts

@@ -325,24 +325,34 @@ interface ProductMetadata {
     /** Whether this is the primary/default variant */
     isMainVariant?: boolean;
 }
-interface Plan {
+interface Product {
     id: string;
     name: string;
     slug: string;
     description: string | null;
-    billingPeriod: 'WEEKLY' | 'MONTHLY' | 'YEARLY' | 'CUSTOM';
+    type: 'SUBSCRIPTION' | 'ONE_TIME' | 'CREDITS' | 'DONATION';
+    billingPeriod: 'WEEKLY' | 'MONTHLY' | 'YEARLY' | 'ONE_TIME' | 'CUSTOM' | null;
     price: number;
-    trialDays: number;
-    /** Customer-facing features (e.g., storage limits, support level) */
-    features: Record<string, unknown> | null;
+    currency: string;
+    trialDays: number | null;
     /** System metadata for grouping and organization */
     metadata: ProductMetadata | null;
     /** Convenience field: extracted from metadata.productFamily for easier access */
     productFamily?: string | null;
     displayOrder: number;
 }
+interface ProductsResult {
+    products: Product[];
+}
+type Plan = Product;
 interface PlansResult {
-    plans: Plan[];
+    plans: Product[];
+}
+interface FetchProductsOptions {
+    /**
+     * Filter by product type
+     */
+    type?: 'SUBSCRIPTION' | 'ONE_TIME' | 'CREDITS' | 'DONATION';
 }
 interface RecurContextValue {
     /**
@@ -354,7 +364,12 @@ interface RecurContextValue {
      */
     checkout: (options: CheckoutOptions) => Promise<void>;
     /**
-     * Fetch available subscription plans
+     * Fetch available products
+     */
+    fetchProducts: (options?: FetchProductsOptions) => Promise<ProductsResult>;
+    /**
+     * @deprecated Use fetchProducts instead
+     * Fetch available subscription plans (backward compatibility)
      */
     fetchPlans: () => Promise<PlansResult>;
     /**
@@ -558,28 +573,32 @@ declare function RecurProvider({ children, config: initialConfig }: RecurProvide
  */
 declare function useRecur(): RecurContextValue;
 
-interface UsePlansOptions {
+interface UseProductsOptions {
     /**
-     * Whether to fetch plans immediately on mount
+     * Whether to fetch products immediately on mount
      * @default true
      */
     enabled?: boolean;
     /**
-     * Callback when plans are fetched successfully
+     * Filter by product type
      */
-    onSuccess?: (plans: Plan[]) => void;
+    type?: 'SUBSCRIPTION' | 'ONE_TIME' | 'CREDITS' | 'DONATION';
+    /**
+     * Callback when products are fetched successfully
+     */
+    onSuccess?: (products: Product[]) => void;
     /**
      * Callback when an error occurs
      */
     onError?: (error: Error) => void;
 }
-interface UsePlansResult {
+interface UseProductsResult {
     /**
-     * The fetched plans data
+     * The fetched products data
      */
-    data: Plan[] | undefined;
+    data: Product[] | undefined;
     /**
-     * Whether the plans are currently being fetched
+     * Whether the products are currently being fetched
      */
     isLoading: boolean;
     /**
@@ -592,29 +611,38 @@ interface UsePlansResult {
     refetch: () => Promise<void>;
 }
 /**
- * usePlans Hook
+ * useProducts Hook
  *
- * Fetch available subscription plans with automatic state management
+ * Fetch available products with automatic state management
  *
  * @example
  * ```tsx
- * function PlansPage() {
- *   const { data: plans, isLoading, error } = usePlans();
+ * function ProductsPage() {
+ *   const { data: products, isLoading, error } = useProducts();
  *
- *   if (isLoading) return <PlansSkeletonLoader />;
+ *   if (isLoading) return <ProductsSkeletonLoader />;
  *   if (error) return <ErrorMessage error={error} />;
  *
  *   return (
  *     <div>
- *       {plans?.map(plan => (
- *         <PlanCard key={plan.id} plan={plan} />
+ *       {products?.map(product => (
+ *         <ProductCard key={product.id} product={product} />
  *       ))}
  *     </div>
  *   );
  * }
  * ```
+ *
+ * @example Filter by type
+ * ```tsx
+ * // Only fetch subscription products
+ * const { data: subscriptions } = useProducts({ type: 'SUBSCRIPTION' });
+ *
+ * // Only fetch one-time products
+ * const { data: oneTimeProducts } = useProducts({ type: 'ONE_TIME' });
+ * ```
  */
-declare function usePlans(options?: UsePlansOptions): UsePlansResult;
+declare function useProducts(options?: UseProductsOptions): UseProductsResult;
 
 interface UseSubscribeOptions {
     /**
@@ -696,4 +724,4 @@ interface UseSubscribeResult {
  */
 declare function useSubscribe(options?: UseSubscribeOptions): UseSubscribeResult;
 
-export { type CheckoutError, type CheckoutOptions, type CheckoutResult, type Plan, type PlansResult, type ProductMetadata, type RecurConfig, type RecurContextValue, RecurProvider, type RecurProviderProps, type SubscriptionResult, type UsePlansOptions, type UsePlansResult, type UseSubscribeOptions, type UseSubscribeResult, usePlans, useRecur, useSubscribe };
+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 };

package/dist/index.d.ts

@@ -325,24 +325,34 @@ interface ProductMetadata {
     /** Whether this is the primary/default variant */
     isMainVariant?: boolean;
 }
-interface Plan {
+interface Product {
     id: string;
     name: string;
     slug: string;
     description: string | null;
-    billingPeriod: 'WEEKLY' | 'MONTHLY' | 'YEARLY' | 'CUSTOM';
+    type: 'SUBSCRIPTION' | 'ONE_TIME' | 'CREDITS' | 'DONATION';
+    billingPeriod: 'WEEKLY' | 'MONTHLY' | 'YEARLY' | 'ONE_TIME' | 'CUSTOM' | null;
     price: number;
-    trialDays: number;
-    /** Customer-facing features (e.g., storage limits, support level) */
-    features: Record<string, unknown> | null;
+    currency: string;
+    trialDays: number | null;
     /** System metadata for grouping and organization */
     metadata: ProductMetadata | null;
     /** Convenience field: extracted from metadata.productFamily for easier access */
     productFamily?: string | null;
     displayOrder: number;
 }
+interface ProductsResult {
+    products: Product[];
+}
+type Plan = Product;
 interface PlansResult {
-    plans: Plan[];
+    plans: Product[];
+}
+interface FetchProductsOptions {
+    /**
+     * Filter by product type
+     */
+    type?: 'SUBSCRIPTION' | 'ONE_TIME' | 'CREDITS' | 'DONATION';
 }
 interface RecurContextValue {
     /**
@@ -354,7 +364,12 @@ interface RecurContextValue {
      */
     checkout: (options: CheckoutOptions) => Promise<void>;
     /**
-     * Fetch available subscription plans
+     * Fetch available products
+     */
+    fetchProducts: (options?: FetchProductsOptions) => Promise<ProductsResult>;
+    /**
+     * @deprecated Use fetchProducts instead
+     * Fetch available subscription plans (backward compatibility)
      */
     fetchPlans: () => Promise<PlansResult>;
     /**
@@ -558,28 +573,32 @@ declare function RecurProvider({ children, config: initialConfig }: RecurProvide
  */
 declare function useRecur(): RecurContextValue;
 
-interface UsePlansOptions {
+interface UseProductsOptions {
     /**
-     * Whether to fetch plans immediately on mount
+     * Whether to fetch products immediately on mount
      * @default true
      */
     enabled?: boolean;
     /**
-     * Callback when plans are fetched successfully
+     * Filter by product type
      */
-    onSuccess?: (plans: Plan[]) => void;
+    type?: 'SUBSCRIPTION' | 'ONE_TIME' | 'CREDITS' | 'DONATION';
+    /**
+     * Callback when products are fetched successfully
+     */
+    onSuccess?: (products: Product[]) => void;
     /**
      * Callback when an error occurs
      */
     onError?: (error: Error) => void;
 }
-interface UsePlansResult {
+interface UseProductsResult {
     /**
-     * The fetched plans data
+     * The fetched products data
      */
-    data: Plan[] | undefined;
+    data: Product[] | undefined;
     /**
-     * Whether the plans are currently being fetched
+     * Whether the products are currently being fetched
      */
     isLoading: boolean;
     /**
@@ -592,29 +611,38 @@ interface UsePlansResult {
     refetch: () => Promise<void>;
 }
 /**
- * usePlans Hook
+ * useProducts Hook
  *
- * Fetch available subscription plans with automatic state management
+ * Fetch available products with automatic state management
  *
  * @example
  * ```tsx
- * function PlansPage() {
- *   const { data: plans, isLoading, error } = usePlans();
+ * function ProductsPage() {
+ *   const { data: products, isLoading, error } = useProducts();
  *
- *   if (isLoading) return <PlansSkeletonLoader />;
+ *   if (isLoading) return <ProductsSkeletonLoader />;
  *   if (error) return <ErrorMessage error={error} />;
  *
  *   return (
  *     <div>
- *       {plans?.map(plan => (
- *         <PlanCard key={plan.id} plan={plan} />
+ *       {products?.map(product => (
+ *         <ProductCard key={product.id} product={product} />
  *       ))}
  *     </div>
  *   );
  * }
  * ```
+ *
+ * @example Filter by type
+ * ```tsx
+ * // Only fetch subscription products
+ * const { data: subscriptions } = useProducts({ type: 'SUBSCRIPTION' });
+ *
+ * // Only fetch one-time products
+ * const { data: oneTimeProducts } = useProducts({ type: 'ONE_TIME' });
+ * ```
  */
-declare function usePlans(options?: UsePlansOptions): UsePlansResult;
+declare function useProducts(options?: UseProductsOptions): UseProductsResult;
 
 interface UseSubscribeOptions {
     /**
@@ -696,4 +724,4 @@ interface UseSubscribeResult {
  */
 declare function useSubscribe(options?: UseSubscribeOptions): UseSubscribeResult;
 
-export { type CheckoutError, type CheckoutOptions, type CheckoutResult, type Plan, type PlansResult, type ProductMetadata, type RecurConfig, type RecurContextValue, RecurProvider, type RecurProviderProps, type SubscriptionResult, type UsePlansOptions, type UsePlansResult, type UseSubscribeOptions, type UseSubscribeResult, usePlans, useRecur, useSubscribe };
+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 };