musora-content-services 2.94.7 → 2.95.0

package/src/services/awards/internal/content-progress-observer.js

@@ -0,0 +1,137 @@
+import { awardManager } from './award-manager'
+import { awardDefinitions } from './award-definitions'
+import { onProgressSaved } from '../../progress-events'
+import { COLLECTION_TYPE } from '../../sync/models/ContentProgress'
+
+
+class ContentProgressObserver {
+  constructor() {
+    this.subscription = null
+    this.progressEventUnsubscribe = null
+    this.isObserving = false
+    this.processingContentIds = new Set()
+    this.debounceTimers = new Map()
+    this.debounceMs = 50
+    this.allChildIds = new Set()
+  }
+
+  /** @returns {Promise<() => void>} */
+  async start(database) {
+    if (this.isObserving) {
+      return () => {}
+    }
+
+    await awardDefinitions.refresh()
+    const allAwards = await awardDefinitions.getAll()
+
+    this.allChildIds.clear()
+    for (const award of allAwards) {
+      if (award.content_id) {
+        this.allChildIds.add(award.content_id)
+      }
+      if (award.child_ids) {
+        award.child_ids.forEach(childId => this.allChildIds.add(childId))
+      }
+    }
+
+    if (this.allChildIds.size === 0) {
+      return () => {}
+    }
+
+    this.progressEventUnsubscribe = onProgressSaved((event) => {
+      if (this.allChildIds.has(event.contentId)) {
+        this.handleProgressChange({
+          content_id: event.contentId,
+          state: event.progressStatus,
+          progress_percent: event.progressPercent,
+          collection_type: event.collectionType,
+          collection_id: event.collectionId
+        })
+      }
+    })
+
+    this.isObserving = true
+
+    return () => this.stop()
+  }
+
+  /** @returns {Promise<void>} */
+  async handleProgressChange(progressRecord) {
+    try {
+      const childContentId = progressRecord.content_id
+      const collectionType = progressRecord.collection_type
+      const collectionId = progressRecord.collection_id
+
+      const allAwards = await awardDefinitions.getAll()
+      let parentAwards = []
+
+      const isLearningPathContext = collectionType === COLLECTION_TYPE.LEARNING_PATH && collectionId
+      if (isLearningPathContext) {
+        parentAwards = allAwards.filter(award => {
+          return award.child_ids?.includes(childContentId) &&
+            award.content_type === collectionType &&
+            award.content_id === collectionId
+        })
+      } else {
+        parentAwards = allAwards.filter(award => award.child_ids?.includes(childContentId))
+      }
+
+      for (const award of parentAwards) {
+        if (award.content_id) {
+          this.debounceAwardCheck(award.content_id)
+        }
+      }
+    } catch (error) {
+      console.error('[ContentProgressObserver] Error handling progress change:', error)
+    }
+  }
+
+  debounceAwardCheck(contentId) {
+    if (this.debounceTimers.has(contentId)) {
+      clearTimeout(this.debounceTimers.get(contentId))
+    }
+
+    const timerId = setTimeout(async () => {
+      this.debounceTimers.delete(contentId)
+      await this.checkAward(contentId)
+    }, this.debounceMs)
+
+    this.debounceTimers.set(contentId, timerId)
+  }
+
+  /** @returns {Promise<void>} */
+  async checkAward(contentId) {
+    if (this.processingContentIds.has(contentId)) {
+      return
+    }
+
+    this.processingContentIds.add(contentId)
+
+    try {
+      await awardManager.onContentCompleted(contentId)
+    } catch (error) {
+      console.error(`[ContentProgressObserver] Error checking award for content ${contentId}:`, error)
+    } finally {
+      this.processingContentIds.delete(contentId)
+    }
+  }
+
+  stop() {
+    if (this.progressEventUnsubscribe) {
+      this.progressEventUnsubscribe()
+      this.progressEventUnsubscribe = null
+    }
+
+    for (const timerId of this.debounceTimers.values()) {
+      clearTimeout(timerId)
+    }
+    this.debounceTimers.clear()
+    this.processingContentIds.clear()
+    this.allChildIds.clear()
+
+    this.isObserving = false
+  }
+}
+
+
+export const contentProgressObserver = new ContentProgressObserver()

package/src/services/awards/internal/image-utils.js

