convex-cms 0.0.1

package/dist/client/schema/index.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Code-Only Schema System
+ *
+ * This module provides type-safe content type definitions using Convex validators.
+ * Types are automatically inferred via Convex's native `Infer<typeof validator>` pattern.
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { v, Infer } from "convex/values";
+ * import { defineContentType, InferContentType } from "@convex-cms/core";
+ *
+ * // Define a content type with a Convex validator
+ * export const blogPost = defineContentType({
+ *   name: "blog_post",
+ *   validator: v.object({
+ *     title: v.string(),
+ *     content: v.string(),
+ *     publishedAt: v.optional(v.number()),
+ *   }),
+ *   meta: {
+ *     displayName: "Blog Post",
+ *     titleField: "title",
+ *   },
+ * });
+ *
+ * // Type is automatically inferred
+ * type BlogPostData = InferContentType<typeof blogPost>;
+ * // { title: string; content: string; publishedAt?: number }
+ * ```
+ *
+ * ## Creating a Schema
+ *
+ * ```typescript
+ * import { createContentSchema, InferSchema } from "@convex-cms/core";
+ *
+ * // Combine multiple content types into a schema
+ * export const contentSchema = createContentSchema({
+ *   blogPost,
+ *   author,
+ *   product,
+ * });
+ *
+ * // Infer all types at once
+ * export type ContentTypes = InferSchema<typeof contentSchema.definitions>;
+ * // {
+ * //   blog_post: { title: string; content: string; ... };
+ * //   author: { name: string; bio?: string; ... };
+ * //   product: { name: string; price: number; ... };
+ * // }
+ * ```
+ *
+ * ## Using with CMS Client
+ *
+ * ```typescript
+ * import { createCmsClient } from "@convex-cms/core";
+ * import { components } from "./_generated/api";
+ * import { contentSchema } from "./schema";
+ *
+ * // Create a schema-aware CMS client
+ * export const cms = createCmsClient(components.convexCms, {
+ *   schema: contentSchema,
+ *   // ... other options
+ * });
+ *
+ * // Now get() returns typed data
+ * const post = await cms.contentEntries.get<"blog_post">(ctx, id);
+ * post.data.title    // ✅ string - fully typed
+ * post.data.typo     // ❌ Error: Property 'typo' does not exist
+ * ```
+ *
+ * @module
+ */
+export { defineContentType, createContentSchema, toFieldDefinitions } from "./defineContentType.js";
+export type { ContentTypeConfig, ContentTypeDefinition, ContentTypeMeta, FieldMeta, FieldRenderAs, } from "./types.js";
+export type { InferContentType, InferSchema, ContentSchema, SchemaContentTypeNames, SchemaContentType, ContentTypeFieldNames, } from "./types.js";
+export type { ContentSchemaInstance, DatabaseFieldDefinition } from "./defineContentType.js";
+export { isContentTypeDefinition } from "./types.js";
+export { createTypedCmsClient, TypedContentEntriesApiImpl } from "./typedClient.js";
+export { detectSchemaDrift, formatDriftReport, hasErrors, filterReportByContentTypes, } from "./schemaDrift.js";
+export type { DriftSeverity, DriftType, DriftIssue, DriftSummary, SchemaDriftReport, DetectDriftOptions, } from "./schemaDrift.js";
+export { generateTypesFromDatabase, generateTypesFromDefinitions, validateGeneratedCode, } from "./codegen.js";
+export type { CodegenOptions, CodegenResult, } from "./codegen.js";
+export type { TypedContentEntry, TypedPaginationResult, TypedContentEntriesApi, TypedCreateEntryOptions, TypedUpdateEntryOptions, TypedListEntriesOptions, SchemaDataType, ValidContentTypeName, HasContentType, GetContentTypeDefinition, TypedCmsClientConfig, TypedCmsClient, } from "./typedClient.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/client/schema/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/schema/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AAMH,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAOpG,YAAY,EACV,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,SAAS,EACT,aAAa,GACd,MAAM,YAAY,CAAC;AAGpB,YAAY,EACV,gBAAgB,EAChB,WAAW,EACX,aAAa,EACb,sBAAsB,EACtB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,YAAY,CAAC;AAGpB,YAAY,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAG7F,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAMrD,OAAO,EAAE,oBAAoB,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AAMpF,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,SAAS,EACT,0BAA0B,GAC3B,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EACV,aAAa,EACb,SAAS,EACT,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAM1B,OAAO,EACL,yBAAyB,EACzB,4BAA4B,EAC5B,qBAAqB,GACtB,MAAM,cAAc,CAAC;AAEtB,YAAY,EACV,cAAc,EACd,aAAa,GACd,MAAM,cAAc,CAAC;AAOtB,YAAY,EACV,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACtB,uBAAuB,EACvB,uBAAuB,EACvB,uBAAuB,EACvB,cAAc,EACd,oBAAoB,EACpB,cAAc,EACd,wBAAwB,EACxB,oBAAoB,EACpB,cAAc,GACf,MAAM,kBAAkB,CAAC"}

package/dist/client/schema/index.js

@@ -0,0 +1,92 @@
+/**
+ * Code-Only Schema System
+ *
+ * This module provides type-safe content type definitions using Convex validators.
+ * Types are automatically inferred via Convex's native `Infer<typeof validator>` pattern.
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { v, Infer } from "convex/values";
+ * import { defineContentType, InferContentType } from "@convex-cms/core";
+ *
+ * // Define a content type with a Convex validator
+ * export const blogPost = defineContentType({
+ *   name: "blog_post",
+ *   validator: v.object({
+ *     title: v.string(),
+ *     content: v.string(),
+ *     publishedAt: v.optional(v.number()),
+ *   }),
+ *   meta: {
+ *     displayName: "Blog Post",
+ *     titleField: "title",
+ *   },
+ * });
+ *
+ * // Type is automatically inferred
+ * type BlogPostData = InferContentType<typeof blogPost>;
+ * // { title: string; content: string; publishedAt?: number }
+ * ```
+ *
+ * ## Creating a Schema
+ *
+ * ```typescript
+ * import { createContentSchema, InferSchema } from "@convex-cms/core";
+ *
+ * // Combine multiple content types into a schema
+ * export const contentSchema = createContentSchema({
+ *   blogPost,
+ *   author,
+ *   product,
+ * });
+ *
+ * // Infer all types at once
+ * export type ContentTypes = InferSchema<typeof contentSchema.definitions>;
+ * // {
+ * //   blog_post: { title: string; content: string; ... };
+ * //   author: { name: string; bio?: string; ... };
+ * //   product: { name: string; price: number; ... };
+ * // }
+ * ```
+ *
+ * ## Using with CMS Client
+ *
+ * ```typescript
+ * import { createCmsClient } from "@convex-cms/core";
+ * import { components } from "./_generated/api";
+ * import { contentSchema } from "./schema";
+ *
+ * // Create a schema-aware CMS client
+ * export const cms = createCmsClient(components.convexCms, {
+ *   schema: contentSchema,
+ *   // ... other options
+ * });
+ *
+ * // Now get() returns typed data
+ * const post = await cms.contentEntries.get<"blog_post">(ctx, id);
+ * post.data.title    // ✅ string - fully typed
+ * post.data.typo     // ❌ Error: Property 'typo' does not exist
+ * ```
+ *
+ * @module
+ */
+// =============================================================================
+// Core Functions
+// =============================================================================
+export { defineContentType, createContentSchema, toFieldDefinitions } from "./defineContentType.js";
+// Runtime utilities
+export { isContentTypeDefinition } from "./types.js";
+// =============================================================================
+// Typed Client Factory
+// =============================================================================
+export { createTypedCmsClient, TypedContentEntriesApiImpl } from "./typedClient.js";
+// =============================================================================
+// Schema Drift Detection
+// =============================================================================
+export { detectSchemaDrift, formatDriftReport, hasErrors, filterReportByContentTypes, } from "./schemaDrift.js";
+// =============================================================================
+// Type Code Generation
+// =============================================================================
+export { generateTypesFromDatabase, generateTypesFromDefinitions, validateGeneratedCode, } from "./codegen.js";
+//# sourceMappingURL=index.js.map

