feat(ai): Subscription-tier-based rate limiting with credits and questions

Replace role-based AI rate limiting with subscription tiers (free/plus/admin)
and two currencies: questions (AI tutor chat) and credits (content generation).
Credits support variable cost — module generation charges 1 credit per lesson.

Author: rajiv_rago

app/api/ai/chat/route.ts

@@ -35,7 +35,8 @@ export async function POST(request: NextRequest) {
     }
 
     // Rate limit check
-    const rateCheck = await enforceAIRateLimit(user.userId, user.role, "chat");
+    const subTier = user.role === "admin" ? "admin" as const : user.subscriptionTier;
+    const rateCheck = await enforceAIRateLimit(user.userId, subTier, "questions");
     if (rateCheck.blocked) return rateCheck.response;
 
     const body = await request.json();

app/api/ai/generate/route.ts

@@ -41,7 +41,8 @@ export async function POST(request: NextRequest) {
     }
 
     // Rate limit check
-    const rateCheck = await enforceAIRateLimit(user.userId, user.role, "generate");
+    const subTier = user.role === "admin" ? "admin" as const : user.subscriptionTier;
+    const rateCheck = await enforceAIRateLimit(user.userId, subTier, "credits");
     if (rateCheck.blocked) return rateCheck.response;
 
     if (user.role !== "teacher" && user.role !== "admin") {

app/api/courses/ai/[courseId]/generate-all/route.ts

@@ -1,7 +1,7 @@
 import { NextRequest, NextResponse } from "next/server";
 import mongoose from "mongoose";
 import { dbConnect } from "@/lib/db";
-import { Course, Module } from "@/lib/models";
+import { Course, Module, Lesson } from "@/lib/models";
 import { authenticate } from "@/lib/auth";
 import { AIProviderName, AITier } from "@/lib/ai/types";
 import { resolveProvider } from "@/lib/ai/utils/providerResolver";
@@ -22,10 +22,6 @@ export async function POST(
       return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
     }
 
-    // Single rate limit check for the entire batch
-    const rateCheck = await enforceAIRateLimit(user.userId, user.role, "course_generation");
-    if (rateCheck.blocked) return rateCheck.response;
-
     const { courseId } = await params;
 
     if (!mongoose.Types.ObjectId.isValid(courseId)) {
@@ -61,6 +57,31 @@ export async function POST(
       );
     }
 
+    // Find eligible modules (skeleton or failed — skip generating and completed)
+    const eligibleModules = await Module.find({
+      course: courseId,
+      contentStatus: { $in: ["skeleton", "failed"] },
+    }).sort({ order: 1 });
+
+    if (eligibleModules.length === 0) {
+      return NextResponse.json({
+        jobs: [],
+        message: "All modules already completed or generating",
+      });
+    }
+
+    // Count total lessons across all eligible modules to determine credit cost
+    const eligibleModuleIds = eligibleModules.map((m) => m._id);
+    const totalLessonCount = await Lesson.countDocuments({
+      module: { $in: eligibleModuleIds },
+    });
+    const creditCost = Math.max(totalLessonCount, 1);
+
+    // Rate limit check — costs 1 credit per lesson across all eligible modules
+    const subTier = user.role === "admin" ? "admin" as const : user.subscriptionTier;
+    const rateCheck = await enforceAIRateLimit(user.userId, subTier, "credits", creditCost);
+    if (rateCheck.blocked) return rateCheck.response;
+
     // Fail fast: verify provider before enqueueing any jobs
     const { tier: reqTier, provider: reqProvider, model: reqModel } = validation.data;
     const userPreferences = (reqTier || reqProvider) ? undefined : await getUserAIPreferences(user.userId);
@@ -85,19 +106,6 @@ export async function POST(
       );
     }
 
-    // Find eligible modules (skeleton or failed — skip generating and completed)
-    const eligibleModules = await Module.find({
-      course: courseId,
-      contentStatus: { $in: ["skeleton", "failed"] },
-    }).sort({ order: 1 });
-
-    if (eligibleModules.length === 0) {
-      return NextResponse.json({
-        jobs: [],
-        message: "All modules already completed or generating",
-      });
-    }
-
     // Enqueue a job for each eligible module
     const jobs = [];
     for (const mod of eligibleModules) {

app/api/courses/ai/[courseId]/lessons/[lessonId]/generate/route.ts

@@ -22,8 +22,9 @@ export async function POST(
       return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
     }
 
-    // Rate limit check
-    const rateCheck = await enforceAIRateLimit(user.userId, user.role, "course_generation");
+    // Rate limit check — single lesson costs 1 credit
+    const subTier = user.role === "admin" ? "admin" as const : user.subscriptionTier;
+    const rateCheck = await enforceAIRateLimit(user.userId, subTier, "credits");
     if (rateCheck.blocked) return rateCheck.response;
 
     const { courseId, lessonId } = await params;
@@ -114,6 +115,7 @@ export async function POST(
         tier: reqTier,
         provider: reqProvider,
         model: reqModel,
+        feedback: validation.data.feedback,
       },
       userId: user.userId,
     });

