Auto-deploy Samoulla Backend: c82f2c9fc666cea51323d5ea793409fcf6d80b82

.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+config.env
+uploads/*.xlsx

Dockerfile

@@ -0,0 +1,22 @@
+# Use official Node.js image
+FROM node:20-slim
+
+# Set working directory
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install dependencies
+# We use --omit=dev to keep the image small for production
+RUN npm install --omit=dev
+
+# Copy the rest of the application code
+COPY . .
+
+# Hugging Face Spaces uses port 7860 by default
+ENV PORT=7860
+EXPOSE 7860
+
+# Start the application
+CMD ["node", "server.js"]

README.md

@@ -0,0 +1,13 @@
+---
+title: Samoulla Backend
+emoji: 🚀
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+app_port: 7860
+pinned: false
+---
+
+# Samoulla Backend
+
+This is the backend for the Samouulla graduation project, hosted on Hugging Face Spaces.

app.js

@@ -0,0 +1,179 @@
+const express = require('express');
+const dotenv = require('dotenv');
+
+dotenv.config({ path: './config.env' });
+const morgan = require('morgan');
+const helmet = require('helmet');
+const rateLimit = require('express-rate-limit');
+const mongoSanitize = require('express-mongo-sanitize');
+const xss = require('xss-clean');
+const hpp = require('hpp');
+const compression = require('compression');
+const cors = require('cors');
+
+const AppError = require('./utils/appError');
+const globalErrorHandler = require('./middlewares/errorMiddleware');
+
+const productRouter = require('./routes/productRoutes');
+const authRouter = require('./routes/authRoutes');
+const cartRouter = require('./routes/cartRoutes');
+const orderRouter = require('./routes/orderRoutes');
+const promoRouter = require('./routes/promoRoutes');
+const categoryRouter = require('./routes/categoryRoutes');
+const brandRouter = require('./routes/brandRoutes');
+const providerRouter = require('./routes/providerRoutes');
+const reviewRouter = require('./routes/reviewRouter');
+const addressRoutes = require('./routes/addressRoutes');
+const favoriteRouter = require('./routes/favoriteRoutes');
+const imageRouter = require('./routes/imageRoutes');
+const usersRouter = require('./routes/usersRoutes');
+const adminRouter = require('./routes/adminRoutes');
+const vendorRouter = require('./routes/vendorRoutes');
+const newsletterRouter = require('./routes/newsletterRoutes');
+const notificationRouter = require('./routes/notificationRoutes');
+const contentRouter = require('./routes/contentRoutes');
+const permissionRouter = require('./routes/permissionRoutes');
+const shippingRouter = require('./routes/shippingRoutes');
+const financeRouter = require('./routes/financeRoutes');
+const paymentRouter = require('./routes/paymentRoutes');
+const vendorRequestRouter = require('./routes/vendorRequestRoutes');
+const returnRequestRouter = require('./routes/returnRequestRoutes');
+const visitRouter = require('./routes/visitRoutes');
+
+const app = express();
+app.set('trust proxy', 1);
+
+// GLOBAL MIDDLEWARES
+
+// Implement CORS
+app.use(
+  cors({
+    origin: [
+      'http://localhost:5173',
+      'https://samoulla-web.vercel.app',
+      'https://samoulla.vercel.app',
+      'https://samoulla.com',
+      'https://www.samoulla.com',
+      process.env.FRONTEND_URL,
+    ].filter(Boolean),
+    credentials: true,
+  }),
+);
+
+// Set security HTTP headers
+app.use(helmet());
+
+// Development logging
+if (process.env.NODE_ENV === 'development') {
+  app.use(morgan('dev'));
+}
+
+// Limit requests for auth routes (login/register/reset password)
+const authLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 200,
+  message:
+    'Too many authentication attempts. Please try again after 15 minutes.',
+  standardHeaders: true,
+  legacyHeaders: false,
+  validate: { trustProxy: false },
+});
+
+// Limit requests from same API (global browsing)
+const limiter = rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: process.env.NODE_ENV === 'development' ? 10000 : 20000,
+  message: 'Too many requests from this IP, please try again in 15 minutes.',
+  standardHeaders: true,
+  legacyHeaders: false,
+  validate: { trustProxy: false },
+});
+
+app.use('/samoulla/v1/auth', authLimiter);
+app.use('/samoulla', limiter);
+
+// Body parser, reading data from body into req.body
+app.use(express.json({ limit: '10kb' }));
+
+// Data sanitization against NoSQL query injection
+app.use(mongoSanitize());
+
+// Data sanitization against XSS
+app.use(xss());
+
+// Prevent parameter pollution
+app.use(
+  hpp({
+    whitelist: [
+      'price',
+      'ratingsAverage',
+      'ratingsQuantity',
+      'stock',
+      'brand',
+      'category',
+    ],
+  }),
+);
+
+app.use(compression());
+
+// HEALTH CHECK ROUTES (must stay lightweight and never be rate-limited)
+app.get('/', (req, res) => {
+  res.status(200).json({
+    status: 'success',
+    message: 'Samoulla Backend is Alive and Runningg! 🚀',
+  });
+});
+
+app.get('/healthz', (req, res) => {
+  res.status(200).json({
+    status: 'success',
+    service: 'samoulla-backend',
+    uptime: process.uptime(),
+    timestamp: new Date().toISOString(),
+  });
+});
+
+app.get('/samoulla/v1/health', (req, res) => {
+  res.status(200).json({
+    status: 'success',
+    service: 'samoulla-backend',
+    uptime: process.uptime(),
+    timestamp: new Date().toISOString(),
+  });
+});
+
+// ROUTES
+app.use('/samoulla/v1/products', productRouter);
+app.use('/samoulla/v1/auth', authRouter);
+app.use('/samoulla/v1/cart', cartRouter);
+app.use('/samoulla/v1/orders', orderRouter);
+app.use('/samoulla/v1/promos', promoRouter);
+app.use('/samoulla/v1/categories', categoryRouter);
+app.use('/samoulla/v1/brands', brandRouter);
+app.use('/samoulla/v1/providers', providerRouter);
+app.use('/samoulla/v1/reviews', reviewRouter);
+app.use('/samoulla/v1/addresses', addressRoutes);
+app.use('/samoulla/v1/favorites', favoriteRouter);
+app.use('/samoulla/v1/images', imageRouter);
+app.use('/samoulla/v1/users', usersRouter);
+app.use('/samoulla/v1/admin', adminRouter);
+app.use('/samoulla/v1/vendor', vendorRouter);
+app.use('/samoulla/v1/newsletter', newsletterRouter);
+app.use('/samoulla/v1/notifications', notificationRouter);
+app.use('/samoulla/v1/content', contentRouter);
+app.use('/samoulla/v1/permissions', permissionRouter);
+app.use('/samoulla/v1/shipping', shippingRouter);
+app.use('/samoulla/v1/finance', financeRouter);
+app.use('/samoulla/v1/payment', paymentRouter);
+app.use('/samoulla/v1/vendor-requests', vendorRequestRouter);
+app.use('/samoulla/v1/return-requests', returnRequestRouter);
+app.use('/samoulla/v1/visits', visitRouter);
+
+app.all('*', (req, res, next) => {
+  next(new AppError(`Can't find ${req.originalUrl} on this server!`, 404));
+});
+
+app.use(globalErrorHandler);
+
+module.exports = app;

broken-url.txt

@@ -0,0 +1 @@
+https://res.cloudinary.com/dm9ym99zh/image/upload/v1771515557/samoulla/products/6996da5201c93defc57509d4/cover-1771515557455.jpg

config/cloudinary.js

@@ -0,0 +1,216 @@
+const cloudinary = require('cloudinary').v2;
+const { CloudinaryStorage } = require('multer-storage-cloudinary');
+const multer = require('multer');
+
+// Configure Cloudinary with your credentials
+cloudinary.config({
+  cloud_name: process.env.CLOUDINARY_CLOUD_NAME,
+  api_key: process.env.CLOUDINARY_API_KEY,
+  api_secret: process.env.CLOUDINARY_API_SECRET,
+});
+
+const IMAGE_FORMATS = ['jpg', 'jpeg', 'png', 'webp'];
+const VIDEO_FORMATS = ['mp4', 'webm'];
+const IMAGE_MAX_SIZE = 5 * 1024 * 1024; // 5 MB
+const VIDEO_MAX_SIZE = 25 * 1024 * 1024; // 25 MB
+
+// Configure Cloudinary storage for product images
+// Supports dynamic folder structure: samoulla/products/{productId}/
+const productStorage = new CloudinaryStorage({
+  cloudinary: cloudinary,
+  params: async (req, file) => {
+    // Get productId from request body or params
+    const productId = req.body.productId || req.params.productId || 'temp';
+
+    // Determine if it's a cover image or gallery image
+    const iscover = file.fieldname === 'imageCover';
+    const prefix = iscover ? 'cover' : 'img';
+
+    return {
+      folder: `samoulla/products/${productId}`, // Each product gets its own folder
+      allowed_formats: IMAGE_FORMATS,
+      public_id: `${prefix}-${Date.now()}`, // Unique filename
+      transformation: [
+        { width: 1000, height: 1000, crop: 'limit' },
+        { quality: 'auto' },
+        { fetch_format: 'auto' },
+      ],
+    };
+  },
+});
+
+// Configure Cloudinary storage for category images
+const categoryStorage = new CloudinaryStorage({
+  cloudinary: cloudinary,
+  params: {
+    folder: 'samoulla/categories',
+    allowed_formats: IMAGE_FORMATS,
+    transformation: [
+      { width: 500, height: 500, crop: 'limit' },
+      { quality: 'auto' },
+      { fetch_format: 'auto' },
+    ],
+  },
+});
+
+// Configure Cloudinary storage for brand logos
+const brandStorage = new CloudinaryStorage({
+  cloudinary: cloudinary,
+  params: {
+    folder: 'samoulla/brands',
+    allowed_formats: IMAGE_FORMATS,
+    transformation: [
+      { width: 300, height: 300, crop: 'limit' },
+      { quality: 'auto' },
+      { fetch_format: 'auto' },
+    ],
+  },
+});
+
+// Configure Cloudinary storage for user avatars
+const avatarStorage = new CloudinaryStorage({
+  cloudinary: cloudinary,
+  params: {
+    folder: 'samoulla/avatars',
+    allowed_formats: IMAGE_FORMATS,
+    transformation: [
+      { width: 300, height: 300, crop: 'fill', gravity: 'face' },
+      { quality: 'auto' },
+      { fetch_format: 'auto' },
+    ],
+  },
+});
+
+// Configure Cloudinary storage for provider logos
+const providerStorage = new CloudinaryStorage({
+  cloudinary: cloudinary,
+  params: {
+    folder: 'samoulla/providers',
+    allowed_formats: IMAGE_FORMATS,
+    transformation: [
+      { width: 300, height: 300, crop: 'limit' },
+      { quality: 'auto' },
+      { fetch_format: 'auto' },
+    ],
+  },
+});
+
+const heroImageStorage = new CloudinaryStorage({
+  cloudinary: cloudinary,
+  params: async (req, file) => {
+    const slideId = req.body.slideId || 'temp';
+    const type = req.body.type || 'main'; // main or poster
+
+    return {
+      folder: `samoulla/hero-images/${slideId}`,
+      allowed_formats: IMAGE_FORMATS,
+      public_id: `${type}-${Date.now()}`,
+      transformation: [
+        { width: 1920, height: 1080, crop: 'limit' },
+        { quality: 'auto' },
+        { fetch_format: 'auto' },
+      ],
+    };
+  },
+});
+
+// Configure Cloudinary storage for hero slide videos
+// Quality is baked in at upload time so delivery never needs a paid transformation
+const heroVideoStorage = new CloudinaryStorage({
+  cloudinary: cloudinary,
+  params: async (req, file) => {
+    const slideId = req.body.slideId || 'temp';
+
+    return {
+      folder: `samoulla/hero-images/${slideId}`,
+      allowed_formats: VIDEO_FORMATS,
+      resource_type: 'video',
+      public_id: `video-${Date.now()}`,
+      eager: [{ quality: 'auto', fetch_format: 'auto' }],
+      eager_async: true, // process in background, don't block the upload response
+    };
+  },
+});
+
+// Create multer upload instances
+const uploadProductImage = multer({
+  storage: productStorage,
+  limits: { fileSize: IMAGE_MAX_SIZE },
+});
+const uploadCategoryImage = multer({
+  storage: categoryStorage,
+  limits: { fileSize: IMAGE_MAX_SIZE },
+});
+const uploadBrandLogo = multer({
+  storage: brandStorage,
+  limits: { fileSize: IMAGE_MAX_SIZE },
+});
+const uploadProviderLogo = multer({
+  storage: providerStorage,
+  limits: { fileSize: IMAGE_MAX_SIZE },
+});
+const uploadAvatar = multer({
+  storage: avatarStorage,
+  limits: { fileSize: IMAGE_MAX_SIZE },
+});
+const uploadHeroImage = multer({
+  storage: heroImageStorage,
+  limits: { fileSize: IMAGE_MAX_SIZE },
+});
+const uploadHeroVideo = multer({
+  storage: heroVideoStorage,
+  limits: { fileSize: VIDEO_MAX_SIZE },
+});
+
+// Helper function to delete image from Cloudinary
+const deleteImage = async (publicId) => {
+  try {
+    const result = await cloudinary.uploader.destroy(publicId);
+    return result;
+  } catch (error) {
+    console.error('Error deleting image from Cloudinary:', error);
+    throw error;
+  }
+};
+
+// Helper function to delete entire product folder
+const deleteProductFolder = async (productId) => {
+  try {
+    // Delete all images in the product folder
+    const result = await cloudinary.api.delete_resources_by_prefix(
+      `samoulla/products/${productId}/`,
+    );
+
+    // Delete the empty folder
+    await cloudinary.api.delete_folder(`samoulla/products/${productId}`);
+
+    return result;
+  } catch (error) {
+    console.error('Error deleting product folder from Cloudinary:', error);
+    throw error;
+  }
+};
+
+// Helper function to extract public_id from Cloudinary URL
+const getPublicIdFromUrl = (url) => {
+  if (!url) return null;
+
+  // Extract public_id from Cloudinary URL
+  // Example URL: https://res.cloudinary.com/demo/image/upload/v1234567890/samoulla/products/abc123.jpg
+  const matches = url.match(/\/v\d+\/(.+)\.\w+$/);
+  return matches ? matches[1] : null;
+};
+
+module.exports = {
+  cloudinary,
+  uploadProductImage,
+  uploadCategoryImage,
+  uploadBrandLogo,
+  uploadProviderLogo,
+  uploadAvatar,
+  uploadHeroImage,
+  uploadHeroVideo,
+  deleteImage,
+  deleteProductFolder,
+  getPublicIdFromUrl,
+};

config/samoulla-490417-daa7176c0091.json

@@ -0,0 +1,13 @@
+{
+  "type": "service_account",
+  "project_id": "samoulla-490417",
+  "private_key_id": "daa7176c0091bd157b0e0d82d545fbe2313e1b80",
+  "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC4PtVGiK3ITi8M\no7mS/XV6pY6+m2yteBAQcICc9+jPBD0+iwnWTW5h2hj+qEjakU4VWSwL1kD81cQr\nXdA/Yo30d+bkk6DcMgRn+5W4dbxo/L7zBwmZIc8deTVI6sG4ohuE2Mm0MCDrGvke\nZxwzLutgSfMP/ev/g1bYP3L+8ZnS8IoUSCXceVoR+XTqp8wPkExOp7dU3bNg+oll\nveE7TS/JspsrSKDAakZDViNEkiI//dCYDpEgzZF3w9HZW4L91V/VZyIrOizcegjv\nnMPurJyeU21Qa76oDs0IGi6OusTvU2hn0gvRSFEoTN8a3K8LphZ/dP0xOkZ1n4DJ\ngoSGBtWHAgMBAAECggEABP/7hLL/2FA62aJ1zkXfksj8YzLPk7OO6AtNijT2Fewd\nB135kd2/EZu8EukZNQk9b7ngRp/1WocokC63EIlJpek9FFXnRyJ6WSIMMZnMV6MI\nQYse2Q+AUeHwrr5kLHEFwyio7KFju02blhYhP0hWLeJD3Nq8tU3opOyv37hJvt4p\nYQLT+DZ1/bRhNKJHs0myy19v1ZJJ7jgWIL+rXCcvl24slQ3JfFmghO21LUeh6sOl\n4IgXMMEMA/0r2oR1IBrTkJZfHXRLygeP/oClwFUZIkVdZxjBlyfguCK+nvpcJ03E\nTVfJBibuCak1QE4CuI4yRS6qlQSscgeaJYefPK5qpQKBgQDviTIjMCHCk75RKoW3\nE15bJHdgx1mIBfT5HmzGZRxIS7KCg+8gkqcdLpvb7vo4OtO/dQtIh8zYoyhDrirF\naXV7YvNoPIgCfu2zOG8dxxdHsC0aUWuG/KhRQ2RF2bha4KDFwESAfLLg+T/5ci2V\nARN3LkqOsqA+5hokQ/0gcF6VewKBgQDE6MMaWIGX5q3fvHb1mJok1F3LN1l9i4cP\nnlvQFami0Lp/rtp3c1eC0gzQXlROJXhHYHsCzvJcajU8T5AUzJc2pmyScg4uWVLB\nOwIkZOyQr1HFANll9ZtT93SFyYYaEwcKtVvU5L9xGzkZjEox7ROeeIr6c3s7NNS4\nQ+rCZQTUZQKBgDekrzjtXWpN19ATCKzWmvyhI/ofVPT8LUQRhUMxCbjhnL4k18/B\nQYDN6vbUNNwLDlVTYyOeKD/K5veR5e2l6dyXx+NW7GFoCt+vJGDOduH4UwHiGBBr\ncM4v0YNIaEL0G2TUnRUb4pHQVMQleeE7NsJgxoEPjZoO6dOy14JJmC8xAoGBAJXc\naJCmh4rqP66mKwtj5vzcu72sFGneRR538Xx+4CpQHYCLvS1oFVQ1NRdok1UeY1o/\nbZ+HjSEUnAuYqhmKVBN9uegC8hQIW1lA5bJ5NSowpFUA/nQA5wSSspYX9/3kOVnH\nCWsP5TvZ8i0lflpdCq9zIqLWPRWkcbkDx6nHZFOZAoGADVyPgj6gHvqTdIREVkSq\naeDyOYPy3jB+3ollJmXEBb2Ns1tyU+hXgTYaIs0uTJs0qQoh0Zf0yNLsN4zBi+z2\n0hj0H5okMOtEyijbRGxCyZWGRmuplKKe2tpi0phZNG3OxBHPRGo/1Uhctwz3soz1\n7nGZ9g0Ap9T3r+R0sKQ0q4s=\n-----END PRIVATE KEY-----\n",
+  "client_email": "samoulla-backend@samoulla-490417.iam.gserviceaccount.com",
+  "client_id": "101471276909964073550",
+  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+  "token_uri": "https://oauth2.googleapis.com/token",
+  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
+  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/samoulla-backend%40samoulla-490417.iam.gserviceaccount.com",
+  "universe_domain": "googleapis.com"
+}

controllers/addressController.js

@@ -0,0 +1,87 @@
+const User = require('../models/userModel');
+//address functions
+exports.addAddress = async (req, res) => {
+  try {
+    const user = await User.findByIdAndUpdate(
+      req.user.id,
+      { $push: { addresses: req.body } },
+      { new: true },
+    );
+
+    // Get the newly added address (last item in array)
+    const newAddress = user.addresses[user.addresses.length - 1];
+
+    res.status(201).json({
+      status: 'success',
+      message: 'Address added successfully',
+      address: newAddress,
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', error: err.message });
+  }
+};
+
+exports.getAddresses = async (req, res) => {
+  try {
+    const user = await User.findById(req.user.id).select('addresses').lean();
+    res.json({
+      status: 'success',
+      addresses: user.addresses || [],
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', error: err.message });
+  }
+};
+
+exports.updateAddress = async (req, res) => {
+  try {
+    const user = await User.findOneAndUpdate(
+      { _id: req.user.id, 'addresses._id': req.params.id },
+      { $set: { 'addresses.$': { ...req.body, _id: req.params.id } } },
+      { new: true },
+    );
+
+    if (!user) {
+      return res.status(404).json({
+        status: 'error',
+        message: 'Address not found',
+      });
+    }
+
+    const updatedAddress = user.addresses.find(
+      (addr) => addr._id.toString() === req.params.id,
+    );
+
+    res.json({
+      status: 'success',
+      message: 'Address updated successfully',
+      address: updatedAddress,
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', error: err.message });
+  }
+};
+
+exports.deleteAddress = async (req, res) => {
+  try {
+    const user = await User.findByIdAndUpdate(
+      req.user.id,
+      { $pull: { addresses: { _id: req.params.id } } },
+      { new: true },
+    );
+
+    if (!user) {
+      return res.status(404).json({
+        status: 'error',
+        message: 'User not found',
+      });
+    }
+
+    res.json({
+      status: 'success',
+      message: 'Address deleted successfully',
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', error: err.message });
+  }
+};

controllers/authController.js

@@ -0,0 +1,537 @@
+const bcrypt = require('bcryptjs');
+const jwt = require('jsonwebtoken');
+const User = require('../models/userModel');
+const {
+  sendWelcomeEmail,
+  sendPasswordChangeConfirmationEmail,
+} = require('../utils/emailService');
+
+// Helper function to create JWT
+const signToken = (id) => {
+  return jwt.sign({ id }, process.env.JWT_SECRET, {
+    expiresIn: process.env.JWT_EXPIRES_IN,
+  });
+};
+
+// SIGNUP
+exports.signup = async (req, res) => {
+  try {
+    const { name, email, phone, password } = req.body;
+
+    const existingUser = await User.findOne({ email });
+    if (existingUser) {
+      return res.status(400).json({ message: 'Email already registered' });
+    }
+
+    // Check if phone number already exists
+    const existingPhone = await User.findOne({ phone });
+    if (existingPhone) {
+      return res
+        .status(400)
+        .json({ message: 'Phone number already registered' });
+    }
+
+    // Create user - the pre-save hook in userModel will hash the password
+    const newUser = await User.create({
+      name,
+      email,
+      phone,
+      password, // Will be hashed by pre-save hook
+    });
+
+    const token = signToken(newUser._id);
+
+    // Send welcome email (non-blocking - don't wait for it)
+    sendWelcomeEmail(newUser).catch(() => { });
+
+    res.status(201).json({
+      status: 'success',
+      token,
+      user: {
+        id: newUser._id,
+        name: newUser.name,
+        email: newUser.email,
+        phone: newUser.phone,
+        role: newUser.role,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({ message: 'Signup failed', error: err.message });
+  }
+};
+
+// LOGIN
+exports.login = async (req, res) => {
+  try {
+    const { email, password } = req.body;
+
+    // 1) Check if email and password exist
+    if (!email || !password) {
+      return res
+        .status(400)
+        .json({ message: 'Please provide email and password' });
+    }
+
+    // 2) Check if user exists && password is correct
+    const user = await User.findOne({ email })
+      .select('+password')
+      .populate('provider');
+    if (!user) {
+      return res.status(401).json({ message: 'Invalid email or password' });
+    }
+
+    const isMatch = await bcrypt.compare(password, user.password);
+    if (!isMatch) {
+      return res.status(401).json({ message: 'Invalid email or password' });
+    }
+
+    // 3) Check if user account is active
+    if (!user.isActive) {
+      return res.status(403).json({
+        message: 'Your account has been deactivated. Please contact support.',
+      });
+    }
+
+    // 4) Check if vendor's provider is active
+    if (user.role === 'vendor' && user.provider) {
+      if (!user.provider.isActive) {
+        return res.status(403).json({
+          message:
+            'Your vendor account has been deactivated. Please contact support.',
+        });
+      }
+    }
+
+    // 3) If everything ok, send token
+    const token = signToken(user._id);
+
+    res.status(200).json({
+      status: 'success',
+      token,
+      user: {
+        id: user._id,
+        name: user.name,
+        email: user.email,
+        phone: user.phone,
+        role: user.role,
+        permissions: user.permissions || [],
+        provider: user.role === 'vendor' ? user.provider : undefined,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({ message: 'Login failed', error: err.message });
+  }
+};
+
+// ADMIN PORTAL LOGIN - Only for admin, employee, and vendor roles
+exports.adminLogin = async (req, res) => {
+  try {
+    const { email, password } = req.body;
+
+    // 1) Check if email and password exist
+    if (!email || !password) {
+      return res
+        .status(400)
+        .json({ message: 'Please provide email and password' });
+    }
+
+    // 2) Check if user exists && password is correct
+    const user = await User.findOne({ email })
+      .select('+password')
+      .populate('provider');
+    if (!user) {
+      return res.status(401).json({ message: 'Invalid email or password' });
+    }
+
+    const isMatch = await bcrypt.compare(password, user.password);
+    if (!isMatch) {
+      return res.status(401).json({ message: 'Invalid email or password' });
+    }
+
+    // 3) Check if user has admin portal access (admin, employee, or vendor)
+    const allowedRoles = ['admin', 'employee', 'vendor'];
+    if (!allowedRoles.includes(user.role)) {
+      return res.status(403).json({
+        message:
+          'Access denied. This portal is only for administrators, employees, and vendors.',
+      });
+    }
+
+    // 4) Check if user account is active
+    if (!user.isActive) {
+      return res.status(403).json({
+        message: 'Your account has been deactivated. Please contact support.',
+      });
+    }
+
+    // 5) Check if vendor's provider is active
+    if (user.role === 'vendor' && user.provider) {
+      if (!user.provider.isActive) {
+        return res.status(403).json({
+          message:
+            'Your vendor account has been deactivated. Please contact support.',
+        });
+      }
+    }
+
+    // 6) If everything ok, send token
+    const token = signToken(user._id);
+
+    res.status(200).json({
+      status: 'success',
+      token,
+      user: {
+        id: user._id,
+        name: user.name,
+        email: user.email,
+        phone: user.phone,
+        role: user.role,
+        permissions: user.permissions || [],
+        provider: user.role === 'vendor' ? user.provider : undefined,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({ message: 'Admin login failed', error: err.message });
+  }
+};
+
+exports.getMe = async (req, res) => {
+  try {
+    const user = await User.findById(req.user.id).populate('provider');
+    if (!user) {
+      return res.status(404).json({ message: 'User not found' });
+    }
+
+    res.status(200).json({
+      status: 'success',
+      user: {
+        id: user._id,
+        name: user.name,
+        email: user.email,
+        phone: user.phone,
+        role: user.role,
+        permissions: user.permissions || [],
+        provider: user.role === 'vendor' ? user.provider : undefined,
+      },
+    });
+  } catch (err) {
+    res
+      .status(500)
+      .json({ message: 'Failed to get user details', error: err.message });
+  }
+};
+
+exports.protect = async (req, res, next) => {
+  try {
+    let token;
+
+    // 1) Check if token exists in headers
+    if (
+      req.headers.authorization &&
+      req.headers.authorization.startsWith('Bearer')
+    ) {
+      token = req.headers.authorization.split(' ')[1];
+    }
+
+    if (!token) {
+      return res.status(401).json({ message: 'You are not logged in!' });
+    }
+
+    // 2) Verify token
+    const decoded = jwt.verify(token, process.env.JWT_SECRET);
+
+    // 3) Check if user still exists
+    const currentUser = await User.findById(decoded.id);
+    if (!currentUser) {
+      return res.status(401).json({ message: 'User no longer exists.' });
+    }
+
+    // 4) Check if user is active
+    if (!currentUser.isActive) {
+      return res.status(403).json({
+        message: 'Your account has been deactivated. Please contact support.',
+      });
+    }
+
+    // 5) Grant access
+    req.user = currentUser;
+    next();
+  } catch (err) {
+    res
+      .status(401)
+      .json({ message: 'Invalid or expired token', error: err.message });
+  }
+};
+
+// Optional authentication - sets req.user if token is valid, but doesn't fail if no token
+exports.optionalAuth = async (req, res, next) => {
+  try {
+    let token;
+
+    // 1) Check if token exists in headers
+    if (
+      req.headers.authorization &&
+      req.headers.authorization.startsWith('Bearer')
+    ) {
+      token = req.headers.authorization.split(' ')[1];
+    }
+
+    // If no token, just continue without setting req.user
+    if (!token) {
+      return next();
+    }
+
+    // 2) Verify token
+    const decoded = jwt.verify(token, process.env.JWT_SECRET);
+
+    // 3) Check if user still exists
+    const currentUser = await User.findById(decoded.id);
+    if (currentUser) {
+      req.user = currentUser;
+    }
+
+    next();
+  } catch (err) {
+    // If token is invalid, just continue without setting req.user
+    next();
+  }
+};
+
+exports.logout = (req, res) => {
+  res
+    .status(200)
+    .json({ status: 'success', message: 'Logged out successfully' });
+};
+
+exports.deleteAccount = async (req, res) => {
+  try {
+    const { currentPassword } = req.body;
+
+    // 1) Check if password is provided
+    if (!currentPassword) {
+      return res
+        .status(400)
+        .json({ message: 'Password is required to delete account' });
+    }
+
+    // 2) Get user with password
+    const user = await User.findById(req.user._id).select('+password');
+
+    // 3) Verify password
+    const isMatch = await bcrypt.compare(currentPassword, user.password);
+    if (!isMatch) {
+      return res.status(401).json({ message: 'Incorrect password' });
+    }
+
+    // 4) Delete the account
+    await User.findByIdAndDelete(req.user._id);
+
+    res.status(200).json({
+      status: 'success',
+      message: 'Account deleted successfully',
+    });
+  } catch (err) {
+    res
+      .status(500)
+      .json({ message: 'Failed to delete account', error: err.message });
+  }
+};
+
+exports.updateMe = async (req, res) => {
+  try {
+    const { name, email, phone, city, currentPassword } = req.body;
+
+    // 1) لازم يكتب الباسورد القديمة
+    if (!currentPassword) {
+      return res
+        .status(400)
+        .json({ message: 'You must enter your current password' });
+    }
+
+    // 2) نجيب المستخدم ونقارن الباسورد
+    const user = await User.findById(req.user._id).select('+password');
+
+    const isMatch = await bcrypt.compare(currentPassword, user.password);
+    if (!isMatch) {
+      return res.status(401).json({ message: 'Current password is incorrect' });
+    }
+
+    // 3) نعمل update للبيانات
+    user.name = name || user.name;
+    user.email = email || user.email;
+    user.phone = phone || user.phone;
+    user.city = city || user.city;
+
+    await user.save();
+
+    res.status(200).json({
+      status: 'success',
+      user: {
+        id: user._id,
+        name: user.name,
+        email: user.email,
+        phone: user.phone,
+        city: user.city,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'fail',
+      message: 'Update failed',
+      error: err.message,
+    });
+  }
+};
+
+exports.changePassword = async (req, res) => {
+  try {
+    const { currentPassword, newPassword, confirmNewPassword } = req.body;
+
+    // 1) Check all fields exist
+    if (!currentPassword || !newPassword || !confirmNewPassword) {
+      return res.status(400).json({ message: 'All fields are required' });
+    }
+
+    // 2) Check new passwords match
+    if (newPassword !== confirmNewPassword) {
+      return res.status(400).json({ message: 'New passwords do not match' });
+    }
+
+    // 3) Get current user with password
+    const user = await User.findById(req.user._id).select('+password');
+
+    // 4) Check currentPassword is correct
+    const isMatch = await bcrypt.compare(currentPassword, user.password);
+    if (!isMatch) {
+      return res.status(401).json({ message: 'Current password is incorrect' });
+    }
+
+    // 5) Set new password (will be hashed by pre-save hook)
+    user.password = newPassword;
+
+    // 6) Save user
+    await user.save();
+
+    // 7) Send password change confirmation email
+    sendPasswordChangeConfirmationEmail(user).catch((err) =>
+      console.error(
+        'Failed to send password change confirmation email:',
+        err.message,
+      ),
+    );
+
+    res.status(200).json({
+      status: 'success',
+      message: 'Password updated successfully',
+    });
+  } catch (err) {
+    res
+      .status(500)
+      .json({ message: 'Failed to update password', error: err.message });
+  }
+};
+
+// FORGOT PASSWORD - sends reset token to email
+exports.forgotPassword = async (req, res) => {
+  try {
+    const { email } = req.body;
+
+    if (!email) {
+      return res
+        .status(400)
+        .json({ message: 'Please provide an email address' });
+    }
+
+    const user = await User.findOne({ email });
+    if (!user) {
+      return res
+        .status(404)
+        .json({ message: 'No user found with that email address' });
+    }
+
+    const resetToken = user.createPasswordResetToken();
+    await user.save({ validateBeforeSave: false });
+
+    const { sendPasswordResetEmail } = require('../utils/emailService');
+
+    try {
+      await sendPasswordResetEmail(user, resetToken);
+
+      res.status(200).json({
+        status: 'success',
+        message: 'Password reset link sent to email',
+      });
+    } catch (err) {
+      user.passwordResetToken = undefined;
+      user.passwordResetExpires = undefined;
+      await user.save({ validateBeforeSave: false });
+
+      return res.status(500).json({
+        message: 'Failed to send password reset email. Please try again later.',
+        error: err.message,
+      });
+    }
+  } catch (err) {
+    res.status(500).json({
+      message: 'Failed to process forgot password request',
+      error: err.message,
+    });
+  }
+};
+
+// RESET PASSWORD - validates token and sets new password
+exports.resetPassword = async (req, res) => {
+  try {
+    const crypto = require('crypto');
+    const { password, confirmPassword } = req.body;
+    const { token } = req.params;
+
+    if (!password || !confirmPassword) {
+      return res
+        .status(400)
+        .json({ message: 'Please provide password and confirm password' });
+    }
+
+    if (password !== confirmPassword) {
+      return res.status(400).json({ message: 'Passwords do not match' });
+    }
+
+    if (password.length < 6) {
+      return res
+        .status(400)
+        .json({ message: 'Password must be at least 6 characters' });
+    }
+
+    const hashedToken = crypto.createHash('sha256').update(token).digest('hex');
+
+    const user = await User.findOne({
+      passwordResetToken: hashedToken,
+      passwordResetExpires: { $gt: Date.now() },
+    });
+
+    if (!user) {
+      return res.status(400).json({
+        message:
+          'Invalid or expired reset token. Please request a new password reset.',
+      });
+    }
+
+    user.password = password;
+    user.passwordResetToken = undefined;
+    user.passwordResetExpires = undefined;
+    await user.save();
+
+    const jwtToken = signToken(user._id);
+
+    res.status(200).json({
+      status: 'success',
+      message: 'Password reset successful',
+      token: jwtToken,
+    });
+  } catch (err) {
+    res.status(500).json({
+      message: 'Failed to reset password',
+      error: err.message,
+    });
+  }
+};

controllers/brandController.js

@@ -0,0 +1,162 @@
+const Brand = require('../models/brandModel');
+const { deleteImage, getPublicIdFromUrl } = require('../config/cloudinary');
+
+// Get all brands
+exports.getAllBrands = async (req, res) => {
+  try {
+    const brands = await Brand.find().lean();
+    res.status(200).json({
+      status: 'success',
+      results: brands.length,
+      data: {
+        brands,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'fail',
+      message: err.message,
+    });
+  }
+};
+
+// Get single brand
+exports.getBrand = async (req, res) => {
+  try {
+    const brand = await Brand.findById(req.params.id).lean();
+    if (!brand) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'No brand found with that ID',
+      });
+    }
+    res.status(200).json({
+      status: 'success',
+      data: { brand },
+    });
+  } catch (err) {
+    res.status(400).json({
+      status: 'fail',
+      message: err.message,
+    });
+  }
+};
+
+// Create a new brand
+exports.createBrand = async (req, res) => {
+  try {
+    const lastBrand = await Brand.findOne().sort({ id: -1 });
+    const autoId = lastBrand ? lastBrand.id + 1 : 1;
+
+    const brandData = { ...req.body, id: req.body.id || autoId };
+    if (req.file) {
+      brandData.logo = req.file.path;
+    }
+
+    const newBrand = await Brand.create(brandData);
+
+    res.status(201).json({
+      status: 'success',
+      data: { brand: newBrand },
+    });
+  } catch (err) {
+    res.status(400).json({
+      status: 'fail',
+      message: err.message,
+    });
+  }
+};
+
+// Update a brand
+exports.updateBrand = async (req, res) => {
+  try {
+    const brandId = req.params.id;
+    const oldBrand = await Brand.findById(brandId);
+
+    if (!oldBrand) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'No brand found with that ID',
+      });
+    }
+
+    const updateData = { ...req.body };
+
+    // Handle logo update or deletion
+    if (req.file) {
+      // New logo uploaded
+      updateData.logo = req.file.path;
+
+      // Delete old logo from Cloudinary if it exists
+      if (oldBrand.logo) {
+        const publicId = getPublicIdFromUrl(oldBrand.logo);
+        if (publicId)
+          await deleteImage(publicId).catch((err) =>
+            console.error('Cloudinary delete error:', err),
+          );
+      }
+    } else if (req.body.logo === '') {
+      // Logo explicitly removed
+      updateData.logo = '';
+
+      // Delete old logo from Cloudinary if it exists
+      if (oldBrand.logo) {
+        const publicId = getPublicIdFromUrl(oldBrand.logo);
+        if (publicId)
+          await deleteImage(publicId).catch((err) =>
+            console.error('Cloudinary delete error:', err),
+          );
+      }
+    } else {
+      // Keep existing logo (don't let spreading req.body over oldBrand overwrite it with undefined)
+      delete updateData.logo;
+    }
+
+    const updatedBrand = await Brand.findByIdAndUpdate(brandId, updateData, {
+      new: true,
+      runValidators: true,
+    });
+
+    res.status(200).json({
+      status: 'success',
+      data: { brand: updatedBrand },
+    });
+  } catch (err) {
+    res.status(400).json({
+      status: 'fail',
+      message: err.message,
+    });
+  }
+};
+
+// Delete a brand
+exports.deleteBrand = async (req, res) => {
+  try {
+    const brand = await Brand.findById(req.params.id);
+
+    if (!brand) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'No brand found with that ID',
+      });
+    }
+
+    // Delete logo from Cloudinary if it exists
+    if (brand.logo) {
+      const publicId = getPublicIdFromUrl(brand.logo);
+      if (publicId) await deleteImage(publicId);
+    }
+
+    await Brand.findByIdAndDelete(req.params.id);
+
+    res.status(204).json({
+      status: 'success',
+      data: null,
+    });
+  } catch (err) {
+    res.status(400).json({
+      status: 'fail',
+      message: err.message,
+    });
+  }
+};

controllers/cartController.js

@@ -0,0 +1,279 @@
+const Cart = require('../models/cartModel');
+const Product = require('../models/productModel');
+// add to cart function
+exports.addToCart = async (req, res) => {
+  try {
+    const userId = req.user.id;
+    const { productId, quantity } = req.body;
+
+    const product = await Product.findById(productId);
+    if (!product) {
+      return res.status(404).json({ message: 'Product not found' });
+    }
+    let cart = await Cart.findOne({ user: userId });
+
+    if (!cart) {
+      cart = await Cart.create({
+        user: userId,
+        items: [{ product: productId, quantity }],
+      });
+    } else {
+      const existingItem = cart.items.find(
+        (item) => item.product.toString() === productId,
+      );
+
+      if (existingItem) {
+        existingItem.quantity += quantity;
+      } else {
+        cart.items.push({ product: productId, quantity });
+      }
+      await cart.save();
+    }
+
+    // Populate product details before returning
+    await cart.populate({
+      path: 'items.product',
+      select: 'nameAr nameEn price salePrice imageCover stock',
+    });
+
+    res.status(200).json({
+      status: 'success',
+      message: 'Product added to cart',
+      cart,
+    });
+  } catch (err) {
+    res
+      .status(500)
+      .json({ message: 'Failed to add product', error: err.message });
+  }
+};
+
+exports.getCart = async (req, res) => {
+  try {
+    const userId = req.user.id;
+
+    // Find the cart associated with the user
+    const cart = await Cart.findOne({ user: userId }).populate({
+      path: 'items.product',
+      select: 'nameAr nameEn price salePrice imageCover',
+    });
+
+    if (!cart || cart.items.length === 0) {
+      return res.status(200).json({
+        status: 'success',
+        message: 'Cart is empty',
+        cart: { items: [] },
+      });
+    }
+
+    // Calculate the total price
+    const totalPrice = cart.items.reduce((acc, item) => {
+      const price = item.product.salePrice || item.product.price;
+      return acc + price * item.quantity;
+    }, 0);
+
+    res.status(200).json({
+      status: 'success',
+      cart,
+      totalPrice,
+    });
+  } catch (err) {
+    res
+      .status(500)
+      .json({ message: 'Failed to fetch cart', error: err.message });
+  }
+};
+
+// PATCH /samoulla/v1/cart/update-quantity
+exports.updateQuantity = async (req, res) => {
+  try {
+    const userId = req.user.id;
+    const { productId, action } = req.body;
+
+    const cart = await Cart.findOne({ user: userId }).populate({
+      path: 'items.product',
+      select: 'nameAr nameEn price salePrice imageCover',
+    });
+
+    if (!cart) {
+      return res.status(404).json({ message: 'Cart not found' });
+    }
+
+    const cartItem = cart.items.find(
+      (el) => el.product._id.toString() === productId,
+    );
+
+    if (!cartItem) {
+      return res.status(404).json({ message: 'Product not found in cart' });
+    }
+
+    if (action === 'increase') {
+      cartItem.quantity += 1;
+    } else if (action === 'decrease') {
+      cartItem.quantity -= 1;
+
+      if (cartItem.quantity <= 0) {
+        cart.items = cart.items.filter(
+          (el) => el.product._id.toString() !== productId,
+        );
+      }
+    } else {
+      return res.status(400).json({ message: 'Invalid action' });
+    }
+
+    await cart.save();
+
+    const totalPrice = cart.items.reduce((acc, item) => {
+      const price = item.product.salePrice || item.product.price;
+      return acc + price * item.quantity;
+    }, 0);
+
+    res.status(200).json({
+      status: 'success',
+      cart,
+      totalPrice,
+    });
+  } catch (err) {
+    res
+      .status(500)
+      .json({ message: 'Error updating quantity', error: err.message });
+  }
+};
+
+// PATCH /samoulla/v1/cart/update-quantity
+// {
+//   "productId": "ID_OF_PRODUCT",
+//   "action": "increase"
+// }
+// {
+//   "productId": "ID_OF_PRODUCT",
+//   "action": "decrease"
+// }
+
+// DELETE /samoulla/v1/cart/remove-item
+exports.removeFromCart = async (req, res) => {
+  try {
+    const userId = req.user.id;
+    const { productId } = req.params;
+
+    const cart = await Cart.findOne({ user: userId }).populate({
+      path: 'items.product',
+      select: 'nameAr nameEn price salePrice imageCover',
+    });
+
+    if (!cart) {
+      return res.status(404).json({ message: 'Cart not found' });
+    }
+
+    const itemExists = cart.items.find(
+      (el) => el.product._id.toString() === productId,
+    );
+
+    if (!itemExists) {
+      return res.status(404).json({ message: 'Product not found in cart' });
+    }
+
+    cart.items = cart.items.filter(
+      (el) => el.product._id.toString() !== productId,
+    );
+
+    await cart.save();
+
+    const totalPrice = cart.items.reduce((acc, item) => {
+      const price = item.product.salePrice || item.product.price;
+      return acc + price * item.quantity;
+    }, 0);
+
+    res.status(200).json({
+      status: 'success',
+      message: 'Product removed from cart',
+      cart,
+      totalPrice,
+    });
+  } catch (err) {
+    res
+      .status(500)
+      .json({ message: 'Error removing product', error: err.message });
+  }
+};
+
+exports.clearCart = async (req, res) => {
+  try {
+    const cart = await Cart.findOne({ user: req.user._id });
+
+    if (!cart) {
+      return res.status(404).json({ message: 'Cart not found' });
+    }
+
+    cart.items = [];
+    await cart.save();
+
+    res.status(200).json({
+      status: 'success',
+      message: 'Cart cleared successfully',
+      cart,
+    });
+  } catch (err) {
+    res
+      .status(500)
+      .json({ message: 'Something went wrong', error: err.message });
+  }
+};
+
+// GET /samoulla/v1/cart/all (Admin only)
+exports.getAllCarts = async (req, res) => {
+  try {
+    // Find all carts that are not empty and belong to a user
+    const carts = await Cart.find({
+      user: { $exists: true, $ne: null },
+      items: { $exists: true, $not: { $size: 0 } },
+    })
+      .populate({
+        path: 'user',
+        select: 'name email phone',
+      })
+      .populate({
+        path: 'items.product',
+        select: 'nameAr nameEn price salePrice imageCover',
+      })
+      .sort('-updatedAt');
+
+    res.status(200).json({
+      status: 'success',
+      results: carts.length,
+      data: {
+        carts,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: 'Failed to fetch carts',
+      error: err.message,
+    });
+  }
+};
+// DELETE /samoulla/v1/cart/:id (Admin only)
+exports.deleteCart = async (req, res) => {
+  try {
+    const cart = await Cart.findByIdAndDelete(req.params.id);
+
+    if (!cart) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'No cart found with that ID',
+      });
+    }
+
+    res.status(204).json({
+      status: 'success',
+      data: null,
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: 'Failed to delete cart',
+      error: err.message,
+    });
+  }
+};

controllers/categoryController.js

@@ -0,0 +1,208 @@
+const Category = require('../models/categoryModel');
+
+// Get all categories (optionally filter by parent to get root categories or subcategories)
+exports.getAllCategories = async (req, res) => {
+  try {
+    const { parentId } = req.query;
+
+    // Build filter - if parentId is 'root' or null, get root categories
+    let filter = {};
+    if (parentId === 'root' || parentId === 'null') {
+      filter.parent = null;
+    } else if (parentId) {
+      filter.parent = parentId;
+    }
+
+    const categories = await Category.find(filter)
+      .sort({ id: 1 })
+      .populate('parent', 'nameAr nameEn slug')
+      .lean();
+    res.status(200).json({
+      status: 'success',
+      results: categories.length,
+      data: {
+        categories,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'fail',
+      message: err.message,
+    });
+  }
+};
+
+// Get single category with parent and children
+exports.getCategory = async (req, res) => {
+  try {
+    const category = await Category.findById(req.params.id)
+      .populate('parent', 'nameAr nameEn slug')
+      .populate('children', 'nameAr nameEn slug level')
+      .lean();
+    if (!category) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'No category found with that ID',
+      });
+    }
+    res.status(200).json({
+      status: 'success',
+      data: { category },
+    });
+  } catch (err) {
+    res.status(400).json({
+      status: 'fail',
+      message: err.message,
+    });
+  }
+};
+
+// Create a new category
+exports.createCategory = async (req, res) => {
+  try {
+    const lastCategory = await Category.findOne().sort({ id: -1 });
+    const autoId = lastCategory ? lastCategory.id + 1 : 1;
+
+    const newCategory = await Category.create({
+      // eslint-disable-next-line node/no-unsupported-features/es-syntax
+      ...req.body,
+      id: req.body.id || autoId,
+    });
+
+    res.status(201).json({
+      status: 'success',
+      data: { category: newCategory },
+    });
+  } catch (err) {
+    res.status(400).json({
+      status: 'fail',
+      message: err.message,
+    });
+  }
+};
+
+// Update a category
+exports.updateCategory = async (req, res) => {
+  try {
+    const updatedCategory = await Category.findByIdAndUpdate(
+      req.params.id,
+      req.body,
+      { new: true, runValidators: true },
+    );
+    if (!updatedCategory) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'No category found with that ID',
+      });
+    }
+    res.status(200).json({
+      status: 'success',
+      data: { category: updatedCategory },
+    });
+  } catch (err) {
+    res.status(400).json({
+      status: 'fail',
+      message: err.message,
+    });
+  }
+};
+
+// Delete a category
+exports.deleteCategory = async (req, res) => {
+  try {
+    // First check if category has children
+    const childrenCount = await Category.countDocuments({
+      parent: req.params.id,
+    });
+    if (childrenCount > 0) {
+      return res.status(400).json({
+        status: 'fail',
+        message:
+          'Cannot delete category with subcategories. Delete subcategories first.',
+      });
+    }
+
+    const category = await Category.findByIdAndDelete(req.params.id);
+    if (!category) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'No category found with that ID',
+      });
+    }
+    res.status(204).json({
+      status: 'success',
+      data: null,
+    });
+  } catch (err) {
+    res.status(400).json({
+      status: 'fail',
+      message: err.message,
+    });
+  }
+};
+
+// Get all subcategories of a specific category
+exports.getSubcategories = async (req, res) => {
+  try {
+    const subcategories = await Category.find({ parent: req.params.id }).sort({ id: 1 }).lean();
+    res.status(200).json({
+      status: 'success',
+      results: subcategories.length,
+      data: {
+        subcategories,
+      },
+    });
+  } catch (err) {
+    res.status(400).json({
+      status: 'fail',
+      message: err.message,
+    });
+  }
+};
+
+// Get full category tree (hierarchical structure)
+exports.getCategoryTree = async (req, res) => {
+  try {
+    // Fetch all categories once to build tree in memory
+    const allCategories = await Category.find().sort({ id: 1 }).lean();
+
+    const categoryMap = {};
+    allCategories.forEach((cat) => {
+      categoryMap[cat._id.toString()] = { ...cat, children: [] };
+    });
+
+    const tree = [];
+    allCategories.forEach((cat) => {
+      const catObj = categoryMap[cat._id.toString()];
+      if (cat.parent) {
+        const parentId = cat.parent.toString();
+        if (categoryMap[parentId]) {
+          categoryMap[parentId].children.push(catObj);
+        }
+      } else {
+        tree.push(catObj);
+      }
+    });
+
+    // Sort root categories and children by numeric id
+    tree.sort((a, b) => a.id - b.id);
+    tree.forEach((cat) => {
+      if (cat.children && cat.children.length > 0) {
+        cat.children.sort((a, b) => a.id - b.id);
+      }
+    });
+
+    res.status(200).json({
+      status: 'success',
+      results: tree.length,
+      data: {
+        categories: tree,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'fail',
+      message: err.message,
+    });
+  }
+};

controllers/contentController.js

@@ -0,0 +1,705 @@
+const HeroSlide = require('../models/heroSlideModel');
+const SiteSettings = require('../models/siteSettingsModel');
+const AnnouncementBar = require('../models/announcementBarModel');
+const SalesBanner = require('../models/salesBannerModel');
+const FeaturedBanner = require('../models/featuredBannerModel');
+const WhyChooseUs = require('../models/whyChooseUsModel');
+
+// ============================================
+// HERO SLIDES SECTION
+// ============================================
+
+/**
+ * @desc    Get all active hero slides (Public)
+ * @route   GET /api/content/hero-slides
+ * @access  Public
+ */
+exports.getHeroSlides = async (req, res) => {
+  try {
+    const slides = await HeroSlide.find({ isActive: true }).sort({ order: 1 });
+
+    res.status(200).json({
+      status: 'success',
+      results: slides.length,
+      data: slides,
+    });
+  } catch (error) {
+    res.status(500).json({
+      status: 'fail',
+      message: error.message,
+    });
+  }
+};
+
+/**
+ * @desc    Get all hero slides including inactive (Admin)
+ * @route   GET /api/content/hero-slides/admin/all
+ * @access  Private/Admin
+ */
+exports.getAllHeroSlidesAdmin = async (req, res) => {
+  try {
+    const slides = await HeroSlide.find().sort({ order: 1 });
+
+    res.status(200).json({
+      status: 'success',
+      results: slides.length,
+      data: slides,
+    });
+  } catch (error) {
+    res.status(500).json({
+      status: 'fail',
+      message: error.message,
+    });
+  }
+};
+
+/**
+ * @desc    Get single hero slide by ID
+ * @route   GET /api/content/hero-slides/:id
+ * @access  Public
+ */
+exports.getHeroSlideById = async (req, res) => {
+  try {
+    const slide = await HeroSlide.findById(req.params.id);
+
+    if (!slide) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'Slide not found',
+      });
+    }
+
+    res.status(200).json({
+      status: 'success',
+      data: slide,
+    });
+  } catch (error) {
+    res.status(500).json({
+      status: 'fail',
+      message: error.message,
+    });
+  }
+};
+
+/**
+ * @desc    Create a new hero slide
+ * @route   POST /api/content/hero-slides
+ * @access  Private/Admin
+ */
+exports.createHeroSlide = async (req, res) => {
+  try {
+    const {
+      _id,
+      type,
+      imageSrc,
+      videoSrc,
+      poster,
+      title,
+      description,
+      buttonText,
+      buttonLink,
+      order,
+      isActive,
+    } = req.body;
+
+    const slide = await HeroSlide.create({
+      _id,
+      type,
+      imageSrc,
+      videoSrc,
+      poster,
+      title,
+      description,
+      buttonText,
+      buttonLink,
+      order: order || 0,
+      isActive: isActive !== undefined ? isActive : true,
+    });
+
+    res.status(201).json({
+      status: 'success',
+      data: slide,
+    });
+  } catch (error) {
+    res.status(400).json({
+      status: 'fail',
+      message: error.message,
+    });
+  }
+};
+
+/**
+ * @desc    Update a hero slide
+ * @route   PUT /api/content/hero-slides/:id
+ * @access  Private/Admin
+ */
+exports.updateHeroSlide = async (req, res) => {
+  try {
+    const {
+      type,
+      imageSrc,
+      videoSrc,
+      poster,
+      title,
+      description,
+      buttonText,
+      buttonLink,
+      order,
+      isActive,
+    } = req.body;
+
+    const slide = await HeroSlide.findById(req.params.id);
+
+    if (!slide) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'Slide not found',
+      });
+    }
+
+    // Update fields
+    slide.type = type || slide.type;
+    slide.imageSrc = imageSrc !== undefined ? imageSrc : slide.imageSrc;
+    slide.videoSrc = videoSrc !== undefined ? videoSrc : slide.videoSrc;
+    slide.poster = poster !== undefined ? poster : slide.poster;
+    slide.title = title !== undefined ? title : slide.title;
+    slide.description =
+      description !== undefined ? description : slide.description;
+    slide.buttonText = buttonText !== undefined ? buttonText : slide.buttonText;
+    slide.buttonLink = buttonLink !== undefined ? buttonLink : slide.buttonLink;
+    slide.order = order !== undefined ? order : slide.order;
+    slide.isActive = isActive !== undefined ? isActive : slide.isActive;
+
+    const updatedSlide = await slide.save();
+
+    res.status(200).json({
+      status: 'success',
+      data: updatedSlide,
+    });
+  } catch (error) {
+    res.status(400).json({
+      status: 'fail',
+      message: error.message,
+    });
+  }
+};
+
+/**
+ * @desc    Delete a hero slide
+ * @route   DELETE /api/content/hero-slides/:id
+ * @access  Private/Admin
+ */
+exports.deleteHeroSlide = async (req, res) => {
+  try {
+    const slide = await HeroSlide.findById(req.params.id);
+
+    if (!slide) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'Slide not found',
+      });
+    }
+
+    await HeroSlide.findByIdAndDelete(req.params.id);
+
+    res.status(200).json({
+      status: 'success',
+      message: 'Slide deleted successfully',
+    });
+  } catch (error) {
+    res.status(500).json({
+      status: 'fail',
+      message: error.message,
+    });
+  }
+};
+
+// ============================================
+// SITE SETTINGS SECTION
+// ============================================
+
+/**
+ * @desc    Get site settings
+ * @route   GET /api/content/settings
+ * @access  Public
+ */
+exports.getSiteSettings = async (req, res) => {
+  try {
+    const settings = await SiteSettings.getSettings();
+
+    res.status(200).json({
+      status: 'success',
+      data: settings,
+    });
+  } catch (error) {
+    res.status(500).json({
+      status: 'fail',
+      message: error.message,
+    });
+  }
+};
+
+// ============================================
+// ANNOUNCEMENT BAR SECTION
+// ============================================
+
+/**
+ * @desc    Get announcement bar settings
+ * @route   GET /api/content/announcement-bar
+ * @access  Public
+ */
+exports.getAnnouncementBar = async (req, res) => {
+  try {
+    const settings = await AnnouncementBar.getSettings();
+
+    res.status(200).json({
+      status: 'success',
+      data: settings,
+    });
+  } catch (error) {
+    console.error('ERROR in getAnnouncementBar:', error);
+    res.status(500).json({
+      status: 'fail',
+      message: error.message,
+    });
+  }
+};
+
+/**
+ * @desc    Update announcement bar settings
+ * @route   PUT /api/content/announcement-bar
+ * @access  Private/Admin
+ */
+exports.updateAnnouncementBar = async (req, res) => {
+  try {
+    const settings = await AnnouncementBar.getSettings();
+
+    // Update permitted fields
+    const restrictedFields = ['_id', '__v', 'createdAt', 'updatedAt'];
+    Object.keys(req.body).forEach((key) => {
+      if (!restrictedFields.includes(key)) {
+        settings[key] = req.body[key];
+      }
+    });
+
+    const updatedSettings = await settings.save();
+
+    res.status(200).json({
+      status: 'success',
+      data: updatedSettings,
+    });
+  } catch (error) {
+    console.error('ERROR in updateAnnouncementBar:', error);
+    res.status(400).json({
+      status: 'fail',
+      message: error.message,
+    });
+  }
+};
+
+/**
+ * @desc    Update site settings
+ * @route   PUT /api/content/settings
+ * @access  Private/Admin
+ */
+exports.updateSiteSettings = async (req, res) => {
+  try {
+    const settings = await SiteSettings.getSettings();
+
+    // Update fields if provided
+    if (req.body.topBar) {
+      settings.topBar = { ...settings.topBar, ...req.body.topBar };
+    }
+    if (req.body.footer) {
+      settings.footer = { ...settings.footer, ...req.body.footer };
+    }
+    if (req.body.legalPages) {
+      if (req.body.legalPages.termsAndConditions) {
+        settings.legalPages.termsAndConditions = {
+          ...settings.legalPages.termsAndConditions,
+          ...req.body.legalPages.termsAndConditions,
+          lastUpdated: Date.now(),
+        };
+      }
+      if (req.body.legalPages.privacyPolicy) {
+        settings.legalPages.privacyPolicy = {
+          ...settings.legalPages.privacyPolicy,
+          ...req.body.legalPages.privacyPolicy,
+          lastUpdated: Date.now(),
+        };
+      }
+    }
+
+    const updatedSettings = await settings.save();
+
+    res.status(200).json({
+      status: 'success',
+      data: updatedSettings,
+    });
+  } catch (error) {
+    res.status(400).json({
+      status: 'fail',
+      message: error.message,
+    });
+  }
+};
+
+// ============================================
+// SALES BANNERS SECTION
+// ============================================
+
+/**
+ * @desc    Get all active sales banners
+ * @route   GET /api/content/sales-banners
+ * @access  Public
+ */
+exports.getSalesBanners = async (req, res) => {
+  try {
+    const banners = await SalesBanner.find({ isActive: true }).sort({
+      order: 1,
+    });
+
+    res.status(200).json({
+      status: 'success',
+      results: banners.length,
+      data: banners,
+    });
+  } catch (error) {
+    res.status(500).json({
+      status: 'fail',
+      message: error.message,
+    });
+  }
+};
+
+/**
+ * @desc    Get all sales banners including inactive (Admin)
+ * @route   GET /api/content/sales-banners/admin/all
+ * @access  Private/Admin
+ */
+exports.getAllSalesBannersAdmin = async (req, res) => {
+  try {
+    const banners = await SalesBanner.find().sort({ order: 1 });
+
+    res.status(200).json({
+      status: 'success',
+      results: banners.length,
+      data: banners,
+    });
+  } catch (error) {
+    res.status(500).json({
+      status: 'fail',
+      message: error.message,
+    });
+  }
+};
+
+/**
+ * @desc    Create a new sales banner
+ * @route   POST /api/content/sales-banners
+ * @access  Private/Admin
+ */
+exports.createSalesBanner = async (req, res) => {
+  try {
+    const banner = await SalesBanner.create(req.body);
+
+    res.status(201).json({
+      status: 'success',
+      data: banner,
+    });
+  } catch (error) {
+    res.status(400).json({
+      status: 'fail',
+      message: error.message,
+    });
+  }
+};
+
+/**
+ * @desc    Update a sales banner
+ * @route   PUT /api/content/sales-banners/:id
+ * @access  Private/Admin
+ */
+exports.updateSalesBanner = async (req, res) => {
+  try {
+    const banner = await SalesBanner.findByIdAndUpdate(
+      req.params.id,
+      req.body,
+      {
+        new: true,
+        runValidators: true,
+      },
+    );
+
+    if (!banner) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'Banner not found',
+      });
+    }
+
+    res.status(200).json({
+      status: 'success',
+      data: banner,
+    });
+  } catch (error) {
+    res.status(400).json({
+      status: 'fail',
+      message: error.message,
+    });
+  }
+};
+
+/**
+ * @desc    Delete a sales banner
+ * @route   DELETE /api/content/sales-banners/:id
+ * @access  Private/Admin
+ */
+exports.deleteSalesBanner = async (req, res) => {
+  try {
+    const banner = await SalesBanner.findByIdAndDelete(req.params.id);
+
+    if (!banner) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'Banner not found',
+      });
+    }
+
+    res.status(200).json({
+      status: 'success',
+      message: 'Banner deleted successfully',
+    });
+  } catch (error) {
+    res.status(500).json({
+      status: 'fail',
+      message: error.message,
+    });
+  }
+};
+
+/**
+ * @desc    Delete all sales banners
+ * @route   DELETE /api/content/sales-banners
+ * @access  Private/Admin
+ */
+exports.deleteAllSalesBanners = async (req, res) => {
+  try {
+    await SalesBanner.deleteMany({});
+
+    res.status(200).json({
+      status: 'success',
+      message: 'All banners deleted successfully',
+    });
+  } catch (error) {
+    res.status(500).json({
+      status: 'fail',
+      message: error.message,
+    });
+  }
+};
+// ============================================
+// FEATURED BANNERS SECTION
+// ============================================
+
+/**
+ * @desc    Get all active featured banners
+ * @route   GET /api/content/featured-banners
+ * @access  Public
+ */
+exports.getFeaturedBanners = async (req, res) => {
+  try {
+    const banners = await FeaturedBanner.find({ isActive: true });
+
+    res.status(200).json({
+      status: 'success',
+      results: banners.length,
+      data: banners,
+    });
+  } catch (error) {
+    res.status(500).json({
+      status: 'fail',
+      message: error.message,
+    });
+  }
+};
+
+/**
+ * @desc    Get all featured banners including inactive (Admin)
+ * @route   GET /api/content/featured-banners/admin/all
+ * @access  Private/Admin
+ */
+exports.getAllFeaturedBannersAdmin = async (req, res) => {
+  try {
+    const banners = await FeaturedBanner.find();
+
+    res.status(200).json({
+      status: 'success',
+      results: banners.length,
+      data: banners,
+    });
+  } catch (error) {
+    res.status(500).json({
+      status: 'fail',
+      message: error.message,
+    });
+  }
+};
+
+/**
+ * @desc    Create a new featured banner
+ * @route   POST /api/content/featured-banners
+ * @access  Private/Admin
+ */
+exports.createFeaturedBanner = async (req, res) => {
+  try {
+    const banner = await FeaturedBanner.create(req.body);
+
+    res.status(201).json({
+      status: 'success',
+      data: banner,
+    });
+  } catch (error) {
+    res.status(400).json({
+      status: 'fail',
+      message: error.message,
+    });
+  }
+};
+
+/**
+ * @desc    Update a featured banner
+ * @route   PUT /api/content/featured-banners/:id
+ * @access  Private/Admin
+ */
+exports.updateFeaturedBanner = async (req, res) => {
+  try {
+    const banner = await FeaturedBanner.findByIdAndUpdate(
+      req.params.id,
+      req.body,
+      {
+        new: true,
+        runValidators: true,
+      },
+    );
+
+    if (!banner) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'Banner not found',
+      });
+    }
+
+    res.status(200).json({
+      status: 'success',
+      data: banner,
+    });
+  } catch (error) {
+    res.status(400).json({
+      status: 'fail',
+      message: error.message,
+    });
+  }
+};
+
+/**
+ * @desc    Delete a featured banner
+ * @route   DELETE /api/content/featured-banners/:id
+ * @access  Private/Admin
+ */
+exports.deleteFeaturedBanner = async (req, res) => {
+  try {
+    const banner = await FeaturedBanner.findByIdAndDelete(req.params.id);
+
+    if (!banner) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'Banner not found',
+      });
+    }
+
+    res.status(200).json({
+      status: 'success',
+      message: 'Banner deleted successfully',
+    });
+  } catch (error) {
+    res.status(500).json({
+      status: 'fail',
+      message: error.message,
+    });
+  }
+};
+
+/**
+ * @desc    Delete all featured banners
+ * @route   DELETE /api/content/featured-banners
+ * @access  Private/Admin
+ */
+exports.deleteAllFeaturedBanners = async (req, res) => {
+  try {
+    await FeaturedBanner.deleteMany({});
+
+    res.status(200).json({
+      status: 'success',
+      message: 'All banners deleted successfully',
+    });
+  } catch (error) {
+    res.status(500).json({
+      status: 'fail',
+      message: error.message,
+    });
+  }
+};
+
+// ============================================
+// WHY CHOOSE US SECTION
+// ============================================
+
+/**
+ * @desc    Get Why Choose Us settings
+ * @route   GET /api/content/why-choose-us
+ * @access  Public
+ */
+exports.getWhyChooseUs = async (req, res) => {
+  try {
+    const settings = await WhyChooseUs.getSettings();
+    res.status(200).json({
+      status: 'success',
+      data: settings,
+    });
+  } catch (error) {
+    res.status(500).json({
+      status: 'fail',
+      message: error.message,
+    });
+  }
+};
+
+/**
+ * @desc    Update Why Choose Us settings
+ * @route   PUT /api/content/why-choose-us
+ * @access  Private/Admin
+ */
+exports.updateWhyChooseUs = async (req, res) => {
+  try {
+    const settings = await WhyChooseUs.getSettings();
+
+    const restrictedFields = ['_id', '__v', 'createdAt', 'updatedAt'];
+    Object.keys(req.body).forEach((key) => {
+      if (!restrictedFields.includes(key)) {
+        settings[key] = req.body[key];
+      }
+    });
+
+    const updated = await settings.save();
+    res.status(200).json({
+      status: 'success',
+      data: updated,
+    });
+  } catch (error) {
+    res.status(400).json({
+      status: 'fail',
+      message: error.message,
+    });
+  }
+};

controllers/favoriteController.js

@@ -0,0 +1,106 @@
+const Favorite = require('../models/favoriteModel');
+const Product = require('../models/productModel');
+
+exports.addToFavorites = async (req, res) => {
+  try {
+    const { productId } = req.body;
+
+    // Check product exists
+    const productExists = await Product.findById(productId);
+    if (!productExists) {
+      return res.status(404).json({ message: 'Product not found' });
+    }
+
+    // Check if user has favorite list
+    let fav = await Favorite.findOne({ user: req.user._id });
+
+    if (!fav) {
+      fav = await Favorite.create({
+        user: req.user._id,
+        products: [productId],
+      });
+    } else {
+      if (fav.products.some((p) => p.toString() === productId.toString())) {
+        return res
+          .status(400)
+          .json({ message: 'Product already in favorites' });
+      }
+
+      fav.products.push(productId);
+      await fav.save();
+    }
+
+    res.status(200).json({
+      status: 'success',
+      favorites: fav,
+    });
+  } catch (err) {
+    res.status(500).json({ message: 'Failed to add', error: err.message });
+  }
+};
+
+exports.removeFromFavorites = async (req, res) => {
+  try {
+    const { productId } = req.body;
+
+    const fav = await Favorite.findOne({ user: req.user._id });
+
+    if (!fav) {
+      return res.status(404).json({ message: 'Favorites list not found' });
+    }
+
+    fav.products = fav.products.filter(
+      (p) => p.toString() !== productId.toString(),
+    );
+
+    await fav.save();
+
+    res.status(200).json({
+      status: 'success',
+      message: 'Product removed',
+      favorites: fav,
+    });
+  } catch (err) {
+    res.status(500).json({ message: 'Failed to remove', error: err.message });
+  }
+};
+
+exports.getFavorites = async (req, res) => {
+  try {
+    const fav = await Favorite.findOne({ user: req.user._id }).populate(
+      'products',
+    );
+
+    res.status(200).json({
+      status: 'success',
+      favorites: fav || { user: req.user._id, products: [] },
+    });
+  } catch (err) {
+    res
+      .status(500)
+      .json({ message: 'Failed to load favorites', error: err.message });
+  }
+};
+
+exports.clearFavorites = async (req, res) => {
+  try {
+    const fav = await Favorite.findOne({ user: req.user._id });
+
+    if (!fav) {
+      return res.status(404).json({ message: 'Favorites list not found' });
+    }
+
+    fav.products = [];
+    await fav.save();
+
+    res.status(200).json({
+      status: 'success',
+      message: 'All products removed from favorites',
+      favorites: fav,
+    });
+  } catch (err) {
+    res
+      .status(500)
+      .json({ message: 'Failed to clear favorites', error: err.message });
+  }
+};

controllers/financeController.js

@@ -0,0 +1,1711 @@
+const Order = require('../models/orderModel');
+const Transaction = require('../models/transactionModel');
+const Provider = require('../models/providerModel');
+const Product = require('../models/productModel');
+const Expense = require('../models/expenseModel');
+const Capital = require('../models/capitalModel');
+const {
+  CapitalAccount,
+  CapitalTransfer,
+} = require('../models/capitalAccountModel');
+const User = require('../models/userModel');
+
+// ─────────────────────────────────────────────
+// HELPER: Get only external (non-platform) providers
+// Excludes the platform owner (Yadawy) by checking:
+//   1. Provider's linked user has role admin/superadmin
+//   2. Provider has no linked user but storeName matches platform name
+// ─────────────────────────────────────────────
+const PLATFORM_STORE_NAMES = ['samoulla', 'سامويلا'];
+
+const getExternalProviders = async () => {
+  // Find user IDs that are admin or superadmin
+  const adminUsers = await User.find(
+    { role: { $in: ['admin', 'superadmin'] } },
+    '_id',
+  );
+  const adminUserIds = adminUsers.map((u) => u._id.toString());
+
+  // Fetch all providers with their user populated
+  const allProviders = await Provider.find({}).populate('user', 'role');
+
+  // Filter out platform-owned providers
+  return allProviders.filter((provider) => {
+    // Exclude if linked user is admin/superadmin
+    if (provider.user && adminUserIds.includes(provider.user._id.toString())) {
+      return false;
+    }
+    // Exclude if storeName matches platform names (case-insensitive)
+    if (
+      PLATFORM_STORE_NAMES.includes(
+        (provider.storeName || '').toLowerCase().trim(),
+      )
+    ) {
+      return false;
+    }
+    return true;
+  });
+};
+
+// ─────────────────────────────────────────────
+// HELPER: Calculate financials with optional date range
+// ─────────────────────────────────────────────
+const calculateFinancials = async (startDate, endDate) => {
+  const query = { orderStatus: 'completed' };
+
+  if (startDate || endDate) {
+    query.createdAt = {};
+    if (startDate) query.createdAt.$gte = new Date(startDate);
+    if (endDate) query.createdAt.$lte = new Date(endDate);
+  }
+
+  const orders = await Order.find(query).populate({
+    path: 'items.product',
+    populate: {
+      path: 'provider',
+      populate: { path: 'user' },
+    },
+  });
+
+  let totalWebsiteProfit = 0;
+  let websiteOwnedProfit = 0;
+  let vendorOwnedProfit = 0;
+  let totalRevenue = 0;
+
+  const vendorMap = {};
+
+  for (const order of orders) {
+    for (const item of order.items) {
+      const product = item.product;
+      if (!product || !product.provider) continue;
+
+      const quantity = item.quantity;
+      const sellingPrice = item.unitPrice;
+      const costPrice = product.costPrice || 0;
+      const purchasePrice = product.purchasePrice || 0;
+
+      const itemRevenue = sellingPrice * quantity;
+      const itemWebsiteProfit = (sellingPrice - costPrice) * quantity;
+
+      totalRevenue += itemRevenue;
+
+      const providerUser = product.provider.user;
+      const providerStoreName = (product.provider.storeName || '')
+        .toLowerCase()
+        .trim();
+      let isWebsiteOwned = false;
+
+      if (
+        (providerUser &&
+          (providerUser.role === 'admin' ||
+            providerUser.role === 'superadmin')) ||
+        // If provider is Samoulla or provider ID matches platform IDs
+        PLATFORM_STORE_NAMES.includes(providerStoreName)
+      ) {
+        isWebsiteOwned = true;
+      }
+
+      totalWebsiteProfit += itemWebsiteProfit;
+
+      if (isWebsiteOwned) {
+        websiteOwnedProfit += itemWebsiteProfit;
+      } else {
+        vendorOwnedProfit += itemWebsiteProfit;
+
+        const pid = product.provider._id.toString();
+
+        if (!vendorMap[pid]) {
+          vendorMap[pid] = {
+            totalDeliveredSales: 0,
+            totalRevenueOwed: 0,
+            totalPurchaseCost: 0,
+          };
+        }
+
+        vendorMap[pid].totalDeliveredSales += sellingPrice * quantity;
+        vendorMap[pid].totalRevenueOwed += costPrice * quantity;
+        vendorMap[pid].totalPurchaseCost += purchasePrice * quantity;
+      }
+    }
+  }
+
+  return {
+    totalWebsiteProfit,
+    websiteOwnedProfit,
+    vendorOwnedProfit,
+    totalRevenue,
+    vendorMap,
+  };
+};
+
+// ═════════════════════════════════════════════
+//  ADMIN ENDPOINTS
+// ═════════════════════════════════════════════
+
+// ───────────────��─────────────────────────────
+// GET /finance/admin/stats
+// Admin Financial Overview + Vendors Table
+// Supports ?startDate=...&endDate=...
+// ─────────────────────────────────────────────
+exports.getAdminFinancialStats = async (req, res) => {
+  try {
+    const { startDate, endDate } = req.query;
+
+    const {
+      totalWebsiteProfit,
+      websiteOwnedProfit,
+      vendorOwnedProfit,
+      totalRevenue,
+      vendorMap,
+    } = await calculateFinancials(startDate, endDate);
+
+    const allProviders = await getExternalProviders();
+
+    // Get payouts (optionally filtered by date)
+    const payoutQuery = { type: 'payout' };
+    if (startDate || endDate) {
+      payoutQuery.date = {};
+      if (startDate) payoutQuery.date.$gte = new Date(startDate);
+      if (endDate) payoutQuery.date.$lte = new Date(endDate);
+    }
+    const payouts = await Transaction.find(payoutQuery);
+    const payoutMap = {};
+    payouts.forEach((t) => {
+      const pid = t.provider.toString();
+      payoutMap[pid] = (payoutMap[pid] || 0) + t.amount;
+    });
+
+    const vendorSummary = [];
+
+    for (const provider of allProviders) {
+      const pid = provider._id.toString();
+      const stats = vendorMap[pid] || {
+        totalDeliveredSales: 0,
+        totalRevenueOwed: 0,
+        totalPurchaseCost: 0,
+      };
+      const paidAmount = payoutMap[pid] || 0;
+
+      const vendorProfit = stats.totalRevenueOwed - stats.totalPurchaseCost;
+      const platformCommission =
+        stats.totalDeliveredSales - stats.totalRevenueOwed;
+
+      vendorSummary.push({
+        provider: {
+          _id: provider._id,
+          name: provider.name,
+          storeName: provider.storeName,
+        },
+        totalSales: stats.totalDeliveredSales,
+        vendorProfit,
+        platformCommission,
+        totalOwed: stats.totalRevenueOwed,
+        paidAmount,
+        remainingBalance: stats.totalRevenueOwed - paidAmount,
+      });
+    }
+
+    // Get expenses total for the period
+    const expenseQuery = {};
+    if (startDate || endDate) {
+      expenseQuery.date = {};
+      if (startDate) expenseQuery.date.$gte = new Date(startDate);
+      if (endDate) expenseQuery.date.$lte = new Date(endDate);
+    }
+    const expenses = await Expense.find(expenseQuery);
+    const totalExpenses = expenses.reduce((sum, e) => sum + e.amount, 0);
+
+    // Get capital info
+    const capital = await Capital.getCapital();
+
+    res.status(200).json({
+      status: 'success',
+      data: {
+        totalRevenue,
+        totalWebsiteProfit,
+        profitSplit: {
+          websiteOwned: websiteOwnedProfit,
+          vendorOwned: vendorOwnedProfit,
+        },
+        totalExpenses,
+        netProfit: totalWebsiteProfit - totalExpenses,
+        capital: {
+          initial: capital.initialCapital,
+          current: capital.currentCapital,
+        },
+        vendorSummary,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};
+
+// ─────────────────────────────────────────────
+// POST /finance/admin/payout
+// Create a payout and log to capital
+// ─────────────────────────────────────────────
+exports.createPayout = async (req, res) => {
+  try {
+    const { providerId, amount, note, paymentMethod, referenceId } = req.body;
+
+    if (!amount || amount <= 0) {
+      return res
+        .status(400)
+        .json({ status: 'fail', message: 'Amount must be positive' });
+    }
+
+    const provider = await Provider.findById(providerId);
+    if (!provider) {
+      return res
+        .status(404)
+        .json({ status: 'fail', message: 'Provider not found' });
+    }
+
+    const transaction = await Transaction.create({
+      provider: providerId,
+      admin: req.user._id,
+      amount,
+      type: 'payout',
+      note,
+      paymentMethod,
+      referenceId,
+    });
+
+    // Decrease capital
+    const capital = await Capital.getCapital();
+    capital.currentCapital -= amount;
+    capital.logs.push({
+      type: 'vendor_payout',
+      amount: -amount,
+      balanceAfter: capital.currentCapital,
+      reference: transaction._id,
+      referenceModel: 'Transaction',
+      description:
+        `Payout to ${provider.storeName || provider.name}: ${note || ''}`.trim(),
+      date: new Date(),
+      createdBy: req.user._id,
+    });
+    await capital.save();
+
+    res.status(201).json({
+      status: 'success',
+      data: {
+        transaction,
+        capitalAfter: capital.currentCapital,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};
+
+// ═════════════════════════════════════════════
+//  CAPITAL MANAGEMENT
+// ═════════════════════════════════════════════
+
+// GET /finance/admin/capital
+exports.getCapital = async (req, res) => {
+  try {
+    const capital = await Capital.getCapital();
+    res.status(200).json({
+      status: 'success',
+      data: {
+        initialCapital: capital.initialCapital,
+        currentCapital: capital.currentCapital,
+        logsCount: capital.logs.length,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};
+
+// PUT /finance/admin/capital
+// Set/update initial capital
+exports.setCapital = async (req, res) => {
+  try {
+    const { initialCapital } = req.body;
+
+    if (initialCapital === undefined || initialCapital < 0) {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'initialCapital must be a non-negative number',
+      });
+    }
+
+    const capital = await Capital.getCapital();
+    const diff = initialCapital - capital.initialCapital;
+
+    capital.initialCapital = initialCapital;
+    capital.currentCapital += diff;
+
+    capital.logs.push({
+      type: 'initial',
+      amount: diff,
+      balanceAfter: capital.currentCapital,
+      description: `Initial capital set to ${initialCapital}`,
+      date: new Date(),
+      createdBy: req.user._id,
+    });
+
+    await capital.save();
+
+    res.status(200).json({
+      status: 'success',
+      data: {
+        initialCapital: capital.initialCapital,
+        currentCapital: capital.currentCapital,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};
+
+// POST /finance/admin/capital/adjust
+// Manual adjustment (add/subtract) to capital
+exports.adjustCapital = async (req, res) => {
+  try {
+    const { amount, description } = req.body;
+
+    if (amount === undefined || amount === 0) {
+      return res
+        .status(400)
+        .json({ status: 'fail', message: 'Amount must be a non-zero number' });
+    }
+
+    const capital = await Capital.getCapital();
+    capital.currentCapital += amount;
+
+    capital.logs.push({
+      type: 'adjustment',
+      amount,
+      balanceAfter: capital.currentCapital,
+      description:
+        description || `Manual adjustment: ${amount > 0 ? '+' : ''}${amount}`,
+      date: new Date(),
+      createdBy: req.user._id,
+    });
+
+    await capital.save();
+
+    res.status(200).json({
+      status: 'success',
+      data: {
+        currentCapital: capital.currentCapital,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};
+
+// GET /finance/admin/capital/timeline
+// Returns capital log entries for chart display
+exports.getCapitalTimeline = async (req, res) => {
+  try {
+    const { startDate, endDate, limit } = req.query;
+    const capital = await Capital.getCapital();
+
+    let logs = capital.logs || [];
+
+    // Filter by date
+    if (startDate) {
+      const sd = new Date(startDate);
+      logs = logs.filter((l) => l.date >= sd);
+    }
+    if (endDate) {
+      const ed = new Date(endDate);
+      logs = logs.filter((l) => l.date <= ed);
+    }
+
+    // Sort by date ascending for timeline
+    logs.sort((a, b) => a.date - b.date);
+
+    // Limit
+    if (limit) {
+      logs = logs.slice(-parseInt(limit, 10));
+    }
+
+    res.status(200).json({
+      status: 'success',
+      results: logs.length,
+      data: { logs },
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};
+
+// ═════════════════════════════════════════════
+//  EXPENSE MANAGEMENT
+// ═════════════════════════════════════════════
+
+// GET /finance/admin/expenses
+exports.getExpenses = async (req, res) => {
+  try {
+    const { startDate, endDate, category, page = 1, limit = 50 } = req.query;
+    const query = {};
+
+    if (startDate || endDate) {
+      query.date = {};
+      if (startDate) query.date.$gte = new Date(startDate);
+      if (endDate) query.date.$lte = new Date(endDate);
+    }
+    if (category) query.category = category;
+
+    const skip = (parseInt(page, 10) - 1) * parseInt(limit, 10);
+
+    const [expenses, total] = await Promise.all([
+      Expense.find(query)
+        .sort('-date')
+        .skip(skip)
+        .limit(parseInt(limit, 10))
+        .populate('createdBy', 'name email'),
+      Expense.countDocuments(query),
+    ]);
+
+    const totalAmount = await Expense.aggregate([
+      { $match: query },
+      { $group: { _id: null, total: { $sum: '$amount' } } },
+    ]);
+
+    // Category breakdown
+    const categoryBreakdown = await Expense.aggregate([
+      { $match: query },
+      {
+        $group: {
+          _id: '$category',
+          total: { $sum: '$amount' },
+          count: { $sum: 1 },
+        },
+      },
+      { $sort: { total: -1 } },
+    ]);
+
+    res.status(200).json({
+      status: 'success',
+      results: expenses.length,
+      totalRecords: total,
+      data: {
+        expenses,
+        totalExpenses: (totalAmount[0] && totalAmount[0].total) || 0,
+        categoryBreakdown,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};
+
+// POST /finance/admin/expenses
+exports.createExpense = async (req, res) => {
+  try {
+    const { category, amount, date, notes } = req.body;
+
+    if (!category || !amount) {
+      return res
+        .status(400)
+        .json({ status: 'fail', message: 'category and amount are required' });
+    }
+
+    const expense = await Expense.create({
+      category,
+      amount,
+      date: date || new Date(),
+      notes: notes || '',
+      createdBy: req.user._id,
+    });
+
+    // Decrease capital
+    const capital = await Capital.getCapital();
+    capital.currentCapital -= amount;
+    capital.logs.push({
+      type: 'expense',
+      amount: -amount,
+      balanceAfter: capital.currentCapital,
+      reference: expense._id,
+      referenceModel: 'Expense',
+      description: `Expense (${category}): ${notes || ''}`.trim(),
+      date: expense.date,
+      createdBy: req.user._id,
+    });
+    await capital.save();
+
+    res.status(201).json({
+      status: 'success',
+      data: {
+        expense,
+        capitalAfter: capital.currentCapital,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};
+
+// PUT /finance/admin/expenses/:id
+exports.updateExpense = async (req, res) => {
+  try {
+    const expense = await Expense.findById(req.params.id);
+    if (!expense) {
+      return res
+        .status(404)
+        .json({ status: 'fail', message: 'Expense not found' });
+    }
+
+    const oldAmount = expense.amount;
+
+    // Update fields
+    if (req.body.category) expense.category = req.body.category;
+    if (req.body.amount !== undefined) expense.amount = req.body.amount;
+    if (req.body.date) expense.date = req.body.date;
+    if (req.body.notes !== undefined) expense.notes = req.body.notes;
+
+    await expense.save();
+
+    // Adjust capital for difference
+    const diff = oldAmount - expense.amount; // positive if expense decreased
+    if (diff !== 0) {
+      const capital = await Capital.getCapital();
+      capital.currentCapital += diff;
+      capital.logs.push({
+        type: 'adjustment',
+        amount: diff,
+        balanceAfter: capital.currentCapital,
+        reference: expense._id,
+        referenceModel: 'Expense',
+        description: `Expense updated (${expense.category}): ${oldAmount} → ${expense.amount}`,
+        date: new Date(),
+        createdBy: req.user._id,
+      });
+      await capital.save();
+    }
+
+    res.status(200).json({
+      status: 'success',
+      data: { expense },
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};
+
+// DELETE /finance/admin/expenses/:id
+exports.deleteExpense = async (req, res) => {
+  try {
+    const expense = await Expense.findById(req.params.id);
+    if (!expense) {
+      return res
+        .status(404)
+        .json({ status: 'fail', message: 'Expense not found' });
+    }
+
+    // Restore capital
+    const capital = await Capital.getCapital();
+    capital.currentCapital += expense.amount;
+    capital.logs.push({
+      type: 'adjustment',
+      amount: expense.amount,
+      balanceAfter: capital.currentCapital,
+      description: `Expense deleted (${expense.category}): +${expense.amount} restored`,
+      date: new Date(),
+      createdBy: req.user._id,
+    });
+    await capital.save();
+
+    await Expense.findByIdAndDelete(req.params.id);
+
+    res.status(200).json({
+      status: 'success',
+      message: 'Expense deleted and capital restored',
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};
+
+// ═════════════════════════════════════════════
+//  ANALYTICS (Admin)
+// ═════════════════════════════════════════════
+
+// GET /finance/admin/analytics/monthly-profit
+// Returns monthly profit data for charts
+exports.getMonthlyProfit = async (req, res) => {
+  try {
+    const { year } = req.query;
+    const targetYear = parseInt(year, 10) || new Date().getFullYear();
+
+    const startOfYear = new Date(targetYear, 0, 1);
+    const endOfYear = new Date(targetYear, 11, 31, 23, 59, 59);
+
+    // Aggregate completed orders by month
+    const monthlyData = await Order.aggregate([
+      {
+        $match: {
+          orderStatus: 'completed',
+          createdAt: { $gte: startOfYear, $lte: endOfYear },
+        },
+      },
+      { $unwind: '$items' },
+      {
+        $lookup: {
+          from: 'products',
+          localField: 'items.product',
+          foreignField: '_id',
+          as: 'productInfo',
+        },
+      },
+      { $unwind: { path: '$productInfo', preserveNullAndEmptyArrays: true } },
+      {
+        $group: {
+          _id: { $month: '$createdAt' },
+          totalRevenue: {
+            $sum: { $multiply: ['$items.unitPrice', '$items.quantity'] },
+          },
+          totalCost: {
+            $sum: {
+              $multiply: [
+                { $ifNull: ['$productInfo.costPrice', 0] },
+                '$items.quantity',
+              ],
+            },
+          },
+          orderCount: { $sum: 1 },
+        },
+      },
+      { $sort: { _id: 1 } },
+    ]);
+
+    // Get monthly expenses
+    const monthlyExpenses = await Expense.aggregate([
+      {
+        $match: {
+          date: { $gte: startOfYear, $lte: endOfYear },
+        },
+      },
+      {
+        $group: {
+          _id: { $month: '$date' },
+          totalExpenses: { $sum: '$amount' },
+        },
+      },
+      { $sort: { _id: 1 } },
+    ]);
+
+    const expenseMap = {};
+    monthlyExpenses.forEach((e) => {
+      expenseMap[e._id] = e.totalExpenses;
+    });
+
+    // Build full 12-month response
+    const months = [];
+    for (let m = 1; m <= 12; m++) {
+      const data = monthlyData.find((d) => d._id === m);
+      const revenue = data ? data.totalRevenue : 0;
+      const cost = data ? data.totalCost : 0;
+      const profit = revenue - cost;
+      const expenses = expenseMap[m] || 0;
+
+      months.push({
+        month: m,
+        revenue,
+        profit,
+        expenses,
+        netProfit: profit - expenses,
+        orderCount: data ? data.orderCount : 0,
+      });
+    }
+
+    res.status(200).json({
+      status: 'success',
+      data: { year: targetYear, months },
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};
+
+// GET /finance/admin/analytics/vendor-comparison
+exports.getVendorComparison = async (req, res) => {
+  try {
+    const { startDate, endDate } = req.query;
+    const { vendorMap } = await calculateFinancials(startDate, endDate);
+
+    const allProviders = await getExternalProviders();
+
+    const comparison = [];
+    for (const provider of allProviders) {
+      const pid = provider._id.toString();
+      const stats = vendorMap[pid] || {
+        totalDeliveredSales: 0,
+        totalRevenueOwed: 0,
+        totalPurchaseCost: 0,
+      };
+      const platformCommission =
+        stats.totalDeliveredSales - stats.totalRevenueOwed;
+      const vendorProfit = stats.totalRevenueOwed - stats.totalPurchaseCost;
+
+      comparison.push({
+        provider: {
+          _id: provider._id,
+          name: provider.name,
+          storeName: provider.storeName,
+        },
+        totalSales: stats.totalDeliveredSales,
+        vendorProfit,
+        platformCommission,
+      });
+    }
+
+    // Sort by total sales descending
+    comparison.sort((a, b) => b.totalSales - a.totalSales);
+
+    res.status(200).json({
+      status: 'success',
+      data: { comparison },
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};
+
+// GET /finance/admin/analytics/revenue-vs-expenses
+exports.getRevenueVsExpenses = async (req, res) => {
+  try {
+    const { year } = req.query;
+    const targetYear = parseInt(year, 10) || new Date().getFullYear();
+
+    const startOfYear = new Date(targetYear, 0, 1);
+    const endOfYear = new Date(targetYear, 11, 31, 23, 59, 59);
+
+    // Monthly revenue from completed orders
+    const monthlyRevenue = await Order.aggregate([
+      {
+        $match: {
+          orderStatus: 'completed',
+          createdAt: { $gte: startOfYear, $lte: endOfYear },
+        },
+      },
+      {
+        $group: {
+          _id: { $month: '$createdAt' },
+          revenue: { $sum: '$totalPrice' },
+        },
+      },
+      { $sort: { _id: 1 } },
+    ]);
+
+    // Monthly expenses
+    const monthlyExpenses = await Expense.aggregate([
+      {
+        $match: {
+          date: { $gte: startOfYear, $lte: endOfYear },
+        },
+      },
+      {
+        $group: {
+          _id: { $month: '$date' },
+          expenses: { $sum: '$amount' },
+        },
+      },
+      { $sort: { _id: 1 } },
+    ]);
+
+    // Monthly vendor payouts
+    const monthlyPayouts = await Transaction.aggregate([
+      {
+        $match: {
+          type: 'payout',
+          date: { $gte: startOfYear, $lte: endOfYear },
+        },
+      },
+      {
+        $group: {
+          _id: { $month: '$date' },
+          payouts: { $sum: '$amount' },
+        },
+      },
+      { $sort: { _id: 1 } },
+    ]);
+
+    const revenueMap = {};
+    monthlyRevenue.forEach((r) => {
+      revenueMap[r._id] = r.revenue;
+    });
+    const expenseMap = {};
+    monthlyExpenses.forEach((e) => {
+      expenseMap[e._id] = e.expenses;
+    });
+    const payoutMap = {};
+    monthlyPayouts.forEach((p) => {
+      payoutMap[p._id] = p.payouts;
+    });
+
+    const months = [];
+    for (let m = 1; m <= 12; m++) {
+      months.push({
+        month: m,
+        revenue: revenueMap[m] || 0,
+        expenses: expenseMap[m] || 0,
+        vendorPayouts: payoutMap[m] || 0,
+        totalOutflow: (expenseMap[m] || 0) + (payoutMap[m] || 0),
+      });
+    }
+
+    res.status(200).json({
+      status: 'success',
+      data: { year: targetYear, months },
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};
+
+// GET /finance/admin/summary
+// Daily / Weekly / Monthly summary
+exports.getFinancialSummary = async (req, res) => {
+  try {
+    const { period } = req.query; // 'daily', 'weekly', 'monthly'
+    const now = new Date();
+    let startDate;
+
+    switch (period) {
+      case 'daily':
+        startDate = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+        break;
+      case 'weekly':
+        startDate = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000);
+        break;
+      case 'monthly':
+        startDate = new Date(now.getFullYear(), now.getMonth(), 1);
+        break;
+      default:
+        startDate = new Date(now.getFullYear(), now.getMonth(), 1); // default monthly
+    }
+
+    const { totalWebsiteProfit, totalRevenue, vendorMap } =
+      await calculateFinancials(startDate, now);
+
+    // Expenses in period
+    const expenses = await Expense.aggregate([
+      { $match: { date: { $gte: startDate, $lte: now } } },
+      { $group: { _id: null, total: { $sum: '$amount' } } },
+    ]);
+    const totalExpenses = (expenses[0] && expenses[0].total) || 0;
+
+    // Payouts in period
+    const payouts = await Transaction.aggregate([
+      { $match: { type: 'payout', date: { $gte: startDate, $lte: now } } },
+      { $group: { _id: null, total: { $sum: '$amount' } } },
+    ]);
+    const totalPayouts = (payouts[0] && payouts[0].total) || 0;
+
+    // Order count
+    const orderCount = await Order.countDocuments({
+      orderStatus: 'completed',
+      createdAt: { $gte: startDate, $lte: now },
+    });
+
+    res.status(200).json({
+      status: 'success',
+      data: {
+        period: period || 'monthly',
+        startDate,
+        endDate: now,
+        totalRevenue,
+        totalProfit: totalWebsiteProfit,
+        totalExpenses,
+        totalPayouts,
+        netProfit: totalWebsiteProfit - totalExpenses,
+        orderCount,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};
+
+// GET /finance/admin/export
+// Export financial report as Excel
+exports.exportFinancialReport = async (req, res) => {
+  try {
+    const XLSX = require('xlsx');
+    const { startDate, endDate } = req.query;
+
+    const {
+      totalWebsiteProfit,
+      websiteOwnedProfit,
+      vendorOwnedProfit,
+      totalRevenue,
+      vendorMap,
+    } = await calculateFinancials(startDate, endDate);
+
+    const allProviders = await getExternalProviders();
+
+    // Build vendor summary data
+    const payoutQuery = { type: 'payout' };
+    if (startDate || endDate) {
+      payoutQuery.date = {};
+      if (startDate) payoutQuery.date.$gte = new Date(startDate);
+      if (endDate) payoutQuery.date.$lte = new Date(endDate);
+    }
+    const payouts = await Transaction.find(payoutQuery);
+    const payoutMap = {};
+    payouts.forEach((t) => {
+      const pid = t.provider.toString();
+      payoutMap[pid] = (payoutMap[pid] || 0) + t.amount;
+    });
+
+    // Sheet 1: Overview
+    const overviewData = [
+      ['Financial Report'],
+      ['Period', startDate || 'All Time', endDate || 'Present'],
+      [],
+      ['Total Revenue', totalRevenue],
+      ['Total Platform Profit', totalWebsiteProfit],
+      ['Website-Owned Profit', websiteOwnedProfit],
+      ['Vendor-Owned Profit (Commission)', vendorOwnedProfit],
+    ];
+
+    // Sheet 2: Vendor Details
+    const vendorHeaders = [
+      'Vendor Name',
+      'Store Name',
+      'Total Sales',
+      'Vendor Profit',
+      'Platform Commission',
+      'Total Owed',
+      'Paid Amount',
+      'Remaining Balance',
+    ];
+    const vendorRows = [vendorHeaders];
+
+    for (const provider of allProviders) {
+      const pid = provider._id.toString();
+      const stats = vendorMap[pid] || {
+        totalDeliveredSales: 0,
+        totalRevenueOwed: 0,
+        totalPurchaseCost: 0,
+      };
+      const paidAmount = payoutMap[pid] || 0;
+      const vendorProfit = stats.totalRevenueOwed - stats.totalPurchaseCost;
+      const platformCommission =
+        stats.totalDeliveredSales - stats.totalRevenueOwed;
+
+      vendorRows.push([
+        provider.name,
+        provider.storeName,
+        stats.totalDeliveredSales,
+        vendorProfit,
+        platformCommission,
+        stats.totalRevenueOwed,
+        paidAmount,
+        stats.totalRevenueOwed - paidAmount,
+      ]);
+    }
+
+    // Sheet 3: Expenses
+    const expenseQuery = {};
+    if (startDate || endDate) {
+      expenseQuery.date = {};
+      if (startDate) expenseQuery.date.$gte = new Date(startDate);
+      if (endDate) expenseQuery.date.$lte = new Date(endDate);
+    }
+    const expensesList = await Expense.find(expenseQuery)
+      .sort('-date')
+      .populate('createdBy', 'name');
+    const expenseHeaders = [
+      'Category',
+      'Amount',
+      'Date',
+      'Notes',
+      'Created By',
+    ];
+    const expenseRows = [expenseHeaders];
+    for (const exp of expensesList) {
+      expenseRows.push([
+        exp.category,
+        exp.amount,
+        exp.date ? exp.date.toISOString().split('T')[0] : '',
+        exp.notes,
+        exp.createdBy ? exp.createdBy.name : '',
+      ]);
+    }
+
+    // Build workbook
+    const wb = XLSX.utils.book_new();
+    const ws1 = XLSX.utils.aoa_to_sheet(overviewData);
+    const ws2 = XLSX.utils.aoa_to_sheet(vendorRows);
+    const ws3 = XLSX.utils.aoa_to_sheet(expenseRows);
+
+    XLSX.utils.book_append_sheet(wb, ws1, 'Overview');
+    XLSX.utils.book_append_sheet(wb, ws2, 'Vendors');
+    XLSX.utils.book_append_sheet(wb, ws3, 'Expenses');
+
+    const buffer = XLSX.write(wb, { type: 'buffer', bookType: 'xlsx' });
+
+    res.setHeader(
+      'Content-Type',
+      'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    );
+    res.setHeader(
+      'Content-Disposition',
+      'attachment; filename=financial_report.xlsx',
+    );
+    res.send(buffer);
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};
+
+// ═════════════════════════════════════════════
+//  VENDOR ENDPOINTS
+// ═════════════════════════════════════════════
+
+// ─────────────────────────────────────────────
+// GET /finance/vendor/stats
+// Vendor Profit Overview
+// ─────────────────────────────────────────────
+exports.getVendorMyStats = async (req, res) => {
+  try {
+    if (!req.user.provider) {
+      return res
+        .status(400)
+        .json({ status: 'fail', message: 'User is not linked to a provider' });
+    }
+    const myProviderId = req.user.provider.toString();
+    const { startDate, endDate } = req.query;
+
+    const { vendorMap } = await calculateFinancials(startDate, endDate);
+    const myStats = vendorMap[myProviderId] || {
+      totalDeliveredSales: 0,
+      totalRevenueOwed: 0,
+      totalPurchaseCost: 0,
+    };
+
+    const totalProfit = myStats.totalRevenueOwed - myStats.totalPurchaseCost;
+    const platformCommission =
+      myStats.totalDeliveredSales - myStats.totalRevenueOwed;
+
+    // Get payouts
+    const payoutQuery = { provider: myProviderId, type: 'payout' };
+    if (startDate || endDate) {
+      payoutQuery.date = {};
+      if (startDate) payoutQuery.date.$gte = new Date(startDate);
+      if (endDate) payoutQuery.date.$lte = new Date(endDate);
+    }
+    const payouts = await Transaction.find(payoutQuery).sort('-date');
+    const paidAmount = payouts.reduce((sum, t) => sum + t.amount, 0);
+
+    res.status(200).json({
+      status: 'success',
+      data: {
+        totalSales: myStats.totalDeliveredSales,
+        totalRevenueOwed: myStats.totalRevenueOwed,
+        totalProfit,
+        platformCommission,
+        paidAmount,
+        pendingAmount: myStats.totalRevenueOwed - paidAmount,
+        remainingBalance: myStats.totalRevenueOwed - paidAmount,
+        transactions: payouts,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};
+
+// ─────────────────────────────────────────────
+// GET /finance/vendor/orders
+// Vendor Orders Financial Breakdown
+// ─────────────────────────────────────────────
+exports.getVendorOrderBreakdown = async (req, res) => {
+  try {
+    if (!req.user.provider) {
+      return res
+        .status(400)
+        .json({ status: 'fail', message: 'User is not linked to a provider' });
+    }
+    const myProviderId = req.user.provider.toString();
+    const { startDate, endDate, page = 1, limit = 20 } = req.query;
+
+    // Find completed orders that contain products from this vendor's provider
+    const matchStage = { orderStatus: 'completed' };
+    if (startDate || endDate) {
+      matchStage.createdAt = {};
+      if (startDate) matchStage.createdAt.$gte = new Date(startDate);
+      if (endDate) matchStage.createdAt.$lte = new Date(endDate);
+    }
+
+    const orders = await Order.find(matchStage)
+      .populate({
+        path: 'items.product',
+        populate: { path: 'provider' },
+      })
+      .sort('-createdAt');
+
+    // Filter and compute per-order financials for THIS vendor
+    const orderBreakdown = [];
+
+    for (const order of orders) {
+      let orderVendorSales = 0;
+      let orderVendorCost = 0;
+      let orderVendorProfit = 0;
+      let orderCommission = 0;
+      let hasVendorItems = false;
+
+      const vendorItems = [];
+
+      for (const item of order.items) {
+        if (!item.product || !item.product.provider) continue;
+        if (item.product.provider._id.toString() !== myProviderId) continue;
+
+        hasVendorItems = true;
+        const qty = item.quantity;
+        const sellingPrice = item.unitPrice;
+        const costPrice = item.product.costPrice || 0;
+        const purchasePrice = item.product.purchasePrice || 0;
+
+        const itemSales = sellingPrice * qty;
+        const itemOwed = costPrice * qty;
+        const itemProfit = (costPrice - purchasePrice) * qty;
+        const itemCommission = (sellingPrice - costPrice) * qty;
+
+        orderVendorSales += itemSales;
+        orderVendorCost += itemOwed;
+        orderVendorProfit += itemProfit;
+        orderCommission += itemCommission;
+
+        vendorItems.push({
+          productId: item.product._id,
+          productName: item.product.nameAr || item.product.nameEn,
+          quantity: qty,
+          sellingPrice,
+          costPrice,
+          profitPerUnit: costPrice - purchasePrice,
+          totalProfit: itemProfit,
+          commission: itemCommission,
+        });
+      }
+
+      if (hasVendorItems) {
+        orderBreakdown.push({
+          orderId: order._id,
+          orderDate: order.createdAt,
+          totalSales: orderVendorSales,
+          vendorRevenue: orderVendorCost,
+          vendorProfit: orderVendorProfit,
+          platformCommission: orderCommission,
+          items: vendorItems,
+        });
+      }
+    }
+
+    // Paginate
+    const skip = (parseInt(page, 10) - 1) * parseInt(limit, 10);
+    const paginatedOrders = orderBreakdown.slice(
+      skip,
+      skip + parseInt(limit, 10),
+    );
+
+    res.status(200).json({
+      status: 'success',
+      results: paginatedOrders.length,
+      totalRecords: orderBreakdown.length,
+      data: { orders: paginatedOrders },
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};
+
+// ─────────────────────────────────────────────
+// GET /finance/vendor/payments
+// Vendor Payment History
+// ─────────────────────────────────────────────
+exports.getVendorPaymentHistory = async (req, res) => {
+  try {
+    if (!req.user.provider) {
+      return res
+        .status(400)
+        .json({ status: 'fail', message: 'User is not linked to a provider' });
+    }
+    const myProviderId = req.user.provider.toString();
+    const { startDate, endDate, page = 1, limit = 20 } = req.query;
+
+    const query = { provider: myProviderId, type: 'payout' };
+    if (startDate || endDate) {
+      query.date = {};
+      if (startDate) query.date.$gte = new Date(startDate);
+      if (endDate) query.date.$lte = new Date(endDate);
+    }
+
+    const skip = (parseInt(page, 10) - 1) * parseInt(limit, 10);
+
+    const [payments, total] = await Promise.all([
+      Transaction.find(query)
+        .sort('-date')
+        .skip(skip)
+        .limit(parseInt(limit, 10))
+        .populate('admin', 'name email'),
+      Transaction.countDocuments(query),
+    ]);
+
+    const totalPaid = await Transaction.aggregate([
+      { $match: query },
+      { $group: { _id: null, total: { $sum: '$amount' } } },
+    ]);
+
+    res.status(200).json({
+      status: 'success',
+      results: payments.length,
+      totalRecords: total,
+      data: {
+        payments,
+        totalPaid: (totalPaid[0] && totalPaid[0].total) || 0,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};
+
+// ─────────────────────────────────────────────
+// GET /finance/vendor/analytics
+// Vendor profit analytics (daily/monthly)
+// ─────────────────────────────────────────────
+exports.getVendorAnalytics = async (req, res) => {
+  try {
+    if (!req.user.provider) {
+      return res
+        .status(400)
+        .json({ status: 'fail', message: 'User is not linked to a provider' });
+    }
+    const myProviderId = req.user.provider.toString();
+    const { year, granularity } = req.query; // granularity: 'daily' or 'monthly'
+    const targetYear = parseInt(year, 10) || new Date().getFullYear();
+
+    const startOfYear = new Date(targetYear, 0, 1);
+    const endOfYear = new Date(targetYear, 11, 31, 23, 59, 59);
+
+    // Get completed orders within the year
+    const orders = await Order.find({
+      orderStatus: 'completed',
+      createdAt: { $gte: startOfYear, $lte: endOfYear },
+    }).populate({
+      path: 'items.product',
+      populate: { path: 'provider' },
+    });
+
+    // Group by time period
+    const dataMap = {};
+
+    for (const order of orders) {
+      for (const item of order.items) {
+        if (!item.product || !item.product.provider) continue;
+        if (item.product.provider._id.toString() !== myProviderId) continue;
+
+        const date = new Date(order.createdAt);
+        let key;
+
+        if (granularity === 'daily') {
+          key = date.toISOString().split('T')[0]; // YYYY-MM-DD
+        } else {
+          key = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}`; // YYYY-MM
+        }
+
+        if (!dataMap[key]) {
+          dataMap[key] = { sales: 0, revenue: 0, profit: 0, orders: new Set() };
+        }
+
+        const qty = item.quantity;
+        const sellingPrice = item.unitPrice;
+        const costPrice = item.product.costPrice || 0;
+        const purchasePrice = item.product.purchasePrice || 0;
+
+        dataMap[key].sales += sellingPrice * qty;
+        dataMap[key].revenue += costPrice * qty;
+        dataMap[key].profit += (costPrice - purchasePrice) * qty;
+        dataMap[key].orders.add(order._id.toString());
+      }
+    }
+
+    // Convert to array
+    const analytics = Object.entries(dataMap)
+      .map(([period, data]) => ({
+        period,
+        sales: data.sales,
+        revenue: data.revenue,
+        profit: data.profit,
+        orderCount: data.orders.size,
+      }))
+      .sort((a, b) => a.period.localeCompare(b.period));
+
+    res.status(200).json({
+      status: 'success',
+      data: {
+        year: targetYear,
+        granularity: granularity || 'monthly',
+        analytics,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};
+
+// ═════════════════════════════════════════════
+//  CAPITAL ACCOUNTS (Where is the money?)
+// ═════════════════════════════════════════════
+
+// GET /finance/admin/accounts
+// List all capital accounts with balances
+exports.getCapitalAccounts = async (req, res) => {
+  try {
+    const { includeInactive } = req.query;
+    const query = includeInactive === 'true' ? {} : { isActive: true };
+
+    const accounts = await CapitalAccount.find(query).sort('type name');
+
+    // Totals by type
+    const totals = {
+      cash: 0,
+      bank: 0,
+      e_wallet: 0,
+      other: 0,
+      grand: 0,
+    };
+
+    for (const acc of accounts) {
+      if (!acc.isActive) continue;
+      totals[acc.type] = (totals[acc.type] || 0) + acc.balance;
+      totals.grand += acc.balance;
+    }
+
+    res.status(200).json({
+      status: 'success',
+      results: accounts.length,
+      data: {
+        accounts,
+        totals,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};
+
+// POST /finance/admin/accounts
+// Create a new capital account
+exports.createCapitalAccount = async (req, res) => {
+  try {
+    const { name, type, bankName, accountNumber, balance, notes } = req.body;
+
+    if (!name || !type) {
+      return res
+        .status(400)
+        .json({ status: 'fail', message: 'name and type are required' });
+    }
+
+    const account = await CapitalAccount.create({
+      name,
+      type,
+      bankName: bankName || '',
+      accountNumber: accountNumber || '',
+      balance: balance || 0,
+      notes: notes || '',
+    });
+
+    // If initial balance > 0, log it in capital
+    if (balance && balance > 0) {
+      const capital = await Capital.getCapital();
+      capital.logs.push({
+        type: 'adjustment',
+        amount: balance,
+        balanceAfter: capital.currentCapital,
+        description: `Initial balance for new account "${name}" (${type})`,
+        date: new Date(),
+        createdBy: req.user._id,
+      });
+      await capital.save();
+    }
+
+    res.status(201).json({
+      status: 'success',
+      data: { account },
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};
+
+// PUT /finance/admin/accounts/:id
+// Update a capital account (name, type, bankName, notes, isActive)
+exports.updateCapitalAccount = async (req, res) => {
+  try {
+    const account = await CapitalAccount.findById(req.params.id);
+    if (!account) {
+      return res
+        .status(404)
+        .json({ status: 'fail', message: 'Account not found' });
+    }
+
+    const allowedFields = [
+      'name',
+      'type',
+      'bankName',
+      'accountNumber',
+      'notes',
+      'isActive',
+    ];
+    for (const field of allowedFields) {
+      if (req.body[field] !== undefined) {
+        account[field] = req.body[field];
+      }
+    }
+
+    await account.save();
+
+    res.status(200).json({
+      status: 'success',
+      data: { account },
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};
+
+// DELETE /finance/admin/accounts/:id
+// Soft-delete (deactivate) an account — only if balance is 0
+exports.deleteCapitalAccount = async (req, res) => {
+  try {
+    const account = await CapitalAccount.findById(req.params.id);
+    if (!account) {
+      return res
+        .status(404)
+        .json({ status: 'fail', message: 'Account not found' });
+    }
+
+    if (account.balance !== 0) {
+      return res.status(400).json({
+        status: 'fail',
+        message: `Cannot delete account with non-zero balance (${account.balance}). Transfer the balance first.`,
+      });
+    }
+
+    account.isActive = false;
+    await account.save();
+
+    res.status(200).json({
+      status: 'success',
+      message: 'Account deactivated successfully',
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};
+
+// PUT /finance/admin/accounts/:id/balance
+// Manually set/correct the balance of an account (e.g. after physical count)
+exports.setAccountBalance = async (req, res) => {
+  try {
+    const { balance, note } = req.body;
+
+    if (balance === undefined || balance < 0) {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'balance must be a non-negative number',
+      });
+    }
+
+    const account = await CapitalAccount.findById(req.params.id);
+    if (!account) {
+      return res
+        .status(404)
+        .json({ status: 'fail', message: 'Account not found' });
+    }
+
+    const oldBalance = account.balance;
+    const diff = balance - oldBalance;
+    account.balance = balance;
+    await account.save();
+
+    // Log the adjustment in capital
+    if (diff !== 0) {
+      const capital = await Capital.getCapital();
+      capital.currentCapital += diff;
+      capital.logs.push({
+        type: 'adjustment',
+        amount: diff,
+        balanceAfter: capital.currentCapital,
+        description:
+          `Account "${account.name}" balance corrected: ${oldBalance} → ${balance}. ${note || ''}`.trim(),
+        date: new Date(),
+        createdBy: req.user._id,
+      });
+      await capital.save();
+    }
+
+    res.status(200).json({
+      status: 'success',
+      data: {
+        account,
+        adjustment: diff,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};
+
+// ═════════════════════════════════════════════
+//  CAPITAL TRANSFERS (Move money between accounts)
+// ═════════════════════════════════════════════
+
+// POST /finance/admin/transfers
+// Transfer money from one account to another
+exports.createTransfer = async (req, res) => {
+  try {
+    const { fromAccountId, toAccountId, amount, note } = req.body;
+
+    if (!fromAccountId || !toAccountId) {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'fromAccountId and toAccountId are required',
+      });
+    }
+
+    if (fromAccountId === toAccountId) {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'Cannot transfer to the same account',
+      });
+    }
+
+    if (!amount || amount <= 0) {
+      return res
+        .status(400)
+        .json({ status: 'fail', message: 'Amount must be positive' });
+    }
+
+    const fromAccount = await CapitalAccount.findById(fromAccountId);
+    const toAccount = await CapitalAccount.findById(toAccountId);
+
+    if (!fromAccount) {
+      return res
+        .status(404)
+        .json({ status: 'fail', message: 'Source account not found' });
+    }
+    if (!toAccount) {
+      return res
+        .status(404)
+        .json({ status: 'fail', message: 'Destination account not found' });
+    }
+
+    if (!fromAccount.isActive || !toAccount.isActive) {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'Cannot transfer to/from a deactivated account',
+      });
+    }
+
+    if (fromAccount.balance < amount) {
+      return res.status(400).json({
+        status: 'fail',
+        message: `Insufficient balance in "${fromAccount.name}". Available: ${fromAccount.balance}, Requested: ${amount}`,
+      });
+    }
+
+    // Perform the transfer
+    fromAccount.balance -= amount;
+    toAccount.balance += amount;
+
+    await fromAccount.save();
+    await toAccount.save();
+
+    // Record the transfer
+    const transfer = await CapitalTransfer.create({
+      fromAccount: fromAccountId,
+      toAccount: toAccountId,
+      amount,
+      note: note || '',
+      createdBy: req.user._id,
+    });
+
+    // Log in capital timeline
+    const capital = await Capital.getCapital();
+    capital.logs.push({
+      type: 'adjustment',
+      amount: 0, // net effect on total capital is zero
+      balanceAfter: capital.currentCapital,
+      description:
+        `Transfer: ${amount} from "${fromAccount.name}" → "${toAccount.name}". ${note || ''}`.trim(),
+      date: new Date(),
+      createdBy: req.user._id,
+    });
+    await capital.save();
+
+    res.status(201).json({
+      status: 'success',
+      data: {
+        transfer,
+        fromAccount: {
+          _id: fromAccount._id,
+          name: fromAccount.name,
+          balance: fromAccount.balance,
+        },
+        toAccount: {
+          _id: toAccount._id,
+          name: toAccount.name,
+          balance: toAccount.balance,
+        },
+      },
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};
+
+// GET /finance/admin/transfers
+// Get transfer history
+exports.getTransfers = async (req, res) => {
+  try {
+    const { startDate, endDate, accountId, page = 1, limit = 30 } = req.query;
+    const query = {};
+
+    if (startDate || endDate) {
+      query.date = {};
+      if (startDate) query.date.$gte = new Date(startDate);
+      if (endDate) query.date.$lte = new Date(endDate);
+    }
+
+    // Filter by specific account (either source or destination)
+    if (accountId) {
+      query.$or = [{ fromAccount: accountId }, { toAccount: accountId }];
+    }
+
+    const skip = (parseInt(page, 10) - 1) * parseInt(limit, 10);
+
+    const [transfers, total] = await Promise.all([
+      CapitalTransfer.find(query)
+        .sort('-date')
+        .skip(skip)
+        .limit(parseInt(limit, 10))
+        .populate('fromAccount', 'name type bankName')
+        .populate('toAccount', 'name type bankName')
+        .populate('createdBy', 'name email'),
+      CapitalTransfer.countDocuments(query),
+    ]);
+
+    res.status(200).json({
+      status: 'success',
+      results: transfers.length,
+      totalRecords: total,
+      data: { transfers },
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};

controllers/imageController.js

@@ -0,0 +1,210 @@
+const { deleteImage, getPublicIdFromUrl } = require('../config/cloudinary');
+
+// Upload single image
+exports.uploadImage = async (req, res) => {
+  try {
+    if (!req.file) {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'No file uploaded',
+      });
+    }
+
+    res.status(200).json({
+      status: 'success',
+      data: {
+        url: req.file.path,
+        publicId: req.file.filename,
+      },
+    });
+  } catch (error) {
+    console.error('Upload error details:', error);
+    res.status(500).json({
+      status: 'error',
+      message: error.message,
+    });
+  }
+};
+
+// Upload multiple images
+exports.uploadMultipleImages = async (req, res) => {
+  try {
+    if (!req.files || Object.keys(req.files).length === 0) {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'No files uploaded',
+      });
+    }
+
+    const response = {};
+
+    // Handle imageCover
+    if (req.files.imageCover) {
+      response.imageCover = {
+        url: req.files.imageCover[0].path,
+        publicId: req.files.imageCover[0].filename,
+      };
+    }
+
+    // Handle additional images
+    if (req.files.images) {
+      response.images = req.files.images.map((file) => ({
+        url: file.path,
+        publicId: file.filename,
+      }));
+    }
+
+    res.status(200).json({
+      status: 'success',
+      data: response,
+    });
+  } catch (error) {
+    res.status(500).json({
+      status: 'error',
+      message: error.message,
+    });
+  }
+};
+
+// Delete image
+exports.deleteImage = async (req, res) => {
+  try {
+    const { publicId } = req.body;
+
+    if (!publicId) {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'Public ID is required',
+      });
+    }
+
+    const result = await deleteImage(publicId);
+
+    if (result.result === 'ok') {
+      res.status(200).json({
+        status: 'success',
+        message: 'Image deleted successfully',
+      });
+    } else {
+      res.status(404).json({
+        status: 'fail',
+        message: 'Image not found',
+      });
+    }
+  } catch (error) {
+    res.status(500).json({
+      status: 'error',
+      message: error.message,
+    });
+  }
+};
+
+// Delete image by URL
+exports.deleteImageByUrl = async (req, res) => {
+  try {
+    const { url } = req.body;
+
+    if (!url) {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'Image URL is required',
+      });
+    }
+
+    const publicId = getPublicIdFromUrl(url);
+
+    if (!publicId) {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'Invalid Cloudinary URL',
+      });
+    }
+
+    const result = await deleteImage(publicId);
+
+    if (result.result === 'ok') {
+      res.status(200).json({
+        status: 'success',
+        message: 'Image deleted successfully',
+      });
+    } else {
+      res.status(404).json({
+        status: 'fail',
+        message: 'Image not found',
+      });
+    }
+  } catch (error) {
+    res.status(500).json({
+      status: 'error',
+      message: error.message,
+    });
+  }
+};
+
+// Delete entire product folder
+exports.deleteProductFolder = async (req, res) => {
+  try {
+    const { productId } = req.params;
+
+    if (!productId) {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'Product ID is required',
+      });
+    }
+
+    const {
+      deleteProductFolder: deleteFolderFn,
+    } = require('../config/cloudinary');
+    const result = await deleteFolderFn(productId);
+
+    res.status(200).json({
+      status: 'success',
+      message: 'Product folder deleted successfully',
+      data: result,
+    });
+  } catch (error) {
+    res.status(500).json({
+      status: 'error',
+      message: error.message,
+    });
+  }
+};
+
+// Delete entire hero slide folder
+exports.deleteHeroSlideFolder = async (req, res) => {
+  try {
+    const { slideId } = req.params;
+
+    if (!slideId) {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'Slide ID is required',
+      });
+    }
+
+    const { cloudinary } = require('../config/cloudinary');
+    const folderPath = `samoulla/hero-images/${slideId}`;
+
+    // Delete all resources in the folder (images and videos)
+    await cloudinary.api.delete_resources_by_prefix(`${folderPath}/`, {
+      resource_type: 'image',
+    });
+    await cloudinary.api.delete_resources_by_prefix(`${folderPath}/`, {
+      resource_type: 'video',
+    });
+
+    // Delete the empty folder
+    await cloudinary.api.delete_folder(folderPath);
+
+    res.status(200).json({
+      status: 'success',
+      message: 'Hero slide folder deleted successfully',
+    });
+  } catch (error) {
+    res.status(500).json({
+      status: 'error',
+      message: error.message,
+    });
+  }
+};

controllers/newsletterController.js

@@ -0,0 +1,157 @@
+const Newsletter = require('../models/newsletterModel');
+const {
+  sendNewsletterSubscriptionEmail,
+  sendNewsletterUnsubscribeEmail,
+} = require('../utils/emailService');
+
+/**
+ * Subscribe to newsletter
+ * @route POST /api/v1/newsletter/subscribe
+ * @access Public
+ */
+exports.subscribe = async (req, res) => {
+  try {
+    const { email } = req.body;
+
+    if (!email) {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'البريد الإلكتروني مطلوب',
+      });
+    }
+
+    // Check if email already exists
+    const existingSubscriber = await Newsletter.findOne({ email });
+
+    if (existingSubscriber) {
+      if (existingSubscriber.isActive) {
+        return res.status(400).json({
+          status: 'fail',
+          message: 'هذا البريد الإلكتروني مشترك بالفعل',
+        });
+      } else {
+        // Reactivate subscription
+        existingSubscriber.isActive = true;
+        existingSubscriber.subscribedAt = Date.now();
+        await existingSubscriber.save();
+
+        // Send confirmation email
+        sendNewsletterSubscriptionEmail(email).catch((err) =>
+          console.error(
+            'Failed to send newsletter subscription email:',
+            err.message,
+          ),
+        );
+
+        return res.status(200).json({
+          status: 'success',
+          message: 'تم تفعيل اشتراكك بنجاح',
+        });
+      }
+    }
+
+    // Create new subscriber
+    const subscriber = await Newsletter.create({ email });
+
+    // Send confirmation email (don't wait for it)
+    sendNewsletterSubscriptionEmail(email).catch((err) =>
+      console.error(
+        'Failed to send newsletter subscription email:',
+        err.message,
+      ),
+    );
+
+    res.status(201).json({
+      status: 'success',
+      message: 'تم الاشتراك بنجاح! سنرسل لك أحدث العروض قريباً',
+      data: {
+        subscriber: {
+          email: subscriber.email,
+          subscribedAt: subscriber.subscribedAt,
+        },
+      },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: 'حدث خطأ أثناء الاشتراك',
+      error: err.message,
+    });
+  }
+};
+
+/**
+ * Unsubscribe from newsletter
+ * @route POST /api/v1/newsletter/unsubscribe
+ * @access Public
+ */
+exports.unsubscribe = async (req, res) => {
+  try {
+    const { email } = req.body;
+
+    if (!email) {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'البريد الإلكتروني مطلوب',
+      });
+    }
+
+    const subscriber = await Newsletter.findOne({ email });
+
+    if (!subscriber) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'البريد الإلكتروني غير مشترك',
+      });
+    }
+
+    subscriber.isActive = false;
+    await subscriber.save();
+
+    // Send unsubscribe confirmation email (don't wait for it)
+    sendNewsletterUnsubscribeEmail(email).catch((err) =>
+      console.error(
+        'Failed to send newsletter unsubscribe email:',
+        err.message,
+      ),
+    );
+
+    res.status(200).json({
+      status: 'success',
+      message: 'تم إلغاء الاشتراك بنجاح',
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: 'حدث خطأ أثناء إلغاء الاشتراك',
+      error: err.message,
+    });
+  }
+};
+
+/**
+ * Get all active subscribers (Admin only)
+ * @route GET /api/v1/newsletter/subscribers
+ * @access Private/Admin
+ */
+exports.getSubscribers = async (req, res) => {
+  try {
+    const subscribers = await Newsletter.find({ isActive: true })
+      .select('email subscribedAt')
+      .lean();
+
+    res.status(200).json({
+      status: 'success',
+      results: subscribers.length,
+      data: {
+        subscribers,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: 'حدث خطأ أثناء جلب المشتركين',
+      error: err.message,
+    });
+  }
+};

controllers/notificationController.js

@@ -0,0 +1,825 @@
+const Notification = require('../models/notificationModel');
+const Newsletter = require('../models/newsletterModel');
+const { getIO } = require('../utils/socket');
+
+// Helper to emit and get unread count
+const getAndEmitUnreadCount = async (userId) => {
+  try {
+    const unreadCount = await Notification.countDocuments({
+      user: userId,
+      isRead: false,
+    });
+    getIO().to(userId.toString()).emit('unreadCountUpdate', unreadCount);
+    return unreadCount;
+  } catch (err) {
+    console.error('Error emitting unread count:', err);
+    return 0;
+  }
+};
+
+// Get all notifications for the authenticated user
+exports.getMyNotifications = async (req, res) => {
+  try {
+    if (!req.user) {
+      return res.status(401).json({
+        status: 'fail',
+        message: 'You must be logged in to view notifications',
+      });
+    }
+
+    const page = parseInt(req.query.page, 10) || 1;
+    const limit = parseInt(req.query.limit, 10) || 20;
+    const skip = (page - 1) * limit;
+
+    // Filter options
+    const filter = { user: req.user._id };
+
+    if (req.query.isRead !== undefined) {
+      filter.isRead = req.query.isRead === 'true';
+    }
+
+    if (req.query.type) {
+      filter.type = req.query.type;
+    }
+
+    const notifications = await Notification.find(filter)
+      .sort({ createdAt: -1 })
+      .skip(skip)
+      .limit(limit)
+      .populate('relatedId');
+
+    const total = await Notification.countDocuments(filter);
+    const unreadCount = await Notification.countDocuments({
+      user: req.user._id,
+      isRead: false,
+    });
+
+    res.status(200).json({
+      status: 'success',
+      results: notifications.length,
+      data: {
+        notifications,
+        pagination: {
+          page,
+          limit,
+          total,
+          pages: Math.ceil(total / limit),
+        },
+        unreadCount,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: err.message,
+    });
+  }
+};
+
+// Get unread notification count
+exports.getUnreadCount = async (req, res) => {
+  try {
+    if (!req.user) {
+      return res.status(401).json({
+        status: 'fail',
+        message: 'You must be logged in',
+      });
+    }
+
+    const count = await Notification.countDocuments({
+      user: req.user._id,
+      isRead: false,
+    });
+
+    res.status(200).json({
+      status: 'success',
+      data: { unreadCount: count },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: err.message,
+    });
+  }
+};
+
+// Mark a notification as read
+exports.markAsRead = async (req, res) => {
+  try {
+    if (!req.user) {
+      return res.status(401).json({
+        status: 'fail',
+        message: 'You must be logged in',
+      });
+    }
+
+    const notification = await Notification.findOneAndUpdate(
+      { _id: req.params.id, user: req.user._id },
+      { isRead: true, readAt: new Date() },
+      { new: true },
+    );
+
+    if (!notification) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'Notification not found',
+      });
+    }
+
+    const unreadCount = await getAndEmitUnreadCount(req.user._id);
+
+    // Sync admin dashboard: Notify admins that this notification was read
+    getIO().emit('notificationReadAdmin', {
+      notificationId: notification._id,
+      userId: req.user._id,
+      isRead: true,
+    });
+
+    res.status(200).json({
+      status: 'success',
+      data: { notification, unreadCount },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: err.message,
+    });
+  }
+};
+
+// Mark all notifications as read
+exports.markAllAsRead = async (req, res) => {
+  try {
+    if (!req.user) {
+      return res.status(401).json({
+        status: 'fail',
+        message: 'You must be logged in',
+      });
+    }
+
+    await Notification.updateMany(
+      { user: req.user._id, isRead: false },
+      { isRead: true, readAt: new Date() },
+    );
+
+    await getAndEmitUnreadCount(req.user._id);
+
+    // Sync admin dashboard: Notify admins that ALL user notifications were read
+    getIO().emit('notificationAllReadAdmin', {
+      userId: req.user._id,
+    });
+
+    res.status(200).json({
+      status: 'success',
+      message: 'All notifications marked as read',
+      data: { unreadCount: 0 },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: err.message,
+    });
+  }
+};
+
+// Delete a notification
+exports.deleteNotification = async (req, res) => {
+  try {
+    if (!req.user) {
+      return res.status(401).json({
+        status: 'fail',
+        message: 'You must be logged in',
+      });
+    }
+
+    const notification = await Notification.findOneAndDelete({
+      _id: req.params.id,
+      user: req.user._id,
+    });
+
+    if (!notification) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'Notification not found',
+      });
+    }
+
+    const unreadCount = await getAndEmitUnreadCount(req.user._id);
+
+    // Sync admin dashboard: Notify admins that this notification was deleted
+    getIO().emit('notificationDeletedAdmin', notification._id);
+
+    res.status(200).json({
+      status: 'success',
+      data: { unreadCount },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: err.message,
+    });
+  }
+};
+
+// Delete all read notifications
+exports.deleteAllRead = async (req, res) => {
+  try {
+    if (!req.user) {
+      return res.status(401).json({
+        status: 'fail',
+        message: 'You must be logged in',
+      });
+    }
+
+    await Notification.deleteMany({
+      user: req.user._id,
+      isRead: true,
+    });
+
+    // Sync admin dashboard: Notify admins that ALL user read notifications were deleted
+    getIO().emit('notificationAllDeletedReadAdmin', {
+      userId: req.user._id,
+    });
+
+    res.status(200).json({
+      status: 'success',
+      message: 'All read notifications deleted',
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: err.message,
+    });
+  }
+};
+
+// Admin: Get all notifications
+exports.getAllNotifications = async (req, res) => {
+  try {
+    const page = parseInt(req.query.page, 10) || 1;
+    const limit = parseInt(req.query.limit, 10) || 50;
+    const skip = (page - 1) * limit;
+
+    const notifications = await Notification.find()
+      .populate('user', 'name email')
+      .sort({ createdAt: -1 })
+      .skip(skip)
+      .limit(limit);
+
+    const total = await Notification.countDocuments();
+
+    res.status(200).json({
+      status: 'success',
+      results: notifications.length,
+      data: {
+        notifications,
+        pagination: {
+          page,
+          limit,
+          total,
+          pages: Math.ceil(total / limit),
+        },
+      },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: err.message,
+    });
+  }
+};
+
+// Admin: Create notification for specific user(s)
+exports.createNotification = async (req, res) => {
+  try {
+    const {
+      userId,
+      title,
+      message,
+      type,
+      priority,
+      metadata,
+      relatedId,
+      relatedModel,
+    } = req.body;
+
+    if (!userId || !title || !message) {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'Please provide userId, title, and message',
+      });
+    }
+
+    const {
+      createNotification: createNotifService,
+    } = require('../utils/notificationService');
+    const notification = await createNotifService({
+      userId,
+      title,
+      message,
+      type: type || 'general',
+      priority: priority || 'medium',
+      metadata,
+      relatedId: relatedId || undefined,
+      relatedModel: relatedModel || undefined,
+    });
+
+    if (!notification) {
+      return res.status(200).json({
+        status: 'success',
+        message: 'Notification skipped due to user preferences or error',
+        data: null,
+      });
+    }
+
+    res.status(201).json({
+      status: 'success',
+      data: { notification },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: err.message,
+    });
+  }
+};
+
+// Admin: Broadcast notification to all users
+exports.broadcastNotification = async (req, res) => {
+  try {
+    const {
+      title,
+      message,
+      type,
+      priority,
+      metadata,
+      userRole,
+      relatedId,
+      relatedModel,
+    } = req.body;
+
+    if (!title || !message) {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'Please provide title and message',
+      });
+    }
+
+    const User = require('../models/userModel');
+
+    let users;
+    if (userRole === 'subscriber') {
+      // Find all active newsletter emails
+      const subscribers = await Newsletter.find({ isActive: true }).select(
+        'email',
+      );
+      const emails = subscribers.map((s) => s.email);
+
+      // Find users whose email is in the subscribers list
+      users = await User.find({ email: { $in: emails } }).select('_id');
+    } else {
+      // Filter users by role if specified
+      const filter = userRole && userRole !== 'all' ? { role: userRole } : {};
+      users = await User.find(filter).select('_id');
+    }
+
+    const recipients = users.map((u) => u._id);
+    const { createBulkNotifications } = require('../utils/notificationService');
+
+    const results = await createBulkNotifications(recipients, {
+      title,
+      message,
+      type: type || 'general',
+      priority: priority || 'medium',
+      metadata,
+      relatedId: relatedId || undefined,
+      relatedModel: relatedModel || undefined,
+    });
+
+    res.status(201).json({
+      status: 'success',
+      message: `Notification sent to ${results.length} recipients who opted in`,
+      data: { count: results.length },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: err.message,
+    });
+  }
+};
+
+// Admin: Delete any notification (no user ownership check)
+exports.adminDeleteNotification = async (req, res) => {
+  try {
+    const notification = await Notification.findByIdAndDelete(req.params.id);
+
+    if (!notification) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'Notification not found',
+      });
+    }
+
+    const io = getIO();
+    // Notify the specific user that their notification was deleted
+    io.to(notification.user.toString()).emit(
+      'notificationDeleted',
+      notification._id,
+    );
+
+    // Update the user's unread count after deletion
+    await getAndEmitUnreadCount(notification.user);
+
+    // Sync other admins
+    io.emit('notificationDeletedAdmin', notification._id);
+
+    res.status(200).json({
+      status: 'success',
+      message: 'Notification deleted successfully',
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: err.message,
+    });
+  }
+};
+
+// Get user's notification preferences
+exports.getMyPreferences = async (req, res) => {
+  try {
+    if (!req.user) {
+      return res.status(401).json({
+        status: 'fail',
+        message: 'You must be logged in',
+      });
+    }
+
+    res.status(200).json({
+      status: 'success',
+      data: {
+        preferences: req.user.notificationPreferences,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: err.message,
+    });
+  }
+};
+
+// Update user's notification preferences
+exports.updateMyPreferences = async (req, res) => {
+  try {
+    if (!req.user) {
+      return res.status(401).json({
+        status: 'fail',
+        message: 'You must be logged in',
+      });
+    }
+
+    const { preferences } = req.body;
+
+    if (!preferences) {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'Please provide preferences to update',
+      });
+    }
+
+    // Update user document
+    const User = require('../models/userModel');
+    const existingUser = await User.findById(req.user._id);
+
+    // Guard: Force-enable notifications only for categories the user has permission for.
+    // Admins always receive everything. Employees only receive what matches their permissions.
+    if (req.user.role === 'admin') {
+      if (preferences.orderUpdates) {
+        preferences.orderUpdates.app = true;
+        preferences.orderUpdates.email = true;
+      }
+      if (preferences.productUpdates) {
+        preferences.productUpdates.app = true;
+        preferences.productUpdates.email = true;
+      }
+      delete preferences.vendorOrderVisibility;
+    } else if (req.user.role === 'employee') {
+      const empPerms = req.user.permissions || [];
+      // Only force-enable orderUpdates if the employee has manage_orders permission
+      if (preferences.orderUpdates && empPerms.includes('manage_orders')) {
+        preferences.orderUpdates.app = true;
+        preferences.orderUpdates.email = true;
+      }
+      // Only force-enable productUpdates if the employee has manage_products permission
+      if (preferences.productUpdates && empPerms.includes('manage_products')) {
+        preferences.productUpdates.app = true;
+        preferences.productUpdates.email = true;
+      }
+      delete preferences.vendorOrderVisibility;
+    }
+
+    // Logic to handle disabledAt and blackoutPeriods for vendorOrderVisibility
+    if (preferences.vendorOrderVisibility) {
+      const oldPref =
+        (existingUser.notificationPreferences &&
+          existingUser.notificationPreferences.vendorOrderVisibility) ||
+        {};
+      const wasEnabled = oldPref.app !== false;
+      const isEnabled = preferences.vendorOrderVisibility.app !== false;
+
+      const periods = oldPref.blackoutPeriods || [];
+
+      if (wasEnabled && !isEnabled) {
+        // Just turned off: set disabledAt (start of new blackout)
+        preferences.vendorOrderVisibility.disabledAt = new Date();
+        preferences.vendorOrderVisibility.blackoutPeriods = periods;
+      } else if (!wasEnabled && isEnabled) {
+        // Just turned on: close the current blackout period and clear disabledAt
+        if (oldPref.disabledAt) {
+          periods.push({
+            start: oldPref.disabledAt,
+            end: new Date(),
+          });
+        }
+        preferences.vendorOrderVisibility.blackoutPeriods = periods;
+        preferences.vendorOrderVisibility.disabledAt = null;
+      } else if (!wasEnabled && !isEnabled) {
+        // Stayed off: carry over state
+        preferences.vendorOrderVisibility.disabledAt = oldPref.disabledAt;
+        preferences.vendorOrderVisibility.blackoutPeriods = periods;
+      } else {
+        // Stayed on: carry over state
+        preferences.vendorOrderVisibility.disabledAt = null;
+        preferences.vendorOrderVisibility.blackoutPeriods = periods;
+      }
+    }
+
+    const user = await User.findByIdAndUpdate(
+      req.user._id,
+      { notificationPreferences: preferences },
+      { new: true, runValidators: true },
+    );
+
+    res.status(200).json({
+      status: 'success',
+      data: {
+        preferences: user.notificationPreferences,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: err.message,
+    });
+  }
+};
+
+// Admin: Get current vendor preference state (reads first active vendor as representative)
+exports.getVendorGlobalPreferences = async (req, res) => {
+  try {
+    const User = require('../models/userModel');
+    const vendor = await User.findOne({ role: 'vendor', isActive: true })
+      .select('notificationPreferences')
+      .lean();
+
+    const defaults = {
+      orderUpdates: { app: true, email: true },
+      productUpdates: { app: true, email: true },
+      vendorOrderVisibility: { app: true, email: true },
+    };
+
+    if (!vendor || !vendor.notificationPreferences) {
+      return res
+        .status(200)
+        .json({ status: 'success', data: { preferences: defaults } });
+    }
+
+    const p = vendor.notificationPreferences;
+    return res.status(200).json({
+      status: 'success',
+      data: {
+        preferences: {
+          orderUpdates: {
+            app: p.orderUpdates?.app !== false,
+            email: p.orderUpdates?.email !== false,
+          },
+          productUpdates: {
+            app: p.productUpdates?.app !== false,
+            email: p.productUpdates?.email !== false,
+          },
+          vendorOrderVisibility: {
+            app: p.vendorOrderVisibility?.app !== false,
+            email: p.vendorOrderVisibility?.email !== false,
+          },
+        },
+      },
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};
+
+// Admin: Bulk-update preferences for ALL active vendor users
+// This lets admins globally control whether vendors receive notifications / see orders
+exports.updateAllVendorPreferences = async (req, res) => {
+  try {
+    if (!req.user) {
+      return res
+        .status(401)
+        .json({ status: 'fail', message: 'You must be logged in' });
+    }
+
+    const { preferences } = req.body;
+    if (!preferences) {
+      return res
+        .status(400)
+        .json({ status: 'fail', message: 'Please provide preferences' });
+    }
+
+    const User = require('../models/userModel');
+    const now = new Date();
+
+    // Find all active vendor users
+    const vendors = await User.find({ role: 'vendor', isActive: true }).select(
+      '_id notificationPreferences',
+    );
+
+    if (vendors.length === 0) {
+      return res.status(200).json({
+        status: 'success',
+        message: 'No active vendors found',
+        data: { updatedCount: 0 },
+      });
+    }
+
+    const bulkOps = vendors.map((vendor) => {
+      const existingPrefs = vendor.notificationPreferences || {};
+      const updatedPrefs = { ...existingPrefs };
+
+      // Apply orderUpdates preference — app and email are always kept in sync
+      if (preferences.orderUpdates !== undefined) {
+        const val =
+          typeof preferences.orderUpdates.app === 'boolean'
+            ? preferences.orderUpdates.app
+            : true;
+        updatedPrefs.orderUpdates = {
+          ...(existingPrefs.orderUpdates || {}),
+          app: val,
+          email: val,
+        };
+      }
+
+      // Apply productUpdates preference — app and email are always kept in sync
+      if (preferences.productUpdates !== undefined) {
+        const val =
+          typeof preferences.productUpdates.app === 'boolean'
+            ? preferences.productUpdates.app
+            : true;
+        updatedPrefs.productUpdates = {
+          ...(existingPrefs.productUpdates || {}),
+          app: val,
+          email: val,
+        };
+      }
+
+      // Apply vendorOrderVisibility preference with blackout tracking
+      if (preferences.vendorOrderVisibility !== undefined) {
+        const oldVis = existingPrefs.vendorOrderVisibility || {};
+        const wasEnabled = oldVis.app !== false;
+        const isEnabled = preferences.vendorOrderVisibility.app !== false;
+        const periods = oldVis.blackoutPeriods || [];
+
+        let disabledAt = oldVis.disabledAt || null;
+
+        if (wasEnabled && !isEnabled) {
+          // Turning OFF: record when it was disabled
+          disabledAt = now;
+        } else if (!wasEnabled && isEnabled) {
+          // Turning ON: close the current blackout period
+          if (oldVis.disabledAt) {
+            periods.push({ start: oldVis.disabledAt, end: now });
+          }
+          disabledAt = null;
+        } else if (!wasEnabled && !isEnabled) {
+          // Stayed off: keep previous disabledAt
+        } else {
+          // Stayed on
+          disabledAt = null;
+        }
+
+        // vendorOrderVisibility: app and email always in sync
+        updatedPrefs.vendorOrderVisibility = {
+          app: isEnabled,
+          email: isEnabled,
+          disabledAt,
+          blackoutPeriods: periods,
+        };
+      }
+
+      return {
+        updateOne: {
+          filter: { _id: vendor._id },
+          update: { $set: { notificationPreferences: updatedPrefs } },
+        },
+      };
+    });
+
+    const result = await User.bulkWrite(bulkOps);
+
+    // Emit a socket event so online vendors refresh their preferences
+    const { getIO } = require('../utils/socket');
+    try {
+      const io = getIO();
+      vendors.forEach((vendor) => {
+        io.to(vendor._id.toString()).emit('preferencesUpdated', {
+          preferences: bulkOps.find(
+            (op) =>
+              op.updateOne.filter._id.toString() === vendor._id.toString(),
+          )?.updateOne?.update?.$set?.notificationPreferences,
+        });
+      });
+    } catch (socketErr) {
+      // Non-critical — socket might not be available
+      console.error(
+        'Socket emit error in updateAllVendorPreferences:',
+        socketErr,
+      );
+    }
+
+    res.status(200).json({
+      status: 'success',
+      message: `Updated preferences for ${result.modifiedCount} vendor(s)`,
+      data: { updatedCount: result.modifiedCount },
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};
+
+// ─── Stock Subscription Handlers ─────────────────────────────────────────────
+
+const StockSubscription = require('../models/stockSubscriptionModel');
+
+// POST /notifications/stock-subscribe/:productId
+exports.subscribeToStock = async (req, res) => {
+  try {
+    const { productId } = req.params;
+    const userId = req.user._id;
+
+    // Upsert: create if not exists, reset notifiedAt so they get notified again on next restock
+    await StockSubscription.findOneAndUpdate(
+      { user: userId, product: productId },
+      { user: userId, product: productId, notifiedAt: null },
+      { upsert: true, new: true, setDefaultsOnInsert: true },
+    );
+
+    res.status(200).json({
+      status: 'success',
+      data: { subscribed: true },
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};
+
+// DELETE /notifications/stock-subscribe/:productId
+exports.unsubscribeFromStock = async (req, res) => {
+  try {
+    const { productId } = req.params;
+    const userId = req.user._id;
+
+    await StockSubscription.findOneAndDelete({
+      user: userId,
+      product: productId,
+    });
+
+    res.status(200).json({
+      status: 'success',
+      data: { subscribed: false },
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};
+
+// GET /notifications/stock-subscribe/:productId
+exports.checkStockSubscription = async (req, res) => {
+  try {
+    const { productId } = req.params;
+    const userId = req.user._id;
+
+    const sub = await StockSubscription.findOne({
+      user: userId,
+      product: productId,
+    });
+
+    res.status(200).json({
+      status: 'success',
+      data: { subscribed: !!sub },
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};

controllers/orderController.js

@@ -0,0 +1,1317 @@
+const Order = require('../models/orderModel');
+const Product = require('../models/productModel');
+const ShippingPrice = require('../models/shippingPriceModel');
+const Capital = require('../models/capitalModel');
+const Promo = require('../models/promoCodeModel');
+const User = require('../models/userModel');
+const {
+  sendOrderConfirmationEmail,
+  sendOrderStatusUpdateEmail,
+  sendAdminNewOrderEmail,
+} = require('../utils/emailService');
+const { PERMISSIONS } = require('../utils/permissions');
+const {
+  notifyOrderCreated,
+  notifyOrderProcessing,
+  notifyOrderShipped,
+  notifyOrderCompleted,
+  notifyOrderCancelled,
+  notifyVendorNewOrder,
+  notifyProductOutOfStock,
+  notifyAdminsNewOrder,
+  notifyAdminsProductOutOfStock,
+  emitOrderUpdate,
+} = require('../utils/notificationService');
+
+const { restoreOrderStock, deductOrderStock } = require('../utils/orderUtils');
+const { syncOrderWithSheet } = require('../utils/googleSheetsService');
+
+exports.getAllOrders = async (req, res) => {
+  try {
+    const orders = await Order.find()
+      .populate('user', 'name email address mobile')
+      .populate({
+        path: 'items.product',
+        select: 'nameAr nameEn imageCover price provider',
+        populate: {
+          path: 'provider',
+          select: 'storeName name',
+        },
+      })
+      .sort({ createdAt: -1 })
+      .lean();
+    res.status(200).json({
+      status: 'success',
+      results: orders.length,
+      data: { orders },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: err.message,
+    });
+  }
+};
+
+// Get orders for the authenticated user only
+exports.getMyOrders = async (req, res) => {
+  try {
+    if (!req.user) {
+      return res.status(401).json({
+        status: 'fail',
+        message: 'You must be logged in to view your orders',
+      });
+    }
+
+    const orders = await Order.find({ user: req.user._id })
+      .populate('items.product', 'nameAr nameEn imageCover price')
+      .sort({ createdAt: -1 })
+      .lean();
+
+    res.status(200).json({
+      status: 'success',
+      results: orders.length,
+      data: { orders },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: err.message,
+    });
+  }
+};
+
+exports.getOrder = async (req, res) => {
+  try {
+    const order = await Order.findById(req.params.id)
+      .populate({
+        path: 'items.product',
+        populate: {
+          path: 'provider',
+          model: 'Provider',
+        },
+      })
+      .populate('user', 'name email mobile address')
+      .lean();
+
+    if (!order) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'No order found',
+      });
+    }
+
+    // Authorization check
+    let isAuthorized = false;
+
+    if (req.user) {
+      // 1) Admins and employees with manage_orders permission can see any order
+      const isAdmin = req.user.role === 'admin';
+      const isEmployee =
+        req.user.role === 'employee' &&
+        req.user.permissions.includes(PERMISSIONS.MANAGE_ORDERS);
+
+      // 2) Users can see their own orders
+      const orderUserId = (order.user && order.user._id) || order.user;
+      const isOwner =
+        orderUserId && String(orderUserId) === String(req.user._id);
+
+      // 3) Vendors can see the order if it contains one of their products
+      let isVendorOfThisOrder = false;
+      if (req.user.role === 'vendor' && req.user.provider) {
+        const vendorProviderId = String(
+          req.user.provider._id || req.user.provider,
+        );
+        isVendorOfThisOrder =
+          order.items &&
+          order.items.some((item) => {
+            if (!item.product) return false;
+            const itemProviderId = String(
+              (item.product &&
+                item.product.provider &&
+                item.product.provider._id) ||
+              (item.product && item.product.provider) ||
+              '',
+            );
+            return itemProviderId === vendorProviderId;
+          });
+      }
+
+      if (isAdmin || isEmployee || isOwner || isVendorOfThisOrder) {
+        isAuthorized = true;
+      }
+    } else {
+      // Guest Access:
+      // If the order has NO user attached, we assume it's a guest order and allow access (since they have the ID)
+      if (!order.user) {
+        isAuthorized = true;
+      }
+    }
+
+    if (!isAuthorized) {
+      return res.status(403).json({
+        status: 'fail',
+        message: 'You are not authorized to view this order',
+      });
+    }
+
+    res.status(200).json({
+      status: 'success',
+      data: { order },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: err.message,
+    });
+  }
+};
+
+exports.updateOrder = async (req, res) => {
+  try {
+    // Get the old order to check if status changed
+    const oldOrder = await Order.findById(req.params.id);
+
+    if (!oldOrder) {
+      return res
+        .status(404)
+        .json({ status: 'fail', message: 'No order found' });
+    }
+
+    // Prevent moving order away from 'cancelled' if any items are cancelled
+    if (req.body.orderStatus && req.body.orderStatus !== 'cancelled') {
+      const hasCancelledItems = oldOrder.items.some(
+        (item) => item.fulfillmentStatus === 'cancelled',
+      );
+      if (hasCancelledItems) {
+        // If it's an admin, we allow it BUT we must reset the items and handle stock
+        if (req.user && req.user.role === 'admin') {
+          // Reset all cancelled items to pending
+          const updatedItems = oldOrder.items.map((item) => {
+            if (item.fulfillmentStatus === 'cancelled') {
+              return { ...item.toObject(), fulfillmentStatus: 'pending' };
+            }
+            return item.toObject();
+          });
+          req.body.items = updatedItems;
+
+          // If moving from 'cancelled' order status, deduct stock again
+          if (oldOrder.orderStatus === 'cancelled') {
+            await deductOrderStock(oldOrder.items);
+          }
+        } else {
+          return res.status(400).json({
+            status: 'fail',
+            message:
+              'نعتذر، لا يمكن تغيير حالة الطلب بينما توجد منتجات ملغاة. يجب معالجة المنتجات الملغاة أولاً.',
+          });
+        }
+      }
+    }
+
+    // Handle moving TO cancelled status - propagate to all items
+    if (
+      req.body.orderStatus === 'cancelled' &&
+      oldOrder.orderStatus !== 'cancelled'
+    ) {
+      const updatedItems = oldOrder.items.map((item) => ({
+        ...item.toObject(),
+        fulfillmentStatus: 'cancelled',
+      }));
+      req.body.items = updatedItems;
+    }
+
+    // Check if status is being changed to shipped or completed and all items are ready
+    if (
+      req.body.orderStatus &&
+      ['shipped', 'completed'].includes(req.body.orderStatus)
+    ) {
+      const allReady = oldOrder.items.every(
+        (item) => item.fulfillmentStatus === 'ready',
+      );
+      if (!allReady) {
+        return res.status(400).json({
+          status: 'fail',
+          message:
+            'Cannot change order status to shipped/completed until all items are marked as ready.',
+        });
+      }
+    }
+
+    const updatedOrder = await Order.findByIdAndUpdate(
+      req.params.id,
+      req.body,
+      { new: true, runValidators: true },
+    )
+      .populate({
+        path: 'items.product',
+        populate: {
+          path: 'provider',
+          model: 'Provider',
+        },
+      })
+      .populate('user', 'name email');
+
+    // Check if order status changed and send email + notification
+    if (
+      req.body.orderStatus &&
+      req.body.orderStatus !== oldOrder.orderStatus &&
+      updatedOrder.user
+    ) {
+      // If status changed to cancelled, restore stock
+      if (req.body.orderStatus === 'cancelled') {
+        await restoreOrderStock(updatedOrder.items);
+
+        // ── Capital: Reverse profit if order was previously completed ──
+        if (oldOrder.orderStatus === 'completed') {
+          try {
+            const populatedForReversal = await Order.findById(
+              updatedOrder._id,
+            ).populate({
+              path: 'items.product',
+              select: 'costPrice',
+            });
+
+            let reversedProfit = 0;
+            for (const item of populatedForReversal.items) {
+              if (!item.product) continue;
+              const costPrice = item.product.costPrice || 0;
+              const sellingPrice = item.unitPrice;
+              reversedProfit += (sellingPrice - costPrice) * item.quantity;
+            }
+
+            if (reversedProfit > 0) {
+              const capital = await Capital.getCapital();
+              capital.currentCapital -= reversedProfit;
+              capital.logs.push({
+                type: 'adjustment',
+                amount: -reversedProfit,
+                balanceAfter: capital.currentCapital,
+                reference: updatedOrder._id,
+                referenceModel: 'Order',
+                description: `Reversed profit — completed order #${updatedOrder._id.toString().slice(-8).toUpperCase()} was cancelled`,
+                date: new Date(),
+                createdBy: req.user._id,
+              });
+              await capital.save();
+            }
+          } catch (capitalErr) {
+            console.error(
+              'Failed to reverse capital on order cancellation:',
+              capitalErr.message,
+            );
+          }
+        }
+      }
+
+      // Prepare order data for email
+      const emailOrderData = {
+        orderNumber: updatedOrder._id.toString().slice(-8).toUpperCase(),
+        total: updatedOrder.totalPrice,
+      };
+
+      // Send status update email (don't wait for it)
+      sendOrderStatusUpdateEmail(
+        emailOrderData,
+        updatedOrder.user,
+        req.body.orderStatus,
+      ).catch(() => { });
+
+      // Send notification based on status
+      const userId = updatedOrder.user._id || updatedOrder.user;
+      try {
+        switch (req.body.orderStatus) {
+          case 'created':
+            await notifyOrderCreated(updatedOrder, userId);
+            break;
+          case 'processing':
+            await notifyOrderProcessing(updatedOrder, userId);
+            break;
+          case 'shipped':
+            await notifyOrderShipped(updatedOrder, userId);
+            break;
+          case 'completed':
+            await notifyOrderCompleted(updatedOrder, userId);
+            break;
+          case 'cancelled':
+            await notifyOrderCancelled(updatedOrder, userId);
+            break;
+          default:
+            break;
+        }
+      } catch (notifErr) {
+        // Silent fail
+      }
+
+      // ── Capital: Add profit when order is marked completed ──
+      if (req.body.orderStatus === 'completed') {
+        try {
+          const populatedForProfit = await Order.findById(
+            updatedOrder._id,
+          ).populate({
+            path: 'items.product',
+            select: 'costPrice purchasePrice',
+          });
+
+          let orderProfit = 0;
+          for (const item of populatedForProfit.items) {
+            if (!item.product) continue;
+            const costPrice = item.product.costPrice || 0;
+            const sellingPrice = item.unitPrice;
+            orderProfit += (sellingPrice - costPrice) * item.quantity;
+          }
+
+          if (orderProfit > 0) {
+            const capital = await Capital.getCapital();
+            capital.currentCapital += orderProfit;
+            capital.logs.push({
+              type: 'profit',
+              amount: orderProfit,
+              balanceAfter: capital.currentCapital,
+              reference: updatedOrder._id,
+              referenceModel: 'Order',
+              description: `Profit from completed order #${updatedOrder._id.toString().slice(-8).toUpperCase()}`,
+              date: new Date(),
+              createdBy: req.user._id,
+            });
+            await capital.save();
+          }
+        } catch (capitalErr) {
+          // Silent fail — don't block order update
+          console.error(
+            'Failed to update capital on order completion:',
+            capitalErr.message,
+          );
+        }
+      }
+
+      // Explicitly broadcast order update for the dashboard (ONLY ONCE)
+      emitOrderUpdate(updatedOrder, req.body.orderStatus);
+    }
+
+    res.status(200).json({ status: 'success', data: { order: updatedOrder } });
+
+    // Sync to Google Sheet (live update)
+    syncOrderWithSheet(updatedOrder).catch(() => {});
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};
+
+exports.cancelOrder = async (req, res) => {
+  try {
+    const { id } = req.params;
+    const order = await Order.findById(id);
+    if (!order)
+      return res
+        .status(404)
+        .json({ status: 'fail', message: 'Order not found' });
+
+    if (!req.user)
+      return res.status(401).json({
+        status: 'fail',
+        message: 'You must be logged in to cancel an order',
+      });
+
+    const orderUserId = (order.user && order.user._id) || order.user;
+    const isOwner = orderUserId && String(orderUserId) === String(req.user._id);
+    const isAdmin = req.user.role === 'admin';
+    if (!isOwner && !isAdmin)
+      return res.status(403).json({
+        status: 'fail',
+        message: 'Not authorized to cancel this order',
+      });
+
+    if (order.orderStatus === 'cancelled') {
+      return res
+        .status(400)
+        .json({ status: 'fail', message: 'Order is already cancelled' });
+    }
+
+    await restoreOrderStock(order.items);
+
+    if (order.promo) {
+      try {
+        await Promo.findByIdAndUpdate(order.promo, { $inc: { usedCount: -1 } });
+      } catch (promoErr) {
+        console.error('Failed to restore promo usage:', promoErr);
+      }
+    }
+
+    order.orderStatus = 'cancelled';
+    order.canceledAt = new Date();
+
+    if (order.payment && order.payment.status !== 'failed') {
+      order.payment.status = 'failed';
+    }
+
+    await order.save();
+
+    // Send cancellation notification
+    try {
+      const userId = order.user;
+      await notifyOrderCancelled(order, userId, 'Order cancelled as requested');
+    } catch (notifErr) {
+      // Silent fail
+    }
+
+    // Explicitly broadcast order update for the dashboard (ONLY ONCE)
+    emitOrderUpdate(order, 'order_cancelled');
+
+    // Populate product details before returning
+    await order.populate('items.product', 'nameAr nameEn imageCover price');
+
+    res.status(200).json({ status: 'success', data: { order } });
+
+    // Sync to Google Sheet (live update)
+    syncOrderWithSheet(order).catch(() => {});
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};
+
+exports.deleteOrder = async (req, res) => {
+  try {
+    const order = await Order.findByIdAndDelete(req.params.id);
+    if (!order) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'No order found',
+      });
+    }
+
+    // Explicitly broadcast order update for the dashboard
+    emitOrderUpdate({ _id: req.params.id }, 'order_deleted');
+
+    res.status(204).json({
+      status: 'success',
+      data: null,
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: err.message,
+    });
+  }
+};
+
+exports.getOrderSuccessPage = async (req, res) => {
+  try {
+    const { id } = req.params;
+    const order = await Order.findById(id).populate('items.product').lean();
+    if (!order)
+      return res
+        .status(404)
+        .json({ status: 'fail', message: 'Order not found' });
+
+    res.status(200).json({
+      status: 'success',
+      data: {
+        message: 'Order placed successfully',
+        order,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};
+
+function computeDiscountAmount(type, value, base) {
+  const numericBase = Number(base) || 0;
+  const numericValue = Number(value) || 0;
+  if (type === 'shipping') return 0; // Does not affect subtotal base
+  if (type === 'percentage')
+    return Math.max(0, (numericBase * numericValue) / 100);
+  return Math.max(0, numericValue);
+}
+
+const SiteSettings = require('../models/siteSettingsModel');
+
+exports.createOrder = async (req, res) => {
+  try {
+    const { name, mobile, address, payment, items, promoCode, source } = req.body;
+
+    // Check guest checkout settings
+    if (!req.user) {
+      const settings = await SiteSettings.getSettings();
+      if (!settings.checkout.allowGuestCheckout) {
+        return res.status(401).json({
+          status: 'fail',
+          message:
+            'Guest checkout is disabled. Please log in or create an account to place an order.',
+        });
+      }
+    }
+
+    if (!items || !Array.isArray(items) || items.length === 0) {
+      return res
+        .status(400)
+        .json({ status: 'fail', message: 'Cart items are required' });
+    }
+
+    if (payment && payment.method === 'visa' && !req.user) {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'You must be logged in to pay with Visa',
+      });
+    }
+
+    const productIds = items.map((i) => i.productId);
+    const products = await Product.find({ _id: { $in: productIds } });
+    const productMap = new Map(products.map((p) => [String(p._id), p]));
+
+    const missingIds = productIds.filter((id) => !productMap.has(String(id)));
+    if (missingIds.length > 0) {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'Some products were not found',
+        missingProductIds: missingIds,
+      });
+    }
+
+    // Decrease stock for each product and track out-of-stock items
+    // Decrease stock for each product in bulk
+    const bulkOps = items.map((i) => ({
+      updateOne: {
+        filter: { _id: i.productId },
+        update: { $inc: { stock: -(Number(i.quantity) || 1) } },
+      },
+    }));
+    await Product.bulkWrite(bulkOps);
+
+    // Identify products that went out of stock
+    const outOfStockItems = await Product.find({
+      _id: { $in: productIds },
+      stock: { $lte: 0 },
+    });
+
+    let subtotal = 0;
+    const orderItems = [];
+    for (const i of items) {
+      const prod = productMap.get(String(i.productId));
+      const quantity = Number(i.quantity) || 1;
+      const unitPrice =
+        prod.salePrice && prod.salePrice < prod.price
+          ? prod.salePrice
+          : prod.price;
+      subtotal += unitPrice * quantity;
+      orderItems.push({
+        product: prod._id,
+        name: prod.nameAr || prod.nameEn || prod.barCode,
+        quantity,
+        unitPrice,
+      });
+    }
+
+    // Dynamic Shipping Calculation:
+    // Strictly find price for the governorate level
+    const govPrice = await ShippingPrice.findOne({
+      $or: [
+        { areaNameAr: address.governorate },
+        {
+          areaNameEn: {
+            $regex: new RegExp(`^${address.governorate.trim()}$`, 'i'),
+          },
+        },
+      ],
+      type: 'city',
+    });
+
+    const SHIPPING_COST = govPrice ? govPrice.fees : 300;
+    const deliveryDays = govPrice ? govPrice.deliveryDays : 3;
+
+    // Calculate estimated delivery date
+    const estimatedDeliveryDate = new Date();
+    estimatedDeliveryDate.setDate(
+      estimatedDeliveryDate.getDate() + deliveryDays,
+    );
+
+    let totalPrice = subtotal + SHIPPING_COST;
+
+    let appliedPromo = null;
+    let discountAmountApplied = 0;
+    if (promoCode) {
+      const upper = String(promoCode).trim().toUpperCase();
+      const now = new Date();
+
+      const promo = await Promo.findOne({
+        code: upper,
+        active: true,
+        $and: [
+          { $or: [{ startsAt: null }, { startsAt: { $lte: now } }] },
+          { $or: [{ expiresAt: null }, { expiresAt: { $gt: now } }] },
+        ],
+        minOrderValue: { $lte: subtotal },
+      });
+
+      if (!promo)
+        return res
+          .status(400)
+          .json({ status: 'fail', message: 'Invalid or expired promo code' });
+
+      if (promo.perUserLimit && promo.perUserLimit > 0) {
+        if (!req.user)
+          return res.status(400).json({
+            status: 'fail',
+            message: 'You must be logged in to use this promo code',
+          });
+        const userUses = await Order.countDocuments({
+          user: req.user._id,
+          promo: promo._id,
+        });
+        if (userUses >= promo.perUserLimit)
+          return res.status(400).json({
+            status: 'fail',
+            message: 'Promo code usage limit reached for this user',
+          });
+      }
+
+      if (promo.usageLimit != null && promo.usedCount >= promo.usageLimit)
+        return res
+          .status(400)
+          .json({ status: 'fail', message: 'Promo code has been fully used' });
+
+      await Promo.findByIdAndUpdate(promo._id, { $inc: { usedCount: 1 } });
+      appliedPromo = promo;
+
+      const discount = computeDiscountAmount(promo.type, promo.value, subtotal);
+      discountAmountApplied = discount;
+
+      if (promo.type === 'shipping') {
+        totalPrice = subtotal; // Shipping is free
+        discountAmountApplied = SHIPPING_COST; // Record the shipping saving as the discount
+      } else {
+        totalPrice = Math.max(0, subtotal - discount) + SHIPPING_COST;
+      }
+    }
+
+    const normalizedPayment = { ...payment };
+    // Don't automatically mark visa payments as paid - wait for Paymob callback
+    if (!normalizedPayment || !normalizedPayment.status) {
+      normalizedPayment.status = 'pending';
+    }
+
+    let promoData = {};
+    if (promoCode && appliedPromo) {
+      const discountAmount = Number(discountAmountApplied.toFixed(2));
+      promoData = {
+        promo: appliedPromo._id,
+        promoCode: appliedPromo.code,
+        discountAmount,
+        discountType: appliedPromo.type,
+      };
+    }
+
+    const orderData = {
+      name,
+      mobile,
+      address,
+      items: orderItems,
+      payment: normalizedPayment,
+      totalPrice,
+      estimatedDeliveryDate,
+      shippingPrice: SHIPPING_COST,
+      source: source || 'direct',
+      ...promoData,
+    };
+
+    if (req.user) orderData.user = req.user._id;
+
+    let newOrder;
+    try {
+      newOrder = await Order.create(orderData);
+    } catch (err) {
+      // Rollback: Restore stock if order creation fails
+      try {
+        await restoreOrderStock(orderItems);
+      } catch (restoreErr) {
+        console.error(
+          'Failed to restore stock after order creation error:',
+          restoreErr,
+        );
+      }
+
+      if (appliedPromo) {
+        try {
+          await Promo.findByIdAndUpdate(appliedPromo._id, {
+            $inc: { usedCount: -1 },
+          });
+        } catch (err2) {
+          // Silent fail or use a proper logger
+        }
+      }
+      throw err;
+    }
+
+    // Send notifications (ONLY for CASH orders)
+    // For Visa, we notify only after successful payment confirmation in paymentController
+    if (newOrder.payment.method === 'cash') {
+      try {
+        if (req.user) {
+          notifyOrderCreated(newOrder, req.user._id).catch(() => { });
+        }
+
+        const vendorIds = new Set();
+        products.forEach((p) => {
+          if (p.provider) vendorIds.add(p.provider.toString());
+        });
+
+        vendorIds.forEach((vId) => {
+          notifyVendorNewOrder(newOrder, vId).catch(() => { });
+        });
+
+        notifyAdminsNewOrder(newOrder).catch(() => { });
+      } catch (notifErr) {
+        // Silent fail
+      }
+    }
+
+    // Out-of-stock notifications should happen regardless of payment method
+    // because stock IS deducted from the DB now
+    try {
+      outOfStockItems.forEach((prod) => {
+        if (prod.provider) {
+          notifyProductOutOfStock(prod, prod.provider).catch(() => { });
+        }
+        notifyAdminsProductOutOfStock(prod).catch(() => { });
+      });
+    } catch (vendorNotifErr) {
+      // Silent fail
+    }
+
+    // Explicitly broadcast order update for the dashboard (ONLY ONCE)
+    emitOrderUpdate(newOrder, 'order_created');
+
+    res.status(201).json({
+      status: 'success',
+      data: { order: newOrder },
+    });
+
+    // Sync to Google Sheet (live update)
+    syncOrderWithSheet(newOrder).catch(() => {});
+
+    // Send order confirmation email (non-blocking - after response)
+    // ONLY for cash orders. Visa orders will send once payment is confirmed.
+    if (req.user && newOrder.payment.method === 'cash') {
+      // Populate order with product details and provider for email
+      const populatedOrder = await Order.findById(newOrder._id).populate({
+        path: 'items.product',
+        select: 'nameAr price imageCover',
+        populate: {
+          path: 'provider',
+          select: 'storeName',
+        },
+      });
+
+      // Prepare order data for email template
+      const emailOrderData = {
+        orderNumber: newOrder._id.toString().slice(-8).toUpperCase(), // Last 8 chars of ID
+        items: populatedOrder.items.map((item) => ({
+          product: {
+            nameAr:
+              item.product && item.product.nameAr
+                ? item.product.nameAr
+                : item.name,
+            imageCover:
+              item.product && item.product.imageCover
+                ? item.product.imageCover
+                : null,
+            provider:
+              item.product && item.product.provider
+                ? item.product.provider
+                : null,
+          },
+          quantity: item.quantity,
+          price: item.unitPrice,
+        })),
+        subtotal: subtotal,
+        discount: discountAmountApplied,
+        shippingCost: SHIPPING_COST,
+        total: totalPrice,
+        paymentMethod: newOrder.payment.method,
+        shippingAddress: {
+          street: newOrder.address.street,
+          city: newOrder.address.city,
+          governorate: newOrder.address.governorate,
+          phone: newOrder.mobile,
+        },
+      };
+
+      sendOrderConfirmationEmail(emailOrderData, req.user).catch(() => { });
+    }
+
+    // Notify all admin users by email about the new order
+    User.find({ role: 'admin' })
+      .select('email name')
+      .lean()
+      .then((admins) => {
+        if (!admins || admins.length === 0) return;
+
+        // Reuse emailOrderData if already built (cash orders), otherwise build a minimal version
+        const adminOrderData = {
+          orderNumber: newOrder._id.toString().slice(-8).toUpperCase(),
+          items: newOrder.items.map((item) => ({
+            product: { nameAr: item.name, imageCover: null, provider: null },
+            quantity: item.quantity,
+            price: item.unitPrice,
+          })),
+          subtotal,
+          discount: discountAmountApplied,
+          shippingCost: SHIPPING_COST,
+          total: totalPrice,
+          paymentMethod: newOrder.payment.method,
+          shippingAddress: {
+            street: newOrder.address.street,
+            city: newOrder.address.city,
+            governorate: newOrder.address.governorate,
+            phone: newOrder.mobile,
+          },
+        };
+
+        const customer = req.user
+          ? { name: req.user.name, email: req.user.email }
+          : { name: 'عميل غير مسجل', email: '-' };
+
+        admins.forEach((admin) => {
+          sendAdminNewOrderEmail(adminOrderData, customer, admin.email).catch(
+            () => { },
+          );
+        });
+      })
+      .catch(() => { });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: err.message,
+    });
+  }
+};
+
+exports.updateOrderItemFulfillment = async (req, res) => {
+  try {
+    const { orderId, productId } = req.params;
+    const { fulfillmentStatus } = req.body;
+
+    // Validate fulfillment status
+    const validStatuses = ['pending', 'preparing', 'ready', 'cancelled'];
+    if (!validStatuses.includes(fulfillmentStatus)) {
+      return res
+        .status(400)
+        .json({ status: 'fail', message: 'Invalid fulfillment status' });
+    }
+
+    const order = await Order.findById(orderId).populate('items.product');
+
+    if (!order) {
+      return res
+        .status(404)
+        .json({ status: 'fail', message: 'Order not found' });
+    }
+
+    // Find the item
+    const item = order.items.find(
+      (it) => it.product && it.product._id.toString() === productId,
+    );
+
+    if (!item) {
+      return res
+        .status(404)
+        .json({ status: 'fail', message: 'Product not found in this order' });
+    }
+
+    // Authorization check
+    // Admins and employees with manage_orders can update anything
+    const isAdmin = req.user.role === 'admin';
+    const isEmployee =
+      req.user.role === 'employee' &&
+      req.user.permissions.includes(PERMISSIONS.MANAGE_ORDERS);
+
+    // For vendors, check if they own the product
+    if (!isAdmin && !isEmployee) {
+      if (req.user.role !== 'vendor' || !req.user.provider) {
+        return res
+          .status(403)
+          .json({ status: 'fail', message: 'Not authorized' });
+      }
+
+      const providerId = req.user.provider._id || req.user.provider;
+      if (item.product.provider.toString() !== providerId.toString()) {
+        return res.status(403).json({
+          status: 'fail',
+          message: 'You can only update your own items',
+        });
+      }
+    }
+
+    item.fulfillmentStatus = fulfillmentStatus;
+
+    // Handle cancellation
+    if (fulfillmentStatus === 'cancelled') {
+      order.orderStatus = 'cancelled';
+      // Restore stock for all items in the order
+      await restoreOrderStock(order.items);
+    } else if (
+      // Auto-revert order status to processing if an item is moved back from 'ready'
+      // when the order was already shipped or completed
+      fulfillmentStatus !== 'ready' &&
+      ['shipped', 'completed'].includes(order.orderStatus)
+    ) {
+      order.orderStatus = 'processing';
+    }
+
+    await order.save();
+
+    emitOrderUpdate(order, 'order_item_updated');
+
+    res.status(200).json({
+      status: 'success',
+      data: { order },
+    });
+
+    // Sync to Google Sheet (live update)
+    syncOrderWithSheet(order).catch(() => {});
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};
+
+exports.updateOrderItemQuantity = async (req, res) => {
+  try {
+    const { orderId, productId } = req.params;
+    const { quantity } = req.body;
+
+    if (!quantity || quantity < 1) {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'Quantity must be at least 1',
+      });
+    }
+
+    const order = await Order.findById(orderId).populate('items.product');
+
+    if (!order) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'Order not found',
+      });
+    }
+
+    // Authorization check: Only admins or authorized employees can edit quantities
+    const isAdmin = req.user.role === 'admin';
+    const isEmployee =
+      req.user.role === 'employee' &&
+      req.user.permissions.includes(PERMISSIONS.MANAGE_ORDERS);
+
+    if (!isAdmin && !isEmployee) {
+      return res.status(403).json({
+        status: 'fail',
+        message: 'Not authorized to change quantities',
+      });
+    }
+
+    // Find the item
+    const item = order.items.find(
+      (it) => it.product && it.product._id.toString() === productId,
+    );
+
+    if (!item) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'Product not found in this order',
+      });
+    }
+
+    const oldQuantity = item.quantity;
+    const quantityDiff = quantity - oldQuantity;
+
+    // Update product stock
+    if (quantityDiff !== 0) {
+      const product = await Product.findById(productId);
+      if (product) {
+        // If increasing quantity, check if there's enough stock
+        if (quantityDiff > 0 && product.stock < quantityDiff) {
+          return res.status(400).json({
+            status: 'fail',
+            message: `Insufficient stock for ${product.nameAr || product.nameEn}. Available: ${product.stock}`,
+          });
+        }
+        product.stock -= quantityDiff;
+        await product.save();
+      }
+    }
+
+    // Update item quantity
+    item.quantity = quantity;
+
+    // Recalculate totals
+    let newSubtotal = 0;
+    order.items.forEach((it) => {
+      newSubtotal += it.unitPrice * it.quantity;
+    });
+
+    // Handle discount recalculation if there was a promo code
+    if (order.promo) {
+      const promo = await Promo.findById(order.promo);
+      if (promo) {
+        const newDiscount = computeDiscountAmount(
+          promo.type,
+          promo.value,
+          newSubtotal,
+        );
+        order.discountAmount = newDiscount;
+
+        if (promo.type === 'shipping') {
+          order.totalPrice = newSubtotal;
+        } else {
+          order.totalPrice =
+            Math.max(0, newSubtotal - newDiscount) + order.shippingPrice;
+        }
+      } else {
+        // Promo not found, keep old shipping logic but update total
+        order.totalPrice =
+          newSubtotal + order.shippingPrice - order.discountAmount;
+      }
+    } else {
+      order.totalPrice =
+        newSubtotal + order.shippingPrice - order.discountAmount;
+    }
+
+    await order.save();
+
+    emitOrderUpdate(order, 'order_quantity_updated');
+
+    res.status(200).json({
+      status: 'success',
+      data: { order },
+    });
+
+    // Sync to Google Sheet (live update)
+    syncOrderWithSheet(order).catch(() => {});
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};
+
+exports.addOrderItem = async (req, res) => {
+  try {
+    const { id: orderId } = req.params;
+    const { productId, quantity } = req.body;
+
+    if (!quantity || quantity < 1) {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'Quantity must be at least 1',
+      });
+    }
+
+    const order = await Order.findById(orderId).populate('items.product');
+    if (!order) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'Order not found',
+      });
+    }
+
+    const product = await Product.findById(productId);
+    if (!product) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'Product not found',
+      });
+    }
+
+    if (product.stock < quantity) {
+      return res.status(400).json({
+        status: 'fail',
+        message: `Insufficient stock for ${product.nameAr || product.nameEn}. Available: ${product.stock}`,
+      });
+    }
+
+    // Authorization check
+    const isAdmin = req.user.role === 'admin';
+    const isEmployee =
+      req.user.role === 'employee' &&
+      req.user.permissions.includes(PERMISSIONS.MANAGE_ORDERS);
+
+    if (!isAdmin && !isEmployee) {
+      return res.status(403).json({
+        status: 'fail',
+        message: 'Not authorized to add items to orders',
+      });
+    }
+
+    // Check if product already exists in order
+    const existingItem = order.items.find(
+      (item) => item.product && item.product._id.toString() === productId,
+    );
+
+    if (existingItem) {
+      existingItem.quantity += quantity;
+      existingItem.fulfillmentStatus = 'pending';
+    } else {
+      order.items.push({
+        product: productId,
+        name: product.nameAr || product.nameEn,
+        quantity,
+        unitPrice:
+          product.salePrice && product.salePrice < product.price
+            ? product.salePrice
+            : product.price,
+      });
+    }
+
+    // Deduct stock
+    product.stock -= quantity;
+    await product.save();
+
+    // Recalculate totals
+    let newSubtotal = 0;
+    order.items.forEach((it) => {
+      newSubtotal += it.unitPrice * it.quantity;
+    });
+
+    if (order.promo) {
+      const promo = await Promo.findById(order.promo);
+      if (promo) {
+        const newDiscount = computeDiscountAmount(
+          promo.type,
+          promo.value,
+          newSubtotal,
+        );
+        order.discountAmount = newDiscount;
+
+        if (promo.type === 'shipping') {
+          order.totalPrice = newSubtotal;
+        } else {
+          order.totalPrice =
+            Math.max(0, newSubtotal - newDiscount) + order.shippingPrice;
+        }
+      } else {
+        order.totalPrice =
+          newSubtotal + order.shippingPrice - order.discountAmount;
+      }
+    } else {
+      order.totalPrice =
+        newSubtotal + order.shippingPrice - order.discountAmount;
+    }
+
+    await order.save();
+
+    emitOrderUpdate(order, 'order_item_added');
+
+    res.status(200).json({
+      status: 'success',
+      data: { order },
+    });
+
+    // Sync to Google Sheet (live update)
+    syncOrderWithSheet(order).catch(() => {});
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};
+
+exports.removeOrderItem = async (req, res) => {
+  try {
+    const { orderId, productId } = req.params;
+
+    const order = await Order.findById(orderId);
+
+    if (!order) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'Order not found',
+      });
+    }
+
+    // Authorization check
+    const isAdmin = req.user.role === 'admin';
+    const isEmployee =
+      req.user.role === 'employee' &&
+      req.user.permissions.includes(PERMISSIONS.MANAGE_ORDERS);
+
+    if (!isAdmin && !isEmployee) {
+      return res.status(403).json({
+        status: 'fail',
+        message: 'Not authorized to remove items from orders',
+      });
+    }
+
+    // Find the item index
+    const itemIndex = order.items.findIndex(
+      (it) => it.product && it.product.toString() === productId,
+    );
+
+    if (itemIndex === -1) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'Product not found in this order',
+      });
+    }
+
+    // Prevent removing the last item (order must have at least one item)
+    if (order.items.length <= 1) {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'Cannot remove the last item. Use "Delete Order" instead.',
+      });
+    }
+
+    const itemToRemove = order.items[itemIndex];
+
+    // Restore stock
+    const product = await Product.findById(productId);
+    if (product) {
+      product.stock += itemToRemove.quantity;
+      await product.save();
+    }
+
+    // Remove the item
+    order.items.splice(itemIndex, 1);
+
+    // Recalculate totals
+    let newSubtotal = 0;
+    order.items.forEach((it) => {
+      newSubtotal += it.unitPrice * it.quantity;
+    });
+
+    if (order.promo) {
+      const promo = await Promo.findById(order.promo);
+      if (promo) {
+        const newDiscount = computeDiscountAmount(
+          promo.type,
+          promo.value,
+          newSubtotal,
+        );
+        order.discountAmount = newDiscount;
+
+        if (promo.type === 'shipping') {
+          order.totalPrice = newSubtotal;
+        } else {
+          order.totalPrice =
+            Math.max(0, newSubtotal - newDiscount) + order.shippingPrice;
+        }
+      } else {
+        order.totalPrice =
+          newSubtotal + order.shippingPrice - order.discountAmount;
+      }
+    } else {
+      order.totalPrice =
+        newSubtotal + order.shippingPrice - order.discountAmount;
+    }
+
+    await order.save();
+
+    emitOrderUpdate(order, 'order_item_removed');
+
+    res.status(200).json({
+      status: 'success',
+      data: { order },
+    });
+
+    // Sync to Google Sheet (live update)
+    syncOrderWithSheet(order).catch(() => {});
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};

controllers/paymentController.js

@@ -0,0 +1,516 @@
+const Order = require('../models/orderModel');
+const {
+  initiatePayment: initiatePaymobPayment,
+  verifyPayment: verifyPaymobPayment,
+  refundTransaction: refundPaymobTransaction,
+} = require('../utils/paymobService');
+const { sendOrderConfirmationEmail } = require('../utils/emailService');
+const {
+  notifyOrderCreated,
+  notifyAdminsNewOrder,
+  notifyVendorNewOrder,
+  emitOrderUpdate,
+} = require('../utils/notificationService');
+const { syncOrderWithSheet } = require('../utils/googleSheetsService');
+
+/**
+ * Initiate Paymob payment for an order
+ * This should be called after creating an order with payment method 'visa'
+ */
+exports.initiatePayment = async (req, res) => {
+  try {
+    const { orderId, frontendUrl } = req.body;
+
+    if (!orderId) {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'Order ID is required',
+      });
+    }
+
+    const order = await Order.findById(orderId).populate('items.product');
+
+    if (!order) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'Order not found',
+      });
+    }
+
+    // Verify that the order belongs to the user (if not admin)
+    if (req.user && order.user && String(order.user) !== String(req.user._id)) {
+      return res.status(403).json({
+        status: 'fail',
+        message: 'Not authorized to access this order',
+      });
+    }
+
+    // Check if payment method is visa
+    if (order.payment.method !== 'visa') {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'This order does not require online payment',
+      });
+    }
+
+    // Check if already paid
+    if (order.payment.status === 'paid') {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'This order has already been paid',
+      });
+    }
+
+    // Prepare billing data
+    const nameParts = order.name.split(' ');
+    const billingData = {
+      firstName: nameParts[0] || order.name,
+      lastName: nameParts.slice(1).join(' ') || nameParts[0],
+      email: req.user ? req.user.email : 'guest@samoulla.com',
+      phone: order.mobile,
+      street: order.address.street,
+      city: order.address.city,
+      state: order.address.governorate,
+      country: 'EG',
+      apartment: 'NA',
+      floor: 'NA',
+      building: 'NA',
+      postalCode: 'NA',
+    };
+
+    // Prepare order data for Paymob
+    const orderData = {
+      amount: order.totalPrice,
+      items: order.items.map((item) => ({
+        name: item.name,
+        quantity: item.quantity,
+        unitPrice: item.unitPrice,
+        description: item.name,
+      })),
+      billingData,
+    };
+
+    // Initiate payment with Paymob
+    const paymentResult = await initiatePaymobPayment(orderData);
+
+    if (!paymentResult.success) {
+      return res.status(500).json({
+        status: 'error',
+        message: 'Failed to initiate payment',
+        error: paymentResult.error,
+      });
+    }
+
+    // Update order with Paymob data
+    order.payment.paymobOrderId = paymentResult.paymobOrderId;
+    order.payment.paymentKey = paymentResult.paymentKey;
+    if (frontendUrl) {
+      order.payment.frontendUrl = frontendUrl;
+    }
+    await order.save();
+
+    res.status(200).json({
+      status: 'success',
+      data: {
+        paymentKey: paymentResult.paymentKey,
+        iframeUrl: paymentResult.iframeUrl,
+        paymobOrderId: paymentResult.paymobOrderId,
+      },
+    });
+  } catch (error) {
+    console.error('Payment initiation error:', error);
+    res.status(500).json({
+      status: 'error',
+      message: error.message,
+    });
+  }
+};
+
+const { restoreOrderStock } = require('../utils/orderUtils');
+const Promo = require('../models/promoCodeModel');
+
+/**
+ * Paymob callback handler
+ * This endpoint receives payment status updates from Paymob
+ */
+exports.paymobCallback = async (req, res) => {
+  let order;
+  try {
+    // Combine body and query for consistent data access
+    const transactionData = { ...req.query, ...req.body };
+
+    console.log(
+      'Paymob callback received:',
+      JSON.stringify(transactionData, null, 2),
+    );
+
+    // Verify payment using HMAC
+    const verificationResult = await verifyPaymobPayment(transactionData);
+
+    // TRY TO FIND ORDER EARLY (to get frontendUrl for redirects)
+    if (verificationResult.orderId) {
+      order = await Order.findOne({
+        'payment.paymobOrderId': String(verificationResult.orderId),
+      }).populate('user', 'name email');
+    }
+
+    const fallbackUrl = process.env.FRONTEND_URL || 'http://localhost:5173';
+    const frontendUrl =
+      (order && order.payment && order.payment.frontendUrl) || fallbackUrl;
+
+    // 1. VERIFICATION CHECK
+    if (!verificationResult.hmacVerified) {
+      console.error('Payment verification failed: Invalid HMAC signature');
+      if (req.method === 'GET') {
+        return res.redirect(
+          `${frontendUrl}/checkout?error=verification_failed`,
+        );
+      }
+      return res
+        .status(200)
+        .json({ message: 'Callback received but verification failed' });
+    }
+
+    // 2. FIND AND UPDATE ORDER (If not already found)
+    if (!order) {
+      console.error(
+        'Order not found for Paymob order ID:',
+        verificationResult.orderId,
+      );
+      if (req.method === 'GET') {
+        // If it's a redirect and order is gone (maybe deleted by POST already),
+        // We still want to go back to checkout with a status if possible
+        const status = verificationResult.success ? 'success' : 'failed';
+        if (status === 'failed') {
+          return res.redirect(`${frontendUrl}/checkout?status=failed`);
+        }
+        return res.redirect(`${frontendUrl}/checkout?error=order_not_found`);
+      }
+      return res.status(200).json({ message: 'Order not found' });
+    }
+
+    // IDEMPOTENCY CHECK: Skip if already processed (paid or explicitly cancelled)
+    const isAlreadyPaid = order.payment.status === 'paid';
+    const isAlreadyCancelled = order.orderStatus === 'cancelled';
+
+    if (!isAlreadyPaid && !isAlreadyCancelled) {
+      if (verificationResult.success) {
+        // SUCCESSFUL TRANSACTION
+        order.payment.status = 'paid';
+        order.payment.paidAt = new Date();
+        order.payment.paymobTransactionId = String(
+          verificationResult.transactionId,
+        );
+
+        // Ensure orderStatus is 'created' or 'processing' if paid
+        if (order.orderStatus === 'cancelled') order.orderStatus = 'created';
+
+        await order.save();
+
+        // Send confirmation email and notifications
+        try {
+          // Notify the user
+          if (order.user) {
+            await notifyOrderCreated(order, order.user._id || order.user);
+          }
+
+          // Notify admins
+          await notifyAdminsNewOrder(order);
+
+          // Notify vendors
+          const uniqueProviderIds = new Set();
+          // We need items available here. Let's populate them if needed or use the existing ones.
+          // The order already has items array but products might not be populated with provider.
+          const orderWithProducts = await Order.findById(order._id).populate(
+            'items.product',
+          );
+          orderWithProducts.items.forEach((item) => {
+            if (item.product && item.product.provider) {
+              uniqueProviderIds.add(item.product.provider.toString());
+            }
+          });
+
+          for (const pId of uniqueProviderIds) {
+            await notifyVendorNewOrder(order, pId);
+          }
+
+          // Send Email
+          if (order.user) {
+            // Populate for email (fully)
+            const populatedOrderForEmail = await Order.findById(
+              order._id,
+            ).populate({
+              path: 'items.product',
+              select: 'nameAr price imageCover',
+              populate: { path: 'provider', select: 'storeName' },
+            });
+
+            const emailOrderData = {
+              orderNumber: order._id.toString().slice(-8).toUpperCase(),
+              items: populatedOrderForEmail.items.map((item) => ({
+                product: {
+                  nameAr: (item.product && item.product.nameAr) || item.name,
+                  imageCover: (item.product && item.product.imageCover) || null,
+                  provider: (item.product && item.product.provider) || null,
+                },
+                quantity: item.quantity,
+                price: item.unitPrice,
+              })),
+              subtotal:
+                order.totalPrice -
+                (order.shippingPrice || 0) +
+                (order.discountAmount || 0),
+              discount: order.discountAmount || 0,
+              shippingCost: order.shippingPrice || 0,
+              total: order.totalPrice,
+              paymentMethod: order.payment.method,
+              shippingAddress: {
+                street: order.address.street,
+                city: order.address.city,
+                governorate: order.address.governorate,
+                phone: order.mobile,
+              },
+            };
+
+            await sendOrderConfirmationEmail(emailOrderData, order.user);
+          }
+        } catch (notifErr) {
+          console.error('Notification/Email error:', notifErr);
+        }
+
+        emitOrderUpdate(order, 'payment_completed');
+        console.log(`✅ Payment successful for order ${order._id}`);
+
+        // Sync to Google Sheet (live update)
+        syncOrderWithSheet(order).catch(() => {});
+      } else {
+        // FAILED TRANSACTION
+        // Per user request: Don't place (keep) the order if payment failed.
+        // We delete it instead of marking as cancelled.
+
+        // 1. RESTORE STOCK
+        try {
+          await restoreOrderStock(order.items);
+          console.log(
+            `📦 Stock restored for deleted (previously failed) order ${order._id}`,
+          );
+        } catch (stockErr) {
+          console.error('Failed to restore stock:', stockErr);
+        }
+
+        // 2. RESTORE PROMO (if any)
+        if (order.promo) {
+          try {
+            await Promo.findByIdAndUpdate(order.promo, {
+              $inc: { usedCount: -1 },
+            });
+            console.log(`🏷️ Promo usage rolled back for order ${order._id}`);
+          } catch (promoErr) {
+            console.error('Failed to restore promo usage:', promoErr);
+          }
+        }
+
+        // 3. EMIT FAILURE EVENT (before delete)
+        emitOrderUpdate(order, 'payment_failed');
+
+        // 4. DELETE THE ORDER
+        const orderId = order._id;
+        await Order.findByIdAndDelete(orderId);
+        console.log(`🗑️ Failed order ${orderId} deleted from database`);
+      }
+    } else {
+      console.log(
+        `ℹ️ Order ${order._id} already processed. Status: ${order.payment.status}, OrderStatus: ${order.orderStatus}`,
+      );
+    }
+
+    // 3. FINAL RESPONSE
+    if (req.method === 'GET') {
+      const status = verificationResult.success ? 'success' : 'failed';
+      console.log(
+        `Redirecting user for order ${order._id} with status ${status} to ${frontendUrl}`,
+      );
+
+      if (status === 'success') {
+        return res.redirect(
+          `${frontendUrl}/order-confirmation/${order._id}?status=success`,
+        );
+      }
+      return res.redirect(
+        `${frontendUrl}/checkout?status=failed&orderId=${order._id}`,
+      );
+    }
+
+    res.status(200).json({
+      status: 'success',
+      message: 'Callback processed successfully',
+    });
+  } catch (error) {
+    console.error('Callback processing error:', error);
+    if (req.method === 'GET') {
+      const fallbackUrlCatch =
+        process.env.FRONTEND_URL || 'http://localhost:5173';
+      const frontendUrlCatch =
+        (order && order.payment && order.payment.frontendUrl) ||
+        fallbackUrlCatch;
+      return res.redirect(
+        `${frontendUrlCatch}/checkout?error=internal_server_error`,
+      );
+    }
+    res
+      .status(200)
+      .json({ message: 'Callback received but processing failed' });
+  }
+};
+
+/**
+ * Check payment status for an order
+ */
+exports.checkPaymentStatus = async (req, res) => {
+  try {
+    const { orderId } = req.params;
+
+    const order = await Order.findById(orderId);
+
+    if (!order) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'Order not found',
+      });
+    }
+
+    // Verify that the order belongs to the user (if not admin)
+    if (req.user && order.user && String(order.user) !== String(req.user._id)) {
+      return res.status(403).json({
+        status: 'fail',
+        message: 'Not authorized to access this order',
+      });
+    }
+
+    res.status(200).json({
+      status: 'success',
+      data: {
+        paymentStatus: order.payment.status,
+        paymentMethod: order.payment.method,
+        paidAt: order.payment.paidAt,
+        transactionId: order.payment.paymobTransactionId,
+      },
+    });
+  } catch (error) {
+    console.error('Payment status check error:', error);
+    res.status(500).json({
+      status: 'error',
+      message: error.message,
+    });
+  }
+};
+
+/**
+ * Refund a payment (Admin only)
+ */
+exports.refundPayment = async (req, res) => {
+  try {
+    const { orderId } = req.params;
+    const { amount } = req.body;
+
+    const order = await Order.findById(orderId);
+
+    if (!order) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'Order not found',
+      });
+    }
+
+    // Check if order was paid
+    if (order.payment.status !== 'paid') {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'Cannot refund an unpaid order',
+      });
+    }
+
+    // Check if transaction ID exists
+    if (!order.payment.paymobTransactionId) {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'No Paymob transaction found for this order',
+      });
+    }
+
+    // Determine refund amount
+    const refundAmount = amount || order.totalPrice;
+
+    if (refundAmount > order.totalPrice) {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'Refund amount cannot exceed order total',
+      });
+    }
+
+    // Process refund with Paymob
+    const refundResult = await refundPaymobTransaction(
+      order.payment.paymobTransactionId,
+      refundAmount,
+    );
+
+    if (!refundResult.success) {
+      return res.status(500).json({
+        status: 'error',
+        message: 'Failed to process refund',
+        error: refundResult.error,
+      });
+    }
+
+    // Update order
+    order.payment.refundedAt = new Date();
+    order.payment.refundAmount = refundAmount;
+    order.payment.status = 'failed'; // Mark as failed after refund
+    await order.save();
+
+    // Broadcast order update
+    emitOrderUpdate(order, 'payment_refunded');
+
+    res.status(200).json({
+      status: 'success',
+      data: {
+        message: 'Refund processed successfully',
+        refundAmount,
+        order,
+      },
+    });
+  } catch (error) {
+    console.error('Refund processing error:', error);
+    res.status(500).json({
+      status: 'error',
+      message: error.message,
+    });
+  }
+};
+
+/**
+ * Paymob transaction processed callback (Alternative callback endpoint)
+ */
+exports.paymobTransactionCallback = async (req, res) => {
+  try {
+    // Extract data from query parameters (Paymob sends some data via GET)
+    const transactionData = {
+      ...req.query,
+      ...req.body,
+    };
+
+    console.log(
+      'Transaction callback received:',
+      JSON.stringify(transactionData, null, 2),
+    );
+
+    // Forward to main callback handler
+    req.body = transactionData;
+    return exports.paymobCallback(req, res);
+  } catch (error) {
+    console.error('Transaction callback error:', error);
+    res.status(200).json({ message: 'Callback received' });
+  }
+};
+
+module.exports = exports;

controllers/productController.js

@@ -0,0 +1,2191 @@
+const mongoose = require('mongoose');
+const axios = require('axios');
+const xlsx = require('xlsx');
+const FormData = require('form-data');
+const { cloudinary } = require('../config/cloudinary');
+const Product = require('../models/productModel');
+const Category = require('../models/categoryModel');
+const Provider = require('../models/providerModel');
+const Brand = require('../models/brandModel');
+const User = require('../models/userModel');
+const APIFeatures = require('../utils/apiFeatures');
+const {
+  createSmartSearchRegex,
+  convertArabicNumerals,
+} = require('../utils/arabicSearch');
+const {
+  notifyPastBuyersProductBackInStock,
+  notifyStockSubscribers,
+} = require('../utils/notificationService');
+const {
+  extractVoiceEntities,
+  buildVoiceFilterQuery,
+  buildMongoVoiceQuery,
+  scoreProduct: scoreVoiceProduct,
+  buildSearchTextFromEntities,
+} = require('../utils/voiceSearch');
+
+// Paste your Cloudinary logo URL here to force it as import fallback cover.
+// Example: https://res.cloudinary.com/<cloud-name>/image/upload/v1234567890/samoulla/system/logo-cover.png
+const HARDCODED_IMPORT_LOGO_COVER =
+  'https://res.cloudinary.com/dm9ym99zh/image/upload/v1771470584/Asset_16_wfto7q.png';
+
+const IMPORT_FALLBACK_COVER_IMAGE =
+  HARDCODED_IMPORT_LOGO_COVER ||
+  process.env.IMPORT_FALLBACK_COVER_IMAGE ||
+  'https://placehold.co/1000x1000/png?text=No+Image';
+
+const isImageUrlReachable = async (url) => {
+  if (!url || typeof url !== 'string' || !url.startsWith('http')) return false;
+
+  try {
+    const response = await axios.head(url, {
+      timeout: 7000,
+      maxRedirects: 5,
+      validateStatus: () => true,
+    });
+
+    if (response.status === 405) {
+      const fallbackResponse = await axios.get(url, {
+        timeout: 7000,
+        maxRedirects: 5,
+        headers: { Range: 'bytes=0-0' },
+        validateStatus: () => true,
+      });
+      return fallbackResponse.status >= 200 && fallbackResponse.status < 400;
+    }
+
+    return response.status >= 200 && response.status < 400;
+  } catch (_) {
+    return false;
+  }
+};
+
+// Helper to auto-upload external image URLs to Cloudinary during import
+const uploadExternalImage = async (url, productId, isCover = true) => {
+  if (!url || typeof url !== 'string') return '';
+
+  // Skip non-URL values
+  if (!url.startsWith('http')) return '';
+
+  // Reuse URL only if it's already hosted on the current Cloudinary cloud.
+  // Legacy Cloudinary URLs (e.g., old project cloud) are re-hosted to avoid 404s.
+  const currentCloudName = process.env.CLOUDINARY_CLOUD_NAME;
+  let sourceCloudName = null;
+
+  try {
+    const parsed = new URL(url);
+    const match = parsed.hostname.match(/^res\.cloudinary\.com$/i)
+      ? parsed.pathname.match(/^\/([^/]+)\//)
+      : null;
+    sourceCloudName = match ? match[1] : null;
+
+    const inTargetFolderRegex = new RegExp(
+      `/samoulla/products/${String(productId).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/`,
+    );
+    const isAlreadyInTargetFolder = inTargetFolderRegex.test(parsed.pathname);
+
+    if (sourceCloudName && sourceCloudName === currentCloudName) {
+      const reachable = await isImageUrlReachable(url);
+      if (!reachable) return '';
+
+      // Keep existing URL only when it's already inside the product _id folder.
+      // Otherwise, re-host to enforce folder consistency for this product.
+      if (isAlreadyInTargetFolder) return url;
+    }
+  } catch (_) {
+    return '';
+  }
+
+  try {
+    const prefix = isCover ? 'cover' : 'img';
+    const result = await cloudinary.uploader.upload(url, {
+      folder: `samoulla/products/${productId}`,
+      public_id: `${prefix}-${Date.now()}`,
+      transformation: [
+        { width: 1000, height: 1000, crop: 'limit' },
+        { quality: 'auto' },
+        { fetch_format: 'auto' },
+      ],
+    });
+    return result.secure_url;
+  } catch (err) {
+    console.error(`Auto-upload failed for ${url}:`, err.message);
+    return '';
+  }
+};
+
+// Helper to delete a single image from Cloudinary by its secure URL
+const deleteCloudinaryImage = async (url) => {
+  if (!url || typeof url !== 'string' || !url.includes('cloudinary.com'))
+    return;
+  const currentCloudName = cloudinary.config().cloud_name;
+  if (!url.includes(`/${currentCloudName}/`)) return; // Not our cloud, don't touch it
+  try {
+    // Extract public_id: everything after /upload/(v<digits>/) and before the file extension
+    const match = url.match(/\/upload\/(?:v\d+\/)?(.+?)(?:\.[a-z0-9]+)?$/i);
+    if (!match) return;
+    const publicId = match[1];
+    await cloudinary.uploader.destroy(publicId);
+  } catch (err) {
+    console.error(`Failed to delete Cloudinary image ${url}:`, err.message);
+  }
+};
+
+// Helper to notify the AI service to reload its product cache
+const triggerAiReload = async () => {
+  try {
+    const aiUrl = process.env.AI_SERVICE_URL || 'http://localhost:9001';
+    await axios.post(`${aiUrl}/api/reload-products`);
+    console.log('AI product cache reload triggered successfully');
+  } catch (err) {
+    // Fail silently in production, just log it
+    console.error('Failed to trigger AI product reload:', err.message);
+  }
+};
+
+// Get all products
+exports.getAllProducts = async (req, res) => {
+  try {
+    // 1) Filter by Category (Hierarchy-aware)
+    if (req.query.category !== undefined) {
+      if (
+        req.query.category === 'جميع المنتجات' ||
+        req.query.category === '' ||
+        req.query.category === 'all'
+      ) {
+        delete req.query.category;
+      } else {
+        const categoryValues = req.query.category.split(',');
+        const objectIds = [];
+        const numericIds = [];
+        const nameValues = [];
+
+        categoryValues.forEach((val) => {
+          if (mongoose.Types.ObjectId.isValid(val)) objectIds.push(val);
+          else if (/^\d+$/.test(val)) numericIds.push(val);
+          else nameValues.push(val);
+        });
+
+        // Find initial categories in bulk
+        const foundCategories = await Category.find({
+          $or: [
+            { _id: { $in: objectIds } },
+            { id: { $in: numericIds } },
+            { nameAr: { $in: nameValues } },
+            { nameEn: { $in: nameValues } },
+          ],
+        });
+
+        const categoryIds = foundCategories.map((c) => c._id);
+
+        if (categoryIds.length > 0) {
+          // Get descendants (Level 1)
+          const subCategories = await Category.find({
+            parent: { $in: categoryIds },
+          });
+          const subIds = subCategories.map((c) => c._id);
+          categoryIds.push(...subIds);
+
+          if (subIds.length > 0) {
+            // Level 2 descendants
+            const subSubCategories = await Category.find({
+              parent: { $in: subIds },
+            });
+            categoryIds.push(...subSubCategories.map((c) => c._id));
+          }
+        }
+
+        if (categoryIds.length > 0) {
+          req.query.category = { $in: [...new Set(categoryIds)] };
+        } else {
+          req.query.category = { $in: [new mongoose.Types.ObjectId()] };
+        }
+      }
+    }
+
+    // 2) Filter by Brand (if provided)
+    if (req.query.brand) {
+      const brandValues = req.query.brand.split(',');
+      const isObjectId = mongoose.Types.ObjectId.isValid(brandValues[0]);
+      const isNumericId = /^\d+$/.test(brandValues[0]);
+
+      if (isObjectId) {
+        req.query.brand = { $in: brandValues };
+      } else if (isNumericId) {
+        // Find brand object by numeric ID
+        const brands = await Brand.find({ id: { $in: brandValues } });
+        if (brands.length > 0) {
+          // If product stores name, use names. If it stores ID, use IDs.
+          // For now, let's support both or prioritize names since the current model uses strings.
+          req.query.brand = { $in: brands.map((b) => b.nameEn) };
+        } else {
+          req.query.brand = { $in: ['Unknown Brand'] };
+        }
+      } else {
+        // It's a name
+        req.query.brand = { $in: brandValues };
+      }
+    }
+
+    // 3) Filter by Provider (if provided) - Supports multiple providers by name or slug
+    if (req.query.provider) {
+      const providerValues = req.query.provider.split(',');
+      const providers = await Provider.find({
+        $or: [
+          { storeName: { $in: providerValues } },
+          { slug: { $in: providerValues } },
+          {
+            _id: {
+              $in: providerValues.filter((id) =>
+                mongoose.Types.ObjectId.isValid(id),
+              ),
+            },
+          },
+        ],
+      });
+
+      if (providers.length > 0) {
+        req.query.provider = { $in: providers.map((p) => p._id) };
+      } else {
+        req.query.provider = { $in: ['000000000000000000000000'] };
+      }
+    }
+
+    // 3) Filter by Sale Price (if onSale is true)
+    let salePriceQuery = {};
+    if (req.query.onSale === 'true') {
+      salePriceQuery = { salePrice: { $gt: 0 } };
+      delete req.query.onSale;
+    }
+
+    // Store original search term for relevance scoring (before it gets deleted)
+    const originalSearchTerm = req.query.search
+      ? convertArabicNumerals(req.query.search.trim())
+      : null;
+    const hasExplicitSort = !!req.query.sort;
+
+    // 4) Search by Name, Description, Barcode, or ID (if provided)
+    let searchQuery = {};
+    let relatedQuery = null; // $or query for "related" products (any-word match)
+    if (req.query.search) {
+      // TRACK SEARCH: Save the user's last 5 search terms in their profile if logged in
+      if (req.user) {
+        const searchTerm = req.query.search.trim();
+        if (searchTerm) {
+          // Remove if already exists to move it to the end (most recent)
+          const searchHistory = (req.user.recentSearches || []).filter(
+            (s) => s.toLowerCase() !== searchTerm.toLowerCase(),
+          );
+          searchHistory.push(searchTerm);
+
+          // Keep only last 5
+          if (searchHistory.length > 5) {
+            searchHistory.shift();
+          }
+
+          req.user.recentSearches = searchHistory;
+          // Non-blocking update
+          User.findByIdAndUpdate(req.user._id, {
+            recentSearches: searchHistory,
+          }).catch(() => {});
+        }
+      }
+
+      const searchTerms = req.query.search
+        .split(' ')
+        .map((term) => convertArabicNumerals(term.trim()))
+        .filter((term) => term.length > 0);
+
+      if (searchTerms.length > 0) {
+        // Pre-fetch all matching categories for all terms at once
+        const allSearchRegexes = searchTerms.map((term) =>
+          createSmartSearchRegex(term),
+        );
+        const allMatchingCategories = await Category.find({
+          $or: allSearchRegexes.flatMap((regex) => [
+            { nameAr: regex },
+            { nameEn: regex },
+          ]),
+        }).select('_id nameAr nameEn');
+
+        const searchConditions = searchTerms.map((term) => {
+          const searchRegex = createSmartSearchRegex(term);
+
+          const matchingCategoryIds = allMatchingCategories
+            .filter(
+              (cat) =>
+                (cat.nameAr && cat.nameAr.match(searchRegex)) ||
+                (cat.nameEn && cat.nameEn.match(searchRegex)),
+            )
+            .map((cat) => cat._id);
+
+          // Build search conditions array
+          const conditions = [
+            { nameAr: searchRegex },
+            { nameEn: searchRegex },
+            { descriptionAr: searchRegex },
+            { descriptionEn: searchRegex },
+            { barCode: searchRegex },
+          ];
+
+          if (matchingCategoryIds && matchingCategoryIds.length > 0) {
+            conditions.push({ category: { $in: matchingCategoryIds } });
+          }
+
+          // Check if term looks like a hex string (potential partial ObjectId)
+          if (/^[0-9a-fA-F]+$/.test(term)) {
+            conditions.push({
+              $expr: {
+                $regexMatch: {
+                  input: { $toString: '$_id' },
+                  regex: term,
+                  options: 'i',
+                },
+              },
+            });
+          }
+
+          return { $or: conditions };
+        });
+
+        searchQuery = { $and: searchConditions };
+
+        // Also build an $or query for "related" results (match ANY word).
+        // When multiple words are searched, this lets us append products that
+        // match some — but not all — of the words after the primary matches.
+        if (searchTerms.length > 1) {
+          // Flatten each per-word condition into one big $or
+          const relatedOrConditions = searchConditions.flatMap(
+            (c) => c.$or || [],
+          );
+          relatedQuery = { $or: relatedOrConditions, ...salePriceQuery };
+        }
+      }
+
+      // Remove search from query so it doesn't interfere with APIFeatures
+      delete req.query.search;
+    }
+
+    // Combine search and salePrice queries
+    const combinedQuery = { ...searchQuery, ...salePriceQuery };
+
+    // Calculate pagination params up front
+    const page = req.query.page * 1 || 1;
+    const limit = req.query.limit * 1 || 100;
+
+    // When search is active and no explicit sort, fetch ALL matches so we can
+    // score every result for relevance before paginating. This ensures the best
+    // match is always on page 1 regardless of insertion order in the DB.
+    let products;
+    let totalCount;
+
+    if (originalSearchTerm && !hasExplicitSort) {
+      // Fetch ALL primary matching products ($and — all words must match)
+      const allFeaturesQuery = new APIFeatures(
+        Product.find(combinedQuery)
+          .populate('category', 'nameAr _id')
+          .populate('provider', 'storeName _id'),
+        req.query,
+      )
+        .filter()
+        .sort()
+        .limitFields();
+
+      const primaryProducts = await allFeaturesQuery.query.lean();
+      const primaryIds = new Set(primaryProducts.map((p) => String(p._id)));
+
+      // Fetch related products ($or — match ANY word) that aren't already in primary set
+      let relatedProducts = [];
+      if (relatedQuery) {
+        relatedProducts = await Product.find({
+          ...relatedQuery,
+          _id: { $nin: [...primaryIds] }, // exclude already-found primary products
+        })
+          .populate('category', 'nameAr _id')
+          .populate('provider', 'storeName _id')
+          .select('-__v')
+          .lean();
+      }
+
+      // Merge: primary first, related appended
+      // Scoring below will rank primary products higher (they match all words)
+      products = [...primaryProducts, ...relatedProducts];
+      totalCount = products.length;
+    } else {
+      // Regular path: paginate in DB (faster when no search or explicit sort)
+      const countFeatures = new APIFeatures(
+        Product.find(combinedQuery)
+          .populate('category', 'nameAr _id')
+          .populate('provider', 'storeName _id'),
+        req.query,
+      )
+        .filter()
+        .sort()
+        .limitFields();
+
+      totalCount = await Product.countDocuments(
+        countFeatures.query.getFilter(),
+      );
+
+      const features = new APIFeatures(
+        Product.find(combinedQuery)
+          .populate('category', 'nameAr _id')
+          .populate('provider', 'storeName _id'),
+        req.query,
+      )
+        .filter()
+        .sort()
+        .limitFields()
+        .paginate();
+
+      products = await features.query.lean();
+    }
+
+    // Apply intelligent relevance scoring if search is active and no explicit sort
+    if (originalSearchTerm && !hasExplicitSort && products.length > 0) {
+      // Normalize for Arabic-aware comparisons
+      const { normalizeArabic } = require('../utils/arabicSearch');
+      const normalizedSearchTerm = normalizeArabic(originalSearchTerm);
+      const searchWords = normalizedSearchTerm
+        .split(/\s+/)
+        .filter((w) => w.length > 0);
+      const isMultiWord = searchWords.length > 1;
+
+      /**
+       * Score a single string field against the search term.
+       * Returns a score 0-100 for that field.
+       */
+      const IS_PURE_NUMBER = /^\d+(\.\d+)?$/;
+      const scoreField = (rawText) => {
+        if (!rawText) return 0;
+        const norm = normalizeArabic(rawText);
+
+        // --- Full-phrase matching ---
+        // Exact full match (always valid)
+        if (norm === normalizedSearchTerm) return 100;
+
+        // For pure-number queries (e.g. "5"), don't use startsWith/includes
+        // because "5" would falsely match "1500", "50", etc.
+        if (!IS_PURE_NUMBER.test(normalizedSearchTerm)) {
+          // Starts with full phrase
+          if (norm.startsWith(normalizedSearchTerm)) return 85;
+          // Contains the full phrase as a substring
+          if (norm.includes(normalizedSearchTerm)) return 65;
+        }
+
+        if (isMultiWord) {
+          // For multi-word queries: score based on how many words match in the name.
+          // Numbers must match as exact whole words (so "5" does NOT match "1500").
+          const IS_NUMBER = /^\d+(\.\d+)?$/;
+          let wordMatchCount = 0;
+          let allWordsMatched = true;
+          const normWords = norm.split(/\s+/);
+
+          for (const word of searchWords) {
+            let matched = false;
+            if (IS_NUMBER.test(word)) {
+              // Numeric token: require exact equality only
+              matched = normWords.some((nw) => nw === word);
+            } else {
+              // Text token: allow starts-with / contains (fuzzy)
+              matched = normWords.some(
+                (nw) => nw === word || nw.startsWith(word) || nw.includes(word),
+              );
+            }
+            if (matched) {
+              wordMatchCount++;
+            } else {
+              allWordsMatched = false;
+            }
+          }
+
+          if (wordMatchCount === 0) return 0;
+          const ratio = wordMatchCount / searchWords.length;
+          // All words matched → high score
+          if (ratio === 1) return allWordsMatched ? 80 : 72;
+          // Partial match: scale 10-58
+          return 10 + Math.round(ratio * 48);
+        }
+
+        // Single-word fallback
+        // Whole-word boundary match
+        try {
+          const wbRegex = new RegExp(
+            `(^|\\s)${normalizedSearchTerm.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(\\s|$)`,
+          );
+          if (wbRegex.test(norm)) return 60;
+        } catch (_) {
+          // ignore regex errors
+        }
+
+        return 0;
+      };
+
+      /**
+       * Combined scorer for a product.
+       * Name scores are weighted heavily; description/category as fallback.
+       */
+      const scoreProduct = (product) => {
+        const nameArScore = scoreField(product.nameAr);
+        const nameEnScore = scoreField(product.nameEn);
+        const nameScore = Math.max(nameArScore, nameEnScore);
+
+        // If we got a solid name match, return it directly
+        if (nameScore >= 60) return nameScore;
+
+        // Check description
+        const descArText = Array.isArray(product.descriptionAr)
+          ? product.descriptionAr.join(' ')
+          : product.descriptionAr || '';
+        const descEnText = Array.isArray(product.descriptionEn)
+          ? product.descriptionEn.join(' ')
+          : product.descriptionEn || '';
+        const descScore = Math.max(
+          scoreField(descArText),
+          scoreField(descEnText),
+        );
+
+        if (descScore > 0)
+          return Math.max(nameScore, Math.round(descScore * 0.4));
+
+        // Matched via category/barcode — keep it low but above 0
+        return nameScore > 0 ? nameScore : 8;
+      };
+
+      // Sort products by score (descending)
+      products = products.sort((a, b) => scoreProduct(b) - scoreProduct(a));
+
+      // Apply manual pagination after scoring (only for search path)
+      if (originalSearchTerm && !hasExplicitSort) {
+        const skip = (page - 1) * limit;
+        products = products.slice(skip, skip + limit);
+      }
+    }
+
+    const totalPages = Math.ceil(totalCount / limit);
+
+    res.status(200).json({
+      status: 'success',
+      results: products.length,
+      totalCount,
+      totalPages,
+      currentPage: page,
+      data: {
+        products,
+      },
+    });
+  } catch (err) {
+    console.error('getAllProducts error:', err);
+    res.status(500).json({
+      status: 'fail',
+      message: 'Error fetching products',
+      error: err.message,
+    });
+  }
+};
+
+// Get search suggestions
+exports.getSuggestions = async (req, res) => {
+  try {
+    const { search } = req.query;
+    if (!search) {
+      return res
+        .status(200)
+        .json({ status: 'success', data: { products: [], categories: [] } });
+    }
+
+    const {
+      createSmartSearchRegex,
+      getSimilarity,
+      convertArabicNumerals,
+    } = require('../utils/arabicSearch');
+
+    const searchTerms = search
+      .split(' ')
+      .map((term) => convertArabicNumerals(term.trim()))
+      .filter((term) => term.length > 0);
+    let productQuery = {};
+    let categoryQuery = {};
+
+    if (searchTerms.length > 0) {
+      const searchConditions = searchTerms.map((term) => {
+        const searchRegex = createSmartSearchRegex(term);
+        return {
+          $or: [{ nameAr: searchRegex }, { nameEn: searchRegex }],
+        };
+      });
+
+      productQuery = { $and: searchConditions };
+      categoryQuery = { $and: searchConditions };
+    }
+
+    // Fetch matching products (fetch more for ranking)
+    let products = await Product.find(productQuery)
+      .select('nameAr nameEn imageCover price slug _id')
+      .limit(100)
+      .lean();
+
+    // Rank products by similarity
+    products = products
+      .map((p) => ({
+        ...p,
+        score: Math.max(
+          getSimilarity(search, p.nameAr),
+          getSimilarity(search, p.nameEn),
+        ),
+      }))
+      .sort((a, b) => b.score - a.score)
+      .slice(0, 5);
+
+    // Fetch matching categories
+    let categories = await Category.find(categoryQuery)
+      .select('nameAr nameEn _id id')
+      .limit(50)
+      .lean();
+
+    // Rank categories by similarity
+    categories = categories
+      .map((c) => ({
+        ...c,
+        score: Math.max(
+          getSimilarity(search, c.nameAr),
+          getSimilarity(search, c.nameEn),
+        ),
+      }))
+      .sort((a, b) => b.score - a.score)
+      .slice(0, 3);
+
+    res.status(200).json({
+      status: 'success',
+      data: {
+        products,
+        categories,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'fail',
+      message: 'Error fetching suggestions',
+    });
+  }
+};
+
+// Voice-based technical search (transcript -> entities -> filters -> ranking)
+exports.voiceSearch = async (req, res) => {
+  try {
+    const { transcript = '', limit = 12 } = req.body || {};
+
+    if (!transcript || !String(transcript).trim()) {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'transcript is required',
+      });
+    }
+
+    const cappedLimit = Math.min(Math.max(Number(limit) || 12, 1), 40);
+
+    const categories = await Category.find({})
+      .select('_id id nameAr nameEn')
+      .lean();
+
+    const extraction = extractVoiceEntities({
+      transcript: String(transcript),
+      categories,
+    });
+
+    const { entities } = extraction;
+
+    const queryEntities = {
+      categoryId: entities.category?.id || null,
+      categoryObjectId: entities.category?.objectId || null,
+      powerType: entities.powerType,
+      voltage: entities.voltage,
+      powerWatts: entities.powerWatts,
+      sizeMm: entities.sizeMm,
+      usage: entities.usage,
+      minPrice: entities.minPrice,
+      maxPrice: entities.maxPrice,
+      keywords: Array.isArray(entities.keywords) ? entities.keywords : [],
+    };
+
+    const mongoQuery = buildMongoVoiceQuery(queryEntities);
+    let candidates = await Product.find(mongoQuery)
+      .populate('category', 'nameAr nameEn _id id')
+      .populate('provider', 'storeName _id')
+      .limit(cappedLimit * 5)
+      .lean();
+
+    // Strong fallback: if no direct results, search broad set with optional price filter.
+    if (candidates.length === 0) {
+      const fallbackQuery = {};
+
+      if (queryEntities.minPrice !== null || queryEntities.maxPrice !== null) {
+        fallbackQuery.price = {};
+        if (queryEntities.minPrice !== null) {
+          fallbackQuery.price.$gte = queryEntities.minPrice;
+        }
+        if (queryEntities.maxPrice !== null) {
+          fallbackQuery.price.$lte = queryEntities.maxPrice;
+        }
+      }
+
+      candidates = await Product.find(fallbackQuery)
+        .populate('category', 'nameAr nameEn _id id')
+        .populate('provider', 'storeName _id')
+        .sort('-createdAt')
+        .limit(cappedLimit * 10)
+        .lean();
+    }
+
+    const rankedProducts = candidates
+      .map((product) => ({
+        ...product,
+        relevanceScore: scoreVoiceProduct(product, queryEntities),
+      }))
+      .sort((a, b) => b.relevanceScore - a.relevanceScore)
+      .slice(0, cappedLimit);
+
+    const cleanedSearchText =
+      buildSearchTextFromEntities(queryEntities) || transcript;
+    const finalSearchText =
+      cleanedSearchText.trim().length > 0 ? cleanedSearchText : transcript;
+
+    const queryParams = {
+      ...buildVoiceFilterQuery(queryEntities),
+      search: finalSearchText,
+    };
+
+    return res.status(200).json({
+      status: 'success',
+      results: rankedProducts.length,
+      data: {
+        transcript,
+        intent: extraction.intent,
+        entities,
+        queryParams,
+        mongoQuery,
+        candidatesFound: candidates.length,
+        products: rankedProducts,
+      },
+    });
+  } catch (err) {
+    console.error('Voice search error:', err.message);
+    return res.status(500).json({
+      status: 'fail',
+      message: 'Error processing voice search',
+    });
+  }
+};
+
+exports.transcribeVoice = async (req, res) => {
+  try {
+    if (!process.env.OPENAI_API_KEY) {
+      return res.status(500).json({
+        status: 'fail',
+        message: 'OPENAI_API_KEY is not configured on the backend',
+      });
+    }
+
+    if (!req.file || !req.file.buffer) {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'audio file is required',
+      });
+    }
+
+    const formData = new FormData();
+    const contentType = req.file.mimetype || 'audio/webm';
+    formData.append('file', req.file.buffer, {
+      filename: req.file.originalname || 'voice.webm',
+      contentType,
+    });
+    formData.append('model', process.env.OPENAI_WHISPER_MODEL || 'whisper-1');
+
+    const language = req.body?.language;
+    if (language) {
+      formData.append('language', String(language).slice(0, 5));
+    }
+
+    const whisperResponse = await axios.post(
+      'https://api.openai.com/v1/audio/transcriptions',
+      formData,
+      {
+        headers: {
+          Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
+          ...formData.getHeaders(),
+        },
+        maxBodyLength: Infinity,
+        timeout: 30000,
+      },
+    );
+
+    const transcript = whisperResponse?.data?.text?.trim() || '';
+
+    return res.status(200).json({
+      status: 'success',
+      data: {
+        transcript,
+      },
+    });
+  } catch (error) {
+    return res.status(500).json({
+      status: 'fail',
+      message: 'Failed to transcribe voice using Whisper API',
+      error:
+        error?.response?.data?.error?.message ||
+        error.message ||
+        'Unknown error',
+    });
+  }
+};
+
+// Get a single product by ID
+exports.getProduct = async (req, res) => {
+  try {
+    const { id } = req.params;
+
+    // Check if the provided ID is a valid MongoDB ObjectId
+    const isObjectId = mongoose.Types.ObjectId.isValid(id);
+
+    let product;
+    if (isObjectId) {
+      product = await Product.findById(id)
+        .populate('category', 'nameAr nameEn _id id')
+        .populate('provider', 'storeName name logo _id')
+        .populate('reviews')
+        .lean();
+    } else {
+      // If not an ObjectId, assume it's a slug
+      product = await Product.findOne({ slug: id })
+        .populate('category', 'nameAr nameEn _id id')
+        .populate('provider', 'storeName name logo _id')
+        .populate('reviews')
+        .lean();
+    }
+
+    if (!product) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'No product found with that ID or slug',
+      });
+    }
+
+    res.status(200).json({
+      status: 'success',
+      data: {
+        product,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'fail',
+      message: err.message,
+    });
+  }
+};
+
+// Create a new product
+exports.createProduct = async (req, res) => {
+  try {
+    const categoryIds = Array.isArray(req.body.category)
+      ? req.body.category
+      : [req.body.category];
+
+    const categories = await Category.find({ _id: { $in: categoryIds } });
+    if (!categories || categories.length === 0) {
+      return res.status(400).json({ message: 'Invalid category ids' });
+    }
+
+    const provider = await Provider.findById(req.body.provider);
+    if (!provider) {
+      return res.status(400).json({ message: 'Invalid provider id' });
+    }
+
+    const productData = {
+      // eslint-disable-next-line node/no-unsupported-features/es-syntax
+      ...req.body,
+      category: categories.map((cat) => cat._id),
+      provider: provider._id,
+    };
+
+    const newProduct = await Product.create(productData);
+
+    // Notify AI service to reload cache
+    triggerAiReload();
+
+    res.status(201).json({
+      status: 'success',
+      data: {
+        product: newProduct,
+      },
+    });
+  } catch (err) {
+    res.status(400).json({
+      status: 'fail',
+      message: err.message,
+    });
+  }
+};
+
+// Update a product
+exports.updateProduct = async (req, res) => {
+  try {
+    const oldProduct = await Product.findById(req.params.id);
+    if (!oldProduct) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'Product not found',
+      });
+    }
+
+    const updatedProduct = await Product.findByIdAndUpdate(
+      req.params.id,
+      req.body,
+      { new: true, runValidators: true },
+    );
+
+    // Check for stock replenish (Back in Stock)
+    if (req.body.stock > 0 && (!oldProduct.stock || oldProduct.stock <= 0)) {
+      notifyPastBuyersProductBackInStock(updatedProduct).catch((err) =>
+        console.error(
+          'Failed to send back-in-stock notification (past buyers):',
+          err.message,
+        ),
+      );
+      notifyStockSubscribers(updatedProduct).catch((err) =>
+        console.error(
+          'Failed to send back-in-stock notification (subscribers):',
+          err.message,
+        ),
+      );
+    }
+
+    // Notify AI service to reload cache (any data change)
+    triggerAiReload();
+
+    res.status(200).json({
+      status: 'success',
+      data: {
+        product: updatedProduct,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'fail',
+      message: err.message,
+    });
+  }
+};
+
+// Delete a product
+const { deleteProductFolder } = require('../config/cloudinary');
+
+// ... (existing imports)
+
+// Delete a product
+exports.deleteProduct = async (req, res) => {
+  try {
+    // Delete product from MongoDB
+    const product = await Product.findByIdAndDelete(req.params.id);
+
+    if (!product) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'No product found with that ID',
+      });
+    }
+
+    // Delete associated images folder from Cloudinary
+    try {
+      await deleteProductFolder(req.params.id);
+    } catch (imageError) {
+      console.error(
+        `Failed to delete images for product ${req.params.id}:`,
+        imageError,
+      );
+      // We don't stop the response here, as the product is already deleted
+    }
+
+    res.status(204).json({
+      status: 'success',
+      data: null,
+    });
+  } catch (err) {
+    res.status(404).json({
+      status: 'fail',
+      message: err.message,
+    });
+  }
+};
+
+// Get product statistics (Admin)
+exports.getProductStats = async (req, res) => {
+  try {
+    const stats = await Product.aggregate([
+      {
+        $facet: {
+          totalProducts: [{ $count: 'count' }],
+          available: [{ $match: { stock: { $gt: 10 } } }, { $count: 'count' }],
+          lowStock: [
+            { $match: { stock: { $gt: 0, $lte: 10 } } },
+            { $count: 'count' },
+          ],
+          outOfStock: [{ $match: { stock: 0 } }, { $count: 'count' }],
+        },
+      },
+    ]);
+
+    const result = {
+      total:
+        stats[0].totalProducts && stats[0].totalProducts[0]
+          ? stats[0].totalProducts[0].count
+          : 0,
+      available:
+        stats[0].available && stats[0].available[0]
+          ? stats[0].available[0].count
+          : 0,
+      lowStock:
+        stats[0].lowStock && stats[0].lowStock[0]
+          ? stats[0].lowStock[0].count
+          : 0,
+      outOfStock:
+        stats[0].outOfStock && stats[0].outOfStock[0]
+          ? stats[0].outOfStock[0].count
+          : 0,
+    };
+
+    res.status(200).json({
+      status: 'success',
+      data: result,
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'fail',
+      message: 'Error fetching product statistics',
+    });
+  }
+};
+
+// Get featured products
+exports.getFeaturedProducts = async (req, res) => {
+  try {
+    const products = await Product.find({ isFeatured: true })
+      .populate('category', 'nameAr _id')
+      .populate('provider', 'storeName _id')
+      .limit(20)
+      .lean(); // Limit to 20 for performance (Home Page Carousel)
+
+    res.status(200).json({
+      status: 'success',
+      results: products.length,
+      data: {
+        products,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'fail',
+      message: 'Error fetching featured products',
+    });
+  }
+};
+
+// Import products from Excel file
+exports.importProducts = async (req, res) => {
+  try {
+    if (!req.file) {
+      return res
+        .status(400)
+        .json({ status: 'fail', message: 'No file uploaded' });
+    }
+
+    const { preview } = req.query;
+    const isPreview = preview === 'true';
+
+    // Read from buffer instead of file path (for Vercel serverless)
+    const workbook = xlsx.read(req.file.buffer, { type: 'buffer' });
+    const sheetName = workbook.SheetNames[0];
+    const worksheet = workbook.Sheets[sheetName];
+    const rows = xlsx.utils.sheet_to_json(worksheet);
+
+    const newProducts = [];
+    const updatedProducts = [];
+    const missingProducts = [];
+    const errors = [];
+
+    // Pre-fetch all needed providers and categories to optimize
+    // However, for simplicity and ensuring exact matches per row logic, we'll keep it loop-based
+    // or we could optimize if performance becomes an issue.
+    const isVendor = req.user.role === 'vendor';
+    let vendorProvider = null;
+
+    if (isVendor) {
+      if (!req.user.provider) {
+        return res.status(400).json({
+          status: 'fail',
+          message: 'Vendor user is not associated with any provider',
+        });
+      }
+      // eslint-disable-next-line no-await-in-loop
+      vendorProvider = await Provider.findById(req.user.provider);
+      if (!vendorProvider) {
+        return res.status(400).json({
+          status: 'fail',
+          message: 'Associated provider not found',
+        });
+      }
+    }
+
+    // Deduplicate rows: if the same barCode+provider combo appears more than once in the
+    // sheet, only the LAST occurrence is processed (later row is the intended final version).
+    const lastOccurrenceMap = new Map();
+    rows.forEach((row, idx) => {
+      const providerKey = isVendor
+        ? '__vendor__'
+        : row.provider
+          ? row.provider.toString().trim()
+          : '';
+      const key = `${(row.barCode || '').toString().trim()}||${providerKey}`;
+      lastOccurrenceMap.set(key, idx);
+    });
+
+    for (const [index, row] of rows.entries()) {
+      try {
+        // Skip rows superseded by a later row with the same barCode+provider combo
+        const dupProviderKey = isVendor
+          ? '__vendor__'
+          : row.provider
+            ? row.provider.toString().trim()
+            : '';
+        const dupKey = `${(row.barCode || '').toString().trim()}||${dupProviderKey}`;
+        if (lastOccurrenceMap.get(dupKey) !== index) {
+          // A later row covers this barCode+provider — skip this one
+          // eslint-disable-next-line no-continue
+          continue;
+        }
+
+        // ── DETECT MODE FIRST ──────────────────────────────────────────────────
+        // A "category-only" sheet has just barCode + category and nothing else.
+        // We must detect this BEFORE provider resolution so we don't block on it.
+        const isCategoryOnlyUpdate =
+          row.barCode &&
+          row.category &&
+          !row.nameAr &&
+          !row.brand &&
+          !row.provider &&
+          !row.price;
+
+        const hasPurchaseOrPrice =
+          row.purchasePrice !== undefined || row.price !== undefined;
+
+        const isPriceOnlyUpdate =
+          row.barCode &&
+          hasPurchaseOrPrice &&
+          !row.nameAr &&
+          !row.nameEn &&
+          !row.brand &&
+          !row.category &&
+          !row.salePrice &&
+          !row.stock &&
+          !row.descriptionAr &&
+          !row.descriptionEn &&
+          !row.imageCover &&
+          !row.images &&
+          !row.isFeatured &&
+          !row.ratingsAverage &&
+          !row.ratingsQuantity;
+
+        const isPriceOnlyMissingRequired =
+          row.barCode &&
+          !hasPurchaseOrPrice &&
+          row.costPrice !== undefined &&
+          !row.nameAr &&
+          !row.nameEn &&
+          !row.brand &&
+          !row.category &&
+          !row.price &&
+          !row.salePrice &&
+          !row.stock &&
+          !row.descriptionAr &&
+          !row.descriptionEn &&
+          !row.imageCover &&
+          !row.images &&
+          !row.isFeatured &&
+          !row.ratingsAverage &&
+          !row.ratingsQuantity;
+
+        const isBroadBarcodeUpdate =
+          !isVendor &&
+          (isCategoryOnlyUpdate || (isPriceOnlyUpdate && !row.provider));
+
+        if (isPriceOnlyMissingRequired) {
+          errors.push({
+            row: index + 2,
+            message:
+              'Price-only update requires purchasePrice or price (costPrice is optional)',
+            name: row.nameAr || 'Unknown',
+          });
+          // eslint-disable-next-line no-continue
+          continue;
+        }
+
+        // 1. Resolve Provider (skipped entirely for category-only updates)
+        let provider = vendorProvider;
+        if (!isVendor && !isCategoryOnlyUpdate) {
+          const pIdentifier = row.provider
+            ? row.provider.toString().trim()
+            : '';
+          let foundProvider = null;
+
+          if (/^\d+$/.test(pIdentifier)) {
+            foundProvider = await Provider.findOne({ id: Number(pIdentifier) });
+          }
+
+          if (!foundProvider && mongoose.Types.ObjectId.isValid(pIdentifier)) {
+            foundProvider = await Provider.findById(pIdentifier);
+          }
+
+          if (!foundProvider) {
+            foundProvider = await Provider.findOne({
+              $or: [{ storeName: pIdentifier }, { name: pIdentifier }],
+            });
+          }
+
+          provider = foundProvider;
+
+          if (!provider) {
+            errors.push({
+              row: index + 2,
+              message: `Invalid provider: ${row.provider}`,
+              name: row.nameAr || 'Unknown',
+            });
+            // eslint-disable-next-line no-continue
+            continue;
+          }
+        }
+
+        // Validation: Required fields only for NEW products or full-row updates
+        // For partial/category-only updates, barcode alone is enough to find the product
+        const hasMissingFields =
+          isCategoryOnlyUpdate || isPriceOnlyUpdate
+            ? false // skip full validation for partial updates
+            : isVendor
+              ? !row.barCode || !row.nameAr || !row.brand || !row.category
+              : !row.barCode ||
+                !row.nameAr ||
+                !row.brand ||
+                !row.category ||
+                !row.provider;
+
+        if (hasMissingFields) {
+          errors.push({
+            row: index + 2,
+            message: isVendor
+              ? 'Missing required fields: Barcode, Name, Brand, or Category'
+              : 'Missing required fields: Barcode, Name, Brand, Category, or Provider',
+          });
+          // eslint-disable-next-line no-continue
+          continue;
+        }
+
+        // Search for existing product(s) by barcode.
+        // For category-only updates: find ALL products with this barcode (across all providers)
+        // For full updates: find by barcode+provider to enforce uniqueness per provider
+        // eslint-disable-next-line no-await-in-loop
+        const existingProducts = isBroadBarcodeUpdate
+          ? await Product.find({ barCode: row.barCode.toString().trim() })
+          : null;
+
+        // eslint-disable-next-line no-await-in-loop
+        const existingProduct = isBroadBarcodeUpdate
+          ? existingProducts && existingProducts.length > 0
+            ? existingProducts[0]
+            : null
+          : await Product.findOne({
+              barCode: row.barCode,
+              provider: provider._id,
+            });
+
+        // (Redundant but safe: If vendor, they only see products for their own provider anyway due to search above)
+        if (
+          existingProduct &&
+          isVendor &&
+          !existingProduct.provider.equals(vendorProvider._id)
+        ) {
+          errors.push({
+            row: index + 2,
+            message:
+              'You do not have permission to update this product (belongs to another provider)',
+            name: row.nameAr,
+          });
+          // eslint-disable-next-line no-continue
+          continue;
+        }
+
+        if (existingProduct) {
+          if (isPriceOnlyUpdate) {
+            const normalizedBarcode = row.barCode.toString().trim();
+            const nextPurchasePrice =
+              row.purchasePrice !== undefined && row.purchasePrice !== null
+                ? Number(row.purchasePrice) || 0
+                : undefined;
+            const nextCostPrice =
+              row.costPrice !== undefined && row.costPrice !== null
+                ? Number(row.costPrice) || 0
+                : undefined;
+            const nextPrice =
+              row.price !== undefined && row.price !== null
+                ? Number(row.price) || 0
+                : undefined;
+
+            if (isPreview) {
+              updatedProducts.push({
+                barCode: normalizedBarcode,
+                changes: {
+                  ...(nextPurchasePrice !== undefined
+                    ? {
+                        purchasePrice: {
+                          old: existingProduct.purchasePrice,
+                          new: nextPurchasePrice,
+                        },
+                      }
+                    : {}),
+                  ...(nextCostPrice !== undefined
+                    ? {
+                        costPrice: {
+                          old: existingProduct.costPrice,
+                          new: nextCostPrice,
+                        },
+                      }
+                    : {}),
+                  ...(nextPrice !== undefined
+                    ? {
+                        price: {
+                          old: existingProduct.price,
+                          new: nextPrice,
+                        },
+                      }
+                    : {}),
+                },
+                providerName:
+                  (provider && provider.storeName) || 'All Providers',
+              });
+            } else {
+              const updateFields = {};
+              if (nextPurchasePrice !== undefined)
+                updateFields.purchasePrice = nextPurchasePrice;
+              if (nextCostPrice !== undefined)
+                updateFields.costPrice = nextCostPrice;
+              if (nextPrice !== undefined) updateFields.price = nextPrice;
+
+              if (isBroadBarcodeUpdate) {
+                // eslint-disable-next-line no-await-in-loop
+                await Product.updateMany(
+                  { barCode: normalizedBarcode },
+                  { $set: updateFields },
+                );
+              } else {
+                // eslint-disable-next-line no-await-in-loop
+                await Product.findByIdAndUpdate(existingProduct._id, {
+                  $set: updateFields,
+                });
+              }
+
+              updatedProducts.push(normalizedBarcode);
+            }
+
+            // eslint-disable-next-line no-continue
+            continue;
+          }
+
+          // EXISTING PRODUCT: Update all fields
+          // SMART CATEGORY RESOLUTION
+          const rawCategoryValue = (row.category || '').toString().trim();
+          const categoryIdentifiers = rawCategoryValue
+            ? [
+                ...new Set(
+                  rawCategoryValue
+                    .split(',')
+                    .map((val) => val.trim())
+                    .filter(Boolean),
+                ),
+              ]
+            : [];
+
+          const categoryObjectIds = [];
+          const categoryNamesForPreview = [];
+
+          for (const identifier of categoryIdentifiers) {
+            let foundCategory = null;
+
+            // 1. Try Numeric ID
+            if (/^\d+$/.test(identifier)) {
+              foundCategory = await Category.findOne({
+                id: Number(identifier),
+              });
+            }
+
+            // 2. Try ObjectId
+            if (!foundCategory && mongoose.Types.ObjectId.isValid(identifier)) {
+              foundCategory = await Category.findById(identifier);
+            }
+
+            // 3. Try Name (Ar/En) or Slug
+            if (!foundCategory) {
+              foundCategory = await Category.findOne({
+                $or: [
+                  { nameAr: identifier },
+                  { nameEn: identifier },
+                  { slug: identifier },
+                ],
+              });
+            }
+
+            if (foundCategory) {
+              categoryObjectIds.push(foundCategory._id);
+              categoryNamesForPreview.push(foundCategory.nameAr);
+            }
+          }
+
+          // Validation: Ensure at least one category is found
+          if (
+            categoryIdentifiers.length > 0 &&
+            categoryObjectIds.length === 0
+          ) {
+            errors.push({
+              row: index + 2,
+              message: `None of the provided category identifiers were found: ${row.category}`,
+              name: row.nameAr,
+            });
+            // eslint-disable-next-line no-continue
+            continue;
+          }
+
+          // SMART BRAND RESOLUTION
+          let brandName = row.brand;
+          if (row.brand) {
+            let foundBrand = null;
+            const bIdentifier = row.brand.toString().trim();
+
+            if (/^\d+$/.test(bIdentifier)) {
+              foundBrand = await Brand.findOne({ id: Number(bIdentifier) });
+            }
+
+            if (!foundBrand && mongoose.Types.ObjectId.isValid(bIdentifier)) {
+              foundBrand = await Brand.findById(bIdentifier);
+            }
+
+            if (!foundBrand) {
+              foundBrand = await Brand.findOne({
+                $or: [
+                  { nameEn: bIdentifier },
+                  { nameAr: bIdentifier },
+                  { slug: bIdentifier },
+                ],
+              });
+            }
+
+            if (foundBrand) brandName = foundBrand.nameEn;
+          }
+
+          // Handle Image Uploads to Cloudinary (ONLY if not preview)
+          let finalImageCover = row.imageCover || existingProduct.imageCover;
+          let finalImages = row.images
+            ? row.images.split(',')
+            : existingProduct.images || [];
+
+          if (!isPreview) {
+            if (row.imageCover) {
+              // eslint-disable-next-line no-await-in-loop
+              finalImageCover = await uploadExternalImage(
+                row.imageCover,
+                existingProduct._id,
+                true,
+              );
+            }
+
+            if (row.images) {
+              const imgArray = row.images.split(',');
+              // eslint-disable-next-line no-await-in-loop
+              finalImages = await Promise.all(
+                imgArray.map((img) =>
+                  uploadExternalImage(img.trim(), existingProduct._id, false),
+                ),
+              );
+
+              finalImages = finalImages.filter(Boolean);
+
+              // Delete any old extra images that are no longer in the updated list
+              if (finalImages.length > 0) {
+                const oldImages = existingProduct.images || [];
+                for (const oldImg of oldImages) {
+                  if (oldImg && !finalImages.includes(oldImg)) {
+                    // eslint-disable-next-line no-await-in-loop
+                    await deleteCloudinaryImage(oldImg);
+                  }
+                }
+              }
+            }
+
+            // Keep updates resilient: use first valid gallery image, otherwise keep old cover.
+            if (!finalImageCover && finalImages.length > 0) {
+              [finalImageCover] = finalImages;
+            }
+            if (!finalImageCover) {
+              // eslint-disable-next-line no-await-in-loop
+              const existingCoverIsReachable = await isImageUrlReachable(
+                existingProduct.imageCover,
+              );
+              finalImageCover = existingCoverIsReachable
+                ? existingProduct.imageCover
+                : IMPORT_FALLBACK_COVER_IMAGE;
+            }
+
+            // If cover changed, cleanup old cover on our Cloudinary cloud.
+            if (
+              finalImageCover &&
+              existingProduct.imageCover &&
+              existingProduct.imageCover !== finalImageCover
+            ) {
+              // eslint-disable-next-line no-await-in-loop
+              await deleteCloudinaryImage(existingProduct.imageCover);
+            }
+          }
+
+          // PARTIAL UPDATE: Only include fields that are present in the Excel row
+          const updateData = {};
+
+          // Category is always updated when provided (required for category-only mode)
+          if (categoryObjectIds.length > 0)
+            updateData.category = categoryObjectIds;
+
+          // Only update other fields if they are actually present in the row
+          if (
+            row.nameEn !== undefined &&
+            row.nameEn !== null &&
+            row.nameEn !== ''
+          )
+            updateData.nameEn = row.nameEn;
+          if (
+            row.nameAr !== undefined &&
+            row.nameAr !== null &&
+            row.nameAr !== ''
+          )
+            updateData.nameAr = row.nameAr;
+          if (row.descriptionEn)
+            updateData.descriptionEn = row.descriptionEn.split(',');
+          if (row.descriptionAr)
+            updateData.descriptionAr = row.descriptionAr.split(',');
+          if (brandName && row.brand) updateData.brand = brandName;
+          if (provider) updateData.provider = provider._id;
+          if (row.stock !== undefined && row.stock !== null && row.stock !== '')
+            updateData.stock = Number(row.stock) || 0;
+          if (
+            row.isFeatured !== undefined &&
+            row.isFeatured !== null &&
+            row.isFeatured !== ''
+          )
+            updateData.isFeatured = Boolean(Number(row.isFeatured));
+          if (row.price !== undefined && row.price !== null && row.price !== '')
+            updateData.price = Number(row.price) || 0;
+          if (
+            row.purchasePrice !== undefined &&
+            row.purchasePrice !== null &&
+            row.purchasePrice !== ''
+          )
+            updateData.purchasePrice = Number(row.purchasePrice) || 0;
+          if (
+            row.salePrice !== undefined &&
+            row.salePrice !== null &&
+            row.salePrice !== ''
+          )
+            updateData.salePrice = Number(row.salePrice) || 0;
+          if (row.ratingsAverage !== undefined && row.ratingsAverage !== '')
+            updateData.ratingsAverage = Number(row.ratingsAverage) || 0;
+          if (row.ratingsQuantity !== undefined && row.ratingsQuantity !== '')
+            updateData.ratingsQuantity = Number(row.ratingsQuantity) || 0;
+          if (finalImageCover) updateData.imageCover = finalImageCover;
+          if (finalImages && finalImages.length > 0)
+            updateData.images = finalImages;
+
+          if (isPreview) {
+            // Calculate changes for preview — only show fields that are actually in updateData
+            const changes = {};
+            if (
+              'nameAr' in updateData &&
+              existingProduct.nameAr !== updateData.nameAr
+            )
+              changes.nameAr = {
+                old: existingProduct.nameAr,
+                new: updateData.nameAr,
+              };
+            if (
+              'nameEn' in updateData &&
+              existingProduct.nameEn !== updateData.nameEn
+            )
+              changes.nameEn = {
+                old: existingProduct.nameEn,
+                new: updateData.nameEn,
+              };
+            if (
+              'price' in updateData &&
+              existingProduct.price !== updateData.price
+            )
+              changes.price = {
+                old: existingProduct.price,
+                new: updateData.price,
+              };
+            if (
+              'purchasePrice' in updateData &&
+              existingProduct.purchasePrice !== updateData.purchasePrice
+            )
+              changes.purchasePrice = {
+                old: existingProduct.purchasePrice,
+                new: updateData.purchasePrice,
+              };
+            if (
+              'salePrice' in updateData &&
+              existingProduct.salePrice !== updateData.salePrice
+            )
+              changes.salePrice = {
+                old: existingProduct.salePrice,
+                new: updateData.salePrice,
+              };
+            if (
+              'stock' in updateData &&
+              existingProduct.stock !== updateData.stock
+            )
+              changes.stock = {
+                old: existingProduct.stock,
+                new: updateData.stock,
+              };
+            if (
+              'brand' in updateData &&
+              existingProduct.brand !== updateData.brand
+            )
+              changes.brand = {
+                old: existingProduct.brand,
+                new: updateData.brand,
+              };
+            if ('category' in updateData)
+              changes.category = {
+                old: '(previous)',
+                new: categoryNamesForPreview.join(', '),
+              };
+
+            updatedProducts.push({
+              nameAr: updateData.nameAr || existingProduct.nameAr,
+              barCode: row.barCode,
+              changes,
+              categoryNames: categoryNamesForPreview.join(', '),
+              providerName: (provider && provider.storeName) || 'All Providers',
+            });
+          } else if (isCategoryOnlyUpdate) {
+            // CATEGORY-ONLY: update ALL products with this barcode across all providers
+            // eslint-disable-next-line no-await-in-loop
+            await Product.updateMany(
+              { barCode: row.barCode.toString().trim() },
+              { $set: { category: categoryObjectIds } },
+            );
+            updatedProducts.push(row.barCode);
+          } else {
+            // Update single product (full update path)
+            // eslint-disable-next-line no-await-in-loop
+            const updatedProd = await Product.findByIdAndUpdate(
+              existingProduct._id,
+              { $set: updateData },
+              { new: true },
+            );
+
+            // Check if restocked
+            if (
+              updateData.stock > 0 &&
+              (!existingProduct.stock || existingProduct.stock <= 0)
+            ) {
+              notifyPastBuyersProductBackInStock(updatedProd).catch((err) =>
+                console.error(
+                  'Failed to send back-in-stock notification during import:',
+                  err.message,
+                ),
+              );
+            }
+
+            updatedProducts.push(existingProduct.barCode);
+          }
+        } else {
+          if (isPriceOnlyUpdate) {
+            missingProducts.push({
+              row: index + 2,
+              barCode: row.barCode.toString().trim(),
+              provider: row.provider ? row.provider.toString().trim() : '',
+              purchasePrice:
+                row.purchasePrice !== undefined && row.purchasePrice !== null
+                  ? Number(row.purchasePrice) || 0
+                  : undefined,
+              costPrice:
+                row.costPrice !== undefined && row.costPrice !== null
+                  ? Number(row.costPrice) || 0
+                  : undefined,
+              price:
+                row.price !== undefined && row.price !== null
+                  ? Number(row.price) || 0
+                  : undefined,
+            });
+            // eslint-disable-next-line no-continue
+            continue;
+          }
+
+          // NEW PRODUCT: Create
+          // SMART CATEGORY RESOLUTION (NEW PRODUCT)
+          const rawCategoryValueNew = (row.category || '').toString().trim();
+          const categoryIdentifiersNew = rawCategoryValueNew
+            ? [
+                ...new Set(
+                  rawCategoryValueNew
+                    .split(',')
+                    .map((val) => val.trim())
+                    .filter(Boolean),
+                ),
+              ]
+            : [];
+
+          const categoryObjectIdsNew = [];
+          const categoryNamesForPreviewNew = [];
+
+          for (const identifier of categoryIdentifiersNew) {
+            let foundCategory = null;
+
+            if (/^\d+$/.test(identifier)) {
+              foundCategory = await Category.findOne({
+                id: Number(identifier),
+              });
+            }
+
+            if (!foundCategory && mongoose.Types.ObjectId.isValid(identifier)) {
+              foundCategory = await Category.findById(identifier);
+            }
+
+            if (!foundCategory) {
+              foundCategory = await Category.findOne({
+                $or: [
+                  { nameAr: identifier },
+                  { nameEn: identifier },
+                  { slug: identifier },
+                ],
+              });
+            }
+
+            if (foundCategory) {
+              categoryObjectIdsNew.push(foundCategory._id);
+              categoryNamesForPreviewNew.push(foundCategory.nameAr);
+            }
+          }
+
+          if (
+            categoryIdentifiersNew.length > 0 &&
+            categoryObjectIdsNew.length === 0
+          ) {
+            errors.push({
+              row: index + 2,
+              message: `None of the provided category identifiers were found: ${row.category}`,
+              name: row.nameAr,
+            });
+            // eslint-disable-next-line no-continue
+            continue;
+          }
+
+          // SMART BRAND RESOLUTION (NEW PRODUCT)
+          let brandNameForNew = row.brand;
+          if (row.brand) {
+            let foundBrand = null;
+            const bIdentifier = row.brand.toString().trim();
+
+            if (/^\d+$/.test(bIdentifier)) {
+              foundBrand = await Brand.findOne({ id: Number(bIdentifier) });
+            }
+
+            if (!foundBrand && mongoose.Types.ObjectId.isValid(bIdentifier)) {
+              foundBrand = await Brand.findById(bIdentifier);
+            }
+
+            if (!foundBrand) {
+              foundBrand = await Brand.findOne({
+                $or: [
+                  { nameEn: bIdentifier },
+                  { nameAr: bIdentifier },
+                  { slug: bIdentifier },
+                ],
+              });
+            }
+
+            if (foundBrand) brandNameForNew = foundBrand.nameEn;
+          }
+
+          // Generate potential ID for new product to use in folder name
+          const newProductId = new mongoose.Types.ObjectId();
+
+          // Handle Image Uploads to Cloudinary (ONLY if not preview)
+          let finalImageCoverNew = row.imageCover;
+          let finalImagesNew = row.images ? row.images.split(',') : [];
+
+          if (!isPreview) {
+            if (row.imageCover) {
+              // eslint-disable-next-line no-await-in-loop
+              finalImageCoverNew = await uploadExternalImage(
+                row.imageCover,
+                newProductId,
+                true,
+              );
+            }
+
+            if (row.images) {
+              const imgArray = row.images.split(',');
+              // eslint-disable-next-line no-await-in-loop
+              finalImagesNew = await Promise.all(
+                imgArray.map((img) =>
+                  uploadExternalImage(img.trim(), newProductId, false),
+                ),
+              );
+            }
+
+            // Ensure new products always have a valid cover image to satisfy schema validation.
+            finalImagesNew = finalImagesNew.filter(Boolean);
+            if (!finalImageCoverNew && finalImagesNew.length > 0) {
+              [finalImageCoverNew] = finalImagesNew;
+            }
+            if (!finalImageCoverNew) {
+              finalImageCoverNew = IMPORT_FALLBACK_COVER_IMAGE;
+            }
+          }
+
+          const productData = {
+            _id: newProductId,
+            nameEn: row.nameEn,
+            nameAr: row.nameAr,
+            descriptionEn: row.descriptionEn
+              ? row.descriptionEn.split(',')
+              : [],
+            descriptionAr: row.descriptionAr
+              ? row.descriptionAr.split(',')
+              : [],
+            barCode: row.barCode,
+            brand: brandNameForNew,
+            category: categoryObjectIdsNew,
+            provider: provider._id,
+            stock: Number(row.stock) || 0,
+            isFeatured: Boolean(Number(row.isFeatured)),
+            price: Number(row.price) || 0,
+            purchasePrice: Number(row.purchasePrice) || 0,
+            salePrice: Number(row.salePrice) || 0,
+            ratingsAverage: Number(row.ratingsAverage) || 0,
+            ratingsQuantity: Number(row.ratingsQuantity) || 0,
+            imageCover: finalImageCoverNew,
+            images: finalImagesNew,
+          };
+
+          if (isPreview) {
+            newProducts.push({
+              ...productData,
+              categoryNames: categoryNamesForPreviewNew.join(', '),
+              providerName: provider.storeName,
+            });
+          } else {
+            // eslint-disable-next-line no-await-in-loop
+            await Product.create(productData);
+            newProducts.push(row.barCode);
+          }
+        }
+      } catch (err) {
+        errors.push({
+          row: index + 2,
+          message: err.message,
+          name: row.nameAr || 'Unknown',
+        });
+      }
+    }
+
+    // No file cleanup needed - using memory storage
+
+    const { missingExport } = req.query;
+    const shouldExportMissing =
+      missingExport === 'true' && missingProducts.length > 0;
+
+    if (shouldExportMissing) {
+      const templateRows = missingProducts.map((item) => ({
+        barCode: item.barCode || '',
+        provider: item.provider || '',
+        purchasePrice:
+          item.purchasePrice !== undefined ? item.purchasePrice : '',
+        costPrice: item.costPrice !== undefined ? item.costPrice : '',
+        price: item.price !== undefined ? item.price : '',
+        nameAr: '',
+        nameEn: '',
+        brand: '',
+        category: '',
+        stock: '',
+        imageCover: '',
+        images: '',
+      }));
+
+      const workbook = xlsx.utils.book_new();
+      const worksheet = xlsx.utils.json_to_sheet(templateRows);
+      xlsx.utils.book_append_sheet(workbook, worksheet, 'MissingProducts');
+
+      const buffer = xlsx.write(workbook, { type: 'buffer', bookType: 'xlsx' });
+
+      res.setHeader(
+        'Content-Type',
+        'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+      );
+      res.setHeader(
+        'Content-Disposition',
+        `attachment; filename=missing-products-${Date.now()}.xlsx`,
+      );
+
+      res.send(buffer);
+      return;
+    }
+
+    res.status(200).json({
+      status: 'success',
+      mode: isPreview ? 'preview' : 'execute',
+      summary: {
+        newCount: newProducts.length,
+        updatedCount: updatedProducts.length,
+        missingCount: missingProducts.length,
+        errorsCount: errors.length,
+      },
+      data: {
+        newProducts,
+        updatedProducts,
+        missingProducts,
+        errors,
+      },
+    });
+
+    // Notify AI service to reload cache after batch import
+    if (!isPreview && (newProducts.length > 0 || updatedProducts.length > 0)) {
+      triggerAiReload();
+    }
+  } catch (error) {
+    // No file cleanup needed - using memory storage
+
+    console.error(error);
+    res.status(500).json({
+      status: 'error',
+      message: 'Something went wrong',
+      error: error.message,
+    });
+  }
+};
+
+// Export products to Excel file
+exports.exportProducts = async (req, res) => {
+  try {
+    const isVendor = req.user.role === 'vendor';
+    const query = {};
+
+    if (isVendor) {
+      if (!req.user.provider) {
+        return res.status(400).json({
+          status: 'fail',
+          message: 'Vendor user is not associated with any provider',
+        });
+      }
+      query.provider = req.user.provider;
+    }
+
+    // Add category filter if provided
+    if (req.query.category) {
+      query.category = req.query.category;
+    }
+
+    // Add brand filter if provided
+    if (req.query.brand) {
+      query.brand = req.query.brand;
+    }
+
+    // Fetch products with populated category and provider
+    const products = await Product.find(query)
+      .populate('category', 'id nameAr nameEn')
+      .populate('provider', 'id storeName');
+
+    // Prepare data for Excel
+    const excelData = products.map((product) => ({
+      nameEn: product.nameEn || '',
+      nameAr: product.nameAr || '',
+      descriptionEn: product.descriptionEn
+        ? product.descriptionEn.join(',')
+        : '',
+      descriptionAr: product.descriptionAr
+        ? product.descriptionAr.join(',')
+        : '',
+      barCode: product.barCode || '',
+      brand:
+        typeof product.brand === 'string' &&
+        /^[0-9a-fA-F]{24}$/.test(product.brand)
+          ? product.brand
+          : product.brand || '',
+      category:
+        product.category && product.category.length > 0
+          ? product.category.map((cat) => cat.id).join(',')
+          : '',
+      provider: product.provider ? product.provider.id : '',
+      stock: product.stock || 0,
+      isFeatured: product.isFeatured ? 1 : 0,
+      price: product.price || 0,
+      purchasePrice: product.purchasePrice || 0,
+      salePrice: product.salePrice || 0,
+      ratingsAverage: product.ratingsAverage || 0,
+      ratingsQuantity: product.ratingsQuantity || 0,
+      imageCover: product.imageCover || '',
+      images:
+        product.images && product.images.length > 0
+          ? product.images.join(',')
+          : '',
+    }));
+
+    // Create workbook and worksheet
+    const workbook = xlsx.utils.book_new();
+    const worksheet = xlsx.utils.json_to_sheet(excelData);
+
+    // Add worksheet to workbook
+    xlsx.utils.book_append_sheet(workbook, worksheet, 'Products');
+
+    // Generate buffer
+    const buffer = xlsx.write(workbook, { type: 'buffer', bookType: 'xlsx' });
+
+    // Set headers for file download
+    res.setHeader(
+      'Content-Type',
+      'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    );
+    res.setHeader(
+      'Content-Disposition',
+      `attachment; filename=products-export-${Date.now()}.xlsx`,
+    );
+
+    // Send file
+    res.send(buffer);
+  } catch (error) {
+    console.error('Export error:', error);
+    res.status(500).json({
+      status: 'error',
+      message: 'Failed to export products',
+      error: error.message,
+    });
+  }
+};
+
+// Generate Facebook Product Catalog XML Feed
+exports.getFacebookCatalog = async (req, res) => {
+  try {
+    // 1. Fetch products (limit to in-stock or all? Facebook usually wants all with availability status)
+    const products = await Product.find()
+      .populate('category', 'nameAr nameEn')
+      .populate('brand', 'nameEn nameAr')
+      .limit(2000); // Increased limit for Meta catalog
+
+    // 2. Format as RSS 2.0 (Facebook XML standard)
+    const frontendUrl = (
+      process.env.FRONTEND_URL || 'https://www.samoulla.com'
+    ).replace(/\/$/, '');
+
+    let xml = `<?xml version="1.0"?>
+<rss xmlns:g="http://base.google.com/ns/1.0" version="2.0">
+  <channel>
+    <title>Samoulla Product Catalog</title>
+    <link>${frontendUrl}</link>
+    <description>Quality tools, hardware, and equipment from Samoulla</description>`;
+
+    products.forEach((product) => {
+      const id = product._id.toString();
+      const title = (product.nameEn || product.nameAr || '').replace(
+        /[&<>"']/g,
+        (m) =>
+          ({
+            '&': '&amp;',
+            '<': '&lt;',
+            '>': '&gt;',
+            '"': '&quot;',
+            "'": '&apos;',
+          })[m],
+      );
+      const description = (
+        (product.descriptionEn && product.descriptionEn[0]) ||
+        (product.descriptionAr && product.descriptionAr[0]) ||
+        title
+      ).replace(
+        /[&<>"']/g,
+        (m) =>
+          ({
+            '&': '&amp;',
+            '<': '&lt;',
+            '>': '&gt;',
+            '"': '&quot;',
+            "'": '&apos;',
+          })[m],
+      );
+      const link = `${frontendUrl}/product/${product.slug || id}`;
+      const imageLink = product.imageCover || '';
+      const price = `${product.price} EGP`;
+      const availability = product.stock > 0 ? 'in stock' : 'out of stock';
+      const brand = (product.brand || 'Samoulla').replace(
+        /[&<>"']/g,
+        (m) =>
+          ({
+            '&': '&amp;',
+            '<': '&lt;',
+            '>': '&gt;',
+            '"': '&quot;',
+            "'": '&apos;',
+          })[m],
+      );
+      const categoryName =
+        (product.category &&
+          product.category[0] &&
+          product.category[0].nameEn) ||
+        'Tools & Equipment';
+      const category = categoryName.replace(
+        /[&<>"']/g,
+        (m) =>
+          ({
+            '&': '&amp;',
+            '<': '&lt;',
+            '>': '&gt;',
+            '"': '&quot;',
+            "'": '&apos;',
+          })[m],
+      );
+
+      xml += `
+    <item>
+      <g:id>${id}</g:id>
+      <g:title>${title}</g:title>
+      <g:description>${description}</g:description>
+      <g:link>${link}</g:link>
+      <g:image_link>${imageLink}</g:image_link>
+      <g:condition>new</g:condition>
+      <g:availability>${availability}</g:availability>
+      <g:price>${price}</g:price>
+      <g:brand>${brand}</g:brand>
+      <g:google_product_category>${category}</g:google_product_category>
+    </item>`;
+    });
+
+    xml += `
+  </channel>
+</rss>`;
+
+    // 3. Send response with XML header
+    res.set('Content-Type', 'text/xml');
+    res.status(200).send(xml);
+  } catch (error) {
+    console.error('Facebook Catalog Error:', error);
+    res.status(500).json({
+      status: 'error',
+      message: 'Failed to generate catalog',
+    });
+  }
+};

controllers/promoController.js

@@ -0,0 +1,225 @@
+const Promo = require('../models/promoCodeModel');
+const Order = require('../models/orderModel');
+
+exports.createPromo = async (req, res) => {
+  try {
+    const data = req.body;
+    if (data.code) data.code = String(data.code).trim().toUpperCase();
+    if (data.categoryId === '') data.categoryId = null;
+    const promo = await Promo.create(data);
+    res.status(201).json({
+      status: 'success',
+      data: { promo },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: err.message,
+    });
+  }
+};
+
+exports.getPromos = async (req, res) => {
+  try {
+    const promos = await Promo.find().sort({ createdAt: -1 }).limit(200);
+    res.status(200).json({
+      status: 'success',
+      results: promos.length,
+      data: { promos },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: err.message,
+    });
+  }
+};
+
+exports.getPromo = async (req, res) => {
+  try {
+    const promo = await Promo.findById(req.params.id);
+    if (!promo)
+      return res
+        .status(404)
+        .json({ status: 'fail', message: 'Promo not found' });
+    res.status(200).json({
+      status: 'success',
+      data: { promo },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: err.message,
+    });
+  }
+};
+
+exports.updatePromo = async (req, res) => {
+  try {
+    const data = req.body;
+    if (data.code) data.code = String(data.code).trim().toUpperCase();
+    if (data.categoryId === '') data.categoryId = null;
+    const promo = await Promo.findByIdAndUpdate(req.params.id, data, {
+      new: true,
+      runValidators: true,
+    });
+    if (!promo)
+      return res
+        .status(404)
+        .json({ status: 'fail', message: 'Promo not found' });
+    res.status(200).json({
+      status: 'success',
+      data: { promo },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: err.message,
+    });
+  }
+};
+
+exports.deletePromo = async (req, res) => {
+  try {
+    const promo = await Promo.findByIdAndDelete(req.params.id);
+    if (!promo)
+      return res
+        .status(404)
+        .json({ status: 'fail', message: 'Promo not found' });
+    res.status(204).json({
+      status: 'success',
+      data: null,
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: err.message,
+    });
+  }
+};
+const computeDiscountAmount = (type, value, base) => {
+  const numericBase = Number(base) || 0;
+  const numericValue = Number(value) || 0;
+  if (type === 'shipping') return 0; // Shipping discount doesn't affect subtotal
+  if (type === 'percentage' || type === 'welcome')
+    return Math.max(0, (numericBase * numericValue) / 100);
+  return Math.max(0, numericValue);
+};
+
+exports.validatePromo = async (req, res) => {
+  try {
+    const { promoCode, subtotal, items } = req.body || {};
+    const base = Number(subtotal) || 0;
+    const cartItems = Array.isArray(items) ? items : [];
+    if (!promoCode)
+      return res.status(200).json({
+        status: 'success',
+        data: { code: null, discountedTotal: base },
+      });
+
+    const upper = String(promoCode).trim().toUpperCase();
+    const now = new Date();
+
+    const promo = await Promo.findOne({ code: upper });
+
+    if (!promo) {
+      return res.status(200).json({
+        status: 'fail',
+        message: 'كود الخصم غير موجود',
+      });
+    }
+
+    if (!promo.active) {
+      return res.status(200).json({
+        status: 'fail',
+        message: 'كود الخصم هذا غير مفعّل حالياً',
+      });
+    }
+
+    if (promo.startsAt && promo.startsAt > now) {
+      return res.status(200).json({
+        status: 'fail',
+        message: 'كود الخصم لم يبدأ مفعوله بعد',
+      });
+    }
+
+    if (promo.expiresAt && promo.expiresAt < now) {
+      return res.status(200).json({
+        status: 'fail',
+        message: 'انتهت صلاحية كود الخصم هذا',
+      });
+    }
+
+    if (promo.minOrderValue > base) {
+      return res.status(200).json({
+        status: 'fail',
+        message: `يجب أن تكون قيمة الطلب ${promo.minOrderValue} جنيه على الأقل لاستخدام هذا الكود`,
+      });
+    }
+
+    // Check usage limits if needed
+    if (promo.usageLimit !== null && promo.usedCount >= promo.usageLimit) {
+      return res.status(200).json({
+        status: 'fail',
+        message: 'تم استهلاك الحد الأقصى لاستخدام كود الخصم هذا',
+      });
+    }
+
+    // Check per-user limit
+    if (req.user && promo.perUserLimit !== null) {
+      const userUsageCount = await Order.countDocuments({
+        user: req.user._id,
+        promoCode: upper,
+        orderStatus: { $ne: 'cancelled' }, // Count everything except cancelled
+      });
+
+      if (userUsageCount >= promo.perUserLimit) {
+        return res.status(200).json({
+          status: 'fail',
+          message: `لقد استنفدت الحد الأقصى لاستخدام هذا الكود (${promo.perUserLimit} مرات)`,
+        });
+      }
+    }
+
+    // Determine eligible base for discount calculation
+    let eligibleBase = base;
+    if (promo.canBeUsedWithSaleItems === false && cartItems.length > 0) {
+      eligibleBase = cartItems.reduce((sum, item) => {
+        // If product is NOT on sale, it is eligible
+        if (!item.isOnSale) {
+          return sum + Number(item.price) * Number(item.quantity);
+        }
+        return sum;
+      }, 0);
+
+      // If no eligible items and it's not a shipping discount, return error
+      if (eligibleBase <= 0 && promo.type !== 'shipping') {
+        return res.status(200).json({
+          status: 'fail',
+          message: 'كود الخصم هذا لا يمكن استخدامه مع المنتجات المخفضة',
+        });
+      }
+    }
+
+    const discount = computeDiscountAmount(
+      promo.type,
+      promo.value,
+      eligibleBase,
+    );
+    const discounted = Math.max(0, base - discount);
+
+    return res.status(200).json({
+      status: 'success',
+      data: {
+        code: promo.code,
+        discountType: promo.type,
+        discountValue: promo.value,
+        discountedTotal: discounted,
+        isFreeShipping: promo.type === 'shipping',
+        expiresAt: promo.expiresAt,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({ status: 'error', message: err.message });
+  }
+};

controllers/providerController.js

@@ -0,0 +1,317 @@
+const Provider = require('../models/providerModel');
+const User = require('../models/userModel');
+const Product = require('../models/productModel');
+const Order = require('../models/orderModel');
+const { deleteImage, getPublicIdFromUrl } = require('../config/cloudinary');
+
+// Get all providers
+exports.getAllProviders = async (req, res) => {
+  try {
+    const providers = await Provider.find().populate('user', 'email');
+
+    // Calculate stats for each provider
+    const providersWithStats = await Promise.all(
+      providers.map(async (provider) => {
+        const providerData = provider.toObject();
+
+        // Add email from user
+        if (provider.user) {
+          providerData.email = provider.user.email;
+        }
+
+        // Count total products for this provider
+        const totalProducts = await Product.countDocuments({
+          provider: provider._id,
+        });
+
+        // Get all products for this provider
+        const products = await Product.find({ provider: provider._id }).select(
+          '_id',
+        );
+        const productIds = products.map((p) => p._id);
+
+        // Calculate total sales and order count from COMPLETED orders only
+        const orders = await Order.find({
+          'items.product': { $in: productIds },
+          orderStatus: 'completed', // Only count delivered orders
+        });
+
+        let totalSales = 0;
+        const orderSet = new Set();
+
+        orders.forEach((order) => {
+          orderSet.add(order._id.toString());
+          // Sum up sales for this provider's products in each order
+          order.items.forEach((item) => {
+            if (productIds.some((id) => id.equals(item.product))) {
+              totalSales += item.quantity * item.unitPrice;
+            }
+          });
+        });
+
+        providerData.totalProducts = totalProducts;
+        providerData.totalSales = totalSales;
+        providerData.orderCount = orderSet.size;
+
+        return providerData;
+      }),
+    );
+
+    res.status(200).json({
+      status: 'success',
+      results: providersWithStats.length,
+      data: {
+        providers: providersWithStats,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'fail',
+      message: err.message,
+    });
+  }
+};
+
+// Get single provider
+exports.getProvider = async (req, res) => {
+  try {
+    const provider = await Provider.findById(req.params.id).populate(
+      'user',
+      'email',
+    );
+    if (!provider) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'No provider found with that ID',
+      });
+    }
+
+    // Include email from user in response
+    const providerData = provider.toObject();
+    if (provider.user) {
+      providerData.email = provider.user.email;
+    }
+
+    res.status(200).json({
+      status: 'success',
+      data: { provider: providerData },
+    });
+  } catch (err) {
+    res.status(400).json({
+      status: 'fail',
+      message: err.message,
+    });
+  }
+};
+
+// Create a new provider
+exports.createProvider = async (req, res) => {
+  try {
+    const { email, password, name, storeName, phoneNumber, address } = req.body;
+
+    // 1. Check if email or phone already exists in User collection
+    const existingUser = await User.findOne({
+      $or: [{ email }, { phone: phoneNumber }],
+    });
+    if (existingUser) {
+      const field =
+        existingUser.email === email ? 'البريد الإلكتروني' : 'رقم الهاتف';
+      return res.status(400).json({
+        status: 'fail',
+        message: `${field} مسجل بالفعل لمستخدم آخر`,
+      });
+    }
+
+    // 2. Get next provider ID
+    const lastProvider = await Provider.findOne().sort({ id: -1 });
+    const nextId = lastProvider ? lastProvider.id + 1 : 1;
+
+    const providerData = {
+      name,
+      storeName,
+      phoneNumber,
+      address,
+      id: nextId,
+    };
+
+    if (req.file) {
+      providerData.logo = req.file.path;
+    }
+
+    // 3. Create Provider document first
+    let newProvider;
+    try {
+      newProvider = await Provider.create(providerData);
+    } catch (err) {
+      if (err.code === 11000) {
+        const field = Object.keys(err.keyPattern)[0];
+        const message =
+          field === 'storeName'
+            ? 'اسم المتجر مسجل بالفعل'
+            : 'رقم الهاتف مسجل بالفعل في قائمة الموردين';
+        return res.status(400).json({ status: 'fail', message });
+      }
+      throw err;
+    }
+
+    // 4. Create User account for vendor
+    try {
+      const vendorUser = await User.create({
+        name,
+        email,
+        phone: phoneNumber,
+        password,
+        role: 'vendor',
+        provider: newProvider._id,
+      });
+
+      // 5. Update provider with user reference
+      newProvider.user = vendorUser._id;
+      await newProvider.save();
+
+      res.status(201).json({
+        status: 'success',
+        data: { provider: newProvider },
+      });
+    } catch (err) {
+      // Rollback: Delete the created provider if user creation fails
+      await Provider.findByIdAndDelete(newProvider._id);
+      throw err;
+    }
+  } catch (err) {
+    res.status(400).json({
+      status: 'fail',
+      message: err.message,
+    });
+  }
+};
+
+// Update a provider
+exports.updateProvider = async (req, res) => {
+  try {
+    const providerId = req.params.id;
+    const oldProvider = await Provider.findById(providerId);
+
+    if (!oldProvider) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'No provider found with that ID',
+      });
+    }
+
+    const updateData = { ...req.body };
+
+    // Handle logo update or deletion
+    if (req.file) {
+      // New logo uploaded
+      updateData.logo = req.file.path;
+
+      // Delete old logo from Cloudinary if it exists
+      if (oldProvider.logo) {
+        const publicId = getPublicIdFromUrl(oldProvider.logo);
+        if (publicId) {
+          await deleteImage(publicId).catch((err) =>
+            console.error('Cloudinary delete error:', err),
+          );
+        }
+      }
+    } else if (req.body.logo === '') {
+      // Logo explicitly removed
+      updateData.logo = '';
+
+      // Delete old logo from Cloudinary if it exists
+      if (oldProvider.logo) {
+        const publicId = getPublicIdFromUrl(oldProvider.logo);
+        if (publicId) {
+          await deleteImage(publicId).catch((err) =>
+            console.error('Cloudinary delete error:', err),
+          );
+        }
+      }
+    } else {
+      // Keep existing logo - remove it from updateData so it doesn't try to update with a string/URL
+      delete updateData.logo;
+    }
+
+    const updatedProvider = await Provider.findByIdAndUpdate(
+      providerId,
+      updateData,
+      { new: true, runValidators: true },
+    );
+
+    if (!updatedProvider) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'No provider found with that ID',
+      });
+    }
+
+    // Also update the associated User's email, phone, and password if they changed
+    if (
+      updatedProvider.user &&
+      (req.body.email || req.body.phoneNumber || req.body.password)
+    ) {
+      const user = await User.findById(updatedProvider.user);
+      if (user) {
+        if (req.body.email) user.email = req.body.email;
+        if (req.body.phoneNumber) user.phone = req.body.phoneNumber;
+        if (req.body.password) user.password = req.body.password;
+
+        await user.save();
+      }
+    }
+
+    res.status(200).json({
+      status: 'success',
+      data: { provider: updatedProvider },
+    });
+  } catch (err) {
+    if (err.code === 11000) {
+      const field = Object.keys(err.keyPattern)[0];
+      const message =
+        field === 'storeName'
+          ? 'اسم المتجر مسجل بالفعل'
+          : 'رقم الهاتف أو البريد الإلكتروني مسجل بالفعل';
+      return res.status(400).json({ status: 'fail', message });
+    }
+    res.status(400).json({
+      status: 'fail',
+      message: err.message,
+    });
+  }
+};
+
+// Delete a provider
+exports.deleteProvider = async (req, res) => {
+  try {
+    const provider = await Provider.findById(req.params.id);
+    if (!provider) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'No provider found with that ID',
+      });
+    }
+
+    // Delete associated user
+    if (provider.user) {
+      await User.findByIdAndDelete(provider.user);
+    }
+
+    // Delete logo from Cloudinary if it exists
+    if (provider.logo) {
+      const publicId = getPublicIdFromUrl(provider.logo);
+      if (publicId) await deleteImage(publicId);
+    }
+
+    await Provider.findByIdAndDelete(req.params.id);
+    res.status(204).json({
+      status: 'success',
+      data: null,
+    });
+  } catch (err) {
+    res.status(400).json({
+      status: 'fail',
+      message: err.message,
+    });
+  }
+};

controllers/returnRequestController.js

@@ -0,0 +1,85 @@
+const ReturnRequest = require('../models/returnRequestModel');
+
+// 1. Submit Return Request (Public)
+exports.submitRequest = async (req, res) => {
+  try {
+    const newRequest = await ReturnRequest.create(req.body);
+
+    res.status(201).json({
+      status: 'success',
+      message: 'تم إرسال طلب الاسترجاع بنجاح',
+      data: { request: newRequest },
+    });
+  } catch (err) {
+    res.status(400).json({
+      status: 'fail',
+      message: err.message,
+    });
+  }
+};
+
+// 2. Get All Requests (Admin)
+exports.getAllRequests = async (req, res) => {
+  try {
+    const requests = await ReturnRequest.find().sort({ createdAt: -1 });
+    res.status(200).json({
+      status: 'success',
+      results: requests.length,
+      data: { requests },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'fail',
+      message: err.message,
+    });
+  }
+};
+
+// 3. Delete Request (Admin)
+exports.deleteRequest = async (req, res) => {
+  try {
+    const request = await ReturnRequest.findByIdAndDelete(req.params.id);
+    if (!request) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'No request found with that ID',
+      });
+    }
+
+    res.status(204).json({
+      status: 'success',
+      data: null,
+    });
+  } catch (err) {
+    res.status(400).json({
+      status: 'fail',
+      message: err.message,
+    });
+  }
+};
+
+// 4. Toggle Read Status (Admin)
+exports.toggleReadStatus = async (req, res) => {
+  try {
+    const request = await ReturnRequest.findById(req.params.id);
+    if (!request) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'No request found with that ID',
+      });
+    }
+
+    request.isRead = !request.isRead;
+    await request.save();
+
+    res.status(200).json({
+      status: 'success',
+      data: { request },
+    });
+  } catch (err) {
+    res.status(400).json({
+      status: 'fail',
+      message: err.message,
+    });
+  }
+};

controllers/reviewController.js

@@ -0,0 +1,129 @@
+const Review = require('../models/reviewModel');
+const Product = require('../models/productModel');
+
+// create a review
+exports.createReview = async (req, res) => {
+  try {
+    const { product, rating, review } = req.body;
+
+    // Ensure product exists
+    const existingProduct = await Product.findById(product);
+    if (!existingProduct) {
+      return res.status(400).json({ message: 'Invalid product ID' });
+    }
+
+    // Prevent duplicate reviews by same user
+    const existingReview = await Review.findOne({
+      product,
+      user: req.user._id,
+    });
+    if (existingReview) {
+      return res
+        .status(400)
+        .json({ message: 'You already reviewed this product' });
+    }
+
+    // Create review
+    const newReview = await Review.create({
+      product,
+      user: req.user._id,
+      rating,
+      review,
+    });
+
+    res.status(201).json({
+      status: 'success',
+      data: newReview,
+    });
+  } catch (error) {
+    res.status(500).json({ message: error.message });
+  }
+};
+
+// get all reviews
+exports.getAllReviews = async (req, res) => {
+  try {
+    const reviews = await Review.find().populate({
+      path: 'product',
+      select: 'nameEn nameAr price imageCover',
+    });
+
+    res.status(200).json({
+      status: 'success',
+      results: reviews.length,
+      data: reviews,
+    });
+  } catch (error) {
+    res.status(500).json({ message: error.message });
+  }
+};
+
+// get all reviews for a product
+exports.getProductReviews = async (req, res) => {
+  try {
+    const reviews = await Review.find({ product: req.params.productId });
+
+    res.status(200).json({
+      status: 'success',
+      results: reviews.length,
+      data: reviews,
+    });
+  } catch (error) {
+    res.status(500).json({ message: error.message });
+  }
+};
+
+// Update a review
+exports.updateReview = async (req, res) => {
+  try {
+    const review = await Review.findById(req.params.id);
+
+    if (!review) {
+      return res.status(404).json({ message: 'Review not found' });
+    }
+
+    // Only review owner can edit
+    if (review.user.toString() !== req.user._id.toString()) {
+      return res.status(403).json({ message: 'Not authorized' });
+    }
+
+    const updated = await Review.findByIdAndUpdate(
+      req.params.id,
+      { rating: req.body.rating, review: req.body.review },
+      { new: true, runValidators: true },
+    );
+
+    // Trigger recalculation manually (because findByIdAndUpdate doesn’t trigger post('save'))
+    await Review.calcAverageRatings(review.product);
+
+    res.status(200).json({
+      status: 'success',
+      data: updated,
+    });
+  } catch (error) {
+    res.status(500).json({ message: error.message });
+  }
+};
+
+// Delete a review
+exports.deleteReview = async (req, res) => {
+  try {
+    const review = await Review.findById(req.params.id);
+
+    if (!review) {
+      return res.status(404).json({ message: 'Review not found' });
+    }
+
+    // Only review owner or admin can delete
+    if (review.user.toString() !== req.user._id.toString()) {
+      return res.status(403).json({ message: 'Not authorized' });
+    }
+
+    await Review.findByIdAndDelete(req.params.id);
+    await Review.calcAverageRatings(review.product);
+
+    res.status(204).json({ status: 'success', data: null });
+  } catch (error) {
+    res.status(500).json({ message: error.message });
+  }
+};

controllers/settingsController.js

@@ -0,0 +1,44 @@
+const SiteSettings = require('../models/siteSettingsModel');
+
+exports.getSettings = async (req, res) => {
+    try {
+        const settings = await SiteSettings.getSettings();
+        res.status(200).json({
+            status: 'success',
+            data: { settings },
+        });
+    } catch (err) {
+        res.status(500).json({
+            status: 'error',
+            message: err.message,
+        });
+    }
+};
+
+exports.updateSettings = async (req, res) => {
+    try {
+        // getSettings handles finding or creating
+        let settings = await SiteSettings.getSettings();
+
+        // Update fields
+        if (req.body.checkout) {
+            settings.checkout = { ...settings.checkout.toObject(), ...req.body.checkout };
+        }
+
+        // Add other settings updates here as needed (topBar, footer, etc.)
+        if (req.body.topBar) settings.topBar = { ...settings.topBar.toObject(), ...req.body.topBar };
+        if (req.body.footer) settings.footer = { ...settings.footer.toObject(), ...req.body.footer };
+
+        await settings.save();
+
+        res.status(200).json({
+            status: 'success',
+            data: { settings },
+        });
+    } catch (err) {
+        res.status(500).json({
+            status: 'error',
+            message: err.message,
+        });
+    }
+};

controllers/shippingController.js

@@ -0,0 +1,179 @@
+const bostaService = require('../utils/bostaService');
+const ShippingPrice = require('../models/shippingPriceModel');
+
+// Get all Cities (Governorates) merged with our local price data
+exports.getGovernorates = async (req, res) => {
+  try {
+    const bostaData = await bostaService.getBostaCities();
+    const governorates = bostaData.data || bostaData;
+
+    // Fetch our local pricing data
+    const localPrices = await ShippingPrice.find();
+    const priceMap = new Map(localPrices.map((p) => [p.bostaCityId, p]));
+
+    // Merge price data into governorates list
+    const mergedGovernorates = governorates.map((gov) => {
+      const localData = priceMap.get(gov._id);
+      return {
+        ...gov,
+        // Normalize names for frontend (Bosta uses name and nameAr strings)
+        name: {
+          ar:
+            gov.nameAr ||
+            gov.name ||
+            (gov._id === 'Jrb6X6ucjiYgMP4T7' ? 'الإسكندرية' : ''),
+          en: gov.name || (gov._id === 'Jrb6X6ucjiYgMP4T7' ? 'Alexandria' : ''),
+        },
+        fees: localData ? localData.fees || 0 : 0,
+        deliveryDays: localData ? localData.deliveryDays || 3 : 3,
+        isActive: localData ? localData.isActive !== false : true,
+      };
+    });
+
+    res.status(200).json({
+      status: 'success',
+      results: mergedGovernorates.length,
+      data: {
+        governorates: mergedGovernorates,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: 'Failed to fetch governorates',
+      error: err.message,
+    });
+  }
+};
+
+// Update or Create Shipping Fee for a City
+exports.updateShippingFee = async (req, res) => {
+  try {
+    const {
+      bostaCityId,
+      bostaZoneId,
+      type = 'city',
+      fees,
+      deliveryDays,
+      areaNameAr,
+      areaNameEn,
+      isActive,
+    } = req.body;
+
+    if (!bostaCityId) {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'Bosta City ID is required',
+      });
+    }
+
+    // Search by both City and Zone ID to ensure uniqueness for zones
+    // For better control, we'll explicitly pick which one to match if multiple exist
+    // But usually there should be only one city document
+
+    const shippingPrice = await ShippingPrice.findOneAndUpdate(
+      { bostaCityId, bostaZoneId: bostaZoneId || null },
+      {
+        fees,
+        deliveryDays,
+        areaNameAr,
+        areaNameEn,
+        type,
+        isActive,
+      },
+      {
+        new: true,
+        upsert: true,
+        runValidators: true,
+        setDefaultsOnInsert: true,
+      },
+    );
+
+    res.status(200).json({
+      status: 'success',
+      data: {
+        shippingPrice,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: 'Failed to update shipping fee',
+      error: err.message,
+    });
+  }
+};
+
+// Get Zones (Areas/Districts) for a City
+exports.getCities = async (req, res) => {
+  try {
+    const { id } = req.params; // governorate ID
+    const data = await bostaService.getBostaZones(id);
+    const zones = data.data || data;
+
+    // Fetch local prices for these zones
+    const localPrices = await ShippingPrice.find({
+      bostaCityId: id,
+      type: 'zone',
+    });
+    const priceMap = new Map(localPrices.map((p) => [p.bostaZoneId, p]));
+
+    const mergedZones = zones.map((zone) => {
+      const localData = priceMap.get(zone._id);
+      return {
+        ...zone,
+        name: {
+          ar: zone.nameAr || zone.name,
+          en: zone.name,
+        },
+        fees: localData ? localData.fees : 0,
+        isActive: localData ? localData.isActive : true,
+      };
+    });
+
+    res.status(200).json({
+      status: 'success',
+      results: mergedZones.length,
+      data: {
+        cities: mergedZones,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: 'Failed to fetch cities',
+      error: err.message,
+    });
+  }
+};
+// Get Districts for a City/Governorate
+exports.getDistricts = async (req, res) => {
+  try {
+    const { id } = req.params; // governorate ID
+    const data = await bostaService.getBostaDistricts(id);
+    const districts = data.data || data;
+
+    const normalizedDistricts = districts.map((d) => ({
+      _id: d.districtId,
+      zoneId: d.zoneId,
+      name: {
+        ar: d.districtOtherName || d.districtName,
+        en: d.districtName,
+      },
+    }));
+
+    res.status(200).json({
+      status: 'success',
+      results: normalizedDistricts.length,
+      data: {
+        districts: normalizedDistricts,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: 'Failed to fetch districts',
+      error: err.message,
+    });
+  }
+};

controllers/userManagementController.js

@@ -0,0 +1,473 @@
+const User = require('../models/userModel');
+const Provider = require('../models/providerModel');
+const Newsletter = require('../models/newsletterModel');
+const bcrypt = require('bcryptjs');
+
+// Get all users (with filtering by role)
+exports.getAllUsers = async (req, res) => {
+  try {
+    const { role, isActive } = req.query;
+    let users;
+
+    if (role === 'subscriber') {
+      // Find all active newsletter emails
+      const subscribers = await Newsletter.find({ isActive: true }).select(
+        'email',
+      );
+      const emails = subscribers.map((s) => s.email);
+
+      // Find users whose email is in the subscribers list (for in-app notifications)
+      users = await User.find({ email: { $in: emails } }).select('-password');
+
+      // For the results count, we show the total number of newsletter subscribers
+      return res.status(200).json({
+        status: 'success',
+        results: subscribers.length,
+        data: {
+          users,
+          totalSubscribers: subscribers.length,
+        },
+      });
+    } else {
+      const filter = {};
+      if (role) filter.role = role;
+      if (isActive !== undefined) filter.isActive = isActive === 'true';
+
+      users = await User.find(filter).select('-password');
+    }
+
+    res.status(200).json({
+      status: 'success',
+      results: users.length,
+      data: {
+        users,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: 'Failed to fetch users',
+      error: err.message,
+    });
+  }
+};
+
+// Get single user by ID
+exports.getUser = async (req, res) => {
+  try {
+    const user = await User.findById(req.params.id).select('-password');
+
+    if (!user) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'User not found',
+      });
+    }
+
+    res.status(200).json({
+      status: 'success',
+      data: {
+        user,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: 'Failed to fetch user',
+      error: err.message,
+    });
+  }
+};
+
+// Create user with specific role (admin only)
+exports.createUser = async (req, res) => {
+  try {
+    const { name, email, phone, password, role, permissions, providerData } =
+      req.body;
+
+    // Validate required fields
+    if (!name || !email || !phone || !password) {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'Please provide name, email, phone, and password',
+      });
+    }
+
+    // Check if email already exists
+    const existingUser = await User.findOne({ email });
+    if (existingUser) {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'Email already registered',
+      });
+    }
+
+    // Check if phone already exists
+    const existingPhone = await User.findOne({ phone });
+    if (existingPhone) {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'Phone number already registered',
+      });
+    }
+
+    // Create user data object
+    const userData = {
+      name,
+      email,
+      phone,
+      password,
+      role: role || 'customer',
+    };
+
+    // Add permissions if role is employee
+    if (role === 'employee' && permissions) {
+      userData.permissions = permissions;
+    }
+
+    // Create the user first
+    const newUser = await User.create(userData);
+
+    // If role is vendor, create or link provider
+    if (role === 'vendor' && providerData) {
+      const provider = await Provider.create({
+        ...providerData,
+        user: newUser._id,
+      });
+      newUser.provider = provider._id;
+      await newUser.save();
+    }
+
+    // Remove password from response
+    newUser.password = undefined;
+
+    res.status(201).json({
+      status: 'success',
+      data: {
+        user: newUser,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: 'Failed to create user',
+      error: err.message,
+    });
+  }
+};
+
+// Update user details (for employees)
+exports.updateUser = async (req, res) => {
+  try {
+    const { name, email, phone, password, permissions, isActive } = req.body;
+
+    const user = await User.findById(req.params.id);
+
+    if (!user) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'User not found',
+      });
+    }
+
+    // Update basic fields if provided
+    if (name) user.name = name;
+    if (email) {
+      // Check if email is already taken by another user
+      const existingUser = await User.findOne({
+        email,
+        _id: { $ne: req.params.id },
+      });
+      if (existingUser) {
+        return res.status(400).json({
+          status: 'fail',
+          message: 'Email already in use',
+        });
+      }
+      user.email = email;
+    }
+    if (phone) {
+      // Check if phone is already taken by another user
+      const existingPhone = await User.findOne({
+        phone,
+        _id: { $ne: req.params.id },
+      });
+      if (existingPhone) {
+        return res.status(400).json({
+          status: 'fail',
+          message: 'Phone number already in use',
+        });
+      }
+      user.phone = phone;
+    }
+
+    // Update password if provided
+    if (password) {
+      user.password = password; // Will be hashed by pre-save middleware
+    }
+
+    // Update permissions if user is employee
+    if (user.role === 'employee' && permissions !== undefined) {
+      user.permissions = permissions;
+    }
+
+    // Update isActive status
+    if (isActive !== undefined) {
+      user.isActive = isActive;
+    }
+
+    await user.save();
+
+    // Remove password from response
+    user.password = undefined;
+
+    res.status(200).json({
+      status: 'success',
+      data: {
+        user,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: 'Failed to update user',
+      error: err.message,
+    });
+  }
+};
+
+// Update user role
+exports.updateUserRole = async (req, res) => {
+  try {
+    const { role } = req.body;
+
+    if (!role || !['customer', 'admin', 'employee', 'vendor'].includes(role)) {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'Please provide a valid role',
+      });
+    }
+
+    const user = await User.findById(req.params.id);
+
+    if (!user) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'User not found',
+      });
+    }
+
+    user.role = role;
+
+    // Clear permissions if changing from employee to another role
+    if (role !== 'employee') {
+      user.permissions = [];
+    }
+
+    await user.save();
+
+    res.status(200).json({
+      status: 'success',
+      data: {
+        user,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: 'Failed to update user role',
+      error: err.message,
+    });
+  }
+};
+
+// Update employee permissions
+exports.updateEmployeePermissions = async (req, res) => {
+  try {
+    const { permissions } = req.body;
+
+    if (!Array.isArray(permissions)) {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'Permissions must be an array',
+      });
+    }
+
+    const user = await User.findById(req.params.id);
+
+    if (!user) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'User not found',
+      });
+    }
+
+    if (user.role !== 'employee') {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'Permissions can only be set for employees',
+      });
+    }
+
+    user.permissions = permissions;
+    await user.save();
+
+    // Emit socket event to notify the employee of permission changes
+    try {
+      const io = require('../utils/socket').getIO();
+      io.to(user._id.toString()).emit('permissionsUpdated', {
+        permissions: user.permissions,
+        message: 'تم تحديث صلاحياتك من قبل المسؤول',
+      });
+    } catch (socketError) {
+      console.error('Failed to emit permission update:', socketError);
+      // Don't fail the request if socket emission fails
+    }
+
+    res.status(200).json({
+      status: 'success',
+      data: {
+        user,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: 'Failed to update permissions',
+      error: err.message,
+    });
+  }
+};
+
+// Update vendor information
+exports.updateVendorInfo = async (req, res) => {
+  try {
+    const { vendorInfo } = req.body;
+
+    if (!vendorInfo) {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'Please provide vendor information',
+      });
+    }
+
+    const user = await User.findById(req.params.id);
+
+    if (!user) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'User not found',
+      });
+    }
+
+    if (user.role !== 'vendor') {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'Vendor info can only be set for vendors',
+      });
+    }
+
+    user.vendorInfo = { ...user.vendorInfo, ...vendorInfo };
+    await user.save();
+
+    res.status(200).json({
+      status: 'success',
+      data: {
+        user,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: 'Failed to update vendor info',
+      error: err.message,
+    });
+  }
+};
+
+// Deactivate user account
+exports.deactivateUser = async (req, res) => {
+  try {
+    const user = await User.findById(req.params.id);
+
+    if (!user) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'User not found',
+      });
+    }
+
+    user.isActive = false;
+    await user.save();
+
+    res.status(200).json({
+      status: 'success',
+      message: 'User account deactivated successfully',
+      data: {
+        user,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: 'Failed to deactivate user',
+      error: err.message,
+    });
+  }
+};
+
+// Activate user account
+exports.activateUser = async (req, res) => {
+  try {
+    const user = await User.findById(req.params.id);
+
+    if (!user) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'User not found',
+      });
+    }
+
+    user.isActive = true;
+    await user.save();
+
+    res.status(200).json({
+      status: 'success',
+      message: 'User account activated successfully',
+      data: {
+        user,
+      },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: 'Failed to activate user',
+      error: err.message,
+    });
+  }
+};
+
+// Delete user (permanent)
+exports.deleteUser = async (req, res) => {
+  try {
+    const user = await User.findByIdAndDelete(req.params.id);
+
+    if (!user) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'User not found',
+      });
+    }
+
+    res.status(200).json({
+      status: 'success',
+      message: 'User deleted successfully',
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'error',
+      message: 'Failed to delete user',
+      error: err.message,
+    });
+  }
+};

controllers/usersController.js

@@ -0,0 +1,191 @@
+const User = require('../models/userModel');
+const Order = require('../models/orderModel');
+
+// Get all users with their order statistics
+exports.getAllUsers = async (req, res) => {
+  try {
+    // Get all users sorted by registration date (newest first)
+    const users = await User.find()
+      .select('-password')
+      .sort({ createdAt: -1 })
+      .lean();
+
+    // Get current month date range
+    const now = new Date();
+    const startOfMonth = new Date(now.getFullYear(), now.getMonth(), 1);
+    const endOfMonth = new Date(
+      now.getFullYear(),
+      now.getMonth() + 1,
+      0,
+      23,
+      59,
+      59,
+    );
+
+    // Get order counts for each user
+    const usersWithStats = await Promise.all(
+      users.map(async (user) => {
+        // Count total orders for this user
+        const totalOrders = await Order.countDocuments({ user: user._id });
+
+        // Count orders this month
+        const ordersThisMonth = await Order.countDocuments({
+          user: user._id,
+          createdAt: { $gte: startOfMonth, $lte: endOfMonth },
+        });
+
+        // Calculate total spent
+        const orders = await Order.find({ user: user._id });
+        const totalSpent = orders.reduce(
+          (sum, order) => sum + order.totalPrice,
+          0,
+        );
+
+        // Calculate tier based on order count
+        let tier = 'حديدي'; // Iron (default for 0 orders)
+        if (totalOrders >= 35) {
+          tier = 'بلاتيني'; // Platinum
+        } else if (totalOrders >= 20) {
+          tier = 'ذهبي'; // Gold
+        } else if (totalOrders >= 10) {
+          tier = 'فضي'; // Silver
+        } else if (totalOrders >= 1) {
+          tier = 'برونزي'; // Bronze
+        }
+
+        // isActive is true if user has orders this month
+        const isActive = ordersThisMonth > 0;
+
+        return {
+          ...user,
+          totalOrders,
+          totalSpent,
+          tier,
+          isActive,
+        };
+      }),
+    );
+
+    res.status(200).json({
+      status: 'success',
+      results: usersWithStats.length,
+      data: usersWithStats,
+    });
+  } catch (err) {
+    console.error('Error fetching users:', err);
+    res.status(500).json({
+      status: 'fail',
+      message: 'Failed to fetch users',
+      error: err.message,
+    });
+  }
+};
+
+// Get user by ID with their orders
+exports.getUserById = async (req, res) => {
+  try {
+    const { id } = req.params;
+
+    // Find user by ID
+    const user = await User.findById(id).select('-password').lean();
+
+    if (!user) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'User not found',
+      });
+    }
+
+    // Get all orders for this user
+    const orders = await Order.find({ user: id })
+      .populate('items.product', 'nameAr nameEn price images')
+      .populate('promo', 'code discountType discountValue')
+      .sort({ createdAt: -1 })
+      .lean();
+
+    // Get current month date range
+    const now = new Date();
+    const startOfMonth = new Date(now.getFullYear(), now.getMonth(), 1);
+    const endOfMonth = new Date(
+      now.getFullYear(),
+      now.getMonth() + 1,
+      0,
+      23,
+      59,
+      59,
+    );
+
+    // Count total orders
+    const totalOrders = orders.length;
+
+    // Count orders this month
+    const ordersThisMonth = orders.filter(
+      (order) =>
+        order.createdAt >= startOfMonth && order.createdAt <= endOfMonth,
+    ).length;
+
+    // Calculate total spent
+    const totalSpent = orders.reduce((sum, order) => sum + order.totalPrice, 0);
+
+    // Calculate tier based on order count
+    let tier = 'حديدي'; // Iron (default for 0 orders)
+    if (totalOrders >= 35) {
+      tier = 'بلاتيني'; // Platinum
+    } else if (totalOrders >= 20) {
+      tier = 'ذهبي'; // Gold
+    } else if (totalOrders >= 10) {
+      tier = 'فضي'; // Silver
+    } else if (totalOrders >= 1) {
+      tier = 'برونزي'; // Bronze
+    }
+
+    // isActive is true if user has orders this month
+    const isActive = ordersThisMonth > 0;
+
+    res.status(200).json({
+      status: 'success',
+      data: {
+        user: {
+          ...user,
+          totalOrders,
+          totalSpent,
+          tier,
+          isActive,
+        },
+        orders,
+      },
+    });
+  } catch (err) {
+    console.error('Error fetching user by ID:', err);
+    res.status(500).json({
+      status: 'fail',
+      message: 'Failed to fetch user details',
+      error: err.message,
+    });
+  }
+};
+
+// Delete a user
+exports.deleteUser = async (req, res) => {
+  try {
+    const user = await User.findByIdAndDelete(req.params.id);
+
+    if (!user) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'User not found',
+      });
+    }
+
+    res.status(204).json({
+      status: 'success',
+      data: null,
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'fail',
+      message: 'Failed to delete user',
+      error: err.message,
+    });
+  }
+};

controllers/vendorRequestController.js

@@ -0,0 +1,212 @@
+const VendorRequest = require('../models/vendorRequestModel');
+const Provider = require('../models/providerModel');
+const User = require('../models/userModel');
+const {
+  sendVendorAcceptanceEmail,
+  sendVendorRejectionEmail,
+} = require('../utils/emailService');
+const { deleteImage, getPublicIdFromUrl } = require('../config/cloudinary');
+
+// 1. Submit Vendor Request (Public)
+exports.submitRequest = async (req, res) => {
+  try {
+    const requestData = { ...req.body };
+    if (req.file) {
+      requestData.logo = req.file.path;
+    }
+
+    const newRequest = await VendorRequest.create(requestData);
+
+    res.status(201).json({
+      status: 'success',
+      message: 'Form submitted successfully',
+      data: { request: newRequest },
+    });
+  } catch (err) {
+    res.status(400).json({
+      status: 'fail',
+      message: err.message,
+    });
+  }
+};
+
+// 2. Get All Requests (Admin)
+exports.getAllRequests = async (req, res) => {
+  try {
+    const requests = await VendorRequest.find().sort({ createdAt: -1 });
+    res.status(200).json({
+      status: 'success',
+      results: requests.length,
+      data: { requests },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'fail',
+      message: err.message,
+    });
+  }
+};
+
+// 3. Get Single Request (Admin)
+exports.getRequest = async (req, res) => {
+  try {
+    const request = await VendorRequest.findById(req.params.id);
+    if (!request) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'No request found with that ID',
+      });
+    }
+    res.status(200).json({
+      status: 'success',
+      data: { request },
+    });
+  } catch (err) {
+    res.status(400).json({
+      status: 'fail',
+      message: err.message,
+    });
+  }
+};
+
+// 4. Delete Request (Admin)
+exports.deleteRequest = async (req, res) => {
+  try {
+    const request = await VendorRequest.findById(req.params.id);
+    if (!request) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'No request found with that ID',
+      });
+    }
+
+    // Delete logo from Cloudinary if it exists
+    if (request.logo) {
+      const publicId = getPublicIdFromUrl(request.logo);
+      if (publicId) await deleteImage(publicId).catch(() => {});
+    }
+
+    await VendorRequest.findByIdAndDelete(req.params.id);
+
+    res.status(204).json({
+      status: 'success',
+      data: null,
+    });
+  } catch (err) {
+    res.status(400).json({
+      status: 'fail',
+      message: err.message,
+    });
+  }
+};
+
+// 5. Respond to Request (Admin)
+// This will handle both Accept and Refuse
+exports.respondToRequest = async (req, res) => {
+  try {
+    const { status, password } = req.body;
+    const request = await VendorRequest.findById(req.params.id);
+
+    if (!request) {
+      return res.status(404).json({
+        status: 'fail',
+        message: 'No request found with that ID',
+      });
+    }
+
+    if (status === 'accepted') {
+      // Create Provider Account (Logic similar to AdminProviderAdd.jsx handles it on frontend, but we need backend logic too)
+      // Actually, the user said: "if i accept it uses the info in the form and give me option to assign his password"
+      // So the admin will submit a final form with password.
+
+      // First check if user with same email or phone exists
+      const existingUser = await User.findOne({
+        $or: [{ email: request.email }, { phone: request.phoneNumber }],
+      });
+      if (existingUser) {
+        const field =
+          existingUser.email === request.email
+            ? 'البريد الإلكتروني'
+            : 'رقم الهاتف';
+        return res.status(400).json({
+          status: 'fail',
+          message: `${field} مسجل بالفعل لمستخدم آخر`,
+        });
+      }
+
+      // Get last provider ID for auto-increment
+      const lastProvider = await Provider.findOne().sort({ id: -1 });
+      const autoId = lastProvider ? lastProvider.id + 1 : 1;
+
+      // 1. Create Provider document (without user link yet)
+      const newProvider = await Provider.create({
+        id: autoId,
+        name: request.ownerName,
+        storeName: request.businessName,
+        phoneNumber: request.phoneNumber,
+        address: request.address,
+        logo: request.logo,
+      });
+
+      // 2. Create User account for vendor and link to provider
+      try {
+        const newUser = await User.create({
+          name: request.ownerName,
+          email: request.email,
+          phone: request.phoneNumber,
+          password: password,
+          role: 'vendor',
+          provider: newProvider._id,
+        });
+
+        // 3. Update provider with user reference
+        newProvider.user = newUser._id;
+        await newProvider.save();
+
+        // 4. Update Request Status
+        request.status = 'accepted';
+        request.reviewedAt = Date.now();
+        await request.save();
+
+        // 5. Send Acceptance Email
+        await sendVendorAcceptanceEmail({
+          email: request.email,
+          name: request.ownerName,
+          storeName: request.businessName,
+          password: password,
+        });
+
+        return res.status(200).json({
+          status: 'success',
+          message: 'Request accepted and provider created',
+          data: { provider: newProvider },
+        });
+      } catch (err) {
+        // Rollback: Delete the created provider if user creation fails
+        await Provider.findByIdAndDelete(newProvider._id);
+        throw err;
+      }
+    } else if (status === 'rejected') {
+      request.status = 'rejected';
+      request.reviewedAt = Date.now();
+      await request.save();
+
+      // Send Rejection Email
+      await sendVendorRejectionEmail({
+        email: request.email,
+        name: request.ownerName,
+        storeName: request.businessName,
+      });
+
+      return res.status(200).json({
+        status: 'success',
+        message: 'Request rejected',
+      });
+    }
+  } catch (err) {
+    res.status(400).json({
+      status: 'fail',
+      message: err.message,
+    });
+  }
+};

controllers/visitController.js

@@ -0,0 +1,211 @@
+const Visit = require('../models/visitModel');
+
+// Track a visit
+exports.trackVisit = async (req, res) => {
+  try {
+    const { sessionId, page, userId } = req.body;
+
+    if (!sessionId) {
+      return res.status(400).json({
+        status: 'fail',
+        message: 'Session ID is required',
+      });
+    }
+
+    // Get IP address from request
+    const xForwardedFor = req.headers['x-forwarded-for'];
+    const ipAddress =
+      (xForwardedFor ? xForwardedFor.split(',')[0] : null) ||
+      req.connection.remoteAddress ||
+      req.socket.remoteAddress ||
+      req.ip;
+
+    // Get user agent
+    const userAgent = req.headers['user-agent'] || '';
+
+    // Grouping priority:
+    // 1. If we have a userId, we find the ONE global record for this user
+    // 2. If no userId (guest), we find a recent record for this sessionId
+    const today = new Date();
+    today.setHours(0, 0, 0, 0);
+
+    const query = { createdAt: { $gte: today } };
+    if (userId) {
+      query.user = userId;
+    } else {
+      query.sessionId = sessionId;
+    }
+
+    let visit = await Visit.findOne(query).populate('user', 'name email');
+
+    if (visit) {
+      // Grouping: Increment count and update last active time
+      visit.count += 1;
+      visit.lastVisitedAt = new Date();
+      // Update user ID if it was null before (guest just logged in)
+      if (!visit.user && userId) {
+        visit.user = userId;
+      }
+      // Update IP and User Agent to latest
+      visit.ipAddress = ipAddress;
+      visit.userAgent = userAgent;
+      visit.page = page || '/';
+      await visit.save();
+    } else {
+      // Create new visit document
+      visit = await Visit.create({
+        user: userId || null,
+        ipAddress,
+        userAgent,
+        page: page || '/',
+        sessionId,
+        count: 1,
+        lastVisitedAt: new Date(),
+      });
+      // Populate if it was a user
+      if (userId) {
+        await visit.populate('user', 'name email');
+      }
+    }
+
+    res.status(200).json({
+      status: 'success',
+      data: { visit },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'fail',
+      message: err.message,
+    });
+  }
+};
+
+// Get visit statistics
+exports.getVisitStats = async (req, res) => {
+  try {
+    const now = new Date();
+
+    // Today's start
+    const todayStart = new Date(
+      now.getFullYear(),
+      now.getMonth(),
+      now.getDate(),
+    );
+
+    // Current month boundaries
+    const currentMonthStart = new Date(now.getFullYear(), now.getMonth(), 1);
+    const currentMonthEnd = new Date(
+      now.getFullYear(),
+      now.getMonth() + 1,
+      0,
+      23,
+      59,
+      59,
+    );
+
+    // Previous month boundaries
+    const previousMonthStart = new Date(
+      now.getFullYear(),
+      now.getMonth() - 1,
+      1,
+    );
+    const previousMonthEnd = new Date(
+      now.getFullYear(),
+      now.getMonth(),
+      0,
+      23,
+      59,
+      59,
+    );
+
+    // Helper for summing counts and counting documents
+    const getStats = async (filter = {}) => {
+      const uniqueVisits = await Visit.countDocuments(filter);
+      const totalResult = await Visit.aggregate([
+        { $match: filter },
+        { $group: { _id: null, total: { $sum: '$count' } } },
+      ]);
+      const totalVisits = totalResult.length > 0 ? totalResult[0].total : 0;
+      return { uniqueVisits, totalVisits };
+    };
+
+    // Get all time stats
+    const allTime = await getStats();
+
+    // Get today's stats
+    const today = await getStats({ createdAt: { $gte: todayStart } });
+
+    // Get monthly stats for growth calculation
+    const currentMonth = await getStats({
+      createdAt: { $gte: currentMonthStart, $lte: currentMonthEnd },
+    });
+    const previousMonth = await getStats({
+      createdAt: { $gte: previousMonthStart, $lte: previousMonthEnd },
+    });
+
+    // Calculate monthly growth percentage based on TOTAL visits
+    let monthlyGrowth = 0;
+    if (previousMonth.totalVisits > 0) {
+      monthlyGrowth =
+        ((currentMonth.totalVisits - previousMonth.totalVisits) /
+          previousMonth.totalVisits) *
+        100;
+    } else if (currentMonth.totalVisits > 0) {
+      monthlyGrowth = 100;
+    }
+
+    res.status(200).json({
+      status: 'success',
+      data: {
+        totalVisits: allTime.totalVisits,
+        uniqueVisits: allTime.uniqueVisits,
+        todayVisits: today.totalVisits,
+        todayUnique: today.uniqueVisits,
+        currentMonthVisits: currentMonth.totalVisits,
+        previousMonthVisits: previousMonth.totalVisits,
+        monthlyGrowth: parseFloat(monthlyGrowth.toFixed(1)),
+      },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'fail',
+      message: err.message,
+    });
+  }
+};
+
+// Get all visits (admin only)
+exports.getAllVisits = async (req, res) => {
+  try {
+    const { page = 1, limit = 50, startDate, endDate } = req.query;
+
+    // Build filter
+    const filter = {};
+    if (startDate || endDate) {
+      filter.createdAt = {};
+      if (startDate) filter.createdAt.$gte = new Date(startDate);
+      if (endDate) filter.createdAt.$lte = new Date(endDate);
+    }
+
+    const visits = await Visit.find(filter)
+      .populate('user', 'name email')
+      .sort({ createdAt: -1 })
+      .limit(limit * 1)
+      .skip((page - 1) * limit);
+
+    const count = await Visit.countDocuments(filter);
+
+    res.status(200).json({
+      status: 'success',
+      results: visits.length,
+      totalPages: Math.ceil(count / limit),
+      currentPage: page,
+      data: { visits },
+    });
+  } catch (err) {
+    res.status(500).json({
+      status: 'fail',
+      message: err.message,
+    });
+  }
+};

devData/brands.json

@@ -0,0 +1,21 @@
+[
+  { "id": 1, "nameEn": "Fit" },
+  { "id": 7, "nameEn": "Max" },
+  { "id": 5, "nameEn": "LORRAIN" },
+  { "id": 3, "nameEn": "Hans" },
+  { "id": 11, "nameEn": "Annovi" },
+  { "id": 13, "nameEn": "Bisso" },
+  { "id": 15, "nameEn": "durmiri" },
+  { "id": 16, "nameEn": "Remo" },
+  { "id": 17, "nameEn": "Total" },
+  { "id": 18, "nameEn": "Ingco" },
+  { "id": 19, "nameEn": "Dyllu" },
+  { "id": 20, "nameEn": "DCA" },
+  { "id": 21, "nameEn": "brennenstuhl" },
+  { "id": 22, "nameEn": "WOKIN" },
+  { "id": 23, "nameEn": "HARDEN" },
+  { "id": 24, "nameEn": "PIT" },
+  { "id": 25, "nameEn": "UNI-T" },
+  { "id": 26, "nameEn": "RONIX" },
+  { "id": 27, "nameEn": "Steco" }
+]

devData/broken-images.json

@@ -0,0 +1 @@
+[]

devData/categories.json

@@ -0,0 +1,39 @@
+[
+  { "id": 1, "nameAr": "عدد كهربائيه", "nameEn": "Electrical Tools", "parentName": null },
+  { "id": 2, "nameAr": "عدد هواء", "nameEn": "Air Tools", "parentName": null },
+  { "id": 3, "nameAr": "عدد يدوية", "nameEn": "Hand Tools", "parentName": null },
+  { "id": 4, "nameAr": "عدد لحام", "nameEn": "Welding Tools", "parentName": null },
+  { "id": 5, "nameAr": "عدد سمكرة", "nameEn": "Body Tools", "parentName": null },
+  { "id": 8, "nameAr": "ادوات قياس", "nameEn": "Measuring Tools", "parentName": null },
+  { "id": 9, "nameAr": "شنيور بطارية", "nameEn": "Cordless Drill", "parentName": "عدد كهربائيه" },
+  { "id": 11, "nameAr": "كمبروسر ولاعة", "nameEn": "Mini Air Compressor", "parentName": "عدد هواء" },
+  { "id": 12, "nameAr": "ميني كرافت", "nameEn": "Mini Craft", "parentName": "عدد كهربائيه" },
+  { "id": 13, "nameAr": "صواريخ قطعية", "nameEn": "Angle Grinders", "parentName": "عدد كهربائيه" },
+  { "id": 14, "nameAr": "كوريك", "nameEn": "Jack", "parentName": "عدد يدوية" },
+  { "id": 15, "nameAr": "هيلتي", "nameEn": "Demolition Hammer", "parentName": "عدد كهربائيه" },
+  { "id": 16, "nameAr": "بنس برشام", "nameEn": "Riveter Tools", "parentName": "عدد يدوية" },
+  { "id": 17, "nameAr": "عدد ميكانيكا", "nameEn": "Mechanical Tools", "parentName": "عدد يدوية" },
+  { "id": 18, "nameAr": "شفاط زجاج", "nameEn": "Glass Suction", "parentName": "عدد يدوية" },
+  { "id": 19, "nameAr": "دريل", "nameEn": "Drill", "parentName": "عدد كهربائيه" },
+  { "id": 20, "nameAr": "عروض", "nameEn": "Offers", "parentName": null },
+  { "id": 21, "nameAr": "ماكينة لحام", "nameEn": "Welding Machine", "parentName": "عدد لحام" },
+  { "id": 22, "nameAr": "هزار سيراميك", "nameEn": "Ceramic Cutter", "parentName": "عدد يدوية" },
+  { "id": 23, "nameAr": "مشحمة", "nameEn": "Grease Gun", "parentName": "عدد هواء" },
+  { "id": 24, "nameAr": "مسدس هواء", "nameEn": "Air Gun", "parentName": "عدد هواء" },
+  { "id": 25, "nameAr": "ماكينات هواء", "nameEn": "Air Machines", "parentName": "عدد هواء" },
+  { "id": 26, "nameAr": "كمبروسر", "nameEn": "Air Compressor", "parentName": "عدد هواء" },
+  { "id": 27, "nameAr": "طلمبة غسيل", "nameEn": "Washing Pump", "parentName": "عدد هواء" },
+  { "id": 28, "nameAr": "دباسه", "nameEn": "Stapler", "parentName": "عدد هواء" },
+  { "id": 29, "nameAr": "موازين ليزر", "nameEn": "Laser Levels", "parentName": "ادوات قياس" },
+  { "id": 31, "nameAr": "لمبه لحام", "nameEn": "Welding Lamp", "parentName": "عدد لحام" },
+  { "id": 32, "nameAr": "بنس و بك لحام", "nameEn": "Welding Pliers", "parentName": "عدد لحام" },
+  { "id": 33, "nameAr": "لحام مواسير", "nameEn": "Tube Welding", "parentName": "عدد لحام" },
+  { "id": 34, "nameAr": "منظم لحام", "nameEn": "Welding Regulator", "parentName": "عدد لحام" },
+  { "id": 35, "nameAr": "وش لحام", "nameEn": "Welding Mask", "parentName": "عدد لحام" },
+  { "id": 37, "nameAr": "عروض ادوات البيت", "nameEn": "Home Offers", "parentName": "عروض" },
+  { "id": 38, "nameAr": "عروض عدد السيارات", "nameEn": "Car Tools Offers", "parentName": "عروض" },
+  { "id": 39, "nameAr": "مشتركات", "nameEn": "Power Strips", "parentName": "عدد كهربائيه" },
+  { "id": 40, "nameAr": "ميزان مياه", "nameEn": "Spirit Level", "parentName": "ادوات قياس" },
+  { "id": 41, "nameAr": "روتر", "nameEn": "Router", "parentName": "عدد كهربائيه" },
+  { "id": 42, "nameAr": "ادوات ربط", "nameEn": "Fastening Tools", "parentName": "عدد يدوية" }
+]

devData/dump-broken.js

@@ -0,0 +1,18 @@
+const mongoose = require('mongoose');
+const fs = require('fs');
+const dotenv = require('dotenv');
+const Product = require('../models/productModel');
+
+dotenv.config({ path: './config.env' });
+const DB = process.env.DATABASE.replace('<PASSWORD>', process.env.DATABASE_PASSWORD);
+
+mongoose.connect(DB).then(async () => {
+  const p = await Product.findOne({ nameAr: { $regex: /صاروخ توتال 9 بوصة/ } });
+  if (p) {
+    fs.writeFileSync('broken-url.txt', p.imageCover);
+    console.log("Broken URL saved to broken-url.txt");
+  } else {
+    console.log("Product not found");
+  }
+  process.exit();
+});

devData/fix-provider-ids.js

@@ -0,0 +1,57 @@
+const mongoose = require('mongoose');
+const dotenv = require('dotenv');
+const Provider = require('../models/providerModel');
+
+dotenv.config({ path: './config.env' });
+const DB = process.env.DATABASE.replace('<PASSWORD>', process.env.DATABASE_PASSWORD);
+
+mongoose.connect(DB).then(async () => {
+  console.log('DB connection successful!\n');
+
+  try {
+    // 1. Get the current providers
+    const center = await Provider.findOne({ storeName: 'سنتر المنصورة' });
+    const wekalt = await Provider.findOne({ storeName: 'وكالة العدد' });
+
+    if (!center) { console.log('Could not find Center El Mansoura'); return process.exit(1); }
+    if (!wekalt) { console.log('Could not find Wekalt El 3edad'); return process.exit(1); }
+
+    console.log('Found providers. Shifting IDs to temporary numbers...');
+    
+    // Assign temp IDs first to avoid unique constraint errors
+    await Provider.findByIdAndUpdate(center._id, { id: 1002 }, { validateBeforeSave: false });
+    await Provider.findByIdAndUpdate(wekalt._id, { id: 1003 }, { validateBeforeSave: false });
+
+    // 2. Check if Samoulla exists, if not create it
+    let samoulla = await Provider.findOne({ storeName: { $regex: /samoulla|صمولة/i } });
+    if (!samoulla) {
+      console.log('Creating Samoulla provider...');
+      samoulla = await Provider.create({
+        name: 'Samoulla Admin',
+        storeName: 'Samoulla',
+        address: 'Main HQ',
+        phoneNumber: '01000000000',
+        id: 1, // Give Samoulla ID 1
+        isActive: true
+      });
+    } else {
+      console.log('Samoulla already exists, updating ID to 1...');
+      await Provider.findByIdAndUpdate(samoulla._id, { id: 1 }, { validateBeforeSave: false });
+    }
+
+    // 3. Assign final IDs
+    console.log('Assigning final IDs to Center El Mansoura and Wekalt El 3edad...');
+    await Provider.findByIdAndUpdate(center._id, { id: 2 }, { validateBeforeSave: false });
+    await Provider.findByIdAndUpdate(wekalt._id, { id: 3 }, { validateBeforeSave: false });
+
+    console.log('\n--- Final Providers ---');
+    const all = await Provider.find({}, { storeName: 1, id: 1 }).sort({ id: 1 });
+    all.forEach(p => console.log(`ID: ${p.id} | Store: ${p.storeName}`));
+
+    console.log('\n✅ Successfully updated! No products were harmed or shifted.');
+    
+  } catch (err) {
+    console.error('Error during update:', err);
+  }
+  process.exit();
+}).catch((err) => { console.error(err); process.exit(1); });

devData/import-brands.js

@@ -0,0 +1,54 @@
+const fs = require('fs');
+const mongoose = require('mongoose');
+const dotenv = require('dotenv');
+const Brand = require('../models/brandModel');
+
+dotenv.config({ path: './config.env' });
+
+const DB = process.env.DATABASE.replace(
+  '<PASSWORD>',
+  process.env.DATABASE_PASSWORD,
+);
+
+mongoose
+  .connect(DB)
+  .then(() => console.log('DB connection successful!'))
+  .catch((err) => {
+    console.log('DB connection error:', err);
+  });
+
+// Read JSON file
+const brands = JSON.parse(
+  fs.readFileSync(`${__dirname}/brands.json`, 'utf-8'),
+);
+
+// Import data into DB
+const importData = async () => {
+  try {
+    // Optional: Delete existing brands if you want a clean seed each time
+    await Brand.deleteMany();
+    console.log('Existing brands deleted.');
+
+    await Brand.create(brands);
+    console.log('Brands successfully loaded!');
+  } catch (err) {
+    console.log(err);
+  }
+  process.exit();
+};
+
+const deleteData = async () => {
+    try {
+      await Brand.deleteMany();
+      console.log('Brands successfully deleted!');
+    } catch (err) {
+      console.log(err);
+    }
+    process.exit();
+};
+
+if (process.argv[2] === '--import') {
+  importData();
+} else if (process.argv[2] === '--delete') {
+  deleteData();
+}

devData/import-categories.js

@@ -0,0 +1,84 @@
+const fs = require('fs');
+const mongoose = require('mongoose');
+const dotenv = require('dotenv');
+const Category = require('../models/categoryModel');
+
+dotenv.config({ path: './config.env' });
+
+const DB = process.env.DATABASE.replace(
+  '<PASSWORD>',
+  process.env.DATABASE_PASSWORD,
+);
+
+mongoose
+  .connect(DB)
+  .then(() => console.log('DB connection successful!'))
+  .catch((err) => {
+    console.log('DB connection error:', err);
+  });
+
+// Read JSON file
+const categories = JSON.parse(
+  fs.readFileSync(`${__dirname}/categories.json`, 'utf-8'),
+);
+
+// Import data into DB
+const importData = async () => {
+  try {
+    // Delete all existing categories to avoid duplicates during seed
+    await Category.deleteMany();
+    console.log('Existing categories deleted.');
+
+    // 1. Separate root and subcategories
+    const rootCategories = categories.filter(cat => !cat.parentName);
+    const subCategories = categories.filter(cat => cat.parentName);
+
+    // 2. Insert root categories
+    const createdRoots = await Category.insertMany(rootCategories.map(cat => ({
+        id: cat.id,
+        nameAr: cat.nameAr,
+        nameEn: cat.nameEn,
+        parent: null
+    })));
+    console.log(`${createdRoots.length} Root categories loaded.`);
+
+    // 3. Create a map of nameAr to _id
+    const idMap = {};
+    const allCategories = await Category.find();
+    allCategories.forEach(cat => {
+        idMap[cat.nameAr] = cat._id;
+    });
+
+    // 4. Insert subcategories with parent _id
+    const subCatsToInsert = subCategories.map(cat => ({
+        id: cat.id,
+        nameAr: cat.nameAr,
+        nameEn: cat.nameEn,
+        parent: idMap[cat.parentName] || null
+    }));
+
+    const createdSubs = await Category.insertMany(subCatsToInsert);
+    console.log(`${createdSubs.length} Sub-categories loaded.`);
+
+    console.log('All categories successfully loaded!');
+  } catch (err) {
+    console.log(err);
+  }
+  process.exit();
+};
+
+const deleteData = async () => {
+    try {
+      await Category.deleteMany();
+      console.log('Categories successfully deleted!');
+    } catch (err) {
+      console.log(err);
+    }
+    process.exit();
+};
+
+if (process.argv[2] === '--import') {
+  importData();
+} else if (process.argv[2] === '--delete') {
+  deleteData();
+}

devData/importProducts.js

@@ -0,0 +1,55 @@
+const fs = require('fs');
+const mongoose = require('mongoose');
+const dotenv = require('dotenv');
+const Product = require('../models/productModel');
+const Category = require('../models/categoryModel');
+const Provider = require('../models/providerModel');
+
+dotenv.config({ path: './config.env' });
+
+const DB = process.env.DATABASE.replace(
+  '<PASSWORD>',
+  process.env.DATABASE_PASSWORD,
+);
+
+mongoose
+  .connect(DB)
+  .then(() => console.log('DB connection successful!'))
+  .catch((err) => {
+    console.log('DB connection error:', err);
+  });
+
+// Read JSON file
+const products = JSON.parse(
+  fs.readFileSync(`${__dirname}/products-sample.json`, 'utf-8'),
+);
+
+// Import data into DB
+const importData = async () => {
+  try {
+    await Product.create(products);
+    console.log('Data successfully loaded!');
+  } catch (err) {
+    console.log(err);
+  }
+  process.exit();
+};
+
+// Delete all data from DB
+const deleteData = async () => {
+  try {
+    await Product.deleteMany();
+    await Category.deleteMany();
+    await Provider.deleteMany();
+    console.log('Data successfully deleted!');
+  } catch (err) {
+    console.log(err);
+  }
+  process.exit();
+};
+
+if (process.argv[2] === '--import') {
+  importData();
+} else if (process.argv[2] === '--delete') {
+  deleteData();
+}

devData/inspect-broken.js

@@ -0,0 +1,17 @@
+const mongoose = require('mongoose');
+const dotenv = require('dotenv');
+const Product = require('../models/productModel');
+
+dotenv.config({ path: './config.env' });
+const DB = process.env.DATABASE.replace('<PASSWORD>', process.env.DATABASE_PASSWORD);
+
+mongoose.connect(DB).then(async () => {
+  const p = await Product.findOne({ nameAr: { $regex: /صاروخ توتال 9 بوصة/ } });
+  if (p) {
+    console.log("Product Name:", p.nameAr);
+    console.log("imageCover:", p.imageCover);
+  } else {
+    console.log("Product not found");
+  }
+  process.exit();
+});

devData/list-providers.js

@@ -0,0 +1,15 @@
+const mongoose = require('mongoose');
+const dotenv = require('dotenv');
+const fs = require('fs');
+const Provider = require('../models/providerModel');
+
+dotenv.config({ path: './config.env' });
+
+const DB = process.env.DATABASE.replace('<PASSWORD>', process.env.DATABASE_PASSWORD);
+
+mongoose.connect(DB).then(async () => {
+  const all = await Provider.find({}, { storeName: 1, name: 1, id: 1 }).sort({ id: 1 }).lean();
+  fs.writeFileSync(__dirname + '/providers-dump.json', JSON.stringify(all, null, 2), 'utf-8');
+  console.log('Written to providers-dump.json');
+  process.exit();
+}).catch((err) => { console.error(err); process.exit(1); });

devData/products-sample.json

@@ -0,0 +1,448 @@
+[
+  {
+    "nameEn": "Cordless Drill 18V",
+    "nameAr": "مثقاب لاسلكي 18 فولت",
+    "descriptionEn": "High power cordless drill with two lithium batteries and fast charger.",
+    "descriptionAr": "مثقاب لاسلكي عالي القوة مع بطاريتين ليثيوم وشاحن سريع.",
+    "barCode": "100000000001",
+    "brand": "Bosch",
+    "category": "6908d121e0f022413d414ff9",
+    "provider": "Cairo Tools",
+    "available": true,
+    "quantity": 40,
+    "price": 1499,
+    "purchasePrice": 1100,
+    "salePrice": 1399,
+    "imageCover": "https://example.com/images/drill1.jpg",
+    "images": [
+      "https://example.com/images/drill1-1.jpg",
+      "https://example.com/images/drill1-2.jpg"
+    ],
+    "ratingsAverage": 4.6,
+    "ratingsQuantity": 18,
+    "addedAt": "2025-10-21T10:00:00Z"
+  },
+  {
+    "nameEn": "Impact Drill 750W",
+    "nameAr": "مثقاب صدمات 750 واط",
+    "descriptionEn": "Heavy-duty impact drill suitable for concrete and steel.",
+    "descriptionAr": "مثقاب قوي مناسب للخرسانة والفولاذ.",
+    "barCode": "100000000002",
+    "brand": "Makita",
+    "category": "6908d121e0f022413d414ff9",
+    "provider": "Alex Hardware",
+    "available": true,
+    "quantity": 25,
+    "price": 1799,
+    "purchasePrice": 1350,
+    "salePrice": 1699,
+    "imageCover": "https://example.com/images/impactdrill.jpg",
+    "images": [
+      "https://example.com/images/impactdrill-1.jpg"
+    ],
+    "ratingsAverage": 4.7,
+    "ratingsQuantity": 22,
+    "addedAt": "2025-10-21T10:00:00Z"
+  },
+  {
+    "nameEn": "Electric Screwdriver 12V",
+    "nameAr": "مفك كهربائي 12 فولت",
+    "descriptionEn": "Compact 12V electric screwdriver with adjustable torque.",
+    "descriptionAr": "مفك كهربائي مدمج بجهد 12 فولت مع عزم قابل للتعديل.",
+    "barCode": "100000000003",
+    "brand": "DeWalt",
+    "category": "6908d121e0f022413d414ff9",
+    "provider": "Delta Tools",
+    "available": true,
+    "quantity": 60,
+    "price": 899,
+    "purchasePrice": 650,
+    "salePrice": 850,
+    "imageCover": "https://example.com/images/screwdriver1.jpg",
+    "images": [
+      "https://example.com/images/screwdriver1-1.jpg"
+    ],
+    "ratingsAverage": 4.4,
+    "ratingsQuantity": 11,
+    "addedAt": "2025-10-21T10:00:00Z"
+  },
+  {
+    "nameEn": "Angle Grinder 1000W",
+    "nameAr": "صاروخ جلخ 1000 واط",
+    "descriptionEn": "High-speed angle grinder ideal for metal cutting and polishing.",
+    "descriptionAr": "صاروخ جلخ عالي السرعة مثالي لقطع المعادن والتلميع.",
+    "barCode": "100000000004",
+    "brand": "Black+Decker",
+    "category": "6908d121e0f022413d414ff9",
+    "provider": "PowerPro Supplies",
+    "available": true,
+    "quantity": 35,
+    "price": 1199,
+    "purchasePrice": 880,
+    "salePrice": 1099,
+    "imageCover": "https://example.com/images/grinder.jpg",
+    "images": [
+      "https://example.com/images/grinder-1.jpg"
+    ],
+    "ratingsAverage": 4.5,
+    "ratingsQuantity": 14,
+    "addedAt": "2025-10-21T10:00:00Z"
+  },
+  {
+    "nameEn": "Circular Saw 1400W",
+    "nameAr": "منشار دائري 1400 واط",
+    "descriptionEn": "Powerful circular saw for wood and plastic materials.",
+    "descriptionAr": "منشار دائري قوي للخشب والمواد البلاستيكية.",
+    "barCode": "100000000005",
+    "brand": "Makita",
+    "category": "6908d121e0f022413d414ff9",
+    "provider": "Delta Tools",
+    "available": true,
+    "quantity": 20,
+    "price": 2299,
+    "purchasePrice": 1800,
+    "salePrice": 2199,
+    "imageCover": "https://example.com/images/saw1.jpg",
+    "images": [
+      "https://example.com/images/saw1-1.jpg"
+    ],
+    "ratingsAverage": 4.8,
+    "ratingsQuantity": 16,
+    "addedAt": "2025-10-21T10:00:00Z"
+  },
+  {
+    "nameEn": "Hammer Drill 900W",
+    "nameAr": "مثقاب مطرقي 900 واط",
+    "descriptionEn": "Powerful hammer drill with dual speed and metal case.",
+    "descriptionAr": "مثقاب مطرقي قوي بسرعتين وهيكل معدني.",
+    "barCode": "100000000006",
+    "brand": "Bosch",
+    "category": "6908d121e0f022413d414ff9",
+    "provider": "Cairo Tools",
+    "available": true,
+    "quantity": 18,
+    "price": 1999,
+    "purchasePrice": 1550,
+    "salePrice": 1899,
+    "imageCover": "https://example.com/images/hammerdrill.jpg",
+    "images": [
+      "https://example.com/images/hammerdrill-1.jpg"
+    ],
+    "ratingsAverage": 4.7,
+    "ratingsQuantity": 20,
+    "addedAt": "2025-10-21T10:00:00Z"
+  },
+  {
+    "nameEn": "Bench Grinder 150mm",
+    "nameAr": "صاروخ طاولة 150مم",
+    "descriptionEn": "Durable bench grinder for sharpening and shaping tools.",
+    "descriptionAr": "صاروخ طاولة متين لشحذ وتشكيل الأدوات.",
+    "barCode": "100000000007",
+    "brand": "Stanley",
+    "category": "6908d121e0f022413d414ff9",
+    "provider": "PowerPro Supplies",
+    "available": true,
+    "quantity": 15,
+    "price": 999,
+    "purchasePrice": 750,
+    "salePrice": 950,
+    "imageCover": "https://example.com/images/benchgrinder.jpg",
+    "images": [
+      "https://example.com/images/benchgrinder-1.jpg"
+    ],
+    "ratingsAverage": 4.3,
+    "ratingsQuantity": 9,
+    "addedAt": "2025-10-21T10:00:00Z"
+  },
+  {
+    "nameEn": "Heat Gun 2000W",
+    "nameAr": "مسدس حراري 2000 واط",
+    "descriptionEn": "Adjustable temperature heat gun for paint stripping and welding.",
+    "descriptionAr": "مسدس حراري بدرجة حرارة قابلة للتعديل لإزالة الطلاء واللحام.",
+    "barCode": "100000000008",
+    "brand": "Bosch",
+    "category": "6908d121e0f022413d414ff9",
+    "provider": "ToolMaster",
+    "available": true,
+    "quantity": 30,
+    "price": 899,
+    "purchasePrice": 650,
+    "salePrice": 850,
+    "imageCover": "https://example.com/images/heatgun.jpg",
+    "images": [
+      "https://example.com/images/heatgun-1.jpg"
+    ],
+    "ratingsAverage": 4.4,
+    "ratingsQuantity": 13,
+    "addedAt": "2025-10-21T10:00:00Z"
+  },
+  {
+    "nameEn": "Electric Planer 600W",
+    "nameAr": "مِسحَج كهربائي 600 واط",
+    "descriptionEn": "Smooth surface planer for carpentry and woodworking.",
+    "descriptionAr": "مِسحَج كهربائي لنعومة الأسطح في أعمال النجارة.",
+    "barCode": "100000000009",
+    "brand": "Makita",
+    "category": "6908d121e0f022413d414ff9",
+    "provider": "Alex Hardware",
+    "available": true,
+    "quantity": 25,
+    "price": 1299,
+    "purchasePrice": 950,
+    "salePrice": 1199,
+    "imageCover": "https://example.com/images/planer.jpg",
+    "images": [
+      "https://example.com/images/planer-1.jpg"
+    ],
+    "ratingsAverage": 4.5,
+    "ratingsQuantity": 15,
+    "addedAt": "2025-10-21T10:00:00Z"
+  },
+  {
+    "nameEn": "Air Compressor 24L",
+    "nameAr": "كمبروسر هواء 24 لتر",
+    "descriptionEn": "Portable air compressor with 24-liter tank and pressure gauge.",
+    "descriptionAr": "كمبروسر هواء محمول بخزان سعة 24 لتر ومقياس ضغط.",
+    "barCode": "100000000010",
+    "brand": "Stanley",
+    "category": "6908d121e0f022413d414ff9",
+    "provider": "Cairo Tools",
+    "available": true,
+    "quantity": 10,
+    "price": 2999,
+    "purchasePrice": 2500,
+    "salePrice": 2899,
+    "imageCover": "https://example.com/images/compressor.jpg",
+    "images": [
+      "https://example.com/images/compressor-1.jpg"
+    ],
+    "ratingsAverage": 4.8,
+    "ratingsQuantity": 27,
+    "addedAt": "2025-10-21T10:00:00Z"
+  },
+  {
+    "nameEn": "Cordless Screwdriver Set",
+    "nameAr": "طقم مفكات لاسلكية",
+    "descriptionEn": "Rechargeable screwdriver set with 30 bits and LED light.",
+    "descriptionAr": "طقم مفكات لاسلكية قابلة للشحن مع 30 رأس و ضوء LED.",
+    "barCode": "100000000011",
+    "brand": "Black+Decker",
+    "category": "6908d121e0f022413d414ff9",
+    "provider": "Delta Tools",
+    "available": true,
+    "quantity": 50,
+    "price": 699,
+    "purchasePrice": 480,
+    "salePrice": 650,
+    "imageCover": "https://example.com/images/screwset.jpg",
+    "images": [
+      "https://example.com/images/screwset-1.jpg"
+    ],
+    "ratingsAverage": 4.6,
+    "ratingsQuantity": 10,
+    "addedAt": "2025-10-21T10:00:00Z"
+  },
+  {
+    "nameEn": "Mini Grinder 500W",
+    "nameAr": "صاروخ صغير 500 واط",
+    "descriptionEn": "Lightweight mini grinder for detailed cutting and polishing work.",
+    "descriptionAr": "صاروخ صغير خفيف لعمليات القطع والتلميع الدقيقة.",
+    "barCode": "100000000012",
+    "brand": "Bosch",
+    "category": "6908d121e0f022413d414ff9",
+    "provider": "ToolMaster",
+    "available": true,
+    "quantity": 28,
+    "price": 799,
+    "purchasePrice": 600,
+    "salePrice": 750,
+    "imageCover": "https://example.com/images/minigrinder.jpg",
+    "images": [
+      "https://example.com/images/minigrinder-1.jpg"
+    ],
+    "ratingsAverage": 4.5,
+    "ratingsQuantity": 8,
+    "addedAt": "2025-10-21T10:00:00Z"
+  },
+  {
+    "nameEn": "Jigsaw 650W",
+    "nameAr": "منشار ترددي 650 واط",
+    "descriptionEn": "Variable-speed jigsaw ideal for curved and straight cuts.",
+    "descriptionAr": "منشار ترددي بسرعة متغيرة مثالي للقطع المستقيم والمنحني.",
+    "barCode": "100000000013",
+    "brand": "DeWalt",
+    "category": "6908d121e0f022413d414ff9",
+    "provider": "Alex Hardware",
+    "available": true,
+    "quantity": 17,
+    "price": 1599,
+    "purchasePrice": 1200,
+    "salePrice": 1499,
+    "imageCover": "https://example.com/images/jigsaw.jpg",
+    "images": [
+      "https://example.com/images/jigsaw-1.jpg"
+    ],
+    "ratingsAverage": 4.6,
+    "ratingsQuantity": 12,
+    "addedAt": "2025-10-21T10:00:00Z"
+  },
+  {
+    "nameEn": "Cordless Grinder 20V",
+    "nameAr": "صاروخ لاسلكي 20 فولت",
+    "descriptionEn": "Cordless grinder with brushless motor and fast charging battery.",
+    "descriptionAr": "صاروخ لاسلكي بمحرك بدون فُرش وبطارية شحن سريع.",
+    "barCode": "100000000014",
+    "brand": "Makita",
+    "category": "6908d121e0f022413d414ff9",
+    "provider": "Cairo Tools",
+    "available": true,
+    "quantity": 12,
+    "price": 2499,
+    "purchasePrice": 2000,
+    "salePrice": 2399,
+    "imageCover": "https://example.com/images/cordlessgrinder.jpg",
+    "images": [
+      "https://example.com/images/cordlessgrinder-1.jpg"
+    ],
+    "ratingsAverage": 4.9,
+    "ratingsQuantity": 25,
+    "addedAt": "2025-10-21T10:00:00Z"
+  },
+  {
+    "nameEn": "Rotary Hammer 1200W",
+    "nameAr": "مثقاب مطرقي دوار 1200 واط",
+    "descriptionEn": "Professional rotary hammer for drilling through concrete and stone.",
+    "descriptionAr": "مثقاب مطرقي دوار احترافي للحفر في الخرسانة والحجر.",
+    "barCode": "100000000015",
+    "brand": "Bosch",
+    "category": "6908d121e0f022413d414ff9",
+    "provider": "ToolMaster",
+    "available": true,
+    "quantity": 9,
+    "price": 2799,
+    "purchasePrice": 2200,
+    "salePrice": 2699,
+    "imageCover": "https://example.com/images/rotaryhammer.jpg",
+    "images": [
+      "https://example.com/images/rotaryhammer-1.jpg"
+    ],
+    "ratingsAverage": 4.8,
+    "ratingsQuantity": 20,
+    "addedAt": "2025-10-21T10:00:00Z"
+  },
+  {
+    "nameEn": "Electric Sander 300W",
+    "nameAr": "صنفرة كهربائية 300 واط",
+    "descriptionEn": "Orbital sander with dust collector for clean finish.",
+    "descriptionAr": "صنفرة دائرية مزودة بجامع غبار لتشطيب نظيف.",
+    "barCode": "100000000016",
+    "brand": "Stanley",
+    "category": "6908d121e0f022413d414ff9",
+    "provider": "PowerPro Supplies",
+    "available": true,
+    "quantity": 22,
+    "price": 999,
+    "purchasePrice": 700,
+    "salePrice": 950,
+    "imageCover": "https://example.com/images/sander.jpg",
+    "images": [
+      "https://example.com/images/sander-1.jpg"
+    ],
+    "ratingsAverage": 4.5,
+    "ratingsQuantity": 14,
+    "addedAt": "2025-10-21T10:00:00Z",
+    "isFeatured": true
+  },
+  {
+    "nameEn": "Laser Distance Meter 40m",
+    "nameAr": "جهاز قياس مسافة ليزر 40م",
+    "descriptionEn": "Accurate laser distance meter for construction and decoration.",
+    "descriptionAr": "جهاز قياس ليزر دقيق للبناء والديكور.",
+    "barCode": "100000000017",
+    "brand": "Bosch",
+    "category": "6908d121e0f022413d414ff9",
+    "provider": "Delta Tools",
+    "available": true,
+    "quantity": 30,
+    "price": 899,
+    "purchasePrice": 650,
+    "salePrice": 850,
+    "imageCover": "https://example.com/images/laser.jpg",
+    "images": [
+      "https://example.com/images/laser-1.jpg"
+    ],
+    "ratingsAverage": 4.7,
+    "ratingsQuantity": 18,
+    "addedAt": "2025-10-21T10:00:00Z",
+    "isFeatured": true
+  },
+  {
+    "nameEn": "Cordless Nail Gun 18V",
+    "nameAr": "مسدس مسامير لاسلكي 18 فولت",
+    "descriptionEn": "Battery-powered nail gun for furniture and woodwork.",
+    "descriptionAr": "مسدس مسامير يعمل بالبطارية لأعمال الأثاث والنجارة.",
+    "barCode": "100000000018",
+    "brand": "DeWalt",
+    "category": "6908d121e0f022413d414ff9",
+    "provider": "Cairo Tools",
+    "available": true,
+    "quantity": 15,
+    "price": 2599,
+    "purchasePrice": 2100,
+    "salePrice": 2499,
+    "imageCover": "https://example.com/images/nailgun.jpg",
+    "images": [
+      "https://example.com/images/nailgun-1.jpg"
+    ],
+    "ratingsAverage": 4.8,
+    "ratingsQuantity": 22,
+    "addedAt": "2025-10-21T10:00:00Z",
+    "isFeatured": true
+  },
+  {
+    "nameEn": "Electric Chainsaw 1800W",
+    "nameAr": "منشار كهربائي 1800 واط",
+    "descriptionEn": "Fast-cutting electric chainsaw for garden and construction.",
+    "descriptionAr": "منشار كهربائي سريع القطع للحدائق وأعمال البناء.",
+    "barCode": "100000000019",
+    "brand": "Makita",
+    "category": "6908d121e0f022413d414ff9",
+    "provider": "PowerPro Supplies",
+    "available": true,
+    "quantity": 14,
+    "price": 2199,
+    "purchasePrice": 1800,
+    "salePrice": 2099,
+    "imageCover": "https://example.com/images/chainsaw.jpg",
+    "images": [
+      "https://example.com/images/chainsaw-1.jpg"
+    ],
+    "ratingsAverage": 4.6,
+    "ratingsQuantity": 16,
+    "addedAt": "2025-10-21T10:00:00Z",
+    "isFeatured": true
+  },
+  {
+    "nameEn": "Tile Cutter 800W",
+    "nameAr": "قاطع بلاط 800 واط",
+    "descriptionEn": "Precision electric tile cutter with water cooling.",
+    "descriptionAr": "قاطع بلاط كهربائي دقيق مع تبريد مائي.",
+    "barCode": "100000000020",
+    "brand": "Bosch",
+    "category": "6908d121e0f022413d414ff9",
+    "provider": "Alex Hardware",
+    "available": true,
+    "quantity": 12,
+    "price": 1899,
+    "purchasePrice": 1500,
+    "salePrice": 1799,
+    "imageCover": "https://example.com/images/tilecutter.jpg",
+    "images": [
+      "https://example.com/images/tilecutter-1.jpg"
+    ],
+    "ratingsAverage": 4.7,
+    "ratingsQuantity": 15,
+    "addedAt": "2025-10-21T10:00:00Z",
+    "isFeatured": true
+  }
+]

devData/providers-dump.json

@@ -0,0 +1,14 @@
+[
+  {
+    "_id": "69cf17ca5c8342eaac72b15e",
+    "name": "amr tag",
+    "storeName": "سنتر المنصورة",
+    "id": 1
+  },
+  {
+    "_id": "69cf18bb5c8342eaac72b29a",
+    "name": "mohamed moawad",
+    "storeName": "وكالة العدد",
+    "id": 2
+  }
+]

devData/shift-products.js

@@ -0,0 +1,64 @@
+const mongoose = require('mongoose');
+const dotenv = require('dotenv');
+const Product = require('../models/productModel');
+const Provider = require('../models/providerModel');
+
+dotenv.config({ path: './config.env' });
+const DB = process.env.DATABASE.replace('<PASSWORD>', process.env.DATABASE_PASSWORD);
+
+mongoose.connect(DB).then(async () => {
+  console.log('DB connection successful!\n');
+
+  try {
+    const samoulla = await Provider.findOne({ storeName: { $regex: /samoulla|صمولة/i } });
+    const center = await Provider.findOne({ storeName: 'سنتر المنصورة' });
+    const wekalt = await Provider.findOne({ storeName: 'وكالة العدد' });
+
+    if (!samoulla || !center || !wekalt) {
+      console.log('Could not find one of the providers. Aborting.');
+      process.exit(1);
+    }
+
+    console.log('--- Current Product Counts ---');
+    const centerCount = await Product.countDocuments({ provider: center._id });
+    const wekaltCount = await Product.countDocuments({ provider: wekalt._id });
+    const samoullaCount = await Product.countDocuments({ provider: samoulla._id });
+    console.log(`Samoulla: ${samoullaCount} products`);
+    console.log(`Center El Mansoura: ${centerCount} products`);
+    console.log(`Wekalt El 3edad: ${wekaltCount} products\n`);
+
+    console.log('--- Shifting Products ---');
+
+    // 1. Move Center products -> Samoulla
+    if (centerCount > 0) {
+      const result1 = await Product.updateMany(
+        { provider: center._id },
+        { provider: samoulla._id }
+      );
+      console.log(`Moved ${result1.modifiedCount} products from Center El Mansoura to Samoulla`);
+    }
+
+    // 2. Move Wekalt products -> Center
+    if (wekaltCount > 0) {
+      const result2 = await Product.updateMany(
+        { provider: wekalt._id },
+        { provider: center._id }
+      );
+      console.log(`Moved ${result2.modifiedCount} products from Wekalt El 3edad to Center El Mansoura`);
+    }
+
+    console.log('\n--- Final Product Counts ---');
+    const newCenterCount = await Product.countDocuments({ provider: center._id });
+    const newWekaltCount = await Product.countDocuments({ provider: wekalt._id });
+    const newSamoullaCount = await Product.countDocuments({ provider: samoulla._id });
+    
+    console.log(`Samoulla (ID 1): ${newSamoullaCount} products`);
+    console.log(`Center El Mansoura (ID 2): ${newCenterCount} products`);
+    console.log(`Wekalt El 3edad (ID 3): ${newWekaltCount} products`);
+
+    console.log('\n✅ Products successfully shifted!');
+  } catch (err) {
+    console.error('Error:', err);
+  }
+  process.exit();
+}).catch((err) => { console.error(err); process.exit(1); });

devData/test-precise.js

@@ -0,0 +1,28 @@
+const https = require('https');
+
+const urls = [
+  'https://res.cloudinary.com/dm9ym99zh/image/upload/v1771515557/samoulla/products/6996da5201c93defc57509d4/cover-1771515557455.jpg',
+  'https://res.cloudinary.com/dm9ym99zh/image/upload/f_webp,q_auto,w_800,c_fill/v1771515557/samoulla/products/6996da5201c93defc57509d4/cover-1771515557455.jpg'
+];
+
+function check(url) {
+  return new Promise((resolve) => {
+    https.get(url, (res) => {
+      console.log(`URL: ${url}`);
+      console.log(`Status: ${res.statusCode}`);
+      resolve();
+    }).on('error', (err) => {
+      console.log(`URL: ${url}`);
+      console.log(`Error: ${err.message}`);
+      resolve();
+    });
+  });
+}
+
+async function run() {
+  for (const url of urls) {
+    await check(url);
+  }
+}
+
+run();

image-formats.json

@@ -0,0 +1,5 @@
+{
+  "cloudinary": 1036,
+  "other_http": 6,
+  "base64": 1
+}

middlewares/audioUploadMiddleware.js

@@ -0,0 +1,38 @@
+const multer = require('multer');
+
+const storage = multer.memoryStorage();
+
+const allowedMimeTypes = new Set([
+  'audio/webm',
+  'audio/wav',
+  'audio/mpeg',
+  'audio/mp4',
+  'audio/x-m4a',
+  'audio/ogg',
+]);
+
+const fileFilter = (req, file, cb) => {
+  const mimeType = (file && file.mimetype) || '';
+  const isKnownAudioType = allowedMimeTypes.has(mimeType);
+  const isAnyAudioSubtype =
+    typeof mimeType === 'string' && mimeType.startsWith('audio/');
+
+  if (isKnownAudioType || isAnyAudioSubtype) {
+    cb(null, true);
+  } else {
+    cb(
+      new Error('Only audio files are allowed for voice transcription.'),
+      false,
+    );
+  }
+};
+
+const audioUpload = multer({
+  storage,
+  fileFilter,
+  limits: {
+    fileSize: 10 * 1024 * 1024,
+  },
+});
+
+module.exports = audioUpload;

middlewares/authMiddleware.js

@@ -0,0 +1,180 @@
+const User = require('../models/userModel');
+
+// Middleware to restrict access to specific roles
+exports.restrictTo = (...roles) => {
+  return (req, res, next) => {
+    // req.user is set by the protect middleware
+    if (!req.user) {
+      return res.status(401).json({
+        status: 'fail',
+        message: 'You must be logged in to access this resource',
+      });
+    }
+
+    if (!roles.includes(req.user.role)) {
+      return res.status(403).json({
+        status: 'fail',
+        message: 'You do not have permission to perform this action',
+      });
+    }
+
+    next();
+  };
+};
+
+// Middleware to check if user has a specific permission (for employees)
+// Can accept a single permission string or an array of permissions
+exports.checkPermission = (...permissions) => {
+  return (req, res, next) => {
+    if (!req.user) {
+      return res.status(401).json({
+        status: 'fail',
+        message: 'You must be logged in to access this resource',
+      });
+    }
+
+    // Admins have all permissions
+    if (req.user.role === 'admin') {
+      return next();
+    }
+
+    // Special case: Vendors are implicitly allowed to manage products and update fulfillment
+    const userRole = (req.user.role || '').toLowerCase();
+
+    const vendorPermissions = ['manage_products', 'update_item_fulfillment'];
+
+    // For vendors, if any of the required permissions are vendor-implicit, allow it
+    if (userRole === 'vendor') {
+      const hasVendorImplicit = permissions.some((perm) =>
+        vendorPermissions.includes(perm),
+      );
+      if (hasVendorImplicit) return next();
+    }
+
+    // Check if user has ANY of the required permissions
+    const userPermissions = req.user.permissions || [];
+    const hasPermission = permissions.some((perm) =>
+      userPermissions.includes(perm),
+    );
+
+    if (!hasPermission) {
+      return res.status(403).json({
+        status: 'fail',
+        message: `You do not have the required permissions to perform this action. Required: ${permissions.join(' or ')}`,
+      });
+    }
+
+    next();
+  };
+};
+
+// Middleware to verify vendor owns the resource
+exports.isVendorOwner = (resourceType) => {
+  return async (req, res, next) => {
+    if (!req.user) {
+      return res.status(401).json({
+        status: 'fail',
+        message: 'You must be logged in to access this resource',
+      });
+    }
+
+    // Admins can access all resources
+    if (req.user.role === 'admin') {
+      return next();
+    }
+
+    // Only vendors need ownership verification
+    if (req.user.role !== 'vendor') {
+      return res.status(403).json({
+        status: 'fail',
+        message: 'This action is only available to vendors',
+      });
+    }
+
+    try {
+      let resource;
+      const resourceId = req.params.id;
+
+      // Load the resource based on type
+      if (resourceType === 'product') {
+        const Product = require('../models/productModel');
+        resource = await Product.findById(resourceId);
+      }
+      // Add more resource types as needed
+
+      if (!resource) {
+        return res.status(404).json({
+          status: 'fail',
+          message: `${resourceType} not found`,
+        });
+      }
+
+      // Check if vendor owns this resource
+      // Assuming products have a 'vendor' field that references the user
+      if (
+        resource.vendor &&
+        resource.vendor.toString() !== req.user._id.toString()
+      ) {
+        return res.status(403).json({
+          status: 'fail',
+          message: `You can only modify your own ${resourceType}s`,
+        });
+      }
+
+      next();
+    } catch (err) {
+      res.status(500).json({
+        status: 'error',
+        message: 'Error verifying resource ownership',
+        error: err.message,
+      });
+    }
+  };
+};
+
+// Middleware to ensure user account is active
+exports.isActiveUser = (req, res, next) => {
+  if (!req.user) {
+    return res.status(401).json({
+      status: 'fail',
+      message: 'You must be logged in to access this resource',
+    });
+  }
+
+  if (!req.user.isActive) {
+    return res.status(403).json({
+      status: 'fail',
+      message: 'Your account has been deactivated. Please contact support.',
+    });
+  }
+
+  next();
+};
+
+// Combined middleware: protect + isActive (commonly used together)
+exports.protectActive = async (req, res, next) => {
+  const { protect } = require('../controllers/authController');
+
+  // First run protect middleware
+  await new Promise((resolve, reject) => {
+    protect(req, res, (err) => {
+      if (err) reject(err);
+      else resolve();
+    });
+  }).catch((err) => {
+    return res.status(401).json({
+      status: 'fail',
+      message: 'Authentication failed',
+    });
+  });
+
+  // Then check if active
+  if (!req.user.isActive) {
+    return res.status(403).json({
+      status: 'fail',
+      message: 'Your account has been deactivated. Please contact support.',
+    });
+  }
+
+  next();
+};