Integration Guide¶

// On login success (login page)
import { setCookie } from "cookies-next";

const handleLogin = async (credentials) => {
  const response = await authAPI.login(credentials);

  // 2FA early return — no cookie, no Redux update
  if (response.twoFactor) {
    // redirect to 2FA verification page
    return;
  }

  // Store token in cookie (JS-accessible, NOT httpOnly)
  setCookie("token", response.token, {
    maxAge: credentials.rememberMe
      ? 60 * 60 * 24 * 30   // 30 days
      : 60 * 60 * 24 * 7,   // 7 days
    sameSite: "strict",
    secure: process.env.NODE_ENV === "production",
    path: "/",
  });

  // Update Redux — sets isAuthenticated + token, but NOT user
  dispatch(setAuth({ token: response.token }));

  // Hard redirect (full page reload, not Next.js router.push)
  window.location.href = "/dashboard";
};

// components/providers/auth-initializer.jsx
"use client";

export default function AuthInitializer({ children }) {
  const dispatch = useDispatch();

  useEffect(() => {
    // initializeAuth() reads the "token" cookie
    // Sets isAuthenticated + token in Redux, but NOT user
    // User data is fetched separately by useProfile()
    dispatch(initializeAuth());

    // Wire Redux dispatch to Axios interceptor for logout-on-401
    setStoreDispatch(dispatch);
  }, [dispatch]);

  return children;
}

// interceptors/axiosInstance.js
const api = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_URL,
  withCredentials: true,  // Send cookies with requests
});

api.interceptors.request.use((config) => {
  const token = getCookie("token");
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

api.interceptors.response.use(
  (response) => response,
  (error) => {
    if (error.response?.status === 401 || error.response?.status === 403) {
      // Clear cookie
      deleteCookie("token");

      // Clear Redux state
      if (storeDispatch) {
        storeDispatch(logout());
      }

      // Clear React Query cache
      // (queryClient.clear() called in logout action)

      // Redirect to login
      if (typeof window !== "undefined") {
        window.location.href = "/login";
      }
    }
    return Promise.reject(error);
  }
);

// middleware.js
import { NextResponse } from "next/server";

export async function middleware(req) {
  const token = req.cookies.get("token")?.value;
  const { pathname } = req.nextUrl;

  // Protect dashboard routes
  if (pathname.startsWith("/dashboard")) {
    if (!token) {
      return NextResponse.redirect(new URL("/login", req.url));
    }
  }

  // Redirect authenticated users away from auth pages
  if (token && ["/login", "/register"].includes(pathname)) {
    return NextResponse.redirect(new URL("/dashboard", req.url));
  }

  return NextResponse.next();
}

export const config = {
  matcher: ["/login", "/register", "/dashboard/:path*"],
};

// api/users/index.js
import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
import api from "@/interceptors/axiosInstance";

// Fetch current user profile
export const useProfile = () => {
  return useQuery({
    queryKey: ["user", "profile"],
    queryFn: async () => {
      const response = await api.get("/users/profile");
      return response.data.data;
    },
    staleTime: 5 * 60 * 1000,  // 5 minutes
  });
};

// Fetch users list
export const useUsers = (params) => {
  return useQuery({
    queryKey: ["users", params],
    queryFn: async () => {
      const response = await api.get("/users", { params });
      return response.data;
    },
    // staleTime: CACHE_TIME (configurable, in hours)
  });
};

// Create user mutation
export const useCreateUser = () => {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (data) => api.post("/users", data),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ["users"] });
    },
  });
};

// Server component fetching with cache tags
async function getBlogs() {
  const response = await fetch(`${process.env.API_URL}/blogs`, {
    next: { tags: ["blogs"] },
  });
  return response.json();
}

export default async function BlogsPage() {
  const { data: blogs } = await getBlogs();
  return <BlogList blogs={blogs} />;
}

// app/layout.js
async function fetchMetaData() {
  const response = await fetch(
    `${process.env.API_URL}/settings/admin/prefix`,
    { next: { tags: ["settings-group"] } }
  );
  return response.json();
}

