@lssm/module.learning-journey 0.0.0-canary-20251217052941 → 0.0.0-canary-20251217060433

package/dist/contracts/operations.d.ts

@@ -0,0 +1,279 @@
+import * as _lssm_lib_schema211 from "@lssm/lib.schema";
+import * as _lssm_lib_contracts31 from "@lssm/lib.contracts";
+
+//#region src/contracts/operations.d.ts
+/**
+ * Enroll in a course.
+ */
+declare const EnrollInCourseContract: _lssm_lib_contracts31.ContractSpec<_lssm_lib_schema211.SchemaModel<{
+  courseId: {
+    type: _lssm_lib_schema211.FieldType<string, string>;
+    isOptional: false;
+  };
+}>, _lssm_lib_schema211.SchemaModel<{
+  id: {
+    type: _lssm_lib_schema211.FieldType<string, string>;
+    isOptional: false;
+  };
+  learnerId: {
+    type: _lssm_lib_schema211.FieldType<string, string>;
+    isOptional: false;
+  };
+  courseId: {
+    type: _lssm_lib_schema211.FieldType<string, string>;
+    isOptional: false;
+  };
+  status: {
+    type: _lssm_lib_schema211.FieldType<string, string>;
+    isOptional: false;
+  };
+  progress: {
+    type: _lssm_lib_schema211.FieldType<number, number>;
+    isOptional: false;
+  };
+  startedAt: {
+    type: _lssm_lib_schema211.FieldType<Date, string>;
+    isOptional: true;
+  };
+  completedAt: {
+    type: _lssm_lib_schema211.FieldType<Date, string>;
+    isOptional: true;
+  };
+}>, undefined>;
+/**
+ * Complete a lesson.
+ */
+declare const CompleteLessonContract: _lssm_lib_contracts31.ContractSpec<_lssm_lib_schema211.SchemaModel<{
+  lessonId: {
+    type: _lssm_lib_schema211.FieldType<string, string>;
+    isOptional: false;
+  };
+  score: {
+    type: _lssm_lib_schema211.FieldType<number, number>;
+    isOptional: true;
+  };
+  timeSpent: {
+    type: _lssm_lib_schema211.FieldType<number, number>;
+    isOptional: false;
+  };
+}>, _lssm_lib_schema211.SchemaModel<{
+  success: {
+    type: _lssm_lib_schema211.FieldType<boolean, boolean>;
+    isOptional: false;
+  };
+  xpEarned: {
+    type: _lssm_lib_schema211.FieldType<number, number>;
+    isOptional: true;
+  };
+}>, undefined>;
+/**
+ * Submit a card review.
+ */
+declare const SubmitCardReviewContract: _lssm_lib_contracts31.ContractSpec<_lssm_lib_schema211.SchemaModel<{
+  cardId: {
+    type: _lssm_lib_schema211.FieldType<string, string>;
+    isOptional: false;
+  };
+  rating: {
+    type: _lssm_lib_schema211.FieldType<string, string>;
+    isOptional: false;
+  };
+  responseTimeMs: {
+    type: _lssm_lib_schema211.FieldType<number, number>;
+    isOptional: true;
+  };
+}>, _lssm_lib_schema211.SchemaModel<{
+  success: {
+    type: _lssm_lib_schema211.FieldType<boolean, boolean>;
+    isOptional: false;
+  };
+  xpEarned: {
+    type: _lssm_lib_schema211.FieldType<number, number>;
+    isOptional: true;
+  };
+}>, undefined>;
+/**
+ * Get cards due for review.
+ */
+declare const GetDueCardsContract: _lssm_lib_contracts31.ContractSpec<_lssm_lib_schema211.SchemaModel<{
+  deckId: {
+    type: _lssm_lib_schema211.FieldType<string, string>;
+    isOptional: true;
+  };
+  limit: {
+    type: _lssm_lib_schema211.FieldType<number, number>;
+    isOptional: true;
+  };
+}>, _lssm_lib_schema211.SchemaModel<{
+  cards: {
+    type: _lssm_lib_schema211.SchemaModel<{
+      id: {
+        type: _lssm_lib_schema211.FieldType<string, string>;
+        isOptional: false;
+      };
+      deckId: {
+        type: _lssm_lib_schema211.FieldType<string, string>;
+        isOptional: false;
+      };
+      front: {
+        type: _lssm_lib_schema211.FieldType<string, string>;
+        isOptional: false;
+      };
+      back: {
+        type: _lssm_lib_schema211.FieldType<string, string>;
+        isOptional: false;
+      };
+      hints: {
+        type: _lssm_lib_schema211.FieldType<unknown, unknown>;
+        isOptional: true;
+      };
+      isDue: {
+        type: _lssm_lib_schema211.FieldType<boolean, boolean>;
+        isOptional: false;
+      };
+      nextReviewAt: {
+        type: _lssm_lib_schema211.FieldType<Date, string>;
+        isOptional: true;
+      };
+    }>;
+    isArray: true;
+    isOptional: false;
+  };
+  total: {
+    type: _lssm_lib_schema211.FieldType<number, number>;
+    isOptional: false;
+  };
+}>, undefined>;
+/**
+ * Get learner dashboard.
+ */
+declare const GetLearnerDashboardContract: _lssm_lib_contracts31.ContractSpec<_lssm_lib_schema211.SchemaModel<{
+  learnerId: {
+    type: _lssm_lib_schema211.FieldType<string, string>;
+    isOptional: true;
+  };
+}>, _lssm_lib_schema211.SchemaModel<{
+  learner: {
+    type: _lssm_lib_schema211.SchemaModel<{
+      id: {
+        type: _lssm_lib_schema211.FieldType<string, string>;
+        isOptional: false;
+      };
+      userId: {
+        type: _lssm_lib_schema211.FieldType<string, string>;
+        isOptional: false;
+      };
+      displayName: {
+        type: _lssm_lib_schema211.FieldType<string, string>;
+        isOptional: true;
+      };
+      level: {
+        type: _lssm_lib_schema211.FieldType<number, number>;
+        isOptional: false;
+      };
+      totalXp: {
+        type: _lssm_lib_schema211.FieldType<number, number>;
+        isOptional: false;
+      };
+      currentStreak: {
+        type: _lssm_lib_schema211.FieldType<number, number>;
+        isOptional: false;
+      };
+      longestStreak: {
+        type: _lssm_lib_schema211.FieldType<number, number>;
+        isOptional: false;
+      };
+      createdAt: {
+        type: _lssm_lib_schema211.FieldType<Date, string>;
+        isOptional: false;
+      };
+    }>;
+    isOptional: false;
+  };
+  currentStreak: {
+    type: _lssm_lib_schema211.FieldType<number, number>;
+    isOptional: false;
+  };
+  dailyXpGoal: {
+    type: _lssm_lib_schema211.FieldType<number, number>;
+    isOptional: false;
+  };
+  dailyXpProgress: {
+    type: _lssm_lib_schema211.FieldType<number, number>;
+    isOptional: false;
+  };
+  activeEnrollments: {
+    type: _lssm_lib_schema211.SchemaModel<{
+      id: {
+        type: _lssm_lib_schema211.FieldType<string, string>;
+        isOptional: false;
+      };
+      learnerId: {
+        type: _lssm_lib_schema211.FieldType<string, string>;
+        isOptional: false;
+      };
+      courseId: {
+        type: _lssm_lib_schema211.FieldType<string, string>;
+        isOptional: false;
+      };
+      status: {
+        type: _lssm_lib_schema211.FieldType<string, string>;
+        isOptional: false;
+      };
+      progress: {
+        type: _lssm_lib_schema211.FieldType<number, number>;
+        isOptional: false;
+      };
+      startedAt: {
+        type: _lssm_lib_schema211.FieldType<Date, string>;
+        isOptional: true;
+      };
+      completedAt: {
+        type: _lssm_lib_schema211.FieldType<Date, string>;
+        isOptional: true;
+      };
+    }>;
+    isArray: true;
+    isOptional: false;
+  };
+  recentAchievements: {
+    type: _lssm_lib_schema211.SchemaModel<{
+      id: {
+        type: _lssm_lib_schema211.FieldType<string, string>;
+        isOptional: false;
+      };
+      key: {
+        type: _lssm_lib_schema211.FieldType<string, string>;
+        isOptional: false;
+      };
+      name: {
+        type: _lssm_lib_schema211.FieldType<string, string>;
+        isOptional: false;
+      };
+      description: {
+        type: _lssm_lib_schema211.FieldType<string, string>;
+        isOptional: false;
+      };
+      icon: {
+        type: _lssm_lib_schema211.FieldType<string, string>;
+        isOptional: true;
+      };
+      xpReward: {
+        type: _lssm_lib_schema211.FieldType<number, number>;
+        isOptional: false;
+      };
+      unlockedAt: {
+        type: _lssm_lib_schema211.FieldType<Date, string>;
+        isOptional: true;
+      };
+    }>;
+    isArray: true;
+    isOptional: false;
+  };
+  dueCardCount: {
+    type: _lssm_lib_schema211.FieldType<number, number>;
+    isOptional: false;
+  };
+}>, undefined>;
+//#endregion
+export { CompleteLessonContract, EnrollInCourseContract, GetDueCardsContract, GetLearnerDashboardContract, SubmitCardReviewContract };