package/dist/client/schema/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/client/schema/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AAEH,gFAAgF;AAChF,iBAAiB;AACjB,gFAAgF;AAEhF,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AA4BpG,oBAAoB;AACpB,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAErD,gFAAgF;AAChF,uBAAuB;AACvB,gFAAgF;AAEhF,OAAO,EAAE,oBAAoB,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AAEpF,gFAAgF;AAChF,yBAAyB;AACzB,gFAAgF;AAEhF,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,SAAS,EACT,0BAA0B,GAC3B,MAAM,kBAAkB,CAAC;AAW1B,gFAAgF;AAChF,uBAAuB;AACvB,gFAAgF;AAEhF,OAAO,EACL,yBAAyB,EACzB,4BAA4B,EAC5B,qBAAqB,GACtB,MAAM,cAAc,CAAC"}

package/dist/client/schema/schemaDrift.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Schema Drift Detection
+ *
+ * Compares code-defined schemas against database schemas to detect
+ * discrepancies that could cause runtime issues.
+ *
+ * @example
+ * ```typescript
+ * import { detectSchemaDrift } from "@convex-cms/core";
+ *
+ * const report = await detectSchemaDrift(ctx, cms, contentSchema);
+ *
+ * if (report.hasDrift) {
+ *   console.warn("Schema drift detected:");
+ *   console.log(report.summary);
+ *
+ *   for (const diff of report.fieldDifferences) {
+ *     console.log(`${diff.contentType}.${diff.field}: ${diff.message}`);
+ *   }
+ * }
+ * ```
+ */
+import type { ContentTypeDefinition } from "./types.js";
+import type { ContentSchemaInstance } from "./defineContentType.js";
+import type { ConvexContext } from "../wrapper.js";
+import type { CmsClient } from "../wrapper.js";
+/**
+ * Severity level for drift issues.
+ */
+export type DriftSeverity = "error" | "warning" | "info";
+/**
+ * Type of schema difference detected.
+ */
+export type DriftType = "CONTENT_TYPE_MISSING_IN_DB" | "CONTENT_TYPE_MISSING_IN_CODE" | "FIELD_MISSING_IN_DB" | "FIELD_MISSING_IN_CODE" | "FIELD_TYPE_MISMATCH" | "FIELD_REQUIRED_MISMATCH" | "FIELD_OPTIONS_MISMATCH" | "CONTENT_TYPE_METADATA_MISMATCH";
+/**
+ * A single schema drift issue.
+ */
+export interface DriftIssue {
+    /**
+     * Type of drift detected.
+     */
+    type: DriftType;
+    /**
+     * Severity level.
+     */
+    severity: DriftSeverity;
+    /**
+     * Content type name involved.
+     */
+    contentType: string;
+    /**
+     * Field name (if applicable).
+     */
+    field?: string;
+    /**
+     * Human-readable description of the issue.
+     */
+    message: string;
+    /**
+     * Expected value (from code).
+     */
+    expected?: unknown;
+    /**
+     * Actual value (from database).
+     */
+    actual?: unknown;
+}
+/**
+ * Summary statistics for the drift report.
+ */
+export interface DriftSummary {
+    /**
+     * Number of content types only in code (not in database).
+     */
+    missingInDatabase: number;
+    /**
+     * Number of content types only in database (not in code).
+     */
+    missingInCode: number;
+    /**
+     * Number of field-level differences.
+     */
+    fieldDifferences: number;
+    /**
+     * Total number of issues found.
+     */
+    totalIssues: number;
+    /**
+     * Number of error-level issues.
+     */
+    errors: number;
+    /**
+     * Number of warning-level issues.
+     */
+    warnings: number;
+}
+/**
+ * Full schema drift detection report.
+ */
+export interface SchemaDriftReport {
+    /**
+     * Whether any drift was detected.
+     */
+    hasDrift: boolean;
+    /**
+     * Summary statistics.
+     */
+    summary: DriftSummary;
+    /**
+     * All detected issues.
+     */
+    issues: DriftIssue[];
+    /**
+     * Content types defined in code but not in database.
+     */
+    missingInDatabase: string[];
+    /**
+     * Content types in database but not in code.
+     */
+    missingInCode: string[];
+    /**
+     * Timestamp when the check was performed.
+     */
+    checkedAt: number;
+}
+/**
+ * Options for drift detection.
+ */
+export interface DetectDriftOptions {
+    /**
+     * Whether to include info-level issues in the report.
+     * @default false
+     */
+    includeInfoLevel?: boolean;
+    /**
+     * Content type names to check. If not provided, checks all.
+     */
+    contentTypes?: string[];
+    /**
+     * Whether to treat missing-in-database as errors.
+     * When true, code types not in DB are errors; when false, they're warnings.
+     * @default true
+     */
+    strictMissingInDb?: boolean;
+    /**
+     * Whether to treat missing-in-code as errors.
+     * When false, DB types not in code are warnings (allows admin-created types).
+     * @default false
+     */
+    strictMissingInCode?: boolean;
+}
+/**
+ * Detects schema drift between code-defined schemas and database state.
+ *
+ * @param ctx - Convex context
+ * @param cmsClient - The CMS client to use for database queries
+ * @param schema - The code-defined content schema
+ * @param options - Detection options
+ * @returns A drift report with all detected issues
+ *
+ * @example
+ * ```typescript
+ * const report = await detectSchemaDrift(ctx, cms, contentSchema);
+ *
+ * if (report.hasDrift) {
+ *   console.error("Schema drift detected!");
+ *   console.log(`Errors: ${report.summary.errors}`);
+ *   console.log(`Warnings: ${report.summary.warnings}`);
+ *
+ *   for (const issue of report.issues) {
+ *     console.log(`[${issue.severity}] ${issue.message}`);
+ *   }
+ * }
+ * ```
+ */
+export declare function detectSchemaDrift<TSchema extends ContentSchemaInstance<Record<string, ContentTypeDefinition>>>(ctx: ConvexContext, cmsClient: CmsClient, schema: TSchema, options?: DetectDriftOptions): Promise<SchemaDriftReport>;
+/**
+ * Format a drift report as a human-readable string.
+ *
+ * @param report - The drift report to format
+ * @returns A formatted string suitable for console output
+ */
+export declare function formatDriftReport(report: SchemaDriftReport): string;
+/**
+ * Check if a drift report h errors (not just warnings).
+ *
+ * @param report - The drift report to check
+ * @returns true if there are error-level issues
+ */
+export declare function hasErrors(report: SchemaDriftReport): boolean;
+/**
+ * Filter a drift report to only include specific content types.
+ *
+ * @param report - The full drift report
+ * @param contentTypes - Content type names to include
+ * @returns A filtered report
+ */
+export declare function filterReportByContentTypes(report: SchemaDriftReport, contentTypes: string[]): SchemaDriftReport;
+//# sourceMappingURL=schemaDrift.d.ts.map

