musora-content-services 2.87.0 → 2.88.0

package/.claude/settings.local.json

@@ -1,8 +1,14 @@
 {
   "permissions": {
     "allow": [
-      "Bash(rg:*)"
+      "Read(//app/musora-platform-backend/**)",
+      "Read(//app/musora-platform-frontend/**)",
+      "Bash(find:*)",
+      "Bash(sed:*)",
+      "Read(//app/**)",
+      "Bash(cat:*)"
     ],
-    "deny": []
+    "deny": [],
+    "ask": []
   }
-}
+}

package/.yarnrc.yml

@@ -0,0 +1 @@
+nodeLinker: node-modules

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 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.88.0](https://github.com/railroadmedia/musora-content-services/compare/v2.86.1...v2.88.0) (2025-11-26)
+
+
+### Features
+
+* **BEH-1418:** refactor learning path endpoints ([#589](https://github.com/railroadmedia/musora-content-services/issues/589)) ([e3637f6](https://github.com/railroadmedia/musora-content-services/commit/e3637f6359ddf8f4295eead890de6457b942b4ea))
+* Implement unified user reporting system ([7aa42ab](https://github.com/railroadmedia/musora-content-services/commit/7aa42ab8dcee09ce3f293d9fbb1a203dcbe94414))
+* **MU2-1250:** Implement unified user reporting system ([3303282](https://github.com/railroadmedia/musora-content-services/commit/33032829b729efa9f9b1e40f31179127c8c74f9d))
+
 ## [2.87.0](https://github.com/railroadmedia/musora-content-services/compare/v2.86.1...v2.87.0) (2025-11-26)
 
 

package/package.json

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

package/src/index.d.ts

@@ -242,6 +242,11 @@ import {
 	recommendations
 } from './services/recommendations.js';
 
+import {
+	getReportIssueOptions,
+	report
+} from './services/reporting/reporting.ts';
+
 import {
 	buildEntityAndTotalQuery,
 	fetchAll,
@@ -597,6 +602,7 @@ declare module 'musora-content-services' {
 		getRecent,
 		getRecentActivity,
 		getRecommendedForYou,
+		getReportIssueOptions,
 		getResumeTimeSeconds,
 		getResumeTimeSecondsByIds,
 		getSanityDate,
@@ -662,6 +668,7 @@ declare module 'musora-content-services' {
 		removeContentAsNotInterested,
 		removeUserPractice,
 		replyToComment,
+		report,
 		reportComment,
 		reportPlaylist,
 		requestEmailChange,

package/src/index.js

@@ -242,6 +242,11 @@ import {
 	recommendations
 } from './services/recommendations.js';
 
+import {
+	getReportIssueOptions,
+	report
+} from './services/reporting/reporting.ts';
+
 import {
 	buildEntityAndTotalQuery,
 	fetchAll,
@@ -596,6 +601,7 @@ export {
 	getRecent,
 	getRecentActivity,
 	getRecommendedForYou,
+	getReportIssueOptions,
 	getResumeTimeSeconds,
 	getResumeTimeSecondsByIds,
 	getSanityDate,
@@ -661,6 +667,7 @@ export {
 	removeContentAsNotInterested,
 	removeUserPractice,
 	replyToComment,
+	report,
 	reportComment,
 	reportPlaylist,
 	requestEmailChange,

package/src/services/reporting/README.md

@@ -0,0 +1,316 @@
+# Reporting Service
+
+Service for submitting user reports about content, comments, forum posts, and playlists.
+
+## Overview
+
+This service provides two main functions for reporting content:
+
+1. **`report()`** - Unified method to submit reports for any type of content (content, comments, forum posts, playlists)
+2. **`getReportIssueOptions()`** - Helper function to get valid issue options for each reportable type, with support for platform-specific options (web vs mobile app)
+
+Reports are sent to the appropriate team (support or mentors) based on the content type. Both functions are designed to be used by the web platform (MPF) and mobile app (MA) to ensure consistent reporting options and behavior.
+
+## Features
+
+- ✅ Unified `report()` method for all reportable types
+- ✅ Type-safe issue selection with TypeScript generics
+- ✅ Platform-specific options (web vs mobile app)
+- ✅ Helper function to get valid issue options by type
+- ✅ Rate limiting (10 requests per minute per user)
+- ✅ Emails sent to appropriate teams (support or mentors)
+- ✅ Full TypeScript support with mapped types
+
+## Installation
+
+The reporting service is included in `musora-content-services`. Simply import the functions you need:
+
+```typescript
+import { report, getReportIssueOptions } from 'musora-content-services'
+```
+
+Both functions are exported from `services/reporting/reporting.ts`.
+
+## API Reference
+
+### `report<T>(params)`
+
+Unified method to submit a report for any type. Uses TypeScript generics for type-safe issue selection.
+
+**Type Parameter:**
+- `T extends ReportableType` - The type of content being reported
+
+**Parameters:**
+```typescript
+type ReportParams<T extends ReportableType> = {
+  type: T                    // 'content' | 'comment' | 'forum_post' | 'playlist'
+  id: number                 // ID of the entity being reported
+  issue: IssueTypeMap[T]     // Type-safe issue (varies by type)
+  details?: string           // Required when issue is 'other', not sent otherwise
+  brand: string              // Required: 'drumeo', 'pianote', 'guitareo', 'singeo', 'playbass'
+}
+```
+
+**Returns:** `Promise<ReportResponse>`
+```typescript
+interface ReportResponse {
+  report_id: number         // The ID of the submitted report
+  message: string          // Success message
+}
+```
+
+**Example - Report Content:**
+```typescript
+import { report } from 'musora-content-services'
+
+const response = await report({
+  type: 'content',
+  id: 12345,
+  issue: 'video_issue',
+  brand: 'drumeo'
+})
+
+console.log(`Report submitted with ID: ${response.report_id}`)
+console.log(response.message) // "Report submitted successfully"
+```
+
+**Example - Report Comment:**
+```typescript
+await report({
+  type: 'comment',
+  id: 67890,
+  issue: 'offensive_language',
+  brand: 'pianote'
+})
+```
+
+**Example - Report Forum Post:**
+```typescript
+await report({
+  type: 'forum_post',
+  id: 45678,
+  issue: 'abusive',
+  brand: 'guitareo'
+})
+```
+
+**Example - Report Playlist:**
+```typescript
+await report({
+  type: 'playlist',
+  id: 99999,
+  issue: 'incorrect_metadata',
+  brand: 'singeo'
+})
+```
+
+**Example - Report with 'other' issue (details required):**
+```typescript
+await report({
+  type: 'content',
+  id: 12345,
+  issue: 'other',
+  details: 'The instructor audio is out of sync with the video',
+  brand: 'drumeo'
+})
+```
+
+---
+
+### `getReportIssueOptions(type, isMobileApp?)`
+
+Helper function to get valid issue options for a specific reportable type. Returns both the value and user-friendly label for each option.
+
+**Parameters:**
+```typescript
+type: ReportableType       // 'content' | 'comment' | 'forum_post' | 'playlist'
+isMobileApp?: boolean     // Default: false. Set to true for mobile app options
+```
+
+**Returns:** `ReportIssueOption[]`
+```typescript
+interface ReportIssueOption {
+  value: string    // Issue value to send to API
+  label: string    // User-friendly label for display
+}
+```
+
+**Example - Web Platform:**
+```typescript
+import { getReportIssueOptions } from 'musora-content-services'
+
+// Get content issue options for web
+const options = getReportIssueOptions('content')
+// Returns:
+// [
+//   { value: 'incorrect_metadata', label: 'The lesson image, title or description is incorrect' },
+//   { value: 'video_issue', label: 'Video issue' },
+//   { value: 'assignment_issue', label: 'An issue with lesson assignment' },
+//   { value: 'other', label: 'Other' }
+// ]
+  options.map(opt => ({
+    ...opt,
+    label: t(`report.${opt.value}`)
+  }))
+```
+
+**Example - Mobile App:**
+```typescript
+// Get content issue options for mobile app (includes download option)
+const options = getReportIssueOptions('content', true)
+// Returns:
+// [
+//   { value: 'incorrect_metadata', label: 'The lesson image, title or description is incorrect' },
+//   { value: 'video_issue', label: 'Video issue' },
+//   { value: 'download_unavailable', label: 'Download is not available' },
+//   { value: 'assignment_issue', label: 'An issue with lesson assignment' },
+//   { value: 'other', label: 'Other' }
+// ]
+ options.map(opt => ({
+    ...opt,
+    label: t(`report.${opt.value}`)
+  }))
+```
+
+**Example - Comment Issues:**
+```typescript
+const commentOptions = getReportIssueOptions('comment')
+// Returns:
+// [
+//   { value: 'offensive_language', label: 'It contains offensive language or content' },
+//   { value: 'abusive', label: "It's abusive or harmful" },
+//   { value: 'personal_information', label: 'It contains personal information' },
+//   { value: 'misleading', label: "It's misleading or a false claim" },
+//   { value: 'other', label: 'Other reasons' }
+// ]
+```
+
+---
+
+## Report Issues by Type
+
+### Content & Playlists:
+- `incorrect_metadata` - The lesson image, title or description is incorrect
+- `video_issue` - Video issue
+- `download_unavailable` - Download is not available (mobile app only)
+- `assignment_issue` - An issue with lesson assignment
+- `other` - Other
+
+### Comments & Forum Posts:
+- `offensive_language` - It contains offensive language or content
+- `abusive` - It's abusive or harmful
+- `personal_information` - It contains personal information
+- `misleading` - It's misleading or a false claim
+- `other` - Other reasons
+
+**Important:** The `details` field is **required** when `issue` is `'other'` and should **not be sent** for other issue types.
+
+---
+
+## Rate Limiting
+
+API requests are rate-limited to **10 requests per minute per user**. If you exceed this limit, you'll receive a `429 Too Many Requests` error.
+
+---
+
+## Email Recipients
+
+Reports are automatically routed to the appropriate team:
+
+| Report Type | Email Recipient |
+|-------------|----------------|
+| Forum Posts | mentors@musora.com |
+| Comments | mentors@musora.com |
+| Content | support@musora.com |
+| Playlists | support@musora.com |
+
+---
+
+## Platform-Specific Options
+
+The `getReportIssueOptions()` function supports platform-specific options via the `isMobileApp` parameter:
+
+**Web Platform (default):**
+- Does NOT include "Download is not available" option
+- Use: `getReportIssueOptions('content')`
+
+**Mobile App:**
+- INCLUDES "Download is not available" option for content and playlists
+- Use: `getReportIssueOptions('content', true)`
+
+
+---
+
+## Error Handling
+
+```typescript
+import { report } from 'musora-content-services'
+
+try {
+  const response = await report({
+    type: 'content',
+    id: 123,
+    issue: 'video_issue',
+    brand: 'drumeo'
+  })
+
+  // Handle success
+  showToast('Report submitted successfully')
+} catch (error) {
+  if (error.status === 429) {
+    // Rate limit exceeded
+    showToast('Too many reports. Please try again later.')
+  } else if (error.status === 422) {
+    // Validation error
+    showToast(error.message || 'Invalid report data')
+  } else if (error.status === 401) {
+    // Not authenticated
+    showToast('Please log in to submit a report')
+  } else {
+    // Other errors
+    showToast('Failed to submit report')
+  }
+}
+```
+
+---
+
+## Type Safety
+
+The reporting service uses TypeScript generics to ensure type-safe issue selection:
+
+```typescript
+// ✅ Type-safe: 'video_issue' is valid for content
+await report({
+  type: 'content',
+  id: 123,
+  issue: 'video_issue',  // TypeScript knows this is valid
+  brand: 'drumeo'
+})
+
+// ❌ Type error: 'offensive_language' is not valid for content
+await report({
+  type: 'content',
+  id: 123,
+  issue: 'offensive_language',  // TypeScript error!
+  brand: 'drumeo'
+})
+
+// ✅ Type-safe: 'offensive_language' is valid for comments
+await report({
+  type: 'comment',
+  id: 456,
+  issue: 'offensive_language',  // TypeScript knows this is valid
+  brand: 'drumeo'
+})
+```
+
+The `IssueTypeMap` maps each reportable type to its valid issues:
+```typescript
+type IssueTypeMap = {
+  forum_post: ForumIssueType
+  comment: CommentIssueType
+  content: ContentIssueType
+  playlist: PlaylistIssueType
+}
+```

package/src/services/reporting/reporting.ts

@@ -0,0 +1,189 @@
+/**
+ * @module Reporting
+ * @description Service for submitting user reports about content, comments, forum posts, and playlists.
+ *
+ * This service provides a unified method to report any type of content when users encounter
+ * inappropriate behavior, technical issues, or other problems.
+ *
+ */
+
+import { HttpClient } from '../../infrastructure/http/HttpClient'
+import { globalConfig } from '../config.js'
+import {
+  ReportResponse,
+  ReportableType,
+  IssueTypeMap,
+  ReportIssueOption,
+} from './types'
+import {Brand} from "../../lib/brands";
+
+/**
+ * Parameters for submitting a report with type-safe issue values
+ */
+export type ReportParams<T extends ReportableType = ReportableType> = {
+  /** Type of content being reported */
+  type: T
+  /** ID of the content being reported */
+  id: number
+  /** Issue category - type-safe based on reportable type */
+  issue: IssueTypeMap[T]
+  /** Details about the issue - required when issue is 'other', not sent otherwise */
+  details?: string
+  /** Brand context (required: drumeo, pianote, guitareo, singeo, playbass) */
+  brand: Brand
+}
+
+/**
+ * Submit a report for any type of content.
+ *
+ * This is a unified method that handles all report types (content, comment, forum_post, playlist).
+ * The issue parameter is type-safe based on the reportable type.
+ *
+ * @param {ReportParams} params - The report parameters
+ * @returns {Promise<ReportResponse>} The report submission response
+ * @throws {HttpError} Throws HttpError if the request fails
+ *
+ * @example
+ * // Report content with technical issue - no details needed
+ * const response = await report({
+ *   type: 'content',
+ *   id: 123,
+ *   issue: 'video_issue',
+ *   brand: 'drumeo'
+ * })
+ *
+ * console.log(`Report submitted with ID: ${response.report_id}`)
+ *
+ * @example
+ * // Report with 'other' issue - details required
+ * await report({
+ *   type: 'content',
+ *   id: 456,
+ *   issue: 'other',
+ *   details: 'The instructor audio is out of sync with the video',
+ *   brand: 'drumeo'
+ * })
+ *
+ * @example
+ * // Report forum post
+ * await report({
+ *   type: 'forum_post',
+ *   id: 789,
+ *   issue: 'abusive',
+ *   brand: 'drumeo'
+ * })
+ */
+export async function report<T extends ReportableType>(params: ReportParams<T>): Promise<ReportResponse> {
+  const httpClient = new HttpClient(globalConfig.baseUrl)
+
+  // Build request body
+  const requestBody: any = {
+    reportable_type: params.type,
+    reportable_id: params.id,
+    issue: params.issue,
+    brand: params.brand,
+  }
+
+  // Add details only when provided (required for 'other' issue)
+  if (params.details) {
+    requestBody.details = params.details
+  }
+
+  const response = await httpClient.post<ReportResponse>(
+    '/api/user-reports/v1/reports',
+    requestBody
+  )
+
+  return response
+}
+
+/**
+ * Get valid report issue options for a specific reportable type
+ *
+ * @param {ReportableType} type - The type of content being reported
+ * @param {boolean} isMobileApp - Whether this is for mobile app (includes download option)
+ * @returns {ReportIssueOption[]} Array of valid issue options with their labels
+ *
+ * @example
+ * // Web options (default)
+ * const contentOptions = getReportIssueOptions('content')
+ * // Returns: [
+ * //   { value: 'incorrect_metadata', label: 'The lesson image, title or description is incorrect' },
+ * //   { value: 'video_issue', label: 'Video issue' },
+ * //   { value: 'assignment_issue', label: 'An issue with lesson assignment' },
+ * //   { value: 'other', label: 'Other' }
+ * // ]
+ *
+ * @example
+ * // Mobile app options (includes download)
+ * const contentOptions = getReportIssueOptions('content', true)
+ * // Returns: [
+ * //   { value: 'incorrect_metadata', label: 'The lesson image, title or description is incorrect' },
+ * //   { value: 'video_issue', label: 'Video issue' },
+ * //   { value: 'download_unavailable', label: 'Download is not available' },
+ * //   { value: 'assignment_issue', label: 'An issue with lesson assignment' },
+ * //   { value: 'other', label: 'Other' }
+ * // ]
+ */
+export function getReportIssueOptions(type: ReportableType, isMobileApp: boolean = false): ReportIssueOption[] {
+  switch (type) {
+    case 'forum_post':
+      return [
+        { value: 'offensive_language', label: 'It contains offensive language or content' },
+        { value: 'abusive', label: "It's abusive or harmful" },
+        { value: 'personal_information', label: 'It contains personal information' },
+        { value: 'misleading', label: "It's misleading or a false claim" },
+        { value: 'other', label: 'Other reasons' },
+      ]
+
+    case 'comment':
+      return [
+        { value: 'offensive_language', label: 'It contains offensive language or content' },
+        { value: 'abusive', label: "It's abusive or harmful" },
+        { value: 'personal_information', label: 'It contains personal information' },
+        { value: 'misleading', label: "It's misleading or a false claim" },
+        { value: 'other', label: 'Other reasons' },
+      ]
+
+    case 'content':
+      const contentOptions = [
+        { value: 'incorrect_metadata', label: 'The lesson image, title or description is incorrect' },
+        { value: 'video_issue', label: 'Video issue' },
+      ]
+
+      // Add download option only for mobile app
+      if (isMobileApp) {
+        contentOptions.push({ value: 'download_unavailable', label: 'Download is not available' })
+      }
+
+      contentOptions.push(
+        { value: 'assignment_issue', label: 'An issue with lesson assignment' },
+        { value: 'other', label: 'Other' }
+      )
+
+      return contentOptions
+
+    case 'playlist':
+      const playlistOptions = [
+        { value: 'incorrect_metadata', label: 'The lesson image, title or description is incorrect' },
+        { value: 'video_issue', label: 'Video issue' },
+      ]
+
+      // Add download option only for mobile app
+      if (isMobileApp) {
+        playlistOptions.push({ value: 'download_unavailable', label: 'Download is not available' })
+      }
+
+      playlistOptions.push(
+        { value: 'assignment_issue', label: 'An issue with lesson assignment' },
+        { value: 'other', label: 'Other' }
+      )
+
+      return playlistOptions
+
+    default:
+      return [
+        { value: 'other', label: 'Other' },
+      ]
+  }
+}

package/src/services/reporting/types.ts

@@ -0,0 +1,56 @@
+/**
+ * @module Reporting Types
+ */
+
+/**
+ * Type of entity being reported
+ */
+export type ReportableType = 'content' | 'comment' | 'forum_post' | 'playlist'
+
+/**
+ * Valid issue types for forum posts
+ */
+export type ForumIssueType = 'spam' | 'harassment' | 'inappropriate' | 'other'
+
+/**
+ * Valid issue types for comments
+ */
+export type CommentIssueType = 'offensive_language' | 'abusive' | 'personal_information' | 'misleading' | 'other'
+
+/**
+ * Valid issue types for content
+ */
+export type ContentIssueType = 'incorrect_metadata' | 'video_issue' | 'download_unavailable' | 'assignment_issue' | 'other'
+
+/**
+ * Valid issue types for playlists
+ */
+export type PlaylistIssueType = 'incorrect_metadata' | 'video_issue' | 'download_unavailable' | 'assignment_issue' | 'other'
+
+/**
+ * Map reportable type to its valid issue types
+ */
+export type IssueTypeMap = {
+  forum_post: ForumIssueType
+  comment: CommentIssueType
+  content: ContentIssueType
+  playlist: PlaylistIssueType
+}
+
+/**
+ * Response from submitting a report
+ */
+export interface ReportResponse {
+  /** The ID of the submitted report */
+  report_id: number
+  /** Success message */
+  message: string
+}
+
+/**
+ * Report issue option
+ */
+export interface ReportIssueOption {
+  value: string
+  label: string
+}

package/test/reporting.test.js

@@ -0,0 +1,132 @@
+/**
+ * Tests for Reporting Service
+ *
+ * Note: These tests use mocked HTTP calls. For integration tests,
+ * ensure the backend API is running at the configured baseUrl.
+ */
+
+import { initializeTestService } from './initializeTests.js'
+import {
+  reportContent,
+  reportForumPost,
+  submitReport
+} from '../src/services/reporting/reporting.ts'
+
+// Mock HttpClient to avoid actual API calls in tests
+jest.mock('../src/infrastructure/http/HttpClient', () => {
+  return {
+    HttpClient: jest.fn().mockImplementation(() => ({
+      post: jest.fn().mockResolvedValue({
+        report_id: 12345,
+        message: 'Report submitted successfully',
+        is_duplicate: false
+      })
+    }))
+  }
+})
+
+describe('Reporting Service', () => {
+  beforeEach(() => {
+    initializeTestService()
+  })
+
+  describe('reportContent', () => {
+    test('should submit a content report with video_not_working category', async () => {
+      const result = await reportContent({
+        contentId: 123,
+        category: 'video_not_working',
+        description: 'Video freezes at 2:30'
+      })
+
+      expect(result).toBeDefined()
+      expect(result.report_id).toBe(12345)
+      expect(result.message).toBe('Report submitted successfully')
+      expect(result.is_duplicate).toBe(false)
+    })
+
+    test('should submit a content report without description', async () => {
+      const result = await reportContent({
+        contentId: 456,
+        category: 'incorrect_content'
+      })
+
+      expect(result).toBeDefined()
+      expect(result.report_id).toBeDefined()
+    })
+
+    test('should submit a content report with other category and description', async () => {
+      const result = await reportContent({
+        contentId: 789,
+        category: 'other',
+        description: 'Audio quality is very poor'
+      })
+
+      expect(result).toBeDefined()
+      expect(result.report_id).toBeDefined()
+      expect(result.message).toBeDefined()
+    })
+  })
+
+  describe('reportForumPost', () => {
+    test('should submit a forum post report with required brand', async () => {
+      const result = await reportForumPost({
+        postId: 555,
+        brand: 'drumeo',
+        category: 'spam'
+      })
+
+      expect(result).toBeDefined()
+      expect(result.report_id).toBeDefined()
+    })
+
+    test('should submit a forum post report with description', async () => {
+      const result = await reportForumPost({
+        postId: 666,
+        brand: 'pianote',
+        category: 'harassment',
+        description: 'User is harassing other members'
+      })
+
+      expect(result).toBeDefined()
+      expect(result.report_id).toBeDefined()
+      expect(result.message).toBeDefined()
+    })
+  })
+
+  describe('submitReport', () => {
+    test('should submit a generic report for content', async () => {
+      const result = await submitReport({
+        reportableType: 'content',
+        reportableId: 999,
+        category: 'technical_issue',
+        description: 'Page not loading'
+      })
+
+      expect(result).toBeDefined()
+      expect(result.report_id).toBeDefined()
+    })
+
+    test('should submit a generic report for playlist', async () => {
+      const result = await submitReport({
+        reportableType: 'playlist',
+        reportableId: 777,
+        category: 'incorrect_content'
+      })
+
+      expect(result).toBeDefined()
+      expect(result.report_id).toBeDefined()
+    })
+
+    test('should submit a generic report for comment', async () => {
+      const result = await submitReport({
+        reportableType: 'comment',
+        reportableId: 888,
+        category: 'inappropriate',
+        description: 'Comment contains offensive language'
+      })
+
+      expect(result).toBeDefined()
+      expect(result.report_id).toBeDefined()
+    })
+  })
+})