create-vexcms 0.0.3

package/templates/base-nextjs/convex/vex/collections.ts

@@ -0,0 +1,321 @@
+import type { DataModel } from "@convex/_generated/dataModel"
+import type { GenericQueryCtx, TableNamesInDataModel } from "convex/server"
+
+import { mutation, query } from "@convex/_generated/server"
+import { findCollectionBySlug, hasPermission } from "@vexcms/core"
+import { paginationOptsValidator } from "convex/server"
+import { ConvexError, v } from "convex/values"
+
+import { TABLE_SLUG_USERS } from "~/db/constants"
+
+import config from "../../vex.config"
+import { access } from "../../src/vexcms/access"
+import * as Collections from "./model/collections"
+
+function requireCollection(slug: string) {
+  const match = findCollectionBySlug({ slug, config })
+  if (!match) {
+    throw new ConvexError(`Collection not found: ${slug}`)
+  }
+  return match
+}
+
+/**
+ * Try to get the current user. Returns null if not authenticated.
+ * Use this for queries where auth is optional (read filtering).
+ */
+async function getUser(ctx: GenericQueryCtx<DataModel>) {
+  const identity = await ctx.auth.getUserIdentity()
+  if (!identity?.email) return null
+
+  const user = await ctx.db
+    .query(TABLE_SLUG_USERS)
+    .withIndex("by_email", (q) => q.eq("email", identity.email!))
+    .first()
+
+  if (!user) return null
+
+  return {
+    user: user as Record<string, unknown>,
+    roles: (user.role as string[]) ?? [],
+  }
+}
+
+/**
+ * Get the current user, throwing if not authenticated.
+ * Use this for mutations where auth is required.
+ */
+async function requireUser(ctx: GenericQueryCtx<DataModel>) {
+  const result = await getUser(ctx)
+  if (!result) {
+    throw new ConvexError("Not authenticated")
+  }
+  return result
+}
+
+/**
+ * Check permission and throw ConvexError if denied.
+ * Error message includes which roles would grant the permission.
+ */
+function checkPermission(props: Parameters<typeof hasPermission>[0]) {
+  const result = hasPermission(props)
+  const denied =
+    result === false ||
+    (typeof result === "object" && !Object.values(result).some(Boolean))
+
+  if (denied) {
+    const grantingRoles: string[] = []
+    if (props.access) {
+      for (const role of props.access.roles) {
+        const check = hasPermission({ ...props, userRoles: [role] })
+        const allowed =
+          check === true ||
+          (typeof check === "object" && Object.values(check).some(Boolean))
+        if (allowed) grantingRoles.push(role)
+      }
+    }
+
+    const rolesHint =
+      grantingRoles.length > 0
+        ? ` Requires one of: ${grantingRoles.join(", ")}`
+        : ""
+    throw new ConvexError(
+      `Access denied: "${props.action}" on "${props.resource}".${rolesHint}`,
+    )
+  }
+
+  return result
+}
+
+export const listDocuments = query({
+  args: {
+    collectionSlug: v.string(),
+    order: v.optional(v.union(v.literal("asc"), v.literal("desc"))),
+    paginationOpts: paginationOptsValidator,
+  },
+  handler: async (ctx, args) => {
+    const result = await Collections.listDocuments<DataModel>({
+      args: {
+        collectionSlug: args.collectionSlug as TableNamesInDataModel<DataModel>,
+        order: args.order,
+        paginationOpts: args.paginationOpts,
+      },
+      ctx,
+    })
+
+    // Filter by read permission if user is authenticated
+    const auth = await getUser(ctx)
+    if (!auth) return result
+
+    const filteredPage = result.page.filter((doc: Record<string, unknown>) => {
+      const readAllowed = hasPermission({
+        access,
+        user: auth.user,
+        userRoles: auth.roles,
+        resource: args.collectionSlug,
+        action: "read",
+        data: doc,
+      })
+      return readAllowed === true
+    })
+
+    return { ...result, page: filteredPage }
+  },
+})
+
+export const countDocuments = query({
+  args: { collectionSlug: v.string() },
+  handler: async (ctx, { collectionSlug }) => {
+    return await Collections.countDocuments<DataModel>({
+      args: { collectionSlug: collectionSlug as TableNamesInDataModel<DataModel> },
+      ctx,
+    })
+  },
+})
+
+export const getDocument = query({
+  args: {
+    collectionSlug: v.string(),
+    documentId: v.string(),
+    preview: v.optional(v.boolean()),
+  },
+  handler: async (ctx, { collectionSlug, documentId, preview }) => {
+    const doc = await Collections.getDocument<DataModel>({
+      args: {
+        collectionSlug: collectionSlug as TableNamesInDataModel<DataModel>,
+        documentId,
+        preview,
+      },
+      ctx,
+    })
+
+    if (doc) {
+      const auth = await getUser(ctx)
+      if (auth) {
+        const readAllowed = hasPermission({
+          access,
+          user: auth.user,
+          userRoles: auth.roles,
+          resource: collectionSlug,
+          action: "read",
+          data: doc as Record<string, unknown>,
+        })
+        if (readAllowed !== true) return null
+      }
+    }
+
+    return doc
+  },
+})
+
+export const updateDocument = mutation({
+  args: {
+    collectionSlug: v.string(),
+    documentId: v.string(),
+    fields: v.any(),
+  },
+  handler: async (ctx, { collectionSlug, documentId, fields }) => {
+    const match = requireCollection(collectionSlug)
+    const { user, roles } = await requireUser(ctx)
+
+    const fieldNames = Object.keys(fields as Record<string, unknown>)
+    checkPermission({
+      access,
+      user,
+      userRoles: roles,
+      resource: collectionSlug,
+      action: "update",
+      fields: fieldNames,
+      data: fields as Record<string, unknown>,
+    })
+
+    return await Collections.updateDocument<DataModel>({
+      args: {
+        collectionFields: match.fields,
+        collectionSlug: collectionSlug as TableNamesInDataModel<DataModel>,
+        documentId,
+        fields: fields as Record<string, unknown>,
+      },
+      ctx,
+    })
+  },
+})
+
+export const createDocument = mutation({
+  args: {
+    collectionSlug: v.string(),
+    fields: v.any(),
+  },
+  handler: async (ctx, { collectionSlug, fields }) => {
+    const match = requireCollection(collectionSlug)
+    const { user, roles } = await requireUser(ctx)
+
+    const fieldNames = Object.keys(fields as Record<string, unknown>)
+    checkPermission({
+      access,
+      user,
+      userRoles: roles,
+      resource: collectionSlug,
+      action: "create",
+      fields: fieldNames,
+      data: fields as Record<string, unknown>,
+    })
+
+    return await Collections.createDocument<DataModel>({
+      args: {
+        collectionFields: match.fields,
+        collectionSlug: collectionSlug as TableNamesInDataModel<DataModel>,
+        fields: fields as Record<string, unknown>,
+        kind: match.kind,
+      },
+      ctx,
+    })
+  },
+})
+
+export const deleteDocument = mutation({
+  args: {
+    collectionSlug: v.string(),
+    documentId: v.string(),
+  },
+  handler: async (ctx, { collectionSlug, documentId }) => {
+    const match = requireCollection(collectionSlug)
+    const { user, roles } = await requireUser(ctx)
+
+    checkPermission({
+      access,
+      user,
+      userRoles: roles,
+      resource: collectionSlug,
+      action: "delete",
+    })
+
+    await Collections.deleteDocument<DataModel>({
+      args: {
+        collectionSlug: collectionSlug as TableNamesInDataModel<DataModel>,
+        documentId,
+        kind: match.kind,
+      },
+      ctx,
+    })
+  },
+})
+
+export const bulkDeleteDocuments = mutation({
+  args: {
+    collectionSlug: v.string(),
+    documentIds: v.array(v.string()),
+  },
+  handler: async (ctx, { collectionSlug, documentIds }) => {
+    const { user, roles } = await requireUser(ctx)
+
+    checkPermission({
+      access,
+      user,
+      userRoles: roles,
+      resource: collectionSlug,
+      action: "delete",
+    })
+
+    return await Collections.bulkDeleteDocuments<DataModel>({
+      args: { documentIds },
+      ctx,
+    })
+  },
+})
+
+export const searchDocuments = query({
+  args: {
+    collectionSlug: v.string(),
+    query: v.string(),
+    searchField: v.string(),
+    searchIndexName: v.string(),
+  },
+  handler: async (ctx, { collectionSlug, query: searchQuery, searchField, searchIndexName }) => {
+    const results = await Collections.searchDocuments<DataModel>({
+      args: {
+        collectionSlug: collectionSlug as TableNamesInDataModel<DataModel>,
+        query: searchQuery,
+        searchField,
+        searchIndexName,
+      },
+      ctx,
+    })
+
+    // Filter by read permission if user is authenticated
+    const auth = await getUser(ctx)
+    if (!auth) return results
+
+    return (results as Record<string, unknown>[]).filter((doc) => {
+      const readAllowed = hasPermission({
+        access,
+        user: auth.user,
+        userRoles: auth.roles,
+        resource: collectionSlug,
+        action: "read",
+        data: doc,
+      })
+      return readAllowed === true
+    })
+  },
+})

