musora-content-services 2.157.0 → 2.158.0

package/.claude/settings.local.json

@@ -0,0 +1,22 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(tree:*)",
+      "Bash(find:*)",
+      "Bash(docker exec:*)",
+      "Bash(node:*)",
+      "Bash(npm run build-index:*)",
+      "Bash(npm run link_mcs:*)",
+      "Bash(./link_mcs.sh:*)",
+      "Bash(curl:*)",
+      "Bash(php artisan:*)",
+      "Bash(git checkout:*)",
+      "Bash(source .env)",
+      "Bash(echo:*)",
+      "Bash(grep:*)",
+      "Bash(gh api repos/railroadmedia/musora-platform-backend/commits/1f9878a5e681bf1e2233c0d59a618d477b118c49 --jq '.commit.message' 2>/dev/null || echo \"no access\")",
+      "WebFetch(domain:github.com)",
+      "Read(//app/**)"
+    ]
+  }
+}

package/.github/workflows/docs.js.yml

@@ -31,7 +31,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '24'
 
       - name: Install dependencies for v2
         working-directory: main-content

package/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 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.158.0](https://github.com/railroadmedia/musora-content-services/compare/v2.153.0...v2.158.0) (2026-05-05)
+
+
+### Features
+
+* **BEHLTP-23:** add multi-user account update endpoint ([#914](https://github.com/railroadmedia/musora-content-services/issues/914)) ([98f6c4b](https://github.com/railroadmedia/musora-content-services/commit/98f6c4bb830c7a8a25ba556ca07fc97023667011))
+* **BEHSTP-167:** offline progress tracking support ([#889](https://github.com/railroadmedia/musora-content-services/issues/889)) ([0528597](https://github.com/railroadmedia/musora-content-services/commit/05285977237ccbfa577a5770a1762c31d855e59e))
+* handle late-start active paths, and set up better resetAllLearningPaths ([#928](https://github.com/railroadmedia/musora-content-services/issues/928)) ([5d80430](https://github.com/railroadmedia/musora-content-services/commit/5d80430fbedfb21668882d402c5f6b07c82cfbf9))
+* **MU2-1384:** enable related lessons for non-members ([#943](https://github.com/railroadmedia/musora-content-services/issues/943)) ([f091bd7](https://github.com/railroadmedia/musora-content-services/commit/f091bd7e7edfcfe8808684d97faff22f62ef6fe0))
+* **MU2-1452:** free tier content sort to front ([#915](https://github.com/railroadmedia/musora-content-services/issues/915)) ([0655e68](https://github.com/railroadmedia/musora-content-services/commit/0655e685f32fe77728d7b8c2505283adbc1a7c97))
+* **MU2-1463:** initialize onboarding flow ([#929](https://github.com/railroadmedia/musora-content-services/issues/929)) ([4daae5f](https://github.com/railroadmedia/musora-content-services/commit/4daae5ff28599b53fa9ee5b9bea8bdb08b706978))
+* muppet - add invite validity/error data ([#923](https://github.com/railroadmedia/musora-content-services/issues/923)) ([3938fa5](https://github.com/railroadmedia/musora-content-services/commit/3938fa56ec9295023b6ba624c5f238d1645a911b))
+
+
+### Bug Fixes
+
+* add missing vimeo_live_event_id field to downloads field list ([#948](https://github.com/railroadmedia/musora-content-services/issues/948)) ([2b54208](https://github.com/railroadmedia/musora-content-services/commit/2b5420838f200ee061dc7af27029df8a3c38f87c))
+* add typeof before LokiJSAdapter in parameter list ([6a135b5](https://github.com/railroadmedia/musora-content-services/commit/6a135b57c516c277a50d707417544ab2f9eeb194))
+* **BEHSTP-160:** hide future content in related lessons ([#952](https://github.com/railroadmedia/musora-content-services/issues/952)) ([b8d5e06](https://github.com/railroadmedia/musora-content-services/commit/b8d5e0662fae47285978ed1c2d641cc514f25ecd))
+* **BR-460:** report option label updates ([#940](https://github.com/railroadmedia/musora-content-services/issues/940)) ([8ad8f72](https://github.com/railroadmedia/musora-content-services/commit/8ad8f72dd9a1284b4098aa00f08962a53a170275))
+* **BR-627:** add pagination support to fetch followed threads method ([779e308](https://github.com/railroadmedia/musora-content-services/commit/779e30881e76b17e17124852c4d2ee02d62ccf87))
+* **BR-632:** dont trickle progress to children when enrolling in GC ([#916](https://github.com/railroadmedia/musora-content-services/issues/916)) ([67a96d6](https://github.com/railroadmedia/musora-content-services/commit/67a96d69bd8b61f12d0efd45475a7b0b08c58813))
+* **BR-659:** fix resources for null parents ([#951](https://github.com/railroadmedia/musora-content-services/issues/951)) ([b78157b](https://github.com/railroadmedia/musora-content-services/commit/b78157b9dbb9f4d8861bca9546eab79a1c04c01e))
+* export ([#936](https://github.com/railroadmedia/musora-content-services/issues/936)) ([16b78be](https://github.com/railroadmedia/musora-content-services/commit/16b78be3dca3cee8981f1347a37f1b1b00ffe691))
+* remove prevSession args ([#937](https://github.com/railroadmedia/musora-content-services/issues/937)) ([2fe1dc2](https://github.com/railroadmedia/musora-content-services/commit/2fe1dc280a21e060b15567afe60a4cf959cecc90))
+* remove timestamp filtering of practice records in offline mode ([#938](https://github.com/railroadmedia/musora-content-services/issues/938)) ([1a8ac03](https://github.com/railroadmedia/musora-content-services/commit/1a8ac03bfa1b9b3670c45049adb9b833263ef871))
+* revert activity timestamp changes ([#942](https://github.com/railroadmedia/musora-content-services/issues/942)) ([bd9f97d](https://github.com/railroadmedia/musora-content-services/commit/bd9f97d6547409b7f2856bf716c90d6723306c36))
+* **TMA-239:** MCS - Sanity - Add a v=2 query parameter to all sanity requests to force a cache refresh ([#933](https://github.com/railroadmedia/musora-content-services/issues/933)) ([eac5a2c](https://github.com/railroadmedia/musora-content-services/commit/eac5a2c6848aee80c462ba0ccbeba52a92652fa9))
+* **TMA-275:** MCS - Sanity - Add a v2 url segment to to all sanity requests to force a cache refresh ([#946](https://github.com/railroadmedia/musora-content-services/issues/946)) ([b5df1dc](https://github.com/railroadmedia/musora-content-services/commit/b5df1dc943cc9d477dcac5879daaf0725fa60f76))
+
+### [2.157.2](https://github.com/railroadmedia/musora-content-services/compare/v2.157.0...v2.157.2) (2026-04-30)
+
+
+### Bug Fixes
+
+* add missing vimeo_live_event_id field to downloads field list ([#948](https://github.com/railroadmedia/musora-content-services/issues/948)) ([2b54208](https://github.com/railroadmedia/musora-content-services/commit/2b5420838f200ee061dc7af27029df8a3c38f87c))
+
+### [2.157.1](https://github.com/railroadmedia/musora-content-services/compare/v2.157.0...v2.157.1) (2026-04-30)
+
+
+### Bug Fixes
+
+* add missing vimeo_live_event_id field to downloads field list ([#948](https://github.com/railroadmedia/musora-content-services/issues/948)) ([2b54208](https://github.com/railroadmedia/musora-content-services/commit/2b5420838f200ee061dc7af27029df8a3c38f87c))
+
 ## [2.157.0](https://github.com/railroadmedia/musora-content-services/compare/v2.155.11...v2.157.0) (2026-04-29)
 
 

package/jest.live.config.js

@@ -0,0 +1,10 @@
+/** @type {import('jest').Config} */
+import baseConfig from './jest.config.js'
+
+export default {
+  ...baseConfig,
+  modulePathIgnorePatterns: [],
+  setupFilesAfterEnv: ['dotenv/config'],
+  testTimeout: 1000000,
+  collectCoverage: false,
+}

package/package.json

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

package/src/contentTypeConfig.js

@@ -116,7 +116,7 @@ export const descriptionField = 'description[0].children[0].text'
 // this pulls both any defined resources for the document as well as any resources in the parent document
 export const resourcesField = `[
           ... resource[]{resource_name, _key, "resource_url": coalesce('${CloudFrontURl}'+string::split(resource_aws.asset->fileURL, '${AWSUrl}')[1], resource_url )},
-          ... coalesce(parent_content_reference[]->resource[]{resource_name, _key, "resource_url": coalesce('${CloudFrontURl}'+string::split(resource_aws.asset->fileURL, '${AWSUrl}')[1], resource_url )}, []),
+          ... coalesce(parent_content_reference[count(@->resource) > 0]->resource[]{resource_name, _key, "resource_url": coalesce('${CloudFrontURl}'+string::split(resource_aws.asset->fileURL, '${AWSUrl}')[1], resource_url )}, []),
           ]`
 
 export const contentAwardField = "*[references(^._id) && _type == 'content-award'][0]"
@@ -149,6 +149,7 @@ export function getLiveFields(minimum = false) {
     "live_event_start_time",
     "live_event_end_time",
     "live_event_stream_id",
+    "vimeo_live_event_id",
     "'live_event_is_global': live_global_event == true",
     "'videoId': coalesce(live_event_stream_id, video.external_id)",
   ]

package/src/index.d.ts

@@ -153,6 +153,10 @@ import {
 	toLocalDay
 } from './services/dateUtils.js';
 
+import {
+	getEndScreen
+} from './services/endScreen/endScreen.ts';
+
 import {
 	createForumCategory,
 	deleteForumCategory,
@@ -667,6 +671,7 @@ declare module 'musora-content-services' {
 		getContentAwardsByIds,
 		getContentRows,
 		getDailySession,
+		getEndScreen,
 		getEnrichedLearningPath,
 		getEnrichedLearningPaths,
 		getHierarchies,

package/src/index.js

@@ -157,6 +157,10 @@ import {
 	toLocalDay
 } from './services/dateUtils.js';
 
+import {
+	getEndScreen
+} from './services/endScreen/endScreen.ts';
+
 import {
 	createForumCategory,
 	deleteForumCategory,
@@ -666,6 +670,7 @@ export {
 	getContentAwardsByIds,
 	getContentRows,
 	getDailySession,
+	getEndScreen,
 	getEnrichedLearningPath,
 	getEnrichedLearningPaths,
 	getHierarchies,

package/src/services/endScreen/README.md

@@ -0,0 +1,62 @@
+# End Screen Service
+
+Determines what content to show after a user finishes a lesson.
+
+## Functions
+
+| Function | Type | Use case |
+|---|---|---|
+| `getEndScreen(params)` | async | All content types — lessons, courses, playlists |
+
+---
+
+## Decision Logic
+
+### `getEndScreen`
+
+```
+single-song / play-along / jam →  countdown-up-next  +  RecSys recommendation
+playlist (not last item)       →  countdown-up-next  +  next item
+playlist (last item)           →  null
+no course                      →  countdown-up-next  +  RecSys recommendation
+course (not last lesson)       →  countdown-up-next  +  next lesson
+course (last, has next course) →  course-complete    +  first lesson of next course
+course (last, no next course)  →  course-complete    +  RecSys recommendation
+```
+
+RecSys fallback: if the recommender returns nothing → related lesson (standalone) or related course (course-complete)
+
+
+## API Reference
+
+### `getEndScreen(params): Promise<EndScreenResult>`
+
+```typescript
+// Parameters
+{
+  lesson:      { id: number, type?: string }          // required
+  brand:       string                                  // required
+  course?:     { id: number, children?: ContentItem[] }
+  collection?: { id: number, type: string, children?: { id: number, children?: ContentItem[] }[] }
+  playlist?:   { id: number, items?: ContentItem[] }
+  user_playlist_item_index?: number  // current item's index in playlist; skips findIndex lookup when provided
+}
+
+// Return value
+{
+  variant:           'countdown-up-next' | 'course-complete'
+  upNext:            object | null   // null if RecSys and related content both return nothing
+  countdownAutoplay: boolean
+  ctaLabels:         { primary: string, secondary: string }
+}
+```
+
+---
+
+## Implementation
+
+### When to call
+
+Call `getEndScreen` **at page load**, not when the video ends. RecSys calls happen in the background while the user watches — by the time the video ends, the result is ready.
+
+

package/src/services/endScreen/endScreen.ts

@@ -0,0 +1,153 @@
+import {fetchSimilarItems} from '../recommendations.js'
+import {fetchByRailContentIds, fetchCourseCollectionData, fetchRelatedLessons} from '../sanity.js'
+import { addContextToContent } from '../contentAggregator.js'
+import { playAlongLessonTypes, jamTrackLessonTypes, lessonTypesMapping } from '../../contentTypeConfig.js'
+import {getUserData} from "../user/management.js";
+import type {
+  ContentItem,
+  Collection,
+  Course,
+  Playlist,
+  CtaLabels,
+  EndScreenResult,
+  GetEndScreenParams,
+} from './types.ts'
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+const SINGLE_SONG_LESSON_TYPES: string[] = [
+  ...playAlongLessonTypes,
+  ...jamTrackLessonTypes,
+  ...lessonTypesMapping['single lessons'],
+]
+const COURSE_COMPLETE_CTA: CtaLabels = { primary: 'Play Now', secondary: 'Back to Home'}
+const COUNTDOWN_CTA: CtaLabels = { primary: 'Play Now' }
+const COUNTDOWN_CTA_REPLAY: CtaLabels = { primary: 'Play Now', secondary: 'Replay' }
+
+export async function getEndScreen({
+  lesson,
+  course = null,
+  collection = null,
+  playlist = null,
+  user_playlist_item_index = null,
+  next_item = null,
+  brand
+}: GetEndScreenParams): Promise<EndScreenResult> {
+  const userData = await getUserData()
+  const isAdmin = userData?.is_admin ?? false
+
+  if (playlist) {
+    const nextItem = next_item ??
+      getNextItemInPlaylistOrNull(lesson.id, playlist, user_playlist_item_index, isAdmin)
+
+    return nextItem ? buildCountdown(nextItem, false) : null
+  }
+
+  if (SINGLE_SONG_LESSON_TYPES.includes(lesson.type ?? '')) {
+    return buildCountdown(await fetchEndScreenRecommendation(brand, lesson.id, null, isAdmin), true)
+  }
+
+  if (!course) {
+    return buildCountdown(await fetchEndScreenRecommendation(brand, lesson.id, null, isAdmin), false)
+  }
+
+  const nextLesson = getNextLessonOrNull(lesson.id, course, isAdmin)
+  if (nextLesson) {
+    return buildCountdown(nextLesson, false)
+  }
+
+  // TODO: remove internal fetch if FE provides collection.children directly
+  // collection.vue fetches lessonsInCourse (course children) but not the parent collection's courses
+  const resolvedCollection: Collection | null =
+    collection?.type === 'course' && collection?.parent_id
+      ? await fetchCourseCollectionData(collection.parent_id)
+      : collection
+
+  const nextCourseFirstLesson = getFirstLessonOfNextCourseOrNull(course.id, resolvedCollection, isAdmin)
+  if (nextCourseFirstLesson) {
+    return buildCourseComplete(nextCourseFirstLesson)
+  }
+
+  return buildCourseComplete(await fetchEndScreenRecommendation(brand, lesson.id, course.id, isAdmin))
+}
+
+// ─── Builders ─────────────────────────────────────────────────────────────────
+
+function buildCountdown(upNext: any, withReply: boolean): EndScreenResult {
+  return { variant: 'countdown-up-next', upNext, countdownAutoplay: true, ctaLabels: withReply ? COUNTDOWN_CTA_REPLAY : COUNTDOWN_CTA }
+}
+
+function buildCourseComplete(upNext: any): EndScreenResult {
+  return { variant: 'course-complete', upNext, countdownAutoplay: false, ctaLabels: COURSE_COMPLETE_CTA }
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function getNextItemInPlaylistOrNull(contentId: number, playlist: Playlist, user_playlist_item_index: number|null, isAdmin: boolean): ContentItem | null {
+  const items = playlist.items ?? []
+  const index = user_playlist_item_index !== null ? user_playlist_item_index : items.findIndex((item) => Number(item.id) === Number(contentId))
+  if (index < 0 || index === items.length - 1) return null
+  return items.slice(index + 1).find(item => isReleasedContent(item, isAdmin)) ?? null
+}
+
+function getNextLessonOrNull(lessonId: number, course: Course, isAdmin: boolean): ContentItem | null {
+  const children = course.children ?? []
+  const index = children.findIndex((child) => Number(child.id) === Number(lessonId))
+  if (index < 0 || index === children.length - 1) return null
+  return children.slice(index + 1).find(child => isReleasedContent(child, isAdmin)) ?? null
+}
+
+function isReleasedContent(content: ContentItem, isAdmin: boolean): boolean {
+  if (isAdmin) return true
+  if (!content?.status) return false
+  return (content.status === 'published') && !content.need_access
+}
+
+function getFirstLessonOfNextCourseOrNull(
+  courseId: number,
+  collection: Collection | null,
+  isAdmin: boolean
+): ContentItem | null {
+  if (!collection) return null
+  const courses = collection.children ?? []
+  const index = courses.findIndex((course) => Number(course.id) === Number(courseId))
+  if (index < 0 || index === courses.length - 1) return null
+  const nextCourse = courses.slice(index + 1).find(course => isReleasedContent(course, isAdmin))
+  if (!nextCourse?.children) return null
+  return nextCourse.children.find(lesson => isReleasedContent(lesson, isAdmin)) ?? null
+}
+
+async function fetchEndScreenRecommendation(
+  brand: string,
+  contentId: number,
+  parentId: number | null = null,
+  isAdmin: boolean
+): Promise<any | null> {
+  try {
+    let recData: number[] = await fetchSimilarItems(contentId, brand, 20)
+    const contents: ContentItem[] = recData.length > 0 ? await fetchByRailContentIds(recData) : []
+    let recommended =
+      contents?.find((c) => isReleasedContent(c, isAdmin) && c.id !== parentId && (!c.parent_id || c.parent_id !== parentId)) ??
+      contents?.find((c) => isReleasedContent(c, isAdmin) && c.id !== parentId) ??
+      null
+
+    if (!recommended) {
+      const relatedLesson = await fetchRelatedLessons(parentId ?? contentId).then((r) =>
+        r.related_lessons?.[0] ?? null
+      )
+      recommended = isReleasedContent(relatedLesson, isAdmin) ? relatedLesson : null
+    }
+
+    if (!recommended) {
+      return null
+    }
+
+    return await addContextToContent(() => recommended, {
+      addProgressPercentage: true,
+      addProgressStatus: true,
+      addNavigateTo: true,
+    })
+  } catch {
+    return null
+  }
+}

package/src/services/endScreen/types.ts

@@ -0,0 +1,63 @@
+/**
+ * @module EndScreen Types
+ */
+
+export type EndScreenVariant =
+  | 'countdown-up-next'
+  | 'course-complete'
+
+export interface CtaLabels {
+  primary: string
+  secondary?: string
+}
+
+export interface EndScreenResult {
+  variant: EndScreenVariant
+  upNext: object | null
+  countdownAutoplay: boolean
+  ctaLabels: CtaLabels
+}
+
+export interface ContentItem {
+  id: number
+  type?: string
+  status?: string
+  parent_id?: number
+  need_access?: boolean
+}
+
+export interface Course {
+  id: number
+  type?: string
+  status?: string
+  children?: ContentItem[]
+}
+
+export interface CourseInCollection {
+  id: number
+  status?: string
+  children?: ContentItem[]
+}
+
+export interface Collection {
+  id: number
+  type: string
+  status?: string
+  parent_id?: number
+  children?: CourseInCollection[]
+}
+
+export interface Playlist {
+  id: number
+  items?: ContentItem[]
+}
+
+export interface GetEndScreenParams {
+  lesson: ContentItem
+  course?: Course | null
+  collection?: Collection | null
+  playlist?: Playlist | null
+  user_playlist_item_index?: number | null
+  next_item?: any | null
+  brand: string
+}

package/src/services/forums/threads.ts

@@ -184,18 +184,29 @@ export async function unlockThread(threadId: number, brand: string): Promise<voi
   return httpClient.delete<void>(`${baseUrl}/v1/threads/${threadId}/lock?brand=${brand}`)
 }
 
+export interface FetchFollowedThreadsParams {
+  page?: number,
+  limit?: number,
+}
+
 /**
  * Fetches followed forum Threads for the given brand and current user.
  *
  * @param {string} brand - The brand context (e.g., "drumeo", "singeo").
+ * @param {FetchFollowedThreadsParams} params - Optional pagination parameters.
  * @returns {Promise<PaginatedResponse<ForumThread>>} - A promise that resolves to the list of forum threads.
  * @throws {HttpError} - If the request fails.
  */
 export async function fetchFollowedThreads(
-  brand: string
+  brand: string,
+  params: FetchFollowedThreadsParams = {}
 ): Promise<PaginatedResponse<ForumThread>> {
   const httpClient = new HttpClient(globalConfig.baseUrl)
-  return httpClient.get<PaginatedResponse<ForumThread>>(`${baseUrl}/v1/threads?brand=${brand}`)
+  const queryObj: Record<string, string> = { brand, ...Object.fromEntries(
+      Object.entries(params).filter(([_, v]) => v !== undefined && v !== null).map(([k, v]) => [k, String(v)])
+    )}
+  const query = new URLSearchParams(queryObj).toString()
+  return httpClient.get<PaginatedResponse<ForumThread>>(`${baseUrl}/v1/threads?${query}`)
 }
 
 export interface FetchLatestThreadParams {