taleem-kernel 1.3.0 → 1.5.0

package/readme.md

@@ -1,505 +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 owns the canonical Taleem Prisma/SQLite schema and provides the domain modules used by Taleem Server, Taleem Studio, and other Taleem applications.
-
-The kernel is intentionally small: modules expose operations that make sense for Taleem rather than blindly exposing Prisma CRUD.
-
----
-
-## Core
-
-```js
-kernel.db
-
-kernel.config
-
-kernel.jwt
-
-kernel.communicationPolicy
-
-kernel.shutdown()
 ```
 
-`kernel.jwt` is the low-level JWT utility used by the User and Admin 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.
 
-Applications normally should not create or verify application identity tokens directly through `kernel.jwt`. Instead, use the authentication methods on the appropriate domain module.
+This doc is organized for lookup: jump to a module, see its methods, signatures, and gotchas.
 
 ---
 
-## Modules
-
-```js
-kernel.user
-
-kernel.admin
-
-kernel.course
+## 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:
 
-kernel.library
-
-kernel.communication
-
-kernel.subscription
-
-kernel.svg
-
-kernel.image
-
-kernel.audio
+```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
 
-Users are the normal Taleem application users.
-
-User registration and authentication are owned directly by the User module.
-
-### User API
-
 ```js
 kernel.user.list()
-
 kernel.user.get(id)
-
 kernel.user.getByEmail(email)
-
 kernel.user.emailToId(email)
-
-kernel.user.register(data)
-
-kernel.user.login(email, password)
-
+kernel.user.register(data)          // { email, password } → hashes password
+kernel.user.login(email, password)  // → JWT string
 kernel.user.createToken(user)
-
-kernel.user.authenticate(token)
-
+kernel.user.authenticate(token)     // → User; throws on wrong token type or invalid token
 kernel.user.update(id, data)
-
 kernel.user.delete(id)
 ```
 
-Registration creates a User and hashes the supplied password:
-
 ```js
-const user = await kernel.user.register({
-  email: "student@example.com",
-  password: "12345678"
-});
+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);
 ```
 
-Login returns a User JWT:
-
-```js
-const token = await kernel.user.login(
-  "student@example.com",
-  "12345678"
-);
-```
-
-The token can then be authenticated:
-
-```js
-const user = await kernel.user.authenticate(token);
-```
-
-User authentication accepts only tokens with:
-
-```js
-{
-  type: "user"
-}
-```
-
-The User module creates its own tokens using the kernel JWT utility.
+`authenticate()` only accepts tokens with `type: "user"` — an Admin token is rejected here (and vice versa).
 
 ---
 
 ## Admin
 
-Admins are independent of Course structure.
-
-An Admin may be assigned one or more course slugs through `courseSlugs`.
-
-Admin accounts are provisioned separately from normal User registration.
-
-### Admin API
+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.admin.list()
-
 kernel.admin.get(email)
-
-kernel.admin.login(email, password)
-
+kernel.admin.login(email, password)   // → JWT string
 kernel.admin.createToken(admin)
-
-kernel.admin.authenticate(token)
-
-kernel.admin.create(data)
-
+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)
+kernel.admin.isAdmin(email, courseSlug)  // → boolean, course-scoped authorization
 ```
 
-Admin login returns an Admin JWT:
-
-```js
-const token = await kernel.admin.login(
-  "admin@example.com",
-  "12345678"
-);
-```
-
-The token can then be authenticated:
+Authentication and authorization are separate calls — an authenticated Admin is not automatically authorized for every course:
 
 ```js
 const admin = await kernel.admin.authenticate(token);
+const allowed = await kernel.admin.isAdmin(admin.email, courseSlug); // per-course check
 ```
 
-Admin authentication accepts only tokens with:
-
-```js
-{
-  type: "admin"
-}
-```
-
-Admin authorization is handled separately:
-
-```js
-const allowed = await kernel.admin.isAdmin(
-  admin.email,
-  courseSlug
-);
-```
-
-Authentication and authorization are separate concerns.
-
-An authenticated Admin is not automatically authorized for every Course.
-
 ---
 
-## JWT
-
-JWT is the low-level token utility used by the User and Admin modules.
+## JWT (low-level — avoid direct use)
 
 ```js
 kernel.jwt.sign(payload)
