create-tigra 2.6.5 → 2.7.0

package/template/client/src/features/admin/hooks/useAdminUsers.ts

@@ -0,0 +1,132 @@
+'use client';
+
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { toast } from 'sonner';
+
+import { getErrorMessage } from '@/lib/utils/error';
+import { adminService } from '../services/admin.service';
+
+import type { IAdminUser, IAdminUserDetail, IGetUsersParams, IGetSessionsParams } from '../types/admin.types';
+
+// ─── Query Key Factory ──────────────────────────────────────────────────────
+
+export const adminKeys = {
+  all: ['admin'] as const,
+  stats: () => [...adminKeys.all, 'stats'] as const,
+  users: () => [...adminKeys.all, 'users'] as const,
+  userList: (params: IGetUsersParams) => [...adminKeys.users(), 'list', params] as const,
+  userDetail: (userId: string) => [...adminKeys.users(), 'detail', userId] as const,
+  sessions: () => [...adminKeys.all, 'sessions'] as const,
+  sessionList: (params: IGetSessionsParams) => [...adminKeys.sessions(), 'list', params] as const,
+};
+
+// ─── User List ──────────────────────────────────────────────────────────────
+
+interface UseAdminUsersReturn {
+  users: IAdminUser[];
+  pagination: {
+    page: number;
+    limit: number;
+    totalItems: number;
+    totalPages: number;
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+  } | undefined;
+  isLoading: boolean;
+  error: Error | null;
+}
+
+export const useAdminUsers = (params: IGetUsersParams = {}): UseAdminUsersReturn => {
+  const { data, isLoading, error } = useQuery({
+    queryKey: adminKeys.userList(params),
+    queryFn: () => adminService.getUsers(params),
+  });
+
+  return {
+    users: data?.items ?? [],
+    pagination: data?.pagination,
+    isLoading,
+    error,
+  };
+};
+
+// ─── User Detail ────────────────────────────────────────────────────────────
+
+interface UseAdminUserDetailReturn {
+  user: IAdminUserDetail | undefined;
+  isLoading: boolean;
+  error: Error | null;
+}
+
+export const useAdminUserDetail = (userId: string): UseAdminUserDetailReturn => {
+  const { data, isLoading, error } = useQuery({
+    queryKey: adminKeys.userDetail(userId),
+    queryFn: () => adminService.getUserDetail(userId),
+    enabled: !!userId,
+  });
+
+  return {
+    user: data,
+    isLoading,
+    error,
+  };
+};
+
+// ─── Update User Status ─────────────────────────────────────────────────────
+
+interface UseUpdateUserStatusReturn {
+  updateStatus: (params: { userId: string; isActive: boolean }) => void;
+  isUpdating: boolean;
+}
+
+export const useUpdateUserStatus = (): UseUpdateUserStatusReturn => {
+  const queryClient = useQueryClient();
+
+  const mutation = useMutation({
+    mutationFn: ({ userId, isActive }: { userId: string; isActive: boolean }) =>
+      adminService.updateUserStatus(userId, { isActive }),
+    onSuccess: (_data, variables) => {
+      const action = variables.isActive ? 'activated' : 'deactivated';
+      toast.success(`User ${action} successfully`);
+      queryClient.invalidateQueries({ queryKey: adminKeys.users() });
+      queryClient.invalidateQueries({ queryKey: adminKeys.stats() });
+    },
+    onError: (error) => {
+      toast.error(getErrorMessage(error));
+    },
+  });
+
+  return {
+    updateStatus: mutation.mutate,
+    isUpdating: mutation.isPending,
+  };
+};
+
+// ─── Update User Role ───────────────────────────────────────────────────────
+
+interface UseUpdateUserRoleReturn {
+  updateRole: (params: { userId: string; role: 'USER' | 'ADMIN' }) => void;
+  isUpdating: boolean;
+}
+
+export const useUpdateUserRole = (): UseUpdateUserRoleReturn => {
+  const queryClient = useQueryClient();
+
+  const mutation = useMutation({
+    mutationFn: ({ userId, role }: { userId: string; role: 'USER' | 'ADMIN' }) =>
+      adminService.updateUserRole(userId, { role }),
+    onSuccess: () => {
+      toast.success('User role updated successfully');
+      queryClient.invalidateQueries({ queryKey: adminKeys.users() });
+      queryClient.invalidateQueries({ queryKey: adminKeys.stats() });
+    },
+    onError: (error) => {
+      toast.error(getErrorMessage(error));
+    },
+  });
+
+  return {
+    updateRole: mutation.mutate,
+    isUpdating: mutation.isPending,
+  };
+};

