musora-content-services 2.81.0 → 2.83.0

package/src/services/permissions/PermissionsAdapterFactory.ts

@@ -0,0 +1,71 @@
+/**
+ * @module PermissionsAdapterFactory
+ *
+ * Factory for creating the appropriate permissions adapter based on configuration.
+ * Provides a single point of control for switching between v1 and v2 implementations.
+ */
+
+import { PermissionsAdapter } from './PermissionsAdapter'
+import { PermissionsV1Adapter } from './PermissionsV1Adapter'
+import { PermissionsV2Adapter } from './PermissionsV2Adapter'
+import { globalConfig } from '../config.js'
+
+/**
+ * Valid permissions version types
+ */
+export type PermissionsVersion = 'v1' | 'v2'
+
+/**
+ * Singleton instance of the permissions adapter.
+ * Created once and reused throughout the application.
+ */
+let adapterInstance: PermissionsAdapter | null = null
+
+/**
+ * Get the appropriate permissions adapter based on configuration.
+ *
+ * This is a singleton - the same adapter instance is returned on every call.
+ * To switch versions, change globalConfig.permissionsVersion via initializeService().
+ *
+ * @returns The permissions adapter instance
+ * @throws Error if an invalid permissions version is configured
+ *
+ * @example
+ * import { getPermissionsAdapter } from './permissions/PermissionsAdapterFactory.js'
+ *
+ * const adapter = getPermissionsAdapter()
+ * const permissions = await adapter.fetchUserPermissions()
+ */
+export function getPermissionsAdapter(): PermissionsAdapter {
+  if (adapterInstance) {
+    return adapterInstance
+  }
+
+  const version = (globalConfig.permissionsVersion || 'v1') as PermissionsVersion
+
+  switch (version.toLowerCase()) {
+    case 'v1':
+      adapterInstance = new PermissionsV1Adapter()
+      break
+
+    case 'v2':
+      adapterInstance = new PermissionsV2Adapter()
+      break
+
+    default:
+      throw new Error(
+        `Invalid permissionsVersion: ${version}. Must be 'v1' or 'v2'.`
+      )
+  }
+
+  return adapterInstance
+}
+
+/**
+ * Get the current permissions version being used.
+ *
+ * @returns The permissions version ('v1' or 'v2')
+ */
+export function getPermissionsVersion(): PermissionsVersion {
+  return (globalConfig.permissionsVersion || 'v1') as PermissionsVersion
+}

package/src/services/permissions/PermissionsV1Adapter.ts

