npm - @diffsome/react - Versions diffs - 1.1.1 → 1.1.3 - Mend

@diffsome/react 1.1.1 → 1.1.3

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

Files changed (4) hide show

package/README.md CHANGED Viewed

@@ -8,25 +8,91 @@ Headless React hooks and providers for Diffsome SDK. Build any e-commerce or CMS
 npm install @diffsome/react @diffsome/sdk
 # or
 yarn add @diffsome/react @diffsome/sdk
+# or
+pnpm add @diffsome/react @diffsome/sdk
 ```
-## Quick Start
+## Configuration
+### Option 1: Environment Variables (Recommended)
+**Next.js** (`.env.local`)
+```bash
+NEXT_PUBLIC_DIFFSOME_TENANT_ID=my-store
+NEXT_PUBLIC_DIFFSOME_API_KEY=pky_xxx        # optional
+NEXT_PUBLIC_DIFFSOME_BASE_URL=https://api.diffsome.com  # optional
+```
+**Create React App** (`.env`)
+```bash
+REACT_APP_DIFFSOME_TENANT_ID=my-store
+REACT_APP_DIFFSOME_API_KEY=pky_xxx
+```
+Then simply wrap your app:
 ```tsx
-import { DiffsomeProvider, useAuth, useCart, useProducts } from '@diffsome/react';
+import { DiffsomeProvider } from '@diffsome/react';
 function App() {
   return (
-    <DiffsomeProvider
-      config={{
-        tenantId: 'my-store',
-        apiKey: 'pky_your_api_key',
-      }}
-    >
-      <Shop />
+    <DiffsomeProvider>
+      <YourApp />
     </DiffsomeProvider>
   );
 }