package/template/client/src/features/admin/services/admin.service.ts

@@ -0,0 +1,94 @@
+import { apiClient } from '@/lib/api/axios.config';
+import { API_ENDPOINTS } from '@/lib/constants/api-endpoints';
+
+import type { ApiResponse, PaginatedApiResponse } from '@/lib/api/api.types';
+import type {
+  IAdminUser,
+  IAdminUserDetail,
+  IAdminSession,
+  IDashboardStats,
+  IGetUsersParams,
+  IGetSessionsParams,
+  IUpdateUserStatusRequest,
+  IUpdateUserRoleRequest,
+} from '../types/admin.types';
+
+interface PaginatedData<T> {
+  items: T[];
+  pagination: {
+    page: number;
+    limit: number;
+    totalItems: number;
+    totalPages: number;
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+  };
+}
+
+class AdminService {
+  // ─── Dashboard Stats ────────────────────────────────────────────────
+
+  async getDashboardStats(): Promise<IDashboardStats> {
+    const response = await apiClient.get<ApiResponse<IDashboardStats>>(
+      API_ENDPOINTS.ADMIN.STATS,
+    );
+    return response.data.data;
+  }
+
+  // ─── User Management ───────────────────────────────────────────────
+
+  async getUsers(params?: IGetUsersParams): Promise<PaginatedData<IAdminUser>> {
+    const response = await apiClient.get<PaginatedApiResponse<IAdminUser>>(
+      API_ENDPOINTS.ADMIN.USERS,
+      { params },
+    );
+    return response.data.data;
+  }
+
+  async getUserDetail(userId: string): Promise<IAdminUserDetail> {
+    const response = await apiClient.get<ApiResponse<IAdminUserDetail>>(
+      API_ENDPOINTS.ADMIN.USER_DETAIL(userId),
+    );
+    return response.data.data;
+  }
+
+  async updateUserStatus(
+    userId: string,
+    data: IUpdateUserStatusRequest,
+  ): Promise<IAdminUser> {
+    const response = await apiClient.patch<ApiResponse<IAdminUser>>(
+      API_ENDPOINTS.ADMIN.USER_STATUS(userId),
+      data,
+    );
+    return response.data.data;
+  }
+
+  async updateUserRole(
+    userId: string,
+    data: IUpdateUserRoleRequest,
+  ): Promise<IAdminUser> {
+    const response = await apiClient.patch<ApiResponse<IAdminUser>>(
+      API_ENDPOINTS.ADMIN.USER_ROLE(userId),
+      data,
+    );
+    return response.data.data;
+  }
+
+  // ─── Session Management ────────────────────────────────────────────
+
+  async getSessions(
+    params?: IGetSessionsParams,
+  ): Promise<PaginatedData<IAdminSession>> {
+    const response = await apiClient.get<PaginatedApiResponse<IAdminSession>>(
+      API_ENDPOINTS.ADMIN.SESSIONS,
+      { params },
+    );
+    return response.data.data;
+  }
+
+  async deleteSession(sessionId: string): Promise<void> {
+    await apiClient.delete(API_ENDPOINTS.ADMIN.SESSION_DELETE(sessionId));
+  }
+}
+
+export const adminService = new AdminService();

package/template/client/src/features/admin/types/admin.types.ts

@@ -0,0 +1,65 @@
+import type { IUser } from '@/features/auth/types/auth.types';
+import type { PaginationParams } from '@/lib/api/api.types';
+
+// ─── Admin User ─────────────────────────────────────────────────────────────
+
+export interface IAdminUser extends IUser {
+  deletedAt: string | null;
+  failedLoginAttempts: number;
+  lockedUntil: string | null;
+}
+
+export interface IAdminUserDetail extends IAdminUser {
+  sessionCount: number;
+  lastLogin: string | null;
+}
+
+// ─── Admin Session ──────────────────────────────────────────────────────────
+
+export interface IAdminSession {
+  id: string;
+  userId: string;
+  deviceInfo: string | null;
+  ipAddress: string | null;
+  lastActiveAt: string;
+  expiresAt: string;
+  createdAt: string;
+  user: {
+    id: string;
+    email: string;
+    firstName: string;
+    lastName: string;
+  };
+}
+
+// ─── Dashboard Stats ────────────────────────────────────────────────────────
+
+export interface IDashboardStats {
+  totalUsers: number;
+  activeUsers: number;
+  adminCount: number;
+  recentSignups: number;
+  activeSessions: number;
+}
+
+// ─── Request Params ─────────────────────────────────────────────────────────
+
+export interface IGetUsersParams extends PaginationParams {
+  search?: string;
+  role?: 'USER' | 'ADMIN';
+  isActive?: boolean;
+  sortBy?: 'createdAt' | 'email' | 'firstName';
+  sortOrder?: 'asc' | 'desc';
+}
+
+export interface IGetSessionsParams extends PaginationParams {
+  userId?: string;
+}
+
+export interface IUpdateUserStatusRequest {
+  isActive: boolean;
+}
+
+export interface IUpdateUserRoleRequest {
+  role: 'USER' | 'ADMIN';
+}