@@ -0,0 +1,232 @@
+/**
+ * @module PermissionsV1Adapter
+ *
+ * Permissions adapter for the current (v1) permissions system.
+ * Implements the existing permission logic using permission IDs.
+ */
+
+import {
+  PermissionsAdapter,
+  UserPermissions,
+  ContentItem,
+  PermissionFilterOptions,
+} from './PermissionsAdapter'
+import {
+  fetchUserPermissions as fetchUserPermissionsV1,
+} from '../user/permissions.js'
+import { plusMembershipPermissions, membershipPermissions } from '../../contentTypeConfig.js'
+import { arrayToRawRepresentation } from '../../filterBuilder.js'
+
+/**
+ * V1 Permissions Adapter implementing the current permissions system.
+ *
+ * Logic:
+ * - Content access based on permission IDs
+ * - Admins bypass all checks
+ * - Content with no permissions is accessible to all
+ * - User needs at least ONE matching permission to access content
+ * - If showMembershipRestrictedContent: also show content that requires membership
+ */
+export class PermissionsV1Adapter extends PermissionsAdapter {
+  /**
+   * Fetch user permissions data from v1 API.
+   *
+   * @returns The user's permissions data
+   */
+  async fetchUserPermissions(): Promise<UserPermissions> {
+    return await fetchUserPermissionsV1()
+  }
+
+  /**
+   * Check if user needs access to specific content.
+   *
+   * V1 Logic:
+   * - Admins always have access (return false)
+   * - Content with no permissions is accessible (return false)
+   * - User must have at least ONE matching permission (return false if found)
+   * - Otherwise user needs access (return true)
+   *
+   * @param content - The content item with permission_id array
+   * @param userPermissions - The user's permissions
+   * @returns True if user needs access, false if they have it
+   */
+  doesUserNeedAccess(content: ContentItem, userPermissions: UserPermissions): boolean {
+    // Admins always have access
+    if (this.isAdmin(userPermissions)) {
+      return false
+    }
+
+    // Get content's required permissions
+    const contentPermissions = new Set(content?.permission_id ?? [])
+
+    // Content with no permissions is accessible to all
+    if (contentPermissions.size === 0) {
+      return false
+    }
+
+    // Convert user permissions to Set for fast lookup
+    const userPermissionSet = new Set(userPermissions?.permissions ?? [])
+
+    // Check if user has ANY of the required permissions
+    for (const permission of contentPermissions) {
+      if (userPermissionSet.has(permission)) {
+        return false // User has access
+      }
+    }
+
+    // User doesn't have any required permissions
+    return true
+  }
+
+  /**
+   * Generate GROQ filter string for permissions.
+   *
+   * V1 Logic:
+   * - Admins bypass filter (return null)
+   * - Filter: content has no permission OR references user's permissions
+   * - If showMembershipRestrictedContent: also show content that requires membership
+   * - If showOnlyOwnedContent: exclude membership content (permissions 91, 92), show only purchased/owned content
+   *
+   * @param userPermissions - The user's permissions
+   * @param options - Options for filter generation
+   * @returns GROQ filter string or null for admin
+   */
+  generatePermissionsFilter(
+    userPermissions: UserPermissions,
+    options: PermissionFilterOptions = {}
+  ): string | null {
+    const {
+      prefix = '',
+      showMembershipRestrictedContent = false,
+      showOnlyOwnedContent = false,
+    } = options
+
+    // Admins bypass permission filter
+    if (this.isAdmin(userPermissions)) {
+      return null
+    }
+
+    const userPermissionIds = this.getUserPermissionIds(userPermissions)
+    const isDereferencedContext = prefix === '@->'
+
+    if (showOnlyOwnedContent) {
+      return this.buildOwnedContentFilter(userPermissionIds, prefix, isDereferencedContext)
+    }
+
+    return this.buildStandardPermissionFilter(
+      userPermissionIds,
+      prefix,
+      isDereferencedContext,
+      showMembershipRestrictedContent
+    )
+  }
+
+  /**
+   * Build filter for owned content only (excluding membership content).
+   *
+   * @param userPermissionIds - User's permission IDs
+   * @param prefix - GROQ prefix for nested queries
+   * @param isDereferencedContext - Whether we're in a dereferenced context
+   * @returns GROQ filter string for owned content
+   */
+  private buildOwnedContentFilter(
+    userPermissionIds: string[],
+    prefix: string,
+    isDereferencedContext: boolean
+  ): string {
+    // Filter out membership permissions to get only owned permissions
+    const ownedPermissions = userPermissionIds.filter(
+      permId => !membershipPermissions.includes(parseInt(permId))
+    )
+
+    if (ownedPermissions.length === 0) {
+      // User has no owned permissions (only membership or none at all)
+      // Return filter that matches nothing - user can't see any owned content
+      return `${prefix}_id == null`
+    }
+
+    // Content must have at least one owned permission AND no membership permissions
+    if (isDereferencedContext) {
+      // In dereferenced context, check arrays directly
+      const hasOwnedPermission = `count((${prefix}permission[]._ref)[@ in *[_type == 'permission' && railcontent_id in ${arrayToRawRepresentation(ownedPermissions)}]._id]) > 0`
+      const hasMembershipPermission = `count((${prefix}permission[]._ref)[@ in *[_type == 'permission' && railcontent_id in ${arrayToRawRepresentation(membershipPermissions)}]._id]) > 0`
+      return `(${hasOwnedPermission} && !${hasMembershipPermission})`
+    }
+
+    // Non-dereferenced: use references() function
+    const hasOwnedPermissions = `references(*[_type == 'permission' && railcontent_id in ${arrayToRawRepresentation(ownedPermissions)}]._id)`
+    const hasMembershipPermissions = `references(*[_type == 'permission' && railcontent_id in ${arrayToRawRepresentation(membershipPermissions)}]._id)`
+    return `(${hasOwnedPermissions} && !${hasMembershipPermissions})`
+  }
+
+  /**
+   * Build standard permission filter (content with no permissions OR user has matching permissions).
+   *
+   * @param userPermissionIds - User's permission IDs
+   * @param prefix - GROQ prefix for nested queries
+   * @param isDereferencedContext - Whether we're in a dereferenced context
+   * @param showMembershipRestrictedContent - Whether to show membership-restricted content
+   * @returns GROQ filter string for standard permissions
+   */
+  private buildStandardPermissionFilter(
+    userPermissionIds: string[],
+    prefix: string,
+    isDereferencedContext: boolean,
+    showMembershipRestrictedContent: boolean
+  ): string {
+    const clauses: string[] = []
+
+    // Content with no permissions is accessible to all
+    clauses.push(`!defined(${prefix}permission)`)
+
+    // User has matching permissions
+    if (userPermissionIds.length > 0) {
+      clauses.push(this.buildPermissionCheck(userPermissionIds, prefix, isDereferencedContext))
+    }
+
+    // Include membership-restricted content
+    if (showMembershipRestrictedContent) {
+      clauses.push(
+        this.buildPermissionCheck(
+          membershipPermissions.map(String),
+          prefix,
+          isDereferencedContext
+        )
+      )
+    }
+
+    return `(${clauses.join(' || ')})`
+  }
+
+  /**
+   * Build GROQ permission check for given permissions.
+   * Handles both dereferenced and standard contexts.
+   *
+   * @param permissions - Permission IDs to check
+   * @param prefix - GROQ prefix for nested queries
+   * @param isDereferencedContext - Whether we're in a dereferenced context
+   * @returns GROQ filter string for permission check
+   */
+  private buildPermissionCheck(
+    permissions: string[],
+    prefix: string,
+    isDereferencedContext: boolean
+  ): string {
+    if (isDereferencedContext) {
+      // In dereferenced context, check the permission array directly
+      return `count((${prefix}permission[]._ref)[@ in *[_type == 'permission' && railcontent_id in ${arrayToRawRepresentation(permissions)}]._id]) > 0`
+    }
+    // In standard context, use references() function
+    return `references(*[_type == 'permission' && railcontent_id in ${arrayToRawRepresentation(permissions)}]._id)`
+  }
+
+  /**
+   * Get user's permission IDs.
+   *
+   * @param userPermissions - The user's permissions
+   * @returns Array of permission IDs
+   */
+  getUserPermissionIds(userPermissions: UserPermissions): string[] {
+    return userPermissions?.permissions ?? []
+  }
+}

