API Documentation

This document describes all APIs used and required by the application: existing internal routes, the backend contract consumed by the frontend, entities and their relations, authentication, and admin panel CRUD endpoints.

1. Authentication & Access Control

  • Auth: NextAuth with Credentials (plus optional Google and GitHub providers).
  • Session strategy: JWT. User object extended with role: "admin" | "user".
  • Middleware-protected routes: /admin (requires admin), /user (requires session).

NextAuth endpoints

  • POST/GET /api/auth/[...nextauth] — handled by NextAuth
  • GET /api/me — current session snapshot
  • GET /api/admin — requires admin role

2. Internal API Routes (built-in)

GET /api/me

Returns whether the user is authenticated and the session payload.

Response 200
{
  "authenticated": boolean,
  "session": {
    "user": {
      "name": string | null,
      "email": string | null,
      "image": string | null,
      "role": "admin" | "user"
    } | null,
    "expires": string
  } | null
}

GET /api/admin

Requires an authenticated session with role=admin.

Response 200
{ "message": "Welcome, admin!", "email": string | null, "role": "admin" }

Response 401
{ "error": "Unauthorized" }

3. Frontend → Backend Contract (consumed by lib/api.ts)

When NEXT_PUBLIC_API_URL is set, the frontend calls these endpoints on your backend. If not set, the app serves mock data with the same shapes.

3.1 Content

GET /content/hero-banner
Response 200: { data: { title: string; subtitle: string; image: string; ctaText: string; ctaLink: string }, success: true }

3.2 Categories

GET /categories
GET /categories/{slug}

// Category type
interface Category { id: string; name: string; slug: string; description: string; image: string; productCount: number }

// Responses
{ data: Category[], success: true }
{ data: Category, success: true }

3.3 Products

GET /products?category={slug}&featured=true|false&limit={n}&page={n}
GET /products/{slug}

interface Product {
  id: string
  title: string
  description: string
  price: number
  images: string[]
  category: string // references Category.slug
  slug: string
  inStock: boolean
  featured?: boolean
}

{ data: Product[], success: true }
{ data: Product, success: true }

3.4 Reviews

GET /products/{id}/reviews
GET /reviews/featured?limit={n}

interface Review { id: string; productId: string; customerName: string; rating: number; comment: string; createdAt: string }

{ data: Review[], success: true }

Note: reviews use productId that maps to Product.id (product detail uses slug).

3.5 Blog

GET /blog?limit={n}&page={n}
GET /blog/{slug}

interface BlogPost {
  id: string
  title: string
  slug: string
  excerpt: string
  content: string
  featuredImage: string
  publishedAt: string
  seo: { title: string; description: string; keywords: string[] }
}

{ data: BlogPost[], success: true }
{ data: BlogPost, success: true }

3.6 CRM & Leads

POST /crm/events
Body: { type: "whatsapp_chat", productId: string, productTitle: string, source: "frontend", timestamp: ISOString }

POST /crm/leads
Body: { name: string, email: string, message: string, phone?: string, source: "contact_form", timestamp: ISOString }

Response: { data: null, success: true, message?: string }

3.7 Cart

POST /cart/add
Body: { productId: string, quantity: number, price: number }

GET /cart
Response: { data: { productId: string; quantity: number; price: number }[], success: true }

3.8 Newsletter

POST /newsletter/subscribe
Body: { email: string, source: "website", timestamp: ISOString }
Response: { data: null, success: true }

3.9 Search

GET /search/products?q={query}&category={slug}&minPrice={n}&maxPrice={n}&sortBy={field}
Response: { data: Product[], success: true }

4. Entities & Relations

Canonical schemas derived from the UI and existing types.

// Wrapper
interface ApiResponse<T = any> { data: T; message?: string; success: boolean }

// Core entities
interface Category { id: string; name: string; slug: string; description: string; image: string; productCount: number }
interface Product {
  id: string
  title: string
  description: string
  price: number
  images: string[]
  category: string // FK -> Category.slug
  slug: string
  inStock: boolean
  featured?: boolean
}
interface Review { id: string; productId: string; customerName: string; rating: number; comment: string; createdAt: string } // FK -> Product.id
interface BlogPost { id: string; title: string; slug: string; excerpt: string; content: string; featuredImage: string; publishedAt: string; seo: { title: string; description: string; keywords: string[] } }
interface CartItem { productId: string; quantity: number; price: number }

// Auth
interface AppUser { id: string; name: string | null; email: string | null; role: "admin" | "user" }

// Admin/Orders (UI-derived)
interface Order { id: string; customer: string; email: string; total: number; status: "processing" | "delivered" | "pending" | "cancelled" }
  • Product.category references Category.slug. Review.productId references Product.id.
  • BlogPost.seo contains nested metadata used for SEO rendering.

5. Admin Panel CRUD Endpoints (required by UI)

These endpoints power the Admin pages under /admin. Protect all with admin role.

// Products
GET   /admin/products                -> { data: Product[], success: true }
POST  /admin/products                Body: Product (without id for create) -> { data: Product, success: true }
GET   /admin/products/{id}           -> { data: Product, success: true }
PUT   /admin/products/{id}           Body: Partial<Product> -> { data: Product, success: true }
DELETE/admin/products/{id}           -> { data: null, success: true }

// Categories
GET   /admin/categories              -> { data: Category[], success: true }
POST  /admin/categories              Body: Category -> { data: Category, success: true }
GET   /admin/categories/{id}         -> { data: Category, success: true }
PUT   /admin/categories/{id}         Body: Partial<Category> -> { data: Category, success: true }
DELETE/admin/categories/{id}         -> { data: null, success: true }

// Blog
GET   /admin/blog                    -> { data: BlogPost[], success: true }
POST  /admin/blog                    Body: BlogPost -> { data: BlogPost, success: true }
GET   /admin/blog/{id}               -> { data: BlogPost, success: true }
PUT   /admin/blog/{id}               Body: Partial<BlogPost> -> { data: BlogPost, success: true }
DELETE/admin/blog/{id}               -> { data: null, success: true }

// Users
GET   /admin/users                   -> { data: AppUser[], success: true }
GET   /admin/users/{id}              -> { data: AppUser, success: true }
PUT   /admin/users/{id}              Body: { role?: "admin"|"user" } -> { data: AppUser, success: true }

// Orders
GET   /admin/orders                  -> { data: Order[], success: true }
GET   /admin/orders/{id}             -> { data: Order, success: true }
PUT   /admin/orders/{id}             Body: { status: Order["status"] } -> { data: Order, success: true }

6. Error Handling

Errors should use HTTP status codes. Body should still follow the wrapper where feasible.

// Error shape
{ "data": null, "success": false, "message": string }

7. Environment Variables

  • NEXT_PUBLIC_API_URL — base URL for the backend powering endpoints in section 3.
  • NEXTAUTH_SECRET — JWT secret for auth.
  • GITHUB_ID/GITHUB_SECRET, GOOGLE_ID/GOOGLE_SECRET — optional OAuth providers.