@hiyve/courses

Framework-agnostic engine for structured courses. A provider — a coach, trainer, teacher or clinician — builds a course of sections, lessons and blocks and enrolls their own clients, who work through it at their own pace. The engine decides what each client can open (prerequisites, drip timers, provider approval), keeps locked lessons away from clients until they open, tracks progress across devices and scores quizzes. You choose where courses are kept: your own backend, memory, or Hiyve user files from the /hiyve entry.

Installation

npm install @hiyve/courses
Copy

Quick start

import {
  addLesson,
  addSection,
  completeLesson,
  computeLessonStates,
  createCourse,
  createMemoryCourseBackend,
  createMemoryCourseStorage,
  createProgress,
  enrollClient,
} from '@hiyve/courses';

const backend = createMemoryCourseBackend();
const provider = createMemoryCourseStorage({ userId: 'coach@example.com', backend });
const client = createMemoryCourseStorage({ userId: 'client@example.com', backend });

// Build a course: Week 1 is open at once; Week 2 opens seven days after enrollment.
let course = createCourse({ title: 'Strength basics', ownerId: provider.userId });
const week1 = addSection(course, { title: 'Week 1' });
const warmUp = addLesson(week1.course, week1.section.id, { title: 'Warm-up' });
course = warmUp.course;
const week2 = addSection(course, { title: 'Week 2' });
course = addLesson(week2.course, week2.section.id, {
  title: 'Progressions',
  access: { drip: { afterEnrollmentDays: 7 } },
}).course;
course = await provider.createCourse(course);

// Enroll a client; lessons they can have now are opened to them.
const { enrollment } = await enrollClient(provider, course, { userId: 'client@example.com', userName: 'Sam' });

// The client works through the course.
let progress = createProgress(enrollment);
progress = completeLesson(progress, warmUp.lesson.id);
progress = await client.saveProgress(progress);

computeLessonStates(course, enrollment, progress);
// { [lessonId]: { status: 'completed' | 'available' | 'locked' | 'awaiting-approval', reasons, … } }
Copy

Courses

A course is a tree: Course → Section → Lesson → Block. The course holds the outline and each lesson's unlock rules; a lesson's blocks are kept separately (LessonContent) so they reach a client only once the lesson opens to them.

Blocks with required: true count toward completing their lesson.

Building

Every function returns a new object and leaves its input unchanged.

Unlock rules

Each lesson's access can require other lessons (prerequisites), carry a due date (due, a Schedule like drip's — it marks an unfinished lesson overdue and never locks anything), release on a timer (drip: { afterEnrollmentDays }, or { onDate } with an ISO 8601 moment carrying its offset, like '2026-10-14T09:00:00Z' — a date on its own, 'YYYY-MM-DD', means midnight UTC, the same moment wherever it is checked, and must be a real calendar date), and require the provider's approval once completed (requiresApproval). A course with settings.progression: 'sequential' also requires each lesson's predecessor.

A lesson with a drip rule, one that needs a lesson requiring approval, or one that needs a lesson that is itself hard-locked (however far down the chain) is hard-locked: its content and files are not readable by the client until it opens. A lesson hard-locked only because of the lesson it needs opens together with that lesson, then stays locked on screen until its prerequisites are met. Every other lesson is opened at enrollment and locked on screen only, so it opens the moment its prerequisites are met.

Enrollment overviews

listEnrollmentOverviews(courseId) on the storage returns an EnrollmentOverview per client — status, what is open, approval decisions and completed lessons — without loading each client's progress, so provider screens stay fast with many clients.

LockReason is one of prerequisite (with lessonIds), approval (completed lessons awaiting approval), drip (with availableAt), paused, removed, or access-pending — the rules are met but the provider's app hasn't opened the lesson yet.

Drip lessons and lessons behind an approval open when the provider's app runs syncAccess (or syncCourseAccess) — on enrollment, after an approval, after a course edit, and from time to time while it is open. A server of your own can open them on time by implementing grantLessonAccess in your CourseStorage.

Time arguments (TimeInput) accept a Date, epoch milliseconds or an ISO 8601 string.

Progress

The client writes their own Progress; the provider reads it.

Quizzes

Questions are single-choice, multi-choice, short-text (matched ignoring case and extra spaces), number (with an optional tolerance), long-text and scale; the last two are never scored.

A quiz with scoring: 'auto' is scored on submission, and its right answers travel with the lesson — a determined client can read them. With scoring: 'review' the provider scores it and the right answers never reach clients: save lessons with saveLesson, which keeps them in the course's private answers (CourseKeys).

Submissions and review