package/dist/client/schema/schemaDrift.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemaDrift.d.ts","sourceRoot":"","sources":["../../../src/client/schema/schemaDrift.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAEpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAO/C;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAEzD;;GAEG;AACH,MAAM,MAAM,SAAS,GACjB,4BAA4B,GAC5B,8BAA8B,GAC9B,qBAAqB,GACrB,uBAAuB,GACvB,qBAAqB,GACrB,yBAAyB,GACzB,wBAAwB,GACxB,gCAAgC,CAAC;AAErC;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,IAAI,EAAE,SAAS,CAAC;IAEhB;;OAEG;IACH,QAAQ,EAAE,aAAa,CAAC;IAExB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,aAAa,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,gBAAgB,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,QAAQ,EAAE,OAAO,CAAC;IAElB;;OAEG;IACH,OAAO,EAAE,YAAY,CAAC;IAEtB;;OAEG;IACH,MAAM,EAAE,UAAU,EAAE,CAAC;IAErB;;OAEG;IACH,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAE5B;;OAEG;IACH,aAAa,EAAE,MAAM,EAAE,CAAC;IAExB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IAExB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAE5B;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,SAAS,qBAAqB,CAAC,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC,EAE5E,GAAG,EAAE,aAAa,EAClB,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,OAAO,EACf,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,iBAAiB,CAAC,CAwF5B;AAyKD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAyCnE;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAE5D;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,iBAAiB,EACzB,YAAY,EAAE,MAAM,EAAE,GACrB,iBAAiB,CAoBnB"}