package/templates/base-nextjs/convex/vex/firstUser.ts

@@ -0,0 +1,134 @@
+import { ConvexError } from "convex/values"
+
+import { mutation, query } from "../_generated/server"
+
+import { TABLE_SLUG_USERS } from "~/db/constants"
+import { USER_ROLES } from "~/db/constants/auth"
+
+/**
+ * Check if the admin panel has been bootstrapped (at least one admin exists).
+ * Used by the landing page to determine whether to show "Sign Up" or "Sign In".
+ */
+export const isBootstrapped = query({
+  args: {},
+  handler: async (ctx) => {
+    const allUsers = await ctx.db.query(TABLE_SLUG_USERS).collect()
+
+    return allUsers.some((user) => {
+      const roles = user.role ?? []
+      return roles.includes(USER_ROLES.admin)
+    })
+  },
+})
+
+/**
+ * Promote the current user to admin if no admin exists yet.
+ * Called after the first user signs up.
+ *
+ * Convex mutations are serialized, so two simultaneous signups
+ * cannot both become admin — the second will see the first's promotion.
+ */
+export const promoteFirstAdmin = mutation({
+  args: {},
+  handler: async (ctx) => {
+    const identity = await ctx.auth.getUserIdentity()
+    if (!identity?.email) {
+      throw new ConvexError("Not authenticated")
+    }
+
+    // Find the current user by email
+    const currentUser = await ctx.db
+      .query(TABLE_SLUG_USERS)
+      .withIndex("by_email", (q) => q.eq("email", identity.email!))
+      .first()
+
+    if (!currentUser) {
+      throw new ConvexError("User not found")
+    }
+
+    // Check if any user already has admin role
+    const allUsers = await ctx.db.query(TABLE_SLUG_USERS).collect()
+    const hasAdmin = allUsers.some((user) => {
+      const roles = user.role ?? []
+      return roles.includes(USER_ROLES.admin)
+    })
+
+    if (hasAdmin) {
+      return { promoted: false }
+    }
+
+    // Promote this user to admin
+    const currentRoles = currentUser.role ?? []
+    if (!currentRoles.includes(USER_ROLES.admin)) {
+      await ctx.db.patch(currentUser._id, {
+        role: [...currentRoles, USER_ROLES.admin],
+      })
+    }
+
+    return { promoted: true }
+  },
+})
+
+/**
+ * Get the onboarding completion status for a user.
+ */
+export const getOnboardingStatus = query({
+  args: {},
+  handler: async (ctx) => {
+    const identity = await ctx.auth.getUserIdentity()
+    if (!identity?.email) return { complete: false }
+
+    const user = await ctx.db
+      .query(TABLE_SLUG_USERS)
+      .withIndex("by_email", (q) => q.eq("email", identity.email!))
+      .first()
+
+    if (!user) return { complete: false }
+
+    return { complete: !!(user as any).vex_onboarding_complete }
+  },
+})
+
+/**
+ * Mark the onboarding tour as complete for the current user.
+ */
+export const completeOnboarding = mutation({
+  args: {},
+  handler: async (ctx) => {
+    const identity = await ctx.auth.getUserIdentity()
+    if (!identity?.email) return
+
+    const user = await ctx.db
+      .query(TABLE_SLUG_USERS)
+      .withIndex("by_email", (q) => q.eq("email", identity.email!))
+      .first()
+
+    if (!user) return
+
+    await ctx.db.patch(user._id, {
+      vex_onboarding_complete: true,
+    } as any)
+  },
+})
+
+/**
+ * Reset the onboarding tour for the current user (restart tour).
+ */
+export const resetOnboarding = mutation({
+  args: {},
+  handler: async (ctx) => {
+    const identity = await ctx.auth.getUserIdentity()
+    if (!identity?.email) return
+
+    const user = await ctx.db
+      .query(TABLE_SLUG_USERS)
+      .withIndex("by_email", (q) => q.eq("email", identity.email!))
+      .first()
+
+    if (!user) return
+
+    await ctx.db.patch(user._id, {
+      vex_onboarding_complete: false,
+    } as any)
+  },
+})

