convex-cms 0.0.3 → 0.0.5-alpha.2

package/dist/client/adminApi.js

@@ -1,716 +0,0 @@
-/**
- * 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