musora-content-services 2.160.4 → 2.160.5

package/.agent/decisions/2026-05-20-live-event-fetch-permissions-id.md

@@ -0,0 +1,23 @@
+---
+date: 2026-05-20
+branch: fix/live-event-fetch-permissions-id
+pr: https://github.com/railroadmedia/musora-content-services/pull/982
+status: open
+tags: [bug-fix]
+---
+
+# Include permission_id in live event minimum fields
+
+## Context
+Live event consumers downstream of `getLiveFields()` need `permission_id` to resolve access to events. Without it on the returned payload, callers had to issue an extra query (or fall back to defaults) to determine whether the current user is permitted to view a given live event.
+
+## Decision
+Add `'permission_id'` to the `minimumFields` array in `getLiveFields()` in `src/contentTypeConfig.js` so the field is projected from Sanity alongside the other core live event fields (`live_event_start_time`, `live_event_end_time`, `live_event_stream_id`, `vimeo_live_event_id`, etc.).
+
+## Alternatives Considered
+- Put `permission_id` in `additionalFields` instead of `minimumFields`. Rejected — callers requesting the minimum projection are the ones that gate playback, so they need permission resolution by default.
+- Fetch `permission_id` in a separate query at the consumer layer. Rejected — duplicates Sanity round-trips and spreads access logic.
+
+## Consequences
+- All live event responses produced via `getLiveFields()` now include `permission_id`.
+- Incidental formatting (single-quote and trailing-comma normalization) was applied to the same file by the editor — not behavioral.

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 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.160.5](https://github.com/railroadmedia/musora-content-services/compare/v2.160.4...v2.160.5) (2026-05-22)
+
+
+### Bug Fixes
+
+* add a null check for method intro video ([#983](https://github.com/railroadmedia/musora-content-services/issues/983)) ([dbcaa72](https://github.com/railroadmedia/musora-content-services/commit/dbcaa7250ccca71ddcefda0d0514a7a013055784))
+* **live-events:** fetch permission ids ([#982](https://github.com/railroadmedia/musora-content-services/issues/982)) ([cd12054](https://github.com/railroadmedia/musora-content-services/commit/cd12054a58a0752614f8cdebcf79750edae948c3))
+
 ### [2.160.4](https://github.com/railroadmedia/musora-content-services/compare/v2.160.3...v2.160.4) (2026-05-20)
 
 

package/package.json

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

package/src/contentTypeConfig.js

@@ -146,22 +146,23 @@ export const assignmentsField = `"assignments":assignment[]{
 // todo: refactor live event queries to use this
 export function getLiveFields(minimum = false) {
   const minimumFields = [
-    "live_event_start_time",
-    "live_event_end_time",
-    "live_event_stream_id",
-    "vimeo_live_event_id",
+    'live_event_start_time',
+    'live_event_end_time',
+    'live_event_stream_id',
+    'vimeo_live_event_id',
     "'live_event_is_global': live_global_event == true",
     "'videoId': coalesce(live_event_stream_id, video.external_id)",
+    "'permission_id': permission_v2",
   ]
   const additionalFields = [
     "'slug': slug.current",
     "'id': railcontent_id",
-    "title",
-    "published_on",
+    'title',
+    'published_on',
     "'thumbnail': thumbnail.asset->url",
     `${artistOrInstructorName()}`,
-    "difficulty_string",
-    "railcontent_id",
+    'difficulty_string',
+    'railcontent_id',
     `'instructors': ${instructorField}`,
   ]
 
@@ -694,10 +695,7 @@ export let contentTypeConfig = {
     }`,
   ],
   'new-and-scheduled': {
-    fields: [
-      'show_in_new_feed',
-      isLiveField(),
-    ],
+    fields: ['show_in_new_feed', isLiveField()],
     includeChildFields: true,
   },
 }
@@ -816,7 +814,7 @@ export function artistOrInstructorNameAsArray(key = 'artists') {
 
 export async function getFieldsForContentTypeWithFilteredChildren(
   contentType,
-  asQueryString = true,
+  asQueryString = true
 ) {
   const childFields = getChildFieldsForContentType(contentType, true)
   const parentFields = getFieldsForContentType(contentType, false)
@@ -831,7 +829,7 @@ export async function getFieldsForContentTypeWithFilteredChildren(
         "children": child[${childFilter}]->{
           ${childFields}
         },
-      }`,
+      }`
     )
   }
   return asQueryString ? parentFields.toString() + ',' : parentFields
@@ -921,7 +919,7 @@ const filterHandlers = {
   length: (value) => {
     // Find the matching length option by name
     const lengthOption = Object.values(LengthFilterOptions).find(
-      (opt) => typeof opt === 'object' && opt.name === value,
+      (opt) => typeof opt === 'object' && opt.name === value
     )
 
     if (!lengthOption) return ''

package/src/index.d.ts

@@ -9,6 +9,7 @@ import {
 	getAwardStatistics,
 	getBadgeFields,
 	getCompletedAwards,
+	getCompletedAwardsByUser,
 	getContentAwards,
 	getContentAwardsByIds,
 	getInProgressAwards,
@@ -455,8 +456,9 @@ import {
 
 import {
 	deleteProfilePicture,
-	otherStats
-} from './services/user/profile.js';
+	otherStats,
+	updateProfileVisibility
+} from './services/user/profile.ts';
 
 import {
 	generateAuthSessionUrl,
@@ -665,6 +667,7 @@ declare module 'musora-content-services' {
 		getAwardStatistics,
 		getBadgeFields,
 		getCompletedAwards,
+		getCompletedAwardsByUser,
 		getContentAwards,
 		getContentAwardsByIds,
 		getContentRows,
@@ -828,6 +831,7 @@ declare module 'musora-content-services' {
 		updatePlaylist,
 		updatePost,
 		updatePracticeNotes,
+		updateProfileVisibility,
 		updateThread,
 		updateUserPractice,
 		upgradeSubscription,

package/src/index.js

@@ -13,6 +13,7 @@ import {
 	getAwardStatistics,
 	getBadgeFields,
 	getCompletedAwards,
+	getCompletedAwardsByUser,
 	getContentAwards,
 	getContentAwardsByIds,
 	getInProgressAwards,
@@ -459,8 +460,9 @@ import {
 
 import {
 	deleteProfilePicture,
-	otherStats
-} from './services/user/profile.js';
+	otherStats,
+	updateProfileVisibility
+} from './services/user/profile.ts';
 
 import {
 	generateAuthSessionUrl,
@@ -664,6 +666,7 @@ export {
 	getAwardStatistics,
 	getBadgeFields,
 	getCompletedAwards,
+	getCompletedAwardsByUser,
 	getContentAwards,
 	getContentAwardsByIds,
 	getContentRows,
@@ -827,6 +830,7 @@ export {
 	updatePlaylist,
 	updatePost,
 	updatePracticeNotes,
+	updateProfileVisibility,
 	updateThread,
 	updateUserPractice,
 	upgradeSubscription,

package/src/infrastructure/sanity/README.md

@@ -0,0 +1,230 @@
+# Sanity Infrastructure
+
+This module provides a TypeScript-based infrastructure for interacting with Sanity CMS, following the same architectural patterns as the HTTP client.
+
+## Architecture
+
+The Sanity infrastructure follows a modular design with clear separation of concerns:
+
+- **SanityClient**: Base client class that provides low-level methods for executing raw GROQ queries
+- **ContentClient**: Specialized client that extends SanityClient with content-specific methods like `fetchById`
+- **Interfaces**: Define contracts for configuration, queries, responses, and errors
+- **Providers**: Handle configuration management
+- **Executors**: Handle the actual execution of queries against the Sanity API
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { SanityClient, ContentClient } from './infrastructure/sanity'
+
+// Create client instances (use global configuration automatically)
+const sanityClient = new SanityClient()      // For raw GROQ queries
+const contentClient = new ContentClient()    // For content-specific operations
+
+// Fetch a single document by type and ID (recommended approach)
+const song = await contentClient.fetchById({
+  type: 'song',
+  id: 123
+})
+
+// Fetch with custom fields
+const songWithCustomFields = await contentClient.fetchById({
+  type: 'song',
+  id: 123,
+  fields: [
+    "'id': railcontent_id",
+    'title',
+    "'artist': artist->name",
+    'album',
+    'difficulty_string'
+  ]
+})
+
+// Fetch with children (for courses, packs, etc.)
+const courseWithLessons = await contentClient.fetchById({
+  type: 'course',
+  id: 456,
+  includeChildren: true
+})
+
+// Fetch multiple content items by IDs
+const multipleSongs = await contentClient.fetchByIds([123, 456, 789], 'song', 'drumeo')
+
+// Fetch content by brand and type
+const drumeoSongs = await contentClient.fetchByBrandAndType('drumeo', 'song', {
+  limit: 20,
+  sortBy: 'published_on desc'
+})
+
+// Use base SanityClient for raw GROQ queries (for complex queries)
+const songs = await sanityClient.fetchList(`
+  *[_type == "song" && brand == "drumeo"] | order(published_on desc)[0...10]{
+    "id": railcontent_id,
+    title,
+    "artist": artist->name
+  }
+`)
+
+// Execute complex queries with base client
+const result = await sanityClient.executeQuery(`
+  {
+    "songs": *[_type == "song"][0...5],
+    "total": count(*[_type == "song"])
+  }
+`)
+```
+
+### Custom Configuration
+
+```typescript
+import { SanityClient, ContentClient, ConfigProvider, SanityConfig } from './infrastructure/sanity'
+
+// Use custom configuration provider
+class CustomConfigProvider implements ConfigProvider {
+  getConfig(): SanityConfig {
+    return {
+      projectId: 'custom-project',
+      dataset: 'production',
+      version: '2021-06-07',
+      token: 'custom-token',
+      perspective: 'published',
+      useCachedAPI: true,
+      debug: false
+    }
+  }
+}
+
+const customConfigProvider = new CustomConfigProvider()
+const sanityClient = new SanityClient(customConfigProvider)
+const contentClient = new ContentClient(customConfigProvider)
+```
+
+### Error Handling
+
+```typescript
+try {
+  const result = await sanityClient.fetchSingle('*[_type == "song"][0]')
+} catch (error) {
+  if (error.query) {
+    console.error('Query failed:', error.query)
+    console.error('Error:', error.message)
+  }
+}
+```
+
+## Configuration
+
+The SanityClient uses the global configuration from the config service by default. Ensure your application is initialized with proper Sanity configuration:
+
+```javascript
+import { initializeService } from './services/config'
+
+initializeService({
+  sanityConfig: {
+    token: 'your-sanity-api-token',
+    projectId: 'your-sanity-project-id',
+    dataset: 'your-dataset-name',
+    version: '2021-06-07',
+    perspective: 'published',
+    useCachedAPI: false,
+    debug: false
+  },
+  // ... other config
+})
+```
+
+## API Reference
+
+### SanityClient (Base Client)
+
+#### Methods
+
+- `fetchSingle<T>(query: string, params?: Record<string, any>): Promise<T | null>`
+  - Executes a query and returns the first result
+  
+- `fetchList<T>(query: string, params?: Record<string, any>): Promise<T[]>`
+  - Executes a query and returns all results as an array
+  
+- `executeQuery<T>(query: string, params?: Record<string, any>): Promise<T | null>`
+  - Executes a raw query and returns the full response
+  
+- `refreshConfig(): void`
+  - Refreshes the configuration (useful if global config changes)
+
+### ContentClient (Specialized Client)
+
+#### Methods
+
+- `fetchById<T>(options: FetchByIdOptions): Promise<T | null>`
+  - Fetches a single document by type and ID (recommended for simple lookups)
+  - Options: `{ type: string, id: number | string, fields?: string[], includeChildren?: boolean }`
+
+- `fetchByIds<T>(ids: (number | string)[], type?: string, brand?: string, fields?: string[]): Promise<T[]>`
+  - Fetches multiple content items by their IDs
+  - Results are sorted to match the order of input IDs
+
+- `fetchByBrandAndType<T>(brand: string, type: string, options?: {...}): Promise<T[]>`
+  - Fetches content by brand and type with basic filtering
+  - Options: `{ limit?: number, offset?: number, sortBy?: string, fields?: string[] }`
+
+- All methods from SanityClient (inherited)
+
+### Interfaces
+
+- `SanityConfig`: Configuration structure for Sanity connection
+- `SanityQuery`: Structure for GROQ queries
+- `SanityResponse<T>`: Structure for Sanity API responses
+- `SanityError`: Structure for Sanity-specific errors
+- `QueryExecutor`: Interface for query execution implementations
+- `ConfigProvider`: Interface for configuration providers
+
+## Examples
+
+See the `examples/usage.ts` file for comprehensive usage examples.
+
+## Migration from Legacy Code
+
+To migrate from the existing `fetchByRailContentId` function:
+
+```typescript
+// Old way
+import { fetchByRailContentId } from './services/sanity'
+const result = await fetchByRailContentId(123, 'song')
+
+// New way (recommended)
+import { ContentClient } from './infrastructure/sanity'
+const contentClient = new ContentClient()
+const result = await contentClient.fetchById({ type: 'song', id: 123 })
+```
+
+To migrate from the existing `fetchByRailContentIds` function:
+
+```typescript
+// Old way
+import { fetchByRailContentIds } from './services/sanity'
+const results = await fetchByRailContentIds([123, 456, 789], 'song', 'drumeo')
+
+// New way
+import { ContentClient } from './infrastructure/sanity'
+const contentClient = new ContentClient()
+const results = await contentClient.fetchByIds([123, 456, 789], 'song', 'drumeo')
+```
+
+To migrate from the existing `fetchSanity` function:
+
+```typescript
+// Old way
+import { fetchSanity } from './services/sanity'
+const result = await fetchSanity(query, isList)
+
+// New way
+import { SanityClient } from './infrastructure/sanity'
+const sanityClient = new SanityClient()
+const result = isList 
+  ? await sanityClient.fetchList(query)
+  : await sanityClient.fetchSingle(query)
+```
+
+The new architecture provides better type safety, error handling, separation of concerns, and follows modern architectural patterns. 

package/src/infrastructure/sanity/SanityClient.ts

@@ -0,0 +1,105 @@
+import { ConfigProvider } from './interfaces/ConfigProvider'
+import { QueryExecutor } from './interfaces/QueryExecutor'
+import { SanityQuery } from './interfaces/SanityQuery'
+import { SanityConfig } from './interfaces/SanityConfig'
+import { SanityError } from './interfaces/SanityError'
+import { DefaultConfigProvider } from './providers/DefaultConfigProvider'
+import { FetchQueryExecutor } from './executors/FetchQueryExecutor'
+
+export class SanityClient {
+  private configProvider: ConfigProvider
+  private queryExecutor: QueryExecutor
+  private config: SanityConfig | null = null
+
+  constructor(
+    configProvider: ConfigProvider = new DefaultConfigProvider(),
+    queryExecutor: QueryExecutor = new FetchQueryExecutor()
+  ) {
+    this.configProvider = configProvider
+    this.queryExecutor = queryExecutor
+  }
+
+  /**
+   * Execute a GROQ query and return a single result
+   */
+  public async fetchSingle<T>(query: string, params?: Record<string, any>): Promise<T | null> {
+    try {
+      const sanityQuery: SanityQuery = { query, params }
+      const response = await this.queryExecutor.execute<T[]>(sanityQuery, this.getConfig())
+
+      if (response.result && Array.isArray(response.result) && response.result.length > 0) {
+        return response.result[0]
+      }
+
+      return null
+    } catch (error: any) {
+      this.handleError(error, query)
+      return null
+    }
+  }
+
+  /**
+   * Execute a GROQ query and return multiple results
+   */
+  public async fetchList<T>(query: string, params?: Record<string, any>): Promise<T[]> {
+    try {
+      const sanityQuery: SanityQuery = { query, params }
+      const response = await this.queryExecutor.execute<T[]>(sanityQuery, this.getConfig())
+
+      return response.result || []
+    } catch (error: any) {
+      this.handleError(error, query)
+      return []
+    }
+  }
+
+  /**
+   * Execute a raw GROQ query and return the full response
+   */
+  public async executeQuery<T>(query: string, params?: Record<string, any>): Promise<T | null> {
+    try {
+      const sanityQuery: SanityQuery = { query, params }
+      const response = await this.queryExecutor.execute<T>(sanityQuery, this.getConfig())
+
+      return response.result
+    } catch (error: any) {
+      this.handleError(error, query)
+      return null
+    }
+  }
+
+  /**
+   * Get configuration, loading it if necessary
+   */
+  private getConfig(): SanityConfig {
+    if (!this.config) {
+      this.config = this.configProvider.getConfig()
+    }
+    return this.config
+  }
+
+  /**
+   * Handle and rethrow errors
+   */
+  private handleError(error: any, query: string): never {
+    if ('message' in error && 'query' in error) {
+      // This is already a SanityError
+      throw error as SanityError
+    }
+
+    // Convert to SanityError
+    throw {
+      message: error.message || 'Sanity query failed',
+      query,
+      originalError: error,
+    } as SanityError
+  }
+
+  /**
+   * Refresh the configuration (useful if global config changes)
+   */
+  public refreshConfig(): void {
+    this.config = null
+  }
+}
+

package/src/infrastructure/sanity/clients/ContentClient.ts

@@ -0,0 +1,164 @@
+import { SanityClient } from '../SanityClient'
+import { FetchByIdOptions } from '../interfaces/FetchByIdOptions'
+import { ConfigProvider } from '../interfaces/ConfigProvider'
+import { QueryExecutor } from '../interfaces/QueryExecutor'
+
+/**
+ * ContentClient extends SanityClient with content-specific methods
+ * for easier content fetching and management
+ */
+export class ContentClient extends SanityClient {
+  constructor(configProvider?: ConfigProvider, queryExecutor?: QueryExecutor) {
+    super(configProvider, queryExecutor)
+  }
+
+  /**
+   * Fetch content by type and ID (similar to fetchByRailContentId)
+   */
+  public async fetchById<T>(options: FetchByIdOptions): Promise<T | null> {
+    try {
+      const { type, id, fields, includeChildren = false } = options
+      
+      // Build the base query
+      let query = `*[railcontent_id == ${id} && _type == '${type}']`
+      
+      // Build fields string
+      let fieldsString = this.buildFieldsString(type, fields, includeChildren)
+      
+      // Complete the query
+      query += `{${fieldsString}}[0]`
+      
+      return await this.fetchSingle<T>(query)
+    } catch (error: any) {
+      this.handleContentError(error, `fetchById(${JSON.stringify(options)})`)
+      return null
+    }
+  }
+
+  /**
+   * Fetch multiple content items by their IDs
+   */
+  public async fetchByIds<T>(
+    ids: (number | string)[],
+    type?: string,
+    brand?: string,
+    fields?: string[]
+  ): Promise<T[]> {
+    try {
+      if (!ids || ids.length === 0) {
+        return []
+      }
+
+      const idsString = ids.join(',')
+      const typeFilter = type ? ` && _type == '${type}'` : ''
+      const brandFilter = brand ? ` && brand == "${brand}"` : ''
+      const fieldsString = this.buildFieldsString(type || '', fields, false)
+
+      const query = `*[railcontent_id in [${idsString}]${typeFilter}${brandFilter}]{${fieldsString}}`
+
+      const results = await this.fetchList<T>(query)
+
+      // Sort results to match the order of input IDs
+      return results.sort((a: any, b: any) => {
+        const indexA = ids.indexOf(a.id || a.railcontent_id)
+        const indexB = ids.indexOf(b.id || b.railcontent_id)
+        return indexA - indexB
+      })
+          } catch (error: any) {
+        this.handleContentError(error, `fetchByIds([${ids.join(',')}])`)
+        return []
+      }
+  }
+
+  /**
+   * Fetch content by brand and type with basic filtering
+   */
+  public async fetchByBrandAndType<T>(
+    brand: string,
+    type: string,
+    options: {
+      limit?: number
+      offset?: number
+      sortBy?: string
+      fields?: string[]
+    } = {}
+  ): Promise<T[]> {
+    try {
+      const { limit = 10, offset = 0, sortBy = 'published_on desc', fields } = options
+      const fieldsString = this.buildFieldsString(type, fields, false)
+
+      const query = `*[brand == "${brand}" && _type == "${type}"] | order(${sortBy})[${offset}...${offset + limit}]{${fieldsString}}`
+
+      return await this.fetchList<T>(query)
+    } catch (error: any) {
+      this.handleContentError(error, `fetchByBrandAndType(${brand}, ${type})`)
+      return []
+    }
+  }
+
+  /**
+   * Build fields string for queries based on content type and options
+   */
+  private buildFieldsString(type: string, customFields?: string[], includeChildren: boolean = false): string {
+    // Default fields that are commonly used
+    const defaultFields = [
+      "'sanity_id': _id",
+      "'id': railcontent_id",
+      'railcontent_id',
+      'title',
+      "'image': thumbnail.asset->url",
+      "'thumbnail': thumbnail.asset->url",
+      'difficulty',
+      'difficulty_string',
+      'web_url_path',
+      "'url': web_url_path",
+      'published_on',
+      "'type': _type",
+      'brand',
+      'status',
+      "'slug': slug.current",
+      "'permission_id': permission[]->railcontent_id",
+      'length_in_seconds',
+      "'artist': artist->name",
+      "'instructors': instructor[]->name"
+    ]
+
+    // Use custom fields if provided, otherwise use defaults
+    let fields = customFields || defaultFields
+
+    // Add children-related fields if requested
+    if (includeChildren) {
+      fields = [
+        ...fields,
+        "'child_count': coalesce(count(child[]->), 0)",
+        `"lessons": child[]->{
+          "id": railcontent_id,
+          title,
+          "image": thumbnail.asset->url,
+          "instructors": instructor[]->name,
+          length_in_seconds,
+          web_url_path
+        }`
+      ]
+    }
+
+    return fields.join(',\n    ')
+  }
+
+  /**
+   * Handle and rethrow errors with additional context
+   */
+  private handleContentError(error: any, context: string): never {
+    if ('message' in error && 'query' in error) {
+      // This is already a SanityError
+      throw error
+    }
+
+    // Convert to SanityError with context
+    throw {
+      message: error.message || `ContentClient operation failed: ${context}`,
+      query: context,
+      originalError: error,
+    }
+  }
+}