-
 kernel.jwt.verify(token)
 ```
 
-User and Admin own their respective identity tokens.
-
-Applications should normally use:
-
-```js
-kernel.user.login(...)
-kernel.user.authenticate(...)
-
-kernel.admin.login(...)
-kernel.admin.authenticate(...)
-```
-
-rather than calling `kernel.jwt` directly.
-
-The important architectural rule is:
-
-```text
-JWT
- ↓
- ├── User
- │    ├── login()
- │    ├── createToken()
- │    └── authenticate()
- │
- └── Admin
-      ├── login()
-      ├── createToken()
-      └── authenticate()
-```
-
-There is no shared identity/authentication module routing between User and Admin.
+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
 
-Course is **not a CRUD entity**.
-
-A Course originates as a static course artifact (`course.json`). The artifact is the source of truth and is materialized into the database by the kernel.
-
-Internally, a Course is represented by two tables:
-
-```text
-Course
-  |
-  +-- Group
-       |
-       +-- items[]  // library slugs
-```
-
-There are intentionally no Prisma relationships between Course, Group, and Library. Their relationship is maintained through Taleem slugs.
-
-### Course API
+Course is plain CRUD — created, updated, and retired like any other record. **There is no artifact/seed step.**
 
 ```js
-kernel.course.list()
-
-kernel.course.get(courseSlug)
-
-kernel.course.getGroups(courseSlug)
-
-kernel.course.getGroup(courseSlug, groupSlug)
+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.course.getGroupItems(courseSlug, groupSlug)
+### Access control
 
-kernel.course.seed(course)
+`Course.access` is one of three tiers:
 
-kernel.course.wipe()
-```
+| 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 |
 
-`seed()` materializes a complete course artifact:
+For `SUBSCRIPTION` courses, `course.authorize()` delegates to `kernel.subscription.authorize(userId, courseSlug)` — see Subscription below for exactly what "active" means.
 
-```js
-await kernel.course.seed(course);
-```
+Since a Course with subscription history can't be hard-deleted (Restrict), retiring a course in practice means `update(slug, { isActive: false })`, not `delete()`.
 
-`wipe()` removes the materialized Course and Group data before rebuilding from the source artifacts:
+---
 
-```js
-await kernel.course.wipe();
-```
+## Group
 
-There are deliberately no:
+Uniquely identified by the composite key `(courseSlug, slug)`.
 
 ```js
-course.create()
-
-course.update()
-
-course.delete()
+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
 ```
 
-because a Course is an artifact, not an independently edited CRUD record.
-
 ---
 
 ## Library
 
-Library contains the actual authored Taleem content.
-
-Library items belong logically to a Course and Group through string slugs:
-
-```text
-Library.courseSlug → Course.slug
-
-Library.groupSlug  → Group.slug
-
-Library.slug       → Group.items[]
-```
-
-These are application-level relationships, not Prisma foreign keys.
-
-### Library API
+The actual authored content. Relates to Course only indirectly, through Group (`library.group.course`).
 
 ```js
-kernel.library.list()
-
-kernel.library.listByCourse(courseSlug)
-
-kernel.library.listByGroup(courseSlug, groupSlug)
-
-kernel.library.get(slug)
-
-kernel.library.create(data)
-
+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)
+kernel.library.delete(slug)     // throws if any Communication rows still reference it
+kernel.library.createFromSlot(slug, courseSlug, groupSlug, type)
 ```
 
 Filtering:
 
 ```js
-kernel.library.list({
-  type,
-  courseSlug,
-  groupSlug
-});
+kernel.library.list({ type, courseSlug, groupSlug, status }); // status only applied when includeUnpublished is true
 ```
 
-`list()` returns the library metadata needed by applications without requiring the full content body.
-
-Library items also have a lifecycle status:
+### Lifecycle
 
 ```text
-DRAFT
-PUBLISHED
-ARCHIVED
+DRAFT → PUBLISHED → ARCHIVED
 ```
 
-The default status for a new Library item is:
+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:
 
-```text
-DRAFT
+```js
+kernel.library.get(slug, { includeUnpublished: true });
+kernel.library.list({ courseSlug }, { includeUnpublished: true });
 ```
 
----
-
-## Assets
-
-SVG, Image, and Audio are independent reusable assets.
-
-They are not tied to Courses, Groups, or Library records at the database level.
-
-Their metadata is intentionally small:
+To retire content that has live discussion, archive it (`update(slug, { status: "ARCHIVED" })`) rather than deleting — delete is blocked while Communication rows exist.
 