package/templates/base-nextjs/convex/vex/helpers.ts

@@ -0,0 +1,33 @@
+import { createVexQuery } from "@vexcms/core"
+
+import { query } from "../_generated/server"
+
+/**
+ * Typed vexQuery builder — use this instead of `query` for queries
+ * that need draft/snapshot support (live preview, versioning).
+ *
+ * Automatically adds `_vexDrafts` arg and provides `ctx.drafts`
+ * with full return type inference from your DataModel.
+ *
+ * @example
+ * ```ts
+ * import { vexQuery } from "./vex/helpers"
+ * import { getPreviewSnapshot } from "@vexcms/core"
+ *
+ * export const getBySlug = vexQuery({
+ *   args: { slug: v.string() },
+ *   handler: async (ctx, args) => {
+ *     const doc = await ctx.db.query("pages")
+ *       .withIndex("by_slug", (q) => q.eq("slug", args.slug))
+ *       .first()
+ *     if (!doc) return null
+ *     if (ctx.drafts === "snapshot") {
+ *       const snapshot = await getPreviewSnapshot({ ctx, collection: "pages", documentId: doc._id })
+ *       if (snapshot) return { ...doc, ...snapshot }
+ *     }
+ *     return doc
+ *   },
+ * })
+ * ```
+ */
+export const vexQuery = createVexQuery(query)

