musora-content-services 2.19.2 → 2.21.0

package/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(rg:*)"
+    ],
+    "deny": []
+  }
+}

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 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.21.0](https://github.com/railroadmedia/musora-content-services/compare/v2.20.0...v2.21.0) (2025-07-12)
+
+
+### Features
+
+* **BEH-572:** ai recommender row categories ([#337](https://github.com/railroadmedia/musora-content-services/issues/337)) ([d1984d2](https://github.com/railroadmedia/musora-content-services/commit/d1984d28371fa2d4f22d8ddb50fdcfd952399b46))
+
+## [2.20.0](https://github.com/railroadmedia/musora-content-services/compare/v2.19.2...v2.20.0) (2025-07-11)
+
+
+### Features
+
+* **BEH-662:** add pinned guided course to homepage ([#332](https://github.com/railroadmedia/musora-content-services/issues/332)) ([6a06612](https://github.com/railroadmedia/musora-content-services/commit/6a066121684cbab1610119906568e4320c4df08c))
+* **BEH-706:** add continue behaviour to lessons collection page and index page ([#326](https://github.com/railroadmedia/musora-content-services/issues/326)) ([6add054](https://github.com/railroadmedia/musora-content-services/commit/6add054841688ea0cd550f11ad21e047de63f235))
+
 ### [2.19.2](https://github.com/railroadmedia/musora-content-services/compare/v2.19.1...v2.19.2) (2025-07-09)
 
 ### [2.19.1](https://github.com/railroadmedia/musora-content-services/compare/v2.19.0...v2.19.1) (2025-07-09)

package/package.json

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

package/src/contentTypeConfig.js

@@ -24,7 +24,6 @@ export const DEFAULT_FIELDS = [
   "'url': web_url_path",
   'published_on',
   "'type': _type",
-  'progress_percent',
   "'length_in_seconds' : coalesce(length_in_seconds, soundslice[0].soundslice_length_in_second)",
   'brand',
   "'genre': genre[]->name",
@@ -139,7 +138,7 @@ export const singleLessonTypes = ['quick-tips', 'rudiment', 'coach-lessons'];
 export const practiceAlongsLessonTypes = ['workout', 'boot-camp','challenges'];
 export const performancesLessonTypes = ['performance','solo','drum-fest-international-2022'];
 export const documentariesLessonTypes = ['tama','sonor','history-of-electronic-drums','paiste-cymbals'];
-export const liveArchivesLessonTypes = ['podcast', 'coach-stream', 'question-and-answer', 'live-streams'];
+export const liveArchivesLessonTypes = ['podcast', 'coach-stream', 'question-and-answer', 'live-streams', 'live'];
 export const studentArchivesLessonTypes = ['student-review', 'student-focus','student-collaboration'];
 export const tutorialsLessonTypes = ['song-tutorial'];
 export const transcriptionsLessonTypes = ['song'];
@@ -180,6 +179,8 @@ export const lessonTypesMapping = {
   'jam tracks': ['jam-track'],
 };
 
+export const getNextLessonLessonParentTypes = ['course', 'guided-course', 'pack-bundle'];
+
 export const progressTypesMapping = {
   'lesson': [...singleLessonTypes,...practiceAlongsLessonTypes, ...liveArchivesLessonTypes, ...performancesLessonTypes, ...studentArchivesLessonTypes, ...documentariesLessonTypes, 'live'],
   'course': ['course'],
@@ -207,12 +208,33 @@ export const filterTypes = {
 export const recentTypes = {
   lessons: [...individualLessonsTypes],
   songs: [...tutorialsLessonTypes, ...transcriptionsLessonTypes, ...playAlongLessonTypes],
-  home: [...individualLessonsTypes, ...tutorialsLessonTypes, ...transcriptionsLessonTypes, ...playAlongLessonTypes]
+  home: [...individualLessonsTypes, ...tutorialsLessonTypes, ...transcriptionsLessonTypes, ...playAlongLessonTypes,
+  'guided-course', 'learning-path', 'live']
 }
 
 export let contentTypeConfig = {
   'progress-tracker': {
-    fields: ['"parent_content_data": parent_content_data[].id','"badge" : badge.asset->url','"lessons": child[]->{"id": railcontent_id, "slug":slug.current, "brand":brand, "type": _type, "lessons": child[]->{"id":railcontent_id, "slug":slug.current,  "type": _type,"brand":brand}}'],
+    fields: ['"parent_content_data": parent_content_data[].id',
+      '"badge" : badge.asset->url',
+      '"lessons": child[]->{' +
+        '"id": railcontent_id,' +
+        '"slug":slug.current,' +
+        '"brand":brand,' +
+        '"type": _type,' +
+        '"thumbnail": thumbnail.asset->url,' +
+        'published_on,' +
+        '"lessons": child[]->{' +
+          '"id":railcontent_id,' +
+          '"slug":slug.current,' +
+          '"type": _type,' +
+          '"brand":brand},' +
+          '"thumbnail": thumbnail.asset->url,' +
+          'published_on,' +
+        '}'
+    ],
+
+
+
   },
   song: {
     fields: ['album', 'soundslice', 'instrumentless', `"resources": ${resourcesField}`],
@@ -420,10 +442,14 @@ export let contentTypeConfig = {
       '"logo_image_url": logo_image_url.asset->url',
       'total_xp',
       `"children": child[]->{
-                "description": ${descriptionField},
-                "lesson_count": child_count,
-                ${getFieldsForContentType()}
-            }`,
+        "description": ${descriptionField},
+        "lesson_count": child_count,
+        "children": child[]->{
+          "description": ${descriptionField},
+          ${getFieldsForContentType()}
+        },
+        ${getFieldsForContentType()}
+      }`,
       `"resources": ${resourcesField}`,
       '"thumbnail": thumbnail.asset->url',
       '"light_mode_logo": light_mode_logo_url.asset->url',

package/src/index.d.ts

@@ -62,6 +62,8 @@ import {
 	getAllCompleted,
 	getAllStarted,
 	getAllStartedOrCompleted,
+	getLastInteractedOf,
+	getNextLesson,
 	getProgressDateByIds,
 	getProgressPercentage,
 	getProgressPercentageByIds,
@@ -187,6 +189,7 @@ import {
 	fetchCoachLessons,
 	fetchComingSoon,
 	fetchCommentModContentData,
+	fetchContentRows,
 	fetchFoundation,
 	fetchGenreLessons,
 	fetchHierarchy,
@@ -284,6 +287,7 @@ import {
 	createPracticeNotes,
 	deletePracticeSession,
 	deleteUserActivity,
+	findIncompleteLesson,
 	getPracticeNotes,
 	getPracticeSessions,
 	getProgressRows,
@@ -361,6 +365,7 @@ declare module 'musora-content-services' {
 		fetchContentInProgress,
 		fetchContentPageUserData,
 		fetchContentProgress,
+		fetchContentRows,
 		fetchEnrollmentPageMetadata,
 		fetchFoundation,
 		fetchGenreLessons,
@@ -422,14 +427,17 @@ declare module 'musora-content-services' {
 		fetchUserPracticeMeta,
 		fetchUserPracticeNotes,
 		fetchUserPractices,
+		findIncompleteLesson,
 		getActiveDiscussions,
 		getAllCompleted,
 		getAllStarted,
 		getAllStartedOrCompleted,
 		getContentRows,
+		getLastInteractedOf,
 		getLessonContentRows,
 		getMonday,
 		getNewAndUpcoming,
+		getNextLesson,
 		getPracticeNotes,
 		getPracticeSessions,
 		getProgressDateByIds,

package/src/index.js

@@ -62,6 +62,8 @@ import {
 	getAllCompleted,
 	getAllStarted,
 	getAllStartedOrCompleted,
+	getLastInteractedOf,
+	getNextLesson,
 	getProgressDateByIds,
 	getProgressPercentage,
 	getProgressPercentageByIds,
@@ -187,6 +189,7 @@ import {
 	fetchCoachLessons,
 	fetchComingSoon,
 	fetchCommentModContentData,
+	fetchContentRows,
 	fetchFoundation,
 	fetchGenreLessons,
 	fetchHierarchy,
@@ -284,6 +287,7 @@ import {
 	createPracticeNotes,
 	deletePracticeSession,
 	deleteUserActivity,
+	findIncompleteLesson,
 	getPracticeNotes,
 	getPracticeSessions,
 	getProgressRows,
@@ -360,6 +364,7 @@ export {
 	fetchContentInProgress,
 	fetchContentPageUserData,
 	fetchContentProgress,
+	fetchContentRows,
 	fetchEnrollmentPageMetadata,
 	fetchFoundation,
 	fetchGenreLessons,
@@ -421,14 +426,17 @@ export {
 	fetchUserPracticeMeta,
 	fetchUserPracticeNotes,
 	fetchUserPractices,
+	findIncompleteLesson,
 	getActiveDiscussions,
 	getAllCompleted,
 	getAllStarted,
 	getAllStartedOrCompleted,
 	getContentRows,
+	getLastInteractedOf,
 	getLessonContentRows,
 	getMonday,
 	getNewAndUpcoming,
+	getNextLesson,
 	getPracticeNotes,
 	getPracticeSessions,
 	getProgressDateByIds,

package/src/services/content-org/guided-courses.ts

@@ -40,7 +40,7 @@ export async function guidedCourses() {
   return await fetchHandler(url, 'GET')
 }
 
-export async function pinnedGuidedCourses() {
-  const url: string = `${BASE_PATH}/v1/user/guided-courses/pinned`
+export async function pinnedGuidedCourses(brand) {
+  const url: string = `${BASE_PATH}/v1/user/guided-courses/pinned?brand=${brand}`
   return await fetchHandler(url, 'GET')
 }

package/src/services/content.js

@@ -11,11 +11,12 @@ import {
   fetchUpcomingEvents,
   fetchScheduledReleases,
   fetchReturning,
-  fetchLeaving, fetchScheduledAndNewReleases
+  fetchLeaving, fetchScheduledAndNewReleases, fetchContentRows
 } from './sanity.js'
 import {TabResponseType, Tabs, capitalizeFirstLetter} from '../contentMetaData.js'
 import {fetchHandler} from "./railcontent";
-import {recommendations} from "./recommendations";
+import {recommendations, rankCategories} from "./recommendations";
+import {addContextToContent} from "./contentAggregator.js";
 
 
 export async function getLessonContentRows (brand='drumeo', pageName = 'lessons') {
@@ -149,11 +150,11 @@ export async function getRecent(brand, pageName, tabName = 'all', {
 }
 
 /**
- * Fetches content rows for a given brand and page with optional filtering by content row id.
+ * Fetches content rows for a given brand and page with optional filtering by content row slug.
  *
  * @param {string} brand - The brand for which to fetch content rows.
  * @param {string} pageName - The page name (e.g., 'lessons', 'songs', 'challenges').
- * @param {string} [contentRowId] - The specific content row ID to fetch.
+ * @param {string|null} contentRowSlug - The specific content row ID to fetch.
  * @param {Object} params - Parameters for pagination.
  * @param {number} [params.page=1] - The page number for pagination.
  * @param {number} [params.limit=10] - The maximum number of content items per row.
@@ -168,32 +169,48 @@ export async function getRecent(brand, pageName, tabName = 'all', {
  *   .then(content => console.log(content))
  *   .catch(error => console.error(error));
  */
-export async function getContentRows(brand, pageName, contentRowId , {
+export async function getContentRows(brand, pageName, contentRowSlug = null, {
   page = 1,
-  limit = 10,
+  limit = 10
 } = {}) {
-  const contentRow = contentRowId ? `&content_row_id=${contentRowId}` : ''
-  const url = `/api/content/v1/rows?brand=${brand}&page_name=${pageName}${contentRow}&page=${page}&limit=${limit}`;
-  const contentRows =  await fetchHandler(url, 'get', null) || [];
-  const results = await Promise.all(
-    contentRows.map(async (row) => {
-      if (row.content.length === 0){
-        return { id: row.id, title: row.title, items: [] }
-      }
-      const data = await fetchByRailContentIds(row.content)
-      return { id: row.id, title: row.title, items: data }
-    })
-  )
+  const sanityData = await addContextToContent(fetchContentRows, brand, pageName, contentRowSlug, {
+    dataField: 'content',
+    iterateDataFieldOnEachArrayElement: true,
+    addProgressStatus: true,
+    addProgressPercentage: true,
+    addNextLesson: true
+  })
+  if (!sanityData) {
+    return []
+  }
+  let contentMap = {}
+  let recData = {}
+  let slugNameMap = {}
+  for (const category of sanityData) {
+    recData[category.slug] = category.content.map(item => item.railcontent_id)
+    for (const content of category.content) {
+      contentMap[content.railcontent_id] = content
+    }
+    slugNameMap[category.slug] = category.name
+  }
+  const start = (page - 1) * limit
+  const end = start + limit
+  const sortedData = await rankCategories(brand, recData)
+  let finalData = []
+  for (const category of sortedData) {
+    finalData.push( {
+      id: category.slug,
+      title: slugNameMap[category.slug],
+      items: category.items.slice(start, end).map(id => contentMap[id])})
+  }
 
-  if (contentRowId) {
-    return {
+  return contentRowSlug ?
+    {
       type: TabResponseType.CATALOG,
-      data: results[0].items,
+      data: finalData[0].items,
       meta: {}
-    };
-  }
-
-  return results
+    }
+    : finalData
 }
 
 /**

package/src/services/contentAggregator.js

@@ -1,7 +1,12 @@
-import { getProgressStateByIds, getProgressPercentageByIds, getResumeTimeSecondsByIds } from "./contentProgress"
-import { isContentLikedByIds } from "./contentLikes"
-import { fetchLikeCount, fetchLastInteractedChild } from "./railcontent"
-
+import {
+  getLastInteractedOf,
+  getNextLesson,
+  getProgressPercentageByIds,
+  getProgressStateByIds,
+  getResumeTimeSecondsByIds
+} from "./contentProgress"
+import {isContentLikedByIds} from "./contentLikes"
+import {fetchLastInteractedChild, fetchLikeCount} from "./railcontent"
 
 
 export async function addContextToContent(dataPromise, ...dataArgs)
@@ -11,12 +16,15 @@ export async function addContextToContent(dataPromise, ...dataArgs)
 
   const {
     dataField = null,
+    iterateDataFieldOnEachArrayElement = false,
     addProgressPercentage = false,
     addIsLiked = false,
     addLikeCount = false,
     addProgressStatus = false,
     addResumeTimeSeconds = false,
     addLastInteractedChild = false,
+    addNextLesson = false,
+    addLastInteractedParent = false,
   } = options
 
   const dataParam = lastArg === options ? dataArgs.slice(0, -1) : dataArgs
@@ -24,26 +32,49 @@ export async function addContextToContent(dataPromise, ...dataArgs)
   const data = await dataPromise(...dataParam)
   if(!data) return false
 
-  let ids = []
+  let items = []
+  let dataMap = []
 
-  if (dataField && data?.[dataField]) {
-    ids = data[dataField].map(item => item?.id).filter(Boolean);
+  if (dataField && (data?.[dataField] || iterateDataFieldOnEachArrayElement)) {
+    if (iterateDataFieldOnEachArrayElement && Array.isArray(data)) {
+      for(const parent of data) {
+        ids = [...ids, ...parent[dataField].map(item => item?.id).filter(Boolean)]
+      }
+    } else {
+      ids = data[dataField].map(item => item?.id).filter(Boolean);
+    }
   } else if (Array.isArray(data)) {
-    ids = data.map(item => item?.id).filter(Boolean);
+    items = data;
   } else if (data?.id) {
-    ids = [data.id]
+    items = [data]
+  }
+
+  const ids = items.map(item => item?.id).filter(Boolean)
+
+  //create data structure for common use by functions
+  if (addNextLesson) {
+    items.forEach((item) => {
+      if (item?.id) {
+        dataMap.push({
+          'children': item.children?.map(child => child.id) ?? [],
+          'type': item.type,
+          'id': item.id,
+        })
+      }
+    })
   }
 
   if(ids.length === 0) return false
 
-  const [progressPercentageData, progressStatusData, isLikedData, resumeTimeData, lastInteractedChildData] = await Promise.all([
+  const [progressPercentageData, progressStatusData, isLikedData, resumeTimeData, lastInteractedChildData, nextLessonData] = await Promise.all([
     addProgressPercentage ? getProgressPercentageByIds(ids) : Promise.resolve(null),
     addProgressStatus ? getProgressStateByIds(ids) : Promise.resolve(null),
     addIsLiked ? isContentLikedByIds(ids) : Promise.resolve(null),
     addResumeTimeSeconds ? getResumeTimeSecondsByIds(ids) : Promise.resolve(null),
     addLastInteractedChild ? fetchLastInteractedChild(ids)  : Promise.resolve(null),
+    (addNextLesson || addLastInteractedParent) ? getNextLesson(dataMap) : Promise.resolve(null),
   ])
-  
+
   const addContext = async (item) => ({
     ...item,
     ...(addProgressPercentage ? { progressPercentage: progressPercentageData?.[item.id] } : {}),
@@ -52,12 +83,26 @@ export async function addContextToContent(dataPromise, ...dataArgs)
     ...(addLikeCount && ids.length === 1 ? { likeCount: await fetchLikeCount(item.id) } : {}),
     ...(addResumeTimeSeconds ? { resumeTime: resumeTimeData?.[item.id] } : {}),
     ...(addLastInteractedChild ? { lastInteractedChild: lastInteractedChildData?.[item.id] } : {}),
+    ...(addNextLesson ? { nextLesson: nextLessonData?.[item.id] } : {}),
   })
-  
+
+  if (addLastInteractedParent) {
+    const parentId = await getLastInteractedOf(ids);
+    data['nextLesson'] = nextLessonData[parentId];
+  }
+
   if (dataField) {
-    data[dataField] = Array.isArray(data[dataField])
+    if (iterateDataFieldOnEachArrayElement) {
+      for(let parent of data) {
+        parent[dataField] = Array.isArray(parent[dataField])
+          ? await Promise.all(parent[dataField].map(addContext))
+          : await addContext(parent[dataField])
+      }
+    } else {
+      data[dataField] = Array.isArray(data[dataField])
         ? await Promise.all(data[dataField].map(addContext))
         : await addContext(data[dataField])
+    }
     return data
   } else {
     return Array.isArray(data)

package/src/services/contentProgress.js

@@ -5,8 +5,9 @@ import {
   postRecordWatchSession,
 } from './railcontent.js'
 import { DataContext, ContentProgressVersionKey } from './dataContext.js'
-import { fetchHierarchy } from './sanity.js'
-import {recordUserPractice} from "./userActivity";
+import {fetchHierarchy} from './sanity.js'
+import {recordUserPractice, findIncompleteLesson} from "./userActivity";
+import {getNextLessonLessonParentTypes} from "../contentTypeConfig.js";
 
 const STATE_STARTED = 'started'
 const STATE_COMPLETED = 'completed'
@@ -14,10 +15,11 @@ const DATA_KEY_STATUS = 's'
 const DATA_KEY_PROGRESS = 'p'
 const DATA_KEY_RESUME_TIME = 't'
 const DATA_KEY_LAST_UPDATED_TIME = 'u'
+
 export let dataContext = new DataContext(ContentProgressVersionKey, fetchContentProgress)
 
 export async function getProgressPercentage(contentId) {
-  return getById(contentIds, DATA_KEY_PROGRESS, 0)
+  return getById(contentId, DATA_KEY_PROGRESS, 0)
 }
 
 export async function getProgressPercentageByIds(contentIds) {
@@ -40,6 +42,70 @@ export async function getResumeTimeSecondsByIds(contentIds) {
   return getByIds(contentIds, DATA_KEY_RESUME_TIME, 0)
 }
 
+export async function getNextLesson(dataMap)
+{
+  let nextLessonData = {}
+
+  for (const content of dataMap) {
+
+    //only calculate nextLesson if needed, based on content type
+    if (!getNextLessonLessonParentTypes.includes(content.type)) {
+      nextLessonData[content.id] = null
+
+    } else {
+      //return first child if parent-content is complete or no progress
+      const contentState = await getProgressState(content.id)
+      if (contentState !== STATE_STARTED) {
+        nextLessonData[content.id] = content.children[0]
+
+      } else {
+        //if content in progress
+
+        const childrenStates = await getProgressStateByIds(content.children)
+
+        //calculate last_engaged
+        const lastInteracted = await getLastInteractedOf(content.children)
+        const lastInteractedStatus = childrenStates[lastInteracted]
+
+        //different nextLesson behaviour for different content types
+        if (content.type === 'course' || content.type === 'pack-bundle') {
+          if (lastInteractedStatus === STATE_STARTED) {
+            nextLessonData[content.id] = lastInteracted
+          } else {
+            nextLessonData[content.id] = findIncompleteLesson(childrenStates, lastInteracted, content.type)
+          }
+
+        } else if (content.type === 'guided-course') {
+          nextLessonData[content.id] = findIncompleteLesson(childrenStates, lastInteracted, content.type)
+        }
+      }
+    }
+  }
+  return nextLessonData
+}
+
+/**
+ * filter through contents, only keeping the most recent
+ * @param {array} contentIds
+ * @returns {Promise<number>}
+ */
+export async function getLastInteractedOf(contentIds) {
+  const data = await getByIds(contentIds, DATA_KEY_LAST_UPDATED_TIME, 0)
+  const sorted = Object.keys(data)
+    .map(function (key) {
+      return parseInt(key)
+    })
+    .sort(function (a, b) {
+      let v1 = data[a]
+      let v2 = data[b]
+      if (v1 > v2) return -1
+      else if (v1 < v2) return 1
+      return 0
+    })
+
+  return sorted[0]
+}
+
 export async function getProgressDateByIds(contentIds) {
   let data = await dataContext.getData()
   let progress = {}

package/src/services/recommendations.js

@@ -80,11 +80,14 @@ export async function rankCategories(brand, categories) {
       globalConfig.recommendationsConfig.token
     )
     const response = await httpClient.post(url, data)
-    let rankedCategories = {}
-    response['ranked_playlists'].forEach(
-      (category) =>
-        (rankedCategories[category['playlist_id']] = categories[category['playlist_id']])
-    )
+    let rankedCategories = []
+
+    for (const rankedPlaylist of response['ranked_playlists']) {
+      rankedCategories.push({
+        'slug': rankedPlaylist.playlist_id,
+        'items': rankedPlaylist.ranked_items
+      })
+    }
     return rankedCategories
   } catch (error) {
     console.error('Fetch error:', error)

package/src/services/sanity.js

@@ -513,7 +513,7 @@ export async function fetchByRailContentId(id, contentType) {
  *   .catch(error => console.error(error));
  */
 export async function fetchByRailContentIds(ids, contentType = undefined, brand = undefined) {
-  if (!ids) {
+  if (!ids?.length) {
     return []
   }
   const idsString = ids.join(',')
@@ -540,6 +540,21 @@ export async function fetchByRailContentIds(ids, contentType = undefined, brand
   return sortedResults
 }
 
+export async function fetchContentRows(brand, pageName, contentRowSlug)
+{
+  if (pageName === 'lessons') pageName = 'lesson'
+  if (pageName === 'songs') pageName = 'song'
+  const rowString = contentRowSlug ? ` && slug.current == "${contentRowSlug.toLowerCase()}"` : ''
+  return fetchSanity(`*[_type == 'recommended-content-row' && brand == '${brand}' && type == '${pageName}'${rowString}]{
+    brand,
+    name,
+    'slug': slug.current,
+    'content': content[]->{ ${getFieldsForContentType()} }
+  }`, true)
+}
+
+
+
 /**
  * Fetch all content for a specific brand and type with pagination, search, and grouping options.
  * @param {string} brand - The brand for which to fetch content.
@@ -2356,9 +2371,11 @@ export async function fetchTabData(
 
   filter = `brand == "${brand}" ${includedFieldsFilter} ${progressFilter}`
   const childrenFilter = await new FilterBuilder(``, { isChildrenFilter: true }).buildFilter()
-  entityFieldsString = ` ${fieldsString},
-                                    'lesson_count': coalesce(count(child[${childrenFilter}]->), 0) ,
-                                    'length_in_seconds': coalesce(
+  entityFieldsString =
+    ` ${fieldsString},
+    'children': child[${childrenFilter}]->{'id': railcontent_id},
+    'lesson_count': coalesce(count(child[${childrenFilter}]->), 0),
+    'length_in_seconds': coalesce(
       math::sum(
         select(
           child[${childrenFilter}]->length_in_seconds

package/src/services/userActivity.js

@@ -8,16 +8,25 @@ import {
   fetchUserPracticeMeta,
   fetchUserPracticeNotes,
   fetchHandler,
-  fetchRecentUserActivities, fetchChallengeLessonData
+  fetchRecentUserActivities,
+  fetchChallengeLessonData,
+  fetchLastInteractedChild,
 } from './railcontent'
 import { DataContext, UserActivityVersionKey } from './dataContext.js'
 import { fetchByRailContentIds, fetchShows } from './sanity'
-import {fetchPlaylist, fetchUserPlaylists} from "./content-org/playlists";
+import {fetchPlaylist, fetchUserPlaylists} from "./content-org/playlists"
+import {pinnedGuidedCourses} from "./content-org/guided-courses"
 import {convertToTimeZone, getMonday, getWeekNumber, isSameDate, isNextDay, getTimeRemainingUntilLocal} from './dateUtils.js'
 import { globalConfig } from './config'
 import {collectionLessonTypes, lessonTypesMapping, progressTypesMapping, showsLessonTypes, songs} from "../contentTypeConfig";
-import {getAllStartedOrCompleted, getProgressStateByIds} from "./contentProgress";
+import {
+  getAllStartedOrCompleted,
+  getProgressPercentageByIds,
+  getProgressStateByIds,
+  getResumeTimeSecondsByIds
+} from "./contentProgress";
 import {TabResponseType} from "../contentMetaData";
+import {isContentLikedByIds} from "./contentLikes.js";
 
 const DATA_KEY_PRACTICES = 'practices'
 const DATA_KEY_LAST_UPDATED_TIME = 'u'
@@ -351,7 +360,7 @@ export async function removeUserPractice(id) {
         Object.keys(localContext.data[DATA_KEY_PRACTICES]).forEach((date) => {
           localContext.data[DATA_KEY_PRACTICES][date] = localContext.data[DATA_KEY_PRACTICES][
             date
-          ].filter((practice) => practice.id !== id)
+            ].filter((practice) => practice.id !== id)
         })
       }
     },
@@ -911,26 +920,45 @@ export async function getProgressRows({ brand = null, limit = 8 } = {}) {
     'learning-path-course',
     'learning-path-level'
   ]);
+  // TODO slice progress to a reasonable number, say 100
+  const [recentPlaylists, progressContents, allPinnedGuidedCourse, userPinnedItem ] = await Promise.all([
+    fetchUserPlaylists(brand, { sort: '-last_progress', limit: limit}),
+    getAllStartedOrCompleted({onlyIds: false, brand: brand }),
+    pinnedGuidedCourses(brand),
+    getUserPinnedItem(brand),
+  ])
+
+  let pinnedGuidedCourse = allPinnedGuidedCourse?.[0] ?? null
 
-  const recentPlaylists = await fetchUserPlaylists(brand, {
-    sort: '-last_progress',
-    limit: limit,
-  });
   const playlists = recentPlaylists?.data || [];
   const eligiblePlaylistItems = await getEligiblePlaylistItems(playlists);
   const playlistEngagedOnContents = eligiblePlaylistItems.map(item => item.last_engaged_on);
-  const playlistsContents = await fetchByRailContentIds(playlistEngagedOnContents, 'progress-tracker');
+
+  const nonPlaylistContentIds = Object.keys(progressContents)
+  if (pinnedGuidedCourse) {
+    nonPlaylistContentIds.push(pinnedGuidedCourse.content_id);
+  }
+  if (userPinnedItem?.progressType === 'content') {
+    nonPlaylistContentIds.push(userPinnedItem.id)
+  }
+  const [ playlistsContents, contents ] = await Promise.all([
+    fetchByRailContentIds(playlistEngagedOnContents, 'progress-tracker'),
+    fetchByRailContentIds(nonPlaylistContentIds, 'progress-tracker', brand),
+  ]);
+
   const excludedParents = new Set();
   const existingShows = new Set();
+  // TODO this doesn't work for guided courses as the GC card takes precedence over the playlist card
+  // https://musora.atlassian.net/browse/BEH-812
   for (const item of playlistsContents) {
+
     const contentId = item.id ?? item.railcontent_id;
-    excludedParents.add(contentId)
+    delete progressContents[contentId]
     const parentIds = item.parent_content_data || [];
-    parentIds.forEach(id => excludedParents.add(id));
+    parentIds.forEach(id => delete progressContents[id] );
   }
 
-  const progressContents = await getAllStartedOrCompleted({onlyIds: false, brand: brand, excludedIds: Array.from(excludedParents) });
-  const contents = await fetchByRailContentIds(Object.keys(progressContents), 'progress-tracker', brand);
+
   const contentsMap = {};
   contents.forEach(content => {
     contentsMap[content.railcontent_id] = content;
@@ -985,28 +1013,38 @@ export async function getProgressRows({ brand = null, limit = 8 } = {}) {
       }
     }
   }
-  const pinnedItem = await extractPinnedItem({
-    brand,
+  const pinnedItem = userPinnedItem ? await extractPinnedItem(
+    userPinnedItem,
     progressMap,
-    playlistItems: eligiblePlaylistItems,
-  })
-  const progressList = Array.from(progressMap.values())
+    eligiblePlaylistItems,
+  ) : null
+
+  const pinnedId = pinnedItem?.id
+  const guidedCourseID = pinnedGuidedCourse?.content_id
+  let combined = [];
+  if (pinnedGuidedCourse) {
+    const guidedCourseContent = contentsMap[guidedCourseID]
+    if (guidedCourseContent) {
+      const temp = await extractPinnedGuidedCourseItem(guidedCourseContent, progressMap)
+      temp.pinned = true
+      combined.push(temp)
+    }
+  }
   if (pinnedItem) {
     pinnedItem.pinned = true
+    combined.push(pinnedItem)
   }
+  const progressList = Array.from(progressMap.values())
 
-  const pinnedId = pinnedItem?.id
   const filteredProgressList = pinnedId
-    ? progressList.filter(item => item.id !== pinnedId)
+    ? progressList.filter(item => !(item.id === pinnedId || item.id === guidedCourseID))
     : progressList;
   const filteredPlaylists = pinnedId
-    ? eligiblePlaylistItems.filter(item => item.id !== pinnedId)
+    ? (eligiblePlaylistItems.filter(item => !(item.id === pinnedId || item.id === guidedCourseID)))
     : eligiblePlaylistItems;
-  const combinedBase = [...filteredProgressList, ...filteredPlaylists]
-  const combined = pinnedItem ? [pinnedItem, ...combinedBase] : combinedBase
 
+  combined = [...combined, ...filteredProgressList, ...filteredPlaylists]
   const finalCombined = mergeAndSortItems(combined, limit)
-
   const results = await Promise.all(
     finalCombined.slice(0, limit).map(item =>
       item.type === 'playlist'
@@ -1022,11 +1060,17 @@ export async function getProgressRows({ brand = null, limit = 8 } = {}) {
   };
 }
 
+async function getUserPinnedItem(brand) {
+  const userRaw = await globalConfig.localStorage.getItem('user');
+  const user = userRaw ? JSON.parse(userRaw) : {};
+  user.brand_pinned_progress = user.brand_pinned_progress || {}
+  return user.brand_pinned_progress[brand] ?? null
+}
+
 async function processContentItem(item) {
   let data = item.raw;
   const contentType = getFormattedType(data.type, data.brand);
   const status = item.state;
-
   let ctaText = 'Continue';
   if (contentType === 'transcription' || contentType === 'play-along' || contentType === 'jam-track') ctaText = 'Replay Song';
   if (contentType === 'lesson') ctaText = status === 'completed' ? 'Revisit Lesson' : 'Continue';
@@ -1064,6 +1108,29 @@ async function processContentItem(item) {
       const nextLesson = lessons.find(lesson => lesson.id === nextId)
       data.first_incomplete_child = nextLesson?.parent ?? nextLesson
       data.second_incomplete_child = (nextLesson?.parent) ? nextLesson : null
+      if(data.type === 'guided-course'){
+        let isLocked = new Date(nextLesson.published_on) > new Date()
+        data.thumbnail = nextLesson.thumbnail
+        // USHP-4 completed
+        if (status === 'completed') {
+          // duplicated code to above, but here for clarity
+          ctaText = 'Revisit Lessons'
+        // USHP-1 if lesson locked show unlock in X time
+        } else if (isLocked) {
+          data.is_locked = true
+          const timeRemaining = getTimeRemainingUntilLocal(nextLesson.published_on, {withTotalSeconds: true})
+          data.time_remaining_seconds = timeRemaining.totalSeconds
+          ctaText = 'Next lesson in ' + timeRemaining.formatted
+        }
+        // USHP-2 start course if not started
+        else if (status === 'not-started') {
+          ctaText = "Start Course"
+        }
+        // USHP-3 in progress for lesson
+        else {
+          ctaText = "Continue"
+        }
+      }
     }
   }
 
@@ -1079,7 +1146,7 @@ async function processContentItem(item) {
     data.completed_children = completedCount;
     data.child_count = shows.length;
     item.percent = Math.round((completedCount / shows.length) * 100);
-    if(completedCount == shows.length) {
+    if(completedCount === shows.length) {
       ctaText = 'Revisit Lessons';
     }
   }
@@ -1096,8 +1163,8 @@ async function processContentItem(item) {
       badge:           data.badge ?? null,
       isLocked:        data.is_locked ?? false,
       subtitle:        !data.child_count || data.lesson_count === 1
-                         ? (contentType === 'lesson') ? `${item.percent}% Complete`: `${data.difficulty_string} • ${data.artist_name}`
-                         : `${data.completed_children} of ${data.lesson_count ?? data.child_count} Lessons Complete`
+        ? (contentType === 'lesson') ? `${item.percent}% Complete`: `${data.difficulty_string} • ${data.artist_name}`
+        : `${data.completed_children} of ${data.lesson_count ?? data.child_count} Lessons Complete`
     },
     cta:               {
       text:   ctaText,
@@ -1108,21 +1175,21 @@ async function processContentItem(item) {
         id:    data.id,
         slug:  data.slug,
         child: data.first_incomplete_child
-                 ? {
+          ? {
             id:    data.first_incomplete_child.id,
             type:  data.first_incomplete_child.type,
             brand: data.first_incomplete_child.brand,
             slug:  data.first_incomplete_child.slug,
             child: data.second_incomplete_child
-                     ? {
+              ? {
                 id:    data.second_incomplete_child.id,
                 type:  data.second_incomplete_child.type,
                 brand: data.second_incomplete_child.brand,
                 slug:  data.second_incomplete_child.slug
               }
-                     : null
+              : null
           }
-                 : null
+          : null
       }
     },
     progressTimestamp: item.progressTimestamp
@@ -1234,12 +1301,13 @@ function mergeAndSortItems(items, limit) {
     .sort((a, b) => {
       if (a.pinned && !b.pinned) return -1;
       if (!a.pinned && b.pinned) return 1;
+      // TODO guided course should always be before user pinned item
       return b.progressTimestamp - a.progressTimestamp;
     })
     .slice(0, limit + 5);
 }
 
-function findIncompleteLesson(progressOnItems, currentContentId, contentType) {
+export function findIncompleteLesson(progressOnItems, currentContentId, contentType) {
   const ids = Object.keys(progressOnItems).map(Number);
   if (contentType === 'guided-course') {
     // Return first incomplete lesson
@@ -1274,11 +1342,10 @@ function findIncompleteLesson(progressOnItems, currentContentId, contentType) {
  *   .catch(error => console.error(error));
  */
 export async function pinProgressRow(brand, id, progressType) {
-  if (!(brand && id && progressType)) throw new Error(`undefined parameter progressType: ${progressType} brand: ${brand} or id: ${id}`)
   const url = `/api/user-management-system/v1/progress/pin?brand=${brand}&id=${id}&progressType=${progressType}`;
   const response = await fetchHandler(url, 'PUT', null)
-  if (response && !response.error && response['action'] === 'update_user_pin') {
-    await updateUserPinnedProgressRow(brand, {
+  if (response && !response.error) {
+    await updatePinnedProgressRow(brand, {
       id,
       progressType,
       pinnedAt: new Date().toISOString(),
@@ -1290,25 +1357,23 @@ export async function pinProgressRow(brand, id, progressType) {
  * Unpins the current pinned progress row for a user, scoped by brand.
  *
  * @param {string} brand - The brand context for the unpin action.
- * @param {string} id - The content or playlist id to unpin.
  * @returns {Promise<Object>} - A promise resolving to the response from the unpin API.
  *
  * @example
- * unpinProgressRow('drumeo', 123456)
+ * unpinProgressRow('drumeo')
  *   .then(response => console.log(response))
  *   .catch(error => console.error(error));
  */
-export async function unpinProgressRow(brand, id) {
-  if (!(brand && id)) throw new Error(`undefined parameter brand: ${brand} or id: ${id}`)
-  const url = `/api/user-management-system/v1/progress/unpin?brand=${brand}&id=${id}`
+export async function unpinProgressRow(brand) {
+  const url = `/api/user-management-system/v1/progress/unpin?brand=${brand}`
   const response = await fetchHandler(url, 'PUT', null)
-  if (response && !response.error && response['action'] === 'clear_user_pin') {
-    await updateUserPinnedProgressRow(brand, null)
+  if (response && !response.error) {
+    await updatePinnedProgressRow(brand, null)
   }
   return response
 }
 
-async function updateUserPinnedProgressRow(brand, pinnedData) {
+async function updatePinnedProgressRow(brand, pinnedData) {
   const userRaw = await globalConfig.localStorage.getItem('user');
   const user = userRaw ? JSON.parse(userRaw) : {};
   user.brand_pinned_progress = user.brand_pinned_progress || {}
@@ -1316,14 +1381,7 @@ async function updateUserPinnedProgressRow(brand, pinnedData) {
   await globalConfig.localStorage.setItem('user', JSON.stringify(user))
 }
 
-async function extractPinnedItem({brand, progressMap, playlistItems}) {
-  const userRaw = await globalConfig.localStorage.getItem('user');
-  const user = userRaw ? JSON.parse(userRaw) : {};
-  user.brand_pinned_progress = user.brand_pinned_progress || {}
-
-  const pinned = user.brand_pinned_progress[brand]
-  if (!pinned) return null
-
+async function extractPinnedItem(pinned, progressMap, playlistItems) {
   const {id, progressType, pinnedAt} = pinned
 
   if (progressType === 'content') {
@@ -1356,7 +1414,7 @@ async function extractPinnedItem({brand, progressMap, playlistItems}) {
         raw:     playlist,
         progressTimestamp: new Date(pinnedAt).getTime(),
         type: 'playlist',
-        last_engaged_on: playlist.items[0],
+        last_engaged_on: playlist.last_engaged_on,
       }
     }
   }
@@ -1364,6 +1422,35 @@ async function extractPinnedItem({brand, progressMap, playlistItems}) {
   return null
 }
 
+async function extractPinnedGuidedCourseItem(guidedCourse, progressMap) {
+  const children = guidedCourse.lessons.map(child => child.id)
+  let existingGuidedCourseProgress = null
+  if (progressMap.has(guidedCourse.id)) {
+    existingGuidedCourseProgress = progressMap.get(guidedCourse.id)
+    progressMap.delete(guidedCourse.id)
+  }
+  let lastChild = null
+  children.forEach(child => {
+    if (progressMap.has(child)) {
+      let childProgress = progressMap.get(child)
+      if (!lastChild && childProgress.state !== 'completed') {
+        lastChild = childProgress
+        lastChild.id = child
+      }
+      progressMap.delete(child)
+    }
+  })
+  return existingGuidedCourseProgress ?? {
+    id: guidedCourse.id,
+    state: 'not-started',
+    percent: 0,
+    raw: guidedCourse,
+    pinned: true,
+    progressTimestamp: new Date().getTime(),
+    childIndex: guidedCourse.id,
+  }
+}
+
 function getFirstLeafLessonId(data) {
   function findFirstLeaf(lessons) {
     for (const item of lessons) {
@@ -1380,4 +1467,3 @@ function getFirstLeafLessonId(data) {
 }
 
 
-