package/src/services/permissions/PermissionsV2Adapter.ts

@@ -0,0 +1,226 @@
+/**
+ * @module PermissionsV2Adapter
+ *
+ * Permissions adapter for the new (v2) permissions system.
+ * This is a placeholder implementation to be completed when v2 is ready.
+ *
+ * Key differences from v1:
+ * - New permission structure (to be defined)
+ */
+
+import {
+  PermissionsAdapter,
+  UserPermissions,
+  ContentItem,
+  PermissionFilterOptions,
+} from './PermissionsAdapter'
+import {
+  fetchUserPermissions as fetchUserPermissionsV2,
+} from '../user/permissions.js'
+import {arrayToRawRepresentation, arrayToStringRepresentation} from '../../filterBuilder.js'
+import {basicMembershipTier, plusMembershipPermissions, plusMembershipTier} from "../../contentTypeConfig";
+
+/**
+ * V2 Permissions Adapter for the new permissions system.
+ *
+ * Expected changes:
+ * - Different permission data structure
+ * - Potentially different GROQ filter logic
+ */
+export class PermissionsV2Adapter extends PermissionsAdapter {
+  /**
+   * Fetch user permissions data from API.
+   *
+   * @returns The user's permissions data
+   */
+  async fetchUserPermissions(): Promise<UserPermissions> {
+    return await fetchUserPermissionsV2()
+  }
+
+  /**
+   * Check if user needs access to specific content.
+   *
+   * @param content - The content item
+   * @param userPermissions - The user's permissions
+   * @returns True if user needs access, false if they have it
+   */
+  doesUserNeedAccess(content: ContentItem, userPermissions: UserPermissions): boolean {
+    // Admins always have access
+    if (this.isAdmin(userPermissions)) {
+      return false
+    }
+
+    // Get content's required permissions
+    const oldPermissions = content?.permission_id ?? []
+    const newPermissions = content?.permission_v2 ?? []
+    const contentPermissions = new Set([...oldPermissions, ...newPermissions])
+
+    // Content with no permissions is accessible to all
+    if (contentPermissions.size === 0) {
+      return false
+    }
+
+    // Convert user permissions to Set for fast lookup
+    const userPermissionSet = new Set(userPermissions?.permissions ?? [])
+
+    // Check if user has ANY of the required permissions
+    for (const permission of contentPermissions) {
+      if (userPermissionSet.has(permission)) {
+        return false // User has access
+      }
+    }
+
+    // User doesn't have any required permissions
+    return true
+  }
+
+  /**
+   * Generate GROQ filter string for permissions.
+   *
+   * TODO: Implement v2 filter generation
+   *
+   * V2 Logic:
+   * - When showMembershipRestrictedContent is true:
+   *   * Show content restricted by Plus Membership
+   *   * This supports the membership upgrade modal
+   * - When showOnlyOwnedContent is true:
+   *   * Shows only purchased/owned content
+   *
+   * @param userPermissions - The user's permissions
+   * @param options - Options for filter generation
+   * @returns GROQ filter string or null
+   */
+  generatePermissionsFilter(
+    userPermissions: UserPermissions,
+    options: PermissionFilterOptions = {}
+  ): string | null {
+    const {
+      prefix = '',
+      showMembershipRestrictedContent = false,
+      showOnlyOwnedContent = false,
+    } = options
+
+    // Admins bypass permission filter
+    if (this.isAdmin(userPermissions)) {
+      return null
+    }
+
+    // If showOnlyOwnedContent, show only purchased/owned content
+    if (showOnlyOwnedContent) {
+      return this.buildOwnedContentFilter(userPermissions)
+    }
+
+    let userPermissionIds = this.getUserPermissionIds(userPermissions)
+    const isDereferencedContext = prefix === '@->'
+
+    // If showing membership restricted content
+    if (showMembershipRestrictedContent) {
+      return ` ${prefix}membership_tier in ${arrayToStringRepresentation([plusMembershipTier, basicMembershipTier])} `
+    }
+
+    const filter = this.buildStandardPermissionFilter(
+      userPermissionIds,
+      prefix,
+      isDereferencedContext
+    )
+
+    return filter
+  }
+
+  /**
+   * Build filter for owned content only (a-la-carte purchases).
+   *
+   * In V2, owned content is identified by permission IDs >= 100000000.
+   * These permissions represent direct purchases of individual content items.
+   *
+   * Logic:
+   * 1. Extract user's permission IDs
+   * 2. Filter for IDs >= 100000000 (owned content permissions)
+   * 3. Convert permission IDs to content IDs: content_id = permission_id - 100000000
+   * 4. Filter content to show only items matching these content IDs
+   *
+   * @param userPermissions - The user's permissions
+   * @returns GROQ filter string for owned content
+   */
+  private buildOwnedContentFilter(userPermissions: UserPermissions): string {
+    const minContentPermissionId = 100000000
+    const userPermissionIds = this.getUserPermissionIds(userPermissions)
+
+    // Convert permission IDs to content IDs
+    // Permission ID format: 100000000 + railcontent_id
+    const ownedContentIds = userPermissionIds
+      .map((permissionId) => parseInt(permissionId) - minContentPermissionId)
+      .filter((contentId) => contentId > 0)
+
+    if (ownedContentIds.length === 0) {
+      // User has no owned content permissions
+      // Return filter that matches nothing
+      return `railcontent_id == null`
+    }
+
+    // Content must be in owned content IDs
+    const ownerContentFilter = `railcontent_id in ${arrayToRawRepresentation(ownedContentIds)}`
+    return ` ${ownerContentFilter} `
+  }
+
+  /**
+   * Build standard permission filter (content with no permissions OR user has matching permissions).
+   *
+   * @param userPermissionIds - User's permission IDs
+   * @param prefix - GROQ prefix for nested queries
+   * @param isDereferencedContext - Whether we're in a dereferenced context
+   * @returns GROQ filter string for standard permissions
+   */
+  private buildStandardPermissionFilter(
+    userPermissionIds: string[],
+    prefix: string,
+    isDereferencedContext: boolean
+  ): string {
+    const clauses: string[] = []
+
+    // Content with no permissions is accessible to all
+    // A content has "no permissions" if BOTH permission and permission_v2 are empty/undefined
+    clauses.push(`((!defined(${prefix}permission) || count(${prefix}permission) == 0) && (!defined(${prefix}permission_v2) || count(${prefix}permission_v2) == 0))`)
+
+    // User has matching permissions
+    if (userPermissionIds.length > 0) {
+      clauses.push(this.buildPermissionCheck(userPermissionIds, prefix, isDereferencedContext))
+    }
+
+    return `(${clauses.join(' || ')})`
+  }
+
+  /**
+   * Build GROQ permission check for given permissions.
+   * Handles both dereferenced and standard contexts.
+   *
+   * @param permissions - Permission IDs to check
+   * @param prefix - GROQ prefix for nested queries
+   * @param isDereferencedContext - Whether we're in a dereferenced context
+   * @returns GROQ filter string for permission check
+   */
+  private buildPermissionCheck(
+    permissions: string[],
+    prefix: string,
+    isDereferencedContext: boolean
+  ): string {
+    if (isDereferencedContext) {
+      // In dereferenced context, check the permission array directly
+      return `((count((${prefix}permission[]._ref)[@ in *[_type == 'permission' && railcontent_id in ${arrayToRawRepresentation(permissions)}]._id]) > 0)
+      || count(array::intersects(${prefix}permission_v2, ${arrayToRawRepresentation(permissions)})) > 0)`
+    }
+    // In standard context, use references() function
+    return `(references(*[_type == 'permission' && railcontent_id in ${arrayToRawRepresentation(permissions)}]._id) ||
+     count(array::intersects(permission_v2, ${arrayToRawRepresentation(permissions)})) > 0)`
+  }
+
+  /**
+   * Get user's permission IDs.
+   *
+   * @param userPermissions - The user's permissions
+   * @returns Array of permission IDs
+   */
+  getUserPermissionIds(userPermissions: UserPermissions): string[] {
+    return userPermissions?.permissions ?? []
+  }
+}

