musora-content-services 2.165.4 → 2.166.0

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 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.166.0](https://github.com/railroadmedia/musora-content-services/compare/v2.165.5...v2.166.0) (2026-07-02)
+
+
+### Features
+
+* **BEHLPT-186:**  subscription upgrade endpoints ([#1003](https://github.com/railroadmedia/musora-content-services/issues/1003)) ([9da55f2](https://github.com/railroadmedia/musora-content-services/commit/9da55f24708976190317a3b69381acbccce2f33c))
+
+
+### Bug Fixes
+
+* **BR-671:** fix Latin/World style search ([#1002](https://github.com/railroadmedia/musora-content-services/issues/1002)) ([25fdff8](https://github.com/railroadmedia/musora-content-services/commit/25fdff80c6279e8568ea057ac250f7e057717ccf))
+
+### [2.165.5](https://github.com/railroadmedia/musora-content-services/compare/v2.165.4...v2.165.5) (2026-06-25)
+
+
+### Bug Fixes
+
+* **recommender:** omit web credentials on request ([#1001](https://github.com/railroadmedia/musora-content-services/issues/1001)) ([d03179a](https://github.com/railroadmedia/musora-content-services/commit/d03179a829e1048304b42493c34743999272da7a))
+
 ### [2.165.4](https://github.com/railroadmedia/musora-content-services/compare/v2.165.3...v2.165.4) (2026-06-19)
 
 ### [2.165.3](https://github.com/railroadmedia/musora-content-services/compare/v2.165.1...v2.165.3) (2026-06-19)

package/package.json

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

package/src/contentTypeConfig.js

@@ -876,7 +876,14 @@ function createTypeConditions(lessonTypes) {
  * Filter handler registry - maps filter keys to their handler functions
  */
 const filterHandlers = {
-  style: (value) => `"${value}" in genre[]->name`,
+  style: (value) => {
+    const hasMultipleStyles = value.includes('/')
+    const styles = [value]
+    if (hasMultipleStyles) {
+      styles.push(...value.split('/').map((s) => s.trim()))
+    }
+    return styles.map((style) => `"${style}" in genre[]->name`).join(' || ')
+  },
 
   difficulty: (value) => {
     return `difficulty_string == "${value}"`

package/src/infrastructure/http/HttpClient.ts

@@ -17,17 +17,20 @@ export class HttpClient {
   private token: string | null
   private headerProvider: HeaderProvider
   private requestExecutor: RequestExecutor
+  private credentials: RequestCredentials
 
   constructor(
     baseUrl: string = '',
-    token: string | null = null,
-    headerProvider: HeaderProvider = new DefaultHeaderProvider(),
-    requestExecutor: RequestExecutor = new FetchRequestExecutor()
+    token?: string | null,
+    headerProvider?: HeaderProvider,
+    requestExecutor?: RequestExecutor,
+    credentials?: RequestCredentials
   ) {
     this.baseUrl = baseUrl || globalConfig?.baseUrl || ''
     this.token = token || globalConfig?.sessionConfig?.token || null
-    this.headerProvider = headerProvider
-    this.requestExecutor = requestExecutor
+    this.headerProvider = headerProvider || new DefaultHeaderProvider()
+    this.requestExecutor = requestExecutor || new FetchRequestExecutor()
+    this.credentials = credentials || 'include'
   }
 
   public setToken(token: string): void {
@@ -35,7 +38,7 @@ export class HttpClient {
   }
 
   public clearToken(): void {
-    this.token = null;
+    this.token = null
   }
 
   public async get<T>(url: string, options: _RequestOptions = {}): Promise<T> {
@@ -101,7 +104,7 @@ export class HttpClient {
     const options: RequestOptions = {
       method,
       headers,
-      credentials: 'include',
+      credentials: this.credentials,
     }
 
     if (cache) {

package/src/services/multi-user-accounts/multi-user-accounts.ts

@@ -20,7 +20,9 @@ export interface InviteResponse {
   can_be_accepted: boolean
   is_account_valid: boolean
   is_invite_active: boolean
-  can_user_join: boolean
+  can_user_join: boolean // deprecated in favour of is_user_part_of_existing_mua which is more descriptive
+  is_user_active_subscriber: boolean
+  is_user_part_of_existing_mua: boolean
   primary_user_name: string
   product_name: string
   // These fields leak user information and are excluded entirely for the public endpoint

package/src/services/progress/index.ts

@@ -1,6 +1,13 @@
 import * as state from './state'
 import * as collections from './collections'
+import * as utils from './utils'
 
-export const Progress = { ...state, ...collections }
+export const Progress = { ...state, ...collections, ...utils }
 
-export type { ProgressContentFilter, ProgressQueryOptions, StartedOrCompletedOptions } from './types'
+export type {
+  ProgressContentFilter,
+  ProgressQueryOptions,
+  ProgressSnapshot,
+  RecordIdParts,
+  StartedOrCompletedOptions,
+} from './types'

package/src/services/progress/internal/bubble.ts

@@ -0,0 +1,138 @@
+import { db } from '../../sync'
+import { CollectionParameter } from '../../sync/models/ContentProgress'
+import type { Hierarchy, ProgressMetadata, ProgressSnapshot } from '../types'
+import { getByIds } from './queries'
+
+const MAX_DEPTH = 3
+
+export const filterOutNegativeProgress = (
+  progresses: Record<number, number>,
+  existingProgresses: Record<number, ProgressSnapshot>
+): Record<number, number> =>
+  Object.fromEntries(
+    Object.entries(progresses).filter(
+      ([id, progress]) => progress >= (existingProgresses[Number(id)]?.progress ?? 0)
+    )
+  )
+
+export const getChildrenToDepth = (parentId: number, hierarchy: Hierarchy, depth = 1): number[] => {
+  const childIds = hierarchy.children[parentId] ?? []
+  let allChildrenIds: number[] = [...childIds]
+  childIds.forEach((id) => {
+    allChildrenIds = allChildrenIds.concat(getChildrenToDepth(id, hierarchy, depth - 1))
+  })
+  return allChildrenIds
+}
+
+export const getAncestorAndSiblingIds = (
+  hierarchy: Hierarchy,
+  contentId: number,
+  depth = 1
+): number[] => {
+  if (depth > MAX_DEPTH) return []
+
+  const parentId = hierarchy?.parents?.[contentId]
+  if (!parentId) return []
+
+  if (parentId === contentId) return []
+
+  const siblingIds = hierarchy?.children?.[parentId] ?? []
+  const allIds = [
+    ...siblingIds,
+    parentId,
+    ...getAncestorAndSiblingIds(hierarchy, parentId, depth + 1),
+  ]
+  return [...new Set(allIds)]
+}
+
+export const averageProgressesFor = (
+  hierarchy: Hierarchy,
+  contentId: number,
+  progressData: Map<number, number>,
+  depth = 1
+): Record<number, number> => {
+  if (depth > MAX_DEPTH) return {}
+
+  const parentId = hierarchy?.parents?.[contentId]
+  if (!parentId) return {}
+
+  const parentChildProgress =
+    hierarchy?.children?.[parentId]?.map((childId) => progressData.get(childId) ?? 0) ?? []
+
+  const avgParentProgress =
+    parentChildProgress.length > 0
+      ? Math.round(parentChildProgress.reduce((a, b) => a + b, 0) / parentChildProgress.length)
+      : 0
+
+  return {
+    ...averageProgressesFor(hierarchy, parentId, progressData, depth + 1),
+    [parentId]: avgParentProgress,
+  }
+}
+
+export const trickleProgress = (
+  hierarchy: Hierarchy,
+  contentId: number,
+  progress: number
+): Record<number, number> => {
+  const descendantIds = getChildrenToDepth(contentId, hierarchy, MAX_DEPTH)
+  return Object.fromEntries(descendantIds.map((id) => [id, progress]))
+}
+
+export const bubbleProgress = async (
+  hierarchy: Hierarchy,
+  contentId: number,
+  collection?: CollectionParameter
+): Promise<Record<number, number>> => {
+  const ids = getAncestorAndSiblingIds(hierarchy, contentId)
+  const progresses = await getByIds(ids, (p) => p.progress_percent, 0, collection)
+  return averageProgressesFor(hierarchy, contentId, progresses)
+}
+
+export const computeBubbleTrickleProgresses = async (
+  contentId: number,
+  progress: number,
+  hierarchy: Hierarchy,
+  collection?: CollectionParameter,
+  { bubble = true, trickle = true }: { bubble?: boolean; trickle?: boolean } = {}
+): Promise<Record<number, number>> => ({
+  ...(trickle ? trickleProgress(hierarchy, contentId, progress) : {}),
+  ...(bubble ? await bubbleProgress(hierarchy, contentId, collection) : {}),
+})
+
+export interface BubbleAndTrickleOptions {
+  isResetAction?: boolean
+  accessedDirectly?: boolean
+}
+
+export const bubbleAndTrickleProgressesSafely = async (
+  progresses: Record<number, number>,
+  metadata: Record<number, ProgressMetadata>,
+  options: BubbleAndTrickleOptions = { accessedDirectly: true },
+  collection?: CollectionParameter
+): Promise<void> => {
+  let eraseProgresses: Record<number, number> = {}
+  let activeProgresses = progresses
+
+  if (options.isResetAction) {
+    eraseProgresses = Object.fromEntries(
+      Object.entries(progresses).filter(([, pct]) => pct === 0)
+    ) as Record<number, number>
+    activeProgresses = Object.fromEntries(
+      Object.entries(progresses).filter(([, pct]) => pct > 0)
+    ) as Record<number, number>
+  }
+
+  if (Object.keys(activeProgresses).length > 0) {
+    await db.contentProgress.recordProgressMany(activeProgresses, collection, metadata, {
+      skipPush: true,
+      accessedDirectly: options.accessedDirectly,
+      allowRegression: true,
+    })
+  }
+
+  if (Object.keys(eraseProgresses).length > 0) {
+    const eraseIds = Object.keys(eraseProgresses).map(Number)
+    await db.contentProgress.eraseProgressMany(eraseIds, collection, { skipPush: true })
+  }
+}

package/src/services/progress/internal/queries.ts

@@ -1,9 +1,12 @@
 import { db } from '../../sync'
-import { CollectionParameter } from '../../sync/models/ContentProgress'
+import type { ModelSerialized } from '../../sync/serializers'
+import ContentProgress, { CollectionParameter } from '../../sync/models/ContentProgress'
+
+type Selector<V> = (p: ModelSerialized<ContentProgress>) => V
 
 export const getByIds = async <V>(
   contentIds: number[],
-  dataKey: string,
+  selector: Selector<V>,
   defaultValue: V,
   collection?: CollectionParameter
 ): Promise<Map<number, V>> => {
@@ -12,7 +15,7 @@ export const getByIds = async <V>(
   const progress = new Map(contentIds.map((id) => [id, defaultValue]))
   await db.contentProgress.getSomeProgressByContentIds(contentIds, collection).then((r) => {
     r.data.forEach((p) => {
-      progress.set(p.content_id, p[dataKey] ?? defaultValue)
+      progress.set(p.content_id, selector(p) ?? defaultValue)
     })
   })
   return progress
@@ -20,24 +23,39 @@ export const getByIds = async <V>(
 
 export const getById = async <V>(
   contentId: number,
-  dataKey: string,
+  selector: Selector<V>,
   defaultValue: V,
   collection?: CollectionParameter
 ): Promise<V> => {
   if (!contentId) return defaultValue
   return db.contentProgress
     .getOneProgressByContentId(contentId, collection)
-    .then((r) => r.data?.[dataKey] ?? defaultValue)
+    .then((r) => (r.data ? selector(r.data) : defaultValue) ?? defaultValue)
 }
 
-export const getByRecordIds = async <V>(ids: string[], dataKey: string, defaultValue: V) => {
+export const getByRecordIds = async <V>(ids: string[], selector: Selector<V>, defaultValue: V) => {
   const progress = Object.fromEntries(ids.map((id) => [id, defaultValue]))
 
   await db.contentProgress.getSomeProgressByRecordIds(ids).then((r) => {
     r.data.forEach((p) => {
-      progress[p.id] = p[dataKey] ?? defaultValue
+      progress[p.id] = selector(p) ?? defaultValue
     })
   })
 
   return progress
 }
+
+export const queryById =
+  <V>(selector: Selector<V>, defaultValue: V) =>
+  (contentId: number, collection?: CollectionParameter) =>
+    getById(contentId, selector, defaultValue, collection)
+
+export const queryByIds =
+  <V>(selector: Selector<V>, defaultValue: V) =>
+  (contentIds: number[], collection?: CollectionParameter) =>
+    getByIds(contentIds, selector, defaultValue, collection)
+
+export const queryByRecordIds =
+  <V>(selector: Selector<V>, defaultValue: V) =>
+  (ids: string[]) =>
+    getByRecordIds(ids, selector, defaultValue)

package/src/services/progress/state.ts

@@ -1,20 +1,32 @@
 import { db } from '../sync'
-import { COLLECTION_TYPE, CollectionParameter } from '../sync/models/ContentProgress'
-import { getById, getByIds, getByRecordIds } from './internal/queries'
+import type { ModelSerialized } from '../sync/serializers'
+import ContentProgress, { COLLECTION_TYPE, CollectionParameter } from '../sync/models/ContentProgress'
+import { queryById, queryByIds, queryByRecordIds } from './internal/queries'
+import type { ProgressSnapshot } from './types'
 
-export const state = async (contentId: number, collection?: CollectionParameter) =>
-  getById(contentId, 'state', '', collection)
-
-export const stateByIds = async (contentIds: number[], collection?: CollectionParameter) =>
-  getByIds(contentIds, 'state', '', collection)
-
-export const stateByRecordIds = async (ids: string[]) => getByRecordIds(ids, 'state', '')
+const buildSnapshotMap = <K extends string | number>(
+  ids: K[],
+  records: ModelSerialized<ContentProgress>[],
+  keyOf: (p: ModelSerialized<ContentProgress>) => K,
+  lastUpdateOf: (p: ModelSerialized<ContentProgress>) => number
+): Map<K, ProgressSnapshot> => {
+  const overrides = new Map(
+    records.map((p) => [
+      keyOf(p),
+      { last_update: lastUpdateOf(p), progress: p.progress_percent, status: p.state as string },
+    ])
+  )
+  return new Map(
+    ids.map((id) => [id, overrides.get(id) ?? { last_update: 0, progress: 0, status: '' }])
+  )
+}
 
-export const playbackPositionByIds = async (contentIds: number[], collection?: CollectionParameter) =>
-  getByIds(contentIds, 'resume_time_seconds', 0, collection)
+export const state = queryById((p) => p.state as string, '')
+export const stateByIds = queryByIds((p) => p.state as string, '')
+export const stateByRecordIds = queryByRecordIds((p) => p.state as string, '')
 
-export const playbackPositionByRecordIds = async (ids: string[]) =>
-  getByRecordIds(ids, 'resume_time_seconds', 0)
+export const playbackPositionByIds = queryByIds((p) => p.resume_time_seconds ?? 0, 0)
+export const playbackPositionByRecordIds = queryByRecordIds((p) => p.resume_time_seconds ?? 0, 0)
 
 export const lastInteractedOf = (
   contentIds: number[],
@@ -48,3 +60,23 @@ export const incompleteLesson = (
 
   return ids[0]
 }
+
+export const snapshotByIds = async (
+  contentIds: number[],
+  collection?: CollectionParameter
+): Promise<Map<number, ProgressSnapshot>> =>
+  db.contentProgress
+    .getSomeProgressByContentIds(contentIds, collection)
+    .then((r) => buildSnapshotMap(contentIds, r.data, (p) => p.content_id, (p) => p.last_interacted_a_la_carte))
+
+export const snapshotByRecordIds = async (
+  ids: string[]
+): Promise<Record<string, ProgressSnapshot>> =>
+  db.contentProgress
+    .getSomeProgressByRecordIds(ids)
+    .then((r) => Object.fromEntries(buildSnapshotMap(ids, r.data, (p) => p.id, (p) => p.updated_at)))
+
+export const methodAccessedIds = async (contentIds: number[]): Promise<number[]> =>
+  db.contentProgress
+    .getSomeProgressWhereLastAccessedFromMethod(contentIds)
+    .then((r) => r.data.map((record) => record.content_id))

package/src/services/progress/types.ts

@@ -1,3 +1,29 @@
+export interface ProgressMetadata {
+  brand: string
+  parent_id: number
+  type: string
+}
+
+export interface Hierarchy {
+  parents: Record<number, number>
+  children: Record<number, number[]>
+  metadata?: Record<number, ProgressMetadata>
+}
+
+export interface RecordIdParts {
+  contentId: number
+  collection: {
+    type: string
+    id: number
+  }
+}
+
+export interface ProgressSnapshot {
+  last_update: number
+  progress: number
+  status: string
+}
+
 export interface ProgressContentFilter {
   aLaCarte?: boolean
   learningPaths?: boolean

package/src/services/progress/utils.ts

@@ -0,0 +1,28 @@
+import {
+  COLLECTION_ID_SELF,
+  COLLECTION_TYPE,
+  CollectionParameter,
+} from '../sync/models/ContentProgress'
+import type { RecordIdParts } from './types'
+
+export const generateRecordId = (
+  contentId: number,
+  collection?: CollectionParameter
+): string | null => {
+  return `${contentId}:${collection?.type || COLLECTION_TYPE.SELF}:${collection?.id || COLLECTION_ID_SELF}`
+}
+
+export const extractFromRecordId = (recordId: string): RecordIdParts => {
+  const parts = recordId.split(':')
+  const contentId = Number(parts[0])
+  const collectionType = parts[1]
+  const collectionId = Number(parts[2])
+
+  return {
+    contentId,
+    collection: {
+      type: collectionType || COLLECTION_TYPE.SELF,
+      id: collectionId || COLLECTION_ID_SELF,
+    },
+  }
+}

package/src/services/recommendations.js

@@ -4,7 +4,6 @@
 
 import { globalConfig } from './config.js'
 import { GET, HttpClient } from '../infrastructure/http/HttpClient.ts'
-import { fetchByRailContentIds } from './sanity.js'
 
 /**
  * Exported functions that are excluded from index generation.
@@ -14,7 +13,7 @@ import { fetchByRailContentIds } from './sanity.js'
 const excludeFromGeneratedIndex = []
 
 const RECOMMENDER_URL = 'https://recommender.musora.com'
-const recommenderClient = new HttpClient(RECOMMENDER_URL)
+const recommenderClient = new HttpClient(RECOMMENDER_URL, null, null, null, 'omit')
 
 /**
  * Fetches similar content to the provided content id
@@ -32,23 +31,23 @@ export async function fetchSimilarItems(content_id, brand, count = 10) {
   if (!content_id) {
     return []
   }
-    content_id = parseInt(content_id)
-    const data = {
-      brand: brand,
-      content_ids: content_id,
-      num_similar: count + 1,
-      page_size: count + 1,
-      page: 1,
-      exclude_interacted: true
-    }
-    const url = `/similar_items/`
-    try {
-      const response = await recommenderClient.post(url, data)
-      return response['similar_items'].filter((item) => item !== content_id).slice(0, count)
-    } catch (error) {
-      console.error('Fetch error:', error)
-      return null
-    }
+  content_id = parseInt(content_id)
+  const data = {
+    brand: brand,
+    content_ids: content_id,
+    num_similar: count + 1,
+    page_size: count + 1,
+    page: 1,
+    exclude_interacted: true,
+  }
+  const url = `/similar_items/`
+  try {
+    const response = await recommenderClient.post(url, data)
+    return response['similar_items'].filter((item) => item !== content_id).slice(0, count)
+  } catch (error) {
+    console.error('Fetch error:', error)
+    return null
+  }
 }
 
 /**
@@ -134,9 +133,10 @@ export async function rankItems(brand, content_ids) {
 export async function recommendations(brand, { section = '', contentTypes = [] } = {}) {
   section = section.toUpperCase().replace('-', '_')
   const sectionString = section ? `&section=${section}` : ''
-  const contentTypesString = contentTypes.length > 0
-    ? contentTypes.map(type => `&content_types[]=${encodeURIComponent(type)}`).join('')
-    : ''
+  const contentTypesString =
+    contentTypes.length > 0
+      ? contentTypes.map((type) => `&content_types[]=${encodeURIComponent(type)}`).join('')
+      : ''
   const url = `/api/content/v1/recommendations?brand=${brand}${sectionString}${contentTypesString}`
   return await GET(url)
 }

package/src/services/user/memberships.ts

@@ -148,6 +148,7 @@ export async function fetchRechargeTokens(): Promise<RechargeTokens> {
  * Upgrades the user's subscription or provides a prefilled add-to-cart URL.
  *
  * @param {boolean} featureFlag - MultiUserAccount feature Flag - default false
+ * @param {string} sku- product sku to upgrade to, required if feature flag is set
  *
  * @returns {Promise<UpgradeSubscriptionResponse>} A promise that resolves to an object containing either:
  *  - {string} action - The action performed (e.g., 'instant_upgrade').
@@ -163,10 +164,11 @@ export async function fetchRechargeTokens(): Promise<RechargeTokens> {
  *   .then(response => console.log(response))
  *   .catch(error => console.error(error));
  */
-export async function upgradeSubscription(featureFlag = false): Promise<UpgradeSubscriptionResponse> {
+export async function upgradeSubscription(featureFlag = false, sku): Promise<UpgradeSubscriptionResponse> {
   let featureFlagValue = featureFlag ? 1 : 0
+  let skuValue = sku ? `&sku=${sku}` : ''
   const httpClient = new HttpClient(globalConfig.baseUrl)
-  return httpClient.get<UpgradeSubscriptionResponse>(`${baseUrl}/v1/update-subscription?${multiUserAccountFeatureFlag}=${featureFlagValue}`)
+  return httpClient.get<UpgradeSubscriptionResponse>(`${baseUrl}/v1/update-subscription?${multiUserAccountFeatureFlag}=${featureFlagValue}${skuValue}`)
 }
 
 /**

package/test/unit/HttpClient.test.ts

@@ -35,6 +35,22 @@ describe('HttpClient', () => {
     })
   })
 
+  describe('credentials', () => {
+    test('should default to include', async () => {
+      const client = new HttpClient(baseUrl, token, mockHeaderProvider, mockRequestExecutor)
+      await client.get('/test')
+      const options = mockRequestExecutor.execute.mock.calls[0][1]
+      expect(options.credentials).toBe('include')
+    })
+
+    test('should use provided credentials value', async () => {
+      const client = new HttpClient(baseUrl, token, mockHeaderProvider, mockRequestExecutor, 'omit')
+      await client.get('/test')
+      const options = mockRequestExecutor.execute.mock.calls[0][1]
+      expect(options.credentials).toBe('omit')
+    })
+  })
+
   describe('setToken', () => {
     test('should update the token', () => {
       const newToken = 'new-test-token'

package/test/unit/recommendations.test.js

@@ -0,0 +1,47 @@
+import { fetchSimilarItems } from '../../src/services/recommendations.js'
+
+jest.mock('../../src/infrastructure/http/HttpClient.ts', () => {
+  const mockPost = jest.fn()
+  const MockHttpClient = jest.fn().mockImplementation(() => ({ post: mockPost }))
+  MockHttpClient._mockPost = mockPost
+  return { HttpClient: MockHttpClient, GET: jest.fn() }
+})
+
+const mockPost = () => require('../../src/infrastructure/http/HttpClient.ts').HttpClient._mockPost
+
+describe('fetchSimilarItems', () => {
+  beforeEach(() => {
+    mockPost().mockReset()
+  })
+
+  test('returns empty array when content_id is falsy', async () => {
+    expect(await fetchSimilarItems(null, 'drumeo')).toEqual([])
+    expect(await fetchSimilarItems(0, 'drumeo')).toEqual([])
+    expect(await fetchSimilarItems('', 'drumeo')).toEqual([])
+  })
+
+  test('parses string content_id to integer for filtering', async () => {
+    mockPost().mockResolvedValue({ similar_items: [42, 99] })
+    const result = await fetchSimilarItems('42', 'drumeo', 10)
+    expect(result).not.toContain(42)
+    expect(result).toEqual([99])
+  })
+
+  test('filters out the requested content_id from results', async () => {
+    mockPost().mockResolvedValue({ similar_items: [1, 2, 3] })
+    const result = await fetchSimilarItems(2, 'drumeo', 10)
+    expect(result).toEqual([1, 3])
+  })
+
+  test('respects count limit', async () => {
+    mockPost().mockResolvedValue({ similar_items: [10, 20, 30, 40, 50, 60] })
+    const result = await fetchSimilarItems(99, 'drumeo', 3)
+    expect(result).toHaveLength(3)
+  })
+
+  test('returns null on error', async () => {
+    mockPost().mockRejectedValue(new Error('network failure'))
+    const result = await fetchSimilarItems(1, 'drumeo')
+    expect(result).toBeNull()
+  })
+})

package/test/unit/services/progress-internal/bubble.test.ts

@@ -0,0 +1,279 @@
+let mockProgressRecords: any[] = []
+let mockRecordProgressMany = jest.fn()
+let mockEraseProgressMany = jest.fn()
+
+const repoMocks = {
+  contentProgress: {
+    getSomeProgressByContentIds: jest.fn().mockImplementation((contentIds: number[]) => {
+      const records = mockProgressRecords.filter((r) => contentIds.includes(r.content_id))
+      return Promise.resolve({ data: records })
+    }),
+    recordProgressMany: mockRecordProgressMany,
+    eraseProgressMany: mockEraseProgressMany,
+  },
+}
+
+jest.mock('../../../../src/services/sync/repository-proxy', () => ({
+  __esModule: true,
+  default: repoMocks,
+  ...repoMocks,
+}))
+
+import {
+  averageProgressesFor,
+  bubbleAndTrickleProgressesSafely,
+  bubbleProgress,
+  computeBubbleTrickleProgresses,
+  filterOutNegativeProgress,
+  getAncestorAndSiblingIds,
+  getChildrenToDepth,
+  trickleProgress,
+} from '../../../../src/services/progress/internal/bubble'
+import type { Hierarchy } from '../../../../src/services/progress/types'
+import { COLLECTION_TYPE } from '../../../../src/services/sync/models/ContentProgress'
+
+beforeEach(() => {
+  jest.clearAllMocks()
+  mockProgressRecords = []
+  mockRecordProgressMany.mockResolvedValue({ data: null })
+  mockEraseProgressMany.mockResolvedValue({ data: null })
+})
+
+describe('filterOutNegativeProgress', () => {
+  test('drops entry when new progress is less than existing', () => {
+    const result = filterOutNegativeProgress(
+      { 101: 30 },
+      { 101: { progress: 70, last_update: 0, status: 'started' } }
+    )
+    expect(result).not.toHaveProperty('101')
+  })
+
+  test('keeps entry when new progress equals existing', () => {
+    const result = filterOutNegativeProgress(
+      { 101: 50 },
+      { 101: { progress: 50, last_update: 0, status: 'started' } }
+    )
+    expect(result[101]).toBe(50)
+  })
+
+  test('keeps entry when new progress is greater than existing', () => {
+    const result = filterOutNegativeProgress(
+      { 101: 80 },
+      { 101: { progress: 50, last_update: 0, status: 'started' } }
+    )
+    expect(result[101]).toBe(80)
+  })
+
+  test('keeps entry when no existing snapshot', () => {
+    const result = filterOutNegativeProgress({ 101: 10 }, {})
+    expect(result[101]).toBe(10)
+  })
+
+  test('drops only entries below existing, keeps others in mixed set', () => {
+    const result = filterOutNegativeProgress(
+      { 101: 20, 102: 80, 103: 40 },
+      {
+        101: { progress: 70, last_update: 0, status: 'started' },
+        102: { progress: 20, last_update: 0, status: 'started' },
+        103: { progress: 0, last_update: 0, status: '' },
+      }
+    )
+    expect(result).not.toHaveProperty('101')
+    expect(result[102]).toBe(80)
+    expect(result[103]).toBe(40)
+  })
+
+  test('returns new object, does not mutate input', () => {
+    const progresses = { 101: 10 }
+    const result = filterOutNegativeProgress(progresses, {
+      101: { progress: 50, last_update: 0, status: 'started' },
+    })
+    expect(result).not.toBe(progresses)
+    expect(progresses[101]).toBe(10)
+  })
+})
+
+describe('getChildrenToDepth', () => {
+  const hierarchy: Hierarchy = {
+    parents: { 2: 1, 3: 1, 4: 2 },
+    children: { 1: [2, 3], 2: [4], 3: [], 4: [] },
+  }
+
+  test('returns direct children', () => {
+    expect(getChildrenToDepth(1, hierarchy)).toEqual(expect.arrayContaining([2, 3]))
+  })
+
+  test('returns empty when no children', () => {
+    expect(getChildrenToDepth(4, hierarchy)).toEqual([])
+  })
+
+  test('returns empty for unknown parent', () => {
+    expect(getChildrenToDepth(99, hierarchy)).toEqual([])
+  })
+})
+
+describe('getAncestorAndSiblingIds', () => {
+  const hierarchy: Hierarchy = {
+    parents: { 2: 1, 3: 1, 4: 2, 5: 2 },
+    children: { 1: [2, 3], 2: [4, 5] },
+  }
+
+  test('returns siblings and parent for child node', () => {
+    const result = getAncestorAndSiblingIds(hierarchy, 4)
+    expect(result).toEqual(expect.arrayContaining([5, 2]))
+  })
+
+  test('returns empty for root', () => {
+    expect(getAncestorAndSiblingIds(hierarchy, 1)).toEqual([])
+  })
+
+  test('handles circular dependency without infinite loop', () => {
+    const circular: Hierarchy = { parents: { 1: 1 }, children: { 1: [] } }
+    expect(getAncestorAndSiblingIds(circular, 1)).toEqual([])
+  })
+})
+
+describe('averageProgressesFor', () => {
+  const hierarchy: Hierarchy = {
+    parents: { 2: 1, 3: 1, 4: 2, 5: 2 },
+    children: { 1: [2, 3], 2: [4, 5] },
+  }
+
+  test('averages child progresses up the chain', () => {
+    const progress = new Map<number, number>([
+      [4, 100],
+      [5, 0],
+      [2, 50],
+      [3, 50],
+    ])
+    const result = averageProgressesFor(hierarchy, 4, progress)
+    expect(result[2]).toBe(50)
+    expect(result[1]).toBe(50)
+  })
+
+  test('returns empty for root', () => {
+    expect(averageProgressesFor(hierarchy, 1, new Map())).toEqual({})
+  })
+
+  test('treats missing child progress as 0', () => {
+    const progress = new Map<number, number>([[4, 80]])
+    const result = averageProgressesFor(hierarchy, 4, progress)
+    expect(result[2]).toBe(40)
+  })
+})
+
+describe('trickleProgress', () => {
+  const hierarchy: Hierarchy = {
+    parents: { 2: 1, 3: 1, 4: 2 },
+    children: { 1: [2, 3], 2: [4], 3: [], 4: [] },
+  }
+
+  test('returns descendants with given progress', () => {
+    const result = trickleProgress(hierarchy, 1, 75)
+    expect(result[2]).toBe(75)
+    expect(result[3]).toBe(75)
+  })
+
+  test('returns empty when no descendants', () => {
+    expect(trickleProgress(hierarchy, 4, 100)).toEqual({})
+  })
+})
+
+describe('bubbleProgress', () => {
+  const hierarchy: Hierarchy = {
+    parents: { 2: 1, 3: 1 },
+    children: { 1: [2, 3] },
+  }
+
+  test('aggregates sibling progresses into parent', async () => {
+    mockProgressRecords = [
+      { content_id: 2, progress_percent: 100 },
+      { content_id: 3, progress_percent: 0 },
+    ]
+    const result = await bubbleProgress(hierarchy, 2)
+    expect(result[1]).toBe(50)
+  })
+})
+
+describe('computeBubbleTrickleProgresses', () => {
+  const hierarchy: Hierarchy = {
+    parents: { 2: 1 },
+    children: { 1: [2], 2: [] },
+  }
+
+  test('combines bubble and trickle', async () => {
+    mockProgressRecords = [{ content_id: 2, progress_percent: 80 }]
+    const result = await computeBubbleTrickleProgresses(2, 80, hierarchy)
+    expect(result[1]).toBe(80)
+  })
+
+  test('respects { bubble: false }', async () => {
+    mockProgressRecords = [{ content_id: 2, progress_percent: 80 }]
+    const result = await computeBubbleTrickleProgresses(2, 80, hierarchy, undefined, {
+      bubble: false,
+    })
+    expect(result).not.toHaveProperty('1')
+  })
+
+  test('respects { trickle: false }', async () => {
+    const result = await computeBubbleTrickleProgresses(1, 50, hierarchy, undefined, {
+      trickle: false,
+    })
+    expect(result).not.toHaveProperty('2')
+  })
+})
+
+describe('bubbleAndTrickleProgressesSafely', () => {
+  test('passes positive progresses to recordProgressMany', async () => {
+    await bubbleAndTrickleProgressesSafely({ 1: 50, 2: 100 }, {})
+    expect(mockRecordProgressMany).toHaveBeenCalledWith(
+      { 1: 50, 2: 100 },
+      undefined,
+      {},
+      { skipPush: true, accessedDirectly: true, allowRegression: true }
+    )
+    expect(mockEraseProgressMany).not.toHaveBeenCalled()
+  })
+
+  test('isResetAction separates zero progresses into eraseProgressMany', async () => {
+    await bubbleAndTrickleProgressesSafely(
+      { 1: 50, 2: 0, 3: 0 },
+      {},
+      { isResetAction: true }
+    )
+    expect(mockRecordProgressMany).toHaveBeenCalledWith(
+      { 1: 50 },
+      undefined,
+      {},
+      expect.objectContaining({ allowRegression: true })
+    )
+    expect(mockEraseProgressMany).toHaveBeenCalledWith([2, 3], undefined, { skipPush: true })
+  })
+
+  test('forwards collection argument', async () => {
+    const collection = { type: COLLECTION_TYPE.LEARNING_PATH, id: 10 }
+    await bubbleAndTrickleProgressesSafely({ 1: 50 }, {}, {}, collection)
+    expect(mockRecordProgressMany).toHaveBeenCalledWith(
+      { 1: 50 },
+      collection,
+      {},
+      expect.anything()
+    )
+  })
+
+  test('forwards accessedDirectly option', async () => {
+    await bubbleAndTrickleProgressesSafely({ 1: 50 }, {}, { accessedDirectly: false })
+    expect(mockRecordProgressMany).toHaveBeenCalledWith(
+      { 1: 50 },
+      undefined,
+      {},
+      expect.objectContaining({ accessedDirectly: false })
+    )
+  })
+
+  test('skips both calls when all empty', async () => {
+    await bubbleAndTrickleProgressesSafely({}, {})
+    expect(mockRecordProgressMany).not.toHaveBeenCalled()
+    expect(mockEraseProgressMany).not.toHaveBeenCalled()
+  })
+})

package/test/unit/services/progress.test.ts

@@ -5,6 +5,7 @@ let mockStarted: any = { data: [] }
 let mockCompleted: any = { data: [] }
 let mockCompletedByContentIds: any = { data: [] }
 let mockStartedOrCompleted: any = { data: [] }
+let mockMethodAccessed: any = { data: [] }
 
 const repoMocks = {
   contentProgress: {
@@ -29,6 +30,9 @@ const repoMocks = {
       .fn()
       .mockImplementation(() => Promise.resolve(mockCompletedByContentIds)),
     startedOrCompleted: jest.fn().mockImplementation(() => Promise.resolve(mockStartedOrCompleted)),
+    getSomeProgressWhereLastAccessedFromMethod: jest
+      .fn()
+      .mockImplementation(() => Promise.resolve(mockMethodAccessed)),
   },
 }
 
@@ -39,7 +43,7 @@ jest.mock('../../../src/services/sync/repository-proxy', () => ({
 }))
 
 import { Progress } from '../../../src/services/progress'
-import { COLLECTION_TYPE } from '../../../src/services/sync/models/ContentProgress'
+import { COLLECTION_ID_SELF, COLLECTION_TYPE } from '../../../src/services/sync/models/ContentProgress'
 
 beforeEach(() => {
   jest.clearAllMocks()
@@ -50,6 +54,7 @@ beforeEach(() => {
   mockCompleted = { data: [] }
   mockCompletedByContentIds = { data: [] }
   mockStartedOrCompleted = { data: [] }
+  mockMethodAccessed = { data: [] }
 })
 
 describe('Progress.state', () => {
@@ -298,3 +303,94 @@ describe('Progress.allStartedOrCompleted', () => {
     expect(args.updatedAfter).toBeLessThanOrEqual(after)
   })
 })
+
+describe('Progress.snapshotByIds', () => {
+  test('returns snapshot keyed by content_id with defaults for missing', async () => {
+    mockProgressRecords = [
+      { content_id: 1, last_interacted_a_la_carte: 111, progress_percent: 50, state: 'started' },
+    ]
+    const result = await Progress.snapshotByIds([1, 2])
+    expect(result.get(1)).toEqual({ last_update: 111, progress: 50, status: 'started' })
+    expect(result.get(2)).toEqual({ last_update: 0, progress: 0, status: '' })
+  })
+
+  test('returns empty defaults when no records match', async () => {
+    const result = await Progress.snapshotByIds([99])
+    expect(result.get(99)).toEqual({ last_update: 0, progress: 0, status: '' })
+  })
+})
+
+describe('Progress.snapshotByRecordIds', () => {
+  test('returns snapshot keyed by record id with defaults for missing', async () => {
+    mockRecordsById = {
+      '1:self:0': { id: '1:self:0', updated_at: 222, progress_percent: 75, state: 'completed' },
+    }
+    const result = await Progress.snapshotByRecordIds(['1:self:0', '2:self:0'])
+    expect(result['1:self:0']).toEqual({ last_update: 222, progress: 75, status: 'completed' })
+    expect(result['2:self:0']).toEqual({ last_update: 0, progress: 0, status: '' })
+  })
+})
+
+describe('Progress.methodAccessedIds', () => {
+  test('returns content_ids from records', async () => {
+    mockMethodAccessed = { data: [{ content_id: 10 }, { content_id: 20 }] }
+    const result = await Progress.methodAccessedIds([10, 20, 30])
+    expect(result).toEqual([10, 20])
+  })
+
+  test('returns empty array when no records', async () => {
+    const result = await Progress.methodAccessedIds([1])
+    expect(result).toEqual([])
+  })
+
+  test('forwards contentIds to repository', async () => {
+    await Progress.methodAccessedIds([5, 6])
+    expect(
+      repoMocks.contentProgress.getSomeProgressWhereLastAccessedFromMethod
+    ).toHaveBeenCalledWith([5, 6])
+  })
+})
+
+describe('Progress.generateRecordId', () => {
+  test('no collection uses SELF defaults', () => {
+    expect(Progress.generateRecordId(123)).toBe(
+      `123:${COLLECTION_TYPE.SELF}:${COLLECTION_ID_SELF}`
+    )
+  })
+
+  test('LP collection returns correct format', () => {
+    expect(
+      Progress.generateRecordId(123, { type: COLLECTION_TYPE.LEARNING_PATH, id: 456 })
+    ).toBe('123:learning-path-v2:456')
+  })
+})
+
+describe('Progress.extractFromRecordId', () => {
+  test('self record id parses correctly', () => {
+    expect(Progress.extractFromRecordId('123:self:0')).toEqual({
+      contentId: 123,
+      collection: { type: 'self', id: 0 },
+    })
+  })
+
+  test('LP record id parses correctly', () => {
+    expect(Progress.extractFromRecordId('456:learning-path-v2:789')).toEqual({
+      contentId: 456,
+      collection: { type: 'learning-path-v2', id: 789 },
+    })
+  })
+
+  test('missing collection type defaults to SELF', () => {
+    expect(Progress.extractFromRecordId('123::')).toEqual({
+      contentId: 123,
+      collection: { type: COLLECTION_TYPE.SELF, id: COLLECTION_ID_SELF },
+    })
+  })
+
+  test('missing collection id defaults to COLLECTION_ID_SELF', () => {
+    expect(Progress.extractFromRecordId('123:self:')).toEqual({
+      contentId: 123,
+      collection: { type: 'self', id: COLLECTION_ID_SELF },
+    })
+  })
+})