musora-content-services 2.32.0 → 2.33.1

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.32.0",
+  "version": "2.33.1",
   "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/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,
@@ -319,6 +322,7 @@ declare module 'musora-content-services' {
 		buildImageSRC,
 		calculateLongestStreaks,
 		closeComment,
+		confirmEmailChange,
 		contentStatusCompleted,
 		contentStatusReset,
 		convertToTimeZone,
@@ -348,6 +352,7 @@ declare module 'musora-content-services' {
 		fetchByRailContentIds,
 		fetchByReference,
 		fetchCarouselCardData,
+		fetchCertificate,
 		fetchChatAndLiveEnvent,
 		fetchChatSettings,
 		fetchCoachLessons,
@@ -507,6 +512,7 @@ declare module 'musora-content-services' {
 		replyToComment,
 		reportComment,
 		reportPlaylist,
+		requestEmailChange,
 		reset,
 		resetPassword,
 		restoreComment,

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,
@@ -318,6 +321,7 @@ export {
 	buildImageSRC,
 	calculateLongestStreaks,
 	closeComment,
+	confirmEmailChange,
 	contentStatusCompleted,
 	contentStatusReset,
 	convertToTimeZone,
@@ -347,6 +351,7 @@ export {
 	fetchByRailContentIds,
 	fetchByReference,
 	fetchCarouselCardData,
+	fetchCertificate,
 	fetchChatAndLiveEnvent,
 	fetchChatSettings,
 	fetchCoachLessons,
@@ -506,6 +511,7 @@ export {
 	replyToComment,
 	reportComment,
 	reportPlaylist,
+	requestEmailChange,
 	reset,
 	resetPassword,
 	restoreComment,

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/user/account.ts

@@ -12,6 +12,10 @@ export interface PasswordResetProps {
   token: string
 }
 
+/**
+ * @param {string} email - The email address to check the account status for.
+ * @returns {Promise<{requires_setup: boolean}|HttpError>} - A promise that resolves to an object indicating whether account setup is required, or an HttpError if the request fails.
+ */
 export async function status(email: string): Promise<{ requires_setup: boolean } | HttpError> {
   const httpClient = new HttpClient(globalConfig.baseUrl)
   const response = await httpClient.get<{ requires_setup: boolean }>(
@@ -20,6 +24,10 @@ export async function status(email: string): Promise<{ requires_setup: boolean }
   return response
 }
 
+/**
+ * @param {string} email - The email address to send the account setup email to.
+ * @returns {Promise<void|HttpError>} - A promise that resolves when the email is sent or an HttpError if the request fails.
+ */
 export async function sendAccountSetupEmail(email: string): Promise<void | HttpError> {
   const httpClient = new HttpClient(globalConfig.baseUrl)
   return httpClient.post<void>(
@@ -28,6 +36,14 @@ export async function sendAccountSetupEmail(email: string): Promise<void | HttpE
   )
 }
 
+/**
+ * @param {Object} params - The parameters for setting up the account.
+ * @property {string} email - The email address for the account.
+ * @property {string} password - The new password for the account.
+ * @property {string} passwordConfirmation - The confirmation of the new password.
+ * @property {string} token - The token sent to the user's email for verification.
+ * @returns {Promise<void|HttpError>} - A promise that resolves when the account setup is complete or an HttpError if the request fails.
+ */
 export async function setupAccount({
   email,
   password,
@@ -43,6 +59,10 @@ export async function setupAccount({
   })
 }
 
+/**
+ * @param {string} email - The email address to send the password reset email to.
+ * @returns {Promise<void|HttpError>} - A promise that resolves when the email change request is made.
+ */
 export async function sendPasswordResetEmail(email: string): Promise<void | HttpError> {
   const httpClient = new HttpClient(globalConfig.baseUrl)
   return httpClient.post(`/api/user-management-system/v1/accounts/password/reset-email`, {
@@ -50,6 +70,14 @@ export async function sendPasswordResetEmail(email: string): Promise<void | Http
   })
 }
 
+/**
+ * @param {Object} params - The parameters for resetting the password.
+ * @property {string} email - The email address for the account.
+ * @property {string} password - The new password for the account.
+ * @property {string} passwordConfirmation - The confirmation of the new password.
+ * @property {string} token - The token sent to the user's email for verification.
+ * @returns {Promise<void|HttpError>} - A promise that resolves when the password reset is complete or an HttpError if the request fails.
+ */
 export async function resetPassword({
   email,
   password,
@@ -64,3 +92,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

@@ -146,3 +146,4 @@ export async function updateDisplayName(newDisplayName) {
   const httpClient = new HttpClient(globalConfig.baseUrl, globalConfig.sessionConfig.token)
   return httpClient.put(apiUrl, { display_name: newDisplayName })
 }
+

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.
- */