musora-content-services 2.167.1 → 2.167.2

package/.agent/decisions/2026-07-17-onboarding-statuses.md

@@ -0,0 +1,21 @@
+---
+date: 2026-07-17
+branch: chore/onboarding-statuses
+pr: https://github.com/railroadmedia/musora-content-services/pull/1011
+status: open
+tags: [[feature]]
+---
+
+# Add cross-brand onboarding status endpoint
+
+## Context
+`userOnboardingForBrand(brand)` only returns onboarding state for one brand at a time. Callers that need to know onboarding completion across all brands (e.g. Drumeo, Pianote, Guitareo, Singeo) for a user had no single call to get that.
+
+## Decision
+Added `getOnboardingStatus()` in `src/services/user/onboarding.ts`, hitting `GET /api/user-management-system/v1/users/{userId}/onboardings/status`. Returns `OnboardingStatus`: `has_completed_onboarding` plus a `brands: OnboardingBrandStatus[]` array (`brand`, `is_completed`, `completed_flow`, `completed_at`). Ran `npm run build-index` to regenerate `index.js`/`index.d.ts` so the new function is exported from the package.
+
+## Alternatives Considered
+No alternatives considered — this is additive to the existing per-brand `userOnboardingForBrand` function, not a replacement.
+
+## Consequences
+Consumers (musora-platform-frontend, MusoraApp) can now fetch all-brand onboarding status in a single request instead of looping `userOnboardingForBrand` per brand.

package/.claude/settings.local.json

@@ -24,7 +24,8 @@
       "mcp__github__create_pull_request",
       "mcp__github__search_pull_requests",
       "Bash(git commit *)",
