musora-content-services 2.160.3 → 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/.claude/settings.local.json

@@ -0,0 +1,23 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npx jest *)",
+      "Bash(npx tsc *)",
+      "Skill(counselors)",
+      "Bash(counselors ls *)",
+      "Bash(counselors groups *)",
+      "Bash(counselors run *)",
+      "Bash(npm test *)",
+      "Bash(gh pr *)",
+      "Bash(gh api *)",
+      "Bash(mkdir -p /tmp/pr-review-v2)",
+      "Read(//tmp/pr-review-v2/**)",
+      "Bash(cat /home/alesevero/railenvironment/applications/musora-content-services/AGENTS.md)",
+      "Bash(echo \"no AGENTS.md\")",
+      "Bash(echo \"exit=$?\")",
+      "Bash(git checkout *)",
+      "Skill(pr)",
+      "Skill(create-decision)"
+    ]
+  }
+}

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 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)
+
+
+### Bug Fixes
+
+* **MU2-1510:** process need access for live events ([#964](https://github.com/railroadmedia/musora-content-services/issues/964)) ([66aa2b5](https://github.com/railroadmedia/musora-content-services/commit/66aa2b596b28c272b938672522b9c4024f9e328d))
+* **MU2-1511:** add need access to upcoming live events ([#965](https://github.com/railroadmedia/musora-content-services/issues/965)) ([9366907](https://github.com/railroadmedia/musora-content-services/commit/936690752529d25d80df0192e80b57ad90921445))
+* **MU2-1512:** add child data to new and upcoming ([#960](https://github.com/railroadmedia/musora-content-services/issues/960)) ([329f5c8](https://github.com/railroadmedia/musora-content-services/commit/329f5c8b98ea11f1d456dd53e81b705f55b4f346))
+
 ### [2.160.3](https://github.com/railroadmedia/musora-content-services/compare/v2.160.2...v2.160.3) (2026-05-14)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "musora-content-services",
-  "version": "2.160.3",
+  "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,8 @@ export let contentTypeConfig = {
     }`,
   ],
   'new-and-scheduled': {
-    fields: [
-      'show_in_new_feed',
-      isLiveField(),
-    ],
+    fields: ['show_in_new_feed', isLiveField()],
+    includeChildFields: true,
   },
 }
 
@@ -815,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)
@@ -830,7 +829,7 @@ export async function getFieldsForContentTypeWithFilteredChildren(
         "children": child[${childFilter}]->{
           ${childFields}
         },
-      }`,
+      }`
     )
   }
   return asQueryString ? parentFields.toString() + ',' : parentFields
@@ -920,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
+  }
+}
+