package/dist/contracts/shared.d.ts

@@ -0,0 +1,4 @@
+//#region src/contracts/shared.d.ts
+declare const LEARNING_JOURNEY_OWNERS: readonly ["modules.learning-journey"];
+//#endregion
+export { LEARNING_JOURNEY_OWNERS };

package/dist/docs/index.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/docs/learning-journey.docblock.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/engines/index.d.ts

@@ -0,0 +1,4 @@
+import { CardRating, DEFAULT_SRS_CONFIG, ReviewResult, SRSConfig, SRSEngine, SRSState, srsEngine } from "./srs.js";
+import { DEFAULT_XP_CONFIG, XPActivityType, XPBreakdown, XPCalculationInput, XPConfig, XPEngine, XPResult, xpEngine } from "./xp.js";
+import { DEFAULT_STREAK_CONFIG, StreakConfig, StreakEngine, StreakState, StreakUpdateResult, streakEngine } from "./streak.js";
+export { CardRating, DEFAULT_SRS_CONFIG, DEFAULT_STREAK_CONFIG, DEFAULT_XP_CONFIG, ReviewResult, SRSConfig, SRSEngine, SRSState, StreakConfig, StreakEngine, StreakState, StreakUpdateResult, XPActivityType, XPBreakdown, XPCalculationInput, XPConfig, XPEngine, XPResult, srsEngine, streakEngine, xpEngine };

