@diffsome/react 1.1.2 → 1.1.3

package/dist/index.d.mts

@@ -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

@@ -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

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