@@ -0,0 +1,62 @@
+/**
+ * @module Awards
+ */
+
+
+/**
+ * @param {string} url
+ * @returns {Promise<string>}
+ */
+export async function urlToBase64(url) {
+  try {
+    if (!url) {
+      return ''
+    }
+
+    const response = await fetch(url)
+
+    if (!response.ok) {
+      console.warn(`Failed to fetch image: ${url}`)
+      return ''
+    }
+
+    const blob = await response.blob()
+
+    return new Promise((resolve, reject) => {
+      const reader = new FileReader()
+
+      reader.onloadend = () => {
+        const base64String = reader.result
+        const base64Data = base64String.split(',')[1]
+        resolve(base64Data || '')
+      }
+
+      reader.onerror = () => {
+        console.error(`Failed to convert image to base64: ${url}`)
+        reject(new Error('Failed to convert image to base64'))
+      }
+
+      reader.readAsDataURL(blob)
+    })
+  } catch (error) {
+    console.error(`Error converting URL to base64: ${url}`, error)
+    return ''
+  }
+}
+
+/**
+ * @param {Object<string, string>} urlMap
+ * @returns {Promise<Object<string, string>>}
+ */
+export async function urlMapToBase64(urlMap) {
+  const entries = Object.entries(urlMap)
+
+  const results = await Promise.all(
+    entries.map(async ([key, url]) => {
+      const base64 = await urlToBase64(url)
+      return [key, base64]
+    })
+  )
+
+  return Object.fromEntries(results)
+}

package/src/services/awards/internal/message-generator.js

@@ -0,0 +1,17 @@
+export class AwardMessageGenerator {
+  /** @returns {string} */
+  static generatePopupMessage(completionData) {
+    const { days_user_practiced, practice_minutes, content_title } = completionData
+    const daysLabel = days_user_practiced === 1 ? 'day' : 'days'
+
+    return `You received this award for completing ${content_title}! You practiced a total of ${practice_minutes} minutes over the past ${days_user_practiced} ${daysLabel}.`
+  }
+
+  /** @returns {string} */
+  static generateCertificateMessage(completionData, awardCustomText) {
+    const { content_title, practice_minutes } = completionData
+    const customText = awardCustomText ? ` ${awardCustomText}` : ''
+
+    return `You practiced for a total of ${practice_minutes} minutes during ${content_title}, earning your official certificate of completion.${customText} Well Done!`
+  }
+}

package/src/services/awards/internal/types.js

@@ -0,0 +1,5 @@
+/**  @typedef {Object} AwardDefinition */
+/**  @typedef {Object} CompletionData */
+/**  @typedef {Object} CertificateData */
+
+export {}

package/src/services/awards/types.d.ts

@@ -0,0 +1,79 @@
+export interface AwardDefinition {
+  _id: string
+  is_active: boolean
+  name: string
+  logo: string | null
+  badge: string
+  award: string
+  content_id: number
+  content_type: string
+  type: string
+  brand: string
+  content_title: string
+  award_custom_text: string | null
+  instructor_name: string | null
+  child_ids: number[]
+}
+
+export interface CompletionData {
+  content_title: string
+  completed_at: string
+  days_user_practiced: number
+  practice_minutes: number
+}
+
+export interface AwardCompletionData {
+  completed_at: string
+  days_user_practiced: number
+  practice_minutes: number
+  content_title: string
+  message: string
+}
+
+export interface AwardInfo {
+  awardId: string
+  awardTitle: string
+  badge: string
+  award: string
+  brand: string
+  instructorName: string
+  progressPercentage: number
+  isCompleted: boolean
+  completedAt: string | null
+  completionData: AwardCompletionData | null
+}
+
+export interface ContentAwardsResponse {
+  hasAwards: boolean
+  awards: AwardInfo[]
+}
+
+export interface AwardStatistics {
+  totalAvailable: number
+  completed: number
+  inProgress: number
+  notStarted: number
+  completionPercentage: number
+}
+
+export interface AwardPaginationOptions {
+  limit?: number
+  offset?: number
+}
+
+export interface AwardCallbackPayload {
+  awardId: string
+  name: string
+  badge: string
+  completed_at: string
+  completion_data: AwardCompletionData
+}
+
+export interface ProgressCallbackPayload {
+  awardId: string
+  progressPercentage: number
+}
+
+export type AwardCallbackFunction = (award: AwardCallbackPayload) => void
+export type ProgressCallbackFunction = (progress: ProgressCallbackPayload) => void
+export type UnregisterFunction = () => void

package/src/services/awards/types.js

