feat: enhance API and hooks documentation for authentication and session management

Author: Thavarshan

src/hooks/useAuth.ts

@@ -1,9 +1,84 @@
+/**
+ * React Query hooks for authentication state management.
+ *
+ * **Architecture:**
+ * Wraps auth API functions with React Query for:
+ * - Caching (reduce redundant API calls)
+ * - Loading states (isLoading, isPending)
+ * - Error handling (error object)
+ * - Optimistic updates (immediate UI feedback)
+ * - Query invalidation (refresh data after mutations)
+ *
+ * **Authentication Flow:**
+ * 1. useRegister/useLogin: Mutate to create session
+ * 2. onSuccess: Invalidate ['me'] query to trigger refetch
+ * 3. useMe: Query fetches current user data
+ * 4. useLogout: Mutate to clear session, clear ['me'] cache
+ *
+ * **Cache Keys:**
+ * - ['me']: Current user data (5-minute stale time)
+ *
+ * **Usage Pattern:**
+ * ```typescript
+ * const { mutate: login, isPending } = useLogin();
+ * const { data: user, isLoading } = useMe();
+ * const { mutate: logout } = useLogout();
+ *
+ * // Login
+ * login({ email, password }, {
+ *   onSuccess: () => navigate('/dashboard'),
+ *   onError: (error) => showToast(error.message),
+ * });
+ *
+ * // Check auth
+ * if (user) {
+ *   // User logged in
+ * }
+ *
+ * // Logout
+ * logout();
+ * ```
+ */
 'use client';
 
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
 import { login, register, logout, fetchMe } from '@/lib/api/auth';
 import type { LoginPayload, RegisterPayload } from '@/lib/api/types';
 
+/**
+ * Login mutation hook.
+ *
+ * **Mutation:**
+ * Calls POST /api/auth/login with credentials.
+ * Sets HttpOnly session cookie on success.
+ *
+ * **Side Effects:**
+ * - onSuccess: Invalidates ['me'] query to refetch user data
+ * - Cookie automatically sent on future requests
+ *
+ * **Usage:**
+ * ```typescript
+ * const { mutate: login, isPending, error } = useLogin();
+ *
+ * login({ email: 'user@example.com', password: 'secret' }, {
+ *   onSuccess: () => {
+ *     showToast('Login successful');
+ *     navigate('/dashboard');
+ *   },
+ *   onError: (error) => {
+ *     showToast(error.message);
+ *   },
+ * });
+ * ```
+ *
+ * **Return Values:**
+ * - mutate: Function to trigger login
+ * - isPending: True while request in flight
+ * - error: Error object if request fails
+ * - data: Response data if successful
+ *
+ * @returns React Query mutation result
+ */
 export function useLogin() {
   const queryClient = useQueryClient();
 
@@ -16,6 +91,50 @@ export function useLogin() {
   });
 }
 
+/**
+ * Registration mutation hook.
+ *
+ * **Mutation:**
+ * Calls POST /api/auth/register with user data.
+ * Creates account and sets HttpOnly session cookie.
+ *
+ * **Side Effects:**
+ * - onSuccess: Invalidates ['me'] query to refetch user data
+ * - User immediately authenticated after registration
+ *
+ * **Validation:**
+ * - email: Must be valid and unique
+ * - password: Minimum 8 characters
+ * - firstName, lastName: Required
+ *
+ * **Usage:**
+ * ```typescript
+ * const { mutate: register, isPending, error } = useRegister();
+ *
+ * register({
+ *   email: 'user@example.com',
+ *   password: 'SecurePass123',
+ *   firstName: 'John',
+ *   lastName: 'Doe',
+ * }, {
+ *   onSuccess: () => {
+ *     showToast('Account created!');
+ *     navigate('/dashboard');
+ *   },
+ *   onError: (error) => {
+ *     showToast(error.message); // e.g., "Email already registered"
+ *   },
+ * });
+ * ```
+ *
+ * **Return Values:**
+ * - mutate: Function to trigger registration
+ * - isPending: True while request in flight
+ * - error: Error object if request fails
+ * - data: Response data if successful
+ *
+ * @returns React Query mutation result
+ */
 export function useRegister() {
   const queryClient = useQueryClient();
 
@@ -28,6 +147,40 @@ export function useRegister() {
   });
 }
 
+/**
+ * Logout mutation hook.
+ *
+ * **Mutation:**
+ * Calls POST /api/auth/logout to clear session.
+ * Clears HttpOnly cookie on server.
+ *
+ * **Side Effects:**
+ * - onSuccess: Sets ['me'] query data to null (immediate UI update)
+ * - onSuccess: Invalidates ['me'] query (trigger refetch if component still mounted)
+ *
+ * **Security Note:**
+ * JWT token remains valid until expiration (stateless).
+ * Attacker with stolen token can still use it.
+ * Logout only clears cookie and client cache.
+ *
+ * **Usage:**
+ * ```typescript
+ * const { mutate: logout, isPending } = useLogout();
+ *
+ * logout(undefined, {
+ *   onSuccess: () => {
+ *     showToast('Logged out');
+ *     navigate('/login');
+ *   },
+ * });
+ * ```
+ *
+ * **Return Values:**
+ * - mutate: Function to trigger logout
+ * - isPending: True while request in flight
+ *
+ * @returns React Query mutation result
+ */
 export function useLogout() {
   const queryClient = useQueryClient();
 
@@ -41,6 +194,49 @@ export function useLogout() {
   });
 }
 
+/**
+ * Current user query hook.
+ *
+ * **Query:**
+ * Fetches GET /api/auth/me to get authenticated user.
+ * Requires valid session cookie.
+ *
+ * **Caching:**
+ * - staleTime: 5 minutes (avoid refetch on every navigation)
+ * - retry: false (don't retry on 401, user just not logged in)
+ *
+ * **Usage:**
+ * ```typescript
+ * const { data, isLoading, error } = useMe();
+ *
+ * if (isLoading) return <Spinner />;
+ * if (error) return <LoginPrompt />;
+ * if (data?.user) {
+ *   return <Dashboard user={data.user} />;
+ * }
+ * ```
+ *
+ * **Conditional Fetching:**
+ * ```typescript
+ * // Only fetch if needed
+ * const { data } = useMe(false); // Don't fetch
+ * const { data } = useMe(shouldFetch); // Conditional
+ * ```
+ *
+ * **Return Values:**
+ * - data: { user: User } or undefined
+ * - isLoading: True on initial fetch
+ * - error: Error object if request fails (e.g., 401)
+ *
+ * **Authentication Check:**
+ * ```typescript
+ * const { data: currentUser } = useMe();
+ * const isAuthenticated = Boolean(currentUser?.user);
+ * ```
+ *
+ * @param enabled - Whether to fetch (default: true)
+ * @returns React Query query result
+ */
 export function useMe(enabled = true) {
   return useQuery({
     queryKey: ['me'],