convex-cms 0.0.1

package/dist/client/wrapper.js

@@ -0,0 +1,2651 @@
+/** CMS Client Wrapper with typed method APIs */
+/** @internal Bridges wrapper's simplified types to generated Convex types */
+function _callMutation(ctx, fn, args) {
+    return ctx.runMutation(fn, args);
+}
+/** @internal */
+function callQuery(ctx, fn, args) {
+    return ctx.runQuery(fn, args);
+}
+import { resolveConfig, AuthorizationNotConfiguredError } from "./types.js";
+// Import query builder
+import { createQueryBuilder } from "./queryBuilder.js";
+// Import authorization hooks execution
+import { executeAuthorizationHooks, contextToRbacOptions, operationToRbac, } from "../component/authorizationHooks.js";
+// Import rate limit hooks execution
+import { requireRateLimit, createRateLimitContext, } from "../component/rateLimitHooks.js";
+// Import RBAC utilities from component
+import { hasPermission, hasContentTypePermission, getPermittedContentTypes, DEFAULT_ROLES, } from "../component/roles.js";
+// Import locale fallback chain utilities
+import { resolveFallbackChain, getFallbackChain, } from "../component/localeFallbackChain.js";
+import { resolveLocaleContent, resolveLocaleContentBatch, } from "../component/localeFields.js";
+// =============================================================================
+// Content Types API Wrapper
+// =============================================================================
+/** Content type CRUD operations */
+export class ContentTypesApi {
+    api;
+    config;
+    authHelper;
+    rateLimitHelper;
+    constructor(api, config, authHelper, rateLimitHelper) {
+        this.api = api;
+        this.config = config;
+        this.authHelper = authHelper;
+        this.rateLimitHelper = rateLimitHelper;
+    }
+    /** @throws AuthorizationNotConfiguredError if not configured and not in permissiveMode */
+    async authorize(ctx, operation, userId, resourceId) {
+        // Check if authorization is configured
+        if (!this.authHelper) {
+            if (this.config.permissiveMode) {
+                console.warn(`[ConvexCMS] Authorization not configured for "${operation}". ` +
+                    "Operations are allowed in permissiveMode, but this should NOT be used in production. " +
+                    "Configure getUserRole hook to enable proper authorization.");
+                return;
+            }
+            throw new AuthorizationNotConfiguredError(operation);
+        }
+        // Skip RBAC checks if explicitly disabled
+        if (this.authHelper.skipRbac) {
+            return;
+        }
+        // Check if userId is provided
+        if (!userId) {
+            if (this.config.permissiveMode) {
+                console.warn(`[ConvexCMS] Anonymous operation attempted for "${operation}". ` +
+                    "Operations without userId are allowed in permissiveMode, but this should NOT be used in production.");
+                return;
+            }
+            throw new AuthorizationNotConfiguredError(`${operation} (no userId provided - anonymous operations require permissiveMode)`);
+        }
+        const role = await this.authHelper.getUserRole(ctx, userId);
+        await this.authHelper.requireAuthorization(ctx, {
+            operation,
+            userId,
+            role,
+            resourceId,
+        });
+    }
+    async rateLimit(ctx, operation, userId) {
+        if (!this.rateLimitHelper)
+            return;
+        const role = userId ? await this.rateLimitHelper.getUserRole(ctx, userId) : null;
+        await this.rateLimitHelper.requireRateLimit(operation, { userId, role });
+    }
+    async create(ctx, args) {
+        await this.authorize(ctx, "contentTypes.create", args.createdBy);
+        await this.rateLimit(ctx, "contentTypes.create", args.createdBy);
+        return ctx.runMutation(this.api.contentTypeMutations.createContentType, args);
+    }
+    /** Detects breaking changes; fails unless force:true is specified */
+    async update(ctx, args) {
+        await this.authorize(ctx, "contentTypes.update", args.updatedBy, args.id);
+        await this.rateLimit(ctx, "contentTypes.update", args.updatedBy);
+        return ctx.runMutation(this.api.contentTypeMutations.updateContentType, args);
+    }
+    /** Soft delete by default; use hardDelete:true for permanent, cascade:true to delete entries */
+    async delete(ctx, args) {
+        await this.authorize(ctx, "contentTypes.delete", args.deletedBy, args.id);
+        await this.rateLimit(ctx, "contentTypes.delete", args.deletedBy);
+        return ctx.runMutation(this.api.contentTypeMutations.deleteContentType, args);
+    }
+    /**
+     * Get a content type by ID or name.
+     *
+     * @param ctx - Convex query context
+     * @param args - Get arguments (id or name)
+     * @returns The content type or null if not found
+     *
+     * @example
+     * ```typescript
+     * // Get by ID (fastest - direct document lookup)
+     * const type = await cms.contentTypes.get(ctx, { id: typeId });
+     *
+     * // Get by name (uses index)
+     * const type = await cms.contentTypes.get(ctx, { name: "blog_post" });
+     *
+     * // Include soft-deleted types
+     * const type = await cms.contentTypes.get(ctx, {
+     *   name: "archived_type",
+     *   includeDeleted: true,
+     * });
+     * ```
+     */
+    async get(ctx, args) {
+        return ctx.runQuery(this.api.contentTypes.get, args);
+    }
+    /**
+     * Get a content type by name.
+     *
+     * Convenience method that wraps `get()` for name-based lookup.
+     *
+     * @param ctx - Convex query context
+     * @param name - The machine-readable name of the content type
+     * @param includeDeleted - Whether to include soft-deleted types
+     * @returns The content type or null if not found
+     *
+     * @example
+     * ```typescript
+     * const blogType = await cms.contentTypes.getByName(ctx, "blog_post");
+     * if (blogType) {
+     *   console.log("Fields:", blogType.fields);
+     * }
+     * ```
+     */
+    async getByName(ctx, name, includeDeleted = false) {
+        return this.get(ctx, { name, includeDeleted });
+    }
+    async getById(ctx, id, includeDeleted = false) {
+        return this.get(ctx, { id, includeDeleted });
+    }
+    async exists(ctx, name, includeDeleted = false) {
+        const type = await this.getByName(ctx, name, includeDeleted);
+        return type !== null;
+    }
+    async list(ctx, args = {}) {
+        return ctx.runQuery(this.api.contentTypes.list, args);
+    }
+    async listActive(ctx, paginationOpts) {
+        return this.list(ctx, { isActive: true, includeDeleted: false, paginationOpts });
+    }
+    async getAll(ctx, includeInactive = false) {
+        const result = await this.list(ctx, { isActive: includeInactive ? undefined : true, includeDeleted: false });
+        return result.page;
+    }
+    /**
+     * @example
+     * ```typescript
+     * const count = await cms.contentTypes.count(ctx);
+     * console.log(`You have ${count} content types`);
+     * ```
+     */
+    async count(ctx, includeInactive = false) {
+        const all = await this.getAll(ctx, includeInactive);
+        return all.length;
+    }
+    /**
+     * Deactivate a content type without deleting it.
+     *
+     * Deactivated types remain in the database but are filtered out by default
+     * when listing content types. Existing content entries remain accessible.
+     *
+     * @param ctx - Convex mutation context
+     * @param id - The content type ID to deactivate
+     * @param updatedBy - User ID making the change
+     * @returns The updated content type
+     *
+     * @example
+     * ```typescript
+     * await cms.contentTypes.deactivate(ctx, contentTypeId, currentUserId);
+     * ```
+     */
+    async deactivate(ctx, id, updatedBy) {
+        return this.update(ctx, { id, isActive: false, updatedBy });
+    }
+    /**
+     * Reactivate a previously deactivated content type.
+     *
+     * @param ctx - Convex mutation context
+     * @param id - The content type ID to reactivate
+     * @param updatedBy - User ID making the change
+     * @returns The updated content type
+     *
+     * @example
+     * ```typescript
+     * await cms.contentTypes.reactivate(ctx, contentTypeId, currentUserId);
+     * ```
+     */
+    async reactivate(ctx, id, updatedBy) {
+        return this.update(ctx, { id, isActive: true, updatedBy });
+    }
+}
+// =============================================================================
+// Content Entries API Wrapper
+// =============================================================================
+/** Content entry CRUD and workflow operations */
+export class ContentEntriesApi {
+    api;
+    config;
+    authHelper;
+    rateLimitHelper;
+    constructor(api, config, authHelper, rateLimitHelper) {
+        this.api = api;
+        this.config = config;
+        this.authHelper = authHelper;
+        this.rateLimitHelper = rateLimitHelper;
+    }
+    /** @throws AuthorizationNotConfiguredError if not configured and not in permissiveMode */
+    async authorize(ctx, operation, userId, resourceId, resourceOwnerId, contentTypeId) {
+        if (!this.authHelper) {
+            if (this.config.permissiveMode) {
+                console.warn(`[ConvexCMS] Authorization not configured for "${operation}". ` +
+                    "Operations are allowed in permissiveMode, but this should NOT be used in production.");
+                return;
+            }
+            throw new AuthorizationNotConfiguredError(operation);
+        }
+        if (this.authHelper.skipRbac)
+            return;
+        if (!userId) {
+            if (this.config.permissiveMode) {
+                console.warn(`[ConvexCMS] Anonymous operation attempted for "${operation}". ` +
+                    "Operations without userId are allowed in permissiveMode, but this should NOT be used in production.");
+                return;
+            }
+            throw new AuthorizationNotConfiguredError(`${operation} (no userId provided - anonymous operations require permissiveMode)`);
+        }
+        const role = await this.authHelper.getUserRole(ctx, userId);
+        await this.authHelper.requireAuthorization(ctx, { operation, userId, role, resourceId, resourceOwnerId, contentTypeId });
+    }
+    async rateLimit(ctx, operation, userId, contentTypeId) {
+        if (!this.rateLimitHelper)
+            return;
+        const role = userId ? await this.rateLimitHelper.getUserRole(ctx, userId) : null;
+        await this.rateLimitHelper.requireRateLimit(operation, { userId, role, contentTypeId });
+    }
+    async create(ctx, args) {
+        await this.authorize(ctx, "contentEntries.create", args.createdBy, undefined, undefined, args.contentTypeId);
+        await this.rateLimit(ctx, "contentEntries.create", args.createdBy, args.contentTypeId);
+        const argsWithDefaults = { ...args, locale: args.locale ?? this.config.defaultLocale };
+        return ctx.runMutation(this.api.contentEntryMutations.createEntry, argsWithDefaults);
+    }
+    async update(ctx, args) {
+        const entry = await ctx.runQuery(this.api.contentEntries.get, { id: args.id });
+        if (!entry)
+            throw new Error(`Content entry not found: ${args.id}`);
+        await this.authorize(ctx, "contentEntries.update", args.updatedBy, args.id, entry.createdBy, entry.contentTypeId);
+        await this.rateLimit(ctx, "contentEntries.update", args.updatedBy, entry.contentTypeId);
+        return ctx.runMutation(this.api.contentEntryMutations.updateEntry, args);
+    }
+    async delete(ctx, args) {
+        const entry = await ctx.runQuery(this.api.contentEntries.get, { id: args.id });
+        if (!entry)
+            throw new Error(`Content entry not found: ${args.id}`);
+        await this.authorize(ctx, "contentEntries.delete", args.deletedBy, args.id, entry.createdBy, entry.contentTypeId);
+        await this.rateLimit(ctx, "contentEntries.delete", args.deletedBy, entry.contentTypeId);
+        return ctx.runMutation(this.api.contentEntryMutations.deleteEntry, args);
+    }
+    async get(ctx, args) {
+        return ctx.runQuery(this.api.contentEntries.get, args);
+    }
+    /** Looks up by contentTypeId+slug or contentTypeName+slug */
+    async getBySlug(ctx, args) {
+        // The wrapper's unified interface adapts to the component's split API
+        if (args.contentTypeId) {
+            return ctx.runQuery(this.api.contentEntries.getBySlug, {
+                contentTypeId: args.contentTypeId,
+                slug: args.slug,
+                includeDeleted: false,
+            });
+        }
+        if (args.contentTypeName) {
+            return ctx.runQuery(this.api.contentEntries.getBySlugAndTypeName, {
+                contentTypeName: args.contentTypeName,
+                slug: args.slug,
+                includeDeleted: false,
+            });
+        }
+        throw new Error("getBySlug requires either contentTypeId or contentTypeName");
+    }
+    /** Standard Convex pagination format compatible with usePaginatedQuery */
+    async list(ctx, args) {
+        return ctx.runQuery(this.api.contentEntries.list, args);
+    }
+    /**
+     * Publish a content entry.
+     *
+     * @param ctx - Convex mutation context
+     * @param args - Publish arguments
+     * @returns The published entry
+     */
+    async publish(ctx, args) {
+        // Fetch entry for ownership-based authorization
+        const entry = await ctx.runQuery(this.api.contentEntries.get, { id: args.id });
+        if (!entry) {
+            throw new Error(`Content entry not found: ${args.id}`);
+        }
+        // Authorization check - contentEntries.publish (with ownership info)
+        await this.authorize(ctx, "contentEntries.publish", args.updatedBy, args.id, entry.createdBy, entry.contentTypeId);
+        // Rate limit check - contentEntries.publish
+        await this.rateLimit(ctx, "contentEntries.publish", args.updatedBy, entry.contentTypeId);
+        return ctx.runMutation(this.api.contentEntryMutations.publishEntry, args);
+    }
+    /**
+     * Unpublish a content entry (revert to draft).
+     *
+     * @param ctx - Convex mutation context
+     * @param args - Unpublish arguments
+     * @returns The unpublished entry
+     */
+    async unpublish(ctx, args) {
+        // Fetch entry for ownership-based authorization
+        const entry = await ctx.runQuery(this.api.contentEntries.get, { id: args.id });
+        if (!entry) {
+            throw new Error(`Content entry not found: ${args.id}`);
+        }
+        // Authorization check - contentEntries.unpublish (with ownership info)
+        await this.authorize(ctx, "contentEntries.unpublish", args.updatedBy, args.id, entry.createdBy, entry.contentTypeId);
+        // Rate limit check - contentEntries.unpublish
+        await this.rateLimit(ctx, "contentEntries.unpublish", args.updatedBy, entry.contentTypeId);
+        return ctx.runMutation(this.api.contentEntryMutations.unpublishEntry, args);
+    }
+    /**
+     * Schedule a content entry for future publication.
+     *
+     * @param ctx - Convex mutation context
+     * @param args - Schedule arguments
+     * @returns The scheduled entry
+     *
+     * @example
+     * ```typescript
+     * await cms.contentEntries.schedule(ctx, {
+     *   id: entryId,
+     *   publishAt: Date.now() + 24 * 60 * 60 * 1000, // Tomorrow
+     * });
+     * ```
+     */
+    async schedule(ctx, args) {
+        if (!this.config.features.scheduling) {
+            throw new Error("Scheduling feature is not enabled");
+        }
+        // Fetch entry for ownership-based authorization
+        const entry = await ctx.runQuery(this.api.contentEntries.get, { id: args.id });
+        if (!entry) {
+            throw new Error(`Content entry not found: ${args.id}`);
+        }
+        // Authorization check - contentEntries.schedule (with ownership info)
+        await this.authorize(ctx, "contentEntries.schedule", args.updatedBy, args.id, entry.createdBy, entry.contentTypeId);
+        // Rate limit check - contentEntries.schedule
+        await this.rateLimit(ctx, "contentEntries.schedule", args.updatedBy, entry.contentTypeId);
+        return ctx.runMutation(this.api.scheduledPublish.scheduleEntry, args);
+    }
+    /**
+     * Restore a soft-deleted content entry.
+     *
+     * Removes the deletedAt timestamp from a soft-deleted entry,
+     * making it active again. Only works for soft-deleted entries;
+     * hard-deleted entries cannot be recovered.
+     *
+     * @param ctx - Convex mutation context
+     * @param args - Restore arguments
+     * @returns The restored entry
+     *
+     * @example
+     * ```typescript
+     * // Restore a soft-deleted entry
+     * const restored = await cms.contentEntries.restore(ctx, {
+     *   id: entryId,
+     *   restoredBy: currentUserId,
+     * });
+     * console.log(restored.deletedAt); // undefined
+     * ```
+     */
+    async restore(ctx, args) {
+        if (!this.config.features.softDelete) {
+            throw new Error("Soft delete feature is not enabled");
+        }
+        // Fetch entry for ownership-based authorization
+        const entry = await ctx.runQuery(this.api.contentEntries.get, { id: args.id });
+        if (!entry) {
+            throw new Error(`Content entry not found: ${args.id}`);
+        }
+        // Authorization check - contentEntries.restore (with ownership info)
+        await this.authorize(ctx, "contentEntries.restore", args.restoredBy, args.id, entry.createdBy, entry.contentTypeId);
+        // Rate limit check - contentEntries.restore
+        await this.rateLimit(ctx, "contentEntries.restore", args.restoredBy, entry.contentTypeId);
+        return ctx.runMutation(this.api.contentEntryMutations.restoreEntry, args);
+    }
+    /**
+     * Create a fluent query builder for constructing complex content queries.
+     *
+     * The query builder provides a chainable API for building queries with:
+     * - Content type filtering
+     * - Status filtering (single or multiple)
+     * - Field-level filters with various operators
+     * - Full-text search
+     * - Locale filtering
+     * - Cursor-based pagination
+     * - Sort direction
+     *
+     * @returns A new ContentQueryBuilder instance
+     *
+     * @example
+     * ```typescript
+     * // Simple query
+     * const posts = await cms.contentEntries
+     *   .query()
+     *   .contentType("blog_post")
+     *   .status("published")
+     *   .limit(10)
+     *   .execute(ctx);
+     *
+     * // Complex query with field filters
+     * const featured = await cms.contentEntries
+     *   .query()
+     *   .contentType("blog_post")
+     *   .where("category", "eq", "technology")
+     *   .whereContains("tags", "featured")
+     *   .whereGreaterThan("views", 100)
+     *   .newestFirst()
+     *   .limit(5)
+     *   .execute(ctx);
+     *
+     * // Pagination
+     * const page1 = await cms.contentEntries
+     *   .query()
+     *   .contentType("blog_post")
+     *   .limit(20)
+     *   .execute(ctx);
+     *
+     * const page2 = await cms.contentEntries
+     *   .query()
+     *   .contentType("blog_post")
+     *   .limit(20)
+     *   .cursor(page1.continueCursor)
+     *   .execute(ctx);
+     *
+     * // Get first result only
+     * const latest = await cms.contentEntries
+     *   .query()
+     *   .contentType("blog_post")
+     *   .published()
+     *   .newestFirst()
+     *   .first(ctx);
+     *
+     * // Check if results exist
+     * const hasPublished = await cms.contentEntries
+     *   .query()
+     *   .contentType("blog_post")
+     *   .published()
+     *   .exists(ctx);
+     * ```
+     */
+    query() {
+        return createQueryBuilder(this.api);
+    }
+    /**
+     * Resolve locale content for a single content entry.
+     *
+     * Takes a content entry with potentially localized field values and resolves
+     * all localized fields to single values based on the requested locale and
+     * fallback chain. This merges localized and default field values.
+     *
+     * Resolution order for each localized field:
+     * 1. Try the requested locale
+     * 2. Try each locale in the fallback chain (in order)
+     * 3. Try the default locale
+     * 4. Return first available locale as last resort
+     *
+     * @param entry - The content entry to resolve (with raw localized data)
+     * @param options - Locale resolution options
+     * @returns The entry with resolved data and metadata about resolution
+     *
+     * @example
+     * ```typescript
+     * // Get an entry
+     * const entry = await cms.contentEntries.get(ctx, { id: entryId });
+     *
+     * // Resolve to Spanish with English fallback
+     * const resolved = cms.contentEntries.resolveLocale(entry, {
+     *   locale: "es-ES",
+     *   fallbackChain: ["en-US"],
+     *   defaultLocale: "en-US",
+     *   fields: contentType.fields,
+     * });
+     *
+     * // Access resolved data
+     * console.log(resolved.data.title); // "Hola" (Spanish) or "Hello" (English fallback)
+     *
+     * // Check which fields used fallback
+     * if (resolved.localeResolution.fieldsFromFallback.includes("title")) {
+     *   console.log("Title was not translated to Spanish");
+     * }
+     *
+     * // See which locale each field was resolved from
+     * console.log(resolved.localeResolution.fieldResolutions);
+     * // { content: "en-US" } - content was resolved from English
+     * ```
+     */
+    resolveLocale(entry, options) {
+        return resolveLocaleContent(entry, options);
+    }
+    /**
+     * Resolve locale content for multiple content entries.
+     *
+     * Convenience method for batch-resolving a list of entries.
+     * Useful after fetching a paginated list of content entries.
+     *
+     * @param entries - Array of content entries to resolve
+     * @param options - Locale resolution options (applied to all entries)
+     * @returns Array of entries with resolved locale data
+     *
+     * @example
+     * ```typescript
+     * // Fetch published blog posts
+     * const { page } = await cms.contentEntries.list(ctx, {
+     *   contentTypeName: "blog_post",
+     *   status: "published",
+     *   paginationOpts: { numItems: 10 },
+     * });
+     *
+     * // Resolve all entries to Spanish
+     * const resolvedPosts = cms.contentEntries.resolveLocaleBatch(page, {
+     *   locale: "es-ES",
+     *   fallbackChain: cms.getLocaleFallbackChain("es-ES"),
+     *   defaultLocale: cms.config.defaultLocale,
+     *   fields: blogPostType.fields,
+     * });
+     *
+     * // Use resolved data
+     * for (const post of resolvedPosts) {
+     *   console.log(post.data.title); // Resolved title in Spanish or fallback
+     * }
+     * ```
+     */
+    resolveLocaleBatch(entries, options) {
+        return resolveLocaleContentBatch(entries, options);
+    }
+    /**
+     * List content entries with automatic locale resolution.
+     *
+     * This is a convenience method that combines `list()` and `resolveLocaleBatch()`
+     * into a single call. It fetches content entries and automatically resolves
+     * all localized fields to the requested locale with fallback support.
+     *
+     * Note: This method requires the content type's field definitions to properly
+     * resolve localized fields. You can either pass them explicitly or let the
+     * method fetch them automatically (requires an extra query).
+     *
+     * @param ctx - Convex query context
+     * @param args - Query options with pagination
+     * @param localeOptions - Locale resolution options
+     * @returns Paginated result with locale-resolved entries
+     *
+     * @example
+     * ```typescript
+     * // List with locale resolution
+     * const { page, continueCursor, isDone } = await cms.contentEntries.listWithLocale(
+     *   ctx,
+     *   {
+     *     contentTypeName: "blog_post",
+     *     status: "published",
+     *     paginationOpts: { numItems: 10 },
+     *   },
+     *   {
+     *     locale: "es-ES",
+     *     fields: blogPostType.fields, // Required for resolution
+     *   }
+     * );
+     *
+     * // All entries have resolved locale data
+     * for (const post of page) {
+     *   console.log(post.data.title); // Resolved title
+     *   console.log(post.localeResolution.fieldsFromFallback); // Which fields used fallback
+     * }
+     * ```
+     */
+    async listWithLocale(ctx, args, localeOptions) {
+        // Fetch raw entries
+        const result = await this.list(ctx, args);
+        // Resolve locale for all entries
+        const resolvedPage = this.resolveLocaleBatch(result.page, localeOptions);
+        return {
+            page: resolvedPage,
+            continueCursor: result.continueCursor,
+            isDone: result.isDone,
+        };
+    }
+    /**
+     * Get a content entry by ID with automatic locale resolution.
+     *
+     * Fetches the entry and resolves all localized fields to the requested locale.
+     *
+     * @param ctx - Convex query context
+     * @param args - Get arguments
+     * @param localeOptions - Locale resolution options
+     * @returns The entry with resolved locale data, or null if not found
+     *
+     * @example
+     * ```typescript
+     * const post = await cms.contentEntries.getWithLocale(
+     *   ctx,
+     *   { id: entryId },
+     *   {
+     *     locale: "es-ES",
+     *     fallbackChain: ["en-US"],
+     *     defaultLocale: "en-US",
+     *     fields: blogPostType.fields,
+     *   }
+     * );
+     *
+     * if (post) {
+     *   console.log(post.data.title); // Resolved title
+     * }
+     * ```
+     */
+    async getWithLocale(ctx, args, localeOptions) {
+        const entry = await this.get(ctx, args);
+        if (!entry)
+            return null;
+        return this.resolveLocale(entry, localeOptions);
+    }
+    /**
+     * Get a content entry by slug with automatic locale resolution.
+     *
+     * Fetches the entry by slug and resolves all localized fields to the requested locale.
+     *
+     * @param ctx - Convex query context
+     * @param args - Get by slug arguments
+     * @param localeOptions - Locale resolution options
+     * @returns The entry with resolved locale data, or null if not found
+     *
+     * @example
+     * ```typescript
+     * const post = await cms.contentEntries.getBySlugWithLocale(
+     *   ctx,
+     *   {
+     *     contentTypeName: "blog_post",
+     *     slug: "hello-world",
+     *   },
+     *   {
+     *     locale: "es-ES",
+     *     fields: blogPostType.fields,
+     *   }
+     * );
+     * ```
+     */
+    async getBySlugWithLocale(ctx, args, localeOptions) {
+        const entry = await this.getBySlug(ctx, args);
+        if (!entry)
+            return null;
+        return this.resolveLocale(entry, localeOptions);
+    }
+    // ===========================================================================
+    // Duplicate Entry
+    // ===========================================================================
+    /**
+     * Duplicate a content entry.
+     *
+     * Creates a copy of an existing content entry with a new unique slug.
+     * The duplicate always starts as a draft, regardless of the source entry's status.
+     * Media references are copied by default but can be cleared.
+     *
+     * @param ctx - Convex mutation context
+     * @param args - Duplicate arguments
+     * @returns The duplicated entry
+     *
+     * @example
+     * ```typescript
+     * // Simple duplication with auto-generated slug
+     * const copy = await cms.contentEntries.duplicate(ctx, {
+     *   sourceEntryId: originalPost._id,
+     *   createdBy: currentUserId,
+     * });
+     *
+     * // Duplicate with custom slug
+     * const copy = await cms.contentEntries.duplicate(ctx, {
+     *   sourceEntryId: templateId,
+     *   slug: "new-post-from-template",
+     *   createdBy: currentUserId,
+     * });
+     *
+     * // Duplicate without media references (for a fresh start)
+     * const copy = await cms.contentEntries.duplicate(ctx, {
+     *   sourceEntryId: originalPost._id,
+     *   copyMediaReferences: false,
+     *   createdBy: currentUserId,
+     * });
+     * ```
+     */
+    async duplicate(ctx, args) {
+        // Authorization check - duplicating is similar to create
+        await this.authorize(ctx, "contentEntries.create", args.createdBy);
+        // Rate limit check
+        await this.rateLimit(ctx, "contentEntries.create", args.createdBy);
+        return ctx.runMutation(this.api.contentEntryMutations.duplicateEntry, args);
+    }
+    // ===========================================================================
+    // Bulk Operations
+    // ===========================================================================
+    /**
+     * Publish multiple content entries in a single transaction.
+     *
+     * This is more efficient than publishing entries one by one. Each entry that
+     * is already published will be skipped (idempotent behavior). Deleted or
+     * archived entries will fail with an error message.
+     *
+     * @param ctx - Convex mutation context
+     * @param args - Bulk publish arguments
+     * @returns Bulk operation result with success/failure details for each entry
+     *
+     * @example
+     * ```typescript
+     * const result = await cms.contentEntries.bulkPublish(ctx, {
+     *   ids: [entry1._id, entry2._id, entry3._id],
+     *   changeDescription: "Publishing launch content",
+     *   updatedBy: currentUserId,
+     * });
+     * console.log(`Published ${result.succeeded} of ${result.total} entries`);
+     * if (result.failed > 0) {
+     *   result.results.filter(r => !r.success).forEach(r => {
+     *     console.error(`Failed to publish ${r.id}: ${r.error}`);
+     *   });
+     * }
+     * ```
+     */
+    async bulkPublish(ctx, args) {
+        // Authorization check for each entry (bulk check)
+        await this.authorize(ctx, "contentEntries.publish", args.updatedBy);
+        // Rate limit check
+        await this.rateLimit(ctx, "contentEntries.publish", args.updatedBy);
+        return ctx.runMutation(this.api.bulkOperations.bulkPublish, args);
+    }
+    /**
+     * Unpublish multiple content entries in a single transaction.
+     *
+     * Reverts published entries to draft status. Non-published entries are
+     * skipped (idempotent behavior).
+     *
+     * @param ctx - Convex mutation context
+     * @param args - Bulk unpublish arguments
+     * @returns Bulk operation result with success/failure details for each entry
+     *
+     * @example
+     * ```typescript
+     * const result = await cms.contentEntries.bulkUnpublish(ctx, {
+     *   ids: [entry1._id, entry2._id],
+     *   updatedBy: currentUserId,
+     * });
+     * ```
+     */
+    async bulkUnpublish(ctx, args) {
+        // Authorization check
+        await this.authorize(ctx, "contentEntries.unpublish", args.updatedBy);
+        // Rate limit check
+        await this.rateLimit(ctx, "contentEntries.unpublish", args.updatedBy);
+        return ctx.runMutation(this.api.bulkOperations.bulkUnpublish, args);
+    }
+    /**
+     * Delete multiple content entries in a single transaction.
+     *
+     * By default, performs soft delete (entries can be restored later).
+     * When hardDelete is true, permanently removes entries and all their versions.
+     *
+     * @param ctx - Convex mutation context
+     * @param args - Bulk delete arguments
+     * @returns Bulk operation result with success/failure details for each entry
+     *
+     * @example
+     * ```typescript
+     * // Soft delete (default)
+     * const result = await cms.contentEntries.bulkDelete(ctx, {
+     *   ids: [entry1._id, entry2._id],
+     *   deletedBy: currentUserId,
+     * });
+     *
+     * // Hard delete (permanent)
+     * const result = await cms.contentEntries.bulkDelete(ctx, {
+     *   ids: [entry1._id, entry2._id],
+     *   deletedBy: currentUserId,
+     *   hardDelete: true,
+     * });
+     * ```
+     */
+    async bulkDelete(ctx, args) {
+        // Authorization check
+        await this.authorize(ctx, "contentEntries.delete", args.deletedBy);
+        // Rate limit check
+        await this.rateLimit(ctx, "contentEntries.delete", args.deletedBy);
+        return ctx.runMutation(this.api.bulkOperations.bulkDelete, args);
+    }
+    /**
+     * Update multiple content entries with the same changes in a single transaction.
+     *
+     * Applies the same data updates and/or status change to all specified entries.
+     * Data is merged with existing data for each entry (partial updates).
+     * Each entry is validated against its content type schema.
+     *
+     * @param ctx - Convex mutation context
+     * @param args - Bulk update arguments
+     * @returns Bulk operation result with success/failure details for each entry
+     *
+     * @example
+     * ```typescript
+     * // Update data for multiple entries
+     * const result = await cms.contentEntries.bulkUpdate(ctx, {
+     *   ids: [entry1._id, entry2._id, entry3._id],
+     *   data: { featured: true, category: "news" },
+     *   updatedBy: currentUserId,
+     * });
+     *
+     * // Change status for multiple entries
+     * const result = await cms.contentEntries.bulkUpdate(ctx, {
+     *   ids: [entry1._id, entry2._id],
+     *   status: "archived",
+     *   updatedBy: currentUserId,
+     * });
+     * ```
+     */
+    async bulkUpdate(ctx, args) {
+        // Authorization check
+        await this.authorize(ctx, "contentEntries.update", args.updatedBy);
+        // Rate limit check
+        await this.rateLimit(ctx, "contentEntries.update", args.updatedBy);
+        return ctx.runMutation(this.api.bulkOperations.bulkUpdate, args);
+    }
+    /**
+     * Restore multiple soft-deleted content entries in a single transaction.
+     *
+     * Removes the deletedAt marker from entries, making them active again.
+     * Only works for soft-deleted entries. Non-deleted entries are skipped
+     * (idempotent behavior).
+     *
+     * @param ctx - Convex mutation context
+     * @param args - Bulk restore arguments
+     * @returns Bulk operation result with success/failure details for each entry
+     *
+     * @example
+     * ```typescript
+     * const result = await cms.contentEntries.bulkRestore(ctx, {
+     *   ids: [deletedEntry1._id, deletedEntry2._id],
+     *   restoredBy: currentUserId,
+     * });
+     * ```
+     */
+    async bulkRestore(ctx, args) {
+        if (!this.config.features.softDelete) {
+            throw new Error("Soft delete feature is not enabled");
+        }
+        // Authorization check
+        await this.authorize(ctx, "contentEntries.restore", args.restoredBy);
+        // Rate limit check
+        await this.rateLimit(ctx, "contentEntries.restore", args.restoredBy);
+        return ctx.runMutation(this.api.bulkOperations.bulkRestore, args);
+    }
+}
+// =============================================================================
+// Versions API Wrapper
+// =============================================================================
+/**
+ * Wrapper for content version operations.
+ *
+ * Provides comprehensive version management including:
+ * - Version history retrieval with pagination
+ * - Getting specific versions by ID or number
+ * - Version comparison and diff generation
+ * - Rollback functionality
+ * - Finding latest and published versions
+ *
+ * @example
+ * ```typescript
+ * // Get version history for an entry
+ * const history = await cms.versions.getHistory(ctx, {
+ *   entryId: entry._id,
+ *   paginationOpts: { numItems: 10 },
+ * });
+ *
+ * // Compare two versions
+ * const diff = await cms.versions.compare(ctx, {
+ *   entryId: entry._id,
+ *   fromVersionNumber: 1,
+ *   toVersionNumber: 5,
+ * });
+ *
+ * // Rollback to a previous version
+ * await cms.versions.rollback(ctx, {
+ *   entryId: entry._id,
+ *   versionNumber: 3,
+ * });
+ * ```
+ */
+export class VersionsApi {
+    api;
+    config;
+    authHelper;
+    rateLimitHelper;
+    constructor(api, config, authHelper, rateLimitHelper) {
+        this.api = api;
+        this.config = config;
+        this.authHelper = authHelper;
+        this.rateLimitHelper = rateLimitHelper;
+    }
+    /**
+     * Check if versioning feature is enabled.
+     * @throws Error if versioning is not enabled
+     */
+    ensureVersioningEnabled() {
+        if (!this.config.features.versioning) {
+            throw new Error("Versioning feature is not enabled");
+        }
+    }
+    /**
+     * Perform authorization check for version operations.
+     * @param ctx - The Convex context (passed to authorization hooks for database access)
+     * @param operation - The CMS operation being performed
+     * @param userId - The user performing the operation
+     * @param resourceId - Optional resource ID (entry ID for version operations)
+     * @throws AuthorizationNotConfiguredError if authorization is not configured and permissiveMode is false
+     */
+    async authorize(ctx, operation, userId, resourceId) {
+        if (!this.authHelper) {
+            if (this.config.permissiveMode) {
+                console.warn(`[ConvexCMS] Authorization not configured for "${operation}". ` +
+                    "Operations are allowed in permissiveMode, but this should NOT be used in production.");
+                return;
+            }
+            throw new AuthorizationNotConfiguredError(operation);
+        }
+        if (this.authHelper.skipRbac) {
+            return;
+        }
+        if (!userId) {
+            if (this.config.permissiveMode) {
+                console.warn(`[ConvexCMS] Anonymous operation attempted for "${operation}".`);
+                return;
+            }
+            throw new AuthorizationNotConfiguredError(`${operation} (no userId provided - anonymous operations require permissiveMode)`);
+        }
+        const role = await this.authHelper.getUserRole(ctx, userId);
+        await this.authHelper.requireAuthorization(ctx, {
+            operation,
+            userId,
+            role,
+            resourceId,
+        });
+    }
+    /**
+     * Enforce rate limit for version operations.
+     * @param ctx - The Convex context (for database access)
+     * @param operation - The CMS operation being performed
+     * @param userId - The user performing the operation
+     */
+    async rateLimit(ctx, operation, userId) {
+        // Skip if no rate limit helper configured
+        if (!this.rateLimitHelper) {
+            return;
+        }
+        const role = userId ? await this.rateLimitHelper.getUserRole(ctx, userId) : null;
+        await this.rateLimitHelper.requireRateLimit(operation, {
+            userId,
+            role,
+        });
+    }
+    /**
+     * Get version history with standard Convex pagination.
+     *
+     * Returns versions in reverse chronological order (newest first).
+     * Compatible with `usePaginatedQuery` React hook.
+     *
+     * @param ctx - Convex query context
+     * @param args - History query arguments with pagination
+     * @returns Paginated version history or null if entry not found
+     *
+     * @example
+     * ```typescript
+     * // Get first page of version history
+     * const { page, continueCursor, isDone } = await cms.versions.getHistory(ctx, {
+     *   entryId: entry._id,
+     *   paginationOpts: { numItems: 10 },
+     * });
+     *
+     * // Get next page
+     * if (!isDone && continueCursor) {
+     *   const nextPage = await cms.versions.getHistory(ctx, {
+     *     entryId: entry._id,
+     *     paginationOpts: { numItems: 10, cursor: continueCursor },
+     *   });
+     * }
+     * ```
+     */
+    async getHistory(ctx, args) {
+        this.ensureVersioningEnabled();
+        return ctx.runQuery(this.api.contentEntries.getVersionHistory, args);
+    }
+    /**
+     * Get a specific version by ID or version number.
+     *
+     * @param ctx - Convex query context
+     * @param args - Get arguments (entryId required, plus versionId or versionNumber)
+     * @returns The version or null if not found
+     *
+     * @example
+     * ```typescript
+     * // Get by version number
+     * const version = await cms.versions.get(ctx, {
+     *   entryId: entry._id,
+     *   versionNumber: 3,
+     * });
+     *
+     * // Get by version ID
+     * const version = await cms.versions.get(ctx, {
+     *   entryId: entry._id,
+     *   versionId: "abc123",
+     * });
+     * ```
+     */
+    async get(ctx, args) {
+        this.ensureVersioningEnabled();
+        return ctx.runQuery(this.api.contentEntries.getVersion, args);
+    }
+    /**
+     * Get a version by its version number (convenience method).
+     *
+     * @param ctx - Convex query context
+     * @param entryId - The content entry ID
+     * @param versionNumber - The version number to retrieve
+     * @returns The version or null if not found
+     *
+     * @example
+     * ```typescript
+     * const version3 = await cms.versions.getByNumber(ctx, entry._id, 3);
+     * ```
+     */
+    async getByNumber(ctx, entryId, versionNumber) {
+        return this.get(ctx, { entryId, versionNumber });
+    }
+    /**
+     * Get a version by its document ID (convenience method).
+     *
+     * @param ctx - Convex query context
+     * @param entryId - The content entry ID
+     * @param versionId - The version document ID
+     * @returns The version or null if not found
+     *
+     * @example
+     * ```typescript
+     * const version = await cms.versions.getById(ctx, entry._id, versionDocId);
+     * ```
+     */
+    async getById(ctx, entryId, versionId) {
+        return this.get(ctx, { entryId, versionId });
+    }
+    /**
+     * Get the latest (most recent) version snapshot for an entry.
+     *
+     * @param ctx - Convex query context
+     * @param entryId - The content entry ID
+     * @returns The latest version or null if no versions exist
+     *
+     * @example
+     * ```typescript
+     * const latest = await cms.versions.getLatest(ctx, entry._id);
+     * console.log(`Current version: ${latest?.versionNumber}`);
+     * ```
+     */
+    async getLatest(ctx, entryId) {
+        this.ensureVersioningEnabled();
+        const history = await this.getHistory(ctx, {
+            entryId,
+            paginationOpts: { numItems: 1, cursor: null },
+        });
+        return history?.page[0] ?? null;
+    }
+    /**
+     * Get the latest published version for an entry.
+     *
+     * Searches through version history to find the most recent version
+     * that was published (wasPublished = true).
+     *
+     * @param ctx - Convex query context
+     * @param entryId - The content entry ID
+     * @returns The latest published version or null if none published
+     *
+     * @example
+     * ```typescript
+     * const published = await cms.versions.getLatestPublished(ctx, entry._id);
+     * if (published) {
+     *   console.log(`Published at: ${new Date(published.publishedAt!)}`);
+     * }
+     * ```
+     */
+    async getLatestPublished(ctx, entryId) {
+        this.ensureVersioningEnabled();
+        // Iterate through pages to find the first published version
+        let cursor = null;
+        let isDone = false;
+        while (!isDone) {
+            const history = await this.getHistory(ctx, {
+                entryId,
+                paginationOpts: { numItems: 50, cursor },
+            });
+            if (!history)
+                return null;
+            const publishedVersion = history.page.find((v) => v.wasPublished);
+            if (publishedVersion) {
+                return publishedVersion;
+            }
+            cursor = history.continueCursor;
+            isDone = history.isDone;
+        }
+        return null;
+    }
+    /**
+     * Get all published versions for an entry.
+     *
+     * @param ctx - Convex query context
+     * @param entryId - The content entry ID
+     * @param limit - Maximum number of published versions to return (default: 10)
+     * @returns Array of published versions (newest first)
+     *
+     * @example
+     * ```typescript
+     * const publishedVersions = await cms.versions.getPublishedHistory(ctx, entry._id, 5);
+     * console.log(`Found ${publishedVersions.length} published versions`);
+     * ```
+     */
+    async getPublishedHistory(ctx, entryId, limit = 10) {
+        this.ensureVersioningEnabled();
+        const published = [];
+        let cursor = null;
+        let isDone = false;
+        while (!isDone && published.length < limit) {
+            const history = await this.getHistory(ctx, {
+                entryId,
+                paginationOpts: { numItems: 50, cursor },
+            });
+            if (!history)
+                break;
+            for (const version of history.page) {
+                if (version.wasPublished) {
+                    published.push(version);
+                    if (published.length >= limit)
+                        break;
+                }
+            }
+            cursor = history.continueCursor;
+            isDone = history.isDone;
+        }
+        return published;
+    }
+    /**
+     * Compare two versions and generate a detailed diff.
+     *
+     * Analyzes field-level changes between two versions, identifying:
+     * - Added fields (present in toVersion but not fromVersion)
+     * - Removed fields (present in fromVersion but not toVersion)
+     * - Modified fields (present in both but with different values)
+     *
+     * @param ctx - Convex query context
+     * @param args - Comparison arguments
+     * @returns Detailed version comparison or null if versions not found
+     *
+     * @example
+     * ```typescript
+     * const diff = await cms.versions.compare(ctx, {
+     *   entryId: entry._id,
+     *   fromVersionNumber: 1,
+     *   toVersionNumber: 5,
+     * });
+     *
+     * if (diff) {
+     *   console.log(`${diff.summary.totalChanges} changes detected`);
+     *   for (const change of diff.changes) {
+     *     console.log(`${change.field}: ${change.changeType}`);
+     *   }
+     * }
+     * ```
+     */
+    async compare(ctx, args) {
+        this.ensureVersioningEnabled();
+        // Get the fromVersion
+        const fromVersion = await this.getByNumber(ctx, args.entryId, args.fromVersionNumber);
+        if (!fromVersion)
+            return null;
+        // Get the toVersion
+        const toVersion = await this.getByNumber(ctx, args.entryId, args.toVersionNumber);
+        if (!toVersion)
+            return null;
+        // Generate the comparison
+        return this.generateComparison(fromVersion, toVersion);
+    }
+    /**
+     * Compare the current entry state with a specific version.
+     *
+     * Useful for seeing what has changed since a particular point in time.
+     *
+     * @param ctx - Convex query context
+     * @param entryId - The content entry ID
+     * @param versionNumber - The version number to compare against
+     * @returns Comparison between the version and current state, or null
+     *
+     * @example
+     * ```typescript
+     * // See what changed since version 3
+     * const diff = await cms.versions.compareWithCurrent(ctx, entry._id, 3);
+     * ```
+     */
+    async compareWithCurrent(ctx, entryId, versionNumber) {
+        this.ensureVersioningEnabled();
+        const fromVersion = await this.getByNumber(ctx, entryId, versionNumber);
+        if (!fromVersion)
+            return null;
+        const latest = await this.getLatest(ctx, entryId);
+        if (!latest)
+            return null;
+        return this.generateComparison(fromVersion, latest);
+    }
+    /**
+     * Check if a specific version exists.
+     *
+     * @param ctx - Convex query context
+     * @param entryId - The content entry ID
+     * @param versionNumber - The version number to check
+     * @returns true if the version exists
+     *
+     * @example
+     * ```typescript
+     * if (await cms.versions.exists(ctx, entry._id, 5)) {
+     *   // Version 5 exists
+     * }
+     * ```
+     */
+    async exists(ctx, entryId, versionNumber) {
+        const version = await this.getByNumber(ctx, entryId, versionNumber);
+        return version !== null;
+    }
+    /**
+     * Count total number of versions for an entry.
+     *
+     * @param ctx - Convex query context
+     * @param entryId - The content entry ID
+     * @returns Total number of version snapshots
+     *
+     * @example
+     * ```typescript
+     * const count = await cms.versions.count(ctx, entry._id);
+     * console.log(`Entry has ${count} versions`);
+     * ```
+     */
+    async count(ctx, entryId) {
+        this.ensureVersioningEnabled();
+        let total = 0;
+        let cursor = null;
+        let isDone = false;
+        while (!isDone) {
+            const history = await this.getHistory(ctx, {
+                entryId,
+                paginationOpts: { numItems: 100, cursor },
+            });
+            if (!history)
+                break;
+            total += history.page.length;
+            cursor = history.continueCursor;
+            isDone = history.isDone;
+        }
+        return total;
+    }
+    /**
+     * Rollback a content entry to a previous version.
+     *
+     * This is a non-destructive operation that:
+     * 1. Creates a snapshot of the current state (for undo capability)
+     * 2. Restores data and slug from the target version
+     * 3. Increments the version number
+     * 4. Creates a new snapshot documenting the rollback
+     *
+     * The entry's status, scheduled publish time, and publishing timestamps
+     * are preserved (not restored from the target version).
+     *
+     * @param ctx - Convex mutation context
+     * @param args - Rollback arguments
+     * @returns The updated entry with rolled back content
+     *
+     * @example
+     * ```typescript
+     * // Rollback to version 3
+     * const entry = await cms.versions.rollback(ctx, {
+     *   entryId: entry._id,
+     *   versionNumber: 3,
+     *   updatedBy: currentUserId,
+     * });
+     *
+     * // The entry is now at a new version number (e.g., 7)
+     * // but with content from version 3
+     * console.log(`Rolled back, now at version ${entry.version}`);
+     * ```
+     */
+    async rollback(ctx, args) {
+        this.ensureVersioningEnabled();
+        // Authorization check - versions.rollback
+        await this.authorize(ctx, "versions.rollback", args.updatedBy, args.entryId);
+        // Rate limit check - versions.rollback
+        await this.rateLimit(ctx, "versions.rollback", args.updatedBy);
+        return ctx.runMutation(this.api.versionMutations.rollbackVersion, args);
+    }
+    // =========================================================================
+    // Private Helper Methods
+    // =========================================================================
+    /**
+     * Generate a detailed comparison between two versions.
+     */
+    generateComparison(fromVersion, toVersion) {
+        const changes = [];
+        const fromData = fromVersion.data;
+        const toData = toVersion.data;
+        // Get all unique field names from both versions
+        const allFields = new Set([
+            ...Object.keys(fromData),
+            ...Object.keys(toData),
+        ]);
+        let fieldsAdded = 0;
+        let fieldsRemoved = 0;
+        let fieldsModified = 0;
+        for (const field of allFields) {
+            const oldValue = fromData[field];
+            const newValue = toData[field];
+            const inOld = field in fromData;
+            const inNew = field in toData;
+            let changeType;
+            if (!inOld && inNew) {
+                changeType = "added";
+                fieldsAdded++;
+            }
+            else if (inOld && !inNew) {
+                changeType = "removed";
+                fieldsRemoved++;
+            }
+            else if (!this.deepEqual(oldValue, newValue)) {
+                changeType = "modified";
+                fieldsModified++;
+            }
+            else {
+                changeType = "unchanged";
+            }
+            // Only include changes (skip unchanged fields)
+            if (changeType !== "unchanged") {
+                changes.push({
+                    field,
+                    changeType,
+                    oldValue: inOld ? oldValue : undefined,
+                    newValue: inNew ? newValue : undefined,
+                });
+            }
+        }
+        return {
+            fromVersion,
+            toVersion,
+            changes,
+            slugChanged: fromVersion.slug !== toVersion.slug,
+            statusChanged: fromVersion.status !== toVersion.status,
+            summary: {
+                fieldsAdded,
+                fieldsRemoved,
+                fieldsModified,
+                totalChanges: fieldsAdded + fieldsRemoved + fieldsModified,
+            },
+        };
+    }
+    /**
+     * Deep equality check for comparing field values.
+     */
+    deepEqual(a, b) {
+        if (a === b)
+            return true;
+        if (a === null || b === null)
+            return false;
+        if (typeof a !== typeof b)
+            return false;
+        if (typeof a === "object") {
+            if (Array.isArray(a) && Array.isArray(b)) {
+                if (a.length !== b.length)
+                    return false;
+                return a.every((item, index) => this.deepEqual(item, b[index]));
+            }
+            if (!Array.isArray(a) && !Array.isArray(b)) {
+                const aObj = a;
+                const bObj = b;
+                const aKeys = Object.keys(aObj);
+                const bKeys = Object.keys(bObj);
+                if (aKeys.length !== bKeys.length)
+                    return false;
+                return aKeys.every((key) => this.deepEqual(aObj[key], bObj[key]));
+            }
+        }
+        return false;
+    }
+}
+// =============================================================================
+// Media Assets API Wrapper
+// =============================================================================
+/**
+ * Wrapper for media asset operations.
+ */
+export class MediaAssetsApi {
+    api;
+    config;
+    authHelper;
+    rateLimitHelper;
+    constructor(api, config, authHelper, rateLimitHelper) {
+        this.api = api;
+        this.config = config;
+        this.authHelper = authHelper;
+        this.rateLimitHelper = rateLimitHelper;
+    }
+    /**
+     * Perform authorization check for media asset operations.
+     * @param ctx - The Convex context (passed to authorization hooks for database access)
+     * @param operation - The CMS operation being performed
+     * @param userId - The user performing the operation
+     * @param resourceId - Optional resource ID (for update/delete operations)
+     * @param resourceOwnerId - Optional owner ID for ownership-based permissions
+     * @throws AuthorizationNotConfiguredError if authorization is not configured and permissiveMode is false
+     */
+    async authorize(ctx, operation, userId, resourceId, resourceOwnerId) {
+        if (!this.authHelper) {
+            if (this.config.permissiveMode) {
+                console.warn(`[ConvexCMS] Authorization not configured for "${operation}". ` +
+                    "Operations are allowed in permissiveMode, but this should NOT be used in production.");
+                return;
+            }
+            throw new AuthorizationNotConfiguredError(operation);
+        }
+        if (this.authHelper.skipRbac) {
+            return;
+        }
+        if (!userId) {
+            if (this.config.permissiveMode) {
+                console.warn(`[ConvexCMS] Anonymous operation attempted for "${operation}".`);
+                return;
+            }
+            throw new AuthorizationNotConfiguredError(`${operation} (no userId provided - anonymous operations require permissiveMode)`);
+        }
+        const role = await this.authHelper.getUserRole(ctx, userId);
+        await this.authHelper.requireAuthorization(ctx, {
+            operation,
+            userId,
+            role,
+            resourceId,
+            resourceOwnerId,
+        });
+    }
+    /**
+     * Enforce rate limit for media asset operations.
+     * @param ctx - The Convex context (for database access)
+     * @param operation - The CMS operation being performed
+     * @param userId - The user performing the operation
+     */
+    async rateLimit(ctx, operation, userId) {
+        // Skip if no rate limit helper configured
+        if (!this.rateLimitHelper) {
+            return;
+        }
+        const role = userId ? await this.rateLimitHelper.getUserRole(ctx, userId) : null;
+        await this.rateLimitHelper.requireRateLimit(operation, {
+            userId,
+            role,
+        });
+    }
+    /**
+     * Create a new media asset record.
+     *
+     * @param ctx - Convex mutation context
+     * @param args - Asset creation arguments
+     * @returns The created asset
+     *
+     * @example
+     * ```typescript
+     * // After uploading to Convex storage
+     * const asset = await cms.mediaAssets.create(ctx, {
+     *   storageId: storageId,
+     *   filename: "photo.jpg",
+     *   mimeType: "image/jpeg",
+     *   size: 102400,
+     *   type: "image",
+     *   width: 1920,
+     *   height: 1080,
+     * });
+     * ```
+     */
+    async create(ctx, args) {
+        if (!this.config.features.mediaManagement) {
+            throw new Error("Media management feature is not enabled");
+        }
+        // Authorization check - mediaAssets.create
+        await this.authorize(ctx, "mediaItems.create", args.createdBy);
+        // Rate limit check - mediaAssets.create (media uploads are high-frequency operations)
+        await this.rateLimit(ctx, "mediaItems.create", args.createdBy);
+        // Validate file size
+        if (args.size && args.size > this.config.maxMediaFileSize) {
+            throw new Error(`File size ${args.size} exceeds maximum allowed size of ${this.config.maxMediaFileSize} bytes`);
+        }
+        // Cast safe: createMediaAsset always returns kind="asset"
+        return ctx.runMutation(this.api.mediaAssetMutations.createMediaAsset, args);
+    }
+    /**
+     * Update media asset metadata.
+     *
+     * @param ctx - Convex mutation context
+     * @param args - Asset update arguments
+     * @returns The updated asset
+     */
+    async update(ctx, args) {
+        if (!this.config.features.mediaManagement) {
+            throw new Error("Media management feature is not enabled");
+        }
+        // Fetch asset for ownership-based authorization
+        const asset = await ctx.runQuery(this.api.mediaAssets.get, { id: args.id });
+        if (!asset) {
+            throw new Error(`Media asset not found: ${args.id}`);
+        }
+        // Authorization check - mediaAssets.update (with ownership info)
+        await this.authorize(ctx, "mediaItems.update", args.updatedBy, args.id, asset.createdBy);
+        // Rate limit check - mediaAssets.update
+        await this.rateLimit(ctx, "mediaItems.update", args.updatedBy);
+        // Cast safe: updateMediaAsset always returns kind="asset"
+        return ctx.runMutation(this.api.mediaAssetMutations.updateMediaAsset, args);
+    }
+    /**
+     * Soft delete a media asset.
+     *
+     * @param ctx - Convex mutation context
+     * @param args - Delete arguments
+     * @returns The deleted asset
+     */
+    async delete(ctx, args) {
+        if (!this.config.features.mediaManagement) {
+            throw new Error("Media management feature is not enabled");
+        }
+        // Fetch asset for ownership-based authorization
+        const asset = await ctx.runQuery(this.api.mediaAssets.get, { id: args.id });
+        if (!asset) {
+            throw new Error(`Media asset not found: ${args.id}`);
+        }
+        // Authorization check - mediaAssets.delete (with ownership info)
+        await this.authorize(ctx, "mediaItems.delete", args.deletedBy, args.id, asset.createdBy);
+        // Rate limit check - mediaAssets.delete
+        await this.rateLimit(ctx, "mediaItems.delete", args.deletedBy);
+        // Cast safe: deleteMediaAsset always returns kind="asset"
+        return ctx.runMutation(this.api.mediaAssetMutations.deleteMediaAsset, args);
+    }
+    /**
+     * Get a media asset by ID.
+     *
+     * @param ctx - Convex query context
+     * @param args - Get arguments
+     * @returns The asset or null if not found
+     */
+    async get(ctx, args) {
+        if (!this.config.features.mediaManagement) {
+            throw new Error("Media management feature is not enabled");
+        }
+        // Cast safe: mediaAssets.get filters for kind="asset"
+        return ctx.runQuery(this.api.mediaAssets.get, args);
+    }
+    /**
+     * List media assets with optional filters.
+     *
+     * @param ctx - Convex query context
+     * @param args - Query options
+     * @returns Paginated list of assets
+     */
+    async list(ctx, args = {}) {
+        if (!this.config.features.mediaManagement) {
+            throw new Error("Media management feature is not enabled");
+        }
+        return await callQuery(ctx, this.api.mediaAssets.list, args);
+    }
+    /**
+     * Generate a temporary upload URL for client-side file uploads.
+     *
+     * The upload flow works as follows:
+     * 1. Call this method to get a temporary upload URL
+     * 2. POST the file to the URL with Content-Type header set to the file's MIME type
+     * 3. The response contains a `storageId` that references the uploaded file
+     * 4. Call create() to save metadata and link the storageId
+     *
+     * @param ctx - Convex mutation context
+     * @param args - Upload configuration options
+     * @returns Upload URL and constraints
+     *
+     * @example
+     * ```typescript
+     * // Generate URL for image uploads
+     * const { uploadUrl, expiresAt, maxFileSize } = await cms.mediaAssets.generateUploadUrl(ctx, {
+     *   maxFileSize: 10 * 1024 * 1024, // 10 MB
+     *   allowedMimeTypes: ["image/jpeg", "image/png", "image/webp"],
+     * });
+     *
+     * // Client-side upload:
+     * const response = await fetch(uploadUrl, {
+     *   method: "POST",
+     *   headers: { "Content-Type": file.type },
+     *   body: file,
+     * });
+     * const { storageId } = await response.json();
+     *
+     * // Then save metadata
+     * const asset = await cms.mediaAssets.create(ctx, {
+     *   storageId,
+     *   filename: file.name,
+     *   mimeType: file.type,
+     *   size: file.size,
+     *   type: "image",
+     * });
+     * ```
+     */
+    async generateUploadUrl(ctx, args = {}) {
+        if (!this.config.features.mediaManagement) {
+            throw new Error("Media management feature is not enabled");
+        }
+        // Rate limit check - mediaAssets.create (upload URL generation precedes asset creation)
+        await this.rateLimit(ctx, "mediaItems.create", args.requestedBy);
+        return ctx.runMutation(this.api.mediaUploadMutations.generateUploadUrl, args);
+    }
+    /**
+     * Restore a soft-deleted media asset.
+     *
+     * @param ctx - Convex mutation context
+     * @param args - Restore arguments
+     * @returns The restored asset
+     *
+     * @example
+     * ```typescript
+     * // Restore a previously deleted asset
+     * const restoredAsset = await cms.mediaAssets.restore(ctx, {
+     *   id: assetId,
+     * });
+     * ```
+     */
+    async restore(ctx, args) {
+        if (!this.config.features.mediaManagement) {
+            throw new Error("Media management feature is not enabled");
+        }
+        // Cast safe: restoreMediaAsset always returns kind="asset"
+        return ctx.runMutation(this.api.mediaAssetMutations.restoreMediaAsset, args);
+    }
+    /**
+     * Find content entries that reference a media asset.
+     *
+     * Useful for checking references before deletion or for understanding asset usage.
+     *
+     * @param ctx - Convex query context
+     * @param args - Query arguments
+     * @returns Array of references with entry and field information
+     *
+     * @example
+     * ```typescript
+     * // Check if asset is used before deleting
+     * const references = await cms.mediaAssets.findReferences(ctx, {
+     *   id: assetId,
+     * });
+     *
+     * if (references.length > 0) {
+     *   console.log(`Asset is used in ${references.length} entries`);
+     *   // Maybe show a warning to the user
+     * }
+     * ```
+     */
+    async findReferences(ctx, args) {
+        if (!this.config.features.mediaManagement) {
+            throw new Error("Media management feature is not enabled");
+        }
+        // Map the wrapper's args structure to the generated API's expected structure
+        return callQuery(ctx, this.api.mediaAssetMutations.findMediaAssetReferences, { mediaAssetId: args.id, limit: args.limit });
+    }
+    // ===========================================================================
+    // Taxonomy Methods
+    // ===========================================================================
+    /**
+     * Get taxonomy terms associated with a media asset.
+     *
+     * @param ctx - Convex query context
+     * @param args - Query arguments
+     * @returns Array of terms associated with the media asset
+     *
+     * @example
+     * ```typescript
+     * const tags = await cms.mediaAssets.getTerms(ctx, {
+     *   mediaId: imageId,
+     * });
+     * ```
+     */
+    async getTerms(ctx, args) {
+        if (!this.config.features.mediaManagement) {
+            throw new Error("Media management feature is not enabled");
+        }
+        return callQuery(ctx, this.api.taxonomies.getTermsByMedia, args);
+    }
+    /**
+     * Set terms for a media asset in a taxonomy (replaces existing terms).
+     *
+     * @param ctx - Convex mutation context
+     * @param args - Mutation arguments
+     *
+     * @example
+     * ```typescript
+     * await cms.mediaAssets.setTerms(ctx, {
+     *   mediaId: imageId,
+     *   taxonomyId: categoriesTaxonomyId,
+     *   termIds: [landscapeId, natureId],
+     *   userId: currentUserId,
+     * });
+     * ```
+     */
+    async setTerms(ctx, args) {
+        if (!this.config.features.mediaManagement) {
+            throw new Error("Media management feature is not enabled");
+        }
+        await this.authorize(ctx, "mediaItems.update", args.userId, args.mediaId);
+        await ctx.runMutation(this.api.taxonomyMutations.setMediaTerms, {
+            mediaId: args.mediaId,
+            taxonomyId: args.taxonomyId,
+            termIds: args.termIds,
+        });
+    }
+    /**
+     * Add a single term to a media asset.
+     *
+     * @param ctx - Convex mutation context
+     * @param args - Mutation arguments
+     *
+     * @example
+     * ```typescript
+     * await cms.mediaAssets.addTerm(ctx, {
+     *   mediaId: imageId,
+     *   termId: landscapeId,
+     *   userId: currentUserId,
+     * });
+     * ```
+     */
+    async addTerm(ctx, args) {
+        if (!this.config.features.mediaManagement) {
+            throw new Error("Media management feature is not enabled");
+        }
+        await this.authorize(ctx, "mediaItems.update", args.userId, args.mediaId);
+        await ctx.runMutation(this.api.taxonomyMutations.addTermToMedia, {
+            mediaId: args.mediaId,
+            termId: args.termId,
+        });
+    }
+    /**
+     * Remove a term from a media asset.
+     *
+     * @param ctx - Convex mutation context
+     * @param args - Mutation arguments
+     *
+     * @example
+     * ```typescript
+     * await cms.mediaAssets.removeTerm(ctx, {
+     *   mediaId: imageId,
+     *   termId: landscapeId,
+     *   userId: currentUserId,
+     * });
+     * ```
+     */
+    async removeTerm(ctx, args) {
+        if (!this.config.features.mediaManagement) {
+            throw new Error("Media management feature is not enabled");
+        }
+        await this.authorize(ctx, "mediaItems.update", args.userId, args.mediaId);
+        await ctx.runMutation(this.api.taxonomyMutations.removeTermFromMedia, {
+            mediaId: args.mediaId,
+            termId: args.termId,
+        });
+    }
+    /**
+     * Create a term inline and add it to a media asset.
+     *
+     * @param ctx - Convex mutation context
+     * @param args - Mutation arguments
+     * @returns The created or existing term ID
+     *
+     * @example
+     * ```typescript
+     * const termId = await cms.mediaAssets.createAndAddTerm(ctx, {
+     *   taxonomyId: tagsTaxonomyId,
+     *   name: "Nature",
+     *   mediaId: imageId,
+     *   userId: currentUserId,
+     * });
+     * ```
+     */
+    async createAndAddTerm(ctx, args) {
+        if (!this.config.features.mediaManagement) {
+            throw new Error("Media management feature is not enabled");
+        }
+        await this.authorize(ctx, "mediaItems.update", args.userId, args.mediaId);
+        return ctx.runMutation(this.api.taxonomyMutations.createTermAndAddToMedia, args);
+    }
+}
+// =============================================================================
+// Media Folders API Wrapper
+// =============================================================================
+/**
+ * Wrapper for media folder operations.
+ */
+export class MediaFoldersApi {
+    api;
+    config;
+    authHelper;
+    rateLimitHelper;
+    constructor(api, config, authHelper, rateLimitHelper) {
+        this.api = api;
+        this.config = config;
+        this.authHelper = authHelper;
+        this.rateLimitHelper = rateLimitHelper;
+    }
+    /**
+     * Perform authorization check for media folder operations.
+     * @param ctx - The Convex context (passed to authorization hooks for database access)
+     * @param operation - The CMS operation being performed
+     * @param userId - The user performing the operation
+     * @param resourceId - Optional resource ID (for update/delete operations)
+     * @param resourceOwnerId - Optional owner ID for ownership-based permissions
+     */
+    async authorize(ctx, operation, userId, resourceId, resourceOwnerId) {
+        if (!this.authHelper) {
+            if (this.config.permissiveMode) {
+                console.warn(`[ConvexCMS] Authorization not configured for "${operation}". ` +
+                    "Operations are allowed in permissiveMode, but this should NOT be used in production.");
+                return;
+            }
+            throw new AuthorizationNotConfiguredError(operation);
+        }
+        if (this.authHelper.skipRbac) {
+            return;
+        }
+        if (!userId) {
+            if (this.config.permissiveMode) {
+                console.warn(`[ConvexCMS] Anonymous operation attempted for "${operation}".`);
+                return;
+            }
+            throw new AuthorizationNotConfiguredError(`${operation} (no userId provided - anonymous operations require permissiveMode)`);
+        }
+        const role = await this.authHelper.getUserRole(ctx, userId);
+        await this.authHelper.requireAuthorization(ctx, {
+            operation,
+            userId,
+            role,
+            resourceId,
+            resourceOwnerId,
+        });
+    }
+    /**
+     * Enforce rate limit for media folder operations.
+     * @param ctx - The Convex context (for database access)
+     * @param operation - The CMS operation being performed
+     * @param userId - The user performing the operation
+     */
+    async rateLimit(ctx, operation, userId) {
+        // Skip if no rate limit helper configured
+        if (!this.rateLimitHelper) {
+            return;
+        }
+        const role = userId ? await this.rateLimitHelper.getUserRole(ctx, userId) : null;
+        await this.rateLimitHelper.requireRateLimit(operation, {
+            userId,
+            role,
+        });
+    }
+    /**
+     * Create a new media folder.
+     *
+     * @param ctx - Convex mutation context
+     * @param args - Folder creation arguments
+     * @returns The created folder
+     */
+    async create(ctx, args) {
+        if (!this.config.features.mediaManagement) {
+            throw new Error("Media management feature is not enabled");
+        }
+        // Authorization check - mediaFolders.create
+        await this.authorize(ctx, "mediaItems.create", args.createdBy);
+        // Rate limit check - mediaFolders.create
+        await this.rateLimit(ctx, "mediaItems.create", args.createdBy);
+        // Cast safe: createMediaFolder always returns kind="folder"
+        return ctx.runMutation(this.api.mediaFolderMutations.createMediaFolder, args);
+    }
+    /**
+     * Update a media folder.
+     *
+     * @param ctx - Convex mutation context
+     * @param args - Folder update arguments
+     * @returns The updated folder
+     */
+    async update(ctx, args) {
+        if (!this.config.features.mediaManagement) {
+            throw new Error("Media management feature is not enabled");
+        }
+        // Fetch folder for ownership-based authorization
+        const folder = await ctx.runQuery(this.api.mediaFolderMutations.getMediaFolder, { id: args.id });
+        if (!folder) {
+            throw new Error(`Media folder not found: ${args.id}`);
+        }
+        // Authorization check - mediaFolders.update (with ownership info)
+        await this.authorize(ctx, "mediaItems.update", args.updatedBy, args.id, folder.createdBy);
+        // Rate limit check - mediaFolders.update
+        await this.rateLimit(ctx, "mediaItems.update", args.updatedBy);
+        // Cast safe: updateMediaFolder always returns kind="folder"
+        return ctx.runMutation(this.api.mediaFolderMutations.updateMediaFolder, args);
+    }
+    /**
+     * Soft delete a media folder.
+     *
+     * @param ctx - Convex mutation context
+     * @param args - Delete arguments
+     * @returns The deleted folder
+     */
+    async delete(ctx, args) {
+        if (!this.config.features.mediaManagement) {
+            throw new Error("Media management feature is not enabled");
+        }
+        // Fetch folder for ownership-based authorization
+        const folder = await ctx.runQuery(this.api.mediaFolderMutations.getMediaFolder, { id: args.id });
+        if (!folder) {
+            throw new Error(`Media folder not found: ${args.id}`);
+        }
+        // Authorization check - mediaFolders.delete (with ownership info)
+        await this.authorize(ctx, "mediaItems.delete", args.deletedBy, args.id, folder.createdBy);
+        // Rate limit check - mediaFolders.delete
+        await this.rateLimit(ctx, "mediaItems.delete", args.deletedBy);
+        // Cast safe: deleteMediaFolder always returns kind="folder"
+        return ctx.runMutation(this.api.mediaFolderMutations.deleteMediaFolder, args);
+    }
+    /**
+     * Get a media folder by ID.
+     *
+     * @param ctx - Convex query context
+     * @param args - Get arguments
+     * @returns The folder or null if not found
+     */
+    async get(ctx, args) {
+        if (!this.config.features.mediaManagement) {
+            throw new Error("Media management feature is not enabled");
+        }
+        // Cast safe: getMediaFolder filters for kind="folder"
+        return ctx.runQuery(this.api.mediaFolderMutations.getMediaFolder, args);
+    }
+    /**
+     * List media folders.
+     *
+     * @param ctx - Convex query context
+     * @param args - Optional filter arguments
+     * @returns Array of folders
+     */
+    async list(ctx, args = {}) {
+        if (!this.config.features.mediaManagement) {
+            throw new Error("Media management feature is not enabled");
+        }
+        // Cast safe: listMediaFolders filters for kind="folder"
+        return ctx.runQuery(this.api.mediaFolderMutations.listMediaFolders, args);
+    }
+    /**
+     * Move a folder to a new parent.
+     *
+     * @param ctx - Convex mutation context
+     * @param args - Move arguments
+     * @returns The moved folder with updated path
+     */
+    async move(ctx, args) {
+        if (!this.config.features.mediaManagement) {
+            throw new Error("Media management feature is not enabled");
+        }
+        // Fetch folder for ownership-based authorization
+        const folder = await ctx.runQuery(this.api.mediaFolderMutations.getMediaFolder, { id: args.id });
+        if (!folder) {
+            throw new Error(`Media folder not found: ${args.id}`);
+        }
+        // Authorization check - mediaFolders.move (with ownership info)
+        await this.authorize(ctx, "mediaItems.move", args.updatedBy, args.id, folder.createdBy);
+        // Rate limit check - mediaFolders.move
+        await this.rateLimit(ctx, "mediaItems.move", args.updatedBy);
+        // Cast safe: moveMediaFolder always returns kind="folder"
+        return ctx.runMutation(this.api.mediaFolderMutations.moveMediaFolder, args);
+    }
+    /**
+     * Restore a soft-deleted media folder.
+     *
+     * @param ctx - Convex mutation context
+     * @param args - Restore arguments
+     * @returns The restored folder
+     *
+     * @example
+     * ```typescript
+     * // Restore a folder and all its contents
+     * const restoredFolder = await cms.mediaFolders.restore(ctx, {
+     *   id: folderId,
+     *   recursive: true,
+     * });
+     * ```
+     */
+    async restore(ctx, args) {
+        if (!this.config.features.mediaManagement) {
+            throw new Error("Media management feature is not enabled");
+        }
+        // Cast safe: restoreMediaFolder always returns kind="folder"
+        return ctx.runMutation(this.api.mediaFolderMutations.restoreMediaFolder, args);
+    }
+    /**
+     * Get a folder by its path.
+     *
+     * @param ctx - Convex query context
+     * @param args - Query arguments with path
+     * @returns The folder or null if not found
+     *
+     * @example
+     * ```typescript
+     * // Find folder by path
+     * const folder = await cms.mediaFolders.getByPath(ctx, {
+     *   path: "/Images/Blog/2026",
+     * });
+     * ```
+     */
+    async getByPath(ctx, args) {
+        if (!this.config.features.mediaManagement) {
+            throw new Error("Media management feature is not enabled");
+        }
+        // Cast safe: getMediaFolderByPath filters for kind="folder"
+        return ctx.runQuery(this.api.mediaFolderMutations.getMediaFolderByPath, args);
+    }
+    /**
+     * Get the entire folder tree as a flat list sorted by path.
+     *
+     * Useful for building folder navigation or selectors.
+     *
+     * @param ctx - Convex query context
+     * @param args - Optional filter arguments
+     * @returns Array of all folders sorted hierarchically by path
+     *
+     * @example
+     * ```typescript
+     * // Get all folders for a tree view
+     * const folders = await cms.mediaFolders.getTree(ctx, {});
+     *
+     * // Build a nested structure
+     * const rootFolders = folders.filter(f => !f.parentId);
+     * ```
+     */
+    async getTree(ctx, args = {}) {
+        if (!this.config.features.mediaManagement) {
+            throw new Error("Media management feature is not enabled");
+        }
+        // Cast safe: getFolderTree filters for kind="folder"
+        return ctx.runQuery(this.api.mediaFolderMutations.getFolderTree, args);
+    }
+}
+// =============================================================================
+// Media Variants API Wrapper
+// =============================================================================
+/**
+ * Wrapper for media variant operations.
+ *
+ * Media variants are optimized versions of media assets (thumbnails, responsive
+ * sizes, format conversions). This API provides methods for creating, listing,
+ * and managing variants.
+ *
+ * @example
+ * ```typescript
+ * // Get all variants for an asset
+ * const variants = await cms.mediaVariants.list(ctx, {
+ *   assetId: assetId,
+ *   status: "completed",
+ * });
+ *
+ * // Get responsive srcset for an image
+ * const srcset = await cms.mediaVariants.getResponsiveSrcset(ctx, {
+ *   assetId: assetId,
+ *   format: "webp",
+ * });
+ * // Use: <img src={srcset.src} srcset={srcset.srcset} sizes="100vw" />
+ * ```
+ */
+export class MediaVariantsApi {
+    api;
+    config;
+    constructor(api, config) {
+        this.api = api;
+        this.config = config;
+    }
+    /**
+     * Create a media variant after external processing.
+     *
+     * Use this when variant processing happens externally (e.g., in a serverless
+     * function or image processing service) and you need to register the
+     * completed variant.
+     *
+     * @param ctx - Convex mutation context
+     * @param args - Variant creation arguments
+     * @returns The created variant with URL
+     *
+     * @example
+     * ```typescript
+     * // After processing image externally and uploading result
+     * const variant = await cms.mediaVariants.create(ctx, {
+     *   assetId: assetId,
+     *   storageId: processedStorageId,
+     *   variantType: "responsive",
+     *   width: 480,
+     *   height: 320,
+     *   format: "webp",
+     *   mimeType: "image/webp",
+     *   size: 25600,
+     *   quality: 80,
+     *   preset: "small",
+     * });
+     * ```
+     */
+    async create(ctx, args) {
+        if (!this.config.features.mediaManagement) {
+            throw new Error("Media management feature is not enabled");
+        }
+        return ctx.runMutation(this.api.mediaVariantMutations.createMediaVariant, args);
+    }
+    /**
+     * Request async generation of a variant.
+     *
+     * Creates a variant record with "pending" status. An external processing
+     * system should pick up pending variants, process them, and update the status.
+     *
+     * @param ctx - Convex mutation context
+     * @param args - Generation request arguments
+     * @returns The pending variant
+     */
+    async requestGeneration(ctx, args) {
+        if (!this.config.features.mediaManagement) {
+            throw new Error("Media management feature is not enabled");
+        }
+        return ctx.runMutation(this.api.mediaVariantMutations.requestVariantGeneration, args);
+    }
+    /**
+     * Get a variant by ID.
+     *
+     * @param ctx - Convex query context
+     * @param args - Query arguments
+     * @returns The variant with URL or null
+     */
+    async get(ctx, args) {
+        if (!this.config.features.mediaManagement) {
+            throw new Error("Media management feature is not enabled");
+        }
+        return ctx.runQuery(this.api.mediaVariants.get, args);
+    }
+    /**
+     * List variants for an asset.
+     *
+     * @param ctx - Convex query context
+     * @param args - Query arguments with filters
+     * @returns Array of variants with URLs
+     *
+     * @example
+     * ```typescript
+     * // Get all completed responsive variants
+     * const variants = await cms.mediaVariants.list(ctx, {
+     *   assetId: assetId,
+     *   variantType: "responsive",
+     *   status: "completed",
+     * });
+     * ```
+     */
+    async list(ctx, args) {
+        if (!this.config.features.mediaManagement) {
+            throw new Error("Media management feature is not enabled");
+        }
+        return ctx.runQuery(this.api.mediaVariants.list, args);
+    }
+    /**
+     * Find the best matching variant for target dimensions.
+     *
+     * @param ctx - Convex query context
+     * @param args - Target size and preferences
+     * @returns Best matching variant or null
+     *
+     * @example
+     * ```typescript
+     * // Get best variant for 400px wide container
+     * const variant = await cms.mediaVariants.getBestVariant(ctx, {
+     *   assetId: assetId,
+     *   targetWidth: 400,
+     *   preferredFormat: "webp",
+     * });
+     * ```
+     */
+    async getBestVariant(ctx, args) {
+        if (!this.config.features.mediaManagement) {
+            throw new Error("Media management feature is not enabled");
+        }
+        return ctx.runQuery(this.api.mediaVariants.getBestVariant, args);
+    }
+    /**
+     * Get responsive srcset data for HTML img/picture tags.
+     *
+     * @param ctx - Convex query context
+     * @param args - Asset ID and optional format filter
+     * @returns Srcset data for responsive images
+     *
+     * @example
+     * ```typescript
+     * const srcset = await cms.mediaVariants.getResponsiveSrcset(ctx, {
+     *   assetId: assetId,
+     *   format: "webp",
+     * });
+     *
+     * // In React:
+     * <img src={srcset.src} srcset={srcset.srcset} sizes="100vw" />
+     * ```
+     */
+    async getResponsiveSrcset(ctx, args) {
+        if (!this.config.features.mediaManagement) {
+            throw new Error("Media management feature is not enabled");
+        }
+        return ctx.runQuery(this.api.mediaVariants.getResponsiveSrcset, args);
+    }
+    /**
+     * Get an asset with all its variants organized by type.
+     *
+     * @param ctx - Convex query context
+     * @param args - Asset ID
+     * @returns Asset with variants or null
+     */
+    async getAssetWithVariants(ctx, args) {
+        if (!this.config.features.mediaManagement) {
+            throw new Error("Media management feature is not enabled");
+        }
+        return ctx.runQuery(this.api.mediaVariants.getAssetWithVariants, args);
+    }
+    /**
+     * Get available variant presets.
+     *
+     * @param ctx - Convex query context
+     * @returns Array of preset configurations
+     */
+    async getPresets(ctx) {
+        if (!this.config.features.mediaManagement) {
+            throw new Error("Media management feature is not enabled");
+        }
+        return ctx.runQuery(this.api.mediaVariants.getPresets, {});
+    }
+    /**
+     * Generate variants from preset configurations.
+     *
+     * Queues multiple variants for async processing.
+     *
+     * @param ctx - Convex mutation context
+     * @param args - Asset ID and preset names
+     * @returns Summary of created variant requests
+     *
+     * @example
+     * ```typescript
+     * // Generate standard responsive set
+     * const result = await cms.mediaVariants.generateFromPresets(ctx, {
+     *   assetId: assetId,
+     *   presets: ["thumbnail", "small", "medium", "large"],
+     * });
+     * console.log(`Queued ${result.succeeded} variants`);
+     * ```
+     */
+    async generateFromPresets(ctx, args) {
+        if (!this.config.features.mediaManagement) {
+            throw new Error("Media management feature is not enabled");
+        }
+        return ctx.runMutation(this.api.mediaVariantMutations.generateFromPresets, args);
+    }
+    /**
+     * Delete a variant.
+     *
+     * @param ctx - Convex mutation context
+     * @param args - Delete arguments
+     * @returns The deleted variant
+     */
+    async delete(ctx, args) {
+        if (!this.config.features.mediaManagement) {
+            throw new Error("Media management feature is not enabled");
+        }
+        return ctx.runMutation(this.api.mediaVariantMutations.deleteMediaVariant, args);
+    }
+    /**
+     * Delete all variants for an asset.
+     *
+     * @param ctx - Convex mutation context
+     * @param args - Asset ID and delete options
+     * @returns Summary of deleted variants
+     */
+    async deleteAllForAsset(ctx, args) {
+        if (!this.config.features.mediaManagement) {
+            throw new Error("Media management feature is not enabled");
+        }
+        return ctx.runMutation(this.api.mediaVariantMutations.deleteAssetVariants, args);
+    }
+    /**
+     * Restore a soft-deleted variant.
+     *
+     * @param ctx - Convex mutation context
+     * @param args - Variant ID to restore
+     * @returns The restored variant
+     */
+    async restore(ctx, args) {
+        if (!this.config.features.mediaManagement) {
+            throw new Error("Media management feature is not enabled");
+        }
+        return ctx.runMutation(this.api.mediaVariantMutations.restoreMediaVariant, args);
+    }
+}
+/**
+ * Creates an enhanced CMS client with typed method wrappers.
+ *
+ * This is the main entry point for using the Convex CMS component.
+ * The returned client provides typed methods for all CMS operations.
+ *
+ * @param componentApi - The component API from `components.convexCms`
+ * @param config - Optional configuration options
+ * @returns An enhanced CMS client instance
+ *
+ * @example
+ * ```typescript
+ * import { createCmsClient } from "@convex-cms/core";
+ * import { components } from "./_generated/api";
+ *
+ * // Create with default configuration
+ * export const cms = createCmsClient(components.convexCms);
+ *
+ * // Create with custom configuration
+ * export const cms = createCmsClient(components.convexCms, {
+ *   defaultLocale: "en-US",
+ *   supportedLocales: ["en-US", "es-ES", "fr-FR"],
+ *   features: {
+ *     versioning: true,
+ *     localization: true,
+ *     scheduling: true,
+ *   },
+ *   maxVersionsPerEntry: 100,
+ * });
+ * ```
+ */
+export function createCmsClient(componentApi, config) {
+    const resolvedConfig = resolveConfig(config);
+    // Store the getUserRole hook from the original config (not resolved)
+    const getUserRoleHook = config?.getUserRole;
+    // Store authorization hooks from config
+    const authHooks = config?.authorizationHooks;
+    // Store rate limit hooks from config
+    const rateLimitHooks = config?.rateLimitHooks;
+    // Create rate limit helper for API classes (only if rateLimitHooks are configured)
+    const rateLimitHelper = rateLimitHooks
+        ? {
+            async getUserRole(ctx, userId) {
+                if (!getUserRoleHook)
+                    return null;
+                return getUserRoleHook(ctx, { userId });
+            },
+            async requireRateLimit(operation, options) {
+                const context = createRateLimitContext(operation, options);
+                return requireRateLimit({
+                    hooks: rateLimitHooks,
+                    context,
+                });
+            },
+        }
+        : undefined;
+    // Create authorization helper for API classes (only if getUserRole is configured)
+    const authHelper = getUserRoleHook
+        ? {
+            async getUserRole(ctx, userId) {
+                return getUserRoleHook(ctx, { userId });
+            },
+            async requireAuthorization(ctx, context) {
+                const fullContext = {
+                    ...context,
+                    ctx: ctx,
+                };
+                const rbacOptions = contextToRbacOptions(fullContext);
+                const result = await executeAuthorizationHooks({
+                    hooks: authHooks,
+                    context: fullContext,
+                    rbacOptions: rbacOptions ?? undefined,
+                    skipRbac: resolvedConfig.skipRbac,
+                });
+                if (!result.allowed) {
+                    const rbacMapping = operationToRbac(fullContext.operation);
+                    // Import UnauthorizedError dynamically to avoid circular dependency
+                    const { UnauthorizedError } = await import("../component/authorization.js");
+                    throw new UnauthorizedError(result.reason ?? "Operation not allowed", {
+                        code: result.rbacResult?.allowed === false
+                            ? result.rbacResult.code
+                            : "PERMISSION_DENIED",
+                        resource: rbacMapping?.resource,
+                        action: rbacMapping?.action,
+                        role: fullContext.role ?? undefined,
+                        userId: fullContext.userId,
+                    });
+                }
+                return result;
+            },
+            skipRbac: resolvedConfig.skipRbac ?? false,
+        }
+        : undefined;
+    return {
+        config: resolvedConfig,
+        api: componentApi,
+        contentTypes: new ContentTypesApi(componentApi, resolvedConfig, authHelper, rateLimitHelper),
+        contentEntries: new ContentEntriesApi(componentApi, resolvedConfig, authHelper, rateLimitHelper),
+        versions: new VersionsApi(componentApi, resolvedConfig, authHelper, rateLimitHelper),
+        mediaAssets: new MediaAssetsApi(componentApi, resolvedConfig, authHelper, rateLimitHelper),
+        mediaFolders: new MediaFoldersApi(componentApi, resolvedConfig, authHelper, rateLimitHelper),
+        mediaVariants: new MediaVariantsApi(componentApi, resolvedConfig),
+        // Locale fallback chain helpers
+        locale: {
+            getConfig() {
+                return {
+                    defaultLocale: resolvedConfig.defaultLocale,
+                    fallbackChains: resolvedConfig.localeFallbackChains,
+                    autoGenerateFallbacks: resolvedConfig.autoGenerateLocaleFallbacks,
+                    supportedLocales: resolvedConfig.supportedLocales,
+                };
+            },
+            getFallbackChain(locale) {
+                const fallbackConfig = this.getConfig();
+                return getFallbackChain(locale, fallbackConfig);
+            },
+            resolve(locale) {
+                const fallbackConfig = this.getConfig();
+                return resolveFallbackChain(locale, fallbackConfig);
+            },
+        },
+        isFeatureEnabled(feature) {
+            return resolvedConfig.features[feature] ?? false;
+        },
+        isLocaleSupported(locale) {
+            return resolvedConfig.supportedLocales.includes(locale);
+        },
+        hasUserRoleHook() {
+            return getUserRoleHook !== undefined;
+        },
+        hasAuthorizationHooks() {
+            if (!authHooks)
+                return false;
+            return !!(authHooks.beforeRbac ||
+                authHooks.afterRbac ||
+                authHooks.onDeny ||
+                (authHooks.operationHooks && Object.keys(authHooks.operationHooks).length > 0));
+        },
+        async getUserRole(ctx, userId) {
+            if (!getUserRoleHook) {
+                throw new Error("No getUserRole hook configured. " +
+                    "Configure a getUserRole function in createCmsClient options to map user IDs to CMS roles.");
+            }
+            return await getUserRoleHook(ctx, { userId });
+        },
+        async hasPermissionForUser(ctx, userId, permission, options) {
+            if (!getUserRoleHook) {
+                throw new Error("No getUserRole hook configured. " +
+                    "Configure a getUserRole function in createCmsClient options to map user IDs to CMS roles.");
+            }
+            const role = await getUserRoleHook(ctx, { userId });
+            // If user has no role, they have no permissions
+            if (role === null) {
+                return {
+                    allowed: false,
+                    role: null,
+                    permission,
+                };
+            }
+            // Check if the role has the requested permission
+            const allowed = hasPermission(role, permission, options?.customRoles);
+            return {
+                allowed,
+                role,
+                permission,
+            };
+        },
+        async authorize(context) {
+            // Build RBAC options from context
+            const rbacOptions = contextToRbacOptions(context);
+            return executeAuthorizationHooks({
+                hooks: authHooks,
+                context,
+                rbacOptions: rbacOptions ?? undefined,
+                skipRbac: resolvedConfig.skipRbac,
+            });
+        },
+        async requireAuthorization(context) {
+            const result = await this.authorize(context);
+            if (!result.allowed) {
+                const rbacMapping = operationToRbac(context.operation);
+                // Import UnauthorizedError dynamically to avoid circular dependency
+                const { UnauthorizedError } = await import("../component/authorization.js");
+                throw new UnauthorizedError(result.reason ?? "Operation not allowed", {
+                    code: result.rbacResult?.allowed === false
+                        ? result.rbacResult.code
+                        : "PERMISSION_DENIED",
+                    resource: rbacMapping?.resource,
+                    action: rbacMapping?.action,
+                    role: context.role ?? undefined,
+                    userId: context.userId,
+                });
+            }
+            return result;
+        },
+        // ==========================================================================
+        // Custom Roles Methods
+        // ==========================================================================
+        getCustomRoles() {
+            return resolvedConfig.customRoles;
+        },
+        getCustomRole(roleName) {
+            return resolvedConfig.customRoles[roleName];
+        },
+        isCustomRole(roleName) {
+            return roleName in resolvedConfig.customRoles;
+        },
+        async hasContentTypePermissionForUser(ctx, userId, permission, contentTypeName) {
+            if (!getUserRoleHook) {
+                throw new Error("No getUserRole hook configured. " +
+                    "Configure a getUserRole function in createCmsClient options to map user IDs to CMS roles.");
+            }
+            const role = await getUserRoleHook(ctx, { userId });
+            if (role === null) {
+                return {
+                    allowed: false,
+                    role: null,
+                    permission,
+                };
+            }
+            // Use the content-type-aware permission check
+            const allowed = hasContentTypePermission(role, permission, {
+                customRoles: resolvedConfig.customRoles,
+                contentTypeName,
+            });
+            return {
+                allowed,
+                role,
+                permission,
+            };
+        },
+        async getPermittedContentTypesForUser(ctx, userId, action) {
+            if (!getUserRoleHook) {
+                throw new Error("No getUserRole hook configured. " +
+                    "Configure a getUserRole function in createCmsClient options to map user IDs to CMS roles.");
+            }
+            const role = await getUserRoleHook(ctx, { userId });
+            if (role === null) {
+                return [];
+            }
+            return getPermittedContentTypes(role, action, {
+                customRoles: resolvedConfig.customRoles,
+            });
+        },
+        getAllRoles() {
+            return {
+                ...DEFAULT_ROLES,
+                ...resolvedConfig.customRoles,
+            };
+        },
+        // ==========================================================================
+        // Resource Ownership Methods
+        // ==========================================================================
+        async canUserPerformOnResource(ctx, userId, resource, action, resourceOwnerId) {
+            if (!getUserRoleHook) {
+                throw new Error("No getUserRole hook configured. " +
+                    "Configure a getUserRole function in createCmsClient options to map user IDs to CMS roles.");
+            }
+            const role = await getUserRoleHook(ctx, { userId });
+            // If user has no role, they have no permissions
+            if (role === null) {
+                return {
+                    allowed: false,
+                    role: null,
+                    reason: "No role assigned to user",
+                    code: "NO_ROLE",
+                };
+            }
+            // Use the core checkPermission function for comprehensive RBAC check
+            const { checkPermission } = await import("../component/authorization.js");
+            const result = checkPermission({
+                userId,
+                role,
+                resource,
+                action,
+                resourceOwnerId,
+                customRoles: resolvedConfig.customRoles,
+            });
+            if (result.allowed === true) {
+                return {
+                    allowed: true,
+                    role,
+                    grantedScope: result.grantedScope,
+                    ownershipVerified: result.ownershipVerified,
+                };
+            }
+            else {
+                // TypeScript narrows result to PermissionDenied when allowed === false
+                const denied = result;
+                return {
+                    allowed: false,
+                    role,
+                    reason: denied.reason,
+                    code: denied.code,
+                    ownershipRequired: denied.code === "OWNERSHIP_REQUIRED",
+                };
+            }
+        },
+        async requireUserCanPerformOnResource(ctx, userId, resource, action, resourceOwnerId) {
+            const result = await this.canUserPerformOnResource(ctx, userId, resource, action, resourceOwnerId);
+            if (!result.allowed) {
+                // Import UnauthorizedError dynamically to avoid circular dependency
+                const { UnauthorizedError } = await import("../component/authorization.js");
+                throw new UnauthorizedError(result.reason ?? "Operation not allowed", {
+                    code: (result.code ?? "PERMISSION_DENIED"),
+                    resource,
+                    action,
+                    role: result.role ?? undefined,
+                    userId,
+                    requiredScope: result.ownershipRequired ? "own" : undefined,
+                });
+            }
+            return {
+                allowed: true,
+                role: result.role,
+                grantedScope: result.grantedScope,
+                ownershipVerified: result.ownershipVerified ?? false,
+            };
+        },
+        isOwner(userId, resourceOwnerId) {
+            // Import the helper synchronously (it's a simple comparison)
+            if (userId === undefined || resourceOwnerId === undefined) {
+                return false;
+            }
+            return userId === resourceOwnerId;
+        },
+    };
+}
+//# sourceMappingURL=wrapper.js.map