convex-cms 0.0.5-alpha.2 → 0.0.5-alpha.4

package/README.md

@@ -1,7 +1,19 @@
 # Convex CMS
 
+> **Alpha Status (v0.0.5)** — Actively developed. APIs may change. [Report issues](https://github.com/obkaro/convex-cms/issues).
+
 A headless CMS built as a [Convex Component](https://docs.convex.dev/components) — content management that runs inside your Convex app.
 
+## Why Convex CMS?
+
+If you're building on Convex and need content management, this is the most integrated option:
+
+- **Zero infrastructure** — Runs entirely within your Convex deployment
+- **True real-time** — Content updates via Convex subscriptions, not polling
+- **Type-safe** — Code-first schemas with full TypeScript inference
+- **Component isolation** — Separate database tables, versioned independently
+- **Agent-native** — 23 pre-built tools for AI agent integration via `@convex-dev/agent`
+
 ## Choose Your Path
 
 ### Need an Admin Interface?
@@ -17,7 +29,7 @@ Your App                         Admin UI
             ├── listContentTypes
             ├── getEntry
             ├── publishEntry
-            └── ... (30+ functions)
+            └── ... (60+ functions across 11 domains)
                     │
                     ▼
             CMS Component
@@ -100,13 +112,33 @@ export default app;
 
 ## What's Included
 
-- **13 field types** — text, richText, media, reference, select, and more
+### Core Content
+- **13 field types** — text, richText, number, boolean, date, datetime, select, multiSelect, reference, media, json, tags, category
 - **Publishing workflows** — draft → scheduled → published with version history
-- **Media management** — uploads, folders, variants, and metadata
+- **Content versioning** — Snapshots, comparison, and rollback
+- **Scheduled publishing** — Convex scheduler integration for future publish dates
+
+### Media Management
+- **File uploads** — Direct to Convex storage with folder organization
+- **Image variants** — Automatic resizing and format conversion
+- **Metadata & tagging** — Alt text, descriptions, taxonomy support
+
+### Organization
+- **Taxonomies** — Hierarchical categories and flat tags
+- **Content locking** — Prevent concurrent edit conflicts
+- **Soft delete & trash** — Configurable retention with restore
+
+### Integration
 - **RBAC** — 4 built-in roles + custom roles with fine-grained permissions
-- **Multi-locale** — content localization with fallback chains
-- **Admin UI** — pre-built React interface (CLI or embeddable)
-- **Agent tools** — Zod schemas for AI integration
+- **Multi-locale** — Content localization with fallback chains
+- **Webhooks** — Event-driven integration with external systems
+- **Event system** — All mutations emit events for async processing
+- **Agent tools** — 23 pre-built tools with Zod schemas for AI integration
+- **Query builder** — Fluent API for complex content queries
+
+### Admin UI
+- **Pre-built React interface** — CLI mode for development, embeddable for production
+- **Visual content editing** — Rich text, media picker, reference selector
 
 ## Admin UI Modes
 
@@ -121,17 +153,20 @@ Both modes call the same functions from your `convex/admin.ts`.
 
 | Guide | Description |
 |-------|-------------|
-| [Admin UI Setup](./docs/guides/admin-ui-setup.md) | CLI and embed modes, auth integration |
 | [Getting Started](./docs/guides/getting-started.md) | Programmatic usage with createCmsClient |
-| [Integration Patterns](./docs/guides/integration-patterns.md) | Common setups and when to use each |
+| [Admin UI Setup](./docs/guides/admin-ui-setup.md) | CLI and embed modes, auth integration |
 | [Content Modeling](./docs/guides/content-modeling.md) | Content types and field definitions |
+| [Query Builder](./docs/guides/query-builder.md) | Fluent API for complex queries |
+| [Taxonomies](./docs/guides/taxonomies.md) | Categories, tags, and organization |
 | [Authorization](./docs/guides/authorization.md) | Roles, permissions, and custom auth |
 | [Media Management](./docs/guides/media.md) | Uploads, folders, and variants |
+| [Agent Tools](./docs/guides/agent-tools.md) | AI agent integration with Zod schemas |
+| [Integration Patterns](./docs/guides/integration-patterns.md) | Common setups and when to use each |
 
 | Reference | Description |
 |-----------|-------------|
 | [Client API](./docs/api/client-api.md) | createCmsClient methods |
-| [Admin API](./docs/api/admin-api.md) | defineAdminAPI functions |
+| [Admin API](./docs/api/admin-api.md) | 60+ defineAdminAPI functions |
 | [Code-First Schema](./docs/api/code-first-schema.md) | TypeScript-first content types |
 | [Field Types](./docs/api/field-types.md) | All 13 field types |
 | [Configuration](./docs/api/configuration.md) | All config options |

package/admin/src/components/BulkActionBar.tsx

@@ -27,10 +27,10 @@ export function BulkActionBar({
     errors?: string[]
   } | null>(null)
 
-  const bulkPublish = useMutation(api.bulkOperations.bulkPublish)
-  const bulkUnpublish = useMutation(api.bulkOperations.bulkUnpublish)
-  const bulkDelete = useMutation(api.bulkOperations.bulkDelete)
-  const bulkUpdate = useMutation(api.bulkOperations.bulkUpdate)
+  const bulkPublish = useMutation(api.admin.bulkPublish)
+  const bulkUnpublish = useMutation(api.admin.bulkUnpublish)
+  const bulkDelete = useMutation(api.admin.bulkDelete)
+  const bulkUpdate = useMutation(api.admin.bulkUpdate)
 
   const handleAction = useCallback((action: BulkAction) => {
     setActiveAction(action)

package/admin/src/components/ContentEntryEditor.tsx

@@ -188,14 +188,14 @@ export function ContentEntryEditor({
   const formDataRef = useRef(formData)
   formDataRef.current = formData
 
-  const createEntry = useMutation(api.entries.create)
-  const updateEntry = useMutation(api.entries.update)
-  const publishEntry = useMutation(api.entries.publish)
-  const unpublishEntry = useMutation(api.entries.unpublish)
-  const scheduleEntry = useMutation(api.entries.schedule)
-  const cancelScheduleEntry = useMutation(api.entries.cancelSchedule)
-  const deleteEntryMutation = useMutation(api.entries.remove)
-  const duplicateEntryMutation = useMutation(api.entries.duplicate)
+  const createEntry = useMutation(api.admin.createEntry)
+  const updateEntry = useMutation(api.admin.updateEntry)
+  const publishEntry = useMutation(api.admin.publishEntry)
+  const unpublishEntry = useMutation(api.admin.unpublishEntry)
+  const scheduleEntry = useMutation(api.admin.scheduleEntry)
+  const cancelScheduleEntry = useMutation(api.admin.cancelScheduledEntry)
+  const deleteEntryMutation = useMutation(api.admin.deleteEntry)
+  const duplicateEntryMutation = useMutation(api.admin.duplicateEntry)
 
   const [showScheduleModal, setShowScheduleModal] = useState(false)
   const [scheduleDateTime, setScheduleDateTime] = useState<string>(() => {
@@ -500,26 +500,6 @@ export function ContentEntryEditor({
     }
   }, [entry, publishEntry, onSave])
 
-  const _handleUnpublish = useCallback(async () => {
-    if (!entry) return
-
-    setIsPublishing(true)
-    setPublishError(null)
-
-    try {
-      const draftEntry = (await unpublishEntry({
-        id: entry._id,
-      })) as ContentEntry
-      onSave?.(draftEntry)
-    } catch (error) {
-      const message =
-        error instanceof Error ? error.message : 'Failed to unpublish'
-      setPublishError(message)
-    } finally {
-      setIsPublishing(false)
-    }
-  }, [entry, unpublishEntry, onSave])
-
   const handleSchedule = useCallback(async () => {
     if (!entry) return
 

package/admin/src/components/ContentTypeFormModal.tsx

@@ -188,8 +188,8 @@ export function ContentTypeFormModal({
 	const [showBreakingWarning, setShowBreakingWarning] = useState(false);
 	const [isForceUpdating, setIsForceUpdating] = useState(false);
 
-	const createContentType = useMutation(api.contentTypes.create);
-	const updateContentType = useMutation(api.contentTypes.update);
+	const createContentType = useMutation(api.admin.createContentType);
+	const updateContentType = useMutation(api.admin.updateContentType);
 
 	// Populate form when editing
 	useEffect(() => {

package/admin/src/components/TaxonomyEditor.tsx

@@ -49,8 +49,8 @@ export function TaxonomyEditor({
   const [submitError, setSubmitError] = useState<string | null>(null)
   const [slugManuallyEdited, setSlugManuallyEdited] = useState(false)
 
-  const createTaxonomy = useMutation(api.taxonomies.createTaxonomy)
-  const updateTaxonomy = useMutation(api.taxonomies.updateTaxonomy)
+  const createTaxonomy = useMutation(api.admin.createTaxonomy)
+  const updateTaxonomy = useMutation(api.admin.updateTaxonomy)
 
   useEffect(() => {
     if (taxonomy) {

package/admin/src/components/TermTree.tsx

@@ -42,10 +42,10 @@ export function TermTree({
   const [error, setError] = useState<string | null>(null)
 
   const termsQuery = isHierarchical
-    ? useQuery(api.taxonomies.getTermsHierarchy, { taxonomyId })
-    : useQuery(api.taxonomies.listTerms, { taxonomyId })
+    ? useQuery(api.admin.getTermsHierarchy, { taxonomyId })
+    : useQuery(api.admin.listTerms, { taxonomyId })
 
-  const deleteTerm = useMutation(api.taxonomies.deleteTerm)
+  const deleteTerm = useMutation(api.admin.deleteTerm)
 
   const terms = (
     isHierarchical ? termsQuery : (termsQuery as { page?: Term[] })?.page
@@ -304,8 +304,8 @@ function TermEditModal({
   const [submitError, setSubmitError] = useState<string | null>(null)
   const [slugManuallyEdited, setSlugManuallyEdited] = useState(false)
 
-  const createTerm = useMutation(api.taxonomies.createTerm)
-  const updateTerm = useMutation(api.taxonomies.updateTerm)
+  const createTerm = useMutation(api.admin.createTerm)
+  const updateTerm = useMutation(api.admin.updateTerm)
 
   const handleChange = useCallback(
     (field: keyof typeof formData, value: string | number) => {

package/admin/src/components/VersionCompare.tsx

@@ -47,7 +47,7 @@ export function VersionCompare({
   onClose,
   onRollback,
 }: VersionCompareProps) {
-  const comparisonQuery = useQuery(api.versions.compare, {
+  const comparisonQuery = useQuery(api.admin.compareVersions, {
     entryId,
     fromVersionNumber: fromVersion,
     toVersionNumber: toVersion,

package/admin/src/components/VersionHistory.tsx

@@ -42,12 +42,12 @@ export function VersionHistory({
   const [rollbackError, setRollbackError] = useState<string | null>(null)
   const [rollbackSuccess, setRollbackSuccess] = useState(false)
 
-  const versionsQuery = useQuery(api.versions.getHistory, {
+  const versionsQuery = useQuery(api.admin.getVersionHistory, {
     entryId,
     paginationOpts: { numItems: 50, cursor: null },
   })
 
-  const rollbackMutation = useMutation(api.versions.rollback)
+  const rollbackMutation = useMutation(api.admin.rollbackVersion)
 
   const versions = (versionsQuery?.page ?? []) as VersionItem[]
   const isLoading = versionsQuery === undefined

package/admin/src/components/fields/CategoryField.tsx

@@ -52,7 +52,7 @@ export function CategoryField({
   const containerRef = useRef<HTMLDivElement>(null)
 
   const hierarchyResult = useQuery(
-    api.taxonomies.getTermsHierarchy,
+    api.admin.getTermsHierarchy,
     taxonomyId ? { taxonomyId: asTaxonomyId(taxonomyId) } : 'skip'
   )
   const categoryTree = (hierarchyResult ?? []) as CategoryTerm[]

package/admin/src/components/fields/MediaField.tsx

@@ -105,12 +105,12 @@ export function MediaField({
   const allowedMimeTypes = field.options?.allowedMimeTypes ?? []
 
   const selectedAsset = useQuery(
-    api.media.getAsset,
+    api.admin.getMediaAsset,
     value ? { id: value } : 'skip'
   )
 
   const assetsResult = useQuery(
-    api.media.listAssets,
+    api.admin.listMediaAssets,
     showPicker
       ? {
           type: typeFilter
@@ -345,8 +345,8 @@ export function MediaField({
 
             <TabsContent value="upload" className="mt-4">
               <UploadDropzone
-                generateUploadUrl={api.media.generateUploadUrl}
-                createAsset={api.media.createAsset}
+                generateUploadUrl={api.admin.generateUploadUrl}
+                createAsset={api.admin.createMediaAsset}
                 onUploadComplete={handleUploadComplete}
                 allowedMimeTypes={allowedMimeTypes}
                 maxFileSize={field.options?.maxFileSize}

package/admin/src/components/fields/ReferenceField.tsx

@@ -75,7 +75,7 @@ export function ReferenceField({
     return Array.isArray(value) ? value : [value]
   }, [value])
 
-  const contentTypes = useQuery(api.contentTypes.list, {
+  const contentTypes = useQuery(api.admin.listContentTypes, {
     isActive: true,
     includeEntryCounts: false,
   })
@@ -91,12 +91,12 @@ export function ReferenceField({
   }, [contentTypes?.page, allowedContentTypes])
 
   const selectedEntry = useQuery(
-    api.entries.get,
+    api.admin.getEntry,
     selectedIds.length === 1 ? { id: selectedIds[0] } : 'skip'
   )
 
   const selectedEntries = useQuery(
-    api.entries.list,
+    api.admin.listEntries,
     selectedIds.length > 1
       ? {
           paginationOpts: { numItems: 100, cursor: null },
@@ -110,7 +110,7 @@ export function ReferenceField({
   }, [selectedEntries?.page, selectedIds])
 
   const entriesResult = useQuery(
-    api.entries.list,
+    api.admin.listEntries,
     showPicker
       ? {
           contentTypeId: contentTypeFilter || undefined,

package/admin/src/components/fields/TagField.tsx

@@ -51,7 +51,7 @@ export function TagField({
   const containerRef = useRef<HTMLDivElement>(null)
 
   const suggestionsResult = useQuery(
-    api.taxonomies.suggestTerms,
+    api.admin.suggestTerms,
     taxonomyId
       ? {
           taxonomyId: asTaxonomyId(taxonomyId),
@@ -64,7 +64,7 @@ export function TagField({
   const suggestions = suggestionsResult ?? []
 
   const selectedTermsResult = useQuery(
-    api.taxonomies.listTerms,
+    api.admin.listTerms,
     taxonomyId && value && value.length > 0
       ? {
           taxonomyId: asTaxonomyId(taxonomyId),
@@ -82,7 +82,7 @@ export function TagField({
     }
   }
 
-  const createTermMutation = useMutation(api.taxonomies.createTerm)
+  const createTermMutation = useMutation(api.admin.createTerm)
 
   useEffect(() => {
     function handleClickOutside(event: MouseEvent) {

package/admin/src/components/filters/TaxonomyFilter.tsx

@@ -49,7 +49,7 @@ export function TaxonomyFilter({
   const [open, setOpen] = useState(false)
   const [search, setSearch] = useState('')
 
-  const taxonomiesResult = useQuery(api.taxonomies.list, { isActive: true })
+  const taxonomiesResult = useQuery(api.admin.listTaxonomies, { isActive: true })
   const taxonomies = taxonomiesResult?.page ?? []
 
   const activeTaxonomy = useMemo(() => {
@@ -62,7 +62,7 @@ export function TaxonomyFilter({
   const targetTaxonomyId = taxonomyId ?? taxonomies[0]?._id
 
   const termsResult = useQuery(
-    api.taxonomies.listTerms,
+    api.admin.listTerms,
     targetTaxonomyId
       ? {
           taxonomyId: targetTaxonomyId,

package/admin/src/components/media/MediaAssetEditDialog.tsx

@@ -38,9 +38,9 @@ export function MediaAssetEditDialog({
   const [isSaving, setIsSaving] = useState(false)
   const [error, setError] = useState('')
 
-  const updateAsset = useMutation(api.media.updateAsset)
+  const updateAsset = useMutation(api.admin.updateMediaAsset)
 
-  const taxonomiesResult = useQuery(api.taxonomies.list, {
+  const taxonomiesResult = useQuery(api.admin.listTaxonomies, {
     isActive: true,
     paginationOpts: { numItems: 50, cursor: null },
   })

package/admin/src/components/media/MediaFolderEditDialog.tsx

@@ -31,7 +31,7 @@ export function MediaFolderEditDialog({
   const [isSaving, setIsSaving] = useState(false)
   const [error, setError] = useState('')
 
-  const updateFolder = useMutation(api.media.updateFolder)
+  const updateFolder = useMutation(api.admin.updateMediaFolder)
 
   useEffect(() => {
     if (folder) {

package/admin/src/components/media/MediaMoveModal.tsx

@@ -34,8 +34,8 @@ export function MediaMoveModal({
   const [isMoving, setIsMoving] = useState(false)
   const [error, setError] = useState('')
 
-  const folderTree = useQuery(api.media.getFolderTree, {})
-  const moveAssets = useMutation(api.media.moveAssets)
+  const folderTree = useQuery(api.admin.getMediaFolderTree, {})
+  const moveAssets = useMutation(api.admin.moveMediaAssets)
 
   const sortedFolders = useMemo(() => {
     if (!folderTree) return []

package/admin/src/components/media/MediaTaxonomyPicker.tsx

@@ -42,14 +42,14 @@ export function MediaTaxonomyPicker({
   const suggestionsRef = useRef<HTMLDivElement>(null)
   const containerRef = useRef<HTMLDivElement>(null)
 
-  const currentTerms = useQuery(api.taxonomies.getTermsByMedia, {
+  const currentTerms = useQuery(api.admin.getTermsByMedia, {
     mediaId,
     taxonomyId,
   })
 
   const selectedTermIds = currentTerms?.map((t: TaxonomyTermDisplay) => t._id) ?? []
 
-  const suggestionsResult = useQuery(api.taxonomies.suggestTerms, {
+  const suggestionsResult = useQuery(api.admin.suggestTerms, {
     taxonomyId,
     query: inputValue,
     limit: 10,
@@ -57,8 +57,8 @@ export function MediaTaxonomyPicker({
   })
   const suggestions = (suggestionsResult ?? []) as TaxonomyTermDisplay[]
 
-  const setMediaTermsMutation = useMutation(api.taxonomies.setMediaTerms)
-  const createTermMutation = useMutation(api.taxonomies.createTermAndAddToMedia)
+  const setMediaTermsMutation = useMutation(api.admin.setMediaTerms)
+  const createTermMutation = useMutation(api.admin.createTermAndAddToMedia)
 
   useEffect(() => {
     function handleClickOutside(event: MouseEvent) {

package/admin/src/contexts/SettingsConfigContext.tsx

@@ -4,7 +4,7 @@ import { api } from "../../convex/_generated/api";
 import type { AdminConfig } from "~/lib/admin-config";
 import { AdminConfigProvider } from "./AdminConfigContext";
 
-type Settings = NonNullable<typeof api.settings.get._returnType>;
+type Settings = NonNullable<typeof api.admin.getSettings._returnType>;
 
 interface SettingsConfigContextValue {
   baseConfig: AdminConfig;
@@ -20,7 +20,7 @@ export function SettingsConfigProvider({
   baseConfig: AdminConfig;
   children: ReactNode;
 }) {
-  const settings = useQuery(api.settings.get);
+  const settings = useQuery(api.admin.getSettings);
 
   const mergedConfig = useMemo((): AdminConfig => {
     if (!settings) return baseConfig;