convex-cms 0.0.1

package/src/client/argTypes.ts

@@ -0,0 +1,316 @@
+/**
+ * Derived argument types using `Infer<>` and `StringifyIds<>` for API boundary serialization.
+ */
+
+import type { Infer } from "convex/values";
+import type {
+	StringifyIds,
+	ContentType,
+	MediaVariantWithUrl,
+} from "../component/documentTypes.js";
+import * as validators from "../component/validators.js";
+
+// =============================================================================
+// Content Type Arguments
+// =============================================================================
+
+export type CreateContentTypeArgs = StringifyIds<Infer<typeof validators.createContentTypeArgs>>;
+
+type UpdateContentTypeArgsBase = StringifyIds<Infer<typeof validators.updateContentTypeArgs>>;
+
+/** Extends base validator type with wrapper-specific `force` field for breaking changes */
+export interface UpdateContentTypeArgs extends UpdateContentTypeArgsBase {
+	force?: boolean;
+}
+
+export type DeleteContentTypeArgs = StringifyIds<Infer<typeof validators.deleteContentTypeArgs>>;
+
+// =============================================================================
+// Content Entry Arguments
+// =============================================================================
+
+export type CreateContentEntryArgs = StringifyIds<Infer<typeof validators.createContentEntryArgs>>;
+export type UpdateContentEntryArgs = StringifyIds<Infer<typeof validators.updateContentEntryArgs>>;
+export type DeleteContentEntryArgs = StringifyIds<Infer<typeof validators.deleteContentEntryArgs>>;
+export type PublishEntryArgs = StringifyIds<Infer<typeof validators.publishEntryArgs>>;
+export type ScheduleEntryArgs = StringifyIds<Infer<typeof validators.scheduleEntryArgs>>;
+export type UnpublishEntryArgs = StringifyIds<Infer<typeof validators.unpublishEntryArgs>>;
+export type DuplicateEntryArgs = StringifyIds<Infer<typeof validators.duplicateContentEntryArgs>>;
+
+// =============================================================================
+// Version Arguments
+// =============================================================================
+
+export type GetVersionHistoryArgs = StringifyIds<Infer<typeof validators.getVersionHistoryArgs>>;
+export type GetVersionArgs = StringifyIds<Infer<typeof validators.getVersionArgs>>;
+export type RollbackVersionArgs = StringifyIds<Infer<typeof validators.rollbackVersionArgs>>;
+export type CompareVersionsArgs = StringifyIds<Infer<typeof validators.compareVersionsArgs>>;
+
+// =============================================================================
+// Media Asset Arguments
+// =============================================================================
+
+export type CreateMediaAssetArgs = StringifyIds<Infer<typeof validators.createMediaAssetArgs>>;
+export type UpdateMediaAssetArgs = StringifyIds<Infer<typeof validators.updateMediaAssetArgs>>;
+export type DeleteMediaAssetArgs = StringifyIds<Infer<typeof validators.deleteMediaAssetArgs>>;
+export type RestoreMediaAssetArgs = StringifyIds<Infer<typeof validators.restoreMediaAssetArgs>>;
+
+// =============================================================================
+// Media Folder Arguments
+// =============================================================================
+
+export type CreateMediaFolderArgs = StringifyIds<Infer<typeof validators.createMediaFolderArgs>>;
+export type UpdateMediaFolderArgs = StringifyIds<Infer<typeof validators.updateMediaFolderArgs>>;
+export type MoveFolderArgs = StringifyIds<Infer<typeof validators.moveFolderArgs>>;
+export type DeleteMediaFolderArgs = StringifyIds<Infer<typeof validators.deleteMediaFolderArgs>>;
+export type RestoreMediaFolderArgs = StringifyIds<Infer<typeof validators.restoreMediaFolderArgs>>;
+export type MoveMediaAssetsArgs = StringifyIds<Infer<typeof validators.moveMediaAssetsArgs>>;
+
+// =============================================================================
+// Media Variant Arguments
+// =============================================================================
+
+export type CreateMediaVariantArgs = StringifyIds<Infer<typeof validators.createMediaVariantArgs>>;
+export type RequestVariantGenerationArgs = StringifyIds<Infer<typeof validators.requestVariantGenerationArgs>>;
+export type UpdateVariantStatusArgs = StringifyIds<Infer<typeof validators.updateVariantStatusArgs>>;
+export type DeleteMediaVariantArgs = StringifyIds<Infer<typeof validators.deleteMediaVariantArgs>>;
+export type DeleteAssetVariantsArgs = StringifyIds<Infer<typeof validators.deleteAssetVariantsArgs>>;
+export type GetMediaVariantArgs = StringifyIds<Infer<typeof validators.getMediaVariantArgs>>;
+export type ListMediaVariantsArgs = StringifyIds<Infer<typeof validators.listMediaVariantsArgs>>;
+export type GetBestVariantArgs = StringifyIds<Infer<typeof validators.getBestVariantArgs>>;
+
+// =============================================================================
+// Bulk Operation Arguments
+// =============================================================================
+
+export type BulkPublishArgs = StringifyIds<Infer<typeof validators.bulkPublishArgs>>;
+export type BulkUnpublishArgs = StringifyIds<Infer<typeof validators.bulkUnpublishArgs>>;
+export type BulkDeleteArgs = StringifyIds<Infer<typeof validators.bulkDeleteArgs>>;
+export type BulkUpdateArgs = StringifyIds<Infer<typeof validators.bulkUpdateArgs>>;
+
+// =============================================================================
+// Trash Operation Arguments
+// =============================================================================
+
+export type UpdateTrashConfigArgs = StringifyIds<Infer<typeof validators.updateTrashConfigArgs>>;
+export type ListTrashArgs = StringifyIds<Infer<typeof validators.listTrashArgs>>;
+export type EmptyTrashArgs = StringifyIds<Infer<typeof validators.emptyTrashArgs>>;
+
+// =============================================================================
+// Content Lock Arguments
+// =============================================================================
+
+export type AcquireLockArgs = StringifyIds<Infer<typeof validators.acquireLockArgs>>;
+export type ReleaseLockArgs = StringifyIds<Infer<typeof validators.releaseLockArgs>>;
+export type ForceReleaseLockArgs = StringifyIds<Infer<typeof validators.forceReleaseLockArgs>>;
+export type RenewLockArgs = StringifyIds<Infer<typeof validators.renewLockArgs>>;
+export type CheckLockArgs = StringifyIds<Infer<typeof validators.checkLockArgs>>;
+export type ListLockedEntriesArgs = StringifyIds<Infer<typeof validators.listLockedEntriesArgs>>;
+
+// =============================================================================
+// Query Arguments
+// =============================================================================
+
+export type ContentQueryArgs = StringifyIds<Infer<typeof validators.contentQueryArgs>>;
+export type MediaQueryArgs = StringifyIds<Infer<typeof validators.mediaQueryArgs>>;
+export type ListMediaAssetsArgsFromValidator = StringifyIds<Infer<typeof validators.listMediaAssetsArgs>>;
+
+// =============================================================================
+// Wrapper-Specific Argument Types (no direct validator equivalents)
+// =============================================================================
+
+import type {
+	ContentQueryOptions,
+	MediaQueryOptions,
+	VariantType,
+	PaginationOpts,
+} from "./types.js";
+
+export interface GetContentTypeArgs {
+	id?: string;
+	name?: string;
+	includeDeleted?: boolean;
+}
+
+export interface ListContentTypesArgs {
+	isActive?: boolean;
+	includeDeleted?: boolean;
+	sortBy?: "name" | "createdAt";
+	sortDirection?: "asc" | "desc";
+	paginationOpts?: PaginationOpts;
+}
+
+export interface GetContentEntryArgs {
+	id: string;
+}
+
+export interface GetContentEntryBySlugArgs {
+	contentTypeId?: string;
+	contentTypeName?: string;
+	slug: string;
+	locale?: string;
+}
+
+export type ListContentEntriesArgs = ContentQueryOptions;
+
+export interface RestoreEntryArgs {
+	id: string;
+	restoredBy?: string;
+}
+
+export interface BulkRestoreArgs {
+	ids: string[];
+	restoredBy?: string;
+}
+
+export interface GetMediaAssetArgs {
+	id: string;
+}
+
+export type ListMediaAssetsArgs = MediaQueryOptions;
+
+export interface GetMediaFolderArgs {
+	id: string;
+}
+
+export interface ListMediaFoldersArgs {
+	parentId?: string;
+	includeDeleted?: boolean;
+}
+
+export interface GenerateUploadUrlArgs {
+	maxFileSize?: number;
+	allowedMimeTypes?: string[];
+	requestedBy?: string;
+}
+
+export interface FindMediaAssetReferencesArgs {
+	id: string;
+	limit?: number;
+}
+
+export interface GetMediaFolderByPathArgs {
+	path: string;
+	includeDeleted?: boolean;
+}
+
+export interface GetFolderTreeArgs {
+	includeDeleted?: boolean;
+}
+
+export interface GenerateFromPresetsArgs {
+	assetId: string;
+	presets: string[];
+	requestedBy?: string;
+}
+
+// =============================================================================
+// Result Types
+// =============================================================================
+
+export interface BreakingChange {
+	type:
+		| "FIELD_REMOVED"
+		| "FIELD_TYPE_CHANGED"
+		| "FIELD_MADE_REQUIRED"
+		| "SELECT_OPTIONS_REMOVED"
+		| "REFERENCE_TYPES_RESTRICTED"
+		| "VALIDATION_TIGHTENED";
+	fieldName: string;
+	message: string;
+	affectedEntriesCount: number;
+}
+
+export interface UpdateContentTypeResult extends ContentType {
+	breakingChanges?: BreakingChange[];
+}
+
+export interface DeleteContentTypeResult {
+	success: boolean;
+	deletedId: string;
+	deletedEntriesCount: number;
+	deletedVersionsCount: number;
+	wasHardDelete: boolean;
+}
+
+export interface BulkOperationItemResult {
+	id: string;
+	success: boolean;
+	error?: string;
+}
+
+export interface BulkOperationResult {
+	total: number;
+	succeeded: number;
+	failed: number;
+	results: BulkOperationItemResult[];
+}
+
+export interface GenerateUploadUrlResult {
+	uploadUrl: string;
+	expiresAt: number;
+	maxFileSize: number;
+	allowedMimeTypes?: string[];
+}
+
+export interface MediaAssetReference {
+	entryId: string;
+	slug: string;
+	contentTypeName: string;
+	fields: string[];
+}
+
+export interface GenerateVariantsResult {
+	total: number;
+	succeeded: number;
+	failed: number;
+	results: {
+		preset: string;
+		success: boolean;
+		variantId?: string;
+		error?: string;
+	}[];
+}
+
+export interface SrcsetEntry {
+	url: string;
+	descriptor: string;
+	width: number;
+	format: string;
+}
+
+export interface ResponsiveSrcsetResult {
+	src: string | null;
+	srcset: string;
+	entries: SrcsetEntry[];
+	sizes?: string;
+}
+
+export interface VariantPreset {
+	name: string;
+	variantType: VariantType;
+	width?: number;
+	height?: number;
+	format: string;
+	quality?: number;
+	description?: string;
+}
+
+export interface AssetWithVariants {
+	original: {
+		_id: string;
+		_creationTime: number;
+		name: string;
+		mimeType: string;
+		size: number;
+		width?: number;
+		height?: number;
+		url: string | null;
+	};
+	variants: MediaVariantWithUrl[];
+	variantsByType: {
+		thumbnail?: MediaVariantWithUrl;
+		responsive: MediaVariantWithUrl[];
+		format: MediaVariantWithUrl[];
+	};
+}