-      "Bash(git add *)"
+      "Bash(git add *)",
+      "mcp__github__list_pull_requests"
     ]
   },
   "model": "sonnet",

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 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.167.2](https://github.com/railroadmedia/musora-content-services/compare/v2.167.1...v2.167.2) (2026-07-17)
+
+
+### Bug Fixes
+
+* **BEHLTP-210:** add non-destructive notification polling pause ([#1009](https://github.com/railroadmedia/musora-content-services/issues/1009)) ([3c0d783](https://github.com/railroadmedia/musora-content-services/commit/3c0d783ee7ae4f54c77f9d37299ba182eaa3ebb5))
+
 ### [2.167.1](https://github.com/railroadmedia/musora-content-services/compare/v2.167.0...v2.167.1) (2026-07-13)
 
 

package/package.json

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

package/src/contentTypeConfig.js

@@ -315,6 +315,7 @@ export const getNextLessonLessonParentTypes = [
   'song-tutorial',
   'learning-path-v2',
   'skill-pack',
+  'documentary',
 ]
 
 export const progressTypesMapping = {

package/src/index.d.ts

@@ -451,6 +451,7 @@ import {
 
 import {
 	getOnboardingRecommendedContent,
+	getOnboardingStatus,
 	initializeOnboardingFlow,
 	startOnboarding,
 	updateOnboarding,
@@ -707,6 +708,7 @@ declare module 'musora-content-services' {
 		getNavigateToForPlaylists,
 		getNewAndUpcoming,
 		getOnboardingRecommendedContent,
+		getOnboardingStatus,
 		getOwnedContent,
 		getPermissionsAdapter,
 		getPermissionsVersion,

package/src/index.js

@@ -455,6 +455,7 @@ import {
 
 import {
 	getOnboardingRecommendedContent,
+	getOnboardingStatus,
 	initializeOnboardingFlow,
 	startOnboarding,
 	updateOnboarding,
@@ -706,6 +707,7 @@ export {
 	getNavigateToForPlaylists,
 	getNewAndUpcoming,
 	getOnboardingRecommendedContent,
+	getOnboardingStatus,
 	getOwnedContent,
 	getPermissionsAdapter,
 	getPermissionsVersion,

package/src/services/contentProgress.js

@@ -173,7 +173,7 @@ export async function getNavigateTo(data) {
         const lastInteracted = await getLastInteractedOf(childrenIds)
         const lastInteractedStatus = childrenStates.get(lastInteracted)
 
-        if (['course', 'skill-pack', 'song-tutorial'].includes(content.type)) {
+        if (['course', 'skill-pack', 'song-tutorial', 'documentary'].includes(content.type)) {
           // todo(BEHSTP-325): remove if/else and make findIncompleteLesson able to return current lesson if `started`
           if (lastInteractedStatus === STATE_STARTED) {
             // send to last interacted

package/src/services/eventsAPI.js

@@ -3,6 +3,7 @@ import {fetchLiveEvent} from "./sanity"
 import { DataContext, PollingStateVersionKey } from './dataContext'
 
 const pollingStateContext = new DataContext(PollingStateVersionKey, fetchLiveEventPollingState)
+const NOTIFICATION_POLLING_INTERVAL_MS = 60_000
 
 /**
  * API for managing notifications and live event polling.
@@ -12,6 +13,7 @@ class EventsAPI {
     this.brand = 'drumeo'
     this.onNotificationStateUpdated = []
     this.pollingInterval = null
+    this.isNotificationPollingPaused = false
     this.isLiveEventPollingActive = true
     this.resumeLiveEventTimeout = null
   }
@@ -27,6 +29,7 @@ class EventsAPI {
    */
   async initialize({ brand = 'drumeo' } = {}) {
     this.brand = brand;
+    this.isNotificationPollingPaused = false;
     await this.setupAutoEvents();
     await this.checkNotifications();
   }
@@ -80,15 +83,56 @@ class EventsAPI {
         const ttlMs = pauseUntil - now;
         await this.pauseLiveEventCheck(ttlMs);
       }
-      this.pollingInterval = setInterval(() => {
-        this.checkNotifications();
-      }, 60000);
+      this.startNotificationInterval();
     } catch (error) {
       console.error('EventsApi: Failed to setup auto events:', error);
       this.checkNotifications();
     }
   }
 
+  /**
+   * Starts notification polling unless it is already active or explicitly paused.
+   */
+  startNotificationInterval() {
+    if (this.pollingInterval || this.isNotificationPollingPaused) {
+      return;
+    }
+
+    this.pollingInterval = setInterval(() => {
+      this.checkNotifications();
+    }, NOTIFICATION_POLLING_INTERVAL_MS);
+  }
+
+  /**
+   * Stops notification polling without removing notification subscribers.
+   */
+  stopNotificationInterval() {
+    if (!this.pollingInterval) {
+      return;
+    }
+
+    clearInterval(this.pollingInterval);
+    this.pollingInterval = null;
+  }
+
+  /**
+   * Pauses notification polling without resetting initialized state or subscribers.
+   */
+  pauseNotificationPolling() {
+    this.isNotificationPollingPaused = true;
+    this.stopNotificationInterval();
+  }
+
+  /**
+   * Resumes notification polling and immediately refreshes notification state.
+   * @returns {Promise<void>}
+   */
+  resumeNotificationPolling() {
+    this.isNotificationPollingPaused = false;
+    this.startNotificationInterval();
+    return this.checkNotifications();
+  }
+
 
   /**
    * Checks for unread notifications and triggers callbacks.
@@ -149,10 +193,8 @@ class EventsAPI {
   }
 
   destroy() {
-    if (this.pollingInterval) {
-      clearInterval(this.pollingInterval);
-      this.pollingInterval = null;
-    }
+    this.isNotificationPollingPaused = true;
+    this.stopNotificationInterval();
 
     if (this.resumeLiveEventTimeout) {
       clearTimeout(this.resumeLiveEventTimeout);

package/src/services/user/onboarding.ts

@@ -117,6 +117,28 @@ export async function userOnboardingForBrand(brand: string): Promise<Onboarding>
   )
 }
 
+export interface OnboardingBrandStatus {
+  brand: string
+  is_completed: boolean
+  completed_flow: string | null
+  completed_at: Date | null
+}
+
+export interface OnboardingStatus {
+  has_completed_onboarding: boolean
+  brands: OnboardingBrandStatus[]
+}
+
+/**
+ * Fetches the current user's onboarding completion status across all brands.
+ *
+ * @returns {Promise<OnboardingStatus>} - A promise that resolves with the cross-brand onboarding status.
+ * @throws {HttpError} - If the HTTP request fails.
+ */
+export async function getOnboardingStatus(): Promise<OnboardingStatus> {
+  return GET(`/api/user-management-system/v1/users/${globalConfig.sessionConfig.userId}/onboardings/status`)
+}
+
 export interface OnboardingRecommendedContent {
   id: number
   title: string

package/test/unit/content-progress/navigateTo.test.ts

@@ -254,6 +254,17 @@ describe('getNavigateTo', () => {
     expect(result[1]).toMatchObject({ id: 101 })
   })
 
+  test('documentary started lastInteracted started navigates to lastInteracted child', async () => {
+    mockProgressRecords = [
+      { content_id: 1, state: 'started', progress_percent: 50, updated_at: 1000 },
+      { content_id: 101, state: 'started', progress_percent: 100, updated_at: 900 },
+      { content_id: 102, state: 'started', progress_percent: 30, updated_at: 1000 },
+    ]
+    mockLastInteracted = 101
+    const result = await getNavigateTo([{ id: 1, type: 'documentary', children: [child(101), child(102)] }])
+    expect(result[1]).toMatchObject({ id: 101 })
+  })
+
   test('course started lastInteracted completed navigates to first incomplete after lastInteracted', async () => {
     mockProgressRecords = [
       { content_id: 1, state: 'started', progress_percent: 60, updated_at: 1000 },

package/test/unit/eventsAPI.test.ts

@@ -0,0 +1,159 @@
+import eventsAPISingleton from '../../src/services/eventsAPI.js'
+import { initializeTestService } from '../initializeTests.js'
+
+const notificationsModule = require('../../src/services/user/notifications.js')
+const EventsAPI = eventsAPISingleton.constructor as new () => typeof eventsAPISingleton
+
+function deferred<T>() {
+  let resolve!: (value: T) => void
+  const promise = new Promise<T>((res) => {
+    resolve = res
+  })
+
+  return { promise, resolve }
+}
+
+describe('EventsAPI notification polling lifecycle', () => {
+  let api: typeof eventsAPISingleton
+  let fetchUnreadCountMock: jest.SpyInstance
+
+  beforeEach(() => {
+    initializeTestService()
+    jest.useFakeTimers()
+
+    api = new EventsAPI()
+    jest.spyOn(api, 'initPollingControl').mockResolvedValue({})
+    fetchUnreadCountMock = jest
+      .spyOn(notificationsModule, 'fetchUnreadCount')
+      .mockResolvedValue({ data: 0 })
+  })
+
+  afterEach(() => {
+    api.destroy()
+    jest.useRealTimers()
+    jest.restoreAllMocks()
+  })
+
+  test('initialize keeps the existing polling behavior', async () => {
+    await api.initialize({ brand: 'pianote' })
+
+    expect(fetchUnreadCountMock).toHaveBeenCalledWith({ brand: 'pianote' })
+    expect(api.pollingInterval).not.toBeNull()
+
+    fetchUnreadCountMock.mockClear()
+    await jest.advanceTimersByTimeAsync(60000)
+
+    expect(fetchUnreadCountMock).toHaveBeenCalledTimes(1)
+  })
+
+  test('pause stops polling without removing subscribers', async () => {
+    const handler = jest.fn()
+    api.addNotificationStateUpdatedHandler(handler)
+    await api.initialize()
+    handler.mockClear()
+    fetchUnreadCountMock.mockClear()
+
+    api.pauseNotificationPolling()
+    await jest.advanceTimersByTimeAsync(120000)
+
+    expect(api.pollingInterval).toBeNull()
+    expect(api.onNotificationStateUpdated).toEqual([handler])
+    expect(fetchUnreadCountMock).not.toHaveBeenCalled()
+  })
+
+  test('resume starts one interval and immediately refreshes existing subscribers', async () => {
+    const handler = jest.fn()
+    api.addNotificationStateUpdatedHandler(handler)
+    await api.initialize()
+    api.pauseNotificationPolling()
+    fetchUnreadCountMock.mockResolvedValue({ data: 1, liveEvent: null })
+    fetchUnreadCountMock.mockClear()
+    handler.mockClear()
+
+    await api.resumeNotificationPolling()
+    const resumedInterval = api.pollingInterval
+    await api.resumeNotificationPolling()
+
+    expect(resumedInterval).not.toBeNull()
+    expect(api.pollingInterval).toBe(resumedInterval)
+    expect(fetchUnreadCountMock).toHaveBeenCalledTimes(2)
+    expect(handler).toHaveBeenLastCalledWith({ unreadCount: 1, liveEvent: null })
+  })
+
+  test('repeated pause calls are safe', async () => {
+    await api.initialize()
+
+    api.pauseNotificationPolling()
+    api.pauseNotificationPolling()
+
+    expect(api.pollingInterval).toBeNull()
+  })
+
+  test('pause during asynchronous setup prevents the interval from being created', async () => {
+    const pollingControl = deferred<Record<string, never>>()
+    jest.spyOn(api, 'initPollingControl').mockReturnValue(pollingControl.promise)
+
+    const initializePromise = api.initialize()
+    api.pauseNotificationPolling()
+    pollingControl.resolve({})
+    await initializePromise
+
+    expect(api.pollingInterval).toBeNull()
+    expect(fetchUnreadCountMock).toHaveBeenCalledTimes(1)
+  })
+
+  test('resume during asynchronous setup creates no duplicate interval', async () => {
+    const pollingControl = deferred<Record<string, never>>()
+    jest.spyOn(api, 'initPollingControl').mockReturnValue(pollingControl.promise)
+
+    const initializePromise = api.initialize()
+    api.pauseNotificationPolling()
+    const resumePromise = api.resumeNotificationPolling()
+    const resumedInterval = api.pollingInterval
+    pollingControl.resolve({})
+    await Promise.all([initializePromise, resumePromise])
+
+    expect(resumedInterval).not.toBeNull()
+    expect(api.pollingInterval).toBe(resumedInterval)
+  })
+
+  test('pause and resume while the initial unread request is pending restores polling', async () => {
+    const initialUnreadCount = deferred<{ data: number }>()
+    fetchUnreadCountMock
+      .mockReturnValueOnce(initialUnreadCount.promise)
+      .mockResolvedValue({ data: 1 })
+
+    const initializePromise = api.initialize()
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(api.pollingInterval).not.toBeNull()
+
+    api.pauseNotificationPolling()
+    const resumePromise = api.resumeNotificationPolling()
+
+    expect(api.pollingInterval).not.toBeNull()
+    initialUnreadCount.resolve({ data: 0 })
+    await Promise.all([initializePromise, resumePromise])
+
+    fetchUnreadCountMock.mockClear()
+    await jest.advanceTimersByTimeAsync(60000)
+    expect(fetchUnreadCountMock).toHaveBeenCalledTimes(1)
+  })
+
+  test('destroy remains a full teardown and initialize can start again', async () => {
+    api.addNotificationStateUpdatedHandler(jest.fn())
+    await api.initialize()
+
+    api.destroy()
+
+    expect(api.pollingInterval).toBeNull()
+    expect(api.onNotificationStateUpdated).toEqual([])
+    expect(api.isLiveEventPollingActive).toBe(false)
+
+    fetchUnreadCountMock.mockClear()
+    await api.initialize()
+
+    expect(api.pollingInterval).not.toBeNull()
+    expect(fetchUnreadCountMock).toHaveBeenCalledTimes(1)
+  })
+})