convex-cms 0.0.1

package/dist/client/adminApi.js

@@ -0,0 +1,716 @@
+/**
+ * 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, } from "convex/server";
+import { v } from "convex/values";
+import { fieldDefinitionValidator, contentStatusValidator, mediaTypeValidator, } from "../component/schema.js";
+// =============================================================================
+// 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, options = {}) {
+    const { auth } = options;
+    // Helper to run auth check if configured
+    const checkAuth = async (ctx, operation) => {
+        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,
+                        name: args.name,
+                        mimeType: args.mimeType,
+                        size: args.size,
+                        parentId: args.parentId,
+                        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,
+                        name: args.name,
+                        title: args.title,
+                        description: args.description,
+                        altText: args.altText,
+                        parentId: args.parentId,
+                        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) => ct.isActive).length;
+                    // Calculate entry stats
+                    const entries = entriesResult.page || [];
+                    const publishedEntries = entries.filter((e) => e.status === "published").length;
+                    const draftEntries = entries.filter((e) => e.status === "draft").length;
+                    const scheduledEntries = entries.filter((e) => e.status === "scheduled").length;
+                    // Calculate media stats by filtering on mimeType prefix
+                    const mediaAssets = (mediaResult.page || []);
+                    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,
+                        },
+                    };
+                },
+            }),
+        },
+    };
+}
+//# sourceMappingURL=adminApi.js.map