taleem-kernel 1.2.0 → 1.5.0

package/readme.md

@@ -1,97 +1,285 @@
-## Taleem Kernel API
+# Taleem Kernel — API Reference
 
 ```js
 import kernel from "taleem-kernel";
 ```
 
-`taleem-kernel` is the shared DB/domain layer for Taleem applications. It provides Prisma/SQLite access and Taleem-specific modules.
+`taleem-kernel` is the shared DB/domain layer for Taleem applications. It owns the canonical Prisma/SQLite schema and exposes domain modules — not raw CRUD — used by Taleem Server, Taleem Studio, and other Taleem apps.
 
-### Core
+This doc is organized for lookup: jump to a module, see its methods, signatures, and gotchas.
+
+---
+
+## Module Index
+
+| Module | Purpose |
+|---|---|
+| `kernel.user` | App user registration/auth |
+| `kernel.admin` | Course-scoped admin accounts |
+| `kernel.course` | Course CRUD + access control |
+| `kernel.group` | Structural grouping within a Course |
+| `kernel.library` | Authored content (articles, players, etc.) |
+| `kernel.communication` | Discussion threads on Library items |
+| `kernel.subscription` | User access to a Course |
+| `kernel.svg` / `kernel.image` / `kernel.audio` | Independent reusable assets |
+| `kernel.jwt` | Low-level token utility (avoid calling directly) |
+| `kernel.db` | Raw Prisma client (escape hatch) |
+| `kernel.config` | Kernel config |
+| `kernel.communicationPolicy` | — |
+| `kernel.shutdown()` | Close DB connection |
+
+Relation graph:
+
+```text
+Course
+  └─ Group
+       └─ Library ─── Communication
+Course ─── Subscription
+```
+
+All relations above are real Prisma relations with `onDelete: Restrict` — nothing cascades. Deleting a parent while children exist throws; detach children first.
+
+---
+
+## User
 
 ```js
-kernel.db              // Prisma client
-kernel.config          // configuration
-kernel.auth            // authentication/JWT
-kernel.communicationPolicy
-kernel.shutdown()
+kernel.user.list()
+kernel.user.get(id)
+kernel.user.getByEmail(email)
+kernel.user.emailToId(email)
+kernel.user.register(data)          // { email, password } → hashes password
+kernel.user.login(email, password)  // → JWT string
+kernel.user.createToken(user)
+kernel.user.authenticate(token)     // → User; throws on wrong token type or invalid token
+kernel.user.update(id, data)
+kernel.user.delete(id)
 ```
 
-### Modules
+```js
+const user = await kernel.user.register({ email: "student@example.com", password: "12345678" });
+const token = await kernel.user.login("student@example.com", "12345678");
+const authed = await kernel.user.authenticate(token);
+```
+
+`authenticate()` only accepts tokens with `type: "user"` — an Admin token is rejected here (and vice versa).
+
+---
+
+## Admin
+
+Admins are independent of Course structure; `courseSlugs` is a **plain string field, not a relation** — deliberately unvalidated since Admin provisioning is script-managed, not app/HTTP-facing.
 
 ```js
-kernel.user
-kernel.admin
-kernel.course
-kernel.library
-kernel.communication
-kernel.subscription
-kernel.svg
-kernel.image
-kernel.audio
+kernel.admin.list()
+kernel.admin.get(email)
+kernel.admin.login(email, password)   // → JWT string
+kernel.admin.createToken(admin)
+kernel.admin.authenticate(token)      // → Admin; requires type: "admin"
+kernel.admin.create(data)             // { email, password, courseSlugs: JSON.stringify([...]) }
+kernel.admin.update(email, data)
+kernel.admin.delete(email)
+kernel.admin.isAdmin(email, courseSlug)  // → boolean, course-scoped authorization
 ```
 
