create-vexcms 0.0.3

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

@@ -0,0 +1,246 @@
+import type { DataModel } from "@convex/_generated/dataModel"
+import type { GenericQueryCtx, TableNamesInDataModel } from "convex/server"
+
+import { ConvexError } from "convex/values"
+import { mutation, query, action } from "@convex/_generated/server"
+import { paginationOptsValidator } from "convex/server"
+import { v } from "convex/values"
+
+import { findCollectionBySlug, hasPermission } from "@vexcms/core"
+import { TABLE_SLUG_USERS } from "~/db/constants"
+import config from "../../vex.config"
+import { access } from "../../src/vexcms/access"
+
+import * as Media from "./model/media"
+
+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[]) ?? [],
+  }
+}
+
+async function requireUser(ctx: GenericQueryCtx<DataModel>) {
+  const result = await getUser(ctx)
+  if (!result) {
+    throw new ConvexError("Not authenticated")
+  }
+  return result
+}
+
+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 generateUploadUrl = mutation({
+  args: {},
+  handler: async (ctx) => {
+    return await ctx.storage.generateUploadUrl()
+  },
+})
+
+export const createMediaDocument = mutation({
+  args: {
+    collectionSlug: v.string(),
+    fields: v.any(),
+  },
+  handler: async (ctx, { collectionSlug, fields }) => {
+    const match = findCollectionBySlug({ slug: collectionSlug, config })
+    if (!match) {
+      throw new ConvexError(`Collection not found: ${collectionSlug}`)
+    }
+
+    const { user, roles } = await requireUser(ctx)
+
+    checkPermission({
+      access,
+      user,
+      userRoles: roles,
+      resource: collectionSlug,
+      action: "create",
+      data: fields as Record<string, unknown>,
+    })
+
+    return await Media.createMediaDocument<DataModel>({
+      ctx,
+      args: {
+        collectionSlug: collectionSlug as TableNamesInDataModel<DataModel>,
+        fields: fields as Record<string, unknown>,
+        collectionFields: match.fields,
+      },
+    })
+  },
+})
+
+export const paginatedSearchDocuments = query({
+  args: {
+    collectionSlug: v.string(),
+    searchIndexName: v.string(),
+    searchField: v.string(),
+    query: v.string(),
+    paginationOpts: paginationOptsValidator,
+  },
+  handler: async (ctx, { collectionSlug, searchIndexName, searchField, query: searchQuery, paginationOpts }) => {
+    const result = await Media.paginatedSearchDocuments<DataModel>({
+      args: {
+        collectionSlug: collectionSlug as TableNamesInDataModel<DataModel>,
+        searchIndexName,
+        searchField,
+        query: searchQuery,
+        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: collectionSlug,
+        action: "read",
+        data: doc,
+      })
+      return readAllowed === true
+    })
+
+    return { ...result, page: filteredPage }
+  },
+})
+
+/**
+ * Downloads a file from a URL and stores it in Convex storage.
+ * Returns storageId + file metadata for the client to create a media document.
+ */
+export const downloadAndStoreUrl = action({
+  args: {
+    url: v.string(),
+    maxSize: v.number(),
+  },
+  handler: async (ctx, { url, maxSize }) => {
+    // 1. Validate URL
+    let parsedUrl: URL
+    try {
+      parsedUrl = new URL(url)
+    } catch {
+      throw new ConvexError("Invalid URL")
+    }
+
+    // 2. Fetch with timeout
+    const controller = new AbortController()
+    const timeoutId = setTimeout(() => controller.abort(), 30000)
+
+    let response: Response
+    try {
+      response = await fetch(parsedUrl.href, { signal: controller.signal })
+    } catch (err: any) {
+      clearTimeout(timeoutId)
+      if (err.name === "AbortError") {
+        throw new ConvexError("URL fetch timed out")
+      }
+      throw new ConvexError(`Failed to fetch URL: ${err.message}`)
+    } finally {
+      clearTimeout(timeoutId)
+    }
+
+    if (!response.ok) {
+      throw new ConvexError(`Failed to fetch URL: ${response.statusText}`)
+    }
+
+    // 3. Reject HTML
+    const contentType = response.headers.get("Content-Type") || ""
+    if (contentType.includes("text/html")) {
+      throw new ConvexError("URL points to an HTML page, not a file")
+    }
+
+    // 4. Read body and check size
+    const arrayBuffer = await response.arrayBuffer()
+    if (arrayBuffer.byteLength > maxSize) {
+      throw new ConvexError(
+        `File size (${arrayBuffer.byteLength} bytes) exceeds maximum allowed (${maxSize} bytes)`,
+      )
+    }
+
+    // 5. Extract filename
+    let filename = "download"
+    try {
+      const pathname = decodeURIComponent(parsedUrl.pathname)
+      const segments = pathname.split("/").filter(Boolean)
+      if (segments.length > 0) {
+        const lastSegment = segments[segments.length - 1]
+        // Strip query-like suffixes that might leak through
+        const clean = lastSegment.split("?")[0].split("#")[0]
+        if (clean) filename = clean
+      }
+    } catch {
+      // Keep default filename
+    }
+
+    // Check Content-Disposition for filename
+    const disposition = response.headers.get("Content-Disposition")
+    if (disposition) {
+      const filenameMatch = disposition.match(/filename\*?=(?:UTF-8'')?["']?([^"';\n]+)/i)
+      if (filenameMatch?.[1]) {
+        filename = decodeURIComponent(filenameMatch[1].trim())
+      }
+    }
+
+    // 6. Extract mimeType
+    let mimeType = "application/octet-stream"
+    if (contentType) {
+      mimeType = contentType.split(";")[0].trim()
+    }
+
+    // 7. Store in Convex storage
+    const blob = new Blob([arrayBuffer], { type: mimeType })
+    const storageId = await ctx.storage.store(blob)
+
+    // 8. Return metadata
+    return {
+      storageId: storageId as string,
+      filename,
+      mimeType,
+      size: arrayBuffer.byteLength,
+    }
+  },
+})

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

@@ -0,0 +1,74 @@
+import { mutation } from "../_generated/server";
+import { v } from "convex/values";
+
+/**
+ * Generic backfill mutation called by the Vex CLI during auto-migration.
+ * Patches existing documents that are missing a field with a default value.
+ *
+ * The CLI calls this in a loop with cursor pagination until `isDone` is true.
+ */
+export const backfillField = mutation({
+  args: {
+    table: v.string(),
+    field: v.string(),
+    value: v.any(),
+    cursor: v.optional(v.string()),
+    batchSize: v.optional(v.number()),
+  },
+  handler: async (ctx, { table, field, value, cursor, batchSize = 100 }) => {
+    const results = await ctx.db
+      .query(table as any)
+      .paginate({ cursor: cursor ?? null, numItems: batchSize });
+
+    let patched = 0;
+    for (const doc of results.page) {
+      if ((doc as any)[field] === undefined) {
+        await ctx.db.patch(doc._id, { [field]: value } as any);
+        patched++;
+      }
+    }
+
+    return {
+      patched,
+      isDone: results.isDone,
+      cursor: results.continueCursor,
+    };
+  },
+});
+
+/**
+ * Generic field removal mutation called by the Vex CLI during auto-migration.
+ * Unsets a field from existing documents so the new schema (without the field)
+ * can be deployed without validation errors.
+ *
+ * The CLI calls this in a loop with cursor pagination until `isDone` is true.
+ */
+export const removeField = mutation({
+  args: {
+    table: v.string(),
+    field: v.string(),
+    cursor: v.optional(v.string()),
+    batchSize: v.optional(v.number()),
+  },
+  handler: async (ctx, { table, field, cursor, batchSize = 100 }) => {
+    const results = await ctx.db
+      .query(table as any)
+      .paginate({ cursor: cursor ?? null, numItems: batchSize });
+
+    let patched = 0;
+    for (const doc of results.page) {
+      if ((doc as any)[field] !== undefined) {
+        // Replace the entire document without the removed field
+        const { _id, _creationTime, [field]: _removed, ...rest } = doc as any;
+        await ctx.db.replace(_id, rest);
+        patched++;
+      }
+    }
+
+    return {
+      patched,
+      isDone: results.isDone,
+      cursor: results.continueCursor,
+    };
+  },
+});

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

@@ -0,0 +1,196 @@
+import type {
+  GenericDataModel,
+  GenericMutationCtx,
+  GenericQueryCtx,
+  PaginationOptions,
+  TableNamesInDataModel,
+} from "convex/server"
+
+import { ConvexError } from "convex/values"
+import { generateFormSchema, getPreviewSnapshot } from "@vexcms/core"
+import type { VexField, CollectionKind } from "@vexcms/core"
+
+async function resolveStorageUrl(
+  ctx: { storage: { getUrl: (id: any) => Promise<string | null> } },
+  doc: any,
+) {
+  if (doc?.storageId) {
+    const url = await ctx.storage.getUrl(doc.storageId)
+    if (url) return { ...doc, url }
+  }
+  return doc
+}
+
+export async function listDocuments<DataModel extends GenericDataModel>(props: {
+  args: {
+    collectionSlug: TableNamesInDataModel<DataModel>
+    paginationOpts: PaginationOptions
+    order?: "asc" | "desc"
+  }
+  ctx: GenericQueryCtx<DataModel>
+}) {
+  const { args, ctx } = props
+  const q = args.order === "desc"
+    ? ctx.db.query(args.collectionSlug).order("desc")
+    : ctx.db.query(args.collectionSlug)
+  const result = await q.paginate(args.paginationOpts)
+  const resolvedPage = await Promise.all(
+    result.page.map((doc: any) => resolveStorageUrl(ctx, doc)),
+  )
+  return { ...result, page: resolvedPage }
+}
+
+export async function countDocuments<DataModel extends GenericDataModel>(props: {
+  ctx: GenericQueryCtx<DataModel>
+  args: { collectionSlug: TableNamesInDataModel<DataModel> }
+}): Promise<number> {
+  return await (props.ctx.db.query(props.args.collectionSlug) as any).count()
+}
+
+export async function getDocument<DataModel extends GenericDataModel>(props: {
+  ctx: GenericQueryCtx<DataModel>
+  args: {
+    collectionSlug: TableNamesInDataModel<DataModel>
+    documentId: string
+    /** When true, merges the transient preview snapshot (from admin live preview) */
+    preview?: boolean
+  }
+}) {
+  const doc = await props.ctx.db.get(props.args.documentId as any)
+  if (!doc) return null
+  const resolved = await resolveStorageUrl(props.ctx, doc)
+
+  // Merge preview snapshot when explicitly requested (live preview iframe).
+  if (props.args.preview) {
+    const snapshot = await getPreviewSnapshot<DataModel>({
+      ctx: props.ctx,
+      collection: props.args.collectionSlug as string,
+      documentId: props.args.documentId,
+    })
+    if (snapshot) {
+      return { ...resolved, ...snapshot }
+    }
+  }
+
+  return resolved
+}
+
+export async function updateDocument<DataModel extends GenericDataModel>(props: {
+  ctx: GenericMutationCtx<DataModel>
+  args: {
+    collectionSlug: TableNamesInDataModel<DataModel>
+    documentId: string
+    fields: Record<string, unknown>
+    collectionFields: Record<string, VexField>
+  }
+}) {
+  const f = { ...props.args.fields }
+
+  // Resolve the file URL from storageId when replacing a media file
+  if (f.storageId && f.url === "") {
+    const url = await props.ctx.storage.getUrl(f.storageId as any)
+    if (url) f.url = url
+  }
+
+  const schema = generateFormSchema({
+    fields: props.args.collectionFields,
+  }).partial()
+
+  const result = schema.safeParse(f)
+  if (!result.success) {
+    throw new ConvexError({
+      message: "Validation failed",
+      errors: result.error.flatten(),
+    })
+  }
+
+  await props.ctx.db.patch(props.args.documentId as any, result.data as any)
+  return props.args.documentId
+}
+
+export async function createDocument<DataModel extends GenericDataModel>(props: {
+  ctx: GenericMutationCtx<DataModel>
+  args: {
+    collectionSlug: TableNamesInDataModel<DataModel>
+    fields: Record<string, unknown>
+    collectionFields: Record<string, VexField>
+    kind: CollectionKind
+  }
+}): Promise<string> {
+  if (props.args.kind === "global") {
+    const existing = await props.ctx.db.query(props.args.collectionSlug).first()
+    if (existing) {
+      throw new ConvexError(
+        `Global "${props.args.collectionSlug}" already exists. Globals can only have one document.`,
+      )
+    }
+  }
+
+  const schema = generateFormSchema({
+    fields: props.args.collectionFields,
+  })
+
+  const result = schema.safeParse(props.args.fields)
+  if (!result.success) {
+    throw new ConvexError({
+      message: "Validation failed",
+      errors: result.error.flatten(),
+    })
+  }
+
+  const data = result.data as Record<string, unknown>
+  // Default vex_status to "published" for all user collections
+  if (!data.vex_status) {
+    data.vex_status = "published"
+  }
+  const id = await props.ctx.db.insert(props.args.collectionSlug as any, data as any)
+  return id as string
+}
+
+export async function deleteDocument<DataModel extends GenericDataModel>(props: {
+  ctx: GenericMutationCtx<DataModel>
+  args: {
+    collectionSlug: TableNamesInDataModel<DataModel>
+    documentId: string
+    kind: CollectionKind
+  }
+}): Promise<void> {
+  if (props.args.kind === "global") {
+    const existing = await props.ctx.db.get(props.args.documentId as any)
+    if (!existing) {
+      throw new ConvexError(
+        `Global "${props.args.collectionSlug}" document not found. Cannot delete a non-existent global.`,
+      )
+    }
+  }
+
+  await props.ctx.db.delete(props.args.documentId as any)
+}
+
+export async function bulkDeleteDocuments<DataModel extends GenericDataModel>(props: {
+  ctx: GenericMutationCtx<DataModel>
+  args: {
+    documentIds: string[]
+  }
+}): Promise<{ deleted: number }> {
+  for (const id of props.args.documentIds) {
+    await props.ctx.db.delete(id as any)
+  }
+  return { deleted: props.args.documentIds.length }
+}
+
+export async function searchDocuments<DataModel extends GenericDataModel>(props: {
+  args: {
+    collectionSlug: TableNamesInDataModel<DataModel>
+    searchIndexName: string
+    searchField: string
+    query: string
+  }
+  ctx: GenericQueryCtx<DataModel>
+}) {
+  const { args, ctx } = props
+  const docs = await (ctx.db.query(args.collectionSlug) as any)
+    .withSearchIndex(args.searchIndexName, (q: any) => q.search(args.searchField, args.query))
+    .take(50)
+  return Promise.all(docs.map((doc: any) => resolveStorageUrl(ctx, doc)))
+}

package/templates/base-nextjs/convex/vex/model/media.ts

@@ -0,0 +1,87 @@
+import type {
+  GenericDataModel,
+  GenericMutationCtx,
+  GenericQueryCtx,
+  PaginationOptions,
+  TableNamesInDataModel,
+} from "convex/server"
+
+import { ConvexError } from "convex/values"
+import { generateFormSchema } from "@vexcms/core"
+import type { VexField } from "@vexcms/core"
+
+export async function createMediaDocument<DataModel extends GenericDataModel>(props: {
+  ctx: GenericMutationCtx<DataModel>
+  args: {
+    collectionSlug: TableNamesInDataModel<DataModel>
+    fields: Record<string, unknown>
+    collectionFields: Record<string, VexField>
+  }
+}): Promise<string> {
+  const f = { ...props.args.fields }
+
+  // Extract system fields that bypass form schema validation
+  const storageId = f.storageId
+  delete f.storageId
+
+  // Resolve the file URL from storageId before inserting
+  if (storageId && (!f.url || f.url === "")) {
+    const url = await props.ctx.storage.getUrl(storageId as any)
+    if (url) f.url = url
+  }
+
+  const schema = generateFormSchema({
+    fields: props.args.collectionFields,
+  })
+
+  const result = schema.safeParse(f)
+  if (!result.success) {
+    throw new ConvexError({
+      message: "Validation failed",
+      errors: result.error.flatten(),
+    })
+  }
+
+  // Re-attach storageId for the DB insert
+  const data = { ...result.data, ...(storageId ? { storageId } : {}) } as any
+  const id = await props.ctx.db.insert(props.args.collectionSlug as any, data)
+  return id as string
+}
+
+async function resolveStorageUrl(
+  ctx: { storage: { getUrl: (id: any) => Promise<string | null> } },
+  doc: any,
+) {
+  if (doc?.storageId) {
+    const url = await ctx.storage.getUrl(doc.storageId)
+    if (url) return { ...doc, url }
+  }
+  return doc
+}
+
+export async function paginatedSearchDocuments<DataModel extends GenericDataModel>(props: {
+  args: {
+    collectionSlug: TableNamesInDataModel<DataModel>
+    searchIndexName: string
+    searchField: string
+    query: string
+    paginationOpts: PaginationOptions
+  }
+  ctx: GenericQueryCtx<DataModel>
+}) {
+  const { args, ctx } = props
+
+  let result
+  if (args.query === "") {
+    result = await ctx.db.query(args.collectionSlug).paginate(args.paginationOpts)
+  } else {
+    result = await (ctx.db.query(args.collectionSlug))
+      .withSearchIndex(args.searchIndexName, (q) => q.search(args.searchField, args.query))
+      .paginate(args.paginationOpts)
+  }
+
+  const resolvedPage = await Promise.all(
+    result.page.map((doc: any) => resolveStorageUrl(ctx, doc)),
+  )
+  return { ...result, page: resolvedPage }
+}