@@ -0,0 +1,101 @@
+/**
+ * @typedef {Object} AwardDefinition
+ * @property {string} _id - Unique Sanity award ID
+ * @property {boolean} is_active - Whether the award is active
+ * @property {string} name - Display name of the award
+ * @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 {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
+ */
+
+/**
+ * @typedef {Object} CompletionData
+ * @property {string} content_title - Title of the completed content
+ * @property {string} completed_at - ISO timestamp of completion
+ * @property {number} days_user_practiced - Number of days the user practiced
+ * @property {number} practice_minutes - Total practice time in minutes
+ */
+
+/**
+ * @typedef {Object} AwardCompletionData
+ * @property {string} completed_at - ISO timestamp of completion
+ * @property {number} days_user_practiced - Number of days the user practiced
+ * @property {number} practice_minutes - Total practice time in minutes
+ * @property {string} content_title - Title of the completed content
+ * @property {string} message - Congratulations message for display
+ */
+
+/**
+ * @typedef {Object} AwardInfo
+ * @property {string} awardId - Unique Sanity award ID
+ * @property {string} awardTitle - Display name of the award
+ * @property {string} badge - URL to badge image
+ * @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 {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
+ */
+
+/**
+ * @typedef {Object} ContentAwardsResponse
+ * @property {boolean} hasAwards - Whether the content has any associated awards
+ * @property {AwardInfo[]} awards - Array of award objects with progress information
+ */
+
+/**
+ * @typedef {Object} AwardStatistics
+ * @property {number} totalAvailable - Total number of awards available
+ * @property {number} completed - Number of completed awards
+ * @property {number} inProgress - Number of awards in progress
+ * @property {number} notStarted - Number of awards not yet started
+ * @property {number} completionPercentage - Overall completion percentage (0-100)
+ */
+
+/**
+ * @typedef {Object} AwardPaginationOptions
+ * @property {number} [limit] - Maximum number of results to return
+ * @property {number} [offset] - Number of results to skip for pagination
+ */
+
+/**
+ * @typedef {Object} AwardCallbackPayload
+ * @property {string} awardId - Unique Sanity award ID
+ * @property {string} name - Display name of the award
+ * @property {string} badge - URL to badge image
+ * @property {string} completed_at - ISO timestamp of completion
+ * @property {AwardCompletionData} completion_data - Practice statistics
+ */
+
+/**
+ * @typedef {Object} ProgressCallbackPayload
+ * @property {string} awardId - Unique Sanity award ID
+ * @property {number} progressPercentage - Completion percentage (0-100)
+ */
+
+/**
+ * @callback AwardCallbackFunction
+ * @param {AwardCallbackPayload} award - Award data when an award is earned
+ * @returns {void}
+ */
+
+/**
+ * @callback ProgressCallbackFunction
+ * @param {ProgressCallbackPayload} progress - Progress data when award progress changes
+ * @returns {void}
+ */
+
+/**
+ * @callback UnregisterFunction
+ * @returns {void}
+ */

package/src/services/config.js