-Each module provides simple DB/domain operations such as:
+Authentication and authorization are separate calls — an authenticated Admin is not automatically authorized for every course:
 
 ```js
-list()
-get(...)
-create(data)
-update(id, data)
-delete(id)
+const admin = await kernel.admin.authenticate(token);
+const allowed = await kernel.admin.isAdmin(admin.email, courseSlug); // per-course check
 ```
 
-with additional module-specific methods such as:
+---
+
+## JWT (low-level — avoid direct use)
 
 ```js
-kernel.user.login()
-kernel.user.register()
-kernel.admin.isAdmin()
-kernel.library.listByCourse()
-kernel.communication.listUnanswered()
-kernel.communication.countUserOpenQuestions()
+kernel.jwt.sign(payload)
+kernel.jwt.verify(token)
 ```
 
-### Schema
+Applications should go through `kernel.user.*` / `kernel.admin.*` instead of calling this directly. There is no shared identity module routing between User and Admin — each owns its own token lifecycle.
+
+---
+
+## Course
 
-The kernel owns the **canonical Taleem Prisma/SQLite schema**. Applications using Taleem DB should use the kernel rather than maintaining their own DB layer.
+Course is plain CRUD — created, updated, and retired like any other record. **There is no artifact/seed step.**
 
 ```js
-kernel.auth.authenticate(token)
-kernel.user.login(email, password)
-kernel.course.list()
-kernel.library.get(slug)
-kernel.svg.get(slug)
+kernel.course.list(filters)     // { access, isActive }
+kernel.course.get(slug)
+kernel.course.create(data)      // { slug, title, access }
+kernel.course.update(slug, data)
+kernel.course.delete(slug)      // throws if Groups or Subscriptions still reference it
+kernel.course.authorize(userId, courseSlug)  // → boolean; throws/denies per access tier
 ```
 
-`kernel.shutdown()` disconnects Prisma when the application exits.
+### Access control
 
-## Schema Management
+`Course.access` is one of three tiers:
 
-The kernel provides two CLI commands for maintaining schema compatibility:
+| Tier | `authorize(null, slug)` | `authorize(userId, slug)` with no subscription | `authorize(userId, slug)` with active subscription |
+|---|---|---|---|
+| `OPEN` | ✅ allowed | ✅ allowed | ✅ allowed |
+| `MEMBERS` | ❌ throws | ✅ allowed (just needs to be logged in) | ✅ allowed |
+| `SUBSCRIPTION` | ❌ throws | ❌ throws | ✅ allowed |
 
-```bash
-npx taleem-kernel schema-check
-npx taleem-kernel schema-update
+For `SUBSCRIPTION` courses, `course.authorize()` delegates to `kernel.subscription.authorize(userId, courseSlug)` — see Subscription below for exactly what "active" means.
+
+Since a Course with subscription history can't be hard-deleted (Restrict), retiring a course in practice means `update(slug, { isActive: false })`, not `delete()`.
+
+---
+
+## Group
+
+Uniquely identified by the composite key `(courseSlug, slug)`.
+
+```js
+kernel.group.list(filters)
+kernel.group.listByCourse(courseSlug)
+kernel.group.get(courseSlug, slug)
+kernel.group.create(data)                    // throws if courseSlug doesn't resolve to a Course
+kernel.group.update(courseSlug, slug, data)
+kernel.group.delete(courseSlug, slug)         // throws if any Library rows still reference it
 ```
 
-`schema-check` compares the application's `prisma/schema.prisma` with the canonical schema shipped with `taleem-kernel`.
+---
 
-`schema-update` copies the kernel's canonical schema into the application's `prisma/schema.prisma`.
+## Library
 
-After updating the schema, run the application's normal Prisma migration/generation process as required.
+The actual authored content. Relates to Course only indirectly, through Group (`library.group.course`).
 
-## Server Dependencies
+```js
+kernel.library.list(filters, options)
+kernel.library.listByCourse(courseSlug, options)
+kernel.library.listByGroup(courseSlug, groupSlug, options)
+kernel.library.get(slug, options)
+kernel.library.create(data)     // throws if (courseSlug, groupSlug) doesn't resolve to a Group
+kernel.library.update(slug, data)
+kernel.library.delete(slug)     // throws if any Communication rows still reference it
+kernel.library.createFromSlot(slug, courseSlug, groupSlug, type)
+```
 
-`taleem-server` should use `taleem-kernel` for all Taleem database access.
+Filtering:
 
-The server provides the HTTP/API layer on top of the kernel:
+```js
+kernel.library.list({ type, courseSlug, groupSlug, status }); // status only applied when includeUnpublished is true
+```
+
+### Lifecycle
 
 ```text
