convex-cms 0.0.1

package/src/client/adminApi.ts

@@ -0,0 +1,942 @@
+/**
+ * Admin API Helper for Convex CMS
+ *
+ * This module provides the `defineAdminAPI` function that creates typed
+ * Convex functions for the admin UI to call. Users export these functions
+ * from their `convex/` directory, which the admin UI then calls.
+ *
+ * This follows the standard Convex component pattern used by:
+ * - @convex-dev/agent's `definePlaygroundAPI`
+ * - template-component's `exposeApi`
+ * - @dodopayments/convex's class-based API
+ *
+ * @example
+ * ```typescript
+ * // convex/admin.ts
+ * import { defineAdminAPI } from "@convex-cms/core";
+ * import { components } from "./_generated/api";
+ *
+ * export const {
+ *   contentTypes,
+ *   entries,
+ *   media,
+ *   stats,
+ * } = defineAdminAPI(components.convexCms, {
+ *   auth: async (ctx, operation) => {
+ *     // Optional: validate user has admin access
+ *     const identity = await ctx.auth.getUserIdentity();
+ *     if (!identity) throw new Error("Unauthorized");
+ *     return identity.subject;
+ *   },
+ * });
+ * ```
+ */
+
+import {
+  queryGeneric,
+  mutationGeneric,
+  type Auth,
+} from "convex/server";
+import { v } from "convex/values";
+import type { ComponentApi } from "../component/_generated/component.js";
+import type { Id } from "../component/_generated/dataModel.js";
+import {
+  fieldDefinitionValidator,
+  contentStatusValidator,
+  mediaTypeValidator,
+} from "../component/schema.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Operation context passed to the auth callback.
+ */
+export type AdminOperation =
+  | { type: "contentTypes.list" }
+  | { type: "contentTypes.get"; id: string }
+  | { type: "contentTypes.create" }
+  | { type: "contentTypes.update"; id: string }
+  | { type: "contentTypes.delete"; id: string }
+  | { type: "entries.list"; contentTypeId: string }
+  | { type: "entries.get"; id: string }
+  | { type: "entries.create"; contentTypeId: string }
+  | { type: "entries.update"; id: string }
+  | { type: "entries.publish"; id: string }
+  | { type: "entries.unpublish"; id: string }
+  | { type: "entries.delete"; id: string }
+  | { type: "entries.duplicate"; id: string }
+  | { type: "entries.schedule"; id: string }
+  | { type: "entries.cancelSchedule"; id: string }
+  | { type: "entries.getScheduled" }
+  | { type: "media.assets.list" }
+  | { type: "media.assets.get"; id: string }
+  | { type: "media.assets.create" }
+  | { type: "media.assets.update"; id: string }
+  | { type: "media.assets.delete"; id: string }
+  | { type: "media.assets.restore"; id: string }
+  | { type: "media.assets.move" }
+  | { type: "media.folders.list" }
+  | { type: "media.folders.get"; id: string }
+  | { type: "media.folders.getTree" }
+  | { type: "media.folders.create" }
+  | { type: "media.folders.update"; id: string }
+  | { type: "media.folders.move"; id: string }
+  | { type: "media.folders.delete"; id: string }
+  | { type: "media.folders.restore"; id: string }
+  | { type: "media.generateUploadUrl" }
+  | { type: "stats.getDashboardStats" };
+
+/**
+ * Options for configuring the admin API.
+ */
+export interface AdminApiOptions {
+  /**
+   * Optional authentication callback.
+   *
+   * Called before each operation to validate access. Should throw if
+   * unauthorized. Returns the authenticated user's ID (or null for anonymous).
+   *
+   * If not provided, all operations are allowed (useful for development).
+   *
+   * @example
+   * ```typescript
+   * auth: async (ctx, operation) => {
+   *   const identity = await ctx.auth.getUserIdentity();
+   *   if (!identity) throw new Error("Unauthorized");
+   *   // Could also check operation.type for fine-grained access control
+   *   return identity.subject;
+   * }
+   * ```
+   */
+  auth?: (
+    ctx: { auth: Auth },
+    operation: AdminOperation
+  ) => Promise<string | null>;
+}
+
+// =============================================================================
+// Validators (reused across functions)
+// =============================================================================
+
+const paginationOptsValidator = v.object({
+  numItems: v.number(),
+  cursor: v.union(v.string(), v.null()),
+});
+
+// =============================================================================
+// defineAdminAPI
+// =============================================================================
+
+/**
+ * Creates typed Convex functions for the CMS admin UI.
+ *
+ * This function returns an object containing query and mutation functions
+ * that the admin UI calls. Users export these from their `convex/` directory.
+ *
+ * @param component - The CMS component API from `components.convexCms`
+ * @param options - Optional configuration including auth callback
+ * @returns Object with namespaced admin functions
+ *
+ * @example
+ * ```typescript
+ * // convex/admin.ts
+ * import { defineAdminAPI } from "@convex-cms/core";
+ * import { components } from "./_generated/api";
+ *
+ * export const { contentTypes, entries, media, stats } = defineAdminAPI(
+ *   components.convexCms
+ * );
+ * ```
+ */
+export function defineAdminAPI(
+  component: ComponentApi,
+  options: AdminApiOptions = {}
+) {
+  const { auth } = options;
+
+  // Helper to run auth check if configured
+  const checkAuth = async (
+    ctx: { auth: Auth },
+    operation: AdminOperation
+  ): Promise<string | null> => {
+    if (auth) {
+      return await auth(ctx, operation);
+    }
+    return null;
+  };
+
+  return {
+    // =========================================================================
+    // Content Types
+    // =========================================================================
+    contentTypes: {
+      list: queryGeneric({
+        args: {
+          isActive: v.optional(v.boolean()),
+        },
+        returns: v.any(),
+        handler: async (ctx, args) => {
+          await checkAuth(ctx, { type: "contentTypes.list" });
+          // Returns paginated result: { page, continueCursor, isDone }
+          return await ctx.runQuery(component.contentTypes.list, {
+            isActive: args.isActive,
+          });
+        },
+      }),
+
+      get: queryGeneric({
+        args: {
+          id: v.optional(v.string()),
+          name: v.optional(v.string()),
+        },
+        returns: v.union(v.any(), v.null()),
+        handler: async (ctx, args) => {
+          await checkAuth(ctx, { type: "contentTypes.get", id: args.id ?? "" });
+          return await ctx.runQuery(component.contentTypes.get, {
+            id: args.id,
+            name: args.name,
+          });
+        },
+      }),
+
+      create: mutationGeneric({
+        args: {
+          name: v.string(),
+          displayName: v.string(),
+          fields: v.array(fieldDefinitionValidator),
+          description: v.optional(v.string()),
+          icon: v.optional(v.string()),
+          singleton: v.optional(v.boolean()),
+          slugField: v.optional(v.string()),
+          titleField: v.optional(v.string()),
+          sortOrder: v.optional(v.number()),
+          /** Required for audit tracking - the user ID creating this content type */
+          createdBy: v.string(),
+        },
+        returns: v.any(),
+        handler: async (ctx, args) => {
+          await checkAuth(ctx, { type: "contentTypes.create" });
+          return await ctx.runMutation(
+            component.contentTypeMutations.createContentType,
+            {
+              name: args.name,
+              displayName: args.displayName,
+              fields: args.fields,
+              description: args.description,
+              icon: args.icon,
+              singleton: args.singleton,
+              slugField: args.slugField,
+              titleField: args.titleField,
+              sortOrder: args.sortOrder,
+              createdBy: args.createdBy,
+            }
+          );
+        },
+      }),
+
+      update: mutationGeneric({
+        args: {
+          id: v.string(),
+          displayName: v.optional(v.string()),
+          fields: v.optional(v.array(fieldDefinitionValidator)),
+          description: v.optional(v.string()),
+          icon: v.optional(v.string()),
+          singleton: v.optional(v.boolean()),
+          slugField: v.optional(v.string()),
+          titleField: v.optional(v.string()),
+          sortOrder: v.optional(v.number()),
+          isActive: v.optional(v.boolean()),
+          updatedBy: v.optional(v.string()),
+        },
+        returns: v.any(),
+        handler: async (ctx, args) => {
+          await checkAuth(ctx, { type: "contentTypes.update", id: args.id });
+          return await ctx.runMutation(
+            component.contentTypeMutations.updateContentType,
+            {
+              id: args.id,
+              displayName: args.displayName,
+              fields: args.fields,
+              description: args.description,
+              icon: args.icon,
+              singleton: args.singleton,
+              slugField: args.slugField,
+              titleField: args.titleField,
+              sortOrder: args.sortOrder,
+              isActive: args.isActive,
+              updatedBy: args.updatedBy,
+            }
+          );
+        },
+      }),
+
+      delete: mutationGeneric({
+        args: {
+          id: v.string(),
+          cascade: v.optional(v.boolean()),
+          hardDelete: v.optional(v.boolean()),
+          deletedBy: v.optional(v.string()),
+        },
+        returns: v.any(),
+        handler: async (ctx, args) => {
+          await checkAuth(ctx, { type: "contentTypes.delete", id: args.id });
+          return await ctx.runMutation(
+            component.contentTypeMutations.deleteContentType,
+            {
+              id: args.id ,
+              cascade: args.cascade,
+              hardDelete: args.hardDelete,
+              deletedBy: args.deletedBy,
+            }
+          );
+        },
+      }),
+    },
+
+    // =========================================================================
+    // Content Entries
+    // =========================================================================
+    entries: {
+      list: queryGeneric({
+        args: {
+          contentTypeId: v.optional(v.string()),
+          status: v.optional(contentStatusValidator),
+          search: v.optional(v.string()),
+          locale: v.optional(v.string()),
+          paginationOpts: paginationOptsValidator,
+        },
+        returns: v.any(),
+        handler: async (ctx, args) => {
+          await checkAuth(ctx, {
+            type: "entries.list",
+            contentTypeId: args.contentTypeId ?? "",
+          });
+          return await ctx.runQuery(component.contentEntries.list, {
+            contentTypeId: args.contentTypeId ,
+            status: args.status,
+            search: args.search,
+            locale: args.locale,
+            paginationOpts: args.paginationOpts,
+          });
+        },
+      }),
+
+      get: queryGeneric({
+        args: {
+          id: v.string(),
+        },
+        returns: v.union(v.any(), v.null()),
+        handler: async (ctx, args) => {
+          await checkAuth(ctx, { type: "entries.get", id: args.id });
+          return await ctx.runQuery(component.contentEntries.get, {
+            id: args.id ,
+          });
+        },
+      }),
+
+      create: mutationGeneric({
+        args: {
+          contentTypeId: v.string(),
+          data: v.any(),
+          slug: v.optional(v.string()),
+          status: v.optional(contentStatusValidator),
+          locale: v.optional(v.string()),
+          primaryEntryId: v.optional(v.string()),
+          createdBy: v.optional(v.string()),
+        },
+        returns: v.any(),
+        handler: async (ctx, args) => {
+          await checkAuth(ctx, {
+            type: "entries.create",
+            contentTypeId: args.contentTypeId,
+          });
+          return await ctx.runMutation(
+            component.contentEntryMutations.createEntry,
+            {
+              contentTypeId: args.contentTypeId ,
+              data: args.data,
+              slug: args.slug,
+              status: args.status,
+              locale: args.locale,
+              primaryEntryId: args.primaryEntryId ,
+              createdBy: args.createdBy,
+            }
+          );
+        },
+      }),
+
+      update: mutationGeneric({
+        args: {
+          id: v.string(),
+          data: v.optional(v.any()),
+          slug: v.optional(v.string()),
+          status: v.optional(contentStatusValidator),
+          scheduledPublishAt: v.optional(v.number()),
+          updatedBy: v.optional(v.string()),
+          regenerateSlug: v.optional(v.boolean()),
+        },
+        returns: v.any(),
+        handler: async (ctx, args) => {
+          await checkAuth(ctx, { type: "entries.update", id: args.id });
+          return await ctx.runMutation(
+            component.contentEntryMutations.updateEntry,
+            {
+              id: args.id ,
+              data: args.data,
+              slug: args.slug,
+              status: args.status,
+              scheduledPublishAt: args.scheduledPublishAt,
+              updatedBy: args.updatedBy,
+              regenerateSlug: args.regenerateSlug,
+            }
+          );
+        },
+      }),
+
+      publish: mutationGeneric({
+        args: {
+          id: v.string(),
+          changeDescription: v.optional(v.string()),
+          updatedBy: v.optional(v.string()),
+        },
+        returns: v.any(),
+        handler: async (ctx, args) => {
+          await checkAuth(ctx, { type: "entries.publish", id: args.id });
+          return await ctx.runMutation(
+            component.contentEntryMutations.publishEntry,
+            {
+              id: args.id ,
+              changeDescription: args.changeDescription,
+              updatedBy: args.updatedBy,
+            }
+          );
+        },
+      }),
+
+      unpublish: mutationGeneric({
+        args: {
+          id: v.string(),
+          updatedBy: v.optional(v.string()),
+        },
+        returns: v.any(),
+        handler: async (ctx, args) => {
+          await checkAuth(ctx, { type: "entries.unpublish", id: args.id });
+          return await ctx.runMutation(
+            component.contentEntryMutations.unpublishEntry,
+            {
+              id: args.id ,
+              updatedBy: args.updatedBy,
+            }
+          );
+        },
+      }),
+
+      delete: mutationGeneric({
+        args: {
+          id: v.string(),
+          hardDelete: v.optional(v.boolean()),
+          deletedBy: v.optional(v.string()),
+        },
+        returns: v.any(),
+        handler: async (ctx, args) => {
+          await checkAuth(ctx, { type: "entries.delete", id: args.id });
+          return await ctx.runMutation(
+            component.contentEntryMutations.deleteEntry,
+            {
+              id: args.id ,
+              hardDelete: args.hardDelete,
+              deletedBy: args.deletedBy,
+            }
+          );
+        },
+      }),
+
+      duplicate: mutationGeneric({
+        args: {
+          id: v.string(),
+          copyMediaReferences: v.optional(v.boolean()),
+          createdBy: v.optional(v.string()),
+        },
+        returns: v.any(),
+        handler: async (ctx, args) => {
+          await checkAuth(ctx, { type: "entries.duplicate", id: args.id });
+          return await ctx.runMutation(
+            component.contentEntryMutations.duplicateEntry,
+            {
+              sourceEntryId: args.id ,
+              copyMediaReferences: args.copyMediaReferences,
+              createdBy: args.createdBy,
+            }
+          );
+        },
+      }),
+
+      schedule: mutationGeneric({
+        args: {
+          id: v.string(),
+          publishAt: v.number(),
+          updatedBy: v.optional(v.string()),
+        },
+        returns: v.any(),
+        handler: async (ctx, args) => {
+          await checkAuth(ctx, { type: "entries.schedule", id: args.id });
+          return await ctx.runMutation(
+            component.scheduledPublish.scheduleEntry,
+            {
+              id: args.id ,
+              publishAt: args.publishAt,
+              updatedBy: args.updatedBy,
+            }
+          );
+        },
+      }),
+
+      cancelSchedule: mutationGeneric({
+        args: {
+          id: v.string(),
+          updatedBy: v.optional(v.string()),
+        },
+        returns: v.any(),
+        handler: async (ctx, args) => {
+          await checkAuth(ctx, { type: "entries.cancelSchedule", id: args.id });
+          return await ctx.runMutation(
+            component.scheduledPublish.cancelScheduledPublish,
+            {
+              id: args.id ,
+              updatedBy: args.updatedBy,
+            }
+          );
+        },
+      }),
+
+      getScheduled: queryGeneric({
+        args: {},
+        returns: v.array(v.any()),
+        handler: async (ctx) => {
+          await checkAuth(ctx, { type: "entries.getScheduled" });
+          return await ctx.runQuery(
+            component.scheduledPublish.getScheduledEntries,
+            {}
+          );
+        },
+      }),
+    },
+
+    // =========================================================================
+    // Media (Assets and Folders)
+    // =========================================================================
+    media: {
+      // --- Assets ---
+      listAssets: queryGeneric({
+        args: {
+          folderId: v.optional(v.string()),
+          type: v.optional(mediaTypeValidator),
+          search: v.optional(v.string()),
+          paginationOpts: paginationOptsValidator,
+        },
+        returns: v.any(),
+        handler: async (ctx, args) => {
+          await checkAuth(ctx, { type: "media.assets.list" });
+          return await ctx.runQuery(component.mediaAssets.list, {
+            folderId: args.folderId ,
+            type: args.type,
+            search: args.search,
+            paginationOpts: args.paginationOpts,
+          });
+        },
+      }),
+
+      getAsset: queryGeneric({
+        args: {
+          id: v.string(),
+        },
+        returns: v.union(v.any(), v.null()),
+        handler: async (ctx, args) => {
+          await checkAuth(ctx, { type: "media.assets.get", id: args.id });
+          return await ctx.runQuery(component.mediaAssets.get, {
+            id: args.id ,
+          });
+        },
+      }),
+
+      createAsset: mutationGeneric({
+        args: {
+          storageId: v.string(),
+          name: v.string(),
+          mimeType: v.string(),
+          size: v.number(),
+          parentId: v.optional(v.string()),
+          width: v.optional(v.number()),
+          height: v.optional(v.number()),
+          title: v.optional(v.string()),
+          description: v.optional(v.string()),
+          altText: v.optional(v.string()),
+          createdBy: v.optional(v.string()),
+        },
+        returns: v.any(),
+        handler: async (ctx, args) => {
+          await checkAuth(ctx, { type: "media.assets.create" });
+          return await ctx.runMutation(
+            component.mediaAssetMutations.createMediaAsset,
+            {
+              storageId: args.storageId as Id<"_storage">,
+              name: args.name,
+              mimeType: args.mimeType,
+              size: args.size,
+              parentId: args.parentId as Id<"mediaItems"> | undefined,
+              width: args.width,
+              height: args.height,
+              title: args.title,
+              description: args.description,
+              altText: args.altText,
+              createdBy: args.createdBy,
+            }
+          );
+        },
+      }),
+
+      updateAsset: mutationGeneric({
+        args: {
+          id: v.string(),
+          name: v.optional(v.string()),
+          title: v.optional(v.string()),
+          description: v.optional(v.string()),
+          altText: v.optional(v.string()),
+          parentId: v.optional(v.string()),
+          tags: v.optional(v.array(v.string())),
+        },
+        returns: v.any(),
+        handler: async (ctx, args) => {
+          await checkAuth(ctx, { type: "media.assets.update", id: args.id });
+          return await ctx.runMutation(
+            component.mediaAssetMutations.updateMediaAsset,
+            {
+              id: args.id as Id<"mediaItems">,
+              name: args.name,
+              title: args.title,
+              description: args.description,
+              altText: args.altText,
+              parentId: args.parentId as Id<"mediaItems"> | undefined,
+              tags: args.tags,
+            }
+          );
+        },
+      }),
+
+      deleteAsset: mutationGeneric({
+        args: {
+          id: v.string(),
+          hardDelete: v.optional(v.boolean()),
+          deletedBy: v.optional(v.string()),
+        },
+        returns: v.any(),
+        handler: async (ctx, args) => {
+          await checkAuth(ctx, { type: "media.assets.delete", id: args.id });
+          return await ctx.runMutation(
+            component.mediaAssetMutations.deleteMediaAsset,
+            {
+              id: args.id ,
+              hardDelete: args.hardDelete,
+              deletedBy: args.deletedBy,
+            }
+          );
+        },
+      }),
+
+      restoreAsset: mutationGeneric({
+        args: {
+          id: v.string(),
+        },
+        returns: v.any(),
+        handler: async (ctx, args) => {
+          await checkAuth(ctx, { type: "media.assets.restore", id: args.id });
+          return await ctx.runMutation(
+            component.mediaAssetMutations.restoreMediaAsset,
+            {
+              id: args.id ,
+            }
+          );
+        },
+      }),
+
+      moveAssets: mutationGeneric({
+        args: {
+          assetIds: v.array(v.string()),
+          targetFolderId: v.optional(v.string()),
+        },
+        returns: v.any(),
+        handler: async (ctx, args) => {
+          await checkAuth(ctx, { type: "media.assets.move" });
+          return await ctx.runMutation(
+            component.mediaAssetMutations.moveMediaAssets,
+            {
+              assetIds: args.assetIds ,
+              targetFolderId: args.targetFolderId ,
+            }
+          );
+        },
+      }),
+
+      // --- Folders ---
+      listFolders: queryGeneric({
+        args: {
+          parentId: v.optional(v.string()),
+        },
+        returns: v.array(v.any()),
+        handler: async (ctx, args) => {
+          await checkAuth(ctx, { type: "media.folders.list" });
+          return await ctx.runQuery(
+            component.mediaFolderMutations.listMediaFolders,
+            {
+              parentId: args.parentId ,
+            }
+          );
+        },
+      }),
+
+      getFolder: queryGeneric({
+        args: {
+          id: v.string(),
+        },
+        returns: v.union(v.any(), v.null()),
+        handler: async (ctx, args) => {
+          await checkAuth(ctx, { type: "media.folders.get", id: args.id });
+          return await ctx.runQuery(
+            component.mediaFolderMutations.getMediaFolder,
+            {
+              id: args.id ,
+            }
+          );
+        },
+      }),
+
+      getFolderTree: queryGeneric({
+        args: {},
+        returns: v.array(v.any()),
+        handler: async (ctx) => {
+          await checkAuth(ctx, { type: "media.folders.getTree" });
+          return await ctx.runQuery(
+            component.mediaFolderMutations.getFolderTree,
+            {}
+          );
+        },
+      }),
+
+      createFolder: mutationGeneric({
+        args: {
+          name: v.string(),
+          parentId: v.optional(v.string()),
+          description: v.optional(v.string()),
+          createdBy: v.optional(v.string()),
+        },
+        returns: v.any(),
+        handler: async (ctx, args) => {
+          await checkAuth(ctx, { type: "media.folders.create" });
+          return await ctx.runMutation(
+            component.mediaFolderMutations.createMediaFolder,
+            {
+              name: args.name,
+              parentId: args.parentId ,
+              description: args.description,
+              createdBy: args.createdBy,
+            }
+          );
+        },
+      }),
+
+      updateFolder: mutationGeneric({
+        args: {
+          id: v.string(),
+          name: v.optional(v.string()),
+          description: v.optional(v.string()),
+          sortOrder: v.optional(v.number()),
+        },
+        returns: v.any(),
+        handler: async (ctx, args) => {
+          await checkAuth(ctx, { type: "media.folders.update", id: args.id });
+          return await ctx.runMutation(
+            component.mediaFolderMutations.updateMediaFolder,
+            {
+              id: args.id ,
+              name: args.name,
+              description: args.description,
+              sortOrder: args.sortOrder,
+            }
+          );
+        },
+      }),
+
+      moveFolder: mutationGeneric({
+        args: {
+          id: v.string(),
+          newParentId: v.optional(v.string()),
+        },
+        returns: v.any(),
+        handler: async (ctx, args) => {
+          await checkAuth(ctx, { type: "media.folders.move", id: args.id });
+          return await ctx.runMutation(
+            component.mediaFolderMutations.moveMediaFolder,
+            {
+              id: args.id ,
+              newParentId: args.newParentId ,
+            }
+          );
+        },
+      }),
+
+      deleteFolder: mutationGeneric({
+        args: {
+          id: v.string(),
+          recursive: v.optional(v.boolean()),
+          hardDelete: v.optional(v.boolean()),
+          deletedBy: v.optional(v.string()),
+        },
+        returns: v.any(),
+        handler: async (ctx, args) => {
+          await checkAuth(ctx, { type: "media.folders.delete", id: args.id });
+          return await ctx.runMutation(
+            component.mediaFolderMutations.deleteMediaFolder,
+            {
+              id: args.id ,
+              recursive: args.recursive,
+              hardDelete: args.hardDelete,
+              deletedBy: args.deletedBy,
+            }
+          );
+        },
+      }),
+
+      restoreFolder: mutationGeneric({
+        args: {
+          id: v.string(),
+          recursive: v.optional(v.boolean()),
+        },
+        returns: v.any(),
+        handler: async (ctx, args) => {
+          await checkAuth(ctx, { type: "media.folders.restore", id: args.id });
+          return await ctx.runMutation(
+            component.mediaFolderMutations.restoreMediaFolder,
+            {
+              id: args.id ,
+              recursive: args.recursive,
+            }
+          );
+        },
+      }),
+
+      // --- Upload ---
+      generateUploadUrl: mutationGeneric({
+        args: {},
+        returns: v.string(),
+        handler: async (ctx) => {
+          await checkAuth(ctx, { type: "media.generateUploadUrl" });
+          return await ctx.storage.generateUploadUrl();
+        },
+      }),
+    },
+
+    // =========================================================================
+    // Dashboard Stats
+    // =========================================================================
+    stats: {
+      getDashboardStats: queryGeneric({
+        args: {},
+        returns: v.object({
+          contentTypes: v.object({
+            total: v.number(),
+            active: v.number(),
+          }),
+          entries: v.object({
+            total: v.number(),
+            published: v.number(),
+            draft: v.number(),
+            scheduled: v.number(),
+          }),
+          media: v.object({
+            total: v.number(),
+            images: v.number(),
+            videos: v.number(),
+            documents: v.number(),
+          }),
+        }),
+        handler: async (ctx) => {
+          await checkAuth(ctx, { type: "stats.getDashboardStats" });
+
+          // Fetch all content types (returns paginated result)
+          const contentTypesResult = await ctx.runQuery(
+            component.contentTypes.list,
+            {}
+          );
+          const contentTypes = contentTypesResult.page || [];
+
+          // Fetch all entries (paginated, get counts)
+          const entriesResult = await ctx.runQuery(
+            component.contentEntries.list,
+            {
+              paginationOpts: { numItems: 1000, cursor: null },
+            }
+          );
+
+          // Fetch all media assets
+          const mediaResult = await ctx.runQuery(component.mediaAssets.list, {
+            paginationOpts: { numItems: 1000, cursor: null },
+          });
+
+          // Calculate content type stats
+          const activeContentTypes = contentTypes.filter(
+            (ct: { isActive: boolean }) => ct.isActive
+          ).length;
+
+          // Calculate entry stats
+          const entries = entriesResult.page || [];
+          const publishedEntries = entries.filter(
+            (e: { status: string }) => e.status === "published"
+          ).length;
+          const draftEntries = entries.filter(
+            (e: { status: string }) => e.status === "draft"
+          ).length;
+          const scheduledEntries = entries.filter(
+            (e: { status: string }) => e.status === "scheduled"
+          ).length;
+
+          // Calculate media stats by filtering on mimeType prefix
+          const mediaAssets = (mediaResult.page || []) as Array<{ kind: string; mimeType?: string }>;
+          const assets = mediaAssets.filter((m) => m.kind === "asset");
+          const images = assets.filter(
+            (m) => m.mimeType?.startsWith("image/")
+          ).length;
+          const videos = assets.filter(
+            (m) => m.mimeType?.startsWith("video/")
+          ).length;
+          const documents = assets.filter(
+            (m) => m.mimeType?.startsWith("application/pdf") ||
+                   m.mimeType?.includes("document") ||
+                   m.mimeType?.includes("sheet") ||
+                   m.mimeType?.includes("presentation")
+          ).length;
+
+          return {
+            contentTypes: {
+              total: contentTypes.length,
+              active: activeContentTypes,
+            },
+            entries: {
+              total: entries.length,
+              published: publishedEntries,
+              draft: draftEntries,
+              scheduled: scheduledEntries,
+            },
+            media: {
+              total: mediaAssets.length,
+              images,
+              videos,
+              documents,
+            },
+          };
+        },
+      }),
+    },
+  };
+}