A client answers a submission block as often as they like; every Submission is kept. The provider comments — pinned to a moment in a recording, a page or an area of a photo (CommentAnchor), with text and/or an attached recording or file — and gives a status from their own list (ReviewStatus). The client replies. The client's submissions and replies live in their progress; the provider's comments and statuses live in the enrollment, so each document keeps one writer. Files cross over: the client's recordings become readable by the provider when progress is saved, and the provider's attachments become readable by the client when the enrollment is saved.

Personalizing, templates and duplicates

Lessons for one client. A provider can add lessons for one client only and hide course lessons from them. Both live in that client's enrollment (clientLessons, hiddenLessons), so no one else is affected; the unlock rules, progress and overviews all work on the client's own version of the course.

Duplicates and templates. duplicateCourse(storage, courseId, { title?, isTemplate? }) copies a course — outline, lessons and private answers, not enrollments — sharing its stored files, as a draft; deleting either keeps files the other still uses. A course with isTemplate: true is a starting point rather than a course clients take. Your app can also supply ready-made outlines as plain data (CourseTemplate, with TemplateSections and TemplateLessons whose prerequisites name other lessons' keys): createCourseFromTemplate(storage, template, { title? }) saves one as a new course, and instantiateTemplate(template, { ownerId }) makes the documents without saving.

Falling behind. behindReason(course, overview, now?, { inactiveDays?, startGraceDays? }) says whether a client is behind — 'overdue' (a lesson's due date has passed; overdueLessonIds lists them), 'not-started' (enrolled a while ago, not begun) or 'inactive' (no activity for a while, lessons left) — or returns null (BehindReason, BehindOptions). Reminders are your app's: check overdueLessons on a schedule and send them however you like.

Storage

Everything is saved through a CourseStorage. Each document has one writer: the provider writes the course, its lessons, its private answers and every enrollment; the client writes only their progress. Saves return the document as saved, with revision increased. A save that would overwrite a newer copy rejects with a CourseStorageError whose code is 'conflict'; progress and enrollments are merged instead.

deleteLessonContent(courseId, lessonId) removes one lesson's content. Besides the documents above, a provider has private review settings (ProviderSettings): loadProviderSettings() and saveProviderSettings(settings).

Workflows

Each runs the engine against a storage and leaves the stored documents consistent with the unlock rules.

Hiyve user files

@hiyve/courses/hiyve keeps courses in Hiyve user files, in a /Courses folder, each shared with exactly the people allowed to read it:

import { createHiyveCourseStorage } from '@hiyve/courses/hiyve';

const storage = createHiyveCourseStorage({
  store,                                   // your HiyveStore
  userId: 'coach@example.com',
  getFileClient: () => store.getSlice('client').client,
});
Copy

The result is a HiyveCourseStorage: a CourseStorage plus canWrite() and refresh(). Creating documents, sharing and reading work without a room. Changing a saved document needs a connected client — a room or a no-video room; without one, such saves reject with code: 'not-ready' and canWrite() is false. subscribe reports { type: 'resync' } whenever the user's file list changes. HIYVE_COURSE_RESOURCE_TYPES lists the resource types course documents carry, for filtering them out of a file manager.

Defaults

Types

Course, CourseStatus, CourseSettings, CourseProgression, CourseSummary, Section, LessonSummary, AccessRule, DripRule, Schedule, LessonContent, Block, BlockBase, BlockType, VideoBlock, AudioBlock, FileBlock, RichTextBlock, RichTextDoc, EmbedBlock, LiveSessionBlock, QuizBlock, CustomBlock, MediaRef, Question, QuestionKind, SingleChoiceQuestion, MultiChoiceQuestion, ShortTextQuestion, NumberQuestion, LongTextQuestion, ScaleQuestion, ChoiceOption, QuizScoring, QuizAnswer, QuizAnswers, QuizAttempt, QuestionKey, QuizKey, CourseKeys, ClientLesson, CourseTemplate, TemplateSection, TemplateLesson, ClientLessonResult, SubmissionBlock, SubmissionKind, Submission, SubmissionSummary, SubmissionComment, CommentSummary, CommentAnchor, CommentInput, SubmissionInput, ReviewStatus, ReviewTone, AppliedReviewStatus, SubmissionReview, ProviderSettings, ReviewInput, ReviewResult, ClientRef, Enrollment, EnrollmentOverview, EnrollmentStatus, EnrollmentSummary, GrantReason, LessonGrant, LessonApproval, ManualCompletion, Progress, BlockProgress, BlockResult, LessonProgress, LastVisited, CourseSchemaVersion.

Requirements

• Any JavaScript environment with fetch and File (modern browsers, Node 20+).
• @hiyve/core — only for the /hiyve entry.