package/src/client/field-types.ts

@@ -0,0 +1,187 @@
+/**
+ * Custom Field Type Registry
+ *
+ * Allows defining custom field types beyond the 13 built-in types.
+ * Custom field types store as 'json' in the database but have their own
+ * validation, default values, and UI rendering through the registry.
+ */
+
+import { v, type Validator } from "convex/values";
+
+export interface FieldTypeDefinition<T = unknown> {
+  name: string;
+  displayName: string;
+  description?: string;
+  icon?: string;
+  validator: Validator<T, "required", string>;
+  defaultValue?: T;
+  extractSearchText?: (value: T) => string;
+  validate?: (value: T, options?: Record<string, unknown>) => FieldValidationResult;
+  optionsSchema?: Record<string, unknown>;
+}
+
+export interface FieldValidationResult {
+  valid: boolean;
+  error?: string;
+}
+
+const fieldTypeRegistry = new Map<string, FieldTypeDefinition>();
+
+const BUILT_IN_TYPES: FieldTypeDefinition[] = [
+  { name: "text", displayName: "Text", icon: "Type", validator: v.string(), defaultValue: "" },
+  {
+    name: "richText",
+    displayName: "Rich Text",
+    icon: "FileText",
+    validator: v.string(),
+    defaultValue: "",
+  },
+  { name: "number", displayName: "Number", icon: "Hash", validator: v.number(), defaultValue: 0 },
+  {
+    name: "boolean",
+    displayName: "Boolean",
+    icon: "ToggleLeft",
+    validator: v.boolean(),
+    defaultValue: false,
+  },
+  {
+    name: "date",
+    displayName: "Date",
+    icon: "Calendar",
+    validator: v.union(v.string(), v.null()),
+    defaultValue: null,
+  },
+  {
+    name: "datetime",
+    displayName: "Date & Time",
+    icon: "Clock",
+    validator: v.union(v.string(), v.null()),
+    defaultValue: null,
+  },
+  {
+    name: "reference",
+    displayName: "Reference",
+    icon: "Link",
+    validator: v.union(v.string(), v.array(v.string()), v.null()),
+    defaultValue: null,
+  },
+  {
+    name: "media",
+    displayName: "Media",
+    icon: "Image",
+    validator: v.union(v.string(), v.null()),
+    defaultValue: null,
+  },
+  { name: "json", displayName: "JSON", icon: "Braces", validator: v.any(), defaultValue: null },
+  {
+    name: "select",
+    displayName: "Select",
+    icon: "ChevronDown",
+    validator: v.string(),
+    defaultValue: "",
+  },
+  {
+    name: "multiSelect",
+    displayName: "Multi Select",
+    icon: "CheckSquare",
+    validator: v.array(v.string()),
+    defaultValue: [],
+  },
+  {
+    name: "tags",
+    displayName: "Tags",
+    icon: "Tags",
+    validator: v.array(v.string()),
+    defaultValue: [],
+  },
+  {
+    name: "category",
+    displayName: "Category",
+    icon: "Folder",
+    validator: v.union(v.string(), v.array(v.string()), v.null()),
+    defaultValue: null,
+  },
+];
+
+BUILT_IN_TYPES.forEach((type) => fieldTypeRegistry.set(type.name, type));
+
+const BUILT_IN_NAMES = new Set(BUILT_IN_TYPES.map((t) => t.name));
+
+/**
+ * Define a custom field type.
+ *
+ * @example
+ * const addressField = defineFieldType({
+ *   name: "address",
+ *   displayName: "Address",
+ *   icon: "MapPin",
+ *   validator: v.object({
+ *     street: v.string(),
+ *     city: v.string(),
+ *     postalCode: v.string(),
+ *     country: v.string(),
+ *   }),
+ *   defaultValue: { street: "", city: "", postalCode: "", country: "" },
+ *   extractSearchText: (value) => `${value.street} ${value.city}`,
+ * });
+ */
+export function defineFieldType<T>(definition: FieldTypeDefinition<T>): FieldTypeDefinition<T> {
+  if (!/^[a-z][a-zA-Z0-9]*$/.test(definition.name)) {
+    throw new Error(
+      `Field type name "${definition.name}" must be camelCase starting with lowercase letter`
+    );
+  }
+  if (BUILT_IN_NAMES.has(definition.name)) {
+    throw new Error(`Cannot redefine built-in field type "${definition.name}"`);
+  }
+  return Object.freeze(definition);
+}
+
+export function registerFieldType(definition: FieldTypeDefinition): void {
+  if (BUILT_IN_NAMES.has(definition.name)) {
+    throw new Error(`Cannot redefine built-in field type "${definition.name}"`);
+  }
+  fieldTypeRegistry.set(definition.name, definition);
+}
+
+export function registerFieldTypes(definitions: FieldTypeDefinition[]): void {
+  for (const definition of definitions) {
+    registerFieldType(definition);
+  }
+}
+
+export function getFieldTypeDefinition(name: string): FieldTypeDefinition | undefined {
+  return fieldTypeRegistry.get(name);
+}
+
+export function getAllFieldTypes(): FieldTypeDefinition[] {
+  return Array.from(fieldTypeRegistry.values());
+}
+
+export function getCustomFieldTypes(): FieldTypeDefinition[] {
+  return Array.from(fieldTypeRegistry.values()).filter((t) => !BUILT_IN_NAMES.has(t.name));
+}
+
+export function isBuiltInFieldType(name: string): boolean {
+  return BUILT_IN_NAMES.has(name);
+}
+
+export function isCustomFieldType(name: string): boolean {
+  return fieldTypeRegistry.has(name) && !BUILT_IN_NAMES.has(name);
+}
+
+export function hasFieldType(name: string): boolean {
+  return fieldTypeRegistry.has(name);
+}
+
+export function getFieldTypeDefaultValue(name: string): unknown {
+  const type = fieldTypeRegistry.get(name);
+  return type?.defaultValue;
+}
+
+export function getFieldTypeIcon(name: string): string | undefined {
+  const type = fieldTypeRegistry.get(name);
+  return type?.icon;
+}
+
+export { BUILT_IN_TYPES };