package/dist/engines/srs.d.ts

@@ -0,0 +1,110 @@
+//#region src/engines/srs.d.ts
+/**
+ * Spaced Repetition System (SRS) Engine
+ *
+ * Implements the SM-2 algorithm variant for optimal flashcard scheduling.
+ *
+ * The algorithm calculates the optimal time to review a card based on:
+ * - User's rating of recall difficulty (again, hard, good, easy)
+ * - Current interval between reviews
+ * - Ease factor (how easy the card is for this user)
+ * - Number of successful repetitions
+ */
+type CardRating = 'AGAIN' | 'HARD' | 'GOOD' | 'EASY';
+interface SRSState {
+  /** Current interval in days */
+  interval: number;
+  /** Ease factor (typically 1.3 to 2.5+) */
+  easeFactor: number;
+  /** Number of successful repetitions */
+  repetitions: number;
+  /** Current learning step (for new cards) */
+  learningStep: number;
+  /** Whether card has graduated to review phase */
+  isGraduated: boolean;
+  /** Whether card is being relearned after a lapse */
+  isRelearning: boolean;
+  /** Number of times card was forgotten */
+  lapses: number;
+}
+interface ReviewResult {
+  /** New interval in days */
+  interval: number;
+  /** New ease factor */
+  easeFactor: number;
+  /** New repetition count */
+  repetitions: number;
+  /** Next review date */
+  nextReviewAt: Date;
+  /** New learning step */
+  learningStep: number;
+  /** Whether card has graduated */
+  isGraduated: boolean;
+  /** Whether card is being relearned */
+  isRelearning: boolean;
+  /** Updated lapse count */
+  lapses: number;
+}
+interface SRSConfig {
+  /** Learning steps in minutes [1, 10] = 1 min, 10 min */
+  learningSteps: number[];
+  /** Graduating interval in days */
+  graduatingInterval: number;
+  /** Easy interval (for easy button on new cards) */
+  easyInterval: number;
+  /** Relearning steps in minutes */
+  relearningSteps: number[];
+  /** Minimum ease factor */
+  minEaseFactor: number;
+  /** Maximum interval in days */
+  maxInterval: number;
+  /** Interval modifier (1.0 = 100%) */
+  intervalModifier: number;
+  /** New cards interval modifier */
+  newIntervalModifier: number;
+  /** Hard interval modifier */
+  hardIntervalModifier: number;
+  /** Easy bonus modifier */
+  easyBonus: number;
+}
+declare const DEFAULT_SRS_CONFIG: SRSConfig;
+declare class SRSEngine {
+  private config;
+  constructor(config?: Partial<SRSConfig>);
+  /**
+   * Calculate the next review state based on rating.
+   */
+  calculateNextReview(state: SRSState, rating: CardRating, now?: Date): ReviewResult;
+  /**
+   * Handle learning phase (new cards).
+   */
+  private handleLearningCard;
+  /**
+   * Handle relearning phase (lapsed cards).
+   */
+  private handleRelearningCard;
+  /**
+   * Handle review phase (graduated cards).
+   */
+  private handleReviewCard;
+  /**
+   * Get initial SRS state for a new card.
+   */
+  getInitialState(): SRSState;
+  /**
+   * Check if a card is due for review.
+   */
+  isDue(nextReviewAt: Date, now?: Date): boolean;
+  /**
+   * Calculate overdue days (negative if not yet due).
+   */
+  getOverdueDays(nextReviewAt: Date, now?: Date): number;
+  private addMinutes;
+  private addDays;
+}
+/**
+ * Default SRS engine instance.
+ */
+declare const srsEngine: SRSEngine;
+//#endregion
+export { CardRating, DEFAULT_SRS_CONFIG, ReviewResult, SRSConfig, SRSEngine, SRSState, srsEngine };