-    "@prisma/client": "^6.19.3",
-    "bcrypt": "^6.0.0",
-    "dotenv": "^17.4.2",
-    "jsonwebtoken": "^9.0.3",
-    "zod": "^4.4.3"
+DRAFT → PUBLISHED → ARCHIVED
+```
+
+New items default to `DRAFT`. **`get()` and `list()` return `PUBLISHED` only by default** — the safe default for public routes. Admin/preview contexts must opt in:
+
+```js
+kernel.library.get(slug, { includeUnpublished: true });
+kernel.library.list({ courseSlug }, { includeUnpublished: true });
+```
+
+To retire content that has live discussion, archive it (`update(slug, { status: "ARCHIVED" })`) rather than deleting — delete is blocked while Communication rows exist.
+
+---
+
+## Communication
+
+Discussion threads on a Library item (student questions, teacher notes, comments).
+
+```js
+kernel.communication.list(filters)
+kernel.communication.get(id)                       // includes { user, library }
+kernel.communication.create(data)                   // throws if librarySlug doesn't resolve to a Library row
+kernel.communication.update(id, data)
+kernel.communication.delete(id)
+kernel.communication.listUnanswered(courseSlug)      // authorResponse is null or ""
+kernel.communication.countUserOpenQuestions(userId)  // → number
+```
+
+Filtering:
+
+```js
+kernel.communication.list({
+  courseSlug,  // resolved via the Library relation
+  librarySlug,
+  userId,
+  initiator,   // STUDENT | TEACHER
+  unanswered
+});
+```
+
+`type` (free-form category, e.g. `"user-comment"`) and `initiator` (`STUDENT` default, or `TEACHER`) are independent axes — don't conflate them.
+
+`get()`/`list()` always include `user` and `library` — no second manual query needed.
+
+---
+
+## Subscription
+
+A User's access to a Course.
+
+```js
+kernel.subscription.list(filters)
+kernel.subscription.get(id)
+kernel.subscription.create(data)   // { userId, courseSlug, startsAt, endsAt }
+kernel.subscription.update(id, data)
+kernel.subscription.delete(id)
+kernel.subscription.authorize(userId, courseSlug)  // throws if no ACTIVE subscription
+```
+
+"Active" = `startsAt <= now <= endsAt` for the given `courseSlug`. An expired (`endsAt` in the past) or not-yet-started (`startsAt` in the future) subscription does **not** authorize.
+
+A Course cannot be hard-deleted while any subscription history exists for it — including expired/cancelled ones.
+
+---
+
+## Assets — SVG, Image, Audio
+
+Independent reusable assets. **Not tied to Course, Group, or Library at the DB level** — referenced by slug from content where needed, not by relation.
+
+```js
+kernel.svg.list() / .get(slug) / .create(data) / .update(slug, data) / .delete(slug)
+kernel.image.list() / .get(slug) / .create(data) / .update(slug, data) / .delete(slug)
+kernel.audio.list() / .get(slug) / .create(data) / .update(slug, data) / .delete(slug)
 ```
 
-The server should **not maintain its own Taleem Prisma models or DB modules**.
+**Field shapes are not identical across the three:**
+
+| Field | Audio | Image | Svg |
+|---|---|---|---|
+| `slug` | required | required | required |
+| `title` | optional | optional | optional |
+| `tags` | optional | optional | optional |
+| `body` | — | — | **required** |
+
+Audio and Image currently have **no file-path field** — `create()` will reject unknown keys like `filePath`. How the record maps to an actual file on disk (slug-as-filename convention, or handled at the app layer) is not encoded in the schema — confirm the convention before wiring up upload/serve logic.
+
+Svg stores its content directly in `body` — it's DB-only, no file involved.
+
+---
+
+## Schema Management
+
+```bash
+npx taleem-kernel schema-check   # diff app's Prisma schema vs kernel's canonical schema
+npx taleem-kernel schema-update  # copy kernel's canonical schema into the app
+```
+
+Run the app's normal Prisma migrate/generate after `schema-update`. Applications should not maintain their own Taleem Prisma models — go through the kernel.
+
+---
+
+## Design Principles (quick reference)
+
+1. Course → Group → Library are real Prisma relations, `onDelete: Restrict` throughout. Nothing cascades.
+2. Course is plain CRUD — no artifact/seed step.
+3. Course/Group/Library are separate tables; Library reaches Course only via Group.
+4. Library has explicit lifecycle (DRAFT/PUBLISHED/ARCHIVED); public reads default to PUBLISHED only.
+5. Communication relates to Library by a real relation; `type` and `initiator` are independent.
+6. Subscription relates to Course by a real relation; Course with subscription history can't be hard-deleted.
+7. `Admin.courseSlugs` is a plain string, not a relation — deliberate, script-managed exception.
+8. SVG/Image/Audio are independent assets, no relation to Course/Group/Library.
+9. User and Admin auth are separate domain concerns, each owning its own token lifecycle.
+10. JWT is low-level; go through User/Admin modules, not `kernel.jwt` directly.

package/src/{ServerKernel.js → index.js}

@@ -2,12 +2,13 @@
 
 import { PrismaClient } from "@prisma/client";
 import Config from "./Config.js";
-import Auth from "./Auth.js";
+// import Auth from "./Auth.js";
 import CommunicationPolicy from "./CommunicationPolicy.js";
 import User from "./modules/User.js";
 import Admin from "./modules/Admin.js";
 import Library from "./modules/Library.js";
 import Course from "./modules/Course.js";
+import Group from "./modules/Group.js";
 import Communication from "./modules/Communication.js";
 import Subscription from "./modules/Subscription.js";
 import Image from "./modules/Image.js";
@@ -18,12 +19,13 @@ class ServerKernel {
 	constructor() {
 		this.config = new Config();
 		this.db = new PrismaClient();
-		this.auth = new Auth(this);
+		// this.auth = new Auth(this);
 		this.communicationPolicy = new CommunicationPolicy(this);
 		this.user = new User(this);
 		this.admin = new Admin(this);
 		this.library = new Library(this);
 		this.course = new Course(this);
+		this.group = new Group(this);
 		this.image = new Image(this);
 		this.audio = new Audio(this);
 		this.svg = new Svg(this);

package/src/modules/Admin.js

@@ -1,9 +1,13 @@
-// src/serverKernel/modules/Admin.js
+// /home/bilal-tariq/00--TALEEM/taleem-kernel/src/modules/Admin.js
 
 import bcrypt from "bcrypt";
+import JWT from "../utils/JWT.js";
 
 export default class Admin {
-	constructor(kernel) { this.kernel = kernel; }
+	constructor(kernel) {
+		this.kernel = kernel;
+		this.jwt = new JWT(kernel);
+	}
 
 	async list(filters = {}) {
 		const where = {};
@@ -15,37 +19,95 @@ export default class Admin {
 		return this.kernel.db.admin.findUnique({ where: { email } });
 	}
 
+	// Authentication
+
 	async login(email, password) {
 		const admin = await this.get(email);
-		if (!admin) throw new Error(`Admin.login(): Admin '${email}' not found.`);
-		if (!admin.isActive) throw new Error(`Admin.login(): Admin '${email}' is inactive.`);
+
+		if (!admin) {
+			throw new Error(`Admin.login(): Admin '${email}' not found.`);
+		}
+
+		if (!admin.isActive) {
+			throw new Error(`Admin.login(): Admin '${email}' is inactive.`);
+		}
 
 		const ok = await bcrypt.compare(password, admin.password);
-		if (!ok) throw new Error(`Admin.login(): Invalid password.`);
 
-		return this.kernel.auth.createAdminToken(admin);
+		if (!ok) {
+			throw new Error(`Admin.login(): Invalid password.`);
+		}
+
+		return this.createToken(admin);
+	}
+
+	async createToken(admin) {
+		return this.jwt.sign({
+			email: admin.email,
+			type: "admin"
+		});
+	}
+
+	async authenticate(token) {
+		const payload = this.jwt.verify(token);
+
+		if (payload.type !== "admin") {
+			throw new Error("Admin token required.");
+		}
+
+		const admin = await this.get(payload.email);
+
+		if (!admin) {
+			throw new Error("Admin not found.");
+		}
+
+		if (!admin.isActive) {
+			throw new Error("Admin is inactive.");
+		}
+
+		return admin;
 	}
 
+	// CRUD
+
 	async create(data) {
 		const createData = { ...data };
-		if (createData.password) createData.password = await bcrypt.hash(createData.password, 10);
-		return this.kernel.db.admin.create({ data: createData });
+
+		if (createData.password) {
+			createData.password = await bcrypt.hash(createData.password, 10);
+		}
+
+		return this.kernel.db.admin.create({
+			data: createData
+		});
 	}
 
 	async update(email, data) {
 		const updateData = { ...data };
-		if (updateData.password) updateData.password = await bcrypt.hash(updateData.password, 10);
-		return this.kernel.db.admin.update({ where: { email }, data: updateData });
+
+		if (updateData.password) {
+			updateData.password = await bcrypt.hash(updateData.password, 10);
+		}
+
+		return this.kernel.db.admin.update({
+			where: { email },
+			data: updateData
+		});
 	}
 
 	async delete(email) {
-		return this.kernel.db.admin.delete({ where: { email } });
+		return this.kernel.db.admin.delete({
+			where: { email }
+		});
 	}
 
 	async isAdmin(email, courseSlug) {
 		const admin = await this.get(email);
+
 		if (!admin) return false;
+
 		const courseSlugs = JSON.parse(admin.courseSlugs || "[]");
+
 		return courseSlugs.includes(courseSlug);
 	}
 }

package/src/modules/Communication.js

@@ -8,18 +8,12 @@ export default class Communication {
 		const where = {};
 
 		if (filters.courseSlug) {
-			const items = await this.kernel.db.library.findMany({
-				where: { courseSlug: filters.courseSlug },
-				select: { slug: true }
-			});
-
-			where.librarySlug = {
-				in: items.map(item => item.slug)
-			};
+			where.library = { courseSlug: filters.courseSlug };
 		}
 
 		if (filters.librarySlug) where.librarySlug = filters.librarySlug;
 		if (filters.userId) where.userId = filters.userId;
+		if (filters.initiator) where.initiator = filters.initiator;
 
 		if (filters.unanswered) {
 			where.OR = [
@@ -30,35 +24,20 @@ export default class Communication {
 
 		return this.kernel.db.communication.findMany({
 			where,
-			include: { user: true },
+			include: { user: true, library: true },
 			orderBy: { createdAt: "desc" }
 		});
 	}
 
 	async get(id) {
-		const item = await this.kernel.db.communication.findUnique({
+		return this.kernel.db.communication.findUnique({
 			where: { id },
-			include: { user: true }
+			include: { user: true, library: true }
 		});
-
-		if (!item) return null;
-
-		const library = await this.kernel.db.library.findUnique({
-			where: { slug: item.librarySlug },
-			select: {
-				slug: true,
-				title: true,
-				courseSlug: true
-			}
-		});
-
-		return {
-			...item,
-			library
-		};
 	}
 
 	async create(data) {
+		// throws if librarySlug doesn't resolve to an existing Library row
 		return this.kernel.db.communication.create({ data });
 	}
 
@@ -76,30 +55,7 @@ export default class Communication {
 	}
 
 	async listUnanswered(courseSlug) {
-		const items = await this.list({
-			courseSlug,
-			unanswered: true
-		});
-
-		const slugs = [...new Set(items.map(item => item.librarySlug))];
-
-		const libraries = await this.kernel.db.library.findMany({
-			where: { slug: { in: slugs } },
-			select: {
-				slug: true,
-				title: true,
-				courseSlug: true
-			}
-		});
-
-		const map = new Map(
-			libraries.map(item => [item.slug, item])
-		);
-
-		return items.map(item => ({
-			...item,
-			library: map.get(item.librarySlug) || null
-		}));
+		return this.list({ courseSlug, unanswered: true });
 	}
 
 	async countUserOpenQuestions(userId) {

package/src/modules/Course.js

@@ -4,51 +4,44 @@ export default class Course {
 	async list(filters = {}) {
 		const where = {};
 		if (filters.access) where.access = filters.access;
+		if (filters.isActive !== undefined) where.isActive = filters.isActive;
 		return this.kernel.db.course.findMany({ where });
 	}
+
 	async get(slug) {
 		return this.kernel.db.course.findUnique({ where: { slug } });
 	}
-	async getGroups(courseSlug) {
-		return this.kernel.db.group.findMany({
-			where: { courseSlug },
-			orderBy: { id: 'asc' }
-		});
-	}
-	async getGroup(courseSlug, groupSlug) {
-		return this.kernel.db.group.findUnique({
-			where: {
-				courseSlug_slug: { courseSlug, slug: groupSlug }
-			}
-		});
-	}
-	async getGroupItems(courseSlug, groupSlug) {
-		const group = await this.getGroup(courseSlug, groupSlug);
-		return group?.items ?? [];
-	}
-	async wipe() {
-	await this.kernel.db.group.deleteMany();
-	await this.kernel.db.course.deleteMany();
-	}
-	async seed(course) {
-		const { groupings = [], ...courseData } = course;
-
-		const created = await this.kernel.db.course.create({
-			data: courseData
-		});
-
-		for (const group of groupings) {
-			await this.kernel.db.group.create({
-				data: {
-					courseSlug: created.slug,
-					slug: group.slug,
-					title: group.title,
-					thumbnail: group.thumbnail ?? null,
-					items: group.items ?? []
-				}
-			});
-		}
-
-		return created;
+
+	async create(data) {
+		return this.kernel.db.course.create({ data });
+	}
+
+	async update(slug, data) {
+		return this.kernel.db.course.update({ where: { slug }, data });
+	}
+
+	async delete(slug) {
+		// throws if any Group or Subscription still references this course
+		return this.kernel.db.course.delete({ where: { slug } });
+	}
+
+	async authorize(userId, courseSlug) {
+	const course = await this.get(courseSlug);
+	if (!course) throw new Error(`Course "${courseSlug}" not found.`);
+
+	if (course.access === "OPEN") return true;
+
+	if (course.access === "MEMBERS") {
+		if (!userId) throw new Error("Login required for this course.");
+		return true;
+	}
+
+	if (course.access === "SUBSCRIPTION") {
+		if (!userId) throw new Error("Login required for this course.");
+		await this.kernel.subscription.authorize(userId, courseSlug);
+		return true;
+	}
+
+	throw new Error(`Unknown access level "${course.access}".`);
 	}
 }