musora-content-services 2.81.0 → 2.83.0

package/src/index.js

@@ -68,6 +68,7 @@ import {
 	getLegacyMethods,
 	getLessonContentRows,
 	getNewAndUpcoming,
+	getOwnedContent,
 	getRecent,
 	getRecommendedForYou,
 	getScheduleContentRows,
@@ -124,6 +125,7 @@ import {
 
 import {
 	createForumCategory,
+	deleteForumCategory,
 	fetchForumCategories,
 	updateForumCategory
 } from './services/forums/categories.ts';
@@ -270,6 +272,7 @@ import {
 	fetchNewReleases,
 	fetchNextPreviousLesson,
 	fetchOtherSongVersions,
+	fetchOwnedContent,
 	fetchPackAll,
 	fetchPackData,
 	fetchPlayAlongsCount,
@@ -441,6 +444,7 @@ export {
 	createThread,
 	deleteAccount,
 	deleteComment,
+	deleteForumCategory,
 	deleteItemsFromPlaylist,
 	deleteNotification,
 	deletePicture,
@@ -518,6 +522,7 @@ export {
 	fetchNotificationSettings,
 	fetchNotifications,
 	fetchOtherSongVersions,
+	fetchOwnedContent,
 	fetchPackAll,
 	fetchPackData,
 	fetchPlayAlongsCount,
@@ -580,6 +585,7 @@ export {
 	getNewAndUpcoming,
 	getNextLesson,
 	getOnboardingRecommendedContent,
+	getOwnedContent,
 	getPracticeNotes,
 	getPracticeSessions,
 	getProgressDateByIds,

package/src/lib/lastUpdated.js

@@ -15,8 +15,8 @@ const excludeFromGeneratedIndex = ['wasLastUpdateOlderThanXSeconds', 'setLastUpd
  *
  * @returns {boolean} - True if the last update was older than X seconds, false otherwise.
  */
-export function wasLastUpdateOlderThanXSeconds(seconds, key) {
-  let lastUpdated = globalConfig.localStorage.getItem(key)
+export async function wasLastUpdateOlderThanXSeconds(seconds, key) {
+  let lastUpdated = await globalConfig.localStorage.getItem(key)
   if (!lastUpdated) return false
   const verifyServerTime = seconds * 1000
   return new Date().getTime() - lastUpdated > verifyServerTime
@@ -29,6 +29,6 @@ export function wasLastUpdateOlderThanXSeconds(seconds, key) {
  *
  * @returns {void}
  */
-export function setLastUpdatedTime(key) {
-  globalConfig.localStorage.setItem(key, new Date().getTime()?.toString())
+export async function setLastUpdatedTime(key) {
+  await globalConfig.localStorage.setItem(key, new Date().getTime()?.toString())
 }

package/src/services/config.js

@@ -12,6 +12,7 @@ export let globalConfig = {
   localStorage: null,
   isMA: false,
   localTimezoneString: null, // In format: America/Vancouver
+  permissionsVersion: 'v1', // 'v1' or 'v2'
 }
 
 /**
@@ -52,6 +53,7 @@ const excludeFromGeneratedIndex = []
  *   baseUrl: 'https://web-staging-one.musora.com',
  *   localStorage: localStorage,
  *   isMA: false,
+ *   permissionsVersion: 'v1', // Optional: 'v1' (default) or 'v2'
  * });
  */
 export function initializeService(config) {
@@ -62,4 +64,5 @@ export function initializeService(config) {
   globalConfig.localStorage = config.localStorage
   globalConfig.isMA = config.isMA || false
   globalConfig.localTimezoneString = config.localTimezoneString || null
+  globalConfig.permissionsVersion = config.permissionsVersion || 'v2'
 }

package/src/services/content/artist.ts

@@ -74,13 +74,13 @@ export interface ArtistLessonOptions {
 }
 
 export interface LessonsByArtistResponse {
-  entity: Artist[]
+  data: Artist[]
 }
 
 /**
  * Fetch the artist's lessons.
- * @param {string} brand - The brand for which to fetch lessons.
  * @param {string} slug - The slug of the artist
+ * @param {string} brand - The brand for which to fetch lessons.
  * @param {string} contentType - The type of the lessons we need to get from the artist. If not defined, groq will get lessons from all content types
  * @param {Object} params - Parameters for sorting, searching, pagination and filtering.
  * @param {string} [params.sort="-published_on"] - The field to sort the lessons by.
@@ -92,13 +92,13 @@ export interface LessonsByArtistResponse {
  * @returns {Promise<LessonsByArtistResponse|null>} - The lessons for the artist and some details about the artist (name and thumbnail).
  *
  * @example
- * fetchArtistLessons('drumeo', '10 Years', 'song', {'-published_on', '', 1, 10, ["difficulty,Intermediate"], [232168, 232824, 303375, 232194, 393125]})
+ * fetchArtistLessons('10 Years', 'drumeo', 'song', {'-published_on', '', 1, 10, ["difficulty,Intermediate"], [232168, 232824, 303375, 232194, 393125]})
  *   .then(lessons => console.log(lessons))
  *   .catch(error => console.error(error));
  */
 export async function fetchArtistLessons(
-  brand: string,
   slug: string,
+  brand: string,
   contentType: string,
   {
     sort = '-published_on',
@@ -127,7 +127,7 @@ export async function fetchArtistLessons(
     progressIds !== undefined ? `&& railcontent_id in [${progressIds.join(',')}]` : ''
   const now = getSanityDate(new Date())
   const query = `{
-    "entity":
+    "data":
       *[_type == 'artist' && slug.current == '${slug}']
         {'type': _type, name, 'thumbnail':thumbnail_url.asset->url,
         'lessons_count': count(*[${addType} brand == '${brand}' && references(^._id)]),
@@ -135,5 +135,5 @@ export async function fetchArtistLessons(
       [${start}...${end}]}
       |order(${sortOrder})
   }`
-  return fetchSanity(query, true)
+  return fetchSanity(query, true, { processNeedAccess: false, processPageType: false })
 }

package/src/services/content/genre.ts

@@ -39,7 +39,7 @@ export async function fetchGenres(brand: string): Promise<Genre[]> {
     'thumbnail': thumbnail_url.asset->url,
     "lessons_count": count(*[${filter}])
   } |order(lower(name)) `
-  return fetchSanity(query, true, { processNeedAccess: false, processPageType: false})
+  return fetchSanity(query, true, { processNeedAccess: false, processPageType: false })
 }
 
 /**
@@ -68,7 +68,7 @@ export async function fetchGenreBySlug(slug: string, brand?: string): Promise<Ge
     'thumbnail':thumbnail_url.asset->url,
     "lessonsCount": count(*[${filter}])
   }`
-  return fetchSanity(query, true, { processNeedAccess: false, processPageType: false})
+  return fetchSanity(query, true, { processNeedAccess: false, processPageType: false })
 }
 
 export interface FetchGenreLessonsOptions {
@@ -81,13 +81,13 @@ export interface FetchGenreLessonsOptions {
 }
 
 export interface LessonsByGenreResponse {
-  entity: Genre[]
+  data: Genre[]
 }
 
 /**
  * Fetch the genre's lessons.
- * @param {string} brand - The brand for which to fetch lessons.
  * @param {string} slug - The slug of the genre
+ * @param {string} brand - The brand for which to fetch lessons.
  * @param {Object} params - Parameters for sorting, searching, pagination and filtering.
  * @param {string} [params.sort="-published_on"] - The field to sort the lessons by.
  * @param {string} [params.searchTerm=""] - The search term to filter the lessons.
@@ -95,16 +95,16 @@ export interface LessonsByGenreResponse {
  * @param {number} [params.limit=10] - The number of items per page.
  * @param {Array<string>} [params.includedFields=[]] - Additional filters to apply to the query in the format of a key,value array. eg. ['difficulty,Intermediate', 'genre,rock'].
  * @param {Array<number>} [params.progressIds=[]] - The ids of the lessons that are in progress or completed
- * @returns {Promise<LessonsByGenreResponse>} - The lessons for the artist and some details about the artist (name and thumbnail).
+ * @returns {Promise<LessonsByGenreResponse|null>} - The lessons for the artist and some details about the artist (name and thumbnail).
  *
  * @example
- * fetchGenreLessons('drumeo', 'Blues', 'song', {'-published_on', '', 1, 10, ["difficulty,Intermediate"], [232168, 232824, 303375, 232194, 393125]})
+ * fetchGenreLessons('Blues', 'drumeo', 'song', {'-published_on', '', 1, 10, ["difficulty,Intermediate"], [232168, 232824, 303375, 232194, 393125]})
  *   .then(lessons => console.log(lessons))
  *   .catch(error => console.error(error));
  */
 export async function fetchGenreLessons(
-  brand: string,
   slug: string,
+  brand: string,
   contentType: string,
   {
     sort = '-published_on',
@@ -114,7 +114,7 @@ export async function fetchGenreLessons(
     includedFields = [],
     progressIds = [],
   }: FetchGenreLessonsOptions = {}
-): Promise<LessonsByGenreResponse> {
+): Promise<LessonsByGenreResponse | null> {
   const fieldsString = DEFAULT_FIELDS.join(',')
   const start = (page - 1) * limit
   const end = start + limit
@@ -127,12 +127,15 @@ export async function fetchGenreLessons(
     progressIds !== undefined ? `&& railcontent_id in [${progressIds.join(',')}]` : ''
   const now = getSanityDate(new Date())
   const query = `{
-    "entity":
+    "data":
       *[_type == 'genre' && slug.current == '${slug}']
-        {'type': _type, name, 'thumbnail':thumbnail_url.asset->url,
-        'lessons_count': count(*[${addType} brand == '${brand}' && references(^._id)]),
-        'lessons': *[${addType} brand == '${brand}' && references(^._id) && (status in ['published'] || (status == 'scheduled' && defined(published_on) && published_on >= '${now}')) ${searchFilter} ${includedFieldsFilter} ${progressFilter}]{${fieldsString}}
-      [${start}...${end}]}
+        {
+          'type': _type,
+          name,
+          'thumbnail': thumbnail_url.asset->url,
+          'lessons_count': count(*[${addType} brand == '${brand}' && references(^._id)]),
+          'lessons': *[${addType} brand == '${brand}' && references(^._id) && (status in ['published'] || (status == 'scheduled' && defined(published_on) && published_on >= '${now}')) ${searchFilter} ${includedFieldsFilter} ${progressFilter}]{${fieldsString}} [${start}...${end}]
+        }
       |order(${sortOrder})
   }`
   return fetchSanity(query, true)

package/src/services/content/instructor.ts

@@ -3,7 +3,7 @@
  */
 import { FilterBuilder } from '../../filterBuilder.js'
 import { filtersToGroq, getFieldsForContentType } from '../../contentTypeConfig.js'
-import { buildEntityAndTotalQuery, fetchSanity, getSortOrder } from '../sanity.js'
+import { fetchSanity, getSanityDate, getSortOrder } from '../sanity.js'
 import { Lesson } from './content'
 
 export interface Instructor {
@@ -80,8 +80,7 @@ export interface FetchInstructorLessonsOptions {
 }
 
 export interface InstructorLessonsResponse {
-  entity: Lesson[]
-  total: number
+  data: Lesson[]
 }
 
 /**
@@ -96,9 +95,9 @@ export interface InstructorLessonsResponse {
  * @param {number} [options.limit=10] - The number of items per page.
  * @param {Array<string>} [options.includedFields=[]] - Additional filters to apply to the query in the format of a key,value array. eg. ['difficulty,Intermediate', 'genre,rock'].
  *
- * @returns {Promise<InstructorLessonsResponse>} - The lessons for the instructor or null if not found.
+ * @returns {Promise<InstructorLessonsResponse|null>} - The lessons for the instructor or null if not found.
  * @example
- * fetchInstructorLessons('instructor123')
+ * fetchInstructorLessons('instructor123', 'drumeo', { page: 2, limit: 10 })
  *   .then(lessons => console.log(lessons))
  *   .catch(error => console.error(error));
  */
@@ -112,20 +111,26 @@ export async function fetchInstructorLessons(
     limit = 20,
     includedFields = [],
   }: FetchInstructorLessonsOptions = {}
-): Promise<InstructorLessonsResponse> {
+): Promise<InstructorLessonsResponse | null> {
   const fieldsString = getFieldsForContentType() as string
   const start = (page - 1) * limit
   const end = start + limit
   const searchFilter = searchTerm ? `&& title match "${searchTerm}*"` : ''
   const includedFieldsFilter = includedFields.length > 0 ? filtersToGroq(includedFields) : ''
-  const filter = `brand == '${brand}' ${searchFilter} ${includedFieldsFilter} && references(*[_type=='instructor' && slug.current == '${slug}']._id)`
-  const filterWithRestrictions = await new FilterBuilder(filter).buildFilter()
 
   sortOrder = getSortOrder(sortOrder, brand)
-  const query = buildEntityAndTotalQuery(filterWithRestrictions, fieldsString, {
-    sortOrder: sortOrder,
-    start: start,
-    end: end,
-  })
-  return fetchSanity(query, true)
+  const now = getSanityDate(new Date())
+  const query = `{
+    "data":
+      *[_type == 'instructor' && slug.current == '${slug}']
+        {
+          'type': _type,
+          name,
+          'thumbnail': thumbnail_url.asset->url,
+          'lessons_count': count(*[brand == '${brand}' && references(^._id)]),
+          'lessons': *[brand == '${brand}' && references(^._id) && (status in ['published'] || (status == 'scheduled' && defined(published_on) && published_on >= '${now}')) ${searchFilter} ${includedFieldsFilter}]{${fieldsString}} [${start}...${end}]
+        }
+      |order(${sortOrder})
+  }`
+  return fetchSanity(query, true, { processNeedAccess: false, processPageType: false })
 }

package/src/services/content.js

@@ -11,31 +11,52 @@ import {
   fetchUpcomingEvents,
   fetchScheduledReleases,
   fetchReturning,
-  fetchLeaving, fetchScheduledAndNewReleases, fetchContentRows
+  fetchLeaving, fetchScheduledAndNewReleases, fetchContentRows, fetchOwnedContent
 } from './sanity.js'
 import {TabResponseType, Tabs, capitalizeFirstLetter} from '../contentMetaData.js'
 import {recommendations, rankCategories, rankItems} from "./recommendations";
 import {addContextToContent} from "./contentAggregator.js";
+import {globalConfig} from "./config";
+import {getUserData} from "./user/management";
+import {filterTypes, ownedContentTypes} from "../contentTypeConfig";
 
 
 export async function getLessonContentRows (brand='drumeo', pageName = 'lessons') {
-  let [recentContentIds, contentRows] = await Promise.all([
+  const [recentContentIds, rawContentRows, userData] = await Promise.all([
     fetchRecent(brand, pageName, { progress: 'recent', limit: 10 }),
-    getContentRows(brand, pageName)
+    getContentRows(brand, pageName),
+    getUserData()
   ])
 
-  contentRows = Array.isArray(contentRows) ? contentRows : [];
+  const contentRows = Array.isArray(rawContentRows) ? rawContentRows : []
+
+  // Only fetch owned content if user has no active membership
+  if (!userData?.has_active_membership) {
+    const type = ownedContentTypes[pageName] || []
+
+    const ownedContent = await fetchOwnedContent(brand, { type })
+    if (ownedContent?.entity && ownedContent.entity.length > 0) {
+      contentRows.unshift({
+        id: 'owned',
+        title: 'Owned ' + capitalizeFirstLetter(pageName),
+        items: ownedContent.entity
+      })
+    }
+  }
+
+  // Add recent content row
   contentRows.unshift({
     id: 'recent',
     title: 'Recent ' + capitalizeFirstLetter(pageName),
     items: recentContentIds || []
-  });
+  })
 
   const results = await Promise.all(
-      contentRows.map(async (row) => {
-        return { id: row.id, title: row.title, items:  row.items }
-      })
+    contentRows.map(async (row) => {
+      return { id: row.id, title: row.title, items:  row.items }
+    })
   )
+
   return results
 }
 
@@ -213,6 +234,7 @@ export async function getContentRows(brand, pageName, contentRowSlug = null, {
     }
     slugNameMap[category.slug] = category.name
   }
+
   const start = (page - 1) * limit
   const end = start + limit
   const sortedData = await rankCategories(brand, recData)
@@ -451,3 +473,59 @@ export async function getLegacyMethods(brand) {
     },
   ]
 }
+
+/**
+ * Fetches content owned by the user (excluding membership content).
+ * Shows only content accessible through purchases/entitlements, not through membership.
+ *
+ * @param {string} brand - The brand for which to fetch owned content.
+ * @param {Object} [params={}] - Parameters for pagination and sorting.
+ * @param {Array<string>} [params.type=[]] - Content type(s) to filter (optional array).
+ * @param {number} [params.page=1] - The page number for pagination.
+ * @param {number} [params.limit=10] - The number of items per page.
+ * @param {string} [params.sort='-published_on'] - The field to sort the data by.
+ * @returns {Promise<Object>} - The fetched owned content with entity array and total count.
+ *
+ * @example
+ * // Fetch all owned content with default pagination
+ * getOwnedContent('drumeo')
+ *   .then(content => console.log(content))
+ *   .catch(error => console.error(error));
+ *
+ * @example
+ * // Fetch owned content with custom pagination and sorting
+ * getOwnedContent('drumeo', {
+ *   page: 2,
+ *   limit: 20,
+ *   sort: '-published_on'
+ * })
+ *   .then(content => console.log(content))
+ *   .catch(error => console.error(error));
+ *
+ * @example
+ * // Fetch owned content filtered by types
+ * getOwnedContent('drumeo', {
+ *   type: ['course', 'pack'],
+ *   page: 1,
+ *   limit: 10
+ * })
+ *   .then(content => console.log(content))
+ *   .catch(error => console.error(error));
+ */
+export async function getOwnedContent(brand, {
+  type = [],
+  page = 1,
+  limit = 10,
+  sort = '-published_on',
+} = {}) {
+  const data = await fetchOwnedContent(brand, { type, page, limit, sort });
+
+  if (!data) {
+    return {
+      entity: [],
+      total: 0
+    };
+  }
+
+  return data;
+}

package/src/services/contentAggregator.js

@@ -108,9 +108,9 @@ export async function addContextToContent(dataPromise, ...dataArgs) {
 
   const addContext = async (item) => ({
     ...item,
-    ...(addProgressPercentage ? { progressPercentage: progressData?.[item.id]['progress'] } : {}),
-    ...(addProgressStatus ? { progressStatus: progressData?.[item.id]['status'] } : {}),
-    ...(addProgressTimestamp ? { progressTimestamp: progressData?.[item.id]['last_update'] } : {}),
+    ...(addProgressPercentage ? { progressPercentage: progressData?.[item.id]?.progress } : {}),
+    ...(addProgressStatus ? { progressStatus: progressData?.[item.id]?.status } : {}),
+    ...(addProgressTimestamp ? { progressTimestamp: progressData?.[item.id]?.last_update } : {}),
     ...(addIsLiked ? { isLiked: isLikedData?.[item.id] } : {}),
     ...(addLikeCount && ids.length === 1 ? { likeCount: await fetchLikeCount(item.id) } : {}),
     ...(addResumeTimeSeconds ? { resumeTime: resumeTimeData?.[item.id] } : {}),
@@ -144,7 +144,7 @@ export async function getNavigateToForPlaylists(data, { dataField = null } = {})
       const progress = progressOnItems[itemId]
       return progress && progress === 'completed'
     })
-    let nextItem = accessibleItems[0] ?? null
+    let nextItem = accessibleItems[0] ?? playlist.items[0] ?? null
     if (!allItemsCompleted) {
       const lastItemProgress = progressOnItems[playlist.last_engaged_on]
       const index = accessibleItems.findIndex((i) => i.content_id === playlist.last_engaged_on)

package/src/services/contentProgress.js

@@ -50,7 +50,10 @@ export async function getNextLesson(data) {
   let nextLessonData = {}
 
   for (const content of data) {
-    const children = content.children?.map((child) => child.id) ?? []
+    // Skip null/undefined entries (can happen when GROQ dereference doesn't match filter)
+    if (!content) continue
+
+    const children = content.children?.filter(Boolean).map((child) => child.id) ?? []
     //only calculate nextLesson if needed, based on content type
     if (!getNextLessonLessonParentTypes.includes(content.type)) {
       nextLessonData[content.id] = null
@@ -101,20 +104,30 @@ export async function getNavigateTo(data) {
   //TODO add parent hierarchy upwards as well
   // data structure is the same but instead of child{} we use parent{}
   for (const content of data) {
+    // Skip null/undefined entries (can happen when GROQ dereference doesn't match filter)
+    if (!content) continue
+
     //only calculate nextLesson if needed, based on content type
     if (!getNextLessonLessonParentTypes.includes(content.type) || !content.children) {
       navigateToData[content.id] = null
     } else {
+      // Filter out null/undefined children (can happen with permission filters)
+      const validChildren = content.children.filter(Boolean)
+      if (validChildren.length === 0) {
+        navigateToData[content.id] = null
+        continue
+      }
+
       const children = new Map()
       const childrenIds = []
-      content.children.forEach((child) => {
+      validChildren.forEach((child) => {
         childrenIds.push(child.id)
         children.set(child.id, child)
       })
       // return first child (or grand child) if parent-content is complete or no progress
       const contentState = await getProgressState(content.id)
       if (contentState !== STATE_STARTED) {
-        const firstChild = content.children[0]
+        const firstChild = validChildren[0]
         let lastInteractedChildNavToData = await getNavigateTo([firstChild])
         lastInteractedChildNavToData = lastInteractedChildNavToData[firstChild.id] ?? null
         navigateToData[content.id] = buildNavigateTo(firstChild, lastInteractedChildNavToData)

package/src/services/forums/categories.ts

@@ -63,3 +63,22 @@ export async function updateForumCategory(
   const httpClient = new HttpClient(globalConfig.baseUrl)
   return httpClient.put<ForumCategory>(`${baseUrl}/v1/categories/${params.id}`, params)
 }
+
+export interface DeleteForumCategoryParams {
+  id: number
+  brand: string
+}
+
+/**
+ * Deletes a forum category.
+ *
+ * @param {DeleteForumCategoryParams} params - The parameters for deleting the forum category.
+ * @returns {Promise<void>} - A promise that resolves when the category is deleted.
+ * @throws {HttpError} - If the request fails.
+ */
+export async function deleteForumCategory(
+  params: DeleteForumCategoryParams
+): Promise<void> {
+  const httpClient = new HttpClient(globalConfig.baseUrl)
+  return httpClient.delete<void>(`${baseUrl}/v1/categories/${params.id}?brand=${params.brand}`)
+}

package/src/services/permissions/PermissionsAdapter.ts

@@ -0,0 +1,111 @@
+/**
+ * @module PermissionsAdapter
+ *
+ * Abstract base class defining the contract for permissions operations.
+ * This abstraction allows swapping between different permission implementations
+ * (v1 and v2) without changing consumer code.
+ */
+
+/**
+ * User permissions data structure
+ */
+export interface UserPermissions {
+  /** Array of permission IDs the user has access to */
+  permissions: string[]
+  /** Whether the user is an admin */
+  isAdmin: boolean
+  /** Whether the user has basic membership */
+  isABasicMember: boolean
+  /** User's access level (v2 - for future use) */
+  access_level?: string
+}
+
+/**
+ * Options for generating permission filters
+ */
+export interface PermissionFilterOptions {
+  /** GROQ prefix for nested queries (e.g., '^.' for parent, '@->' for children) */
+  prefix?: string
+  /**
+   * If true, show content that requires paid membership even if user doesn't have it.
+   * Used for upgrade prompts. V1: includes permissions [91, 92]. V2: shows content with membership_tier='plus'|'basic'|'free'
+   */
+  showMembershipRestrictedContent?: boolean
+  /**
+   * If true, show only content owned by user through purchases/entitlements, excluding membership content.
+   * V1: excludes permissions [91, 92]. V2: excludes content with membership_tier='plus'|'basic'
+   */
+  showOnlyOwnedContent?: boolean
+}
+
+/**
+ * Content item with permission requirements
+ */
+export interface ContentItem {
+  /** Array of permission IDs required to access this content */
+  permission_id?: string[]
+  [key: string]: any
+}
+
+/**
+ * Abstract base class for permissions adapters.
+ * Subclasses must implement all methods to provide version-specific logic.
+ */
+export abstract class PermissionsAdapter {
+  /**
+   * Fetch user permissions data.
+   *
+   * @returns The user's permissions data
+   * @abstract
+   */
+  abstract fetchUserPermissions(): Promise<UserPermissions>
+
+  /**
+   * Check if user needs access to specific content.
+   * Returns true if the user does NOT have access and needs to upgrade/purchase.
+   *
+   * @param content - The content item to check
+   * @param userPermissions - The user's permissions
+   * @returns True if user needs access, false if they already have it
+   * @abstract
+   */
+  abstract doesUserNeedAccess(
+    content: ContentItem,
+    userPermissions: UserPermissions
+  ): boolean
+
+  /**
+   * Generate GROQ filter string for permissions.
+   * Returns null if no filter should be applied (e.g., admin user).
+   *
+   * @param userPermissions - The user's permissions
+   * @param options - Options for filter generation
+   * @returns GROQ filter string or null
+   * @abstract
+   */
+  abstract generatePermissionsFilter(
+    userPermissions: UserPermissions,
+    options?: PermissionFilterOptions
+  ): string | null
+
+  /**
+   * Get user's permission IDs.
+   * Useful for cases where you need raw permission IDs.
+   *
+   * @param userPermissions - The user's permissions
+   * @returns Array of permission IDs
+   * @abstract
+   */
+  abstract getUserPermissionIds(userPermissions: UserPermissions): string[]
+
+  /**
+   * Check if user is an admin.
+   * Admins typically bypass all permission checks.
+   *
+   * @param userPermissions - The user's permissions
+   * @returns True if user is admin
+   */
+  isAdmin(userPermissions: UserPermissions): boolean {
+    return userPermissions?.isAdmin ?? false
+  }
+}