Upload 46 files

src/app.js

@@ -15,6 +15,8 @@ const authRoutes = require("./routes/auth.routes");
 const courseRoutes = require("./routes/course.routes");
 const orderRoutes = require("./routes/order.routes");
 const adminRoutes = require("./routes/admin.routes");
+const voucherRoutes = require("./routes/voucher.routes");
+const webhookRoutes = require("./routes/webhook.routes");
 
 const app = express();
 
@@ -68,6 +70,14 @@ app.use(
 );
 
 app.use(compression());
+
+// Payoneer's webhook signature is computed over the exact raw request
+// body, so this route MUST be registered with a raw-body parser
+// BEFORE the global express.json() below — once express.json() has
+// run, the original bytes are gone and any signature check would
+// fail. See utils/payoneerCheckout.js -> verifyAndParseWebhook.
+app.use("/api/webhooks", express.raw({ type: "*/*", limit: "200kb" }), webhookRoutes);
+
 app.use(express.json({ limit: "100kb" })); // small limit: this API never needs large bodies
 app.use(express.urlencoded({ extended: true, limit: "100kb" }));
 
@@ -92,6 +102,7 @@ app.use("/api/auth", authRoutes);
 app.use("/api/courses", courseRoutes);
 app.use("/api/orders", orderRoutes);
 app.use("/api/admin", adminRoutes);
+app.use("/api/vouchers", voucherRoutes);
 
 app.use(notFound);
 app.use(errorHandler);

src/config/env.js