export async function generateMetadata() {
  const settings = await fetchMetaData();
  return {
    title: settings?.admin?.meta_title || "SaaS App",
    description: settings?.admin?.meta_description,
  };
}

// src/actions/revalidate.js
"use server";
import { revalidateTag } from "next/cache";

// Revalidate a single tag
export async function revalidate(tag) {
  revalidateTag(tag);
}

// Revalidate multiple tags at once
export async function revalidateBulk(tags) {
  tags.forEach((tag) => revalidateTag(tag));
}

// Nuclear option: revalidate all 7 tags
export async function revalidateAll() {
  const allTags = [
    "blogs", "blog-details", "dynamic-page",
    "navigation-links", "packages-data",
    "settings-group", "all-settings",
  ];
  allTags.forEach((tag) => revalidateTag(tag));
}

// Backend middleware checks permissions automatically
router.get("/users", auth(), hasPermission(), UserController.getUsers);
// Requires: /users permission for GET
// Requires: /users/create for POST, /users/edit for PATCH, etc.

// hooks/useCheckPermission.js
import { useSelector } from "react-redux";

export const useCheckPermission = (permission) => {
  const { user } = useSelector((state) => state.auth);

  if (!user) return false;
  if (user.role === "super_admin") return true;

  return user.permissions?.includes(permission);
};

// Usage in component
function AdminButton() {
  const canManageUsers = useCheckPermission("/users/create");

  if (!canManageUsers) return null;

  return <button>Add User</button>;
}

// Dashboard sidebar filters menu items by permission
const { data: links } = useNavigationLinks("dashboard-sidebar-top");

// Backend filters items based on user's permissions
// MenuItem.permission field is checked against user's permissions

// Frontend: uploadFile.js
const uploadFile = async (file) => {
  const formData = new FormData();
  formData.append("file", file);

  // Endpoint: POST ${NEXT_PUBLIC_API_URL}/uploads/image
  const response = await api.post("/uploads/image", formData, {
    headers: { "Content-Type": "multipart/form-data" },
  });

  return response.data.data.url;
};

// Backend: POST /webhooks/stripe (root level, not under /api/v1)
app.post("/webhooks/stripe",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    const sig = req.headers["stripe-signature"];
    const event = stripe.webhooks.constructEvent(req.body, sig, webhookSecret);

    switch (event.type) {
      case "checkout.session.completed":
        await handleCheckoutComplete(event.data.object);
        break;
      case "customer.subscription.updated":
        await handleSubscriptionUpdate(event.data.object);
        break;
    }

    res.json({ received: true });
  }
);

// app.ts
import cors from "cors";
import { getCorsOrigins } from "./shared/getCorsOrigins";

app.use(cors({
  origin: getCorsOrigins(),  // Parses ALLOWED_ORIGINS env var (JSON array)
  credentials: true,         // Allow cookies
}));

// axiosInstance.js
const api = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_URL,
  withCredentials: true,  // Send cookies with requests
});

// ApiError class
throw new ApiError(httpStatus.NOT_FOUND, "User not found");

// Global error handler response shape
{
  "success": false,
  "message": "User not found",
  "error": {
    "path": "/api/v1/users/123",
    "message": "User not found"
  }
}

// In React Query mutation
const createUser = useCreateUser();

const handleSubmit = async (data) => {
  try {
    await createUser.mutateAsync(data);
    toast.success("User created successfully");
  } catch (error) {
    toast.error(error.response?.data?.message || "Failed to create user");
  }
};

// Current architecture (JS-accessible cookie):
setCookie("token", value, {
  maxAge: 60 * 60 * 24 * 30,  // 30 days (rememberMe) or 7 days
  secure: true,                // HTTPS only (auto in production)
  sameSite: "strict",          // Prevent CSRF
  path: "/",
});
// Note: httpOnly is intentionally omitted — frontend JS reads this cookie.
// Mitigate XSS risk via CSP headers, input sanitization, and content security policies.