tier plans improving

Signed-off-by: Kenneth Obsequio <k80308392@gmail.com>

controllers/admin/tier_categories.controller.js

@@ -44,7 +44,7 @@ exports.getCategory = async (req, res) => {
 
 exports.createCategory = async (req, res) => {
   try {
-    const { slug, name, description, rank, color, badge_asset_id, badge_icon, badge_label } = req.body;
+    const { slug, name, description, rank, color, badge_asset_id, badge_icon, badge_label, is_special } = req.body;
     if (!slug || !name) return R.error(res, 'slug and name are required.', 400);
 
     const parsedRank = Number(rank ?? 1);
@@ -63,6 +63,7 @@ exports.createCategory = async (req, res) => {
       badge_label:    badge_label    ?? null,
       is_default:     false,
       is_active:      true,
+      is_special:     !!is_special,
     });
 
     logActivity(req.user?.user_id, 'create_tier_category', { entityType: 'tier_category', details: { slug, name } });
@@ -82,7 +83,7 @@ exports.updateCategory = async (req, res) => {
     const cat = await mdl_TierCategories.findByPk(req.params.id);
     if (!cat) return R.error(res, 'Tier category not found.', 404);
 
-    const { name, description, rank, color, badge_asset_id, badge_icon, badge_label, is_active } = req.body;
+    const { name, description, rank, color, badge_asset_id, badge_icon, badge_label, is_active, is_special } = req.body;
 
     if (!cat.is_default && rank !== undefined) {
       const parsedRank = Number(rank);
@@ -98,7 +99,8 @@ exports.updateCategory = async (req, res) => {
       badge_icon:     badge_icon     !== undefined ? (badge_icon     || null) : cat.badge_icon,
       badge_label:    badge_label    !== undefined ? (badge_label    || null) : cat.badge_label,
       // Default category (free) cannot be deactivated
-      is_active: (!cat.is_default && is_active !== undefined) ? is_active : cat.is_active,
+      is_active:  (!cat.is_default && is_active !== undefined) ? is_active : cat.is_active,
+      is_special: is_special !== undefined ? !!is_special : cat.is_special,
     });
 
     logActivity(req.user?.user_id, 'update_tier_category', { entityType: 'tier_category', details: { id: cat.tier_category_id, slug: cat.slug } });

controllers/admin/tier_policies.controller.js

@@ -15,8 +15,11 @@ const VALID_RULE_TYPES = new Set([
   'course_subscription_access',
   'required_active_tier',
   'group_restriction',
+  'item_allowlist',
 ]);
 
+const VALID_ITEM_TYPES = new Set(['course', 'unit', 'lesson']);
+
 async function validateRules(rules) {
   if (!Array.isArray(rules)) return 'access_rules must be an array.';
 
@@ -41,6 +44,15 @@ async function validateRules(rules) {
       if (!Array.isArray(rule.group_ids))
         return 'group_restriction.group_ids must be an array.';
     }
+
+    if (rule.type === 'item_allowlist') {
+      if (!VALID_ITEM_TYPES.has(rule.item_type))
+        return `item_allowlist.item_type must be one of: ${[...VALID_ITEM_TYPES].join(', ')}.`;
+      if (!Array.isArray(rule.item_ids) || !rule.item_ids.length)
+        return 'item_allowlist.item_ids must be a non-empty array.';
+      if (rule.item_ids.length > 3)
+        return 'item_allowlist.item_ids must contain at most 3 items.';
+    }
   }
   return null;
 }

controllers/admin/tiers.controller.js

@@ -28,6 +28,9 @@ const R = require('../../utils/response.util');
 const { paginate } = require('../../utils/paginate.util');
 const { getFieldValues } = require('../../utils/fieldValues.util');
 const logActivity = require('../../utils/logActivity.util');
+const UserNotification = require('../../models/notifications/user_notification.mdl');
+const { NOTIFICATION_REGISTRY } = require('../../data/notifications.data');
+const { resolveTierPlanUserIds } = require('../../utils/audienceResolver.util');
 
 const {
   excludeAttributes: plansExclude,
@@ -75,6 +78,7 @@ exports.getPlans = async (req, res) => {
       jsonbSchemas: plansSchemas,
       computedAttributes: plansComputed,
       context: archived ? 'archived' : 'list',
+      auditOptions: { mdl_Users, parentAlias: 'TierPlan' },
       findOptions: archived ? {
         paranoid: false,
         where: { deletedAt: { [Op.ne]: null } },
@@ -108,7 +112,7 @@ function computeDurationDays(value, unit) {
 
 exports.createPlan = async (req, res) => {
   try {
-    const { tier_category_id, label, description, features, duration_value, duration_unit = 'day', price, currency } = req.body;
+    const { tier_category_id, label, description, features, duration_value, duration_unit = 'day', price, currency, createdBy } = req.body;
     if (!tier_category_id || !label || !duration_value || !price)
       return R.error(res, 'tier_category_id, label, duration_value, and price are required.', 400);
 
@@ -125,6 +129,7 @@ exports.createPlan = async (req, res) => {
       tier_category_id: category.tier_category_id,
       tier:             category.slug,
       label, description, features, duration_days, duration_unit, price, currency,
+      createdBy: createdBy ?? req.user?.user_id ?? null,
     });
     const plain = plan.get({ plain: true });
     logActivity(req.user?.user_id, 'create_tier_plan', { entityType: 'tier_plan', details: { label: plain.label, tier: plain.tier } });
@@ -145,6 +150,7 @@ exports.updatePlan = async (req, res) => {
     for (const k of allowed) {
       if (req.body[k] !== undefined) updates[k] = req.body[k];
     }
+    updates.updatedBy = req.body.updatedBy ?? req.user?.user_id ?? null;
 
     // Recompute duration_days when value or unit changes
     const { duration_value, duration_unit } = req.body;
@@ -197,8 +203,23 @@ exports.archivePlan = async (req, res) => {
     if (!plan) return R.error(res, 'Plan not found.', 404);
     if (plan.deletedAt) return R.error(res, 'Plan is already archived.', 400);
 
-    await plan.update({ is_active: false });
+    await plan.update({ is_active: false, deletedBy: req.user?.user_id ?? null });
     await plan.destroy();
+
+    try {
+      const userIds = await resolveTierPlanUserIds(plan.plan_id);
+      if (userIds.length) {
+        const now = new Date();
+        const notify = NOTIFICATION_REGISTRY.tier_plan_archived.build({ label: plan.label, planId: plan.plan_id });
+        await UserNotification.bulkCreate(
+          userIds.map((user_id) => ({ user_id, ...notify, seen: false, createdAt: now, updatedAt: now })),
+          { validate: false }
+        );
+      }
+    } catch (notifyErr) {
+      console.error('[ADMIN][ARCHIVE PLAN][NOTIFY]', notifyErr);
+    }
+
     logActivity(req.user?.user_id, 'archive_tier_plan', { entityType: 'tier_plan', details: { label: plan.label } });
     return R.success(res, 'Plan archived successfully.');
   } catch (err) {
@@ -222,9 +243,31 @@ exports.bulkArchivePlans = async (req, res) => {
 
     const activeIds = activePlans.map((p) => p.plan_id);
 
-    await mdl_TierPlans.update({ is_active: false }, { where: { plan_id: activeIds } });
+    await mdl_TierPlans.update({ is_active: false, deletedBy: req.user?.user_id ?? null }, { where: { plan_id: activeIds } });
     await mdl_TierPlans.destroy({ where: { plan_id: activeIds } });
 
+    try {
+      const holders = await mdl_UserTiers.findAll({
+        attributes: ['user_id', 'plan_id'],
+        where: { plan_id: activeIds, status: 'active' },
+        raw: true,
+      });
+      if (holders.length) {
+        const now = new Date();
+        const labelByPlanId = new Map(activePlans.map((p) => [String(p.plan_id), p.label]));
+        const notifications = holders.map(({ user_id, plan_id }) => ({
+          user_id,
+          ...NOTIFICATION_REGISTRY.tier_plan_archived.build({ label: labelByPlanId.get(String(plan_id)), planId: plan_id }),
+          seen: false,
+          createdAt: now,
+          updatedAt: now,
+        }));
+        await UserNotification.bulkCreate(notifications, { validate: false });
+      }
+    } catch (notifyErr) {
+      console.error('[ADMIN][BULK ARCHIVE PLANS][NOTIFY]', notifyErr);
+    }
+
     logActivity(req.user?.user_id, 'bulk_archive_tier_plans', { entityType: 'tier_plan', details: { ids: activeIds, count: activeIds.length } });
     return R.success(res, `${activeIds.length} plan(s) archived successfully.`, {
       archived_ids: activeIds,

controllers/client/course_purchases.controller.js

@@ -4,6 +4,7 @@ const mdl_Product        = require('../../models/courses/products.mdl');
 const paymentSvc         = require('../../services/payment.service');
 const R                  = require('../../utils/response.util');
 const { resolvePurchasable, checkoutPath } = require('../../utils/purchasable.util');
+const { isPurchaseEligible } = require('./courses.controller');
 
 // ─── CREATE ORDER ─────────────────────────────────────────────────────────────
 // Despite the "course" naming (historical — this predates Units/Lessons being
@@ -28,6 +29,12 @@ exports.createCourseOrder = async (req, res) => {
 
     const target = await resolvePurchasable(product.purchasable_type, product.purchasable_id);
     if (!target) return R.error(res, 'Purchasable content not found.', 404);
+
+    const eligible = await isPurchaseEligible(req.user.user_id, target.subscription, product.purchasable_type, product.purchasable_id);
+    if (!eligible) {
+      return R.error(res, "Complete your plan's starter content before purchasing more.", 403);
+    }
+
     const path = checkoutPath(product.purchasable_type, target);
 
     const ppOrder = await paymentSvc.createOrder('paypal', {

controllers/client/courses.controller.js

@@ -160,7 +160,7 @@ async function canAccessCourse(user_id, course_id) {
   // rule engine.
   const { allowed: rankAllowed } = evaluateCourseAccess(
     { tier: userCtx.tier, access_rules: [], group_ids: userCtx.group_ids },
-    course, userCtx.tierRankMap
+    course, userCtx.tierRankMap, { type: 'course', id: course_id }
   );
   if (rankAllowed) return true;
 
@@ -169,7 +169,7 @@ async function canAccessCourse(user_id, course_id) {
   for (const ruleset of userCtx.rulesets) {
     const { allowed } = evaluateCourseAccess(
       { tier: ruleset.tier, access_rules: ruleset.access_rules, group_ids: userCtx.group_ids },
-      course, userCtx.tierRankMap
+      course, userCtx.tierRankMap, { type: 'course', id: course_id }
     );
     if (allowed) return true;
   }
@@ -194,13 +194,22 @@ async function canAccessUnit(user_id, unit_id) {
   const unit = await Unit.findOne({ where: { unit_id, ...notDeleted }, attributes: ['subscription'] });
   if (unit?.subscription) {
     const userCtx = await buildUserContext(user_id);
-    // Unit-level subscription gating is a plain rank check against the user's
-    // best active tier, not a rule-based one.
-    const { allowed } = evaluateCourseAccess(
+    // Plain rank check first, same baseline as canAccessCourse.
+    const { allowed: rankAllowed } = evaluateCourseAccess(
       { tier: userCtx.tier, access_rules: [], group_ids: userCtx.group_ids },
-      { subscription: unit.subscription }, userCtx.tierRankMap
+      { subscription: unit.subscription }, userCtx.tierRankMap, { type: 'unit', id: unit_id }
     );
-    if (allowed) return true;
+    if (rankAllowed) return true;
+
+    // Rule-based fallback (item_allowlist previews, etc.) — mirrors
+    // canAccessCourse's OR-across-active-plans check, previously missing here.
+    for (const ruleset of userCtx.rulesets) {
+      const { allowed } = evaluateCourseAccess(
+        { tier: ruleset.tier, access_rules: ruleset.access_rules, group_ids: userCtx.group_ids },
+        { subscription: unit.subscription }, userCtx.tierRankMap, { type: 'unit', id: unit_id }
+      );
+      if (allowed) return true;
+    }
   }
 
   if (await hasActivePurchase(user_id, 'unit', unit_id)) return true;
@@ -227,11 +236,19 @@ async function canAccessLesson(user_id, lesson_id) {
   const lesson = await Lesson.findOne({ where: { lesson_id, ...notDeleted }, attributes: ['subscription'] });
   if (lesson?.subscription) {
     const userCtx = await buildUserContext(user_id);
-    const { allowed } = evaluateCourseAccess(
+    const { allowed: rankAllowed } = evaluateCourseAccess(
       { tier: userCtx.tier, access_rules: [], group_ids: userCtx.group_ids },
-      { subscription: lesson.subscription }, userCtx.tierRankMap
+      { subscription: lesson.subscription }, userCtx.tierRankMap, { type: 'lesson', id: lesson_id }
     );
-    if (allowed) return true;
+    if (rankAllowed) return true;
+
+    for (const ruleset of userCtx.rulesets) {
+      const { allowed } = evaluateCourseAccess(
+        { tier: ruleset.tier, access_rules: ruleset.access_rules, group_ids: userCtx.group_ids },
+        { subscription: lesson.subscription }, userCtx.tierRankMap, { type: 'lesson', id: lesson_id }
+      );
+      if (allowed) return true;
+    }
   }
 
   if (await hasActivePurchase(user_id, 'lesson', lesson_id)) return true;
@@ -244,9 +261,58 @@ async function canAccessLesson(user_id, lesson_id) {
   return false;
 }
 
-exports.canAccessCourse = canAccessCourse;
-exports.canAccessUnit   = canAccessUnit;
-exports.canAccessLesson = canAccessLesson;
+// ─── Starter-set completion → paid-unlock eligibility ─────────────────────────
+// An `item_allowlist` access rule on a plan whose OWN tier matches the item
+// being evaluated doubles as a "starter set": those items are the plan's free
+// included content, and the subscriber can only purchase ADDITIONAL individual
+// items at that same level once every starter item is complete. A plan whose
+// tier doesn't match (e.g. a Premium plan previewing a couple of Exclusive
+// items) is a preview grant only — it never gates purchase eligibility.
+
+async function areAllItemsComplete(user_id, item_type, item_ids) {
+  if (!Array.isArray(item_ids) || !item_ids.length) return false;
+  for (const id of item_ids) {
+    const result = await evaluateEntity({
+      entityType: item_type,
+      entityId:   id,
+      userId:     user_id,
+      courseId:   item_type === 'course' ? id : null,
+    });
+    if (result.status !== 'completed') return false;
+  }
+  return true;
+}
+
+async function isPurchaseEligible(user_id, itemSubscription, itemType, itemId) {
+  if (!itemSubscription || itemSubscription === 'free') return true;
+
+  const activeTiers = await getActiveTiers(user_id);
+  const relevantPlanIds = activeTiers
+    .filter((t) => t.tier === itemSubscription && t.plan_id)
+    .map((t) => t.plan_id);
+  if (!relevantPlanIds.length) return true; // not subscribed at this level — unrestricted, unchanged behavior
+
+  for (const planId of relevantPlanIds) {
+    const policy = await mdl_PlanPolicy.findOne({ where: { plan_id: planId } });
+    const allowlistRules = (policy?.access_rules ?? []).filter((r) => r.type === 'item_allowlist');
+    if (!allowlistRules.length) return true; // this active plan imposes no starter-set gate
+
+    for (const rule of allowlistRules) {
+      if (rule.item_type === itemType && (rule.item_ids ?? []).map(String).includes(String(itemId))) {
+        return true; // item itself is in the free starter set — no purchase needed
+      }
+      if (await areAllItemsComplete(user_id, rule.item_type, rule.item_ids)) {
+        return true; // starter set complete — this plan unlocks paid access to more
+      }
+    }
+  }
+  return false;
+}
+
+exports.canAccessCourse    = canAccessCourse;
+exports.canAccessUnit      = canAccessUnit;
+exports.canAccessLesson    = canAccessLesson;
+exports.isPurchaseEligible = isPurchaseEligible;
 
 const COURSE_LIST_ATTRS = [
   "course_id", "uuid", "title", "description",
@@ -541,6 +607,9 @@ exports.getCourse = async (req, res) => {
         [Op.or]: [{ expires_at: null }, { expires_at: { [Op.gt]: new Date() } }],
       },
     });
+    const purchaseEligible = (!product || hasPurchase)
+      ? true
+      : await isPurchaseEligible(req.user.user_id, plain.subscription, 'course', courseId);
 
     // Certificate status for the course details card
     const [pendingCert, certificate] = await Promise.all([
@@ -559,6 +628,7 @@ exports.getCourse = async (req, res) => {
       plan_tier,
       product:             product ?? null,
       has_purchased:       !!hasPurchase,
+      purchase_eligible:   purchaseEligible,
       pending_certificate: pendingCert ?? null,
       certificate:         certificate ?? null,
     });
@@ -1379,12 +1449,12 @@ exports.getLessonsByUnitUuid = async (req, res) => {
 
     if (!await canAccessUnit(req.user.user_id, unit.unit_id)) {
       const first = unit.courses?.[0] ?? null;
-      const { product, has_purchased } = await buildCheckoutInfo(req.user.user_id, "unit", unit);
+      const { product, has_purchased, purchase_eligible } = await buildCheckoutInfo(req.user.user_id, "unit", unit);
       return res.status(403).json({
         status: "error",
         message: "You do not have access to this unit.",
         course: first ? { title: first.title, subscription: first.subscription } : null,
-        item: { uuid: unit.uuid, subscription: unit.subscription, product, has_purchased },
+        item: { uuid: unit.uuid, subscription: unit.subscription, product, has_purchased, purchase_eligible },
       });
     }
 
@@ -1508,12 +1578,12 @@ exports.getLessonByUuid = async (req, res) => {
 
     if (!await canAccessLesson(req.user.user_id, lesson.lesson_id)) {
       const firstCourse = lesson.units?.[0]?.courses?.[0] ?? null;
-      const { product, has_purchased } = await buildCheckoutInfo(req.user.user_id, "lesson", lesson);
+      const { product, has_purchased, purchase_eligible } = await buildCheckoutInfo(req.user.user_id, "lesson", lesson);
       return res.status(403).json({
         status: "error",
         message: "You do not have access to this lesson.",
         course: firstCourse ? { title: firstCourse.title, subscription: firstCourse.subscription } : null,
-        item: { uuid: lesson.uuid, subscription: lesson.subscription, product, has_purchased },
+        item: { uuid: lesson.uuid, subscription: lesson.subscription, product, has_purchased, purchase_eligible },
       });
     }
 
@@ -1579,7 +1649,10 @@ async function buildCheckoutInfo(user_id, purchasable_type, record) {
       [Op.or]: [{ expires_at: null }, { expires_at: { [Op.gt]: new Date() } }],
     },
   });
-  return { product: product ?? null, has_purchased: !!hasPurchase };
+  const purchaseEligible = (!product || hasPurchase)
+    ? true
+    : await isPurchaseEligible(user_id, record.subscription, purchasable_type, record[CHECKOUT_PK[purchasable_type]]);
+  return { product: product ?? null, has_purchased: !!hasPurchase, purchase_eligible: purchaseEligible };
 }
 
 exports.getCourseCheckoutInfo = async (req, res) => {
@@ -1590,8 +1663,8 @@ exports.getCourseCheckoutInfo = async (req, res) => {
       attributes: ["course_id", "uuid", "title", "description", "level", "subscription"],
     });
     if (!course) return R.error(res, "Course not found.", 404);
-    const { product, has_purchased } = await buildCheckoutInfo(req.user.user_id, "course", course);
-    return R.success(res, "Checkout info retrieved.", { ...course.toJSON(), product, has_purchased });
+    const { product, has_purchased, purchase_eligible } = await buildCheckoutInfo(req.user.user_id, "course", course);
+    return R.success(res, "Checkout info retrieved.", { ...course.toJSON(), product, has_purchased, purchase_eligible });
   } catch (err) {
     console.error("[CLIENT][COURSES][CHECKOUT INFO]", err);
     return R.error(res, "Could not retrieve checkout info.", 500);
@@ -1601,10 +1674,10 @@ exports.getCourseCheckoutInfo = async (req, res) => {
 exports.getUnitCheckoutInfo = async (req, res) => {
   try {
     const { uuid } = req.params;
-    const unit = await Unit.findOne({ where: { uuid, ...notDeleted }, attributes: ["unit_id", "uuid", "title", "description"] });
+    const unit = await Unit.findOne({ where: { uuid, ...notDeleted }, attributes: ["unit_id", "uuid", "title", "description", "subscription"] });
     if (!unit) return R.error(res, "Unit not found.", 404);
-    const { product, has_purchased } = await buildCheckoutInfo(req.user.user_id, "unit", unit);
-    return R.success(res, "Checkout info retrieved.", { ...unit.toJSON(), product, has_purchased });
+    const { product, has_purchased, purchase_eligible } = await buildCheckoutInfo(req.user.user_id, "unit", unit);
+    return R.success(res, "Checkout info retrieved.", { ...unit.toJSON(), product, has_purchased, purchase_eligible });
   } catch (err) {
     console.error("[CLIENT][UNITS][CHECKOUT INFO]", err);
     return R.error(res, "Could not retrieve checkout info.", 500);
@@ -1614,10 +1687,10 @@ exports.getUnitCheckoutInfo = async (req, res) => {
 exports.getLessonCheckoutInfo = async (req, res) => {
   try {
     const { uuid } = req.params;
-    const lesson = await Lesson.findOne({ where: { uuid, ...notDeleted }, attributes: ["lesson_id", "uuid", "title", "description"] });
+    const lesson = await Lesson.findOne({ where: { uuid, ...notDeleted }, attributes: ["lesson_id", "uuid", "title", "description", "subscription"] });
     if (!lesson) return R.error(res, "Lesson not found.", 404);
-    const { product, has_purchased } = await buildCheckoutInfo(req.user.user_id, "lesson", lesson);
-    return R.success(res, "Checkout info retrieved.", { ...lesson.toJSON(), product, has_purchased });
+    const { product, has_purchased, purchase_eligible } = await buildCheckoutInfo(req.user.user_id, "lesson", lesson);
+    return R.success(res, "Checkout info retrieved.", { ...lesson.toJSON(), product, has_purchased, purchase_eligible });
   } catch (err) {
     console.error("[CLIENT][LESSONS][CHECKOUT INFO]", err);
     return R.error(res, "Could not retrieve checkout info.", 500);

controllers/client/units.controller.js

@@ -146,12 +146,18 @@ exports.getUnits = async (req, res) => {
       const is_locked = (row.subscription || Number(row.course_count) > 0)
         ? !(await coursesCtrl.canAccessUnit(req.user.user_id, row.unit_id))
         : false;
+      const product = productById.get(String(row.unit_id)) ?? null;
+      const has_purchased = purchasedIds.has(String(row.unit_id));
+      const purchase_eligible = (is_locked && product && !has_purchased)
+        ? await coursesCtrl.isPurchaseEligible(req.user.user_id, row.subscription, "unit", row.unit_id)
+        : true;
       result.push({
         ...row,
         courses: coursesByUnit.get(row.unit_id) ?? [],
         is_locked,
-        product: productById.get(String(row.unit_id)) ?? null,
-        has_purchased: purchasedIds.has(String(row.unit_id)),
+        product,
+        has_purchased,
+        purchase_eligible,
       });
     }
 
@@ -208,12 +214,18 @@ exports.getLessons = async (req, res) => {
       const is_locked = (row.subscription || Number(row.unit_count) > 0)
         ? !(await coursesCtrl.canAccessLesson(req.user.user_id, row.lesson_id))
         : false;
+      const product = productById.get(String(row.lesson_id)) ?? null;
+      const has_purchased = purchasedIds.has(String(row.lesson_id));
+      const purchase_eligible = (is_locked && product && !has_purchased)
+        ? await coursesCtrl.isPurchaseEligible(req.user.user_id, row.subscription, "lesson", row.lesson_id)
+        : true;
       result.push({
         ...row,
         courses: coursesByLesson.get(row.lesson_id) ?? [],
         is_locked,
-        product: productById.get(String(row.lesson_id)) ?? null,
-        has_purchased: purchasedIds.has(String(row.lesson_id)),
+        product,
+        has_purchased,
+        purchase_eligible,
       });
     }