@contractspec/module.learning-journey 1.57.0 → 1.58.0

package/dist/node/engines/index.js

@@ -0,0 +1,526 @@
+// src/engines/srs.ts
+var DEFAULT_SRS_CONFIG = {
+  learningSteps: [1, 10],
+  graduatingInterval: 1,
+  easyInterval: 4,
+  relearningSteps: [10],
+  minEaseFactor: 1.3,
+  maxInterval: 365,
+  intervalModifier: 1,
+  newIntervalModifier: 0.5,
+  hardIntervalModifier: 1.2,
+  easyBonus: 1.3
+};
+
+class SRSEngine {
+  config;
+  constructor(config = {}) {
+    this.config = { ...DEFAULT_SRS_CONFIG, ...config };
+  }
+  calculateNextReview(state, rating, now = new Date) {
+    if (!state.isGraduated && !state.isRelearning) {
+      return this.handleLearningCard(state, rating, now);
+    }
+    if (state.isRelearning) {
+      return this.handleRelearningCard(state, rating, now);
+    }
+    return this.handleReviewCard(state, rating, now);
+  }
+  getInitialState() {
+    return {
+      interval: 0,
+      easeFactor: 2.5,
+      repetitions: 0,
+      learningStep: 0,
+      isGraduated: false,
+      isRelearning: false,
+      lapses: 0
+    };
+  }
+  isDue(nextReviewAt, now = new Date) {
+    return nextReviewAt <= now;
+  }
+  getOverdueDays(nextReviewAt, now = new Date) {
+    const diff = now.getTime() - nextReviewAt.getTime();
+    return Math.floor(diff / (1000 * 60 * 60 * 24));
+  }
+  handleLearningCard(state, rating, now) {
+    const steps = this.config.learningSteps;
+    let newStep = state.learningStep;
+    let isGraduated = false;
+    let interval = 0;
+    let nextReviewAt;
+    switch (rating) {
+      case "AGAIN":
+        newStep = 0;
+        interval = steps[0] ?? 1;
+        nextReviewAt = this.addMinutes(now, interval);
+        break;
+      case "HARD":
+        interval = steps[newStep] ?? steps[0] ?? 1;
+        nextReviewAt = this.addMinutes(now, interval);
+        break;
+      case "GOOD":
+        newStep++;
+        if (newStep >= steps.length) {
+          isGraduated = true;
+          interval = this.config.graduatingInterval;
+          nextReviewAt = this.addDays(now, interval);
+        } else {
+          interval = steps[newStep] ?? 10;
+          nextReviewAt = this.addMinutes(now, interval);
+        }
+        break;
+      case "EASY":
+        isGraduated = true;
+        interval = this.config.easyInterval;
+        nextReviewAt = this.addDays(now, interval);
+        break;
+    }
+    return {
+      interval: isGraduated ? interval : 0,
+      easeFactor: state.easeFactor,
+      repetitions: isGraduated ? 1 : 0,
+      nextReviewAt,
+      learningStep: newStep,
+      isGraduated,
+      isRelearning: false,
+      lapses: state.lapses
+    };
+  }
+  handleRelearningCard(state, rating, now) {
+    const steps = this.config.relearningSteps;
+    let newStep = state.learningStep;
+    let isRelearning = true;
+    let interval = 0;
+    let nextReviewAt;
+    switch (rating) {
+      case "AGAIN":
+        newStep = 0;
+        interval = steps[0] ?? 10;
+        nextReviewAt = this.addMinutes(now, interval);
+        break;
+      case "HARD":
+        interval = steps[newStep] ?? steps[0] ?? 10;
+        nextReviewAt = this.addMinutes(now, interval);
+        break;
+      case "GOOD":
+        newStep++;
+        if (newStep >= steps.length) {
+          isRelearning = false;
+          interval = Math.max(1, Math.floor(state.interval * this.config.newIntervalModifier));
+          nextReviewAt = this.addDays(now, interval);
+        } else {
+          interval = steps[newStep] ?? 10;
+          nextReviewAt = this.addMinutes(now, interval);
+        }
+        break;
+      case "EASY":
+        isRelearning = false;
+        interval = Math.max(1, Math.floor(state.interval * this.config.newIntervalModifier * 1.5));
+        nextReviewAt = this.addDays(now, interval);
+        break;
+    }
+    return {
+      interval: isRelearning ? state.interval : interval,
+      easeFactor: state.easeFactor,
+      repetitions: isRelearning ? state.repetitions : state.repetitions + 1,
+      nextReviewAt,
+      learningStep: newStep,
+      isGraduated: true,
+      isRelearning,
+      lapses: state.lapses
+    };
+  }
+  handleReviewCard(state, rating, now) {
+    let newInterval;
+    let newEaseFactor = state.easeFactor;
+    let repetitions = state.repetitions;
+    let isRelearning = false;
+    let learningStep = 0;
+    let lapses = state.lapses;
+    switch (rating) {
+      case "AGAIN":
+        lapses++;
+        isRelearning = true;
+        learningStep = 0;
+        newEaseFactor = Math.max(this.config.minEaseFactor, newEaseFactor - 0.2);
+        newInterval = state.interval;
+        return {
+          interval: newInterval,
+          easeFactor: newEaseFactor,
+          repetitions,
+          nextReviewAt: this.addMinutes(now, this.config.relearningSteps[0] ?? 10),
+          learningStep,
+          isGraduated: true,
+          isRelearning: true,
+          lapses
+        };
+      case "HARD":
+        newEaseFactor = Math.max(this.config.minEaseFactor, newEaseFactor - 0.15);
+        newInterval = Math.max(state.interval + 1, state.interval * this.config.hardIntervalModifier);
+        break;
+      case "GOOD":
+        newInterval = state.interval * newEaseFactor * this.config.intervalModifier;
+        repetitions++;
+        break;
+      case "EASY":
+        newEaseFactor = newEaseFactor + 0.15;
+        newInterval = state.interval * newEaseFactor * this.config.easyBonus * this.config.intervalModifier;
+        repetitions++;
+        break;
+    }
+    newInterval = Math.min(Math.round(newInterval), this.config.maxInterval);
+    newInterval = Math.max(1, newInterval);
+    return {
+      interval: newInterval,
+      easeFactor: newEaseFactor,
+      repetitions,
+      nextReviewAt: this.addDays(now, newInterval),
+      learningStep,
+      isGraduated: true,
+      isRelearning,
+      lapses
+    };
+  }
+  addMinutes(date, minutes) {
+    return new Date(date.getTime() + minutes * 60 * 1000);
+  }
+  addDays(date, days) {
+    return new Date(date.getTime() + days * 24 * 60 * 60 * 1000);
+  }
+}
+var srsEngine = new SRSEngine;
+
+// src/engines/xp.ts
+var DEFAULT_XP_CONFIG = {
+  baseValues: {
+    lesson_complete: 10,
+    quiz_pass: 20,
+    quiz_perfect: 50,
+    flashcard_review: 1,
+    course_complete: 200,
+    module_complete: 50,
+    streak_bonus: 5,
+    achievement_unlock: 0,
+    daily_goal_complete: 15,
+    first_lesson: 25,
+    onboarding_step: 5,
+    onboarding_complete: 50
+  },
+  scoreThresholds: [
+    { min: 90, multiplier: 1.5 },
+    { min: 80, multiplier: 1.25 },
+    { min: 70, multiplier: 1 },
+    { min: 60, multiplier: 0.75 },
+    { min: 0, multiplier: 0.5 }
+  ],
+  streakTiers: [
+    { days: 365, bonus: 50 },
+    { days: 180, bonus: 30 },
+    { days: 90, bonus: 20 },
+    { days: 30, bonus: 15 },
+    { days: 14, bonus: 10 },
+    { days: 7, bonus: 5 },
+    { days: 3, bonus: 2 },
+    { days: 1, bonus: 0 }
+  ],
+  perfectScoreMultiplier: 1.5,
+  firstAttemptBonus: 10,
+  retryPenalty: 0.5,
+  speedBonusMultiplier: 1.2,
+  speedBonusThreshold: 0.8
+};
+
+class XPEngine {
+  config;
+  constructor(config = {}) {
+    this.config = {
+      ...DEFAULT_XP_CONFIG,
+      ...config,
+      baseValues: { ...DEFAULT_XP_CONFIG.baseValues, ...config.baseValues },
+      scoreThresholds: config.scoreThresholds || DEFAULT_XP_CONFIG.scoreThresholds,
+      streakTiers: config.streakTiers || DEFAULT_XP_CONFIG.streakTiers
+    };
+  }
+  calculate(input) {
+    const breakdown = [];
+    const baseXp = input.baseXp ?? this.config.baseValues[input.activity];
+    let totalXp = baseXp;
+    breakdown.push({
+      source: "base",
+      amount: baseXp
+    });
+    if (input.score !== undefined) {
+      const scoreMultiplier = this.getScoreMultiplier(input.score);
+      if (scoreMultiplier !== 1) {
+        const scoreBonus = Math.round(baseXp * (scoreMultiplier - 1));
+        totalXp += scoreBonus;
+        breakdown.push({
+          source: "score_bonus",
+          amount: scoreBonus,
+          multiplier: scoreMultiplier
+        });
+      }
+      if (input.score === 100) {
+        const perfectBonus = Math.round(baseXp * (this.config.perfectScoreMultiplier - 1));
+        totalXp += perfectBonus;
+        breakdown.push({
+          source: "perfect_score",
+          amount: perfectBonus,
+          multiplier: this.config.perfectScoreMultiplier
+        });
+      }
+    }
+    if (input.attemptNumber === 1 && !input.isRetry) {
+      totalXp += this.config.firstAttemptBonus;
+      breakdown.push({
+        source: "first_attempt",
+        amount: this.config.firstAttemptBonus
+      });
+    }
+    if (input.isRetry) {
+      const penalty = Math.round(totalXp * (1 - this.config.retryPenalty));
+      totalXp -= penalty;
+      breakdown.push({
+        source: "retry_penalty",
+        amount: -penalty,
+        multiplier: this.config.retryPenalty
+      });
+    }
+    if (input.currentStreak && input.currentStreak > 0) {
+      const streakBonus = this.getStreakBonus(input.currentStreak);
+      if (streakBonus > 0) {
+        totalXp += streakBonus;
+        breakdown.push({
+          source: "streak_bonus",
+          amount: streakBonus
+        });
+      }
+    }
+    if (baseXp > 0) {
+      totalXp = Math.max(1, totalXp);
+    }
+    return {
+      totalXp: Math.round(totalXp),
+      baseXp,
+      breakdown
+    };
+  }
+  calculateStreakBonus(currentStreak) {
+    const bonus = this.getStreakBonus(currentStreak);
+    return {
+      totalXp: bonus,
+      baseXp: bonus,
+      breakdown: [
+        {
+          source: "streak_bonus",
+          amount: bonus
+        }
+      ]
+    };
+  }
+  getXpForLevel(level) {
+    if (level <= 1)
+      return 0;
+    return Math.round(100 * Math.pow(level - 1, 1.5));
+  }
+  getLevelFromXp(totalXp) {
+    let level = 1;
+    let xpRequired = this.getXpForLevel(level + 1);
+    while (totalXp >= xpRequired && level < 1000) {
+      level++;
+      xpRequired = this.getXpForLevel(level + 1);
+    }
+    const xpForCurrentLevel = this.getXpForLevel(level);
+    const xpForNextLevel = this.getXpForLevel(level + 1);
+    return {
+      level,
+      xpInLevel: totalXp - xpForCurrentLevel,
+      xpForNextLevel: xpForNextLevel - xpForCurrentLevel
+    };
+  }
+  getScoreMultiplier(score) {
+    for (const threshold of this.config.scoreThresholds) {
+      if (score >= threshold.min) {
+        return threshold.multiplier;
+      }
+    }
+    return 1;
+  }
+  getStreakBonus(streak) {
+    for (const tier of this.config.streakTiers) {
+      if (streak >= tier.days) {
+        return tier.bonus;
+      }
+    }
+    return 0;
+  }
+}
+var xpEngine = new XPEngine;
+
+// src/engines/streak.ts
+var DEFAULT_STREAK_CONFIG = {
+  timezone: "UTC",
+  freezesPerMonth: 2,
+  maxFreezes: 5,
+  gracePeriodHours: 4
+};
+
+class StreakEngine {
+  config;
+  constructor(config = {}) {
+    this.config = { ...DEFAULT_STREAK_CONFIG, ...config };
+  }
+  update(state, now = new Date) {
+    const todayDate = this.getDateString(now);
+    const result = {
+      state: { ...state },
+      streakMaintained: false,
+      streakLost: false,
+      freezeUsed: false,
+      newStreak: false,
+      daysMissed: 0
+    };
+    if (!state.lastActivityDate) {
+      result.state.currentStreak = 1;
+      result.state.longestStreak = Math.max(1, state.longestStreak);
+      result.state.lastActivityAt = now;
+      result.state.lastActivityDate = todayDate;
+      result.newStreak = true;
+      result.streakMaintained = true;
+      return result;
+    }
+    if (state.lastActivityDate === todayDate) {
+      result.state.lastActivityAt = now;
+      result.streakMaintained = true;
+      return result;
+    }
+    const daysSinceActivity = this.getDaysBetween(state.lastActivityDate, todayDate);
+    if (daysSinceActivity === 1) {
+      result.state.currentStreak = state.currentStreak + 1;
+      result.state.longestStreak = Math.max(result.state.currentStreak, state.longestStreak);
+      result.state.lastActivityAt = now;
+      result.state.lastActivityDate = todayDate;
+      result.streakMaintained = true;
+      return result;
+    }
+    result.daysMissed = daysSinceActivity - 1;
+    const freezesNeeded = result.daysMissed;
+    if (freezesNeeded <= state.freezesRemaining) {
+      result.state.freezesRemaining = state.freezesRemaining - freezesNeeded;
+      result.state.freezeUsedAt = now;
+      result.state.currentStreak = state.currentStreak + 1;
+      result.state.longestStreak = Math.max(result.state.currentStreak, state.longestStreak);
+      result.state.lastActivityAt = now;
+      result.state.lastActivityDate = todayDate;
+      result.freezeUsed = true;
+      result.streakMaintained = true;
+      return result;
+    }
+    result.streakLost = true;
+    result.state.currentStreak = 1;
+    result.state.lastActivityAt = now;
+    result.state.lastActivityDate = todayDate;
+    result.newStreak = true;
+    return result;
+  }
+  checkStatus(state, now = new Date) {
+    if (!state.lastActivityDate) {
+      return {
+        isActive: false,
+        willExpireAt: null,
+        canUseFreeze: false,
+        daysUntilExpiry: 0
+      };
+    }
+    const todayDate = this.getDateString(now);
+    const daysSinceActivity = this.getDaysBetween(state.lastActivityDate, todayDate);
+    if (daysSinceActivity === 0) {
+      const tomorrow = this.addDays(now, 1);
+      tomorrow.setHours(23, 59, 59, 999);
+      return {
+        isActive: true,
+        willExpireAt: tomorrow,
+        canUseFreeze: state.freezesRemaining > 0,
+        daysUntilExpiry: 1
+      };
+    }
+    if (daysSinceActivity === 1) {
+      const endOfDay = new Date(now);
+      endOfDay.setHours(23 + this.config.gracePeriodHours, 59, 59, 999);
+      return {
+        isActive: true,
+        willExpireAt: endOfDay,
+        canUseFreeze: state.freezesRemaining > 0,
+        daysUntilExpiry: 0
+      };
+    }
+    const missedDays = daysSinceActivity - 1;
+    return {
+      isActive: missedDays <= state.freezesRemaining,
+      willExpireAt: null,
+      canUseFreeze: missedDays <= state.freezesRemaining,
+      daysUntilExpiry: -missedDays
+    };
+  }
+  useFreeze(state, now = new Date) {
+    if (state.freezesRemaining <= 0) {
+      return null;
+    }
+    return {
+      ...state,
+      freezesRemaining: state.freezesRemaining - 1,
+      freezeUsedAt: now
+    };
+  }
+  awardMonthlyFreezes(state) {
+    return {
+      ...state,
+      freezesRemaining: Math.min(state.freezesRemaining + this.config.freezesPerMonth, this.config.maxFreezes)
+    };
+  }
+  getInitialState() {
+    return {
+      currentStreak: 0,
+      longestStreak: 0,
+      lastActivityAt: null,
+      lastActivityDate: null,
+      freezesRemaining: this.config.freezesPerMonth,
+      freezeUsedAt: null
+    };
+  }
+  getMilestones(currentStreak) {
+    const milestones = [3, 7, 14, 30, 60, 90, 180, 365, 500, 1000];
+    const achieved = milestones.filter((m) => currentStreak >= m);
+    const next = milestones.find((m) => currentStreak < m) ?? null;
+    return { achieved, next };
+  }
+  getDateString(date) {
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, "0");
+    const day = String(date.getDate()).padStart(2, "0");
+    return `${year}-${month}-${day}`;
+  }
+  getDaysBetween(dateStr1, dateStr2) {
+    const date1 = new Date(dateStr1);
+    const date2 = new Date(dateStr2);
+    const diffTime = date2.getTime() - date1.getTime();
+    return Math.floor(diffTime / (1000 * 60 * 60 * 24));
+  }
+  addDays(date, days) {
+    return new Date(date.getTime() + days * 24 * 60 * 60 * 1000);
+  }
+}
+var streakEngine = new StreakEngine;
+export {
+  xpEngine,
+  streakEngine,
+  srsEngine,
+  XPEngine,
+  StreakEngine,
+  SRSEngine,
+  DEFAULT_XP_CONFIG,
+  DEFAULT_STREAK_CONFIG,
+  DEFAULT_SRS_CONFIG
+};

