musora-content-services 2.185.1 → 2.186.1

package/src/services/marketing/promotions.ts

@@ -0,0 +1,178 @@
+import { GET, POST } from '../../infrastructure/http/HttpClient'
+import { decorateAsync } from '../../lib/sanity/decorators/base'
+import type { Decoratable, FieldDecoratorAsync } from '../../lib/sanity/decorators/base'
+import { Filters as f } from '../../lib/sanity/filter'
+import { groq } from '../../lib/sanity/groq'
+import type { GroqBuilder } from '../../lib/sanity/groq'
+import type { PromotionalCampaignDocument } from '../../lib/sanity/types/marketing'
+import { SanityQueryError } from '../../lib/sanity/runner'
+import { AsyncEither } from '../../lib/ads/async-either'
+
+const excludeFromGeneratedIndex = [
+  'campaignQuery',
+  'campaignProjection',
+  'userCampaignStateDecorator',
+  'decorateUserCampaignState',
+]
+
+// ============================================
+// TYPES
+// ============================================
+
+export const USER_CAMPAIGN_STATE_FIELD = 'user_state' as const
+
+/**
+ * A campaign's placements are authored in Sanity, but whether a user still sees one is answered by
+ * the backend. `decorateUserCampaignState` attaches the second to the first.
+ */
+export interface UserCampaignState {
+  claimed: boolean
+  dismissed: boolean
+  eligible: boolean
+}
+
+export type WithUserCampaignState<T extends PromotionalCampaignDocument> = T & {
+  user_state: UserCampaignState
+}
+
+export interface CampaignQueryOptions {
+  /** Restricts the query to one campaign, or to any of several. */
+  slug?: string | string[]
+  /** The moment the campaign window is tested against. Defaults to now. */
+  on?: Date
+  /** Set false to return campaigns whose window does not cover `on`. */
+  running?: boolean
+  /** Set false to include campaigns that are toggled off in Sanity. */
+  active?: boolean
+}
+
+const UNTOUCHED: UserCampaignState = { claimed: false, dismissed: false, eligible: true }
+
+// ============================================
+// UTILITIES
+// ============================================
+
+const filterCampaignsForUser = (campaigns: WithUserCampaignState<PromotionalCampaignDocument>[]) =>
+  campaigns.filter(
+    (campaign) =>
+      campaign.user_state.eligible && !campaign.user_state.claimed && !campaign.user_state.dismissed
+  )
+
+// ============================================
+// QUERY BUILDING
+// ============================================
+
+export const campaignProjection: string[] = [
+  '...',
+  'placements[]{ ..., "dark_mode_image": dark_mode_image.asset->url, "light_mode_image": light_mode_image.asset->url }',
+]
+
+function slugFilter(slug: CampaignQueryOptions['slug']): string {
+  const slugs = (Array.isArray(slug) ? slug : [slug]).filter(Boolean) as string[]
+
+  if (!slugs.length) return f.empty
+
+  return slugs.length === 1 ? f.slug(slugs[0]) : f.slugIn(slugs)
+}
+
+export function campaignQuery(
+  options: CampaignQueryOptions = {}
+): GroqBuilder<PromotionalCampaignDocument[]> {
+  const { slug, on = new Date(), running = true, active = true } = options
+
+  return groq<PromotionalCampaignDocument[]>()
+    .and(
+      f.combine(
+        f.type('promotional-campaign'),
+        active && f.flag('active'),
+        running && f.dateWithin('starts_at', 'ends_at', on.toISOString()),
+        slugFilter(slug)
+      )
+    )
+    .order('starts_at desc')
+    .select(...campaignProjection)
+    .default([])
+}
+
+// ============================================
+// FETCHING
+// ============================================
+
+export async function fetchPromotionalCampaigns(
+  options: CampaignQueryOptions = {}
+): Promise<PromotionalCampaignDocument[]> {
+  return campaignQuery(options).run().recover([])
+}
+
+/**
+ * Every running campaign the user has not already claimed or dismissed, and is eligible.
+ */
+export async function fetchAvailablePromotionalCampaigns(
+  options: CampaignQueryOptions = {}
+): Promise<WithUserCampaignState<PromotionalCampaignDocument>[]> {
+  return campaignQuery(options)
+    .run()
+    .flatMap(decorateUserCampaignState)
+    .map(filterCampaignsForUser)
+    .recover([])
+}
+
+/**
+ * Fetches the state of every given campaign in a single request, keyed by slug. The backend leaves
+ * out slugs it has no campaign for, so a missing key means the campaign is unknown to it.
+ */
+export async function fetchUserCampaignStates(
+  slugs: string[]
+): Promise<Record<string, UserCampaignState>> {
+  if (!slugs.length) return {}
+
+  const query = slugs.map((slug) => `slugs[]=${encodeURIComponent(slug)}`).join('&')
+
+  return (await GET(`/api/promotions/v1/campaigns/state?${query}`)) ?? {}
+}
+
+// ============================================
+// DECORATION
+// ============================================
+
+export function userCampaignStateDecorator(
+  states: Record<string, UserCampaignState>
+): FieldDecoratorAsync<Decoratable, typeof USER_CAMPAIGN_STATE_FIELD, UserCampaignState> {
+  return {
+    field: USER_CAMPAIGN_STATE_FIELD,
+    compute: async (item) => {
+      const campaign = item as unknown as PromotionalCampaignDocument
+
+      return states[campaign.slug?.current] ?? UNTOUCHED
+    },
+  }
+}
+
+/**
+ * Attaches each campaign's claim and dismiss state in a single backend request.
+ */
+export function decorateUserCampaignState<T extends PromotionalCampaignDocument>(
+  campaigns: T[]
+): AsyncEither<Error, WithUserCampaignState<T>[]> {
+  return AsyncEither.attempt(async () => {
+    if (!campaigns.length) return []
+
+    const states = await fetchUserCampaignStates(campaigns.map((campaign) => campaign.slug.current))
+    const { field, compute } = userCampaignStateDecorator(states)
+    const decorated = await decorateAsync(campaigns as unknown as Decoratable[], field, compute)
+
+    return decorated as unknown as WithUserCampaignState<T>[]
+  })
+}
+
+// ============================================
+// MUTATIONS
+// ============================================
+
+export async function claimPromotionalCampaign(slug: string): Promise<void> {
+  await POST(`/api/promotions/v1/campaigns/${encodeURIComponent(slug)}/claim`)
+}
+
+export async function dismissPromotionalCampaign(slug: string): Promise<void> {
+  await POST(`/api/promotions/v1/campaigns/${encodeURIComponent(slug)}/dismiss`)
+}