package/dist/engines/streak.d.ts

@@ -0,0 +1,99 @@
+//#region src/engines/streak.d.ts
+/**
+ * Streak Tracking Engine
+ *
+ * Manages daily learning streaks with timezone support and freeze protection.
+ */
+interface StreakState {
+  /** Current streak days */
+  currentStreak: number;
+  /** Longest streak ever */
+  longestStreak: number;
+  /** Last activity timestamp */
+  lastActivityAt: Date | null;
+  /** Last activity date (YYYY-MM-DD) */
+  lastActivityDate: string | null;
+  /** Available streak freezes */
+  freezesRemaining: number;
+  /** When a freeze was last used */
+  freezeUsedAt: Date | null;
+}
+interface StreakUpdateResult {
+  /** Updated streak state */
+  state: StreakState;
+  /** Whether streak was maintained */
+  streakMaintained: boolean;
+  /** Whether streak was lost */
+  streakLost: boolean;
+  /** Whether a freeze was used */
+  freezeUsed: boolean;
+  /** Whether this activity started a new streak */
+  newStreak: boolean;
+  /** Days missed (if streak was lost) */
+  daysMissed: number;
+}
+interface StreakConfig {
+  /** Timezone for the user */
+  timezone: string;
+  /** How many streak freezes to give per month */
+  freezesPerMonth: number;
+  /** Maximum freezes that can be accumulated */
+  maxFreezes: number;
+  /** Grace period in hours after midnight */
+  gracePeriodHours: number;
+}
+declare const DEFAULT_STREAK_CONFIG: StreakConfig;
+declare class StreakEngine {
+  private config;
+  constructor(config?: Partial<StreakConfig>);
+  /**
+   * Update streak based on new activity.
+   */
+  update(state: StreakState, now?: Date): StreakUpdateResult;
+  /**
+   * Check streak status without recording activity.
+   */
+  checkStatus(state: StreakState, now?: Date): {
+    isActive: boolean;
+    willExpireAt: Date | null;
+    canUseFreeze: boolean;
+    daysUntilExpiry: number;
+  };
+  /**
+   * Manually use a freeze to protect streak.
+   */
+  useFreeze(state: StreakState, now?: Date): StreakState | null;
+  /**
+   * Award monthly freezes.
+   */
+  awardMonthlyFreezes(state: StreakState): StreakState;
+  /**
+   * Get initial streak state.
+   */
+  getInitialState(): StreakState;
+  /**
+   * Calculate streak milestones.
+   */
+  getMilestones(currentStreak: number): {
+    achieved: number[];
+    next: number | null;
+  };
+  /**
+   * Get date string in YYYY-MM-DD format.
+   */
+  private getDateString;
+  /**
+   * Get number of days between two date strings.
+   */
+  private getDaysBetween;
+  /**
+   * Add days to a date.
+   */
+  private addDays;
+}
+/**
+ * Default streak engine instance.
+ */
+declare const streakEngine: StreakEngine;
+//#endregion
+export { DEFAULT_STREAK_CONFIG, StreakConfig, StreakEngine, StreakState, StreakUpdateResult, streakEngine };