package/templates/base-nextjs/convex/vex/impersonation.ts

@@ -0,0 +1,51 @@
+import type { DataModel } from "@convex/_generated/dataModel"
+import type { GenericQueryCtx } from "convex/server"
+
+import { query } from "@convex/_generated/server"
+
+import { TABLE_SLUG_USERS } from "~/db/constants"
+
+import { access } from "../../src/vexcms/access"
+
+async function getUser(ctx: GenericQueryCtx<DataModel>) {
+  const identity = await ctx.auth.getUserIdentity()
+  if (!identity?.email) return null
+
+  const user = await ctx.db
+    .query(TABLE_SLUG_USERS)
+    .withIndex("by_email", (q) => q.eq("email", identity.email!))
+    .first()
+
+  return user ?? null
+}
+
+/**
+ * List users available for impersonation.
+ * Only accessible by users with adminRoles.
+ */
+export const listImpersonatableUsers = query({
+  args: {},
+  handler: async (ctx) => {
+    const currentUser = await getUser(ctx)
+    if (!currentUser) return []
+
+    const roles = (currentUser.role as string[]) ?? []
+
+    // Check if user has an adminRole
+    const isAdmin = roles.some((r) => access.adminRoles.includes(r))
+    if (!isAdmin) return []
+
+    // Fetch all users except the current one
+    const allUsers = await ctx.db.query(TABLE_SLUG_USERS).collect()
+
+    return allUsers
+      .filter((u) => u._id !== currentUser._id)
+      .map((u) => ({
+        id: u._id as string,
+        name: u.name as string,
+        email: u.email as string,
+        avatar: (u.image as string) ?? undefined,
+        roles: (u.role as string[]) ?? [],
+      }))
+  },
+})