@@ -25,11 +25,11 @@ const excludeFromGeneratedIndex = []
 /**
  * Initializes the service with the given configuration.
  * This function must be called before using any other functions in this library.
+ * Automatically initializes award definitions with 24-hour cache in the background.
  *
  * @param {Config} config - Configuration object containing API settings.
  *
- * @example
- * // Initialize the service in your app.js
+ * @example Web Application
  * initializeService({
  *   sanityConfig: {
  *     token: 'your-sanity-api-token',
@@ -43,18 +43,30 @@ const excludeFromGeneratedIndex = []
  *     token: 'your-user-api-token',
  *     userId: 'current-user-id',
  *     baseUrl: 'https://web-staging-one.musora.com',
- *     authToken 'your-auth-token',
+ *     authToken: 'your-auth-token',
  *   },
  *   sessionConfig: {
  *     token: 'your-user-api-token',
  *     userId: 'current-user-id',
- *     authToken 'your-auth-token',
+ *     authToken: 'your-auth-token',
  *   },
  *   baseUrl: 'https://web-staging-one.musora.com',
  *   localStorage: localStorage,
  *   isMA: false,
  *   permissionsVersion: 'v1', // Optional: 'v1' (default) or 'v2'
  * });
+ *
+ * @example React Native Application
+ * import AsyncStorage from '@react-native-async-storage/async-storage'
+ *
+ * initializeService({
+ *   sanityConfig: { ... },
+ *   railcontentConfig: { ... },
+ *   sessionConfig: { ... },
+ *   baseUrl: 'https://web-staging-one.musora.com',
+ *   localStorage: AsyncStorage,
+ *   isMA: true,
+ * });
  */
 export function initializeService(config) {
   globalConfig.sanityConfig = config.sanityConfig
@@ -65,4 +77,12 @@ export function initializeService(config) {
   globalConfig.isMA = config.isMA || false
   globalConfig.localTimezoneString = config.localTimezoneString || null
   globalConfig.permissionsVersion = config.permissionsVersion || 'v2'
+
+  if (config.localStorage) {
+    import('./awards/internal/award-definitions')
+      .then(({ awardDefinitions }) => awardDefinitions.initialize())
+      .catch(error => {
+        console.error('Failed to initialize award definitions:', error)
+      })
+  }
 }

package/src/services/content-org/learning-paths.ts

@@ -173,7 +173,7 @@ export async function fetchLearningPathLessons(
   userDate: Date
 ) {
   const learningPath = await getEnrichedLearningPath(learningPathId)
-  let dailySession = await getDailySession(brand, userDate)
+  let dailySession = await getDailySession(brand, userDate) // what if the call just fails, and a DS does exist?
   if (!dailySession) {
     dailySession = await updateDailySession(brand, userDate, false)
   }
@@ -185,19 +185,22 @@ export async function fetchLearningPathLessons(
       is_active_learning_path: isActiveLearningPath,
     }
   }
+  // this assumes that the first entry is active_path, based on user flows
   const todayContentIds = dailySession.daily_session[0]?.content_ids || []
-  const previousLearningPathId = dailySession.daily_session[0]?.learning_path_id
+  const todayLearningPathId = dailySession.daily_session[0]?.learning_path_id
+
   const nextContentIds = dailySession.daily_session[1]?.content_ids || []
   const nextLearningPathId = dailySession.daily_session[1]?.learning_path_id
+
   const completedLessons = []
-  let todaysLessons = []
-  let nextLPLessons = []
+  let thisLPDailies = []
+  let nextLPDailies = []
   let previousLearningPathTodays = []
   const upcomingLessons = []
 
   learningPath.children.forEach((lesson: any) => {
     if (todayContentIds.includes(lesson.id)) {
-      todaysLessons.push(lesson)
+      thisLPDailies.push(lesson)
     } else if (lesson.progressStatus === 'completed') {
       completedLessons.push(lesson)
     } else {
@@ -205,22 +208,23 @@ export async function fetchLearningPathLessons(
     }
   })
 
-  if (todaysLessons.length == 0) {
+  if (thisLPDailies.length == 0) {
     // Daily sessions first lessons are not part of the active learning path, but next lessons are
     // load todays lessons from previous learning path
     previousLearningPathTodays = await getLearningPathLessonsByIds(
       todayContentIds,
-      previousLearningPathId
+      todayLearningPathId
     )
-  } else if (
-    nextContentIds.length > 0 &&
-    todaysLessons.length < 3 &&
-    upcomingLessons.length === 0
+  } else if ( // show next LP dailies if they exist
+    nextContentIds.length > 0
   ) {
     // Daily sessions first lessons are the active learning path and the next lessons are not
     // load next lessons from next learning path
-    // TODO: update item status to locked when the current learning path is not complete
-    nextLPLessons = await getLearningPathLessonsByIds(nextContentIds, nextLearningPathId)
+    const lessons = await getLearningPathLessonsByIds(nextContentIds, nextLearningPathId)
+    nextLPDailies = lessons.map(lesson => ({
+      ...lesson,
+      in_next_learning_path: STATE.COMPLETED === learningPath.progressStatus
+    }))
   }
 
 
@@ -231,8 +235,8 @@ export async function fetchLearningPathLessons(
     active_learning_path_id: dailySession?.active_learning_path_id,
     active_learning_path_created_at: dailySession?.active_learning_path_created_at,
     upcoming_lessons: upcomingLessons,
-    todays_lessons: todaysLessons,
-    next_learning_path_lessons: nextLPLessons,
+    todays_lessons: thisLPDailies,
+    next_learning_path_lessons: nextLPDailies,
     next_learning_path_id: nextLearningPathId,
     completed_lessons: completedLessons,
     previous_learning_path_todays: previousLearningPathTodays,

package/src/services/contentProgress.js

@@ -432,9 +432,10 @@ function normalizeContentIds(contentIds) {
 function normalizeCollection(collection) {
   if (!collection) return null
 
-  if (COLLECTION_TYPE.indexOf(collection.type) === -1) {
+  if (!Object.values(COLLECTION_TYPE).includes(collection.type)) {
     throw new Error(`Invalid collection type: ${collection.type}`)
   }
+  
   if (typeof collection.id === 'string' && isNaN(+collection.id)) {
     throw new Error(`Invalid collection id: ${collection.id}`)
   }