-```text
-slug
+---
 
-title
+## Communication
 
-tags
-```
-
-Assets can be discovered through tags and referenced by content where appropriate.
+Discussion threads on a Library item (student questions, teacher notes, comments).
 
 ```js
-kernel.svg
-
-kernel.image
-
-kernel.audio
+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
 ```
 
-These modules provide the normal asset operations such as:
+Filtering:
 
 ```js
-list()
-
-get()
-
-create()
-
-update()
-
-delete()
+kernel.communication.list({
+  courseSlug,  // resolved via the Library relation
+  librarySlug,
+  userId,
+  initiator,   // STUDENT | TEACHER
+  unanswered
+});
 ```
 
----
-
-## Schema
+`type` (free-form category, e.g. `"user-comment"`) and `initiator` (`STUDENT` default, or `TEACHER`) are independent axes — don't conflate them.
 
-The kernel owns the **canonical Taleem Prisma/SQLite schema**.
-
-Applications using the Taleem database should use the kernel rather than maintaining their own DB/domain layer.
-
-The important architectural rule is:
-
-```text
-Kernel
-
-  ↓
-
-Canonical schema + Taleem domain operations
-
-  ↓
-
-Applications
-```
-
-Applications should not bypass the kernel for normal Taleem DB operations.
+`get()`/`list()` always include `user` and `library` — no second manual query needed.
 
 ---
 
-## Schema Management
+## Subscription
 
-The kernel provides CLI commands for maintaining schema compatibility:
+A User's access to a Course.
 
-```bash
-npx taleem-kernel schema-check
-
-npx taleem-kernel schema-update
+```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
 ```
 
-`schema-check` compares the application's Prisma schema with the canonical schema shipped with `taleem-kernel`.
+"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.
 
-`schema-update` copies the kernel's canonical schema into the application's Prisma schema.
-
-After updating the schema, run the application's normal Prisma migration/generation process as required.
+A Course cannot be hard-deleted while any subscription history exists for it — including expired/cancelled ones.
 
 ---
 
-## Server Dependencies
-
-`taleem-server` should use `taleem-kernel` for all Taleem database access.
-
-The server provides the HTTP/API layer on top of the kernel.
+## Assets — SVG, Image, Audio
 
-The server should **not maintain its own Taleem Prisma models or duplicate DB modules**.
-
-Authentication at the server layer should use the appropriate Kernel identity module:
+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
-const user = await kernel.user.authenticate(token);
+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)
 ```
 
-or:
+**Field shapes are not identical across the three:**
 
-```js
-const admin = await kernel.admin.authenticate(token);
-```
+| Field | Audio | Image | Svg |
+|---|---|---|---|
+| `slug` | required | required | required |
+| `title` | optional | optional | optional |
+| `tags` | optional | optional | optional |
+| `body` | — | — | **required** |
 
-Course-level Admin authorization can then be checked separately:
+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.
 
-```js
-const allowed = await kernel.admin.isAdmin(
-  admin.email,
-  courseSlug
-);
-```
+Svg stores its content directly in `body` — it's DB-only, no file involved.
 
 ---
 
-## Design Principles
-
-The kernel follows a few important Taleem-specific rules:
-
-1. **Course artifacts are the source of truth.**
-
-2. **Course is not generic CRUD.** It is materialized from the course artifact.
-
-3. **Course and Group are internally separate tables but one domain concept.**
-
-4. **Course, Group, and Library are connected by slugs, not Prisma relationships.**
-
-5. **Relational integrity is enforced by the Taleem build/application layer.**
-
-6. **Library contains authored content; Course defines the expected structure and item slugs.**
-
-7. **Library content has an explicit lifecycle: DRAFT, PUBLISHED, and ARCHIVED.**
-
-8. **SVG, Image, and Audio are independent reusable assets.**
-
-9. **User and Admin authentication are separate domain concerns.**
+## Schema Management
 
-10. **JWT is a low-level utility; User and Admin own their identity token lifecycle.**
+```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
+```
 
-11. **The kernel exposes domain operations only where they represent real Taleem behavior.**
+Run the app's normal Prisma migrate/generate after `schema-update`. Applications should not maintain their own Taleem Prisma models — go through the kernel.
 
-The goal is a small, stable kernel that owns the Taleem contract without pretending to be a generic CRUD framework.
+---
 
+## 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}

@@ -8,6 +8,7 @@ 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";
@@ -24,6 +25,7 @@ class ServerKernel {
 		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);