@vexcms/core 0.0.19 → 0.1.0-alpha.2

package/dist/media/types.d.ts

@@ -0,0 +1,332 @@
+import type { GenericDataModel, GenericMutationCtx, GenericQueryCtx } from "convex/server";
+import type { CollectionConfig, CollectionConfigInput } from "../collections";
+import type { BaseFieldMeta, ComponentHKT } from "../fields";
+import type { MediaCollectionSlug, StorageAdapterSlug } from "../types";
+/**
+ * Metadata attached to every media collection linking it to a specific storage adapter.
+ *
+ * Set by `defineMediaCollection()` and tagged onto each collection by the
+ * adapter when it processes its `mediaCollections` array. Core uses
+ * `storageAdapter` to route upload, delete, and URL operations to the
+ * correct adapter at runtime.
+ */
+export type MediaCollectionMeta = {
+    /**
+     * Which storage adapter this collection is linked to specifically. "convex" supported by default
+     */
+    storageAdapter: StorageAdapterSlug;
+};
+/**
+ * Configuration input for a `defineMediaCollection()` call.
+ *
+ * Identical to `CollectionConfigInput` except `fields` is omitted — media
+ * collections have a fixed set of system fields (`alt`, `filename`, `mimeType`,
+ * `size`, `storageId`, `deleted`, `convexUrl`, `width`, `height`) that
+ * `defineMediaCollection()` always injects. Pass extra custom fields via the
+ * `fields` override on `defineMediaCollection()`.
+ *
+ * @example
+ * ```ts
+ * const images = defineMediaCollection({
+ *   slug: "images",
+ *   labels: { singular: "Image", plural: "Images" },
+ * });
+ * ```
+ *
+ * @see {@link MediaCollectionConfig} for the resolved type after defaults are applied
+ * @see {@link file-storage-convex/src!defineMediaCollection} from `@vexcms/file-storage-convex`
+ */
+export type MediaCollectionConfigInput<TFieldMeta extends BaseFieldMeta = BaseFieldMeta, TCollectionMeta extends MediaCollectionMeta = MediaCollectionMeta, TCollectionSlug extends MediaCollectionSlug = MediaCollectionSlug, TFieldSlug extends string = string, TComponent extends ComponentHKT = ComponentHKT> = Omit<CollectionConfigInput<TFieldMeta, TCollectionMeta, TCollectionSlug, TFieldSlug, TComponent>, "fields">;
+/**
+ * Resolved media collection configuration after `defineMediaCollection()` applies system fields and defaults.
+ *
+ * Structurally identical to `CollectionConfig` — all schema generation, admin
+ * panel rendering, and query helpers work against this type. Media collections
+ * are stored in `VexConfig.mediaCollections` separately from user-defined
+ * `collections` and appear under a dedicated "Media" section in the admin panel.
+ *
+ * @see {@link MediaCollectionConfigInput} for the user-facing input type
+ * @see {@link file-storage-convex/src!defineMediaCollection} from `@vexcms/file-storage-convex`
+ */
+export type MediaCollectionConfig<TFieldMeta extends BaseFieldMeta = BaseFieldMeta, TCollectionMeta extends MediaCollectionMeta = MediaCollectionMeta, TCollectionSlug extends MediaCollectionSlug = MediaCollectionSlug, TFieldSlug extends string = string, TComponent extends ComponentHKT = ComponentHKT> = CollectionConfig<TFieldMeta, TCollectionMeta, TCollectionSlug, TFieldSlug, TComponent>;
+/**
+ * Error thrown when storage configuration is invalid.
+ *
+ * Covers: missing required fields on media collections, slug collisions
+ * (between collections and media collections, or across adapters), upload
+ * fields referencing non-existent media collections, or `upload()` used
+ * without a configured storage adapter.
+ */
+export declare class VexStorageConfigError extends Error {
+    /**
+     * @param message — Human-readable description of the configuration error.
+     */
+    constructor(message: string);
+}
+/** Protocol type for file upload methods. */
+export declare const STORAGE_ADAPTER_PROTOCOLS: {
+    readonly presignedUrl: "presigned-url";
+};
+/** Protocol type for file upload methods. */
+export type StorageAdapterProtocol = (typeof STORAGE_ADAPTER_PROTOCOLS)[keyof typeof STORAGE_ADAPTER_PROTOCOLS];
+/**
+ * Return type for `getUrl` — either a resolved URL or an error message, never both.
+ */
+export type GetUrlReturn = {
+    url: string;
+    error?: never;
+} | {
+    url?: never;
+    error: string;
+};
+/**
+ * Shared interface implemented by all storage adapters.
+ *
+ * Defines the minimum contract — `name`, `type`, `mediaCollections`, and the
+ * four lifecycle methods (`createMediaDocument`, `deleteMedia`, `getUrl`,
+ * `uploadFile`) — that every adapter must satisfy regardless of protocol.
+ *
+ * @see {@link StorageAdapterPresignedUrlInterface} for the presigned-URL sub-interface
+ * @see {@link StorageAdapterPresignedUrl} for the abstract base class
+ */
+export interface StorageAdapterBaseInterface {
+    /** Protocol name — tells the admin panel what the identifier of this storage adapter is. */
+    readonly name: StorageAdapterSlug;
+    /** Protocol type — tells the admin panel how to upload files. */
+    readonly type: StorageAdapterProtocol;
+    /**
+     * Processed media collections ready for schema generation and admin panel.
+     *
+     * The adapter validates, augments, and returns these collections. Each
+     * collection is tagged with `meta.storageAdapterName` equal to this adapter's
+     * `name`. Core merges all collections from all adapters into
+     * `VexConfig.mediaCollections` — separate from user-defined `collections`.
+     */
+    mediaCollections: MediaCollectionConfig[];
+    admin: {
+        /**
+         * When `true`, delete operations set `deleted: true` on the media document
+         * instead of physically removing the file. The file remains in storage until
+         * a scheduled cleanup job purges it.
+         *
+         * @default false
+         */
+        softDelete: boolean;
+    };
+    /**
+     * Creates a media document in Convex after the file is uploaded.
+     * All adapters must use this exact signature.
+     */
+    createMediaDocument<TDataModel extends GenericDataModel = GenericDataModel>(ctx: GenericMutationCtx<TDataModel>, args: {
+        collectionSlug: string;
+        storageId: string;
+        filename: string;
+        mimeType: string;
+        size: number;
+        alt?: string;
+        adapterFields?: Record<string, unknown>;
+    }): Promise<string>;
+    /**
+     * Deletes a media document and its file from storage.
+     * All adapters must use this exact signature.
+     */
+    deleteMedia<TDataModel extends GenericDataModel = GenericDataModel>(ctx: GenericMutationCtx<TDataModel>, args: {
+        collectionSlug: string;
+        mediaId: string;
+        softDelete?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Returns a URL for a media file.
+     * All adapters must use this exact signature.
+     */
+    getUrl<TDataModel extends GenericDataModel = GenericDataModel>(ctx: GenericQueryCtx<TDataModel>, args: {
+        collectionSlug: string;
+        mediaId: string;
+    }): Promise<GetUrlReturn>;
+    /**
+     * Uploads a file to the storage backend and returns the storage ID.
+     *
+     * This is a pure JS function that can be called from any framework
+     * (React, Next.js, Svelte, etc.) or even directly in the browser.
+     *
+     * @param file - The file to upload
+     * @param uploadUrl - The presigned URL from generateUploadUrl
+     * @returns Promise resolving to { storageId, url, ... } with adapter-specific fields
+     *
+     * @example
+     * ```ts
+     * // React component
+     * const { storageId } = await adapter.uploadFile(file, uploadUrl);
+     * await createMediaDocument({ storageId, ... });
+     * ```
+     */
+    uploadFile(file: any, uploadUrl: string): Promise<{
+        storageId: string;
+        url?: string;
+        [key: string]: unknown;
+    }>;
+}
+/**
+ * Return type for `generateUploadUrl` — the upload URL and an optional adapter-assigned storage ID.
+ */
+export type GenerateUploadUrlReturn = {
+    url: string;
+    storageId?: string;
+};
+/**
+ * Return type for `uploadFile` — the adapter-assigned storage ID, an optional public URL,
+ * and any adapter-specific fields (e.g. Cloudinary `public_id`, S3 `key`).
+ */
+export type UploadFileReturn = {
+    storageId: string;
+    url?: string;
+    [key: string]: unknown;
+};
+/**
+ * Storage adapter interface for the presigned-URL upload protocol.
+ *
+ * Extends `StorageAdapterBaseInterface` with `generateUploadUrl` — the client
+ * requests a short-lived URL from the server, POSTs the file directly to
+ * storage, then calls `createMediaDocument` with the returned `storageId`.
+ *
+ * @see {@link StorageAdapterBaseInterface} for the shared base contract
+ * @see {@link StorageAdapterPresignedUrl} for the abstract base class to extend
+ */
+export interface StorageAdapterPresignedUrlInterface extends StorageAdapterBaseInterface {
+    readonly type: (typeof STORAGE_ADAPTER_PROTOCOLS)["presignedUrl"];
+    /**
+     * Generates a URL to upload a file to. Returns different shapes per protocol:
+     * - presigned-url: `{ url: string }` — POST the file to this URL
+     * - direct-upload: `{ url: string; storageId?: string }` — PUT the file to this URL
+     * - streaming: `{ url: string; storageId?: string }` — resumable upload session
+     */
+    generateUploadUrl<TDataModel extends GenericDataModel = GenericDataModel>(ctx: GenericMutationCtx<TDataModel>): Promise<GenerateUploadUrlReturn>;
+    /**
+     * Uploads a file to the storage backend and returns the storage ID.
+     *
+     * This is a pure JS function that can be called from any framework
+     * (React, Next.js, Svelte, etc.) or even directly in the browser.
+     *
+     * @param file - The file to upload
+     * @param uploadUrl - The presigned URL from generateUploadUrl
+     * @returns Promise resolving to { storageId, url, ... } with adapter-specific fields
+     *
+     * @example
+     * ```ts
+     * // React component
+     * const { storageId } = await adapter.uploadFile(file, uploadUrl);
+     * await createMediaDocument({ storageId, ... });
+     * ```
+     */
+    uploadFile(file: any, uploadUrl: string): Promise<UploadFileReturn>;
+}
+/**
+ * Base class for storage adapters.
+ *
+ * All file storage adapters must extend this class to ensure consistent
+ * behavior in the admin panel. Adapters override methods to implement
+ * adapter-specific logic (e.g., different storage backends).
+ *
+ * @example
+ * ```ts
+ * // In file-storage-convex/src/adapter/index.ts
+ * import { BaseStorageAdapter } from "@vexcms/core";
+ *
+ * export class ConvexStorageAdapter extends BaseStorageAdapter {
+ *   readonly name = "convex";
+ *
+ *   async generateUploadUrl(ctx) {
+ *     const url = await ctx.storage.generateUploadUrl();
+ *     return { url };
+ *   }
+ *
+ *   // Override other methods as needed...
+ * }
+ * ```
+ */
+export declare abstract class StorageAdapterPresignedUrl implements StorageAdapterPresignedUrlInterface {
+    /** Protocol name — tells the admin panel what the identifier of this storage adapter is. */
+    abstract readonly name: StorageAdapterSlug;
+    /** Protocol type — tells the admin panel how to upload files. */
+    abstract readonly type: StorageAdapterProtocol;
+    abstract mediaCollections: MediaCollectionConfig[];
+    abstract admin: {
+        softDelete: boolean;
+    };
+    /**
+     * Generates a URL to upload a file to.
+     * Override in subclass for adapter-specific implementation.
+     */
+    abstract generateUploadUrl<TDataModel extends GenericDataModel = GenericDataModel>(ctx: GenericMutationCtx<TDataModel>): Promise<{
+        url: string;
+        storageId?: string;
+    }>;
+    /**
+     * Creates a media document in Convex after the file is uploaded.
+     * Override in subclass for adapter-specific implementation.
+     */
+    abstract createMediaDocument<TDataModel extends GenericDataModel = GenericDataModel>(ctx: GenericMutationCtx<TDataModel>, args: {
+        collectionSlug: string;
+        storageId: string;
+        filename: string;
+        mimeType: string;
+        size: number;
+        alt?: string;
+        adapterFields?: Record<string, unknown>;
+    }): Promise<string>;
+    /**
+     * Deletes a media document and its file from storage.
+     * Override in subclass for adapter-specific implementation.
+     */
+    abstract deleteMedia<TDataModel extends GenericDataModel = GenericDataModel>(ctx: GenericMutationCtx<TDataModel>, args: {
+        collectionSlug: string;
+        mediaId: string;
+        softDelete?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Returns a URL for a media file.
+     * Override in subclass for adapter-specific implementation.
+     */
+    abstract getUrl<TDataModel extends GenericDataModel = GenericDataModel>(ctx: GenericQueryCtx<TDataModel>, args: {
+        collectionSlug: string;
+        mediaId: string;
+    }): Promise<{
+        url: string;
+        error?: never;
+    } | {
+        url?: never;
+        error: string;
+    }>;
+    /**
+     * Uploads a file to the storage backend and returns the storage ID.
+     *
+     * This is a pure JS function that can be called from any framework
+     * (React, Next.js, Svelte, etc.) or even directly in the browser.
+     *
+     * @param file - The file to upload
+     * @param uploadUrl - The presigned URL from generateUploadUrl
+     * @returns Promise resolving to { storageId, url, ... } with adapter-specific fields
+     *
+     * @example
+     * ```ts
+     * // React component
+     * const { storageId } = await adapter.uploadFile(file, uploadUrl);
+     * await createMediaDocument({ storageId, ... });
+     * ```
+     */
+    abstract uploadFile(file: any, uploadUrl: string): Promise<{
+        storageId: string;
+        url?: string;
+        [key: string]: unknown;
+    }>;
+}
+/**
+ * Union of all supported storage adapter interface types.
+ *
+ * Currently only presigned-URL adapters are supported. Extend this union
+ * as new upload protocols are added.
+ *
+ * @see {@link StorageAdapterPresignedUrlInterface}
+ */
+export type VexStorageAdapter = StorageAdapterPresignedUrlInterface;
+//# sourceMappingURL=types.d.ts.map

package/dist/media/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/media/types.ts"],"names":[],"mappings":"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"}

package/dist/media/utils.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Formats byte count into human-readable file size.
+ *
+ * Converts raw byte count into appropriate units (B, KB, MB, GB, TB)
+ * with sensible precision for each scale.
+ *
+ * @param bytes - File size in bytes
+ * @returns Formatted string with unit (e.g. "248 KB", "1.4 MB")
+ *
+ * @example
+ * ```ts
+ * formatBytes(1024) // "1 KB"
+ * formatBytes(1536) // "1.5 KB"
+ * formatBytes(1048576) // "1 MB"
+ * formatBytes(248000) // "242.2 KB"
+ * ```
+ */
+export declare function formatBytes(bytes: number): string;
+/**
+ * Formats MIME type into short display name.
+ *
+ * Extracts the subtype from a MIME type and normalizes common variants.
+ *
+ * @param mimeType - Full MIME type (e.g. "image/jpeg")
+ * @returns Uppercase short name (e.g. "JPG")
+ *
+ * @example
+ * ```ts
+ * formatMimeType("image/jpeg") // "JPG"
+ * formatMimeType("image/svg+xml") // "SVG"
+ * formatMimeType("application/pdf") // "PDF"
+ * ```
+ */
+export declare function formatMimeType(mimeType: string): string;
+//# sourceMappingURL=utils.d.ts.map

package/dist/media/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/media/utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMjD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKvD"}

package/dist/media/validators.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Convex validator for `createMediaDocument` arguments.
+ * Every storage adapter must use this in its `createMediaDocument` mutation.
+ */
+export declare const createMediaDocumentArgs: import("convex/values").VObject<{
+    alt?: string | undefined;
+    adapterFields?: Record<string, any> | undefined;
+    storageId: string;
+    collectionSlug: string;
+    fileName: string;
+    mimeType: string;
+    size: number;
+}, {
+    collectionSlug: import("convex/values").VString<string, "required">;
+    storageId: import("convex/values").VString<string, "required">;
+    fileName: import("convex/values").VString<string, "required">;
+    mimeType: import("convex/values").VString<string, "required">;
+    size: import("convex/values").VFloat64<number, "required">;
+    alt: import("convex/values").VString<string | undefined, "optional">;
+    adapterFields: import("convex/values").VRecord<Record<string, any> | undefined, import("convex/values").VString<string, "required">, import("convex/values").VAny<any, "required", string>, "optional", string>;
+}, "required", "storageId" | "collectionSlug" | "fileName" | "mimeType" | "size" | "alt" | "adapterFields" | `adapterFields.${string}`>;
+/**
+ * Convex validator for `createMediaDocument` return value.
+ * Returns the created media document ID.
+ */
+export declare const createMediaDocumentReturn: import("convex/values").VString<string, "required">;
+/**
+ * Convex validator for `deleteMedia` arguments.
+ * Every storage adapter must use this in its `deleteMedia` mutation.
+ */
+export declare const deleteMediaArgs: import("convex/values").VObject<{
+    collectionSlug: string;
+    mediaId: string;
+}, {
+    collectionSlug: import("convex/values").VString<string, "required">;
+    mediaId: import("convex/values").VString<string, "required">;
+}, "required", "collectionSlug" | "mediaId">;
+/**
+ * Convex validator for `deleteMedia` return value.
+ */
+export declare const deleteMediaReturn: import("convex/values").VBoolean<boolean, "required">;
+/**
+ * Convex validator for `getUrl` arguments.
+ * Every storage adapter must use this in its `getUrl` query.
+ */
+export declare const getUrlArgs: import("convex/values").VObject<{
+    collectionSlug: string;
+    mediaId: string;
+}, {
+    collectionSlug: import("convex/values").VString<string, "required">;
+    mediaId: import("convex/values").VString<string, "required">;
+}, "required", "collectionSlug" | "mediaId">;
+/**
+ * Convex validator for `getUrl` return value.
+ */
+export declare const getUrlReturn: import("convex/values").VObject<{
+    url: string;
+}, {
+    url: import("convex/values").VString<string, "required">;
+}, "required", "url">;
+//# sourceMappingURL=validators.d.ts.map

package/dist/media/validators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../src/media/validators.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;uIAQlC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,yBAAyB,qDAAa,CAAC;AAEpD;;;GAGG;AACH,eAAO,MAAM,eAAe;;;;;;4CAG1B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,iBAAiB,uDAAc,CAAC;AAE7C;;;GAGG;AACH,eAAO,MAAM,UAAU;;;;;;4CAGrB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,YAAY;;;;qBAEvB,CAAC"}

package/dist/schema/generateVexSchema.d.ts

@@ -0,0 +1,36 @@
+import type { VexConfig } from "../config/types";
+/**
+ * Generates the full contents of `vex.schema.ts` from a resolved `VexConfig`.
+ *
+ * Returns `{ update: false, contents }` when there are no collections — the output
+ * contains only the auto-generated header and no imports or table declarations.
+ * Returns `{ update: true, contents }` when collections are present — the output
+ * includes the header, `convex/server` and `convex/values` imports, and one
+ * `export const` block per collection.
+ *
+ * @param props - Input props.
+ * @param props.config - The fully resolved Vex configuration.
+ * @returns An object with `update` (whether the file should be written to disk) and `contents` (the file string).
+ *
+ * @example
+ * ```ts
+ * const config = defineConfig({
+ *   collections: [
+ *     defineCollection({ slug: "posts", fields: { title: text() } }),
+ *   ],
+ * });
+ * const { update, contents } = generateVexSchema({ config });
+ * // update   → true
+ * // contents → '// ⚠️ AUTO-GENERATED BY VEX CMS ...\nimport { defineTable } from "convex/server"\n...'
+ * ```
+ *
+ * @see {@link collectionConfigToVexSchema} for the per-collection string builder
+ * @see {@link VexConfig} for the resolved config shape
+ */
+export declare function generateVexSchema(props: {
+    config: VexConfig;
+}): {
+    update: boolean;
+    contents: string;
+};
+//# sourceMappingURL=generateVexSchema.d.ts.map

package/dist/schema/generateVexSchema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateVexSchema.d.ts","sourceRoot":"","sources":["../../src/schema/generateVexSchema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAWjD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,GAAG;IAC/D,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB,CA+BA"}

package/dist/schema/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./generateVexSchema";
+export * from "./migrate";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schema/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAA;AACnC,cAAc,WAAW,CAAA"}

package/dist/schema/migrate.d.ts

@@ -0,0 +1,73 @@
+import type { VexConfig } from "../config/types";
+/** A field that needs migration when its schema changes. */
+export interface NeedsMigrationField {
+    table: string;
+    field: string;
+    isOptional: boolean;
+}
+/** Metadata about a field that was removed from the config. */
+export interface RemovedFieldInfo {
+    table: string;
+    field: string;
+}
+/** Diff result between two schema strings. */
+export interface SchemaDiff {
+    needsMigration: NeedsMigrationField[];
+    removedFields: RemovedFieldInfo[];
+}
+/** A single field backfill operation produced by `planMigration`. */
+export type MigrationOp = {
+    table: string;
+    field: string;
+    defaultValue: unknown;
+};
+/**
+ * Computes a diff between two schema strings, identifying fields that now
+ * need migration and fields that were removed. Stub — always returns an
+ * empty diff; schema-string diffing is not yet implemented.
+ *
+ * @param _previous - The prior schema source string. Currently unused;
+ *   placeholder for the not-yet-implemented diffing logic.
+ * @param _next - The new schema source string. Currently unused;
+ *   placeholder for the not-yet-implemented diffing logic.
+ * @returns An empty {@link SchemaDiff} until diffing is implemented.
+ */
+export declare function diffSchema(_previous: string, _next: string): SchemaDiff;
+/**
+ * Returns a copy of the schema string with the given fields made optional.
+ * Stub — currently returns `schema` unchanged; the rewrite is not yet
+ * implemented.
+ *
+ * @param schema - The schema source string to rewrite.
+ * @param _fields - The fields that should be made optional. Currently
+ *   unused; placeholder for the not-yet-implemented rewrite.
+ * @returns The schema string, unchanged until this is implemented.
+ */
+export declare function makeFieldsOptional(schema: string, _fields: NeedsMigrationField[]): string;
+/**
+ * Returns a copy of the schema string with previously removed fields
+ * re-added as optional. Stub — currently returns `schema` unchanged; the
+ * rewrite is not yet implemented.
+ *
+ * @param schema - The schema source string to rewrite.
+ * @param _removedFields - The fields that were removed from the config and
+ *   should be re-added as optional. Currently unused; placeholder for the
+ *   not-yet-implemented rewrite.
+ * @returns The schema string, unchanged until this is implemented.
+ */
+export declare function addRemovedFieldsAsOptional(schema: string, _removedFields: RemovedFieldInfo[]): string;
+/**
+ * Plans backfill operations from a schema diff. Stub — always returns an
+ * empty array; migration planning is not yet implemented.
+ *
+ * @param _props - The schema diff and resolved config to plan backfills
+ *   from. Currently unused; placeholder for the not-yet-implemented
+ *   planning logic.
+ * @returns An empty list of {@link MigrationOp}s until planning is
+ *   implemented.
+ */
+export declare function planMigration(_props: {
+    diff: SchemaDiff;
+    config: VexConfig;
+}): MigrationOp[];
+//# sourceMappingURL=migrate.d.ts.map

package/dist/schema/migrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/schema/migrate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,4DAA4D;AAC5D,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,+DAA+D;AAC/D,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,8CAA8C;AAC9C,MAAM,WAAW,UAAU;IACzB,cAAc,EAAE,mBAAmB,EAAE,CAAC;IACtC,aAAa,EAAE,gBAAgB,EAAE,CAAC;CACnC;AAED,qEAAqE;AACrE,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,CAEvE;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,mBAAmB,EAAE,GAC7B,MAAM,CAER;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,gBAAgB,EAAE,GACjC,MAAM,CAER;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE;IACpC,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,SAAS,CAAC;CACnB,GAAG,WAAW,EAAE,CAEhB"}

package/dist/types/generateVexTypes.d.ts

@@ -0,0 +1,41 @@
+import type { VexConfig } from "../config/types";
+/**
+ * Generates the full contents of `vex.types.ts` from a resolved `VexConfig`.
+ *
+ * When there are no collections, returns only the auto-generated header.
+ * When collections are present, the output contains:
+ * - Imports for `Id` (from `@convex/_generated/dataModel`) and `VexDocument` (from `@vexcms/core`)
+ * - One `export interface` per collection, extending `VexDocument` with a branded `Id<"slug">` for `_id`
+ * - `export type CollectionSlug` — union of all collection slugs
+ * - `export type DocumentBySlug` — map of slug to document interface
+ * - `declare module '@vexcms/core'` block that augments `GeneratedVexTypes`, narrowing
+ *   `CollectionSlug` and `DocumentBySlug` inside `@vexcms/core` itself
+ *
+ * @param props - Input props.
+ * @param props.config - The fully resolved Vex configuration.
+ * @returns The complete TypeScript source string to write to `vex.types.ts`.
+ *
+ * @example
+ * ```ts
+ * const config = defineConfig({
+ *   collections: [
+ *     defineCollection({ slug: "posts", fields: { title: text({ required: true }) } }),
+ *   ],
+ * });
+ * const contents = generateVexTypes({ config });
+ * // Writes to vex.types.ts:
+ * // import type { Id } from "@convex/_generated/dataModel"
+ * // import type { VexDocument } from "@vexcms/core"
+ * // export interface PostsDocument extends VexDocument { _id: Id<"posts">; title: string }
+ * // export type CollectionSlug = "posts"
+ * // export type DocumentBySlug = { posts: PostsDocument }
+ * // declare module "@vexcms/core" { interface GeneratedVexTypes { ... } }
+ * ```
+ *
+ * @see {@link collectionConfigToInterface} for the per-collection interface builder
+ * @see {@link VexConfig} for the resolved config shape
+ */
+export declare function generateVexTypes(props: {
+    config: VexConfig;
+}): string;
+//# sourceMappingURL=generateVexTypes.d.ts.map

package/dist/types/generateVexTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateVexTypes.d.ts","sourceRoot":"","sources":["../../src/types/generateVexTypes.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AA2CjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,GAAG,MAAM,CA8HrE"}