package/src/services/permissions/README.md

@@ -0,0 +1,139 @@
+# Permissions Module
+
+**Internal abstraction layer for permissions in Musora Content Services.**
+
+## Purpose
+
+This module is **internal to MCS only** and provides a flexible contract between content services and permissions implementations, enabling seamless switching between v1 and v2.
+
+**Note:** This module is not exported from the package. External consumers should use `fetchUserPermissions()` if they need user permissions data.
+
+## Files
+
+- **`index.ts`** - Main exports (TypeScript)
+- **`PermissionsAdapter.ts`** - Abstract base class defining the contract (TypeScript)
+- **`PermissionsV1Adapter.ts`** - V1 implementation (current system, TypeScript)
+- **`PermissionsV2Adapter.ts`** - V2 implementation (placeholder, TypeScript)
+- **`PermissionsAdapterFactory.ts`** - Factory for getting appropriate adapter (TypeScript)
+
+## Usage (Internal MCS only)
+
+```typescript
+import { getPermissionsAdapter } from './permissions/index.js'
+
+// Get adapter (automatically selects v1 or v2 based on config)
+const adapter = getPermissionsAdapter()
+
+// Fetch user permissions
+const permissions = await adapter.fetchUserPermissions()
+
+// Check if user is admin
+if (adapter.isAdmin(permissions)) {
+  // Admin logic
+}
+
+// Check if user needs access to content
+const needsAccess = adapter.doesUserNeedAccess(content, permissions)
+
+// Generate GROQ filter for permissions
+const filter = adapter.generatePermissionsFilter(permissions, {
+  prefix: '',
+  showMembershipRestrictedContent: false,  // Set true to show membership-restricted content for upgrades
+})
+```
+
+## Configuration
+
+Set `permissionsVersion` in `initializeService()`:
+
+```javascript
+import { initializeService } from 'musora-content-services'
+
+initializeService({
+  // ... other config
+  permissionsVersion: 'v1', // 'v1' (default) or 'v2'
+})
+```
+
+## Documentation
+
+For full details, see the inline documentation in each TypeScript file.
+
+## Architecture
+
+```
+Internal MCS Code
+     ↓
+PermissionsAdapterFactory (getPermissionsAdapter)
+     ↓
+PermissionsV1Adapter OR PermissionsV2Adapter
+     ↓
+V1/V2 Implementation
+```
+
+
+## Contract
+
+All adapters must implement:
+
+- `fetchUserPermissions()` - Fetch user's permissions data
+- `doesUserNeedAccess(content, userPermissions)` - Check if user needs access
+- `generatePermissionsFilter(userPermissions, options)` - Generate GROQ filter
+- `getUserPermissionIds(userPermissions)` - Get permission IDs
+- `isAdmin(userPermissions)` - Check if user is admin
+
+## V1 Implementation
+
+Current permissions system:
+- Permission-based access using permission IDs
+- Basic members automatically get access to songs content (permission 92 added to their permissions)
+- Admins bypass all checks
+- Content with no permissions is accessible to all
+
+### Show Membership-Restricted Content
+
+V1 adapter supports showing membership-restricted content for upgrade prompts:
+
+```typescript
+const filter = adapter.generatePermissionsFilter(permissions, {
+  showMembershipRestrictedContent: true,
+})
+```
+
+This shows content requiring paid membership (permissions 91 for Basic, 92 for Plus) even if user doesn't have it. Content requiring other permissions (packs, individual purchases) is still filtered.
+
+**Use case:** Show non-members what membership-tier content is available to encourage upgrades.
+
+## V2 Implementation
+
+New permissions system (placeholder):
+- Different permission structure (TBD)
+
+## Testing
+
+Mock the adapter for tests:
+
+```typescript
+import { PermissionsAdapter, UserPermissions } from './permissions/PermissionsAdapter.js'
+
+class MockAdapter extends PermissionsAdapter {
+  async fetchUserPermissions(): Promise<UserPermissions> {
+    return { permissions: ['78', '91'], isAdmin: false, isABasicMember: true }
+  }
+
+  doesUserNeedAccess(content: any, userPermissions: UserPermissions): boolean {
+    return false // User has access
+  }
+
+  // ... implement other methods
+}
+```
+
+## Contributing
+
+When implementing V2:
+
+1. Update `PermissionsV2Adapter.ts` with v2 logic
+2. Test with `permissionsVersion: 'v2'` in `initializeService()`
+3. Update documentation
+4. Coordinate with frontend team for data structure changes