musora-content-services 2.185.0 → 2.186.0

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

@@ -9,6 +9,8 @@ import { Onboarding } from './onboarding'
 import { OAuthProvider } from './session'
 import { AuthResponse } from './types'
 
+const LOCAL_PART_MASK = '***'
+
 export interface AccountStatus {
   requires_setup: boolean
   last_login_provider?: OAuthProvider
@@ -256,3 +258,24 @@ export async function toggleStudentView(useStudentView: boolean): Promise<UserRe
   const httpClient = new HttpClient(globalConfig.baseUrl, globalConfig.sessionConfig.token)
   return httpClient.patch<UserResource>(apiUrl, { use_student_view: useStudentView })
 }
+
+/**
+ * Masks the local part of an email, keeping the domain intact.
+ * Shows the first character of the local part unless it's 3 characters or shorter,
+ * in which case the whole local part is masked.
+ * @example
+ * maskEmail('abcd@gmail.com') // 'a***@gmail.com'
+ * maskEmail('ab@abc.com') // '***@abc.com'
+ */
+export function maskEmail(email: string): string {
+  const atIndex = email.indexOf('@')
+  if (atIndex === -1) {
+    return email
+  }
+  const localPart = email.slice(0, atIndex)
+  const domain = email.slice(atIndex)
+
+  return localPart.length <= 3
+    ? `${LOCAL_PART_MASK}${domain}`
+    : `${localPart[0]}${LOCAL_PART_MASK}${domain}`
+}

package/src/version-info.js

@@ -1 +1 @@
-export const MCS_VERSION = '2.185.0'
+export const MCS_VERSION = '2.186.0'

package/dist/services/api/types.js

@@ -1,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });

package/src/services/recommendations.js

@@ -1,142 +0,0 @@
-/**
- * @module Railcontent-Services
- */
-
-import { globalConfig } from './config.js'
-import { GET, HttpClient } from '../infrastructure/http/HttpClient.ts'
-
-/**
- * Exported functions that are excluded from index generation.
- *
- * @type {string[]}
- */
-const excludeFromGeneratedIndex = []
-
-const RECOMMENDER_URL = 'https://recommender.musora.com'
-const recommenderClient = new HttpClient(RECOMMENDER_URL, null, null, null, 'omit')
-
-/**
- * Fetches similar content to the provided content id
- *
- * @param {integer} content_id - The ID of the content to find similar items for
- * @param {brand} brand - brand of the content to filter
- * @param {integer} count - number of items to return
- * @returns {Promise<Object|null>} - Returns the content_ids sorted by rank (most significant first)
- * @example
- * rankItems('drumeo', 1113)
- *   .then(status => console.log(status))
- *   .catch(error => console.error(error));
- */
-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
-  }
-}
-
-/**
- * Sorts the provided categories based on the user's match
- *
- * @param {brand} brand - brand of the content to filter
- * @param {Object} categories - Keyed arrays of content ids
- * @returns {Promise<Object|null>} - Returns the content_ids sorted by rank (most significant first), elements in each category are also ranked
- * @example
- * rankCategories('drumeo', {
- *                            1: [111222, 23120, 402199],
- *                            2: [2222, 33333, 44444]
- *                          }
- *                )
- *   .then(status => console.log(status))
- *   .catch(error => console.error(error));
- */
-export async function rankCategories(brand, categories) {
-  if (categories.length === 0) {
-    return []
-  }
-  const data = {
-    brand: brand,
-    user_id: globalConfig.sessionConfig.userId,
-    playlists: categories,
-  }
-  const url = `/rank_each_list/`
-  try {
-    const response = await recommenderClient.post(url, data)
-    const rankedCategories = []
-
-    for (const rankedPlaylist of response['ranked_playlists']) {
-      rankedCategories.push({
-        slug: rankedPlaylist.playlist_id,
-        items: rankedPlaylist.ranked_items,
-      })
-    }
-    return rankedCategories
-  } catch (error) {
-    console.error('RankCategories fetch error:', error)
-  }
-
-  const defaultSorting = []
-  for (const slug in categories) {
-    defaultSorting.push({
-      slug: slug,
-      items: categories[slug],
-    })
-  }
-  return defaultSorting
-}
-
-/**
- * Fetches the completion status of a specific lesson for the current user.
- *
- * @param {brand} brand - brand of the content to filter
- * @param {Array<string>} content_ids - The IDs of the content to rank
- * @returns {Promise<Object|null>} - Returns the content_ids sorted by rank (most significant first)
- * @example
- * rankItems('drumeo', ([111222, 23120, 402199])
- *   .then(status => console.log(status))
- *   .catch(error => console.error(error));
- */
-export async function rankItems(brand, content_ids) {
-  if (content_ids.length === 0) {
-    return []
-  }
-  const data = {
-    brand: brand,
-    user_id: globalConfig.sessionConfig.userId,
-    content_ids: content_ids,
-  }
-  const url = `/rank_items/`
-  try {
-    const response = await recommenderClient.post(url, data)
-    return response['ranked_content_ids']
-  } catch (error) {
-    console.error('rankItems fetch error:', error)
-    return 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 url = `/api/content/v1/recommendations?brand=${brand}${sectionString}${contentTypesString}`
-  return await GET(url)
-}