package/src/services/my-path/placement-quiz.ts

@@ -3,7 +3,7 @@
  */
 import { HttpClient } from '../../infrastructure/http/HttpClient'
 import { globalConfig } from '../config.js'
-import { OnboardingRecommendedContent } from '@/services/user/onboarding'
+import { OnboardingRecommendedContent } from '../user/onboarding'
 
 
 const baseUrl = `/api/my-path/v1/placement-quiz`

package/src/services/progress/mutations.ts

@@ -67,14 +67,40 @@ export const save = async (
   progress: number,
   collection?: CollectionParameter,
   currentSeconds?: number,
+  options: SaveOptions = {}
+) => {
+  const activeCollection = withDefaultCollection(collection)
+  const response = await saveProgressPercent(contentId, progress, activeCollection, currentSeconds, options)
+  await saveResumeTime(contentId, activeCollection, currentSeconds)
+  return response
+}
+
+// resume time is last-write-wins, so it bypasses the percent gate that drops regressed progress
+const saveResumeTime = async (
+  contentId: number,
+  collection: CollectionParameter,
+  currentSeconds: number | undefined
+): Promise<void> => {
+  if (currentSeconds === undefined || currentSeconds === null) return
+
+  await db.contentProgress.updateResumeTime(contentId, collection, currentSeconds, { skipPush: true })
+  if (isPlaylistCollection(collection)) {
+    await db.contentProgress.updateResumeTime(contentId, null, currentSeconds, { skipPush: true })
+  }
+}
+
+const saveProgressPercent = async (
+  contentId: number,
+  progress: number,
+  activeCollection: CollectionParameter,
+  currentSeconds: number | undefined,
   {
     isOffline = false,
     hierarchy = null,
     skipPush = false,
     accessedDirectly = true,
-  }: SaveOptions = {}
+  }: SaveOptions
 ) => {
-  const activeCollection = withDefaultCollection(collection)
   const isPlaylist = isPlaylistCollection(activeCollection)
 
   let progresses: Record<number, number> = { [contentId]: progress }

package/src/services/recommendations.ts

@@ -0,0 +1,307 @@
+/**
+ * @module Recommendations
+ */
+
+import { TabResponseType } from '../contentMetaData.js'
+import { getFieldsForContentTypeWithFilteredChildren } from '../contentTypeConfig.js'
+import { decorateAll, type FieldDecorator } from '../lib/sanity/decorators/base'
+import { accessDecorator, type WithNeedAccess } from '../lib/sanity/decorators/need-access'
+import {
+  lifetimeUpgradeDecorator,
+  type WithNeedLifetimeUpgrade,
+} from '../lib/sanity/decorators/need-lifetime-upgrade'
+import { decorateNavigateTo, type WithNavigateTo } from '../lib/sanity/decorators/navigate-to'
+import { pageTypeDecorator, type WithPageType } from '../lib/sanity/decorators/page-type'
+import { Filters as f } from '../lib/sanity/filter'
+import { groq } from '../lib/sanity/groq'
+import { globalConfig } from './config.js'
+import { GET, HttpClient } from '../infrastructure/http/HttpClient'
+import { fetchUserPermissions, UserPermissions } from './permissions/index'
+
+/**
+ * @type {string[]}
+ */
+const excludeFromGeneratedIndex = []
+
+const RECOMMENDED_ROW_ID = 'recommended'
+const RECOMMENDED_CONTENT_TYPE = 'tab-data'
+
+const RECOMMENDER_URL = 'https://recommender.musora.com'
+const recommenderClient = new HttpClient(RECOMMENDER_URL, null, null, null, 'omit')
+
+interface RecommendedContent {
+  id: number
+  type: string
+  brand: string
+  thumbnail: string
+  published_on: string | null
+  status: string
+  live_event_start_time?: string | null
+  live_event_end_time?: string | null
+  children?: RecommendedContent[]
+  [key: string]: unknown
+}
+
+type DecoratedRecommendedContent = WithNeedLifetimeUpgrade<
+  WithPageType<WithNeedAccess<RecommendedContent>>
+> & { isLive: boolean }
+
+type NavigableRecommendedContent = WithNavigateTo<DecoratedRecommendedContent>
+
+interface RecommendedRow {
+  id: string
+  title: string
+  items: NavigableRecommendedContent[]
+}
+
+interface RecommendedCatalog {
+  type: string
+  data: NavigableRecommendedContent[]
+  meta: Record<string, never>
+}
+
+export interface RecommendedForYouOptions {
+  page?: number
+  limit?: number
+}
+
+export interface RecommendationsOptions {
+  section?: string
+  contentTypes?: string[]
+}
+
+export interface RankedCategory {
+  slug: string
+  items: number[]
+}
+
+export type CategoriesToRank = Record<string, number[]>
+
+/**
+ * @param {number|string} contentId
+ * @param {string} brand
+ * @param {number} [count=10]
+ * @returns {Promise<number[]|null>}
+ * @example
+ * fetchSimilarItems(1113, 'drumeo')
+ *   .then(ids => console.log(ids))
+ *   .catch(error => console.error(error));
+ */
+export async function fetchSimilarItems(
+  contentId: number | string,
+  brand: string,
+  count: number = 10
+): Promise<number[] | null> {
+  if (!contentId) {
+    return []
+  }
+  const id = parseInt(String(contentId))
+  const data = {
+    brand,
+    content_ids: id,
+    num_similar: count + 1,
+    page_size: count + 1,
+    page: 1,
+    exclude_interacted: true,
+  }
+  try {
+    const response = await recommenderClient.post('/similar_items/', data)
+    return response['similar_items'].filter((item: number) => item !== id).slice(0, count)
+  } catch (error) {
+    console.error('Fetch error:', error)
+    return null
+  }
+}
+
+/**
+ * @param {string} brand
+ * @param {CategoriesToRank} categories
+ * @returns {Promise<RankedCategory[]>}
+ * @example
+ * rankCategories('drumeo', { 1: [111222, 23120], 2: [2222, 33333] })
+ *   .then(categories => console.log(categories))
+ *   .catch(error => console.error(error));
+ */
+export async function rankCategories(
+  brand: string,
+  categories: CategoriesToRank
+): Promise<RankedCategory[]> {
+  const data = {
+    brand,
+    user_id: globalConfig.sessionConfig.userId,
+    playlists: categories,
+  }
+  try {
+    const response = await recommenderClient.post('/rank_each_list/', data)
+    return response['ranked_playlists'].map((rankedPlaylist: any) => ({
+      slug: rankedPlaylist.playlist_id,
+      items: rankedPlaylist.ranked_items,
+    }))
+  } catch (error) {
+    console.error('RankCategories fetch error:', error)
+  }
+
+  return Object.entries(categories).map(([slug, items]) => ({ slug, items }))
+}
+
+/**
+ * @param {string} brand
+ * @param {number[]} contentIds
+ * @returns {Promise<number[]>}
+ * @example
+ * rankItems('drumeo', [111222, 23120, 402199])
+ *   .then(ids => console.log(ids))
+ *   .catch(error => console.error(error));
+ */
+export async function rankItems(brand: string, contentIds: number[]): Promise<number[]> {
+  if (contentIds.length === 0) {
+    return []
+  }
+  const data = {
+    brand,
+    user_id: globalConfig.sessionConfig.userId,
+    content_ids: contentIds,
+  }
+  try {
+    const response = await recommenderClient.post('/rank_items/', data)
+    return response['ranked_content_ids']
+  } catch (error) {
+    console.error('rankItems fetch error:', error)
+    return contentIds
+  }
+}
+
+/**
+ * @param {string} brand
+ * @param {RecommendationsOptions} [options={}]
+ * @returns {Promise<number[]>}
+ * @example
+ * recommendations('drumeo', { section: 'lessons', contentTypes: ['course'] })
+ *   .then(ids => console.log(ids))
+ *   .catch(error => console.error(error));
+ */
+export async function recommendations(
+  brand: string,
+  { section = '', contentTypes = [] }: RecommendationsOptions = {}
+): Promise<number[]> {
+  const sectionParam = section.toUpperCase().replace('-', '_')
+  const sectionString = sectionParam ? `&section=${sectionParam}` : ''
+  const contentTypesString = contentTypes
+    .map((type) => `&content_types[]=${encodeURIComponent(type)}`)
+    .join('')
+
+  return await GET(
+    `/api/content/v1/recommendations?brand=${brand}${sectionString}${contentTypesString}`
+  )
+}
+
+const isLiveDecorator: FieldDecorator<RecommendedContent, 'isLive', boolean> = {
+  field: 'isLive',
+  recurse: false,
+  compute: (content) => {
+    const now = new Date().toISOString()
+    return Boolean(
+      content.live_event_start_time &&
+        content.live_event_end_time &&
+        content.live_event_start_time <= now &&
+        content.live_event_end_time >= now
+    )
+  },
+}
+
+const uniqueIds = (ids: Array<number | null | undefined>): number[] => [
+  ...new Set(ids.filter((id) => id !== null && id !== undefined) as number[]),
+]
+
+const sortByRecommendedOrder =
+  (ids: number[]) =>
+  <T extends { id: number }>(content: T[]): T[] =>
+    content.sort((a, b) => ids.indexOf(a.id) - ids.indexOf(b.id))
+
+const decorateRecommendations =
+  (permissions: UserPermissions) =>
+  (contents: RecommendedContent[]): DecoratedRecommendedContent[] =>
+    decorateAll(contents, [
+      accessDecorator(permissions),
+      lifetimeUpgradeDecorator(permissions),
+      pageTypeDecorator,
+      isLiveDecorator,
+    ]) as DecoratedRecommendedContent[]
+
+async function fetchRecommendedContent(
+  ids: number[],
+  brand: string
+): Promise<NavigableRecommendedContent[]> {
+  if (!ids.length) return []
+
+  const [restrictions, lessonCountFilter, fields, permissions] = await Promise.all([
+    f.combineAsync(
+      f.idIn(ids),
+      brand ? f.brand(brand) : f.empty,
+      f.status(),
+      f.notDeprecated(),
+      f.permissions({ showMembershipRestrictedContent: true })
+    ),
+    f.combineAsync('_id in ^.child[]._ref', f.status(), f.notDeprecated(), f.permissions()),
+    getFieldsForContentTypeWithFilteredChildren(RECOMMENDED_CONTENT_TYPE, false) as Promise<
+      string[]
+    >,
+    fetchUserPermissions(),
+  ])
+
+  return groq<RecommendedContent[]>()
+    .and(restrictions)
+    .select(
+      ...fields,
+      `"lesson_count": coalesce(${f.count(lessonCountFilter)}, 0)`,
+      'live_event_start_time',
+      'live_event_end_time'
+    )
+    .default([])
+    .run()
+    .map(decorateRecommendations(permissions))
+    .mapAsync((contents) => decorateNavigateTo(contents))
+    .map(sortByRecommendedOrder(ids))
+    .recover([])
+}
+
+/**
+ * @param {string} brand
+ * @param {string|null} [rowId=null]
+ * @param {Object} [params={}]
+ * @param {number} [params.page=1]
+ * @param {number} [params.limit=10]
+ * @returns {Promise<RecommendedRow|RecommendedCatalog>}
+ * @example
+ * getRecommendedForYou('drumeo')
+ *   .then(content => console.log(content))
+ *   .catch(error => console.error(error));
+ * @example
+ * getRecommendedForYou('drumeo', null, { page: 2, limit: 5 })
+ *   .then(content => console.log(content))
+ *   .catch(error => console.error(error));
+ */
+export async function getRecommendedForYou(
+  brand: string,
+  rowId: string | null = null,
+  { page = 1, limit = 10 }: RecommendedForYouOptions = {}
+): Promise<RecommendedRow | RecommendedCatalog> {
+  const title = brand === 'playbass' ? 'You Might Like' : 'Recommended For You'
+  const data = await recommendations(brand)
+
+  if (!data || !data.length) {
+    return { id: RECOMMENDED_ROW_ID, title, items: [] }
+  }
+
+  const offset = (page - 1) * limit
+  const contents = await fetchRecommendedContent(
+    uniqueIds(data.slice(offset, offset + limit)),
+    brand
+  )
+
+  if (rowId) {
+    return { type: TabResponseType.CATALOG, data: contents, meta: {} }
+  }
+
+  return { id: RECOMMENDED_ROW_ID, title, items: contents }
+}

package/src/services/sanity.js

@@ -33,7 +33,7 @@ import {
   transcriptionsLessonTypes,
   tutorialsLessonTypes,
 } from '../contentTypeConfig.js'
-import { fetchSimilarItems } from './recommendations.js'
+import { fetchSimilarItems } from './recommendations'
 import {
   ALWAYS_VISIBLE_TABS,
   CONTENT_STATUSES,

package/src/services/sync/repositories/content-progress.ts

@@ -12,6 +12,8 @@ interface MetadataParameter {
   parent_id: number
 }
 
+const MIN_INITIAL_RESUME_TIME_SECONDS = 10
+
 export default class ProgressRepository extends SyncRepository<ContentProgress> {
 
   static collectionTypeFilter(
@@ -185,11 +187,7 @@ export default class ProgressRepository extends SyncRepository<ContentProgress>
       r.content_type = metadata.type
       r.content_parent_id = metadata.parent_id
 
-      if (typeof resumeTime != 'undefined') {
-        if (resumeTime >= 10 || r.resume_time_seconds !== null) {
-          r.resume_time_seconds = Math.floor(resumeTime)
-        }
-      }
+      ProgressRepository.applyResumeTime(r, resumeTime)
 
       if (accessedDirectly && r.collection_type === COLLECTION_TYPE.SELF) {
         r.last_interacted_a_la_carte = r.updated_at
@@ -263,6 +261,29 @@ export default class ProgressRepository extends SyncRepository<ContentProgress>
     //todo add event emitting for bulk updates?
   }
 
+  async updateResumeTime(contentId: number, collection: CollectionParameter | null, resumeTime: number, { skipPush = false } = {}) {
+    const id = ContentProgress.generateId(contentId, collection)
+    const existing = await this.readOne(id)
+    if (!existing.data) return
+
+    const currentResumeTime = existing.data.resume_time_seconds
+    const isUnchanged = currentResumeTime === Math.floor(resumeTime)
+    if (isUnchanged || !ProgressRepository.shouldWriteResumeTime(currentResumeTime, resumeTime)) return
+
+    return this.upsertOne(id, (r) => ProgressRepository.applyResumeTime(r, resumeTime), { skipPush })
+  }
+
+  private static shouldWriteResumeTime(currentResumeTime: number | null, resumeTime: number) {
+    return resumeTime >= MIN_INITIAL_RESUME_TIME_SECONDS || currentResumeTime !== null
+  }
+
+  private static applyResumeTime(r: ContentProgress, resumeTime: number | undefined) {
+    if (typeof resumeTime == 'undefined') return
+    if (ProgressRepository.shouldWriteResumeTime(r.resume_time_seconds, resumeTime)) {
+      r.resume_time_seconds = Math.floor(resumeTime)
+    }
+  }
+
   eraseProgress(contentId: number, collection: CollectionParameter | null, { skipPush = false } = {}) {
     return this.deleteOne(ContentProgress.generateId(contentId, collection), { skipPush })
   }

package/src/version-info.js

@@ -1 +1 @@
-export const MCS_VERSION = '2.185.1'
+export const MCS_VERSION = '2.186.1'