package/dist/node/engines/srs.js

@@ -0,0 +1,198 @@
+// src/engines/srs.ts
+var DEFAULT_SRS_CONFIG = {
+  learningSteps: [1, 10],
+  graduatingInterval: 1,
+  easyInterval: 4,
+  relearningSteps: [10],
+  minEaseFactor: 1.3,
+  maxInterval: 365,
+  intervalModifier: 1,
+  newIntervalModifier: 0.5,
+  hardIntervalModifier: 1.2,
+  easyBonus: 1.3
+};
+
+class SRSEngine {
+  config;
+  constructor(config = {}) {
+    this.config = { ...DEFAULT_SRS_CONFIG, ...config };
+  }
+  calculateNextReview(state, rating, now = new Date) {
+    if (!state.isGraduated && !state.isRelearning) {
+      return this.handleLearningCard(state, rating, now);
+    }
+    if (state.isRelearning) {
+      return this.handleRelearningCard(state, rating, now);
+    }
+    return this.handleReviewCard(state, rating, now);
+  }
+  getInitialState() {
+    return {
+      interval: 0,
+      easeFactor: 2.5,
+      repetitions: 0,
+      learningStep: 0,
+      isGraduated: false,
+      isRelearning: false,
+      lapses: 0
+    };
+  }
+  isDue(nextReviewAt, now = new Date) {
+    return nextReviewAt <= now;
+  }
+  getOverdueDays(nextReviewAt, now = new Date) {
+    const diff = now.getTime() - nextReviewAt.getTime();
+    return Math.floor(diff / (1000 * 60 * 60 * 24));
+  }
+  handleLearningCard(state, rating, now) {
+    const steps = this.config.learningSteps;
+    let newStep = state.learningStep;
+    let isGraduated = false;
+    let interval = 0;
+    let nextReviewAt;
+    switch (rating) {
+      case "AGAIN":
+        newStep = 0;
+        interval = steps[0] ?? 1;
+        nextReviewAt = this.addMinutes(now, interval);
+        break;
+      case "HARD":
+        interval = steps[newStep] ?? steps[0] ?? 1;
+        nextReviewAt = this.addMinutes(now, interval);
+        break;
+      case "GOOD":
+        newStep++;
+        if (newStep >= steps.length) {
+          isGraduated = true;
+          interval = this.config.graduatingInterval;
+          nextReviewAt = this.addDays(now, interval);
+        } else {
+          interval = steps[newStep] ?? 10;
+          nextReviewAt = this.addMinutes(now, interval);
+        }
+        break;
+      case "EASY":
+        isGraduated = true;
+        interval = this.config.easyInterval;
+        nextReviewAt = this.addDays(now, interval);
+        break;
+    }
+    return {
+      interval: isGraduated ? interval : 0,
+      easeFactor: state.easeFactor,
+      repetitions: isGraduated ? 1 : 0,
+      nextReviewAt,
+      learningStep: newStep,
+      isGraduated,
+      isRelearning: false,
+      lapses: state.lapses
+    };
+  }
+  handleRelearningCard(state, rating, now) {
+    const steps = this.config.relearningSteps;
+    let newStep = state.learningStep;
+    let isRelearning = true;
+    let interval = 0;
+    let nextReviewAt;
+    switch (rating) {
+      case "AGAIN":
+        newStep = 0;
+        interval = steps[0] ?? 10;
+        nextReviewAt = this.addMinutes(now, interval);
+        break;
+      case "HARD":
+        interval = steps[newStep] ?? steps[0] ?? 10;
+        nextReviewAt = this.addMinutes(now, interval);
+        break;
+      case "GOOD":
+        newStep++;
+        if (newStep >= steps.length) {
+          isRelearning = false;
+          interval = Math.max(1, Math.floor(state.interval * this.config.newIntervalModifier));
+          nextReviewAt = this.addDays(now, interval);
+        } else {
+          interval = steps[newStep] ?? 10;
+          nextReviewAt = this.addMinutes(now, interval);
+        }
+        break;
+      case "EASY":
+        isRelearning = false;
+        interval = Math.max(1, Math.floor(state.interval * this.config.newIntervalModifier * 1.5));
+        nextReviewAt = this.addDays(now, interval);
+        break;
+    }
+    return {
+      interval: isRelearning ? state.interval : interval,
+      easeFactor: state.easeFactor,
+      repetitions: isRelearning ? state.repetitions : state.repetitions + 1,
+      nextReviewAt,
+      learningStep: newStep,
+      isGraduated: true,
+      isRelearning,
+      lapses: state.lapses
+    };
+  }
+  handleReviewCard(state, rating, now) {
+    let newInterval;
+    let newEaseFactor = state.easeFactor;
+    let repetitions = state.repetitions;
+    let isRelearning = false;
+    let learningStep = 0;
+    let lapses = state.lapses;
+    switch (rating) {
+      case "AGAIN":
+        lapses++;
+        isRelearning = true;
+        learningStep = 0;
+        newEaseFactor = Math.max(this.config.minEaseFactor, newEaseFactor - 0.2);
+        newInterval = state.interval;
+        return {
+          interval: newInterval,
+          easeFactor: newEaseFactor,
+          repetitions,
+          nextReviewAt: this.addMinutes(now, this.config.relearningSteps[0] ?? 10),
+          learningStep,
+          isGraduated: true,
+          isRelearning: true,
+          lapses
+        };
+      case "HARD":
+        newEaseFactor = Math.max(this.config.minEaseFactor, newEaseFactor - 0.15);
+        newInterval = Math.max(state.interval + 1, state.interval * this.config.hardIntervalModifier);
+        break;
+      case "GOOD":
+        newInterval = state.interval * newEaseFactor * this.config.intervalModifier;
+        repetitions++;
+        break;
+      case "EASY":
+        newEaseFactor = newEaseFactor + 0.15;
+        newInterval = state.interval * newEaseFactor * this.config.easyBonus * this.config.intervalModifier;
+        repetitions++;
+        break;
+    }
+    newInterval = Math.min(Math.round(newInterval), this.config.maxInterval);
+    newInterval = Math.max(1, newInterval);
+    return {
+      interval: newInterval,
+      easeFactor: newEaseFactor,
+      repetitions,
+      nextReviewAt: this.addDays(now, newInterval),
+      learningStep,
+      isGraduated: true,
+      isRelearning,
+      lapses
+    };
+  }
+  addMinutes(date, minutes) {
+    return new Date(date.getTime() + minutes * 60 * 1000);
+  }
+  addDays(date, days) {
+    return new Date(date.getTime() + days * 24 * 60 * 60 * 1000);
+  }
+}
+var srsEngine = new SRSEngine;
+export {
+  srsEngine,
+  SRSEngine,
+  DEFAULT_SRS_CONFIG
+};