app/api/courses/ai/[courseId]/modules/[moduleId]/generate/route.ts

@@ -1,7 +1,7 @@
 import { NextRequest, NextResponse } from "next/server";
 import mongoose from "mongoose";
 import { dbConnect } from "@/lib/db";
-import { Course, Module } from "@/lib/models";
+import { Course, Module, Lesson } from "@/lib/models";
 import { authenticate } from "@/lib/auth";
 import { AIProviderName, AITier } from "@/lib/ai/types";
 import { resolveProvider } from "@/lib/ai/utils/providerResolver";
@@ -22,10 +22,6 @@ export async function POST(
       return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
     }
 
-    // Rate limit check
-    const rateCheck = await enforceAIRateLimit(user.userId, user.role, "course_generation");
-    if (rateCheck.blocked) return rateCheck.response;
-
     const { courseId, moduleId } = await params;
 
     if (
@@ -73,6 +69,15 @@ export async function POST(
       return NextResponse.json({ error: "Module not found" }, { status: 404 });
     }
 
+    // Count lessons in this module to determine credit cost
+    const lessonCount = await Lesson.countDocuments({ module: moduleId });
+    const creditCost = Math.max(lessonCount, 1);
+
+    // Rate limit check — costs 1 credit per lesson in the module
+    const subTier = user.role === "admin" ? "admin" as const : user.subscriptionTier;
+    const rateCheck = await enforceAIRateLimit(user.userId, subTier, "credits", creditCost);
+    if (rateCheck.blocked) return rateCheck.response;
+
     // Fail fast: verify provider
     const { tier: reqTier, provider: reqProvider, model: reqModel } = validation.data;
     const userPreferences = (reqTier || reqProvider) ? undefined : await getUserAIPreferences(user.userId);

app/api/courses/ai/syllabus/route.ts

@@ -33,7 +33,8 @@ export async function POST(request: NextRequest) {
     }
 
     // Rate limit check
-    const rateCheck = await enforceAIRateLimit(user.userId, user.role, "course_generation");
+    const subTier = user.role === "admin" ? "admin" as const : user.subscriptionTier;
+    const rateCheck = await enforceAIRateLimit(user.userId, subTier, "credits");
     if (rateCheck.blocked) return rateCheck.response;
 
     const body = await request.json();

lib/ai/rateLimit.ts

@@ -1,16 +1,15 @@
 import { NextResponse } from "next/server";
 import AIUsage, { AIUsageCategory } from "@/lib/models/AIUsage";
 import { dbConnect } from "@/lib/db";
-
-type UserRole = "student" | "teacher" | "admin";
+import type { SubscriptionTier } from "@/lib/auth/jwt";
 
 /**
- * Daily request limits by role and category.
+ * Daily limits by category and subscription tier.
+ * Infinity means unlimited (skip DB entirely).
  */
-const DAILY_LIMITS: Record<AIUsageCategory, Record<UserRole, number>> = {
-  chat: { student: 50, teacher: 200, admin: 10_000 },
-  generate: { student: 10, teacher: 50, admin: 10_000 },
-  course_generation: { student: 5, teacher: 20, admin: 10_000 },
+const DAILY_LIMITS: Record<AIUsageCategory, Record<SubscriptionTier, number>> = {
+  questions: { free: 50,  plus: Infinity, admin: Infinity },
+  credits:   { free: 10,  plus: 100,      admin: Infinity },
 };
 
 /**
@@ -25,22 +24,36 @@ export interface RateLimitResult {
   limit: number;
   used: number;
   remaining: number;
+  cost: number;
   resetAt: string; // ISO timestamp of next UTC midnight
 }
 
 /**
  * Checks and atomically increments the AI rate limit counter.
- * Race-condition-free: uses conditional $inc so two concurrent requests
- * cannot both sneak past the limit.
+ * Supports variable cost (e.g. 1 credit per lesson in a module).
+ * For unlimited tiers, skips the DB entirely.
  */
 export async function checkAIRateLimit(
   userId: string,
-  role: UserRole,
-  category: AIUsageCategory
+  tier: SubscriptionTier,
+  category: AIUsageCategory,
+  cost: number = 1
 ): Promise<RateLimitResult> {
+  const limit = DAILY_LIMITS[category][tier];
+
+  // Compute next UTC midnight for reset header
+  const tomorrow = new Date();
+  tomorrow.setUTCDate(tomorrow.getUTCDate() + 1);
+  tomorrow.setUTCHours(0, 0, 0, 0);
+  const resetAt = tomorrow.toISOString();
+
+  // Unlimited tier — skip DB entirely
+  if (!isFinite(limit)) {
+    return { allowed: true, limit, used: 0, remaining: Infinity, cost, resetAt };
+  }
+
   await dbConnect();
 
-  const limit = DAILY_LIMITS[category][role];
   const dateKey = getDateKey();
 
   // Ensure document exists
@@ -50,31 +63,26 @@ export async function checkAIRateLimit(
     { upsert: true }
   );
 
-  // Conditionally increment — only if under the limit
+  // Conditionally increment — only if there's enough headroom for the full cost
   const result = await AIUsage.findOneAndUpdate(
-    { user: userId, category, dateKey, count: { $lt: limit } },
-    { $inc: { count: 1 } },
+    { user: userId, category, dateKey, count: { $lte: limit - cost } },
+    { $inc: { count: cost } },
     { new: true }
   );
 
-  // Compute next UTC midnight for reset header
-  const tomorrow = new Date();
-  tomorrow.setUTCDate(tomorrow.getUTCDate() + 1);
-  tomorrow.setUTCHours(0, 0, 0, 0);
-  const resetAt = tomorrow.toISOString();
-
   if (!result) {
     // Limit reached — fetch current count for headers
     const doc = await AIUsage.findOne({ user: userId, category, dateKey });
     const used = doc?.count ?? limit;
-    return { allowed: false, limit, used, remaining: 0, resetAt };
+    return { allowed: false, limit, used, remaining: Math.max(0, limit - used), cost, resetAt };
   }
 
   return {
     allowed: true,
     limit,
     used: result.count,
     remaining: limit - result.count,
+    cost,
     resetAt,
   };
 }
@@ -84,20 +92,23 @@ export async function checkAIRateLimit(
  */
 export async function enforceAIRateLimit(
   userId: string,
-  role: UserRole,
-  category: AIUsageCategory
+  tier: SubscriptionTier,
+  category: AIUsageCategory,
+  cost: number = 1
 ): Promise<
   | { blocked: true; response: NextResponse }
   | { blocked: false; result: RateLimitResult }
 > {
-  const result = await checkAIRateLimit(userId, role, category);
+  const result = await checkAIRateLimit(userId, tier, category, cost);
 
   if (!result.allowed) {
     const response = NextResponse.json(
       {
         error: "Daily AI rate limit exceeded. Please try again tomorrow.",
         limit: result.limit,
         used: result.used,
+        remaining: result.remaining,
+        cost: result.cost,
         resetAt: result.resetAt,
       },
       { status: 429 }

lib/auth/index.ts

@@ -1,5 +1,5 @@
 export { signToken, verifyToken, verifyTokenForRefresh, decodeToken } from "./jwt";
-export type { JWTPayload } from "./jwt";
+export type { JWTPayload, SubscriptionTier } from "./jwt";
 export {
   authenticate,
   getAuthenticatedUser,

lib/auth/jwt.ts

@@ -10,10 +10,13 @@ const JWT_SECRET: string = process.env.JWT_SECRET;
 const JWT_EXPIRES_IN = (process.env.JWT_EXPIRES_IN || "7d") as SignOptions["expiresIn"];
 const REFRESH_GRACE_PERIOD_SECONDS = 60 * 60; // 1 hour in seconds
 
+export type SubscriptionTier = "free" | "plus" | "admin";
+
 export interface JWTPayload {
   userId: string;
   email: string;
   role: "student" | "teacher" | "admin";
+  subscriptionTier: SubscriptionTier;
   iat?: number;
   exp?: number;
 }
@@ -23,6 +26,7 @@ export function signToken(user: IUser): string {
     userId: user._id.toString(),
     email: user.email,
     role: user.role,
+    subscriptionTier: user.role === "admin" ? "admin" : (user.subscriptionTier || "free"),
   };
 
   return jwt.sign(payload, JWT_SECRET, {

lib/models/AIUsage.ts

@@ -1,6 +1,6 @@
 import mongoose, { Schema, Document, Types } from "mongoose";
 
-export type AIUsageCategory = "chat" | "generate" | "course_generation";
+export type AIUsageCategory = "questions" | "credits";
 
 export interface IAIUsage extends Document {
   _id: Types.ObjectId;
@@ -22,7 +22,7 @@ const AIUsageSchema = new Schema<IAIUsage>(
     },
     category: {
       type: String,
-      enum: ["chat", "generate", "course_generation"],
+      enum: ["questions", "credits"],
       required: true,
     },
     dateKey: {