package/template/client/src/features/auth/components/AuthInitializer.tsx

@@ -5,13 +5,21 @@ import { useEffect } from 'react';
 
 import { usePathname, useRouter } from 'next/navigation';
 
+import { toast } from 'sonner';
+
 import { useAppDispatch, useAppSelector } from '@/store/hooks';
 import { ROUTES } from '@/lib/constants/routes';
+import { isErrorCode, ERROR_CODES } from '@/lib/utils/error';
 import { authService } from '../services/auth.service';
 import { setUser, setInitialized } from '../store/authSlice';
 
 const PROTECTED_PATHS: string[] = [ROUTES.DASHBOARD, ROUTES.PROFILE, '/admin'];
 
+// Auth pages where getMe() should never fire — there is no session to hydrate
+// on login/register/reset-password, and calling getMe() here would trigger the
+// 401 → refresh → fail → redirect chain for no reason.
+const AUTH_PATHS: string[] = [ROUTES.LOGIN, ROUTES.REGISTER, ROUTES.RESET_PASSWORD, ROUTES.VERIFY_ACCOUNT];
+
 interface AuthInitializerProps {
   children: React.ReactNode;
 }
@@ -20,6 +28,10 @@ function isProtectedPath(pathname: string): boolean {
   return PROTECTED_PATHS.some((path) => pathname.startsWith(path));
 }
 
+function isAuthPage(pathname: string): boolean {
+  return AUTH_PATHS.some((path) => pathname.startsWith(path));
+}
+
 export const AuthInitializer = ({ children }: AuthInitializerProps): React.ReactElement => {
   const dispatch = useAppDispatch();
   const pathname = usePathname();
@@ -27,7 +39,15 @@ export const AuthInitializer = ({ children }: AuthInitializerProps): React.React
   const { isAuthenticated, isLoggingOut } = useAppSelector((state) => state.auth);
 
   useEffect(() => {
-    // On public pages, skip auth hydration — just mark as initialized
+    // On auth pages (login, register, etc.), never call getMe().
+    // There is no session to hydrate, and a 401 here would trigger
+    // the refresh → fail → redirect chain, causing an infinite loop.
+    if (isAuthPage(pathname)) {
+      dispatch(setInitialized());
+      return;
+    }
+
+    // On other public pages, skip auth hydration — just mark as initialized
     if (!isProtectedPath(pathname)) {
       dispatch(setInitialized());
       return;
@@ -48,6 +68,9 @@ export const AuthInitializer = ({ children }: AuthInitializerProps): React.React
         // Only redirect on auth errors (401/403), not network failures
         const status = error?.response?.status;
         if (status === 401 || status === 403) {
+          if (isErrorCode(error, ERROR_CODES.ACCOUNT_NOT_ACTIVE)) {
+            toast.error('Your account is not yet activated. Please verify your account.');
+          }
           router.push(ROUTES.LOGIN);
         }
       });

package/template/client/src/features/auth/hooks/useAuth.ts

@@ -7,7 +7,7 @@ import { useRouter, useSearchParams } from 'next/navigation';
 import { toast } from 'sonner';
 
 import { useAppDispatch, useAppSelector } from '@/store/hooks';
-import { getErrorMessage } from '@/lib/utils/error';
+import { getErrorMessage, isErrorCode, ERROR_CODES } from '@/lib/utils/error';
 import { ROUTES } from '@/lib/constants/routes';
 import { authService } from '../services/auth.service';
 import { setUser, setLoggingOut, logout as logoutAction } from '../store/authSlice';
@@ -42,6 +42,10 @@ export const useAuth = (): UseAuthReturn => {
       router.push(redirectTo);
     },
     onError: (error) => {
+      if (isErrorCode(error, ERROR_CODES.ACCOUNT_NOT_ACTIVE)) {
+        toast.error('Your account is not yet activated. Please verify your account to continue.');
+        return;
+      }
       toast.error(getErrorMessage(error));
     },
   });
