musora-content-services 2.95.0 → 2.95.1

package/.claude/settings.local.json

@@ -0,0 +1,18 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(find:*)",
+      "Bash(docker exec:*)",
+      "Bash(npm test:*)",
+      "WebSearch",
+      "WebFetch(domain:watermelondb.dev)",
+      "WebFetch(domain:github.com)",
+      "Bash(git checkout:*)",
+      "Bash(npm run doc:*)",
+      "Bash(cat:*)",
+      "Bash(tr:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [2.95.1](https://github.com/railroadmedia/musora-content-services/compare/v2.95.0...v2.95.1) (2025-12-08)
+
 ## [2.95.0](https://github.com/railroadmedia/musora-content-services/compare/v2.94.8...v2.95.0) (2025-12-08)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "musora-content-services",
-  "version": "2.95.0",
+  "version": "2.95.1",
   "description": "A package for Musoras content services ",
   "main": "src/index.js",
   "type": "module",

package/src/services/awards/award-callbacks.js

@@ -12,27 +12,50 @@ let progressUpdateCallback = null
  * @param {AwardCallbackFunction} callback - Function called with award data when an award is earned
  * @returns {UnregisterFunction} Cleanup function to unregister this callback
  *
- * @example // Display award notification
- * const cleanup = registerAwardCallback((award) => {
- *   showNotification({
- *     title: award.name,
- *     message: award.completion_data.message,
- *     image: award.badge
- *   })
- * })
+ * @description
+ * Registers a callback to be notified when the user earns a new award. Only one
+ * callback can be registered at a time - registering a new one replaces the previous.
+ * Always call the returned cleanup function when your component unmounts.
+ *
+ * The callback receives an award object with:
+ * - `awardId` - Unique Sanity award ID
+ * - `name` - Display name of the award
+ * - `badge` - URL to badge image
+ * - `completed_at` - ISO timestamp
+ * - `completion_data.message` - Pre-generated congratulations message
+ * - `completion_data.practice_minutes` - Total practice time
+ * - `completion_data.days_user_practiced` - Days spent practicing
+ * - `completion_data.content_title` - Title of completed content
+ *
+ * @example // React Native - Show award celebration modal
+ * function useAwardNotification() {
+ *   const [award, setAward] = useState(null)
  *
- * // Later, when component unmounts:
- * cleanup()
+ *   useEffect(() => {
+ *     return registerAwardCallback((awardData) => {
+ *       setAward({
+ *         title: awardData.name,
+ *         badge: awardData.badge,
+ *         message: awardData.completion_data.message,
+ *         practiceMinutes: awardData.completion_data.practice_minutes
+ *       })
+ *     })
+ *   }, [])
  *
- * @example // Track award analytics
- * registerAwardCallback((award) => {
- *   analytics.track('Award Earned', {
- *     awardId: award.awardId,
- *     awardName: award.name,
- *     practiceMinutes: award.completion_data.practice_minutes,
- *     completedAt: award.completed_at
+ *   return { award, dismissAward: () => setAward(null) }
+ * }
+ *
+ * @example // Track award in analytics
+ * useEffect(() => {
+ *   return registerAwardCallback((award) => {
+ *     analytics.track('Award Earned', {
+ *       awardId: award.awardId,
+ *       awardName: award.name,
+ *       practiceMinutes: award.completion_data.practice_minutes,
+ *       contentTitle: award.completion_data.content_title
+ *     })
  *   })
- * })
+ * }, [])
  */
 export function registerAwardCallback(callback) {
   if (typeof callback !== 'function') {
@@ -77,25 +100,41 @@ function unregisterAwardCallback() {
  * @param {ProgressCallbackFunction} callback - Function called with progress data when award progress changes
  * @returns {UnregisterFunction} Cleanup function to unregister this callback
  *
- * @example // Update progress bar
- * const cleanup = registerProgressCallback(({ awardId, progressPercentage }) => {
- *   const progressBar = document.getElementById(`award-${awardId}`)
- *   if (progressBar) {
- *     progressBar.style.width = `${progressPercentage}%`
- *     progressBar.textContent = `${progressPercentage}% Complete`
- *   }
- * })
+ * @description
+ * Registers a callback to be notified when award progress changes (but award is not
+ * yet complete). Only one callback can be registered at a time. Use this to update
+ * progress bars or show "almost there" encouragement.
+ *
+ * The callback receives:
+ * - `awardId` - Unique Sanity award ID
+ * - `progressPercentage` - Current completion percentage (0-99)
+ *
+ * Note: When an award reaches 100%, `registerAwardCallback` fires instead.
+ *
+ * @example // React Native - Update progress in learning path screen
+ * function LearningPathScreen({ learningPathId }) {
+ *   const [awardProgress, setAwardProgress] = useState({})
+ *
+ *   useEffect(() => {
+ *     return registerProgressCallback(({ awardId, progressPercentage }) => {
+ *       setAwardProgress(prev => ({
+ *         ...prev,
+ *         [awardId]: progressPercentage
+ *       }))
+ *     })
+ *   }, [])
  *
- * // Cleanup on unmount
- * return () => cleanup()
+ *   // Use awardProgress to update UI
+ * }
  *
- * @example // React state update
+ * @example // Show encouragement toast at milestones
  * useEffect(() => {
  *   return registerProgressCallback(({ awardId, progressPercentage }) => {
- *     setAwardProgress(prev => ({
- *       ...prev,
- *       [awardId]: progressPercentage
- *     }))
+ *     if (progressPercentage === 50) {
+ *       showToast('Halfway to your award!')
+ *     } else if (progressPercentage >= 90) {
+ *       showToast('Almost there! Just a few more lessons.')
+ *     }
  *   })
  * }, [])
  */

package/src/services/awards/award-query.js

@@ -1,5 +1,54 @@
 /**
  * @module Awards
+ *
+ * @description
+ * Query award progress, listen for award events, and generate certificates.
+ *
+ * **Query Functions** (read-only):
+ * - `getContentAwards(contentId)` - Get awards for a learning path/course
+ * - `getCompletedAwards(brand)` - Get user's earned awards
+ * - `getInProgressAwards(brand)` - Get awards user is working toward
+ * - `getAwardStatistics(brand)` - Get aggregate award stats
+ *
+ * **Event Callbacks**:
+ * - `registerAwardCallback(fn)` - Listen for new awards earned
+ * - `registerProgressCallback(fn)` - Listen for progress updates
+ *
+ * **Certificates**:
+ * - `fetchCertificate(awardId)` - Generate certificate (Web only)
+ *
+ * @example Quick Start
+ * import {
+ *   getContentAwards,
+ *   getCompletedAwards,
+ *   registerAwardCallback
+ * } from 'musora-content-services'
+ *
+ * // Show awards for a learning path
+ * const { hasAwards, awards } = await getContentAwards(learningPathId)
+ *
+ * // Get user's completed awards
+ * const completed = await getCompletedAwards('drumeo')
+ *
+ * // Listen for new awards (show notification)
+ * useEffect(() => {
+ *   return registerAwardCallback((award) => {
+ *     showCelebration(award.name, award.badge, award.completion_data.message)
+ *   })
+ * }, [])
+ *
+ * @example How Awards Update (Collection Context)
+ * // Award progress updates automatically when you save content progress.
+ * // CRITICAL: Pass collection context when inside a learning path!
+ *
+ * import { contentStatusCompleted } from 'musora-content-services'
+ *
+ * // Correct - passes collection context
+ * const collection = { type: 'learning-path-v2', id: learningPathId }
+ * await contentStatusCompleted(lessonId, collection)
+ *
+ * // Wrong - no collection context (affects wrong awards!)
+ * await contentStatusCompleted(lessonId, null)
  */
 
 import './types.js'
@@ -18,31 +67,48 @@ function enhanceCompletionData(completionData) {
 }
 
 /**
- * @param {number} contentId - Railcontent ID of the content item
+ * @param {number} contentId - Railcontent ID of the content item (lesson, course, or learning path)
  * @returns {Promise<ContentAwardsResponse>} Status object with award information
  *
- * @example // Check if content has awards
- * const { hasAwards, awards } = await getContentAwards(234567)
- * if (hasAwards) {
- *   awards.forEach(award => {
- *     console.log(`${award.awardTitle}: ${award.progressPercentage}%`)
- *   })
+ * @description
+ * Returns awards associated with a content item and the user's progress toward each.
+ * Use this to display award progress on learning path or course detail pages.
+ *
+ * - Pass a **learning path ID** to get awards for that learning path
+ * - Pass a **course ID** to get awards for that course
+ * - Pass a **lesson ID** to get all awards that include that lesson in their requirements
+ *
+ * Returns `{ hasAwards: false, awards: [] }` on error (never throws).
+ *
+ * @example // Display award card on learning path detail page
+ * function LearningPathAwardCard({ learningPathId }) {
+ *   const [awardData, setAwardData] = useState({ hasAwards: false, awards: [] })
+ *
+ *   useEffect(() => {
+ *     getContentAwards(learningPathId).then(setAwardData)
+ *   }, [learningPathId])
+ *
+ *   if (!awardData.hasAwards) return null
+ *
+ *   const award = awardData.awards[0] // Learning paths typically have one award
+ *   return (
+ *     <AwardCard
+ *       badge={award.badge}
+ *       title={award.awardTitle}
+ *       progress={award.progressPercentage}
+ *       isCompleted={award.isCompleted}
+ *       completedAt={award.completedAt}
+ *       instructorName={award.instructorName}
+ *     />
+ *   )
  * }
  *
- * @example // Display award progress on course page
- * const { awards } = await getContentAwards(courseId)
- * return (
- *   <div>
- *     {awards.map(award => (
- *       <AwardProgressBar
- *         key={award.awardId}
- *         title={award.awardTitle}
- *         progress={award.progressPercentage}
- *         badge={award.isCompleted ? award.badge : null}
- *       />
- *     ))}
- *   </div>
- * )
+ * @example // Check award status before showing certificate button
+ * const { hasAwards, awards } = await getContentAwards(learningPathId)
+ * const completedAward = awards.find(a => a.isCompleted)
+ * if (completedAward) {
+ *   showCertificateButton(completedAward.awardId)
+ * }
  */
 export async function getContentAwards(contentId) {
   try {
@@ -93,35 +159,70 @@ export async function getContentAwards(contentId) {
 /**
  * @param {string} [brand=null] - Brand to filter by (drumeo, pianote, guitareo, singeo), or null for all brands
  * @param {AwardPaginationOptions} [options={}] - Optional pagination and filtering
- * @returns {Promise<AwardInfo[]>} Array of completed award objects sorted by completion date
+ * @returns {Promise<AwardInfo[]>} Array of completed award objects sorted by completion date (newest first)
  *
- * @example // Display completed awards gallery
- * const awards = await getCompletedAwards()
- * return (
- *   <AwardsGallery>
- *     <h2>My Achievements ({awards.length})</h2>
- *     {awards.map(award => (
- *       <Badge
- *         key={award.awardId}
- *         image={award.badge}
- *         title={award.awardTitle}
- *         date={new Date(award.completedAt).toLocaleDateString()}
- *       />
- *     ))}
- *   </AwardsGallery>
- * )
+ * @description
+ * Returns all awards the user has completed. Use this for "My Achievements" or
+ * profile award gallery screens. Each award includes:
+ *
+ * - Badge and award images for display
+ * - Completion date for "Earned on X" display
+ * - `completionData.message` - Pre-generated congratulations text
+ * - `completionData.practice_minutes` - Total practice time for this award
+ * - `completionData.days_user_practiced` - Days spent earning this award
+ *
+ * Returns empty array `[]` on error (never throws).
+ *
+ * @example // Awards gallery screen
+ * function AwardsGalleryScreen() {
+ *   const [awards, setAwards] = useState([])
+ *   const brand = useBrand() // 'drumeo', 'pianote', etc.
  *
- * @example // Paginated awards list
- * const [page, setPage] = useState(0)
- * const pageSize = 12
- * const awards = await getCompletedAwards('drumeo', {
- *   limit: pageSize,
- *   offset: page * pageSize
- * })
- *
- * @example // Filter by brand
- * const pianoAwards = await getCompletedAwards('pianote')
- * console.log(`You've earned ${pianoAwards.length} piano awards!`)
+ *   useEffect(() => {
+ *     getCompletedAwards(brand).then(setAwards)
+ *   }, [brand])
+ *
+ *   return (
+ *     <FlatList
+ *       data={awards}
+ *       keyExtractor={item => item.awardId}
+ *       numColumns={2}
+ *       renderItem={({ item }) => (
+ *         <AwardBadge
+ *           badge={item.badge}
+ *           title={item.awardTitle}
+ *           earnedDate={new Date(item.completedAt).toLocaleDateString()}
+ *           onPress={() => showAwardDetail(item)}
+ *         />
+ *       )}
+ *     />
+ *   )
+ * }
+ *
+ * @example // Show award detail with practice stats
+ * function AwardDetailModal({ award }) {
+ *   return (
+ *     <Modal>
+ *       <Image source={{ uri: award.award }} />
+ *       <Text>{award.awardTitle}</Text>
+ *       <Text>Instructor: {award.instructorName}</Text>
+ *       <Text>Completed: {new Date(award.completedAt).toLocaleDateString()}</Text>
+ *       <Text>Practice time: {award.completionData.practice_minutes} minutes</Text>
+ *       <Text>Days practiced: {award.completionData.days_user_practiced}</Text>
+ *       <Text>{award.completionData.message}</Text>
+ *     </Modal>
+ *   )
+ * }
+ *
+ * @example // Paginated loading
+ * const PAGE_SIZE = 12
+ * const loadMore = async (page) => {
+ *   const newAwards = await getCompletedAwards(brand, {
+ *     limit: PAGE_SIZE,
+ *     offset: page * PAGE_SIZE
+ *   })
+ *   setAwards(prev => [...prev, ...newAwards])
+ * }
  */
 export async function getCompletedAwards(brand = null, options = {}) {
   try {
@@ -179,42 +280,78 @@ export async function getCompletedAwards(brand = null, options = {}) {
 /**
  * @param {string} [brand=null] - Brand to filter by (drumeo, pianote, guitareo, singeo), or null for all brands
  * @param {AwardPaginationOptions} [options={}] - Optional pagination options
- * @returns {Promise<AwardInfo[]>} Array of in-progress award objects sorted by progress
+ * @returns {Promise<AwardInfo[]>} Array of in-progress award objects sorted by progress percentage (highest first)
  *
- * @example // Display in-progress awards dashboard
- * const inProgress = await getInProgressAwards()
- * return (
- *   <div>
- *     <h2>Keep Going! ({inProgress.length})</h2>
- *     {inProgress.map(award => (
- *       <ProgressCard
- *         key={award.awardId}
- *         title={award.awardTitle}
- *         progress={award.progressPercentage}
- *         badge={award.badge}
- *       />
- *     ))}
- *   </div>
- * )
+ * @description
+ * Returns awards the user has started but not yet completed. Sorted by progress
+ * percentage (highest first) so awards closest to completion appear first.
+ * Use this for "Continue Learning" or dashboard widgets.
+ *
+ * Progress is calculated based on lessons completed within the correct collection
+ * context. For learning paths, only lessons completed within that specific learning
+ * path count toward its award.
+ *
+ * Returns empty array `[]` on error (never throws).
+ *
+ * @example // "Almost There" widget on home screen
+ * function AlmostThereWidget() {
+ *   const [topAwards, setTopAwards] = useState([])
+ *   const brand = useBrand()
+ *
+ *   useEffect(() => {
+ *     // Get top 3 closest to completion
+ *     getInProgressAwards(brand, { limit: 3 }).then(setTopAwards)
+ *   }, [brand])
+ *
+ *   if (topAwards.length === 0) return null
  *
- * @example // Show closest to completion
- * const inProgress = await getInProgressAwards(null, { limit: 3 })
- * console.log('Awards closest to completion:')
- * inProgress.forEach(award => {
- *   console.log(`${award.awardTitle}: ${award.progressPercentage}% complete`)
- * })
- *
- * @example // Filter by brand with pagination
- * const guitarAwards = await getInProgressAwards('guitareo', {
- *   limit: 10,
- *   offset: 0
- * })
+ *   return (
+ *     <View>
+ *       <Text>Almost There!</Text>
+ *       {topAwards.map(award => (
+ *         <TouchableOpacity
+ *           key={award.awardId}
+ *           onPress={() => navigateToLearningPath(award)}
+ *         >
+ *           <Image source={{ uri: award.badge }} />
+ *           <Text>{award.awardTitle}</Text>
+ *           <ProgressBar progress={award.progressPercentage / 100} />
+ *           <Text>{award.progressPercentage}% complete</Text>
+ *         </TouchableOpacity>
+ *       ))}
+ *     </View>
+ *   )
+ * }
+ *
+ * @example // Full in-progress awards list
+ * function InProgressAwardsScreen() {
+ *   const [awards, setAwards] = useState([])
+ *
+ *   useEffect(() => {
+ *     getInProgressAwards().then(setAwards)
+ *   }, [])
+ *
+ *   return (
+ *     <FlatList
+ *       data={awards}
+ *       keyExtractor={item => item.awardId}
+ *       renderItem={({ item }) => (
+ *         <AwardProgressCard
+ *           badge={item.badge}
+ *           title={item.awardTitle}
+ *           progress={item.progressPercentage}
+ *           brand={item.brand}
+ *         />
+ *       )}
+ *     />
+ *   )
+ * }
  */
 export async function getInProgressAwards(brand = null, options = {}) {
   try {
     const allProgress = await db.userAwardProgress.getAll()
     const inProgress = allProgress.data.filter(p =>
-      p.progress_percentage > 0 && (p.progress_percentage < 100 || p.completed_at === null)
+      p.progress_percentage >= 0 && (p.progress_percentage < 100 || p.completed_at === null)
     )
 
     let awards = await Promise.all(
@@ -266,20 +403,51 @@ export async function getInProgressAwards(brand = null, options = {}) {
  * @param {string} [brand=null] - Brand to filter by (drumeo, pianote, guitareo, singeo), or null for all brands
  * @returns {Promise<AwardStatistics>} Statistics object with award counts and completion percentage
  *
- * @example // Display stats widget
+ * @description
+ * Returns aggregate statistics about the user's award progress. Use this for
+ * profile stats, gamification dashboards, or achievement summaries.
+ *
+ * Returns an object with:
+ * - `totalAvailable` - Total awards that can be earned
+ * - `completed` - Number of awards earned
+ * - `inProgress` - Number of awards started but not completed
+ * - `notStarted` - Number of awards not yet started
+ * - `completionPercentage` - Overall completion % (0-100, one decimal)
+ *
+ * Returns all zeros on error (never throws).
+ *
+ * @example // Profile stats card
+ * function ProfileStatsCard() {
+ *   const [stats, setStats] = useState(null)
+ *   const brand = useBrand()
+ *
+ *   useEffect(() => {
+ *     getAwardStatistics(brand).then(setStats)
+ *   }, [brand])
+ *
+ *   if (!stats) return <LoadingSpinner />
+ *
+ *   return (
+ *     <View style={styles.statsCard}>
+ *       <StatItem label="Awards Earned" value={stats.completed} />
+ *       <StatItem label="In Progress" value={stats.inProgress} />
+ *       <StatItem label="Available" value={stats.totalAvailable} />
+ *       <ProgressRing
+ *         progress={stats.completionPercentage / 100}
+ *         label={`${stats.completionPercentage}%`}
+ *       />
+ *     </View>
+ *   )
+ * }
+ *
+ * @example // Achievement progress bar
  * const stats = await getAwardStatistics('drumeo')
  * return (
- *   <StatsWidget>
- *     <Stat label="Earned" value={stats.completed} />
- *     <Stat label="In Progress" value={stats.inProgress} />
- *     <Stat label="Completion" value={`${stats.completionPercentage}%`} />
- *   </StatsWidget>
+ *   <View>
+ *     <Text>{stats.completed} of {stats.totalAvailable} awards earned</Text>
+ *     <ProgressBar progress={stats.completionPercentage / 100} />
+ *   </View>
  * )
- *
- * @example // Progress bar
- * const stats = await getAwardStatistics()
- * console.log(`${stats.completed}/${stats.totalAvailable} awards earned`)
- * console.log(`${stats.completionPercentage}% complete`)
  */
 export async function getAwardStatistics(brand = null) {
   try {
@@ -299,7 +467,7 @@ export async function getAwardStatistics(brand = null) {
     ).length
 
     const inProgressCount = filteredProgress.filter(p =>
-      p.progress_percentage > 0 && (p.progress_percentage < 100 || p.completed_at === null)
+      p.progress_percentage >= 0 && (p.progress_percentage < 100 || p.completed_at === null)
     ).length
 
     const totalAvailable = allDefinitions.length

package/src/services/awards/types.js

@@ -6,14 +6,14 @@
  * @property {string|null} logo - URL to logo image
  * @property {string} badge - URL to badge image
  * @property {string} award - URL to award image
- * @property {number} content_id - Railcontent ID of the parent content
- * @property {string} content_type - Type of content (guided-course, learning-path-v2, etc.)
+ * @property {number} content_id - Railcontent ID of the parent content (e.g., the learning path ID)
+ * @property {string} content_type - Type of parent content ('learning-path-v2', 'guided-course', etc.). Used with content_id to determine collection context for award evaluation.
  * @property {string} type - Sanity document type
  * @property {string} brand - Brand (drumeo, pianote, guitareo, singeo)
  * @property {string} content_title - Title of the associated content
  * @property {string|null} award_custom_text - Custom text for the award
  * @property {string|null} instructor_name - Name of the instructor
- * @property {number[]} child_ids - Array of child content IDs required for completion
+ * @property {number[]} child_ids - Array of child content IDs (lessons) that must be completed to earn this award
  */
 
 /**
@@ -41,7 +41,7 @@
  * @property {string} award - URL to award image
  * @property {string} brand - Brand (drumeo, pianote, guitareo, singeo)
  * @property {string} instructorName - Name of the instructor
- * @property {number} progressPercentage - Completion percentage (0-100)
+ * @property {number} progressPercentage - Completion percentage (0-100). Progress is tracked per collection context for learning paths.
  * @property {boolean} isCompleted - Whether the award is fully completed
  * @property {string|null} completedAt - ISO timestamp of completion, or null if not completed
  * @property {AwardCompletionData|null} completionData - Practice statistics, or null if not started
@@ -50,7 +50,7 @@
 /**
  * @typedef {Object} ContentAwardsResponse
  * @property {boolean} hasAwards - Whether the content has any associated awards
- * @property {AwardInfo[]} awards - Array of award objects with progress information
+ * @property {AwardInfo[]} awards - Array of award objects with progress information. For learning paths, progress is scoped to the specific learning path context.
  */
 
 /**

package/src/services/sync/repositories/user-award-progress.ts

@@ -15,7 +15,7 @@ export default class UserAwardProgressRepository extends SyncRepository<UserAwar
   }
 
   static isInProgress(progress: AwardProgressData): boolean {
-    return progress.progress_percentage > 0 && !UserAwardProgressRepository.isCompleted(progress)
+    return progress.progress_percentage >= 0 && !UserAwardProgressRepository.isCompleted(progress)
   }
 
   static completedAtDate(progress: { completed_at: number | null }): Date | null {