+```
+### Option 2: Direct Config
+```tsx
+<DiffsomeProvider
+  config={{
+    tenantId: 'my-store',           // required
+    apiKey: 'pky_xxx',              // optional
+    baseUrl: 'https://api.diffsome.com',  // optional
+    persistToken: true,             // default: true
+    storageType: 'localStorage',    // 'localStorage' | 'sessionStorage'
+  }}
+>
+  <YourApp />
+</DiffsomeProvider>
+```
+### Next.js App Router Setup
+```tsx
+// app/providers.tsx
+'use client';
+import { DiffsomeProvider } from '@diffsome/react';
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <DiffsomeProvider>
+      {children}
+    </DiffsomeProvider>
+  );
+}
+// app/layout.tsx
+import { Providers } from './providers';
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}
+```
+## Quick Start
+```tsx
+import { DiffsomeProvider, useAuth, useCart, useProducts } from '@diffsome/react';
 function Shop() {
   const { user, login, logout } = useAuth();
@@ -62,29 +128,34 @@ function Shop() {
 ## Available Hooks
 ### Authentication
-- `useAuth()` - Login, register, logout, profile management
+- `useAuth()` - Login, register, logout, profile, password reset
 - `useSocialAuth()` - Social login (Google, Kakao, Naver, etc.)
 ### E-commerce
 - `useCart()` - Cart management (add, update, remove items)
-- `useWishlist()` - Wishlist management
-- `useProducts()` - Product listing with pagination
+- `useWishlist()` - Wishlist management with toggle
+- `useProducts(options?)` - Product listing with pagination & search
 - `useProduct(slug)` - Single product details
 - `useCategories()` - Product categories
-- `useFeaturedProducts()` - Featured products
+- `useFeaturedProducts(limit?)` - Featured products
+- `useProductsByType(type)` - Products by type (digital, subscription, bundle)
+- `useDigitalProducts()` - Digital products shorthand
+- `useSubscriptionProducts()` - Subscription products shorthand
+- `useBundleProducts()` - Bundle products shorthand
+- `useBundleItems(slug)` - Bundle items with pricing
 - `useOrders()` - Order history
 - `useOrder(id)` - Single order details
 - `useCreateOrder()` - Create new order
 ### Payment
-- `usePaymentStatus()` - Check available payment methods (Toss, Stripe)
+- `usePaymentStatus()` - Check available payment methods
 - `useTossPayment()` - Toss Payments (Korea)
 - `useStripePayment()` - Stripe Payments (Global)
 - `useCoupons()` - User's available coupons
 - `useValidateCoupon()` - Validate coupon code
 ### Subscriptions
-- `useSubscriptions()` - User's subscriptions
+- `useSubscriptions()` - User's subscriptions list
 - `useSubscription(id)` - Single subscription with cancel/pause/resume
 - `useCreateSubscription()` - Create subscription via Stripe
@@ -93,15 +164,18 @@ function Shop() {
 - `useOrderDownloads(orderNumber)` - Downloads for specific order
 ### Reviews
-- `useProductReviews(slug)` - Product reviews
+- `useProductReviews(slug)` - Product reviews with stats
 - `useMyReviews()` - User's reviews
 - `useCanReview(slug)` - Check review eligibility
 - `useCreateReview()` - Create product review
 ### Content
-- `useBlog()` - Blog posts with pagination
+- `useBlog(options?)` - Blog posts with pagination
 - `useBlogPost(slug)` - Single blog post
 - `useBlogCategories()` - Blog categories
+- `useBlogTags()` - Blog tags
+- `useFeaturedBlog(limit?)` - Featured blog posts
+- `useBlogSearch()` - Blog search
 - `useBoards()` - Board listing
 - `useBoard(slug)` - Single board
 - `useBoardPosts(slug)` - Board posts
@@ -112,8 +186,8 @@ function Shop() {
 ### Reservations
 - `useReservationServices()` - Available services
-- `useReservationStaffs()` - Staff members
-- `useAvailableSlots(serviceId, date)` - Time slots
+- `useReservationStaffs(serviceId?)` - Staff members
+- `useAvailableSlots(serviceId, staffId?, date)` - Available time slots
 - `useMyReservations()` - User's reservations
 - `useCreateReservation()` - Create reservation
 - `useReservationSettings()` - Reservation settings
@@ -134,7 +208,7 @@ function Shop() {
 ```tsx
 function LoginForm() {
-  const { user, login, logout, loading, error } = useAuth();
+  const { user, login, logout, forgotPassword, loading, error } = useAuth();
   const [email, setEmail] = useState('');
   const [password, setPassword] = useState('');
@@ -143,6 +217,11 @@ function LoginForm() {
     await login({ email, password });
   };
+  const handleForgotPassword = async () => {
+    await forgotPassword(email);
+    alert('Password reset email sent!');
+  };
   if (user) {
     return (
       <div>
@@ -157,17 +236,53 @@ function LoginForm() {
       <input value={email} onChange={(e) => setEmail(e.target.value)} />
       <input type="password" value={password} onChange={(e) => setPassword(e.target.value)} />
       <button disabled={loading}>Login</button>
+      <button type="button" onClick={handleForgotPassword}>Forgot Password</button>
       {error && <p>{error.message}</p>}
     </form>
   );
 }
 ```
+### useProducts with Filters
+```tsx
+function ProductGrid() {
+  const { products, loading, hasMore, loadMore, search } = useProducts({
+    per_page: 12,
+    category: 'electronics',
+  });
+  const [query, setQuery] = useState('');
+  return (
+    <div>
+      <input
+        placeholder="Search products..."
+        value={query}
+        onChange={(e) => setQuery(e.target.value)}
+        onKeyDown={(e) => e.key === 'Enter' && search(query)}
+      />
+      <div className="grid grid-cols-4 gap-4">
+        {products.map(product => (
+          <ProductCard key={product.id} product={product} />
+        ))}
+      </div>
+      {hasMore && (
+        <button onClick={loadMore} disabled={loading}>
+          Load More
+        </button>
+      )}
+    </div>
+  );
+}
+```
 ### useCart
 ```tsx
 function Cart() {
-  const { items, total, updateItem, removeItem, clearCart } = useCart();
+  const { items, total, updateItem, removeItem, clearCart, applyCoupon } = useCart();
   return (
     <div>
@@ -193,12 +308,17 @@ function Cart() {
 ```tsx
 function WishlistButton({ productId }) {
-  const { isInWishlist, toggleWishlist } = useWishlist();
+  const { isInWishlist, toggleWishlist, getProductWishlistCount } = useWishlist();
+  const [count, setCount] = useState(0);
   const inWishlist = isInWishlist(productId);
+  useEffect(() => {
+    getProductWishlistCount(productId).then(setCount);
+  }, [productId]);
   return (
     <button onClick={() => toggleWishlist(productId)}>
-      {inWishlist ? '❤️' : '🤍'}
+      {inWishlist ? '❤️' : '🤍'} {count}
     </button>
   );
 }
@@ -227,6 +347,65 @@ function CheckoutButton({ orderNumber }) {
 }
 ```
+### useSubscription
+```tsx
+function SubscriptionManager({ subscriptionId }) {
+  const { subscription, cancel, pause, resume, loading } = useSubscription(subscriptionId);
+  if (!subscription) return null;
+  return (
+    <div>
+      <p>Plan: {subscription.plan.name}</p>
+      <p>Status: {subscription.status}</p>
+      <p>Next billing: {subscription.current_period_end}</p>
+      {subscription.status === 'active' && (
+        <>
+          <button onClick={pause}>Pause</button>
+          <button onClick={cancel}>Cancel</button>
+        </>
+      )}
+      {subscription.status === 'paused' && (
+        <button onClick={resume}>Resume</button>
+      )}
+    </div>
+  );
+}
+```
+### useBlogSearch
+```tsx
+function BlogSearch() {
+  const { results, search, loading } = useBlogSearch();
+  const [query, setQuery] = useState('');
+  const handleSearch = () => {
+    search(query);
+  };
+  return (
+    <div>
+      <input
+        value={query}
+        onChange={(e) => setQuery(e.target.value)}
+        placeholder="Search blog..."
+      />
+      <button onClick={handleSearch} disabled={loading}>Search</button>
+      {results.map(post => (
+        <article key={post.id}>
+          <h3>{post.title}</h3>
+          <p>{post.excerpt}</p>
+        </article>
+      ))}
+    </div>
+  );
+}
+```
 ### useComments
 ```tsx
@@ -345,9 +524,24 @@ function CustomComponent() {
 All types are re-exported from `@diffsome/sdk`:
 ```tsx
-import type { Product, Cart, Order, Member, CustomEntity, EntityRecord } from '@diffsome/react';
+import type {
+  Product,
+  Cart,
+  Order,
+  Member,
+  CustomEntity,
+  EntityRecord,
+  BlogPost,
+  Reservation,
+  // ... and more
+} from '@diffsome/react';
 ```
+## Requirements
+- React 18.0+
+- @diffsome/sdk 3.2.0+
 ## License
 MIT

package/dist/index.d.mts CHANGED Viewed

@@ -17,24 +17,75 @@ declare function DiffsomeProvider({ children, config }: DiffsomeProviderProps):
 declare function useDiffsome(): DiffsomeContextValue;
 declare function useClient(): Diffsome;
+/**
+ * Return type for the useAuth hook
+ */
 interface UseAuthReturn {
+    /** Currently logged in user, or null if not authenticated */
     user: Member | null;
+    /** Whether the user is currently authenticated */
     isAuthenticated: boolean;
+    /** Whether an auth operation is in progress */
     loading: boolean;
+    /** Error from the last auth operation, if any */
     error: Error | null;
+    /**
+     * Log in with email and password
+     * @param credentials - { email: string, password: string }
+     * @returns AuthResponse with user and token
+     */
     login: (credentials: LoginCredentials) => Promise<AuthResponse>;
+    /**
+     * Register a new account
+     * @param data - { name: string, email: string, password: string, password_confirmation: string }
+     * @returns AuthResponse with user and token
+     */
     register: (data: RegisterData) => Promise<AuthResponse>;
+    /** Log out and clear session */
     logout: () => Promise<void>;
+    /** Fetch current user profile */
     getProfile: () => Promise<Member>;
+    /**
+     * Update user profile
+     * @param data - { name?: string, email?: string, phone?: string, avatar?: File }
+     */
     updateProfile: (data: UpdateProfileData) => Promise<Member>;
+    /**
+     * Send password reset email
+     * @param email - User's email address
+     */
     forgotPassword: (email: string) => Promise<{
         message: string;
     }>;
+    /**
+     * Reset password with token
+     * @param data - { token: string, email: string, password: string, password_confirmation: string }
+     */
     resetPassword: (data: ResetPasswordData) => Promise<{
         message: string;
     }>;
-    refresh: () => Promise<void>;
-}
+    /** Refresh user profile from server */
+    refresh: () => Promise<void>;
+}
+/**
+ * Hook for user authentication - login, register, logout, profile management
+ *
+ * @example
+ * ```tsx
+ * const { user, login, logout, loading } = useAuth();
+ *
+ * // Login
+ * await login({ email: 'user@example.com', password: 'secret' });
+ *
+ * // Check auth state
+ * if (user) {
+ *   console.log('Logged in as:', user.name);
+ * }
+ *
+ * // Logout
+ * await logout();
+ * ```
+ */
 declare function useAuth(): UseAuthReturn;
 interface UseSocialAuthReturn {
@@ -47,24 +98,90 @@ interface UseSocialAuthReturn {
 }
 declare function useSocialAuth(): UseSocialAuthReturn;
+/**
+ * Return type for the useCart hook
+ */
 interface UseCartReturn {
+    /** Full cart object with metadata */
     cart: Cart | null;
+    /** Array of cart items */
     items: CartItem[];
+    /** Number of unique items in cart */
     itemCount: number;
+    /** Total quantity of all items */
     totalQuantity: number;
+    /** Cart subtotal before shipping */
     subtotal: number;
+    /** Shipping fee */
     shippingFee: number;
+    /** Cart total including shipping */
     total: number;
-    loading: boolean;
-    error: Error | null;
+    /** Whether cart is loading */
+    loading: boolean;
+    /** Error from last cart operation */
+    error: Error | null;
+    /**
+     * Add product to cart
+     * @param productId - Product ID to add
+     * @param quantity - Quantity to add (default: 1)
+     * @param variantId - Optional variant ID for variable products
+     * @param options - Optional custom options
+     * @returns Updated cart
+     */
     addToCart: (productId: number, quantity?: number, variantId?: number, options?: Record<string, string>) => Promise<Cart>;
+    /**
+     * Update item quantity
+     * @param itemId - Cart item ID
+     * @param quantity - New quantity
+     */
     updateItem: (itemId: number, quantity: number) => Promise<Cart>;
+    /**
+     * Remove item from cart
+     * @param itemId - Cart item ID to remove
+     */
     removeItem: (itemId: number) => Promise<Cart>;
+    /** Clear all items from cart */
     clearCart: () => Promise<void>;
+    /** Refresh cart from server */
     refresh: () => Promise<void>;
+    /**
+     * Check if product is in cart
+     * @param productId - Product ID
+     * @param variantId - Optional variant ID
+     */
     isInCart: (productId: number, variantId?: number) => boolean;
+    /**
+     * Get quantity of product in cart
+     * @param productId - Product ID
+     * @param variantId - Optional variant ID
+     * @returns Quantity in cart (0 if not in cart)
+     */
     getItemQuantity: (productId: number, variantId?: number) => number;
 }
+/**
+ * Hook for shopping cart management
+ *
+ * @example
+ * ```tsx
+ * const { items, total, addToCart, removeItem, clearCart } = useCart();
+ *
+ * // Add to cart
+ * await addToCart(123, 2); // Add product ID 123, quantity 2
+ *
+ * // With variant
+ * await addToCart(123, 1, 456); // Product 123, variant 456
+ *
+ * // Display cart
+ * items.map(item => (
+ *   <div key={item.id}>
+ *     {item.product_name} x {item.quantity} = ${item.subtotal}
+ *   </div>
+ * ));
+ *
+ * // Total
+ * console.log('Total:', total);
+ * ```
+ */
 declare function useCart(): UseCartReturn;
 interface UseWishlistReturn {
@@ -83,26 +200,96 @@ interface UseWishlistReturn {
 }
 declare function useWishlist(): UseWishlistReturn;
+/**
+ * Return type for the useProducts hook
+ */
 interface UseProductsReturn {
+    /** Array of products */
     products: Product[];
+    /** Pagination metadata (current_page, last_page, total, per_page) */
     meta: PaginationMeta | null;
+    /** Whether products are loading */
     loading: boolean;
+    /** Error from last operation */
     error: Error | null;
+    /** Whether more pages are available */
     hasMore: boolean;
+    /** Load next page of products (appends to list) */
     loadMore: () => Promise<void>;
+    /** Refresh products from server */
     refresh: () => Promise<void>;
+    /**
+     * Search products by query
+     * @param query - Search term
+     */
     search: (query: string) => Promise<void>;
 }
+/**
+ * Options for useProducts hook
+ */
 interface UseProductsOptions extends ProductListParams {
+    /** Whether to fetch products on mount (default: true) */
     autoFetch?: boolean;
 }
+/**
+ * Hook for fetching products with pagination, filtering, and search
+ *
+ * @param options - Filtering and pagination options
+ * @example
+ * ```tsx
+ * // Basic usage
+ * const { products, loading } = useProducts();
+ *
+ * // With filters
+ * const { products } = useProducts({
+ *   category: 'electronics',
+ *   per_page: 20,
+ *   sort: 'price_low',
+ *   min_price: 10,
+ *   max_price: 100,
+ * });
+ *
+ * // Infinite scroll
+ * const { products, hasMore, loadMore } = useProducts({ per_page: 12 });
+ * // Call loadMore() when user scrolls to bottom
+ *
+ * // Search
+ * const { products, search } = useProducts();
+ * await search('laptop'); // Searches products
+ * ```
+ */
 declare function useProducts(options?: UseProductsOptions): UseProductsReturn;
+/**
+ * Return type for the useProduct hook
+ */
 interface UseProductReturn {
+    /** Product data, or null if not loaded */
     product: Product | null;
-    loading: boolean;
-    error: Error | null;
-    refresh: () => Promise<void>;
-}
+    /** Whether product is loading */
+    loading: boolean;
+    /** Error from last operation */
+    error: Error | null;
+    /** Refresh product from server */
+    refresh: () => Promise<void>;
+}
+/**
+ * Hook for fetching a single product by ID or slug
+ *
+ * @param idOrSlug - Product ID (number) or slug (string)
+ * @example
+ * ```tsx
+ * // By slug (recommended)
+ * const { product, loading } = useProduct('wireless-headphones');
+ *
+ * // By ID
+ * const { product } = useProduct(123);
+ *
+ * // Display product
+ * if (product) {
+ *   console.log(product.name, product.sale_price, product.images);
+ * }
+ * ```
+ */
 declare function useProduct(idOrSlug: number | string): UseProductReturn;
 interface UseCategoriesReturn {
     categories: ProductCategory[];

package/dist/index.d.ts CHANGED Viewed

@@ -17,24 +17,75 @@ declare function DiffsomeProvider({ children, config }: DiffsomeProviderProps):
 declare function useDiffsome(): DiffsomeContextValue;
 declare function useClient(): Diffsome;
+/**
+ * Return type for the useAuth hook
+ */
 interface UseAuthReturn {
+    /** Currently logged in user, or null if not authenticated */
     user: Member | null;
+    /** Whether the user is currently authenticated */
     isAuthenticated: boolean;
+    /** Whether an auth operation is in progress */
     loading: boolean;
+    /** Error from the last auth operation, if any */
     error: Error | null;
+    /**
+     * Log in with email and password
+     * @param credentials - { email: string, password: string }
+     * @returns AuthResponse with user and token
+     */
     login: (credentials: LoginCredentials) => Promise<AuthResponse>;
+    /**
+     * Register a new account
+     * @param data - { name: string, email: string, password: string, password_confirmation: string }
+     * @returns AuthResponse with user and token
+     */
     register: (data: RegisterData) => Promise<AuthResponse>;
+    /** Log out and clear session */
     logout: () => Promise<void>;
+    /** Fetch current user profile */
     getProfile: () => Promise<Member>;
+    /**
+     * Update user profile
+     * @param data - { name?: string, email?: string, phone?: string, avatar?: File }
+     */
     updateProfile: (data: UpdateProfileData) => Promise<Member>;
+    /**
+     * Send password reset email
+     * @param email - User's email address
+     */
     forgotPassword: (email: string) => Promise<{
         message: string;
     }>;
+    /**
+     * Reset password with token
+     * @param data - { token: string, email: string, password: string, password_confirmation: string }
+     */
     resetPassword: (data: ResetPasswordData) => Promise<{
         message: string;
     }>;
-    refresh: () => Promise<void>;
-}
+    /** Refresh user profile from server */
+    refresh: () => Promise<void>;
+}
+/**
+ * Hook for user authentication - login, register, logout, profile management
+ *
+ * @example
+ * ```tsx
+ * const { user, login, logout, loading } = useAuth();
+ *
+ * // Login
+ * await login({ email: 'user@example.com', password: 'secret' });
+ *
+ * // Check auth state
+ * if (user) {
+ *   console.log('Logged in as:', user.name);
+ * }
+ *
+ * // Logout
+ * await logout();
+ * ```
+ */
 declare function useAuth(): UseAuthReturn;
 interface UseSocialAuthReturn {
@@ -47,24 +98,90 @@ interface UseSocialAuthReturn {
 }
 declare function useSocialAuth(): UseSocialAuthReturn;
+/**
+ * Return type for the useCart hook
+ */
 interface UseCartReturn {
+    /** Full cart object with metadata */
     cart: Cart | null;
+    /** Array of cart items */
     items: CartItem[];
+    /** Number of unique items in cart */
     itemCount: number;
+    /** Total quantity of all items */
     totalQuantity: number;
+    /** Cart subtotal before shipping */
     subtotal: number;
+    /** Shipping fee */
     shippingFee: number;
+    /** Cart total including shipping */
     total: number;
-    loading: boolean;
-    error: Error | null;
+    /** Whether cart is loading */
+    loading: boolean;
+    /** Error from last cart operation */
+    error: Error | null;
+    /**
+     * Add product to cart
+     * @param productId - Product ID to add
+     * @param quantity - Quantity to add (default: 1)
+     * @param variantId - Optional variant ID for variable products
+     * @param options - Optional custom options
+     * @returns Updated cart
+     */
     addToCart: (productId: number, quantity?: number, variantId?: number, options?: Record<string, string>) => Promise<Cart>;
+    /**
+     * Update item quantity
+     * @param itemId - Cart item ID
+     * @param quantity - New quantity
+     */
     updateItem: (itemId: number, quantity: number) => Promise<Cart>;
+    /**
+     * Remove item from cart
+     * @param itemId - Cart item ID to remove
+     */
     removeItem: (itemId: number) => Promise<Cart>;
+    /** Clear all items from cart */
     clearCart: () => Promise<void>;
+    /** Refresh cart from server */
     refresh: () => Promise<void>;
+    /**
+     * Check if product is in cart
+     * @param productId - Product ID
+     * @param variantId - Optional variant ID
+     */
     isInCart: (productId: number, variantId?: number) => boolean;
+    /**
+     * Get quantity of product in cart
+     * @param productId - Product ID
+     * @param variantId - Optional variant ID
+     * @returns Quantity in cart (0 if not in cart)
+     */
     getItemQuantity: (productId: number, variantId?: number) => number;
 }
+/**
+ * Hook for shopping cart management
+ *
+ * @example
+ * ```tsx
+ * const { items, total, addToCart, removeItem, clearCart } = useCart();
+ *
+ * // Add to cart
+ * await addToCart(123, 2); // Add product ID 123, quantity 2
+ *
+ * // With variant
+ * await addToCart(123, 1, 456); // Product 123, variant 456
+ *
+ * // Display cart
+ * items.map(item => (
+ *   <div key={item.id}>
+ *     {item.product_name} x {item.quantity} = ${item.subtotal}
+ *   </div>
+ * ));
+ *
+ * // Total
+ * console.log('Total:', total);
+ * ```
+ */
 declare function useCart(): UseCartReturn;
 interface UseWishlistReturn {
@@ -83,26 +200,96 @@ interface UseWishlistReturn {
 }
 declare function useWishlist(): UseWishlistReturn;
+/**
+ * Return type for the useProducts hook
+ */
 interface UseProductsReturn {
+    /** Array of products */
     products: Product[];
+    /** Pagination metadata (current_page, last_page, total, per_page) */
     meta: PaginationMeta | null;
+    /** Whether products are loading */
     loading: boolean;
+    /** Error from last operation */
     error: Error | null;
+    /** Whether more pages are available */
     hasMore: boolean;
+    /** Load next page of products (appends to list) */
     loadMore: () => Promise<void>;
+    /** Refresh products from server */
     refresh: () => Promise<void>;
+    /**
+     * Search products by query
+     * @param query - Search term
+     */
     search: (query: string) => Promise<void>;
 }
+/**
+ * Options for useProducts hook
+ */
 interface UseProductsOptions extends ProductListParams {
+    /** Whether to fetch products on mount (default: true) */
     autoFetch?: boolean;
 }
+/**
+ * Hook for fetching products with pagination, filtering, and search
+ *
+ * @param options - Filtering and pagination options
+ * @example
+ * ```tsx
+ * // Basic usage
+ * const { products, loading } = useProducts();
+ *
+ * // With filters
+ * const { products } = useProducts({
+ *   category: 'electronics',
+ *   per_page: 20,
+ *   sort: 'price_low',
+ *   min_price: 10,
+ *   max_price: 100,
+ * });
+ *
+ * // Infinite scroll
+ * const { products, hasMore, loadMore } = useProducts({ per_page: 12 });
+ * // Call loadMore() when user scrolls to bottom
+ *
+ * // Search
+ * const { products, search } = useProducts();
+ * await search('laptop'); // Searches products
+ * ```
+ */
 declare function useProducts(options?: UseProductsOptions): UseProductsReturn;
+/**
+ * Return type for the useProduct hook
+ */
 interface UseProductReturn {
+    /** Product data, or null if not loaded */
     product: Product | null;
-    loading: boolean;
-    error: Error | null;
-    refresh: () => Promise<void>;
-}
+    /** Whether product is loading */
+    loading: boolean;
+    /** Error from last operation */
+    error: Error | null;
+    /** Refresh product from server */
+    refresh: () => Promise<void>;
+}
+/**
+ * Hook for fetching a single product by ID or slug
+ *
+ * @param idOrSlug - Product ID (number) or slug (string)
+ * @example
+ * ```tsx
+ * // By slug (recommended)
+ * const { product, loading } = useProduct('wireless-headphones');
+ *
+ * // By ID
+ * const { product } = useProduct(123);
+ *
+ * // Display product
+ * if (product) {
+ *   console.log(product.name, product.sale_price, product.images);
+ * }
+ * ```
+ */
 declare function useProduct(idOrSlug: number | string): UseProductReturn;
 interface UseCategoriesReturn {
     categories: ProductCategory[];

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@diffsome/react",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "description": "React hooks and providers for Diffsome SDK - Headless e-commerce & CMS",
   "main": "dist/index.js",
   "module": "dist/index.mjs",