@@ -49,6 +53,11 @@ export const useAuth = (): UseAuthReturn => {
   const registerMutation = useMutation({
     mutationFn: (data: IRegisterRequest) => authService.register(data),
     onSuccess: (data) => {
+      if (!data.user.isActive) {
+        toast.success('Account created! Please verify your account to continue.');
+        router.push(ROUTES.VERIFY_ACCOUNT);
+        return;
+      }
       dispatch(setUser(data.user));
       toast.success('Account created successfully');
       router.push(ROUTES.DASHBOARD);

package/template/client/src/features/auth/hooks/usePasswordReset.ts

@@ -0,0 +1,57 @@
+'use client';
+
+import { useMutation } from '@tanstack/react-query';
+import { useRouter } from 'next/navigation';
+import { toast } from 'sonner';
+
+import { ROUTES } from '@/lib/constants/routes';
+import { getErrorMessage } from '@/lib/utils/error';
+import { authService } from '../services/auth.service';
+
+interface UseForgotPasswordReturn {
+  forgotPassword: (email: string) => void;
+  isPending: boolean;
+}
+
+export const useForgotPassword = (): UseForgotPasswordReturn => {
+  const mutation = useMutation({
+    mutationFn: (email: string) => authService.forgotPassword(email),
+    onSuccess: () => {
+      toast.success('Check your email for reset instructions');
+    },
+    onError: (error: unknown) => {
+      toast.error(getErrorMessage(error));
+    },
+  });
+
+  return {
+    forgotPassword: mutation.mutate,
+    isPending: mutation.isPending,
+  };
+};
+
+interface UseResetPasswordReturn {
+  resetPassword: (data: { token: string; newPassword: string }) => void;
+  isPending: boolean;
+}
+
+export const useResetPassword = (): UseResetPasswordReturn => {
+  const router = useRouter();
+
+  const mutation = useMutation({
+    mutationFn: (data: { token: string; newPassword: string }) =>
+      authService.resetPassword(data.token, data.newPassword),
+    onSuccess: () => {
+      toast.success('Password reset successfully. Please sign in.');
+      router.push(ROUTES.LOGIN);
+    },
+    onError: (error: unknown) => {
+      toast.error(getErrorMessage(error));
+    },
+  });
+
+  return {
+    resetPassword: mutation.mutate,
+    isPending: mutation.isPending,
+  };
+};

package/template/client/src/features/auth/services/auth.service.ts

@@ -36,8 +36,8 @@ class AuthService {
     return response.data.data;
   }
 
-  async requestPasswordReset(email: string): Promise<void> {
-    await apiClient.post(API_ENDPOINTS.AUTH.REQUEST_PASSWORD_RESET, { email });
+  async forgotPassword(email: string): Promise<void> {
+    await apiClient.post(API_ENDPOINTS.AUTH.FORGOT_PASSWORD, { email });
   }
 
   async resetPassword(token: string, newPassword: string): Promise<void> {

package/template/client/src/lib/api/axios.config.ts

@@ -4,9 +4,10 @@ import type { InternalAxiosRequestConfig } from 'axios';
 
 import { API_ENDPOINTS } from '@/lib/constants/api-endpoints';
 import { ROUTES } from '@/lib/constants/routes';
+import { env } from '@/lib/env';
 
 const apiClient = axios.create({
-  baseURL: process.env.NEXT_PUBLIC_API_BASE_URL || 'http://localhost:8000/api/v1',
+  baseURL: env.NEXT_PUBLIC_API_BASE_URL,
   timeout: 30000,
   withCredentials: true, // Send cookies with every request
 });
@@ -18,6 +19,14 @@ let refreshTimestamp = 0;
 const REFRESH_TIMEOUT_MS = 15000;
 let failedQueue: { resolve: () => void; reject: (error: unknown) => void }[] = [];
 
+// Circuit breaker — once a refresh fails with a definitive auth error (4xx),
+// this flag is set BEFORE dispatching logout or redirecting. All subsequent
+// 401s are immediately rejected without entering the refresh flow, preventing
+// the race condition where Redux state changes trigger re-renders that fire
+// new API calls before the hard redirect completes.
+// Resets automatically on page reload (window.location.href re-initializes the module).
+let isSessionDead = false;
+
 const processQueue = (error: unknown): void => {
   failedQueue.forEach((promise) => {
     if (error) {
@@ -43,6 +52,12 @@ apiClient.interceptors.response.use(
       return Promise.reject(error);
     }
 
+    // Circuit breaker tripped — session is dead, redirect is pending.
+    // Reject immediately without attempting refresh or queuing.
+    if (isSessionDead) {
+      return Promise.reject(error);
+    }
+
     // Don't retry auth endpoints that don't use tokens —
     // a 401 here means wrong credentials, not an expired token.
     const noRetryEndpoints: string[] = [
@@ -93,6 +108,10 @@ apiClient.interceptors.response.use(
         refreshError.response.status < 500;
 
       if (isAuthFailure) {
+        // Trip the circuit breaker FIRST — prevents any subsequent 401s
+        // from re-entering this flow while the redirect is pending.
+        isSessionDead = true;
+
         const { logout } = await import('@/features/auth/store/authSlice');
         const { store } = await import('@/store');
         store.dispatch(logout());

package/template/client/src/lib/constants/api-endpoints.ts

@@ -5,7 +5,7 @@ export const API_ENDPOINTS = {
     LOGOUT: '/auth/logout',
     REFRESH: '/auth/refresh',
     ME: '/auth/me',
-    REQUEST_PASSWORD_RESET: '/auth/request-password-reset',
+    FORGOT_PASSWORD: '/auth/forgot-password',
     RESET_PASSWORD: '/auth/reset-password',
   },
   USERS: {
@@ -13,4 +13,13 @@ export const API_ENDPOINTS = {
     UPDATE_ME: '/users/me',
     DELETE_ME: '/users/me',
   },
+  ADMIN: {
+    STATS: '/admin/stats',
+    USERS: '/admin/users',
+    USER_DETAIL: (userId: string) => `/admin/users/${userId}`,
+    USER_STATUS: (userId: string) => `/admin/users/${userId}/status`,
+    USER_ROLE: (userId: string) => `/admin/users/${userId}/role`,
+    SESSIONS: '/admin/sessions',
+    SESSION_DELETE: (sessionId: string) => `/admin/sessions/${sessionId}`,
+  },
 } as const;

package/template/client/src/lib/constants/app.constants.ts

@@ -1,4 +1,6 @@
-export const APP_NAME = process.env.NEXT_PUBLIC_APP_NAME || 'My App';
+import { env } from '@/lib/env';
+
+export const APP_NAME = env.NEXT_PUBLIC_APP_NAME;
 
 export const PAGINATION = {
   DEFAULT_PAGE: 1,

package/template/client/src/lib/constants/routes.ts

@@ -2,8 +2,14 @@ export const ROUTES = {
   HOME: '/',
   LOGIN: '/login',
   REGISTER: '/register',
-  VERIFY_EMAIL: '/verify-email',
+  VERIFY_ACCOUNT: '/verify-account',
   RESET_PASSWORD: '/reset-password',
   DASHBOARD: '/dashboard',
   PROFILE: '/profile',
+  ADMIN: {
+    DASHBOARD: '/admin',
+    USERS: '/admin/users',
+    USER_DETAIL: (userId: string) => `/admin/users/${userId}`,
+    SESSIONS: '/admin/sessions',
+  },
 } as const;

package/template/client/src/lib/env.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+
+// Every field MUST have a .default() so the dev fallback (envSchema.parse({}))
+// can produce valid defaults when env vars are missing in development.
+const envSchema = z.object({
+  NEXT_PUBLIC_API_BASE_URL: z
+    .string()
+    .url('NEXT_PUBLIC_API_BASE_URL must be a valid URL')
+    .default('http://localhost:8000/api/v1'),
+  NEXT_PUBLIC_APP_NAME: z.string().default('My App'),
+});
+
+function validateEnv(): z.infer<typeof envSchema> {
+  const result = envSchema.safeParse({
+    NEXT_PUBLIC_API_BASE_URL: process.env.NEXT_PUBLIC_API_BASE_URL,
+    NEXT_PUBLIC_APP_NAME: process.env.NEXT_PUBLIC_APP_NAME,
+  });
+
+  if (!result.success) {
+    const formatted = result.error.issues
+      .map((issue) => `  - ${issue.path.join('.')}: ${issue.message}`)
+      .join('\n');
+
+    console.error(`\n❌ Invalid environment variables:\n${formatted}\n`);
+
+    // In production, fail hard. In development, warn but continue with defaults.
+    if (process.env.NODE_ENV === 'production') {
+      throw new Error('Invalid environment variables');
+    }
+  }
+
+  return result.success ? result.data : envSchema.parse({});
+}
+
+export const env = validateEnv();

package/template/client/src/lib/utils/error.ts

@@ -30,3 +30,7 @@ export const getErrorCode = (error: unknown): string | undefined => {
 export const isErrorCode = (error: unknown, code: string): boolean => {
   return getErrorCode(error) === code;
 };
+
+export const ERROR_CODES = {
+  ACCOUNT_NOT_ACTIVE: 'ACCOUNT_NOT_ACTIVE',
+} as const;