convex-cms 0.0.6 → 0.0.7-alpha.0

package/README.md

@@ -1,86 +1,11 @@
 # Convex CMS
 
-> **Alpha Status (v0.0.5)** — Actively developed. APIs may change. [Report issues](https://github.com/obkaro/convex-cms/issues).
+[![npm version](https://badge.fury.io/js/convex-cms.svg)](https://www.npmjs.com/package/convex-cms)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-A headless CMS built as a [Convex Component](https://docs.convex.dev/components) — content management that runs inside your Convex app.
+> **Alpha (v0.0.6)** Actively developed. APIs may change. [Report issues](https://github.com/obkaro/convex-cms/issues).
 
-## 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?
-
-Use **`defineAdminAPI`** — one line creates all the backend functions for a working admin UI.
-
-```
-Your App                         Admin UI
-    │                               │
-    └── convex/admin.ts ────────────┘
-        defineAdminAPI()
-            │
-            ├── listContentTypes
-            ├── getEntry
-            ├── publishEntry
-            └── ... (60+ functions across 11 domains)
-                    │
-                    ▼
-            CMS Component
-```
-
-→ **[Admin UI Setup Guide](./docs/guides/admin-ui-setup.md)**
-
-### Building Custom Content Logic?
-
-Use **`createCmsClient`** — full programmatic control with typed methods in your Convex functions.
-
-```
-Your Convex Functions
-    │
-    └── cms.contentEntries.list(ctx, { status: "published" })
-        cms.contentTypes.create(ctx, { name: "blog", ... })
-        cms.mediaAssets.upload(ctx, { ... })
-            │
-            ▼
-        CMS Component
-```
-
-→ **[Getting Started Guide](./docs/guides/getting-started.md)**
-
-### Want Full Type Safety?
-
-Use **code-first schemas** — define content types with Convex validators, get TypeScript inference.
-
-```typescript
-const blogPost = defineContentType({
-  name: "blog_post",
-  validator: v.object({
-    title: v.string(),
-    content: v.string(),
-  }),
-});
-
-// TypeScript knows entry.data.title is string
-const entry = await cms.typedContentEntries.get<"blog_post">(ctx, id);
-```
-
-→ **[Code-First Schema Reference](./docs/api/code-first-schema.md)**
-
-### Need Both?
-
-**Most apps use both.** This is the typical setup:
-
-- `defineAdminAPI` powers the admin interface for content editors
-- `createCmsClient` gives you typed methods for custom queries on your frontend
-
-They work together through the same CMS component.
+A headless CMS built as a [Convex Component](https://docs.convex.dev/components). Content management that runs inside your Convex app.
 
 ## Quick Start
 
@@ -110,35 +35,72 @@ export default app;
 **For Custom Functions:** Create a CMS client and use it in your functions
 → [Full Getting Started Guide](./docs/guides/getting-started.md)
 
+## 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`
+
+## Features
+
+| Feature | What it does |
+|---------|--------------|
+| **Code-first config** | Define content types in TypeScript with full type inference |
+| **UI-defined config** | Create and modify content types through the admin interface |
+| **CMS Client** | Programmatic access via `createCmsClient` for custom queries and mutations |
+| **Admin API** | Pre-built functions via `defineAdminAPI` that power the admin UI |
+| **CLI Admin UI** | Run `npx convex-cms admin` for local development |
+| **Embedded Admin UI** | Ship the admin interface as part of your React app |
+
+Any combination of these features works together seamlessly. Pick what fits your workflow.
+
+## In Practice
+
+**Full control over the editorial experience?**  
+Code-first config + CMS Client. You define the schema in TypeScript and build exactly the UI you want.
+
+**Ship fast with a ready-made admin?**  
+Code-first config + Admin API + Embedded Admin UI. Type-safe schemas with a working admin interface out of the box.
+
+**Content team needs to modify schemas without deploys?**  
+UI-defined config + Admin API + Embedded Admin UI. Non-developers can add fields and content types.
+
+**Automated content pipelines?**  
+CMS Client + agent tools. 23 pre-built tools for AI-driven workflows.
+
 ## What's Included
 
 ### 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
-- **Content versioning** — Snapshots, comparison, and rollback
-- **Scheduled publishing** — Convex scheduler integration for future publish dates
+- **13 field types.** text, richText, number, boolean, date, datetime, select, multiSelect, reference, media, json, tags, category
+- **Publishing workflows.** Draft → scheduled → published with version history
+- **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
+- **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
+- **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
-- **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
+- **RBAC.** 4 built-in roles + custom roles with fine-grained permissions
+- **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
+- **Pre-built React interface.** CLI mode for development, embeddable for production
+- **Visual content editing.** Rich text, media picker, reference selector
 
 ## Admin UI Modes
 

package/admin/src/components/ContentEntryEditor.tsx

@@ -95,7 +95,7 @@ export interface ContentType {
 
 export interface ContentEntry {
   _id: string
-  contentTypeId: string
+  contentTypeName: string
   slug: string
   status: 'draft' | 'published' | 'scheduled' | 'archived'
   data: Record<string, unknown>
@@ -645,7 +645,7 @@ export function ContentEntryEditor({
           })) as ContentEntry
         } else {
           savedEntry = (await createEntry({
-            contentTypeId: contentType._id,
+            contentTypeName: contentType.name,
             data: dataForBackend,
           })) as ContentEntry
         }

package/admin/src/components/ContentTypeFormModal.tsx

@@ -32,6 +32,7 @@ import {
 	List,
 	Tag,
 	FolderOpen,
+	Code2,
 } from "lucide-react";
 import { cn } from "~/lib/cn";
 import { BreakingChangesWarningDialog } from "./BreakingChangesWarningDialog";
@@ -139,7 +140,7 @@ interface ContentTypeFormModalProps {
 	onClose: () => void;
 	onCreated?: (contentType: unknown) => void;
 	onUpdated?: (contentType: unknown) => void;
-	contentType?: ContentType | null;
+	contentType?: (ContentType & { source?: "code" | "database" }) | null;
 }
 
 function generateMachineName(displayName: string): string {
@@ -164,6 +165,8 @@ export function ContentTypeFormModal({
 	contentType,
 }: ContentTypeFormModalProps) {
 	const isEditing = !!contentType;
+	const isCodeDefined = contentType?.source === "code";
+	const isReadOnly = isCodeDefined;
 
 	const [displayName, setDisplayName] = useState("");
 	const [machineName, setMachineName] = useState("");
@@ -512,34 +515,62 @@ export function ContentTypeFormModal({
 			<CmsDialog
 				open={isOpen}
 				onOpenChange={(open) => !open && handleClose()}
-				title={isEditing ? "Edit Content Type" : "Create Content Type"}
+				title={
+					isCodeDefined
+						? "View Content Type"
+						: isEditing
+							? "Edit Content Type"
+							: "Create Content Type"
+				}
 				size="2xl"
 				footer={
-					<>
-						<CmsButton
-							variant="outline"
-							onClick={handleClose}
-							disabled={isSubmitting}
-						>
-							Cancel
-						</CmsButton>
-						<CmsButton
-							variant="primary"
-							onClick={handleSubmit}
-							disabled={validationErrors.length > 0}
-							loading={isSubmitting}
-							data-testid={
-								isEditing
-									? "update-content-type-submit"
-									: "create-content-type-submit"
-							}
-						>
-							{isEditing ? "Save Changes" : "Create Content Type"}
+					isReadOnly ? (
+						<CmsButton variant="outline" onClick={handleClose}>
+							Close
 						</CmsButton>
-					</>
+					) : (
+						<>
+							<CmsButton
+								variant="outline"
+								onClick={handleClose}
+								disabled={isSubmitting}
+							>
+								Cancel
+							</CmsButton>
+							<CmsButton
+								variant="primary"
+								onClick={handleSubmit}
+								disabled={validationErrors.length > 0}
+								loading={isSubmitting}
+								data-testid={
+									isEditing
+										? "update-content-type-submit"
+										: "create-content-type-submit"
+								}
+							>
+								{isEditing ? "Save Changes" : "Create Content Type"}
+							</CmsButton>
+						</>
+					)
 				}
 			>
 				<form onSubmit={handleSubmit} className="space-y-6">
+					{isCodeDefined && (
+						<div className="flex items-start gap-3 rounded-lg border border-violet-200 bg-violet-50 p-3">
+							<Code2 className="mt-0.5 size-5 shrink-0 text-violet-600" />
+							<div className="space-y-1">
+								<p className="text-sm font-medium text-violet-900">
+									Managed by Code
+								</p>
+								<p className="text-sm text-violet-700">
+									This content type is defined in your codebase and cannot be
+									edited through the admin interface. To make changes, update
+									the definition in your code.
+								</p>
+							</div>
+						</div>
+					)}
+
 					{/* Basic Info Section */}
 					<div className="space-y-4">
 						<h4 className="text-sm font-semibold text-foreground">
@@ -555,8 +586,8 @@ export function ContentTypeFormModal({
 								value={displayName}
 								onChange={(e) => handleDisplayNameChange(e.target.value)}
 								placeholder="e.g., Blog Post"
-								disabled={isSubmitting}
-								autoFocus
+								disabled={isSubmitting || isReadOnly}
+								autoFocus={!isReadOnly}
 								data-testid="display-name-input"
 							/>
 						</div>
@@ -570,7 +601,7 @@ export function ContentTypeFormModal({
 								value={machineName}
 								onChange={(e) => handleMachineNameChange(e.target.value)}
 								placeholder="e.g., blog_post"
-								disabled={isSubmitting || isEditing}
+								disabled={isSubmitting || isEditing || isReadOnly}
 								className={cn(
 									!isValidMachineName(machineName) &&
 										machineName &&
@@ -592,7 +623,7 @@ export function ContentTypeFormModal({
 								value={description}
 								onChange={(e) => setDescription(e.target.value)}
 								placeholder="Optional description of this content type"
-								disabled={isSubmitting}
+								disabled={isSubmitting || isReadOnly}
 								rows={2}
 							/>
 						</div>
@@ -602,7 +633,7 @@ export function ContentTypeFormModal({
 								id="singleton"
 								checked={singleton}
 								onCheckedChange={(checked) => setSingleton(checked as boolean)}
-								disabled={isSubmitting}
+								disabled={isSubmitting || isReadOnly}
 							/>
 							<Label htmlFor="singleton" className="cursor-pointer">
 								Singleton (only one entry allowed)
@@ -614,17 +645,19 @@ export function ContentTypeFormModal({
 					<div className="space-y-4">
 						<div className="flex items-center justify-between">
 							<h4 className="text-sm font-semibold text-foreground">Fields</h4>
-							<CmsButton
-								type="button"
-								variant="secondary"
-								size="sm"
-								onClick={addField}
-								disabled={isSubmitting}
-								data-testid="add-field-button"
-							>
-								<Plus className="size-3.5" />
-								Add Field
-							</CmsButton>
+							{!isReadOnly && (
+								<CmsButton
+									type="button"
+									variant="secondary"
+									size="sm"
+									onClick={addField}
+									disabled={isSubmitting}
+									data-testid="add-field-button"
+								>
+									<Plus className="size-3.5" />
+									Add Field
+								</CmsButton>
+							)}
 						</div>
 
 						<div className="space-y-2">
@@ -632,41 +665,46 @@ export function ContentTypeFormModal({
 								<div
 									key={index}
 									className={cn(
-										"flex cursor-pointer items-center gap-2 rounded-lg border p-2 transition-colors hover:bg-muted/50",
+										"flex items-center gap-2 rounded-lg border p-2 transition-colors",
+										!isReadOnly && "cursor-pointer hover:bg-muted/50",
 										activeFieldIndex === index && "border-primary bg-primary/5",
 									)}
 									onClick={() => {
-										setActiveFieldIndex(index);
-										setShowFieldEditor(true);
+										if (!isReadOnly) {
+											setActiveFieldIndex(index);
+											setShowFieldEditor(true);
+										}
 									}}
 									data-testid={`field-item-${index}`}
 								>
-									<div className="flex flex-col gap-0.5">
-										{index > 0 && (
-											<button
-												type="button"
-												onClick={(e) => {
-													e.stopPropagation();
-													moveField(index, index - 1);
-												}}
-												className="rounded p-0.5 text-muted-foreground hover:bg-muted hover:text-foreground"
-											>
-												<ChevronUp className="size-3" />
-											</button>
-										)}
-										{index < fields.length - 1 && (
-											<button
-												type="button"
-												onClick={(e) => {
-													e.stopPropagation();
-													moveField(index, index + 1);
-												}}
-												className="rounded p-0.5 text-muted-foreground hover:bg-muted hover:text-foreground"
-											>
-												<ChevronDown className="size-3" />
-											</button>
-										)}
-									</div>
+									{!isReadOnly && (
+										<div className="flex flex-col gap-0.5">
+											{index > 0 && (
+												<button
+													type="button"
+													onClick={(e) => {
+														e.stopPropagation();
+														moveField(index, index - 1);
+													}}
+													className="rounded p-0.5 text-muted-foreground hover:bg-muted hover:text-foreground"
+												>
+													<ChevronUp className="size-3" />
+												</button>
+											)}
+											{index < fields.length - 1 && (
+												<button
+													type="button"
+													onClick={(e) => {
+														e.stopPropagation();
+														moveField(index, index + 1);
+													}}
+													className="rounded p-0.5 text-muted-foreground hover:bg-muted hover:text-foreground"
+												>
+													<ChevronDown className="size-3" />
+												</button>
+											)}
+										</div>
+									)}
 
 									<div className="flex size-8 items-center justify-center rounded bg-muted text-muted-foreground">
 										{FIELD_TYPE_INFO[field.type].icon}
@@ -682,23 +720,25 @@ export function ContentTypeFormModal({
 										</p>
 									</div>
 
-									<button
-										type="button"
-										onClick={(e) => {
-											e.stopPropagation();
-											removeField(index);
-										}}
-										disabled={isSubmitting || fields.length === 1}
-										className="rounded p-1 text-muted-foreground transition-colors hover:bg-destructive/10 hover:text-destructive disabled:opacity-50"
-									>
-										<X className="size-4" />
-									</button>
+									{!isReadOnly && (
+										<button
+											type="button"
+											onClick={(e) => {
+												e.stopPropagation();
+												removeField(index);
+											}}
+											disabled={isSubmitting || fields.length === 1}
+											className="rounded p-1 text-muted-foreground transition-colors hover:bg-destructive/10 hover:text-destructive disabled:opacity-50"
+										>
+											<X className="size-4" />
+										</button>
+									)}
 								</div>
 							))}
 						</div>
 
-						{/* Field Editor Panel */}
-						{showFieldEditor && activeField && activeFieldIndex !== null && (
+						{/* Field Editor Panel - hidden in read-only mode */}
+						{!isReadOnly && showFieldEditor && activeField && activeFieldIndex !== null && (
 							<div
 								className="rounded-lg border bg-muted/30 p-4"
 								data-testid="field-editor"

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

@@ -113,7 +113,7 @@ export function ReferenceField({
     api.admin.listEntries,
     showPicker
       ? {
-          contentTypeId: contentTypeFilter || undefined,
+          contentTypeName: contentTypeFilter || undefined,
           search: searchQuery || undefined,
           paginationOpts: { numItems: 50, cursor: null },
         }
@@ -124,15 +124,15 @@ export function ReferenceField({
     if (!entriesResult?.page) return []
     if (allowedContentTypes.length === 0) return entriesResult.page
 
-    const allowedIds = filteredContentTypes.map((ct) => ct._id)
+    const allowedNames = filteredContentTypes.map((ct) => ct.name)
     return entriesResult.page.filter((entry) =>
-      allowedIds.includes(entry.contentTypeId)
+      allowedNames.includes(entry.contentTypeName)
     )
   }, [entriesResult?.page, allowedContentTypes, filteredContentTypes])
 
-  const getContentTypeName = useCallback(
-    (contentTypeId: string) => {
-      const ct = contentTypes?.page?.find((c) => c._id === contentTypeId)
+  const getContentTypeDisplayName = useCallback(
+    (contentTypeName: string) => {
+      const ct = contentTypes?.page?.find((c) => c.name === contentTypeName)
       return ct?.displayName || ct?.name || 'Unknown'
     },
     [contentTypes?.page]
@@ -177,7 +177,7 @@ export function ReferenceField({
       data?: Record<string, unknown>
       slug?: string
       status: string
-      contentTypeId: string
+      contentTypeName: string
     },
     showRemove = true
   ) => (
@@ -194,7 +194,7 @@ export function ReferenceField({
         </p>
         <div className="flex items-center gap-2">
           <span className="text-xs text-muted-foreground">
-            {getContentTypeName(entry.contentTypeId)}
+            {getContentTypeDisplayName(entry.contentTypeName)}
           </span>
           <CmsStatusBadge status={entry.status as ContentStatus} />
         </div>
@@ -329,7 +329,7 @@ export function ReferenceField({
                           </p>
                           <div className="flex items-center gap-2">
                             <span className="text-xs text-muted-foreground">
-                              {getContentTypeName(entry.contentTypeId)}
+                              {getContentTypeDisplayName(entry.contentTypeName)}
                             </span>
                             <Badge
                               variant="secondary"

package/admin/src/pages/ContentPage.tsx

@@ -39,19 +39,11 @@ import { CmsAdminApi } from "~/embed/contexts/ApiContext";
 
 type ContentType = {
   _id: string;
+  name: string;
   displayName: string;
   titleField?: string;
 };
 
-type Entry = {
-  _id: string;
-  contentTypeId: string;
-  slug?: string;
-  status: string;
-  data: Record<string, unknown>;
-  _creationTime: number;
-};
-
 export interface ContentPageProps {
   api: CmsAdminApi
   navigation: AdminNavigation;
@@ -70,12 +62,12 @@ export function ContentPage({ api, navigation }: ContentPageProps) {
   const isLoadingContentTypes = contentTypesResult === undefined;
 
   const entriesResult = useQuery(api.listEntries, {
-    contentTypeId: selectedTypeId || undefined,
+    contentTypeName: selectedTypeId || undefined,
     status: selectedStatus || undefined,
     search: searchQuery.trim() || undefined,
     paginationOpts: { numItems: 50, cursor: null },
   });
-  const entries: Entry[] = entriesResult?.page ?? [];
+  const entries = entriesResult?.page ?? [];
   const isLoadingEntries = entriesResult === undefined;
 
   const isLoading = isLoadingContentTypes || isLoadingEntries;
@@ -84,16 +76,16 @@ export function ContentPage({ api, navigation }: ContentPageProps) {
     navigation.navigateToNewEntry(contentTypeId);
   };
 
-  const getContentTypeName = (contentTypeId: string) => {
-    const type = contentTypes.find((t) => t._id === contentTypeId);
-    return type?.displayName ?? "Unknown";
+  const getContentTypeDisplayName = (contentTypeName: string) => {
+    const type = contentTypes.find((t) => t.name === contentTypeName);
+    return type?.displayName ?? contentTypeName;
   };
 
   const getEntryTitle = (
     entry: { data: Record<string, unknown> },
-    contentTypeId: string
+    contentTypeName: string
   ) => {
-    const type = contentTypes.find((t) => t._id === contentTypeId);
+    const type = contentTypes.find((t) => t.name === contentTypeName);
     const titleField = type?.titleField ?? "title";
     const title = entry.data[titleField];
     return typeof title === "string" && title ? title : "Untitled";
@@ -291,7 +283,7 @@ export function ContentPage({ api, navigation }: ContentPageProps) {
                       onCheckedChange={(checked) =>
                         handleSelectItem(entry._id, checked as boolean)
                       }
-                      aria-label={`Select ${getEntryTitle(entry, entry.contentTypeId)}`}
+                      aria-label={`Select ${getEntryTitle(entry, entry.contentTypeName)}`}
                     />
                   </td>
                   <td className="p-3">
@@ -301,7 +293,7 @@ export function ContentPage({ api, navigation }: ContentPageProps) {
                       className="block text-left"
                     >
                       <span className="font-medium text-foreground hover:text-primary">
-                        {getEntryTitle(entry, entry.contentTypeId)}
+                        {getEntryTitle(entry, entry.contentTypeName)}
                       </span>
                       <span className="block text-xs text-muted-foreground">
                         {entry.slug}
@@ -309,7 +301,7 @@ export function ContentPage({ api, navigation }: ContentPageProps) {
                     </button>
                   </td>
                   <td className="p-3 text-sm text-muted-foreground">
-                    {getContentTypeName(entry.contentTypeId)}
+                    {getContentTypeDisplayName(entry.contentTypeName)}
                   </td>
                   <td className="p-3">
                     <CmsStatusBadge status={entry.status as ContentStatus} />