@commonpub/learning

Learning path engine for CommonPub.

Overview

Structured learning paths with modules, lessons, enrollment, progress tracking, and certificate generation. Lesson types include articles, videos, quizzes, projects, and interactive explainers (via @commonpub/explainer).

Installation

pnpm add @commonpub/learning

Core Concepts

Learning Path
  -> Module (ordered)
       -> Lesson (ordered)
            - article:   Rich text content
            - video:     Video with transcript
            - quiz:      Questions with scoring
            - project:   Hands-on build exercise
            - explainer: Interactive explainer module

Usage

Progress Tracking

import {
  calculatePathProgress,
  isPathComplete,
  getNextLesson,
  getLessonStatus,
  getCompletionPercentageByModule,
} from '@commonpub/learning';

// Calculate overall path progress
const progress = calculatePathProgress(path, completedLessonIds);
// { completed: 8, total: 12, percentage: 66.7 }

// Check if a path is 100% complete
const done = isPathComplete(path, completedLessonIds);

// Get the next incomplete lesson
const next = getNextLesson(path, completedLessonIds);

// Get status for a specific lesson
const status = getLessonStatus(lessonId, completedLessonIds);
// 'completed' | 'in_progress' | 'locked'

// Progress by module
const moduleProgress = getCompletionPercentageByModule(path, completedLessonIds);
// { 'module-1': 100, 'module-2': 50, 'module-3': 0 }

Certificates

Auto-generated at 100% path completion with verifiable codes:

import {
  generateVerificationCode,
  formatCertificateData,
  buildVerificationUrl,
} from '@commonpub/learning';

// Generate a verification code
const code = generateVerificationCode();
// 'SNAP-A1B2C3-4D5E6F78'

// Format certificate data for display
const cert = formatCertificateData({
  userName: 'Alice',
  pathTitle: 'Electronics 101',
  completedAt: new Date(),
  verificationCode: code,
});

// Build the public verification URL
const url = buildVerificationUrl('hack.build', code);
// 'https://hack.build/certificates/SNAP-A1B2C3-4D5E6F78'

Curriculum Utilities

import {
  flattenLessons,
  countLessons,
  calculateEstimatedDuration,
  formatDuration,
  buildCurriculumTree,
  reorderItems,
} from '@commonpub/learning';

// Flatten all lessons across modules
const allLessons = flattenLessons(path);

// Count total lessons
const count = countLessons(path); // 12

// Estimate total duration
const minutes = calculateEstimatedDuration(path); // 180
const formatted = formatDuration(180); // '3h 0m'

// Build a tree for rendering
const tree = buildCurriculumTree(path);

// Reorder items (drag-and-drop support)
const reordered = reorderItems(items, fromIndex, toIndex);

Validators

import {
  updateLearningPathSchema,
  createModuleSchema,
  updateModuleSchema,
  updateLessonSchema,
  lessonContentSchema,
} from '@commonpub/learning';

Lesson Content Types

type LessonContent =
  | ArticleLessonContent   // { type: 'article', blocks: BlockTuple[] }
  | VideoLessonContent     // { type: 'video', url: string, transcript?: string }
  | QuizLessonContent      // { type: 'quiz', questions: QuizQuestion[] }
  | ProjectLessonContent   // { type: 'project', instructions: BlockTuple[], requirements: string[] }
  | ExplainerLessonContent // { type: 'explainer', explainerId: string }

Development

pnpm build        # Compile TypeScript
pnpm test         # Run 75 tests
pnpm typecheck    # Type-check without emitting

Dependencies

• zod: Input validation
• @commonpub/schema: Table definitions
• @commonpub/config: Feature flags
• @commonpub/explainer: Explainer lesson type integration
• @commonpub/editor: BlockTuple types for article content