musora-content-services 2.31.2 → 2.33.0

package/jsdoc.json

@@ -12,9 +12,19 @@
       "src/services/railcontent.js",
       "src/index.js"
     ],
-    "includePattern": ".js$",
+    "includePattern": "(.js|.ts$)",
     "excludePattern": "(node_modules/|docs)"
   },
+  "plugins": [
+    "node_modules/jsdoc-babel"
+  ],
+  "babel": {
+    "extensions": ["ts"],
+    "ignore": ["**/*.(test|spec).ts"],
+    "babelrc": false,
+    "presets": [["@babel/preset-env", { "targets": { "node": true } }], "@babel/preset-typescript"],
+    "plugins": ["@babel/plugin-transform-class-properties", "@babel/plugin-transform-object-rest-spread"]
+  },
   "opts": {
     "destination": "./docs",
     "recurse": true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "musora-content-services",
-  "version": "2.31.2",
+  "version": "2.33.0",
   "description": "A package for Musoras content services ",
   "main": "src/index.js",
   "type": "module",
@@ -21,9 +21,13 @@
   },
   "homepage": "https://github.com/railroadmedia/musora-content-services#readme",
   "devDependencies": {
+    "@babel/plugin-transform-class-properties": "^7.27.1",
+    "@babel/plugin-transform-object-rest-spread": "^7.28.0",
+    "@babel/preset-typescript": "^7.27.1",
     "dotenv": "^16.4.5",
     "jest": "^29.7.0",
     "jsdoc": "^4.0.3",
+    "jsdoc-babel": "^0.5.0",
     "prettier": "3.4.2",
     "standard-version": "^9.5.0",
     "ts-jest": "^29.2.4"

package/src/contentTypeConfig.js

@@ -9,12 +9,17 @@ export const SONG_TYPES = ['song', 'play-along', 'jam-track', 'song-tutorial-chi
 // Single hierarchy refers to only one element in the hierarchy has video lessons, not that they have a single parent
 export const SINGLE_PARENT_TYPES = ['course-part', 'pack-bundle-lesson', 'song-tutorial-children']
 
+export const artistField = `select(
+          defined(artist) => artist->{ 'name': name, 'thumbnail': thumbnail_url.asset->url},
+          defined(parent_content_data) => *[_type == ^.parent_content_data[0].type && railcontent_id == ^.parent_content_data[0].id][0].artist->{ 'name': name, 'thumbnail': thumbnail_url.asset->url}
+        )`
+
 export const DEFAULT_FIELDS = [
   "'sanity_id' : _id",
   "'id': railcontent_id",
   'railcontent_id',
   artistOrInstructorName(),
-  "'artist': artist->{ 'name': name, 'thumbnail': thumbnail_url.asset->url}",
+  `'artist': ${artistField}`,
   'title',
   "'image': thumbnail.asset->url",
   "'thumbnail': thumbnail.asset->url",

package/src/index.d.ts

@@ -95,8 +95,9 @@ import {
 } from './services/forum.js';
 
 import {
-	fetchAwardsForUser
-} from './services/gamification/awards.js';
+	fetchAwardsForUser,
+	fetchCertificate
+} from './services/gamification/awards.ts';
 
 import {
 	applyCloudflareWrapper,
@@ -219,6 +220,8 @@ import {
 } from './services/sanity.js';
 
 import {
+	confirmEmailChange,
+	requestEmailChange,
 	resetPassword,
 	sendAccountSetupEmail,
 	sendPasswordResetEmail,
@@ -241,9 +244,12 @@ import {
 
 import {
 	blockUser,
+	blockedUsers,
 	deletePicture,
 	getUserData,
+	isDisplayNameAvailable,
 	unblockUser,
+	updateDisplayName,
 	uploadPicture,
 	uploadPictureFromS3
 } from './services/user/management.js';
@@ -312,9 +318,11 @@ declare module 'musora-content-services' {
 		applySanityTransformations,
 		assignModeratorToComment,
 		blockUser,
+		blockedUsers,
 		buildImageSRC,
 		calculateLongestStreaks,
 		closeComment,
+		confirmEmailChange,
 		contentStatusCompleted,
 		contentStatusReset,
 		convertToTimeZone,
@@ -344,6 +352,7 @@ declare module 'musora-content-services' {
 		fetchByRailContentIds,
 		fetchByReference,
 		fetchCarouselCardData,
+		fetchCertificate,
 		fetchChatAndLiveEnvent,
 		fetchChatSettings,
 		fetchCoachLessons,
@@ -463,6 +472,7 @@ declare module 'musora-content-services' {
 		isBucketUrl,
 		isContentLiked,
 		isContentLikedByIds,
+		isDisplayNameAvailable,
 		isNextDay,
 		isSameDate,
 		jumpToContinueContent,
@@ -502,6 +512,7 @@ declare module 'musora-content-services' {
 		replyToComment,
 		reportComment,
 		reportPlaylist,
+		requestEmailChange,
 		reset,
 		resetPassword,
 		restoreComment,
@@ -527,6 +538,7 @@ declare module 'musora-content-services' {
 		unlikeContent,
 		unlikePlaylist,
 		unpinProgressRow,
+		updateDisplayName,
 		updateNotificationSetting,
 		updatePlaylist,
 		updatePracticeNotes,

package/src/index.js

@@ -95,8 +95,9 @@ import {
 } from './services/forum.js';
 
 import {
-	fetchAwardsForUser
-} from './services/gamification/awards.js';
+	fetchAwardsForUser,
+	fetchCertificate
+} from './services/gamification/awards.ts';
 
 import {
 	applyCloudflareWrapper,
@@ -219,6 +220,8 @@ import {
 } from './services/sanity.js';
 
 import {
+	confirmEmailChange,
+	requestEmailChange,
 	resetPassword,
 	sendAccountSetupEmail,
 	sendPasswordResetEmail,
@@ -241,9 +244,12 @@ import {
 
 import {
 	blockUser,
+	blockedUsers,
 	deletePicture,
 	getUserData,
+	isDisplayNameAvailable,
 	unblockUser,
+	updateDisplayName,
 	uploadPicture,
 	uploadPictureFromS3
 } from './services/user/management.js';
@@ -311,9 +317,11 @@ export {
 	applySanityTransformations,
 	assignModeratorToComment,
 	blockUser,
+	blockedUsers,
 	buildImageSRC,
 	calculateLongestStreaks,
 	closeComment,
+	confirmEmailChange,
 	contentStatusCompleted,
 	contentStatusReset,
 	convertToTimeZone,
@@ -343,6 +351,7 @@ export {
 	fetchByRailContentIds,
 	fetchByReference,
 	fetchCarouselCardData,
+	fetchCertificate,
 	fetchChatAndLiveEnvent,
 	fetchChatSettings,
 	fetchCoachLessons,
@@ -462,6 +471,7 @@ export {
 	isBucketUrl,
 	isContentLiked,
 	isContentLikedByIds,
+	isDisplayNameAvailable,
 	isNextDay,
 	isSameDate,
 	jumpToContinueContent,
@@ -501,6 +511,7 @@ export {
 	replyToComment,
 	reportComment,
 	reportPlaylist,
+	requestEmailChange,
 	reset,
 	resetPassword,
 	restoreComment,
@@ -526,6 +537,7 @@ export {
 	unlikeContent,
 	unlikePlaylist,
 	unpinProgressRow,
+	updateDisplayName,
 	updateNotificationSetting,
 	updatePlaylist,
 	updatePracticeNotes,

package/src/services/api/types.ts

@@ -0,0 +1,22 @@
+export interface PaginatedMeta {
+  current_page: number
+  from: number
+  to: number
+  per_page: number
+  last_page: number
+  total: number
+  path: string
+}
+
+export interface PaginatedLinks {
+  first: string
+  last: string
+  next: string
+  prev: string
+}
+
+export interface PaginatedResponse<T> {
+  meta: PaginatedMeta
+  links: PaginatedLinks
+  data: Array<T>
+}

package/src/services/gamification/awards.ts

@@ -0,0 +1,86 @@
+/**
+ * @module Awards
+ */
+
+import { HttpClient } from '../../infrastructure/http/HttpClient'
+import { PaginatedResponse } from '../api/types'
+import { globalConfig } from '../config'
+
+const baseUrl = `/api/gamification`
+
+export interface Award {
+  id: number
+  user_id: number
+  completed_at: string          // ISO-8601 timestamp
+  completion_data: Object
+  award_id: number
+  type: string
+  title: string
+  badge: string
+}
+
+export interface Certificate {
+  id: number
+  user_name: string
+  user_id: number
+  completed_at: string          // ISO-8601 timestamp
+  message: string
+  award_id: number
+  type: string
+  title: string
+  musora_logo: string
+  musora_logo_64: string
+  brand_logo: string
+  brand_logo_64: string
+  ribbon_image: string
+  ribbon_image_64: string
+  award_image: string
+  award_image_64: string
+
+  instructor_signature?: string
+  instructor_signature_64?: string
+}
+/**
+ * Get awards for a specific user.
+ *
+ * NOTE: needs error handling for the response from http client
+ * (Alexandre: I'm doing it in a different branch/PR: https://github.com/railroadmedia/musora-content-services/pull/349)
+ * NOTE: This function still expects brand because FE passes the argument. It is ignored for now
+ *
+ * @param {number} userId - The user ID. If not provided, the authenticated user is used instead.
+ * @param {string} _brand - The brand to fetch the awards for.
+ * @param {number|null} [page=1] - Page attribute for pagination
+ * @param {number|null} [limit=5] - Limit how many items to return
+ * @returns {Promise<PaginatedResponse<Award>>} - The awards for the user.
+ */
+export async function fetchAwardsForUser(
+  userId: number,
+  _brand: string,
+  page: number = 1,
+  limit: number = 5
+): Promise<PaginatedResponse<Award>> {
+  const httpClient = new HttpClient(globalConfig.baseUrl, globalConfig.sessionConfig.token)
+  const response = await httpClient.get<PaginatedResponse<Award>>(
+    `${baseUrl}/v1/users/${userId}/awards?limit=${limit}&page=${page}`
+  )
+
+  return response
+}
+
+/**
+ * Get certificate data for a completed user award
+ *
+ * NOTE: needs error handling for the response from http client
+ * (Alexandre: I'm doing it in a different branch/PR: https://github.com/railroadmedia/musora-content-services/pull/349)
+ * NOTE: This function still expects brand because FE passes the argument. It is ignored for now
+ *
+ * @param {number} userAwardId - The user award progress id
+ * @returns {Promise<Certificate>} - The certificate data for the completed user award.
+ */
+export async function fetchCertificate(userAwardId: number): Promise<Certificate> {
+  const httpClient = new HttpClient(globalConfig.baseUrl, globalConfig.sessionConfig.token)
+  const response = await httpClient.get<Certificate>(
+    `${baseUrl}/v1/users/certificate/${userAwardId}`
+  )
+  return response
+}

package/src/services/sanity.js

@@ -1298,33 +1298,28 @@ export async function fetchSiblingContent(railContentId, brand= null)
 /**
  * Fetch lessons related to a specific lesson by RailContent ID and type.
  * @param {string} railContentId - The RailContent ID of the current lesson.
- * @param {string} brand - The current brand.
  * @returns {Promise<Array<Object>|null>} - The fetched related lessons data or null if not found.
  */
-export async function fetchRelatedLessons(railContentId, brand) {
-  const filterSameTypeAndSortOrder = await new FilterBuilder(
-    `_type==^._type &&  _type in ${JSON.stringify(typeWithSortOrder)} && brand == "${brand}" && railcontent_id !=${railContentId}`
-  ).buildFilter()
-  const filterSameType = await new FilterBuilder(
-    `_type==^._type && !(_type in ${JSON.stringify(typeWithSortOrder)}) && !(defined(parent_type)) && brand == "${brand}" && railcontent_id !=${railContentId}`
-  ).buildFilter()
-  const filterSongSameArtist = await new FilterBuilder(
-    `_type=="song" && _type==^._type && brand == "${brand}" && references(^.artist->_id) && railcontent_id !=${railContentId}`
+export async function fetchRelatedLessons(railContentId)
+{
+  const defaultFilterFields = `_type==^._type && brand == ^.brand && railcontent_id != ${railContentId}`
+
+  const filterSameArtist = await new FilterBuilder(
+    `${defaultFilterFields} && references(^.artist->_id)`
   ).buildFilter()
-  const filterSongSameGenre = await new FilterBuilder(
-    `_type=="song" && _type==^._type && brand == "${brand}" && references(^.genre[]->_id) && railcontent_id !=${railContentId}`
+  const filterSameGenre = await new FilterBuilder(
+    `${defaultFilterFields} && references(^.genre[]->_id)`
   ).buildFilter()
+
   const queryFields = `_id, "id":railcontent_id, published_on, "instructor": instructor[0]->name, title, "thumbnail":thumbnail.asset->url, length_in_seconds, status, "type": _type, difficulty, difficulty_string, railcontent_id, artist->,"permission_id": permission[]->railcontent_id,_type, "genre": genre[]->name`
-  const queryFieldsWithSort = queryFields + ', sort'
-  const query = `*[railcontent_id == ${railContentId} && brand == "${brand}" && (!defined(permission) || references(*[_type=='permission']._id))]{
+
+  const query = `*[railcontent_id == ${railContentId} && (!defined(permission) || references(*[_type=='permission']._id))]{
    _type, parent_type, railcontent_id,
     "related_lessons" : array::unique([
-      ...(*[${filterSongSameArtist}]{${queryFields}}|order(published_on desc, title asc)[0...10]),
-      ...(*[${filterSongSameGenre}]{${queryFields}}|order(published_on desc, title asc)[0...10]),
-      ...(*[${filterSameTypeAndSortOrder}]{${queryFieldsWithSort}}|order(sort asc, title asc)[0...10]),
-      ...(*[${filterSameType}]{${queryFields}}|order(published_on desc, title asc)[0...10])
-      ,
+      ...(*[${filterSameArtist}]{${queryFields}}|order(published_on desc, title asc)[0...10]),
+      ...(*[${filterSameGenre}]{${queryFields}}|order(published_on desc, title asc)[0...10]),
       ])[0...10]}`
+
   return await fetchSanity(query, false)
 }
 

package/src/services/user/account.ts

@@ -64,3 +64,27 @@ export async function resetPassword({
     token,
   })
 }
+
+/**
+ * @param {string} email - The new email address to set for the user.
+ * @param {string} password - The current password of the user for verification.
+ * @returns {Promise<void|HttpError>} - A promise that resolves when the email change request is made.
+ */
+export async function requestEmailChange(
+  email: string,
+  password: string
+): Promise<void | HttpError> {
+  const apiUrl = `/api/user-management-system/v1/accounts/${globalConfig.sessionConfig.userId}/email-change`
+  const httpClient = new HttpClient(globalConfig.baseUrl, globalConfig.sessionConfig.token)
+  return httpClient.post(apiUrl, { email, password })
+}
+
+/**
+ * @param {string} token - The token sent to the user's email for verification.
+ * @returns {Promise<void|HttpError>} - A promise that resolves when the email change is confirmed.
+ */
+export async function confirmEmailChange(token: string): Promise<void | HttpError> {
+  const apiUrl = `/api/user-management-system/v1/accounts/email-change/confirm`
+  const httpClient = new HttpClient(globalConfig.baseUrl, globalConfig.sessionConfig.token)
+  return httpClient.post(apiUrl, { token })
+}

package/src/services/user/management.js

@@ -9,6 +9,16 @@ import { HttpClient } from '../../infrastructure/http/HttpClient'
 
 const baseUrl = `/api/user-management-system`
 
+/**
+ * Fetches the blocked users for the current user.
+ * @returns {Promise<Array<BlockedUsersDTO>>}
+ */
+export async function blockedUsers() {
+  const url = `${baseUrl}/v1/users/${globalConfig.sessionConfig.userId}/blocked`
+  const httpClient = new HttpClient(globalConfig.baseUrl, globalConfig.sessionConfig.token)
+  return httpClient.get(url)
+}
+
 /**
  * Block the provided user
  * @param userId
@@ -116,3 +126,24 @@ export async function getUserData(userId = globalConfig.sessionConfig.userId) {
   const httpClient = new HttpClient(globalConfig.baseUrl, globalConfig.sessionConfig.token)
   return httpClient.get(apiUrl)
 }
+
+/**
+ * @param displayName - The display name to check for availability.
+ * @returns {Promise<{ available: boolean }>} - An object indicating if the display name is available.
+ */
+export async function isDisplayNameAvailable(displayName) {
+  const apiUrl = `${baseUrl}/v1/users/display-names/available?display_name=${encodeURIComponent(displayName)}`
+  const httpClient = new HttpClient(globalConfig.baseUrl, globalConfig.sessionConfig.token)
+  return httpClient.get(apiUrl)
+}
+
+/**
+ * @param newDisplayName - The new display name to set for the user.
+ * @returns {Promise<User>} - A promise that resolves when the display name is updated.
+ */
+export async function updateDisplayName(newDisplayName) {
+  const apiUrl = `${baseUrl}/v1/users/${globalConfig.sessionConfig.userId}/display-name`
+  const httpClient = new HttpClient(globalConfig.baseUrl, globalConfig.sessionConfig.token)
+  return httpClient.put(apiUrl, { display_name: newDisplayName })
+}
+

package/src/services/user/types.js

@@ -134,3 +134,11 @@
  * @property {number} forum_post_likes
  * @property {number} experience_points
  */
+
+/**
+ * @typedef {Object} BlockedUsersDTO
+ *
+ * @property {number} id
+ * @property {string} display_name
+ * @property {string|null} profile_picture_url
+ */

package/src/services/userActivity.js

@@ -995,6 +995,7 @@ function generateContentsMap(contents, playlistsContents) {
   const existingShows = new Set()
   const contentsMap = new Map()
   const childToParentMap = {}
+  if (!contents) return contentsMap
   contents.forEach((content) => {
     if (Array.isArray(content.parent_content_data) && content.parent_content_data.length > 0) {
       childToParentMap[content.id] =
@@ -1073,20 +1074,20 @@ export async function getProgressRows({ brand = null, limit = 8 } = {}) {
     nonPlaylistContentIds.push(userPinnedItem.id)
   }
   const [playlistsContents, contents] = await Promise.all([
-    addContextToContent(fetchByRailContentIds, playlistEngagedOnContents, 'progress-tracker', {
+    playlistEngagedOnContents ? addContextToContent(fetchByRailContentIds, playlistEngagedOnContents, 'progress-tracker', {
       addNextLesson: true,
       addNavigateTo: true,
       addProgressStatus: true,
       addProgressPercentage: true,
       addProgressTimestamp: true,
-    }),
-    addContextToContent(fetchByRailContentIds, nonPlaylistContentIds, 'progress-tracker', brand, {
+    }) : Promise.resolve([]),
+    nonPlaylistContentIds ? addContextToContent(fetchByRailContentIds, nonPlaylistContentIds, 'progress-tracker', brand, {
       addNextLesson: true,
       addNavigateTo: true,
       addProgressStatus: true,
       addProgressPercentage: true,
       addProgressTimestamp: true,
-    }),
+    }) : Promise.resolve([]),
   ])
   const contentsMap = generateContentsMap(contents, playlistsContents)
   let combined = await extractPinnedItemsAndSortAllItems(
@@ -1103,7 +1104,6 @@ export async function getProgressRows({ brand = null, limit = 8 } = {}) {
         item.type === 'playlist' ? processPlaylistItem(item) : processContentItem(item)
       )
   )
-  console.log('HomePageProgressRows results: remove before merge', results)
   return {
     type: TabResponseType.PROGRESS_ROWS,
     displayBrowseAll: combined.length > limit,

package/src/services/gamification/awards.js

@@ -1,93 +0,0 @@
-/**
- * @module Awards
- */
-import '../api/types.js'
-import './types.js'
-
-/**
- * Get awards for a specific user.
- *
- * @param {number|null} userId - The user ID. If not provided, the authenticated user is used instead.
- * @param {string|null} brand - Brand
- * @param {number|null} page - Page attribute for pagination
- * @param {number|null} limit - Limit how many items to return
- * @returns {Promise<PaginatedResponse<Award>>} - The awards for the user.
- */
-export async function fetchAwardsForUser(userId, brand, page = 1, limit = 20) {
-  // TODO: connect to the API to get the user awards
-  return {
-    data: [
-      {
-        id: 1,
-        title: '30-Day Drummer',
-        challenge_title: '30-Day Drummer',
-        award:
-          'https://cdn.sanity.io/files/4032r8py/staging/5c7449ea40f09a096451a48e4a58e4452244e38d.png',
-        badge:
-          'https://cdn.sanity.io/files/4032r8py/staging/5c7449ea40f09a096451a48e4a58e4452244e38d.png',
-        date_completed: '2021-01-01',
-        award_text:
-          'You received this award for completing 30-Day Drummer with a perfect streak. You practiced a total of 123 minutes over the past 30 days.',
-        description:
-          'You received this award for completing 30-Day Drummer with a perfect streak. You practiced a total of 123 minutes over the past 30 days.',
-      },
-      {
-        id: 2,
-        title: '30-Day Bass',
-        challenge_title: '30-Day Bass',
-        award:
-          'https://cdn.sanity.io/files/4032r8py/production/b7efb6a2f0bd57e87dd13f85b1c3b0c876272b7c.png',
-        badge:
-          'https://cdn.sanity.io/files/4032r8py/production/b7efb6a2f0bd57e87dd13f85b1c3b0c876272b7c.png',
-        date_completed: '2022-02-02',
-        award_text:
-          'You received this award for completing 30-Day Bass with a perfect streak. You practiced a total of 123 minutes over the past 30 days.',
-        description:
-          'You received this award for completing 30-Day Bass with a perfect streak. You practiced a total of 123 minutes over the past 30 days.',
-      },
-      {
-        id: 3,
-        title: 'New Piano Players Start Here',
-        challenge_title: 'New Piano Players Start Here',
-        award:
-          'https://cdn.sanity.io/files/4032r8py/staging/94e663015da362b41695f5d6f3a8ca3f8317e1b5.png',
-        badge:
-          'https://cdn.sanity.io/files/4032r8py/staging/94e663015da362b41695f5d6f3a8ca3f8317e1b5.png',
-        date_completed: '2023-03-03',
-        award_text:
-          'You received this award for completing New Piano Players Start Here with a perfect streak. You practiced a total of 123 minutes over the past 30 days.',
-        description:
-          'You received this award for completing New Piano Players Start Here with a perfect streak. You practiced a total of 123 minutes over the past 30 days.',
-      },
-      {
-        id: 4,
-        title: 'Ear Training For Singers',
-        challenge_title: 'Ear Training For Singers',
-        award:
-          'https://cdn.sanity.io/files/4032r8py/staging/24fc36e8351d7994bfe8fb5c63c577cf5ed16dc9.png',
-        badge:
-          'https://cdn.sanity.io/files/4032r8py/staging/24fc36e8351d7994bfe8fb5c63c577cf5ed16dc9.png',
-        date_completed: '2024-04-04',
-        award_text:
-          'You received this award for completing Ear Training For Singers with a perfect streak. You practiced a total of 123 minutes over the past 30 days.',
-        description:
-          'You received this award for completing Ear Training For Singers with a perfect streak. You practiced a total of 123 minutes over the past 30 days.',
-      },
-    ],
-    meta: {
-      current_page: 1,
-      from: 1,
-      to: 15,
-      per_page: 15,
-      last_page: 1,
-      total: 4,
-      path: 'to be implemented when BE is ready',
-    },
-    links: {
-      first: 'to be implemented when BE is ready',
-      last: 'to be implemented when BE is ready',
-      next: 'to be implemented when BE is ready',
-      prev: 'to be implemented when BE is ready',
-    },
-  }
-}

package/src/services/gamification/types.js

@@ -1,8 +0,0 @@
-/**
- * @typedef {Object} Award
- * @property {number} id - Unique identifier for the award.
- * @property {string} title - The title of the award.
- * @property {string} badge - URL of the award badge image.
- * @property {string} description - Description of the award.
- * @property {Date} date_completed - Date when the award was completed.
- */