@@ -23,7 +23,10 @@ const env = {
     .split(",")
     .map((s) => s.trim())
     .filter(Boolean),
-
+  // Base URL used to build absolute redirect links (e.g. Payoneer
+  // Checkout success/cancel URLs) sent to third-party APIs — falls
+  // back to the first allowed CORS origin if not set explicitly.
+  frontendUrl: process.env.FRONTEND_URL || (process.env.CLIENT_ORIGINS || "http://localhost:5173").split(",")[0].trim(),
   mongoUri: process.env.MONGODB_URI,
 
   jwtAccessSecret: process.env.JWT_ACCESS_SECRET,
@@ -57,6 +60,19 @@ const env = {
     accountEmail: process.env.PAYONEER_ACCOUNT_EMAIL || "",
   },
 
+  // Payoneer Checkout (automated card/wallet checkout) — separate from
+  // the manual "payoneer" bank-style transfer above. These credentials
+  // are issued directly by Payoneer only after your business is
+  // approved as a Payoneer Checkout merchant; see
+  // utils/payoneerCheckout.js for what's still a placeholder pending
+  // that approval and your integration-specific API docs from them.
+  payoneerCheckout: {
+    apiBase: process.env.PAYONEER_CHECKOUT_API_BASE || "",
+    apiKey: process.env.PAYONEER_CHECKOUT_API_KEY || "",
+    apiSecret: process.env.PAYONEER_CHECKOUT_API_SECRET || "",
+    webhookSecret: process.env.PAYONEER_CHECKOUT_WEBHOOK_SECRET || "",
+  },
+
   seedAdmin: {
     name: process.env.SEED_ADMIN_NAME || "Site Admin",
     email: process.env.SEED_ADMIN_EMAIL,

src/controllers/admin.controller.js

@@ -1,9 +1,8 @@
-const mongoose = require("mongoose");
 const Order = require("../models/Order");
 const User = require("../models/User");
-const Course = require("../models/Course");
 const AuditLog = require("../models/AuditLog");
-const { sendPaymentConfirmedEmail, sendPaymentRejectedEmail } = require("../utils/email");
+const { sendPaymentRejectedEmail } = require("../utils/email");
+const { confirmOrderAndGrantAccess } = require("../utils/orderConfirmation");
 const logger = require("../utils/logger");
 
 async function listOrders(req, res, next) {
@@ -65,62 +64,21 @@ async function getOrderDetail(req, res, next) {
  * granted (or vice versa).
  */
 async function confirmOrder(req, res, next) {
-  const session = await mongoose.startSession();
   try {
-    let resultOrder;
-    let resultUser;
-    let course;
-
-    await session.withTransaction(async () => {
-      const order = await Order.findById(req.params.id).session(session);
-      if (!order) throw Object.assign(new Error("Order not found."), { status: 404 });
-      if (order.status === "confirmed") throw Object.assign(new Error("Order already confirmed."), { status: 409 });
-      if (!["awaiting_confirmation", "pending_payment"].includes(order.status)) {
-        throw Object.assign(new Error("Order cannot be confirmed from its current status."), { status: 409 });
-      }
-
-      order.status = "confirmed";
-      order.confirmedBy = req.user._id;
-      order.confirmedAt = new Date();
-      await order.save({ session });
-
-      const user = await User.findById(order.user).session(session);
-      if (!user) throw Object.assign(new Error("Associated user not found."), { status: 404 });
-
-      const alreadyEnrolled = user.enrolledCourses.some((ec) => ec.course.toString() === order.course.toString());
-      if (!alreadyEnrolled) {
-        user.enrolledCourses.push({ course: order.course, order: order._id, accessGrantedAt: new Date() });
-        await user.save({ session });
-      }
-
-      course = await Course.findById(order.course).session(session);
-      resultOrder = order;
-      resultUser = user;
-    });
+    const existing = await Order.findById(req.params.id);
+    if (!existing) return res.status(404).json({ error: "Order not found." });
+    if (existing.status === "confirmed") return res.status(409).json({ error: "Order already confirmed." });
 
-    await AuditLog.create({
-      actor: req.user._id,
-      actorEmail: req.user.email,
-      action: "admin.order_confirmed",
-      targetType: "Order",
-      targetId: resultOrder._id,
+    const { order } = await confirmOrderAndGrantAccess({
+      orderId: req.params.id,
+      confirmedBy: req.user._id,
       ip: req.ip,
       userAgent: req.headers["user-agent"],
-      metadata: { userId: resultUser._id.toString() },
     });
 
-    sendPaymentConfirmedEmail({
-      to: resultUser.email,
-      name: resultUser.name,
-      order: resultOrder,
-      courseTitle: course ? course.title : resultOrder.courseTitleSnapshot,
-    }).catch((err) => logger.error("Payment-confirmed email failed", { error: err.message }));
-
-    res.json({ order: resultOrder.toPublicJSON() });
+    res.json({ order: order.toPublicJSON() });
   } catch (err) {
     next(err);
-  } finally {
-    session.endSession();
   }
 }
 

src/controllers/content.controller.js

@@ -2,7 +2,14 @@ const fs = require("fs/promises");
 const mongoose = require("mongoose");
 const Course = require("../models/Course");
 const AuditLog = require("../models/AuditLog");
-const { uploadFromPath, deleteAsset, getSignedPlaybackUrl, resourceTypeForMimetype } = require("../utils/cloudinaryUpload");
+const {
+  uploadFromPath,
+  deleteAsset,
+  getSignedPlaybackUrl,
+  resourceTypeForMimetype,
+  uploadThumbnail: uploadThumbnailToCloudinary,
+  deleteThumbnail,
+} = require("../utils/cloudinaryUpload");
 const logger = require("../utils/logger");
 
 function userHasAccess(user, courseId) {
@@ -282,6 +289,53 @@ async function getCourseCurriculumForAdmin(req, res, next) {
   }
 }
 
+/**
+ * Admin uploads/replaces a course's marketing thumbnail (shown on the
+ * homepage "Our Academy" preview and the Academy catalogue page). If
+ * the course already had one, the old Cloudinary asset is deleted so
+ * replacing a thumbnail doesn't leave the previous image as an
+ * orphaned file in storage.
+ */
+async function uploadThumbnail(req, res, next) {
+  try {
+    const course = await Course.findById(req.params.id);
+    if (!course) return res.status(404).json({ error: "Course not found." });
+    if (!req.file) return res.status(400).json({ error: "No image file was uploaded." });
+
+    const previousPublicId = course.thumbnailPublicId;
+
+    const result = await uploadThumbnailToCloudinary(req.file.path, { filenameHint: course.slug });
+
+    course.image = result.secure_url;
+    course.thumbnailPublicId = result.public_id;
+    await course.save();
+
+    if (previousPublicId) {
+      deleteThumbnail(previousPublicId).catch((err) =>
+        logger.error("Failed to clean up replaced course thumbnail", { error: err.message, publicId: previousPublicId })
+      );
+    }
+
+    await AuditLog.create({
+      actor: req.user._id,
+      actorEmail: req.user.email,
+      action: "admin.course_thumbnail_uploaded",
+      targetType: "Course",
+      targetId: course._id,
+      ip: req.ip,
+      userAgent: req.headers["user-agent"],
+    });
+
+    res.json({ course });
+  } catch (err) {
+    next(err);
+  } finally {
+    if (req.file) {
+      fs.unlink(req.file.path).catch(() => {});
+    }
+  }
+}
+
 module.exports = {
   getCourseCurriculum,
   getLessonAccess,
@@ -292,4 +346,5 @@ module.exports = {
   uploadLesson,
   updateLesson,
   deleteLesson,
+  uploadThumbnail,
 };

src/controllers/course.controller.js

@@ -1,10 +1,43 @@
 const Course = require("../models/Course");
 
+/**
+ * Public course catalogue listing — powers both the homepage "Our
+ * Academy" preview and the full Academy page. Supports the category
+ * filter, free-text search, and pagination the Academy page needs,
+ * since the number of courses is expected to keep growing.
+ *
+ * Query params (all optional):
+ *   category  - one of Course.CATEGORIES, exact match
+ *   search    - matched against title/description (case-insensitive)
+ *   page      - 1-indexed, default 1
+ *   limit     - default 12, capped at 50 to avoid huge unbounded responses
+ */
 async function listCourses(req, res, next) {
   try {
     const filter = req.user?.role === "admin" ? {} : { isPublished: true };
-    const courses = await Course.find(filter).sort({ createdAt: 1 });
-    res.json({ courses });
+
+    if (req.query.category) {
+      filter.category = req.query.category;
+    }
+
+    if (req.query.search) {
+      const escaped = req.query.search.trim().replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      const pattern = new RegExp(escaped, "i");
+      filter.$or = [{ title: pattern }, { description: pattern }];
+    }
+
+    const page = Math.max(1, parseInt(req.query.page, 10) || 1);
+    const limit = Math.min(50, Math.max(1, parseInt(req.query.limit, 10) || 12));
+
+    const [courses, total] = await Promise.all([
+      Course.find(filter)
+        .sort({ createdAt: 1 })
+        .skip((page - 1) * limit)
+        .limit(limit),
+      Course.countDocuments(filter),
+    ]);
+
+    res.json({ courses, total, page, pages: Math.max(1, Math.ceil(total / limit)) });
   } catch (err) {
     next(err);
   }

src/controllers/order.controller.js

@@ -5,6 +5,7 @@ const AuditLog = require("../models/AuditLog");
 const { generateOrderNumber } = require("../utils/orderNumber");
 const { env } = require("../config/env");
 const { sendOrderPlacedEmail, sendAdminNewOrderAlert } = require("../utils/email");
+const payoneerCheckout = require("../utils/payoneerCheckout");
 const logger = require("../utils/logger");
 
 /**
@@ -107,9 +108,92 @@ async function createOrder(req, res, next) {
   }
 }
 
-/** Customer submits their bank wire reference / Payoneer transaction ID after paying. */
-async function submitPaymentProof(req, res, next) {
+/**
+ * Creates an Order plus a hosted Payoneer Checkout session for it, and
+ * returns the redirect URL along with a clear amount/tax/total
+ * breakdown — the frontend shows that breakdown to the buyer before
+ * sending them to Payoneer, per the transparency requirement.
+ *
+ * Unlike createOrder (used for the manual bank_wire/payoneer-reference
+ * flow), this never puts the order in "awaiting_confirmation" for a
+ * human to review — it stays "pending_payment" until Payoneer's
+ * webhook confirms the payment (see webhook.controller.js), at which
+ * point it's auto-confirmed and access is granted automatically.
+ */
+async function createPayoneerCheckoutSession(req, res, next) {
   try {
+    const { courseId } = req.body;
+
+    if (!mongoose.isValidObjectId(courseId)) {
+      return res.status(400).json({ error: "Invalid course selected." });
+    }
+
+    const course = await Course.findById(courseId);
+    if (!course || !course.isPublished) {
+      return res.status(404).json({ error: "Course not found or unavailable." });
+    }
+
+    if (req.user.hasAccessToCourse(course._id)) {
+      return res.status(409).json({ error: "You already have access to this course." });
+    }
+
+    const existingOpenOrder = await Order.findOne({
+      user: req.user._id,
+      course: course._id,
+      paymentMethod: "payoneer_checkout",
+      status: "pending_payment",
+    });
+    if (existingOpenOrder && existingOpenOrder.providerCheckoutUrl) {
+      return res.status(200).json({ order: existingOpenOrder.toPublicJSON(), reused: true });
+    }
+
+    const order = new Order({
+      orderNumber: generateOrderNumber(),
+      user: req.user._id,
+      course: course._id,
+      courseTitleSnapshot: course.title,
+      amount: course.price,
+      currency: course.currency || "USD",
+      paymentMethod: "payoneer_checkout",
+      status: "pending_payment",
+    });
+
+    const session = await payoneerCheckout.createCheckoutSession({
+      order,
+      course,
+      customerEmail: req.user.email,
+      customerName: req.user.name,
+      successUrl: `${env.frontendUrl}/academy/checkout/${order._id}?result=success`,
+      cancelUrl: `${env.frontendUrl}/academy/checkout/${order._id}?result=cancelled`,
+    });
+
+    order.providerSessionId = session.sessionId;
+    order.providerCheckoutUrl = session.checkoutUrl;
+    if (session.tax) {
+      order.taxAmount = session.tax.amount;
+      order.taxCurrency = session.tax.currency;
+    }
+    await order.save();
+
+    await AuditLog.create({
+      actor: req.user._id,
+      actorEmail: req.user.email,
+      action: "order.checkout_session_created",
+      targetType: "Order",
+      targetId: order._id,
+      ip: req.ip,
+      userAgent: req.headers["user-agent"],
+      metadata: { courseId: course._id.toString() },
+    });
+
+    res.status(201).json({ order: order.toPublicJSON() });
+  } catch (err) {
+    next(err);
+  }
+}
+
+/** Customer submits their bank wire reference / Payoneer transaction ID after paying. */
+async function submitPaymentProof(req, res, next) {  try {
     const { reference, note } = req.body;
     const order = await Order.findOne({ _id: req.params.id, user: req.user._id });
     if (!order) return res.status(404).json({ error: "Order not found." });
@@ -158,4 +242,11 @@ async function getMyOrder(req, res, next) {
   }
 }
 
-module.exports = { getPaymentOptions, createOrder, submitPaymentProof, listMyOrders, getMyOrder };
+module.exports = {
+  getPaymentOptions,
+  createOrder,
+  createPayoneerCheckoutSession,
+  submitPaymentProof,
+  listMyOrders,
+  getMyOrder,
+};

src/controllers/voucher.controller.js

@@ -0,0 +1,279 @@
+const mongoose = require("mongoose");
+const Voucher = require("../models/Voucher");
+const Order = require("../models/Order");
+const User = require("../models/User");
+const Course = require("../models/Course");
+const AuditLog = require("../models/AuditLog");
+const { generateOrderNumber } = require("../utils/orderNumber");
+const { generateVoucherCode } = require("../utils/voucherCode");
+const { sendVoucherRedeemedEmail } = require("../utils/email");
+const logger = require("../utils/logger");
+
+function normalizeEmails(emails) {
+  if (!Array.isArray(emails)) return [];
+  return [...new Set(emails.map((e) => String(e).toLowerCase().trim()).filter(Boolean))];
+}
+
+// ---------------------------------------------------------------------
+// Admin: create / list / inspect / deactivate vouchers
+// ---------------------------------------------------------------------
+
+/**
+ * Creates a voucher for a specific course. If no code is supplied, one is
+ * generated server-side (retried on the astronomically unlikely chance of
+ * a collision) so admins can just click "Generate" without inventing a
+ * code themselves.
+ */
+async function createVoucher(req, res, next) {
+  try {
+    const { courseId, code, maxRedemptions, restrictedToEmails, expiresAt, note } = req.body;
+
+    if (!mongoose.isValidObjectId(courseId)) {
+      return res.status(400).json({ error: "Invalid course selected." });
+    }
+    const course = await Course.findById(courseId);
+    if (!course) return res.status(404).json({ error: "Course not found." });
+
+    let finalCode = code ? String(code).toUpperCase().trim() : null;
+    if (finalCode) {
+      const existing = await Voucher.findOne({ code: finalCode });
+      if (existing) return res.status(409).json({ error: "That voucher code is already in use." });
+    } else {
+      for (let attempt = 0; attempt < 5 && !finalCode; attempt++) {
+        const candidate = generateVoucherCode();
+        // eslint-disable-next-line no-await-in-loop
+        const existing = await Voucher.findOne({ code: candidate });
+        if (!existing) finalCode = candidate;
+      }
+      if (!finalCode) {
+        return res.status(500).json({ error: "Could not generate a unique voucher code. Please try again." });
+      }
+    }
+
+    const voucher = await Voucher.create({
+      code: finalCode,
+      course: course._id,
+      createdBy: req.user._id,
+      maxRedemptions: maxRedemptions || 1,
+      restrictedToEmails: normalizeEmails(restrictedToEmails),
+      expiresAt: expiresAt || null,
+      note: note || "",
+    });
+
+    await AuditLog.create({
+      actor: req.user._id,
+      actorEmail: req.user.email,
+      action: "admin.voucher_created",
+      targetType: "Voucher",
+      targetId: voucher._id,
+      ip: req.ip,
+      userAgent: req.headers["user-agent"],
+      metadata: {
+        courseId: course._id.toString(),
+        maxRedemptions: voucher.maxRedemptions,
+        restrictedToEmails: voucher.restrictedToEmails,
+      },
+    });
+
+    res.status(201).json({ voucher: voucher.toAdminJSON() });
+  } catch (err) {
+    if (err && err.code === 11000) {
+      return res.status(409).json({ error: "That voucher code is already in use." });
+    }
+    next(err);
+  }
+}
+
+async function listVouchers(req, res, next) {
+  try {
+    const { courseId, active } = req.query;
+    const filter = {};
+    if (courseId && mongoose.isValidObjectId(courseId)) filter.course = courseId;
+    if (active === "true") filter.isActive = true;
+    if (active === "false") filter.isActive = false;
+
+    const vouchers = await Voucher.find(filter)
+      .sort({ createdAt: -1 })
+      .populate("course", "title")
+      .populate("redemptions.user", "name email");
+
+    res.json({
+      vouchers: vouchers.map((v) => ({
+        ...v.toAdminJSON(),
+        course: v.course ? { id: v.course._id, title: v.course.title } : null,
+        redemptions: v.redemptions.map((r) => ({
+          user: r.user ? { id: r.user._id, name: r.user.name, email: r.user.email } : null,
+          order: r.order,
+          redeemedAt: r.redeemedAt,
+        })),
+      })),
+    });
+  } catch (err) {
+    next(err);
+  }
+}
+
+async function getVoucher(req, res, next) {
+  try {
+    const voucher = await Voucher.findById(req.params.id)
+      .populate("course", "title")
+      .populate("redemptions.user", "name email");
+    if (!voucher) return res.status(404).json({ error: "Voucher not found." });
+
+    res.json({
+      voucher: {
+        ...voucher.toAdminJSON(),
+        course: voucher.course ? { id: voucher.course._id, title: voucher.course.title } : null,
+        redemptions: voucher.redemptions.map((r) => ({
+          user: r.user ? { id: r.user._id, name: r.user.name, email: r.user.email } : null,
+          order: r.order,
+          redeemedAt: r.redeemedAt,
+        })),
+      },
+    });
+  } catch (err) {
+    next(err);
+  }
+}
+
+function makeSetVoucherActiveHandler(isActive) {
+  return async function handler(req, res, next) {
+    try {
+      const voucher = await Voucher.findById(req.params.id);
+      if (!voucher) return res.status(404).json({ error: "Voucher not found." });
+
+      voucher.isActive = isActive;
+      await voucher.save();
+
+      await AuditLog.create({
+        actor: req.user._id,
+        actorEmail: req.user.email,
+        action: isActive ? "admin.voucher_reactivated" : "admin.voucher_deactivated",
+        targetType: "Voucher",
+        targetId: voucher._id,
+        ip: req.ip,
+        userAgent: req.headers["user-agent"],
+      });
+
+      res.json({ voucher: voucher.toAdminJSON() });
+    } catch (err) {
+      next(err);
+    }
+  };
+}
+
+const deactivateVoucher = makeSetVoucherActiveHandler(false);
+const reactivateVoucher = makeSetVoucherActiveHandler(true);
+
+// ---------------------------------------------------------------------
+// User: redeem a voucher code for free course access
+// ---------------------------------------------------------------------
+
+/**
+ * Redeeming a voucher mirrors utils/orderConfirmation.js's
+ * confirmOrderAndGrantAccess: it produces a real (already-confirmed,
+ * zero-amount) Order so the course shows up consistently in "my
+ * orders"/admin reporting, and grants access the same way a paid order
+ * would. Wrapped in a transaction so the order, the user's enrolment,
+ * and the voucher's redemption count can never drift out of sync.
+ */
+async function redeemVoucher(req, res, next) {
+  const { code } = req.body;
+  const normalizedCode = String(code || "")
+    .toUpperCase()
+    .trim();
+
+  const session = await mongoose.startSession();
+  try {
+    let resultOrder;
+    let resultCourse;
+    let blockReason;
+
+    await session.withTransaction(async () => {
+      const voucher = await Voucher.findOne({ code: normalizedCode }).session(session);
+      if (!voucher) {
+        blockReason = "That voucher code isn't valid.";
+        return;
+      }
+
+      const course = await Course.findById(voucher.course).session(session);
+      if (!course || !course.isPublished) {
+        blockReason = "That voucher's course is no longer available.";
+        return;
+      }
+
+      if (req.user.hasAccessToCourse(course._id)) {
+        blockReason = "You already have access to this course.";
+        return;
+      }
+
+      const reason = voucher.redemptionBlockReason(req.user);
+      if (reason) {
+        blockReason = reason;
+        return;
+      }
+
+      const order = new Order({
+        orderNumber: generateOrderNumber(),
+        user: req.user._id,
+        course: course._id,
+        courseTitleSnapshot: course.title,
+        amount: 0,
+        currency: course.currency || "USD",
+        paymentMethod: "voucher",
+        voucher: voucher._id,
+        status: "confirmed",
+        confirmedAt: new Date(),
+      });
+      await order.save({ session });
+
+      const user = await User.findById(req.user._id).session(session);
+      user.enrolledCourses.push({ course: course._id, order: order._id, accessGrantedAt: new Date() });
+      await user.save({ session });
+
+      voucher.redemptions.push({ user: user._id, order: order._id, redeemedAt: new Date() });
+      await voucher.save({ session });
+
+      resultOrder = order;
+      resultCourse = course;
+    });
+
+    if (blockReason) {
+      return res.status(409).json({ error: blockReason });
+    }
+
+    await AuditLog.create({
+      actor: req.user._id,
+      actorEmail: req.user.email,
+      action: "voucher.redeemed",
+      targetType: "Order",
+      targetId: resultOrder._id,
+      ip: req.ip,
+      userAgent: req.headers["user-agent"],
+      metadata: { courseId: resultCourse._id.toString(), voucherCode: normalizedCode },
+    });
+
+    sendVoucherRedeemedEmail({
+      to: req.user.email,
+      name: req.user.name,
+      order: resultOrder,
+      courseTitle: resultCourse.title,
+      voucherCode: normalizedCode,
+    }).catch((err) => logger.error("Voucher-redeemed email failed", { error: err.message }));
+
+    res.status(201).json({ order: resultOrder.toPublicJSON() });
+  } catch (err) {
+    next(err);
+  } finally {
+    session.endSession();
+  }
+}
+
+module.exports = {
+  createVoucher,
+  listVouchers,
+  getVoucher,
+  deactivateVoucher,
+  reactivateVoucher,
+  redeemVoucher,
+};

src/controllers/webhook.controller.js

@@ -0,0 +1,71 @@
+const Order = require("../models/Order");
+const payoneerCheckout = require("../utils/payoneerCheckout");
+const { confirmOrderAndGrantAccess } = require("../utils/orderConfirmation");
+const logger = require("../utils/logger");
+
+// PAYONEER-DOCS-NEEDED: confirm the actual header name Payoneer sends
+// the webhook signature in — this is a placeholder guess following
+// common convention (e.g. Stripe uses "Stripe-Signature").
+const SIGNATURE_HEADER = "x-payoneer-signature";
+
+/**
+ * Receives Payoneer Checkout's payment-status webhook and, on a
+ * successful payment, automatically confirms the matching Order and
+ * grants the buyer access — no admin involved, unlike the manual
+ * bank_wire/payoneer-reference flow.
+ *
+ * Registered in app.js with a raw body parser (see
+ * routes/webhook.routes.js) so `req.body` here is the exact raw
+ * bytes Payoneer signed, not the parsed JSON the rest of the app uses.
+ *
+ * Always responds 200 once the webhook is understood (even for a
+ * "not our order" or "already confirmed" case) so Payoneer doesn't
+ * keep retrying a webhook we've already handled. Only a genuinely bad
+ * signature or unreadable payload gets a 4xx.
+ */
+async function handlePayoneerWebhook(req, res) {
+  let parsed;
+  try {
+    parsed = payoneerCheckout.verifyAndParseWebhook({
+      rawBody: req.body,
+      signatureHeader: req.headers[SIGNATURE_HEADER],
+    });
+  } catch (err) {
+    logger.error("Payoneer webhook rejected", { error: err.message });
+    return res.status(err.status || 400).json({ error: "Invalid webhook." });
+  }
+
+  try {
+    if (parsed.status !== "paid") {
+      // Payoneer also sends non-success events (failed, cancelled,
+      // pending, etc.) — nothing to do for those except acknowledge.
+      logger.info("Payoneer webhook received (non-paid status, no action)", { status: parsed.status });
+      return res.status(200).json({ received: true });
+    }
+
+    const order = await Order.findOne({ providerSessionId: parsed.sessionId, paymentMethod: "payoneer_checkout" });
+    if (!order) {
+      logger.error("Payoneer webhook: no matching order for session", { sessionId: parsed.sessionId });
+      // Still 200 — this is Payoneer's event, not a request we want retried forever.
+      return res.status(200).json({ received: true, matched: false });
+    }
+
+    const { alreadyConfirmed } = await confirmOrderAndGrantAccess({ orderId: order._id, confirmedBy: null });
+
+    logger.info("Payoneer webhook: order auto-confirmed", {
+      orderId: order._id.toString(),
+      alreadyConfirmed,
+    });
+
+    res.status(200).json({ received: true, matched: true });
+  } catch (err) {
+    logger.error("Payoneer webhook processing failed", { error: err.message });
+    // 200 anyway: a bug on our side confirming the order shouldn't
+    // cause Payoneer to hammer us with retries for an event we did
+    // successfully authenticate and understand. This case should
+    // instead be caught by monitoring your server logs.
+    res.status(200).json({ received: true, error: "processing_failed" });
+  }
+}
+
+module.exports = { handlePayoneerWebhook };

src/middleware/rateLimiters.js

@@ -28,4 +28,16 @@ const orderLimiter = rateLimit({
   message: { error: "Too many order attempts. Please try again later or contact support." },
 });
 
-module.exports = { apiLimiter, authLimiter, orderLimiter };
+// Voucher codes are bearer credentials, so redemption attempts are rate
+// limited per client the same way login attempts are, to blunt brute
+// forcing/guessing of codes.
+const voucherRedeemLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000,
+  limit: 15,
+  standardHeaders: true,
+  legacyHeaders: false,
+  skipSuccessfulRequests: true,
+  message: { error: "Too many voucher attempts. Please wait a few minutes and try again." },
+});
+
+module.exports = { apiLimiter, authLimiter, orderLimiter, voucherRedeemLimiter };

src/models/Course.js

@@ -1,4 +1,15 @@
-const mongoose = require("mongoose");
+const mongoose = require("mongoose");
+
+const CATEGORIES = [
+  "Artificial Intelligence",
+  "Cloud Computing",
+  "Quantum Computing",
+  "Cyber Security",
+  "Networking",
+  "Systems Engineering",
+  "Professional Ethics",
+  "Robotics",
+];
 
 const lessonSchema = new mongoose.Schema(
   {
@@ -50,7 +61,18 @@ const courseSchema = new mongoose.Schema(
     duration: { type: String, required: true, trim: true },
     level: { type: String, required: true, trim: true },
     description: { type: String, required: true },
+    category: { type: String, enum: CATEGORIES, required: true, index: true },
+
+    // Marketing thumbnail shown on the homepage "Our Academy" preview and
+    // on the Academy catalogue page. Uploaded by an admin as an actual
+    // image file (see content.controller.js -> uploadThumbnail), stored
+    // in Cloudinary as a plain PUBLIC asset (type: "upload") — unlike
+    // lesson videos/documents, a thumbnail is meant to be publicly
+    // visible to any visitor browsing the storefront, so it deliberately
+    // does NOT use the authenticated/signed-URL scheme those use.
     image: { type: String, default: "" },
+    thumbnailPublicId: { type: String, default: "" },
+
     highlights: { type: [String], default: [] },
     isPublished: { type: Boolean, default: true },
 
@@ -100,5 +122,6 @@ courseSchema.methods.toLockedCurriculumJSON = function toLockedCurriculumJSON()
   }));
 };
 
-module.exports = mongoose.model("Course", courseSchema);
+module.exports = mongoose.model("Course", courseSchema);
+module.exports.CATEGORIES = CATEGORIES;
 

src/models/Order.js

@@ -1,7 +1,7 @@
 const mongoose = require("mongoose");
 const { encryptField, decryptField, hmacIndex } = require("../utils/crypto");
 
-const PAYMENT_METHODS = ["bank_wire", "payoneer"];
+const PAYMENT_METHODS = ["bank_wire", "payoneer", "payoneer_checkout", "voucher"];
 const ORDER_STATUSES = ["pending_payment", "awaiting_confirmation", "confirmed", "rejected", "cancelled"];
 
 const orderSchema = new mongoose.Schema(
@@ -16,7 +16,21 @@ const orderSchema = new mongoose.Schema(
     amount: { type: Number, required: true, min: 0 },
     currency: { type: String, default: "USD" },
 
-    paymentMethod: { type: String, enum: PAYMENT_METHODS, required: true },
+    paymentMethod: { type: String, enum: PAYMENT_METHODS, required: true },
+
+    // Set only when paymentMethod === "voucher": the voucher whose
+    // redemption produced this (free, pre-confirmed) order.
+    voucher: { type: mongoose.Schema.Types.ObjectId, ref: "Voucher", default: null, index: true },
+
+    // --- Automated Payoneer Checkout fields (paymentMethod ===
+    // "payoneer_checkout" only). Populated when the checkout session is
+    // created and used to (a) match an incoming webhook back to this
+    // order, and (b) show the buyer a clear tax breakdown before they're
+    // sent to Payoneer to actually pay. ---
+    providerSessionId: { type: String, default: null, index: true },
+    providerCheckoutUrl: { type: String, default: null },
+    taxAmount: { type: Number, default: 0, min: 0 },
+    taxCurrency: { type: String, default: null },
 
     // Sensitive: encrypted at rest with AES-256-GCM. Never returned by
     // default queries (select: false) and never logged in plaintext.
@@ -63,7 +77,12 @@ orderSchema.methods.toPublicJSON = function toPublicJSON({ includeSensitive = fa
     courseTitleSnapshot: this.courseTitleSnapshot,
     amount: this.amount,
     currency: this.currency,
+    taxAmount: this.taxAmount,
+    taxCurrency: this.taxCurrency,
+    totalAmount: this.amount + (this.taxAmount || 0),
     paymentMethod: this.paymentMethod,
+    voucher: this.voucher || undefined,
+    providerCheckoutUrl: this.providerCheckoutUrl,
     status: this.status,
     confirmedAt: this.confirmedAt,
     rejectionReason: this.rejectionReason,

src/models/Voucher.js

@@ -0,0 +1,100 @@
+const mongoose = require("mongoose");
+
+// Records that a specific user redeemed a specific voucher, and which
+// (free) order that redemption produced — kept as a subdocument so a
+// voucher's full redemption history is visible in one place without a
+// second query.
+const redemptionSchema = new mongoose.Schema(
+  {
+    user: { type: mongoose.Schema.Types.ObjectId, ref: "User", required: true },
+    order: { type: mongoose.Schema.Types.ObjectId, ref: "Order", required: true },
+    redeemedAt: { type: Date, default: Date.now },
+  },
+  { _id: false }
+);
+
+const voucherSchema = new mongoose.Schema(
+  {
+    // Always stored upper-cased so lookups are case-insensitive without
+    // needing a collation — the code itself is not secret in the sense a
+    // password is, but it IS a bearer credential, so it's still generated
+    // with real randomness (see utils/voucherCode.js) rather than
+    // something guessable.
+    code: { type: String, required: true, unique: true, uppercase: true, trim: true, index: true },
+
+    course: { type: mongoose.Schema.Types.ObjectId, ref: "Course", required: true, index: true },
+
+    createdBy: { type: mongoose.Schema.Types.ObjectId, ref: "User", required: true },
+
+    // How many different users may redeem this single code. Defaults to
+    // 1 (one voucher == one seat), but an admin can raise this to hand
+    // the same code to a small group (e.g. a workshop cohort) instead of
+    // generating one per person.
+    maxRedemptions: { type: Number, default: 1, min: 1, max: 10000 },
+
+    redemptions: { type: [redemptionSchema], default: [] },
+
+    // Optional allow-list of emails (lower-cased) this voucher may be
+    // redeemed by. Empty array = anyone who has the code may redeem it
+    // (up to maxRedemptions). Non-empty = only these accounts may, which
+    // is how an admin "gives a voucher to specific users" rather than
+    // just publishing an open promo code.
+    restrictedToEmails: { type: [String], default: [] },
+
+    expiresAt: { type: Date, default: null },
+
+    isActive: { type: Boolean, default: true },
+
+    // Free-text admin memo, e.g. "Scholarship cohort — Fall 2026". Never
+    // shown to the redeeming user.
+    note: { type: String, default: "", maxlength: 500 },
+  },
+  { timestamps: true }
+);
+
+voucherSchema.methods.isExpired = function isExpired() {
+  return !!(this.expiresAt && this.expiresAt.getTime() < Date.now());
+};
+
+voucherSchema.methods.hasRemainingRedemptions = function hasRemainingRedemptions() {
+  return this.redemptions.length < this.maxRedemptions;
+};
+
+voucherSchema.methods.isRedeemableBy = function isRedeemableBy(email) {
+  if (this.restrictedToEmails.length === 0) return true;
+  return this.restrictedToEmails.includes(String(email).toLowerCase().trim());
+};
+
+voucherSchema.methods.hasBeenRedeemedBy = function hasBeenRedeemedBy(userId) {
+  return this.redemptions.some((r) => r.user.toString() === userId.toString());
+};
+
+/** Why (if at all) this voucher currently can't be redeemed — null means it's valid to try. */
+voucherSchema.methods.redemptionBlockReason = function redemptionBlockReason(user) {
+  if (!this.isActive) return "This voucher has been deactivated.";
+  if (this.isExpired()) return "This voucher has expired.";
+  if (!this.hasRemainingRedemptions()) return "This voucher has already been fully redeemed.";
+  if (!this.isRedeemableBy(user.email)) return "This voucher isn't assigned to your account.";
+  if (this.hasBeenRedeemedBy(user._id)) return "You've already redeemed this voucher.";
+  return null;
+};
+
+voucherSchema.methods.toAdminJSON = function toAdminJSON() {
+  return {
+    id: this._id,
+    code: this.code,
+    course: this.course,
+    createdBy: this.createdBy,
+    maxRedemptions: this.maxRedemptions,
+    redemptionsCount: this.redemptions.length,
+    redemptions: this.redemptions,
+    restrictedToEmails: this.restrictedToEmails,
+    expiresAt: this.expiresAt,
+    isActive: this.isActive,
+    isExpired: this.isExpired(),
+    note: this.note,
+    createdAt: this.createdAt,
+  };
+};
+
+module.exports = mongoose.model("Voucher", voucherSchema);

src/routes/admin.routes.js

@@ -5,6 +5,7 @@ const { requireAuth, requireRole } = require("../middleware/auth");
 const { upload } = require("../middleware/upload");
 const ctrl = require("../controllers/admin.controller");
 const contentCtrl = require("../controllers/content.controller");
+const voucherCtrl = require("../controllers/voucher.controller");
 
 const router = express.Router();
 
@@ -45,5 +46,27 @@ router.post(
 router.put("/courses/:id/sections/:sectionId/lessons/:lessonId", contentCtrl.updateLesson);
 router.delete("/courses/:id/sections/:sectionId/lessons/:lessonId", contentCtrl.deleteLesson);
 
+router.post("/courses/:id/thumbnail", upload.single("file"), contentCtrl.uploadThumbnail);
+
+// --- Vouchers: admins issue free-access codes for a specific course ----
+router.get("/vouchers", voucherCtrl.listVouchers);
+router.get("/vouchers/:id", voucherCtrl.getVoucher);
+router.post(
+  "/vouchers",
+  [
+    body("courseId").isMongoId().withMessage("A valid course must be selected."),
+    body("code").optional({ nullable: true }).trim().isLength({ min: 3, max: 40 }),
+    body("maxRedemptions").optional({ nullable: true }).isInt({ min: 1, max: 10000 }),
+    body("restrictedToEmails").optional({ nullable: true }).isArray(),
+    body("restrictedToEmails.*").optional().isEmail(),
+    body("expiresAt").optional({ nullable: true }).isISO8601(),
+    body("note").optional({ nullable: true }).trim().isLength({ max: 500 }),
+  ],
+  validate,
+  voucherCtrl.createVoucher
+);
+router.post("/vouchers/:id/deactivate", voucherCtrl.deactivateVoucher);
+router.post("/vouchers/:id/reactivate", voucherCtrl.reactivateVoucher);
+
 module.exports = router;
 

src/routes/course.routes.js

@@ -4,10 +4,12 @@ const { validate } = require("../middleware/validate");
 const { requireAuth, requireRole } = require("../middleware/auth");
 const ctrl = require("../controllers/course.controller");
 const contentCtrl = require("../controllers/content.controller");
+const { CATEGORIES } = require("../models/Course");
 
 const router = express.Router();
 
 router.get("/", ctrl.listCourses);
+router.get("/categories", (req, res) => res.json({ categories: CATEGORIES }));
 router.get("/:id", ctrl.getCourse);
 
 // Curriculum viewing / lesson playback (learner-facing, requires login;
@@ -23,6 +25,7 @@ const courseValidators = [
   body("duration").trim().notEmpty(),
   body("level").trim().notEmpty(),
   body("description").trim().notEmpty(),
+  body("category").isIn(CATEGORIES).withMessage(`Category must be one of: ${CATEGORIES.join(", ")}`),
 ];
 
 router.post("/", requireAuth, requireRole("admin"), courseValidators, validate, ctrl.createCourse);

src/routes/order.routes.js

@@ -26,6 +26,14 @@ router.post(
   ctrl.createOrder
 );
 
+router.post(
+  "/payoneer/checkout-session",
+  orderLimiter,
+  [body("courseId").isMongoId().withMessage("A valid course must be selected.")],
+  validate,
+  ctrl.createPayoneerCheckoutSession
+);
+
 router.post(
   "/:id/payment-proof",
   orderLimiter,

src/routes/voucher.routes.js

@@ -0,0 +1,20 @@
+const express = require("express");
+const { body } = require("express-validator");
+const { validate } = require("../middleware/validate");
+const { requireAuth } = require("../middleware/auth");
+const { voucherRedeemLimiter } = require("../middleware/rateLimiters");
+const ctrl = require("../controllers/voucher.controller");
+
+const router = express.Router();
+
+router.use(requireAuth);
+
+router.post(
+  "/redeem",
+  voucherRedeemLimiter,
+  [body("code").trim().isLength({ min: 3, max: 40 }).withMessage("Enter a voucher code.")],
+  validate,
+  ctrl.redeemVoucher
+);
+
+module.exports = router;

src/routes/webhook.routes.js

@@ -0,0 +1,8 @@
+const express = require("express");
+const { handlePayoneerWebhook } = require("../controllers/webhook.controller");
+
+const router = express.Router();
+
+router.post("/payoneer", handlePayoneerWebhook);
+
+module.exports = router;

src/seed/seed.js

@@ -1,128 +1,134 @@
-/* eslint-disable no-console */
-const { env } = require("../config/env");
-const { connectDB, disconnectDB } = require("../config/db");
-const User = require("../models/User");
-const Course = require("../models/Course");
-
-const courses = [
-  {
-    title: "Artificial Intelligence Essentials",
-    slug: "artificial-intelligence-essentials",
-    price: 350,
-    duration: "8 weeks",
-    level: "Beginner",
-    description:
-      "A practical introduction to AI: learn what AI can (and cannot) do, work with real datasets, and build your first machine-learning models.",
-    highlights: [
-      "AI concepts, terminology and real-world use cases",
-      "Hands-on Python & ML experiments",
-      "Build a simple predictive model end-to-end",
-    ],
-  },
-  {
-    title: "Cyber Security Essentials",
-    slug: "cyber-security-essentials",
-    price: 300,
-    duration: "6 weeks",
-    level: "Beginner",
-    description:
-      "Learn the foundations of cyber defense: protect devices, networks, and data against the most common digital threats.",
-    highlights: [
-      "Threat landscape and attacker tactics",
-      "Secure browsing, password & identity hygiene",
-      "Basic network and endpoint protection",
-    ],
-  },
-  {
-    title: "AI-Powered Cybersecurity",
-    slug: "ai-powered-cybersecurity",
-    price: 550,
-    duration: "10 weeks",
-    level: "Intermediate to Advanced",
-    description:
-      "Combine AI with security operations: deploy intelligent threat detection, automate incident response, and build resilient SOC workflows.",
-    highlights: [
-      "ML-based threat detection and anomaly analytics",
-      "Automated incident response playbooks",
-      "AI governance, ethics and adversarial risks",
-    ],
-  },
-  {
-    title: "The AI Career Guidance",
-    slug: "the-ai-career-guidance",
-    price: 200,
-    duration: "4 weeks",
-    level: "Career Foundations",
-    description:
-      "Map your path into the AI economy. Discover roles, build a portfolio, and prepare for interviews with guided mentorship.",
-    highlights: [
-      "AI career landscape and skill roadmap",
-      "Portfolio project planning and resume review",
-      "Mock interviews and mentorship sessions",
-    ],
-  },
-  {
-    title: "AI for Business Managers",
-    slug: "ai-for-business-managers",
-    price: 450,
-    duration: "6 weeks",
-    level: "Manager Level",
-    description:
-      "Learn how to evaluate, procure, and manage AI projects that drive real business value without needing to code.",
-    highlights: [
-      "AI strategy, ROI and use-case prioritisation",
-      "Managing data, vendors and project risk",
-      "Leading AI-enabled teams and change",
-    ],
-  },
-  {
-    title: "AI for Business Executives",
-    slug: "ai-for-business-executives",
-    price: 650,
-    duration: "5 weeks",
-    level: "Executive Level",
-    description:
-      "A leadership-level course on AI governance, competitive strategy, and building an AI-ready organisation.",
-    highlights: [
-      "Board-level AI vision and investment decisions",
-      "Regulatory, ethical and governance frameworks",
-      "Building an AI culture and Centre of Excellence",
-    ],
-  },
-];
-
-async function seed() {
-  await connectDB();
-
-  for (const c of courses) {
-    await Course.findOneAndUpdate({ slug: c.slug }, c, { upsert: true, new: true, setDefaultsOnInsert: true });
-  }
-  console.log(`Seeded ${courses.length} courses.`);
-
-  if (env.seedAdmin.email && env.seedAdmin.password) {
-    const existingAdmin = await User.findOne({ email: env.seedAdmin.email.toLowerCase() });
-    if (existingAdmin) {
-      console.log(`Admin account already exists for ${env.seedAdmin.email}, skipping.`);
-    } else {
-      const admin = new User({
-        name: env.seedAdmin.name,
-        email: env.seedAdmin.email.toLowerCase(),
-        role: "admin",
-      });
-      await admin.setPassword(env.seedAdmin.password);
-      await admin.save();
-      console.log(`Created admin account: ${env.seedAdmin.email}`);
-      console.log("IMPORTANT: log in and change this password immediately.");
-    }
-  } else {
-    console.log("SEED_ADMIN_EMAIL / SEED_ADMIN_PASSWORD not set — skipping admin creation.");
-  }
-
-  await disconnectDB();
-  process.exit(0);
-}
-
-seed().catch((err) => {
-  console.error("Seeding failed:", err);
-  process.exit(1);
-});
+/* eslint-disable no-console */
+const { env } = require("../config/env");
+const { connectDB, disconnectDB } = require("../config/db");
+const User = require("../models/User");
+const Course = require("../models/Course");
+
+const courses = [
+  {
+    title: "Artificial Intelligence Essentials",
+    slug: "artificial-intelligence-essentials",
+    category: "Artificial Intelligence",
+    price: 350,
+    duration: "8 weeks",
+    level: "Beginner",
+    description:
+      "A practical introduction to AI: learn what AI can (and cannot) do, work with real datasets, and build your first machine-learning models.",
+    highlights: [
+      "AI concepts, terminology and real-world use cases",
+      "Hands-on Python & ML experiments",
+      "Build a simple predictive model end-to-end",
+    ],
+  },
+  {
+    title: "Cyber Security Essentials",
+    slug: "cyber-security-essentials",
+    category: "Cyber Security",
+    price: 300,
+    duration: "6 weeks",
+    level: "Beginner",
+    description:
+      "Learn the foundations of cyber defense: protect devices, networks, and data against the most common digital threats.",
+    highlights: [
+      "Threat landscape and attacker tactics",
+      "Secure browsing, password & identity hygiene",
+      "Basic network and endpoint protection",
+    ],
+  },
+  {
+    title: "AI-Powered Cybersecurity",
+    slug: "ai-powered-cybersecurity",
+    category: "Cyber Security",
+    price: 550,
+    duration: "10 weeks",
+    level: "Intermediate to Advanced",
+    description:
+      "Combine AI with security operations: deploy intelligent threat detection, automate incident response, and build resilient SOC workflows.",
+    highlights: [
+      "ML-based threat detection and anomaly analytics",
+      "Automated incident response playbooks",
+      "AI governance, ethics and adversarial risks",
+    ],
+  },
+  {
+    title: "The AI Career Guidance",
+    slug: "the-ai-career-guidance",
+    category: "Professional Ethics",
+    price: 200,
+    duration: "4 weeks",
+    level: "Career Foundations",
+    description:
+      "Map your path into the AI economy. Discover roles, build a portfolio, and prepare for interviews with guided mentorship.",
+    highlights: [
+      "AI career landscape and skill roadmap",
+      "Portfolio project planning and resume review",
+      "Mock interviews and mentorship sessions",
+    ],
+  },
+  {
+    title: "AI for Business Managers",
+    slug: "ai-for-business-managers",
+    category: "Professional Ethics",
+    price: 450,
+    duration: "6 weeks",
+    level: "Manager Level",
+    description:
+      "Learn how to evaluate, procure, and manage AI projects that drive real business value without needing to code.",
+    highlights: [
+      "AI strategy, ROI and use-case prioritisation",
+      "Managing data, vendors and project risk",
+      "Leading AI-enabled teams and change",
+    ],
+  },
+  {
+    title: "AI for Business Executives",
+    slug: "ai-for-business-executives",
+    category: "Professional Ethics",
+    price: 650,
+    duration: "5 weeks",
+    level: "Executive Level",
+    description:
+      "A leadership-level course on AI governance, competitive strategy, and building an AI-ready organisation.",
+    highlights: [
+      "Board-level AI vision and investment decisions",
+      "Regulatory, ethical and governance frameworks",
+      "Building an AI culture and Centre of Excellence",
+    ],
+  },
+];
+
+async function seed() {
+  await connectDB();
+
+  for (const c of courses) {
+    await Course.findOneAndUpdate({ slug: c.slug }, c, { upsert: true, new: true, setDefaultsOnInsert: true });
+  }
+  console.log(`Seeded ${courses.length} courses.`);
+
+  if (env.seedAdmin.email && env.seedAdmin.password) {
+    const existingAdmin = await User.findOne({ email: env.seedAdmin.email.toLowerCase() });
+    if (existingAdmin) {
+      console.log(`Admin account already exists for ${env.seedAdmin.email}, skipping.`);
+    } else {
+      const admin = new User({
+        name: env.seedAdmin.name,
+        email: env.seedAdmin.email.toLowerCase(),
+        role: "admin",
+      });
+      await admin.setPassword(env.seedAdmin.password);
+      await admin.save();
+      console.log(`Created admin account: ${env.seedAdmin.email}`);
+      console.log("IMPORTANT: log in and change this password immediately.");
+    }
+  } else {
+    console.log("SEED_ADMIN_EMAIL / SEED_ADMIN_PASSWORD not set — skipping admin creation.");
+  }
+
+  await disconnectDB();
+  process.exit(0);
+}
+
+seed().catch((err) => {
+  console.error("Seeding failed:", err);
+  process.exit(1);
+});

src/utils/cloudinaryUpload.js

@@ -60,6 +60,39 @@ function deleteAsset(publicId, resourceType) {
   return cloudinary.uploader.destroy(publicId, { resource_type: resourceType, type: "authenticated" });
 }
 
+const THUMBNAIL_FOLDER = "aynwerd-course-thumbnails";
+
+/**
+ * Uploads a course thumbnail image. Deliberately PUBLIC (type: "upload",
+ * the Cloudinary default) — unlike lesson videos/documents, a
+ * thumbnail's whole purpose is to be visible to any visitor browsing
+ * the storefront before they've bought anything, so there's nothing to
+ * gate here.
+ */
+async function uploadThumbnail(filePath, { filenameHint }) {
+  const result = await cloudinary.uploader.upload(filePath, {
+    folder: THUMBNAIL_FOLDER,
+    resource_type: "image",
+    type: "upload",
+    use_filename: true,
+    unique_filename: true,
+    filename_override: filenameHint,
+    // Keep thumbnails reasonably sized regardless of what the admin
+    // uploads, so course cards load fast on the storefront.
+    transformation: [{ width: 1024, height: 768, crop: "limit" }],
+  });
+
+  if (!result || !result.public_id || !result.secure_url) {
+    throw new Error(`Cloudinary thumbnail upload did not return the expected result (got: ${JSON.stringify(result)}).`);
+  }
+
+  return result;
+}
+
+function deleteThumbnail(publicId) {
+  return cloudinary.uploader.destroy(publicId, { resource_type: "image", type: "upload" });
+}
+
 /**
  * Builds the overlay layers that stamp a video with the Aynwerd logo
  * plus the viewing learner's email, so any leaked/recorded copy is
@@ -138,4 +171,11 @@ function resourceTypeForMimetype(mimetype) {
   return "raw"; // PDFs, docs, slides, zips, etc.
 }
 
-module.exports = { uploadFromPath, deleteAsset, getSignedPlaybackUrl, resourceTypeForMimetype };
+module.exports = {
+  uploadFromPath,
+  deleteAsset,
+  getSignedPlaybackUrl,
+  resourceTypeForMimetype,
+  uploadThumbnail,
+  deleteThumbnail,
+};

src/utils/email.js

@@ -104,6 +104,23 @@ async function sendPaymentConfirmedEmail({ to, name, order, courseTitle }) {
   });
 }
 
+async function sendVoucherRedeemedEmail({ to, name, order, courseTitle, voucherCode }) {
+  const html = baseLayout(`
+    <p>Hi ${name},</p>
+    <p>Your voucher <strong>${voucherCode}</strong> has been redeemed for <strong>${courseTitle}</strong> —
+    no payment was required.</p>
+    <p><strong>Order number:</strong> ${order.orderNumber}</p>
+    <p>Full access to the course has been unlocked on your account. Log in any time to get started.</p>
+  `);
+
+  return sendMail({
+    to,
+    subject: `Voucher redeemed — ${courseTitle} unlocked`,
+    html,
+    text: `Voucher ${voucherCode} redeemed for ${courseTitle}. Course access unlocked. Order ${order.orderNumber}.`,
+  });
+}
+
 async function sendPaymentRejectedEmail({ to, name, order, courseTitle, reason }) {
   const html = baseLayout(`
     <p>Hi ${name},</p>
@@ -142,6 +159,7 @@ async function sendAdminNewOrderAlert({ order, courseTitle, customerEmail }) {
 module.exports = {
   sendOrderPlacedEmail,
   sendPaymentConfirmedEmail,
+  sendVoucherRedeemedEmail,
   sendPaymentRejectedEmail,
   sendAdminNewOrderAlert,
 };

src/utils/orderConfirmation.js

@@ -0,0 +1,97 @@
+const mongoose = require("mongoose");
+const Order = require("../models/Order");
+const User = require("../models/User");
+const Course = require("../models/Course");
+const AuditLog = require("../models/AuditLog");
+const { sendPaymentConfirmedEmail } = require("./email");
+const logger = require("./logger");
+
+/**
+ * The single source of truth for "an order has been paid — unlock the
+ * course and tell the customer." Used by both:
+ *   - admin.controller.js's confirmOrder (a human admin manually
+ *     reviewing a bank-wire/manual payment reference), and
+ *   - webhook.controller.js's Payoneer webhook handler (an automated
+ *     Payoneer Checkout payment confirmation)
+ *
+ * so that access-granting and the confirmation email can never drift
+ * out of sync between the manual and automated payment paths.
+ *
+ * `confirmedBy` is a User id for a manual admin confirmation, or null
+ * for an automated one (the order's paymentMethod already records how
+ * it was paid).
+ *
+ * Idempotent: safe to call more than once for the same order (a
+ * webhook can legitimately be retried/redelivered by the provider) —
+ * an already-confirmed order is left untouched and simply returned.
+ */
+async function confirmOrderAndGrantAccess({ orderId, confirmedBy = null, ip = null, userAgent = null }) {
+  const session = await mongoose.startSession();
+  try {
+    let resultOrder;
+    let resultUser;
+    let course;
+    let alreadyConfirmed = false;
+
+    await session.withTransaction(async () => {
+      const order = await Order.findById(orderId).session(session);
+      if (!order) throw Object.assign(new Error("Order not found."), { status: 404 });
+
+      if (order.status === "confirmed") {
+        alreadyConfirmed = true;
+        resultOrder = order;
+        return;
+      }
+
+      if (!["awaiting_confirmation", "pending_payment"].includes(order.status)) {
+        throw Object.assign(new Error("Order cannot be confirmed from its current status."), { status: 409 });
+      }
+
+      order.status = "confirmed";
+      order.confirmedBy = confirmedBy;
+      order.confirmedAt = new Date();
+      await order.save({ session });
+
+      const user = await User.findById(order.user).session(session);
+      if (!user) throw Object.assign(new Error("Associated user not found."), { status: 404 });
+
+      const alreadyEnrolled = user.enrolledCourses.some((ec) => ec.course.toString() === order.course.toString());
+      if (!alreadyEnrolled) {
+        user.enrolledCourses.push({ course: order.course, order: order._id, accessGrantedAt: new Date() });
+        await user.save({ session });
+      }
+
+      course = await Course.findById(order.course).session(session);
+      resultOrder = order;
+      resultUser = user;
+    });
+
+    if (alreadyConfirmed) {
+      return { order: resultOrder, alreadyConfirmed: true };
+    }
+
+    await AuditLog.create({
+      actor: confirmedBy,
+      actorEmail: confirmedBy ? undefined : "system:payoneer-webhook",
+      action: confirmedBy ? "admin.order_confirmed" : "system.order_auto_confirmed",
+      targetType: "Order",
+      targetId: resultOrder._id,
+      ip,
+      userAgent,
+      metadata: { userId: resultUser._id.toString(), paymentMethod: resultOrder.paymentMethod },
+    });
+
+    sendPaymentConfirmedEmail({
+      to: resultUser.email,
+      name: resultUser.name,
+      order: resultOrder,
+      courseTitle: course ? course.title : resultOrder.courseTitleSnapshot,
+    }).catch((err) => logger.error("Payment-confirmed email failed", { error: err.message }));
+
+    return { order: resultOrder, alreadyConfirmed: false };
+  } finally {
+    session.endSession();
+  }
+}
+
+module.exports = { confirmOrderAndGrantAccess };

src/utils/payoneerCheckout.js

@@ -0,0 +1,171 @@
+/**
+ * Adapter around Payoneer Checkout (the hosted-payment product that
+ * lets a webstore accept card/wallet payments that settle directly
+ * into a Payoneer account) — https://checkoutdocs.payoneer.com
+ *
+ * IMPORTANT — READ BEFORE GOING LIVE:
+ * Payoneer Checkout is not a self-serve API like Stripe. Per Payoneer's
+ * own documentation, credentials and the exact request/response
+ * contract (endpoint paths, field names, webhook signature scheme) are
+ * issued directly to you by Payoneer's integration team only after
+ * your business applies and is approved as a Payoneer Checkout
+ * merchant. That contract is account-specific, so it isn't something
+ * that can be correctly guessed or hard-coded here in advance.
+ *
+ * What IS real and finished in this file:
+ *   - The env-driven config wiring (config/env.js -> payoneerCheckout)
+ *   - The calling convention the rest of the app uses (see
+ *     controllers/checkout.controller.js and webhook.controller.js)
+ *   - A standard HMAC-SHA256 webhook-signature check, which is the
+ *     common pattern most hosted-checkout providers use (Stripe,
+ *     Paysera, PayMongo, etc. all verify webhooks this way) — but you
+ *     MUST confirm the header name and signing scheme against your own
+ *     Payoneer Checkout webhook docs once you have them, since generic
+ *     industry convention isn't a guarantee it matches Payoneer's
+ *     specific implementation.
+ *
+ * What's a clearly-marked PLACEHOLDER, pending your approved
+ * integration docs from Payoneer:
+ *   - The exact endpoint path for creating a checkout session
+ *   - The exact request body field names Payoneer's API expects
+ *   - The exact response field names for the session id / redirect URL
+ *   - The exact webhook payload field names / event-type values
+ *   - The exact webhook signature header name
+ *
+ * Search for "PAYONEER-DOCS-NEEDED" below for every spot that needs a
+ * one-line fix once you have that contract in hand — the surrounding
+ * logic (error handling, order matching, idempotency) doesn't need to
+ * change.
+ */
+const crypto = require("crypto");
+const { env } = require("../config/env");
+
+function assertConfigured() {
+  if (!env.payoneerCheckout.apiBase || !env.payoneerCheckout.apiKey || !env.payoneerCheckout.apiSecret) {
+    throw Object.assign(
+      new Error(
+        "Payoneer Checkout is not configured yet. Set PAYONEER_CHECKOUT_API_BASE, " +
+          "PAYONEER_CHECKOUT_API_KEY and PAYONEER_CHECKOUT_API_SECRET once your Payoneer " +
+          "Checkout merchant account is approved."
+      ),
+      { status: 503 }
+    );
+  }
+}
+
+/**
+ * Creates a hosted checkout session for one order and returns where to
+ * send the buyer to actually pay, plus any tax Payoneer's session
+ * response reports (so the buyer can be shown a clear amount + tax +
+ * total before being redirected — see checkout.controller.js).
+ *
+ * @param {object} params
+ * @param {object} params.order - the just-created Order document
+ * @param {object} params.course - the Course being purchased
+ * @param {string} params.customerEmail
+ * @param {string} params.customerName
+ * @param {string} params.successUrl - where Payoneer redirects after a successful payment
+ * @param {string} params.cancelUrl - where Payoneer redirects after a cancelled/failed payment
+ */
+async function createCheckoutSession({ order, course, customerEmail, customerName, successUrl, cancelUrl }) {
+  assertConfigured();
+
+  // PAYONEER-DOCS-NEEDED: confirm this path against your approved
+  // Payoneer Checkout API reference.
+  const endpoint = `${env.payoneerCheckout.apiBase}/v1/checkout-sessions`;
+
+  const response = await fetch(endpoint, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      // PAYONEER-DOCS-NEEDED: confirm the auth header/scheme Payoneer
+      // issues you (this assumes a bearer API key, a common pattern,
+      // but Payoneer may use a different header or OAuth2 client-
+      // credentials flow instead).
+      Authorization: `Bearer ${env.payoneerCheckout.apiKey}`,
+    },
+    body: JSON.stringify({
+      // PAYONEER-DOCS-NEEDED: field names below are our best-guess
+      // shape for a hosted checkout session, modelled on the common
+      // pattern across similar providers — confirm every field name
+      // against Payoneer's reference before relying on this in
+      // production.
+      amount: order.amount,
+      currency: order.currency,
+      order_id: order.orderNumber,
+      description: course.title,
+      customer: { email: customerEmail, name: customerName },
+      success_url: successUrl,
+      cancel_url: cancelUrl,
+    }),
+  });
+
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    throw new Error(`Payoneer Checkout session creation failed (${response.status}): ${body}`);
+  }
+
+  const data = await response.json();
+
+  // PAYONEER-DOCS-NEEDED: confirm these response field names.
+  return {
+    sessionId: data.id || data.session_id,
+    checkoutUrl: data.checkout_url || data.redirect_url,
+    tax: data.tax
+      ? { amount: data.tax.amount, currency: data.tax.currency || order.currency }
+      : null,
+  };
+}
+
+/**
+ * Verifies an incoming webhook's signature and normalizes it into
+ * { sessionId, status, providerOrderId }. Throws if the signature is
+ * missing or invalid — the caller (webhook.controller.js) treats a
+ * throw as "reject this request," never as "treat it as paid."
+ *
+ * `rawBody` must be the exact, unparsed request body bytes/string used
+ * to compute the signature — see routes/webhook.routes.js, which
+ * registers this route with a raw body parser specifically so the
+ * bytes here match exactly what Payoneer signed.
+ */
+function verifyAndParseWebhook({ rawBody, signatureHeader }) {
+  if (!env.payoneerCheckout.webhookSecret) {
+    throw Object.assign(new Error("PAYONEER_CHECKOUT_WEBHOOK_SECRET is not configured."), { status: 503 });
+  }
+  if (!signatureHeader) {
+    throw Object.assign(new Error("Missing webhook signature."), { status: 400 });
+  }
+
+  const expectedSignature = crypto
+    .createHmac("sha256", env.payoneerCheckout.webhookSecret)
+    .update(rawBody)
+    .digest("hex");
+
+  // PAYONEER-DOCS-NEEDED: confirm Payoneer's actual signature encoding
+  // (hex vs base64) and whether the header carries just the signature
+  // or a prefixed/versioned value (e.g. Stripe's "t=...,v1=...").
+  const signatureValid =
+    signatureHeader.length === expectedSignature.length &&
+    crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expectedSignature));
+
+  if (!signatureValid) {
+    throw Object.assign(new Error("Invalid webhook signature."), { status: 400 });
+  }
+
+  const payload = JSON.parse(rawBody.toString("utf8"));
+
+  // PAYONEER-DOCS-NEEDED: confirm the actual field/event names Payoneer
+  // sends (this assumes something like { event: "payment.completed",
+  // session_id, order_id }).
+  const eventType = payload.event || payload.type;
+  const status = eventType && eventType.includes("completed") ? "paid" : "other";
+
+  return {
+    sessionId: payload.session_id || payload.id,
+    providerOrderId: payload.order_id,
+    status,
+    raw: payload,
+  };
+}
+
+module.exports = { createCheckoutSession, verifyAndParseWebhook };

src/utils/voucherCode.js

@@ -0,0 +1,21 @@
+const crypto = require("crypto");
+
+// Excludes visually-confusable characters (0/O, 1/I/L) since these codes
+// are meant to be read aloud, typed by hand, or printed on a certificate.
+const ALPHABET = "ABCDEFGHJKMNPQRSTUVWXYZ23456789";
+
+function randomSegment(length) {
+  let out = "";
+  const bytes = crypto.randomBytes(length);
+  for (let i = 0; i < length; i++) {
+    out += ALPHABET[bytes[i] % ALPHABET.length];
+  }
+  return out;
+}
+
+/** e.g. AYN-7K4Q-XP2M — grouped for readability, not a security boundary by itself. */
+function generateVoucherCode() {
+  return `AYN-${randomSegment(4)}-${randomSegment(4)}`;
+}
+
+module.exports = { generateVoucherCode };