package/dist/engines/xp.d.ts

@@ -0,0 +1,96 @@
+//#region src/engines/xp.d.ts
+/**
+ * XP (Experience Points) Engine
+ *
+ * Calculates XP rewards for various learning activities.
+ */
+type XPActivityType = 'lesson_complete' | 'quiz_pass' | 'quiz_perfect' | 'flashcard_review' | 'course_complete' | 'module_complete' | 'streak_bonus' | 'achievement_unlock' | 'daily_goal_complete' | 'first_lesson' | 'onboarding_step' | 'onboarding_complete';
+interface XPCalculationInput {
+  /** Type of activity */
+  activity: XPActivityType;
+  /** Base XP for the activity (from content config) */
+  baseXp?: number;
+  /** Score achieved (0-100) for scored activities */
+  score?: number;
+  /** Current streak (for streak bonuses) */
+  currentStreak?: number;
+  /** Time spent in seconds */
+  timeSpent?: number;
+  /** Attempt number (for quizzes) */
+  attemptNumber?: number;
+  /** Whether this is a retry */
+  isRetry?: boolean;
+}
+interface XPResult {
+  /** Total XP earned */
+  totalXp: number;
+  /** Base XP before bonuses */
+  baseXp: number;
+  /** Breakdown of XP sources */
+  breakdown: XPBreakdown[];
+}
+interface XPBreakdown {
+  /** Source of XP */
+  source: string;
+  /** XP amount */
+  amount: number;
+  /** Multiplier applied */
+  multiplier?: number;
+}
+interface XPConfig {
+  /** Base XP values for each activity */
+  baseValues: Record<XPActivityType, number>;
+  /** Score thresholds for bonus XP */
+  scoreThresholds: {
+    min: number;
+    multiplier: number;
+  }[];
+  /** Streak bonus tiers */
+  streakTiers: {
+    days: number;
+    bonus: number;
+  }[];
+  /** Perfect score bonus multiplier */
+  perfectScoreMultiplier: number;
+  /** First attempt bonus */
+  firstAttemptBonus: number;
+  /** Retry penalty multiplier */
+  retryPenalty: number;
+  /** Speed bonus (complete under expected time) */
+  speedBonusMultiplier: number;
+  /** Speed bonus threshold (percentage of expected time) */
+  speedBonusThreshold: number;
+}
+declare const DEFAULT_XP_CONFIG: XPConfig;
+declare class XPEngine {
+  private config;
+  constructor(config?: Partial<XPConfig>);
+  /**
+   * Calculate XP for an activity.
+   */
+  calculate(input: XPCalculationInput): XPResult;
+  /**
+   * Calculate streak bonus XP.
+   */
+  calculateStreakBonus(currentStreak: number): XPResult;
+  /**
+   * Calculate XP needed for a level.
+   */
+  getXpForLevel(level: number): number;
+  /**
+   * Get level from total XP.
+   */
+  getLevelFromXp(totalXp: number): {
+    level: number;
+    xpInLevel: number;
+    xpForNextLevel: number;
+  };
+  private getScoreMultiplier;
+  private getStreakBonus;
+}
+/**
+ * Default XP engine instance.
+ */
+declare const xpEngine: XPEngine;
+//#endregion
+export { DEFAULT_XP_CONFIG, XPActivityType, XPBreakdown, XPCalculationInput, XPConfig, XPEngine, XPResult, xpEngine };