@magnet-cms/common 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,1065 @@
+import { Type, DynamicModule, ValidationError } from '@nestjs/common';
+import { Readable } from 'node:stream';
+
+type ResolverOptions = {
+    schema: Type;
+};
+type ResolverInput = (() => Type) | ResolverOptions;
+type ResolveOptions = {
+    type: Type | [Type];
+    isArray?: boolean;
+    description?: string;
+};
+type ResolveInput = (() => Type | [Type]) | ResolveOptions;
+type PropOptions = {
+    type?: Type | [Type];
+    description?: string;
+    required?: boolean;
+    unique?: boolean;
+    default?: any;
+    nullable?: boolean;
+    intl?: boolean;
+    hidden?: boolean;
+    readonly?: boolean;
+};
+type BaseSchemaOptions = {
+    timestamps?: boolean;
+};
+type SchemaOptions = {
+    versioning?: boolean;
+    i18n?: boolean;
+};
+
+type UIPresentationFields = 'tab' | 'collapsible' | 'row' | 'customUI';
+type UITypes = 'array' | 'blocks' | 'checkbox' | 'code' | 'combobox' | 'date' | 'email' | 'fileUpload' | 'group' | 'json' | 'multiSelect' | 'number' | 'phone' | 'point' | 'quantity' | 'radio' | 'relationship' | 'richText' | 'select' | 'switch' | 'table' | 'text' | 'textarea' | 'upload';
+type UIBase = {
+    label?: string;
+    description?: string;
+    type?: UITypes;
+    row?: boolean;
+    collapsible?: boolean;
+};
+type UISelectItem = {
+    key: string;
+    value: string;
+};
+type UITab = UIBase & {
+    tab: string;
+    side?: never;
+    options?: UISelectItem[];
+};
+type UISide = UIBase & {
+    side: true;
+    tab?: never;
+    options?: UISelectItem[];
+};
+type UISelect = UIBase & {
+    type: 'select';
+    multi?: boolean;
+    options: UISelectItem[];
+};
+type UIMultiSelect = UIBase & {
+    type: 'multiSelect';
+    options: UISelectItem[];
+};
+type UICombobox = UIBase & {
+    type: 'combobox';
+    options: UISelectItem[];
+};
+type UITableColumn = {
+    key: string;
+    header: string;
+    type?: 'text' | 'badge' | 'status' | 'input' | 'code';
+};
+type UITable = UIBase & {
+    type: 'table';
+    columns?: UITableColumn[];
+};
+type UIDecoratorOptions = UITab | UISide | UISelect | UIMultiSelect | UICombobox | UITable;
+
+type MethodMetadata = {
+    name: string;
+    returnType: {
+        type: Type;
+        isArray: boolean;
+    };
+    params: {
+        arg: string;
+        type: string;
+        name: string;
+    }[];
+    httpMethod: string;
+    routePath: string;
+    guards?: Type[];
+    interceptors?: Type[];
+    pipes?: Type[];
+};
+type ControllerMetadata = {
+    name: string;
+    basePath: string;
+    methods: MethodMetadata[];
+};
+type SchemaPropertyValidation = {
+    type: string;
+    name: string;
+    constraints: number[];
+};
+type SchemaProperty = {
+    name: string;
+    type: string;
+    isArray: boolean;
+    unique: boolean;
+    required: boolean;
+    validations: SchemaPropertyValidation[];
+    ui: UIDecoratorOptions;
+};
+type SchemaMetadata = {
+    name: string;
+    properties: SchemaProperty[];
+    options?: SchemaOptions;
+};
+
+type InitialConfig = {
+    title?: string;
+    description?: string;
+    env: string;
+    schemas: SchemaMetadata[];
+    settings: SchemaMetadata[];
+};
+
+/**
+ * Authenticated user returned from auth strategies
+ */
+interface AuthUser {
+    /** Unique user identifier */
+    id: string;
+    /** User email address */
+    email: string;
+    /** User role for authorization */
+    role: string;
+    /** Optional additional user data */
+    [key: string]: unknown;
+}
+/**
+ * Login credentials (strategy-specific)
+ */
+interface LoginCredentials {
+    email: string;
+    password: string;
+    [key: string]: unknown;
+}
+/**
+ * Registration data (strategy-specific)
+ */
+interface RegisterData {
+    email: string;
+    password: string;
+    name: string;
+    role?: string;
+    [key: string]: unknown;
+}
+/**
+ * Authentication result containing access token
+ */
+interface AuthResult {
+    access_token: string;
+    refresh_token?: string;
+    expires_in?: number;
+    token_type?: string;
+}
+/**
+ * JWT-specific configuration
+ */
+interface JwtAuthConfig {
+    /** JWT secret key */
+    secret: string;
+    /** Token expiration time (e.g., '7d', '1h') */
+    expiresIn?: string;
+}
+/**
+ * Auth configuration for MagnetModuleOptions
+ */
+interface AuthConfig {
+    /** Strategy name to use (default: 'jwt') */
+    strategy?: string;
+    /** JWT-specific configuration */
+    jwt?: JwtAuthConfig;
+    /** Allow extensible config for custom strategies */
+    [key: string]: unknown;
+}
+/**
+ * Abstract base class for authentication strategies.
+ * Similar to StorageAdapter, custom strategies must extend this class.
+ *
+ * @example
+ * ```typescript
+ * export class SupabaseAuthStrategy extends AuthStrategy {
+ *   readonly name = 'supabase'
+ *
+ *   async validate(payload: unknown): Promise<AuthUser | null> {
+ *     // Validate Supabase JWT token
+ *   }
+ *
+ *   async login(credentials: LoginCredentials): Promise<AuthResult> {
+ *     // Authenticate with Supabase
+ *   }
+ *
+ *   async register(data: RegisterData): Promise<AuthUser> {
+ *     // Register user in Supabase
+ *   }
+ *
+ *   async validateCredentials(email: string, password: string): Promise<AuthUser | null> {
+ *     // Validate user credentials
+ *   }
+ * }
+ * ```
+ */
+declare abstract class AuthStrategy {
+    /**
+     * Unique identifier for this strategy
+     */
+    abstract readonly name: string;
+    /**
+     * Initialize the auth strategy (optional setup)
+     */
+    initialize?(): Promise<void>;
+    /**
+     * Validate a token/payload and return the authenticated user
+     * @param payload - Strategy-specific payload (e.g., JWT payload, session data)
+     * @returns Authenticated user or null if invalid
+     */
+    abstract validate(payload: unknown): Promise<AuthUser | null>;
+    /**
+     * Authenticate user with credentials and return tokens
+     * @param credentials - Login credentials (strategy-specific)
+     * @returns Authentication result with access token
+     */
+    abstract login(credentials: LoginCredentials): Promise<AuthResult>;
+    /**
+     * Register a new user
+     * @param data - Registration data
+     * @returns The created user
+     */
+    abstract register(data: RegisterData): Promise<AuthUser>;
+    /**
+     * Validate user credentials (used internally by login)
+     * @param email - User email
+     * @param password - User password
+     * @returns User if valid, null otherwise
+     */
+    abstract validateCredentials(email: string, password: string): Promise<AuthUser | null>;
+    /**
+     * Refresh an access token (optional)
+     * @param refreshToken - The refresh token
+     * @returns New authentication result
+     */
+    refresh?(refreshToken: string): Promise<AuthResult>;
+    /**
+     * Logout/invalidate tokens (optional)
+     * @param token - The token to invalidate
+     */
+    logout?(token: string): Promise<void>;
+    /**
+     * Get the Passport strategy name (for guards)
+     * Returns the name to use with AuthGuard()
+     */
+    getPassportStrategyName(): string;
+}
+
+type MongooseConfig = {
+    uri: string;
+};
+type TypeORMConfig = {
+    type: 'mysql' | 'postgres' | 'sqlite' | 'mariadb' | 'mssql' | 'oracle' | 'mongodb';
+    host: string;
+    port: number;
+    username: string;
+    password: string;
+    database: string;
+};
+type DBConfig = MongooseConfig | TypeORMConfig;
+declare abstract class DatabaseAdapter {
+    abstract connect(options: MagnetModuleOptions): DynamicModule;
+    abstract forFeature(schemas: Type | Type[]): DynamicModule;
+    abstract model<T>(modelInstance: any): any;
+    abstract token(schema: string): string;
+}
+
+/**
+ * Plugin metadata for the @Plugin decorator
+ */
+interface PluginMetadata {
+    /** Unique plugin identifier (e.g., 'content-builder') */
+    name: string;
+    /** Human-readable description */
+    description?: string;
+    /** Semver version */
+    version?: string;
+    /** Plugin dependencies (other plugin names) */
+    dependencies?: string[];
+    /** NestJS module to be auto-imported (optional for backwards compatibility) */
+    module?: Type<unknown>;
+}
+/**
+ * Route definition for plugin frontend
+ */
+interface PluginRouteDefinition {
+    /** Route path (e.g., '/playground') */
+    path: string;
+    /** Component identifier for lazy loading */
+    componentId: string;
+    /** Whether route requires authentication */
+    requiresAuth?: boolean;
+    /** Required permissions */
+    permissions?: string[];
+    /** Child routes */
+    children?: PluginRouteDefinition[];
+}
+/**
+ * Sidebar item for plugin frontend
+ */
+interface PluginSidebarItem {
+    /** Unique identifier */
+    id: string;
+    /** Display title */
+    title: string;
+    /** Route path */
+    url: string;
+    /** Lucide icon name (e.g., 'Boxes', 'Settings') */
+    icon: string;
+    /** Position in sidebar (lower = higher) */
+    order?: number;
+    /** Child items */
+    items?: PluginSidebarItem[];
+    /** Badge to show */
+    badge?: string | number;
+}
+/**
+ * Settings page for plugin
+ */
+interface PluginSettingsPage {
+    /** Settings group identifier */
+    groupId: string;
+    /** Display title */
+    title: string;
+    /** Description */
+    description?: string;
+    /** Component identifier */
+    componentId: string;
+}
+/**
+ * Frontend manifest exposed by plugins via discovery
+ */
+interface PluginFrontendManifest {
+    /** Plugin identifier */
+    pluginName: string;
+    /** Routes to register */
+    routes?: PluginRouteDefinition[];
+    /** Sidebar items */
+    sidebar?: PluginSidebarItem[];
+    /** Settings pages */
+    settings?: PluginSettingsPage[];
+    /** Required permissions */
+    permissions?: string[];
+}
+/**
+ * Enriched plugin manifest with bundle URL for runtime loading
+ * Returned by GET /plugins/manifests endpoint
+ */
+interface EnrichedPluginManifest extends PluginFrontendManifest {
+    /** URL to load the plugin's frontend bundle */
+    bundleUrl: string;
+}
+/**
+ * Plugin configuration passed to MagnetModule.forRoot
+ */
+interface PluginConfig {
+    /** The plugin class decorated with @Plugin */
+    plugin: Type<unknown>;
+    /** Plugin-specific options */
+    options?: Record<string, unknown>;
+    /** Whether the plugin is enabled (default: true) */
+    enabled?: boolean;
+}
+/**
+ * Hook definition for plugins
+ */
+interface PluginHook {
+    instance: unknown;
+    methodName: string | symbol;
+}
+/**
+ * Options for PluginModule.forRoot
+ */
+interface PluginModuleOptions {
+    plugins: PluginConfig[];
+}
+/**
+ * Registered plugin info returned from API
+ */
+interface RegisteredPluginInfo {
+    name: string;
+    description?: string;
+    version?: string;
+    dependencies?: string[];
+    frontend?: PluginFrontendManifest;
+    options?: Record<string, unknown>;
+}
+/**
+ * Interface for plugin lifecycle hooks.
+ * Plugins can implement these methods to respond to lifecycle events.
+ *
+ * @example
+ * ```ts
+ * @Plugin({ name: 'my-plugin', module: MyPluginModule })
+ * export class MyPlugin implements PluginLifecycle {
+ *   onPluginInit() {
+ *     console.log('Plugin initialized')
+ *   }
+ *
+ *   onPluginDestroy() {
+ *     console.log('Plugin destroyed')
+ *   }
+ * }
+ * ```
+ */
+interface PluginLifecycle {
+    /**
+     * Called after the plugin module is initialized.
+     * Use this for plugin-specific setup that needs other services.
+     */
+    onPluginInit?(): void | Promise<void>;
+    /**
+     * Called when the application is shutting down.
+     * Use this for cleanup operations.
+     */
+    onPluginDestroy?(): void | Promise<void>;
+}
+
+interface LocalStorageConfig {
+    /** Directory where files will be stored (e.g., './uploads') */
+    uploadDir: string;
+    /** Public URL path for serving files (e.g., '/media') */
+    publicPath: string;
+    /** Maximum file size in bytes (default: 50MB) */
+    maxFileSize?: number;
+    /** Allowed MIME types (default: all) */
+    allowedMimeTypes?: string[];
+}
+interface S3StorageConfig {
+    /** S3 bucket name */
+    bucket: string;
+    /** AWS region */
+    region: string;
+    /** AWS access key ID */
+    accessKeyId: string;
+    /** AWS secret access key */
+    secretAccessKey: string;
+    /** Custom endpoint URL (for R2, MinIO, etc.) */
+    endpoint?: string;
+    /** Public URL for serving files (CDN URL) */
+    publicUrl?: string;
+    /** Enable path-style access (required for some S3-compatible services) */
+    forcePathStyle?: boolean;
+}
+interface R2StorageConfig extends S3StorageConfig {
+    /** Cloudflare account ID */
+    accountId: string;
+}
+interface StorageConfig {
+    /** Storage adapter to use */
+    adapter: 'local' | 's3' | 'r2';
+    /** Local storage configuration */
+    local?: LocalStorageConfig;
+    /** S3 storage configuration */
+    s3?: S3StorageConfig;
+    /** R2 storage configuration */
+    r2?: R2StorageConfig;
+}
+interface UploadOptions {
+    /** Target folder for the file */
+    folder?: string;
+    /** Custom filename (auto-generated if not provided) */
+    filename?: string;
+    /** MIME type of the file */
+    mimeType?: string;
+    /** Tags for categorization */
+    tags?: string[];
+    /** Alt text for accessibility */
+    alt?: string;
+    /** Custom metadata fields */
+    customFields?: Record<string, unknown>;
+}
+interface UploadResult {
+    /** Unique identifier for the uploaded file */
+    id: string;
+    /** Stored filename */
+    filename: string;
+    /** Original filename from user */
+    originalFilename: string;
+    /** MIME type of the file */
+    mimeType: string;
+    /** File size in bytes */
+    size: number;
+    /** Storage path or key */
+    path: string;
+    /** Public URL to access the file */
+    url: string;
+    /** Folder the file is stored in */
+    folder?: string;
+    /** Tags associated with the file */
+    tags?: string[];
+    /** Alt text for accessibility */
+    alt?: string;
+    /** Image width in pixels (for images only) */
+    width?: number;
+    /** Image height in pixels (for images only) */
+    height?: number;
+    /** Custom metadata fields */
+    customFields?: Record<string, unknown>;
+    /** Upload timestamp */
+    createdAt: Date;
+    /** Last update timestamp */
+    updatedAt: Date;
+}
+interface TransformOptions {
+    /** Target width in pixels */
+    width?: number;
+    /** Target height in pixels */
+    height?: number;
+    /** Resize fit mode */
+    fit?: 'cover' | 'contain' | 'fill' | 'inside' | 'outside';
+    /** Output format */
+    format?: 'jpeg' | 'png' | 'webp' | 'avif';
+    /** Quality (1-100) */
+    quality?: number;
+}
+interface MediaQueryOptions {
+    /** Filter by folder */
+    folder?: string;
+    /** Filter by MIME type (supports partial match) */
+    mimeType?: string;
+    /** Filter by tags (any match) */
+    tags?: string[];
+    /** Search in filename and alt text */
+    search?: string;
+    /** Page number (1-indexed) */
+    page?: number;
+    /** Items per page */
+    limit?: number;
+    /** Sort field */
+    sortBy?: 'createdAt' | 'filename' | 'size';
+    /** Sort direction */
+    sortOrder?: 'asc' | 'desc';
+}
+interface PaginatedMedia<T = UploadResult> {
+    /** List of items */
+    items: T[];
+    /** Total number of items */
+    total: number;
+    /** Current page */
+    page: number;
+    /** Items per page */
+    limit: number;
+    /** Total number of pages */
+    totalPages: number;
+}
+declare abstract class StorageAdapter {
+    /**
+     * Initialize the storage adapter (create directories, check connections)
+     */
+    abstract initialize(): Promise<void>;
+    /**
+     * Upload a file to storage
+     * @param file - File buffer or readable stream
+     * @param originalFilename - Original filename from user
+     * @param options - Upload options
+     */
+    abstract upload(file: Buffer | Readable, originalFilename: string, options?: UploadOptions): Promise<UploadResult>;
+    /**
+     * Upload a file using chunked/streaming upload (for large files)
+     * @param stream - Readable stream of the file
+     * @param originalFilename - Original filename from user
+     * @param totalSize - Total size of the file in bytes
+     * @param options - Upload options
+     */
+    abstract uploadChunked(stream: Readable, originalFilename: string, totalSize: number, options?: UploadOptions): Promise<UploadResult>;
+    /**
+     * Delete a file from storage
+     * @param path - Storage path or key of the file
+     */
+    abstract delete(path: string): Promise<boolean>;
+    /**
+     * Delete multiple files from storage
+     * @param paths - Array of storage paths or keys
+     */
+    abstract deleteMany(paths: string[]): Promise<{
+        deleted: number;
+        failed: string[];
+    }>;
+    /**
+     * Get the public URL for a file
+     * @param path - Storage path or key
+     * @param transform - Optional transform options for images
+     */
+    abstract getUrl(path: string, transform?: TransformOptions): string;
+    /**
+     * Get a readable stream for a file
+     * @param path - Storage path or key
+     */
+    abstract getStream(path: string): Promise<Readable>;
+    /**
+     * Get the file as a buffer
+     * @param path - Storage path or key
+     */
+    abstract getBuffer(path: string): Promise<Buffer>;
+    /**
+     * Check if a file exists
+     * @param path - Storage path or key
+     */
+    abstract exists(path: string): Promise<boolean>;
+    /**
+     * Get a transformed version of an image
+     * @param path - Storage path or key
+     * @param options - Transform options
+     */
+    abstract transform(path: string, options: TransformOptions): Promise<Buffer>;
+    /**
+     * Move/rename a file
+     * @param path - Current storage path or key
+     * @param newPath - New storage path or key
+     */
+    move?(path: string, newPath: string): Promise<UploadResult>;
+    /**
+     * Copy a file
+     * @param path - Source storage path or key
+     * @param newPath - Destination storage path or key
+     */
+    copy?(path: string, newPath: string): Promise<UploadResult>;
+    /**
+     * Generate a signed URL for temporary access (for S3/R2)
+     * @param path - Storage path or key
+     * @param expiresIn - Expiration time in seconds
+     */
+    signedUrl?(path: string, expiresIn?: number): Promise<string>;
+}
+
+interface InternationalizationOptions {
+    locales: string[];
+    defaultLocale: string;
+}
+interface PlaygroundOptions {
+    /**
+     * Path to the directory where module folders will be created
+     * @example './src/modules'
+     */
+    modulesPath?: string;
+    /**
+     * @deprecated Use modulesPath instead
+     * Path to the directory where schema files will be saved
+     */
+    schemasPath?: string;
+}
+declare class MagnetModuleOptions {
+    db: DBConfig;
+    jwt: {
+        secret: string;
+    };
+    /**
+     * Auth configuration (optional, uses JWT by default)
+     */
+    auth?: AuthConfig;
+    internationalization?: InternationalizationOptions;
+    playground?: PlaygroundOptions;
+    storage?: StorageConfig;
+    /**
+     * Plugins to load with the Magnet module
+     */
+    plugins?: PluginConfig[];
+    constructor({ db, jwt, auth, internationalization, playground, storage, plugins, }: MagnetModuleOptions);
+}
+type MagnetModuleOptionsAsync = {
+    useFactory: (...args: any[]) => Promise<MagnetModuleOptions> | MagnetModuleOptions;
+    inject?: Type[];
+    imports?: Type[];
+};
+
+type DiscoveredController = {
+    path: string;
+    schema: string;
+    methods: DiscoveredMethod[];
+};
+type DiscoveredMethod = {
+    name: string;
+    method: string;
+};
+type DiscoveredSchema = {
+    name: string;
+    tableName: string;
+    target: string | object;
+};
+
+type Validations = {
+    type: string;
+    name: string;
+    constraints: any[];
+}[];
+
+type VersionStatus = 'draft' | 'published' | 'archived';
+interface VersionConfig {
+    /**
+     * Maximum number of versions to keep per document
+     */
+    max?: number;
+    /**
+     * Enable drafts mode for this schema
+     */
+    drafts?: boolean | {
+        /**
+         * Auto-publish drafts after a certain time
+         */
+        autoPublish?: boolean;
+        /**
+         * Require approval before publishing
+         */
+        requireApproval?: boolean;
+    };
+}
+interface VersionData<T> {
+    /**
+     * Document ID this version belongs to
+     */
+    documentId: string;
+    /**
+     * Version ID
+     */
+    versionId: string;
+    /**
+     * Version status
+     */
+    status: VersionStatus;
+    /**
+     * Version data
+     */
+    data: T;
+    /**
+     * Version created at
+     */
+    createdAt: Date;
+    /**
+     * Version created by
+     */
+    createdBy?: string;
+    /**
+     * Version notes
+     */
+    notes?: string;
+}
+
+type SettingType = 'string' | 'boolean' | 'number' | 'object' | 'array';
+interface SchemaSetting {
+    key: string;
+    value: unknown;
+    type: SettingType | string;
+}
+interface SettingsFeatureOptions<T = unknown> {
+    group: string;
+    schema: new () => T;
+}
+
+/**
+ * Query operator types for MongoDB-style queries
+ */
+type QueryOperator<T> = {
+    /** Equal to */
+    $eq?: T;
+    /** Not equal to */
+    $ne?: T;
+    /** Greater than */
+    $gt?: T;
+    /** Greater than or equal to */
+    $gte?: T;
+    /** Less than */
+    $lt?: T;
+    /** Less than or equal to */
+    $lte?: T;
+    /** In array */
+    $in?: T[];
+    /** Not in array */
+    $nin?: T[];
+    /** Field exists */
+    $exists?: boolean;
+    /** Regular expression match */
+    $regex?: string | RegExp;
+    /** Regex options (i, m, s, x) */
+    $options?: string;
+};
+/**
+ * Filter value that supports both direct values and operators
+ */
+type FilterValue<T> = T | QueryOperator<T>;
+/**
+ * Full filter query type with logical operators
+ */
+type FilterQuery<Schema> = {
+    [K in keyof Schema]?: FilterValue<Schema[K]>;
+} & {
+    /** Logical AND */
+    $and?: FilterQuery<Schema>[];
+    /** Logical OR */
+    $or?: FilterQuery<Schema>[];
+    /** Logical NOR */
+    $nor?: FilterQuery<Schema>[];
+};
+/**
+ * Sort direction
+ */
+type SortDirection = 1 | -1 | 'asc' | 'desc';
+/**
+ * Sort specification
+ */
+type SortQuery<Schema> = {
+    [K in keyof Schema]?: SortDirection;
+};
+/**
+ * Projection specification for field selection
+ */
+type ProjectionQuery<Schema> = {
+    [K in keyof Schema]?: 0 | 1 | boolean;
+};
+/**
+ * Query execution options
+ */
+interface QueryOptions {
+    /** Maximum number of documents to return */
+    limit?: number;
+    /** Number of documents to skip */
+    skip?: number;
+    /** Return plain objects instead of documents */
+    lean?: boolean;
+}
+/**
+ * Paginated query result
+ */
+interface PaginatedResult<T> {
+    /** Result data */
+    data: T[];
+    /** Total count of matching documents */
+    total: number;
+    /** Current page (if using skip/limit) */
+    page?: number;
+    /** Page size */
+    limit?: number;
+}
+
+declare function Resolver(optionsOrFn: ResolverInput): ClassDecorator;
+
+declare function Resolve(optionsOrFn: ResolveInput): MethodDecorator;
+
+declare function Prop(options?: PropOptions): PropertyDecorator;
+
+declare function Schema(options?: SchemaOptions): ClassDecorator;
+declare function getSchemaOptions(target: Function): SchemaOptions;
+
+declare function Setting(): ClassDecorator;
+
+interface UIFieldMetadata {
+    propertyKey: string | symbol;
+    options: UIDecoratorOptions & {
+        designType: Function;
+    };
+}
+declare function UI(options: UIDecoratorOptions): PropertyDecorator;
+
+declare const Validators: (...validators: PropertyDecorator[]) => <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;
+
+declare const VERSION_METADATA_KEY = "version:metadata";
+/**
+ * Decorator to enable versioning for a schema
+ * @param config Version configuration
+ */
+declare function Version(config?: VersionConfig): ClassDecorator;
+
+declare function InjectModel(model: Type): ParameterDecorator;
+
+declare class ValidationException extends Error {
+    readonly errors: ValidationError[];
+    constructor(errors: ValidationError[]);
+}
+
+/**
+ * Abstract query builder for fluent database queries.
+ * Provides chainable methods for filtering, sorting, pagination, and projection.
+ *
+ * @example
+ * ```typescript
+ * const users = await userModel.query()
+ *   .where({ status: 'active' })
+ *   .sort({ createdAt: -1 })
+ *   .limit(10)
+ *   .exec()
+ * ```
+ */
+declare abstract class QueryBuilder<Schema> {
+    /**
+     * Add filter conditions to the query
+     * @param filter Filter conditions with optional operators
+     */
+    abstract where(filter: FilterQuery<Schema>): this;
+    /**
+     * Add additional AND conditions
+     * @param filter Filter conditions to AND with existing filters
+     */
+    abstract and(filter: FilterQuery<Schema>): this;
+    /**
+     * Add OR conditions
+     * @param filters Array of filter conditions for OR logic
+     */
+    abstract or(filters: FilterQuery<Schema>[]): this;
+    /**
+     * Sort results by specified fields
+     * @param sort Sort specification with field names and directions
+     */
+    abstract sort(sort: SortQuery<Schema>): this;
+    /**
+     * Limit the number of results
+     * @param count Maximum number of documents to return
+     */
+    abstract limit(count: number): this;
+    /**
+     * Skip a number of results (for pagination)
+     * @param count Number of documents to skip
+     */
+    abstract skip(count: number): this;
+    /**
+     * Select specific fields to return
+     * @param projection Field selection (1 to include, 0 to exclude)
+     */
+    abstract select(projection: ProjectionQuery<Schema>): this;
+    /**
+     * Execute the query and return all matching documents
+     */
+    abstract exec(): Promise<BaseSchema<Schema>[]>;
+    /**
+     * Execute the query and return a single document
+     */
+    abstract execOne(): Promise<BaseSchema<Schema> | null>;
+    /**
+     * Count matching documents without fetching them
+     */
+    abstract count(): Promise<number>;
+    /**
+     * Check if any matching documents exist
+     */
+    abstract exists(): Promise<boolean>;
+    /**
+     * Execute with pagination info
+     * @returns Data array with total count
+     */
+    abstract paginate(): Promise<PaginatedResult<BaseSchema<Schema>>>;
+    /**
+     * Set the locale for query results
+     * @param locale The locale to use
+     */
+    abstract locale(locale: string): this;
+    /**
+     * Set the version filter for query
+     * @param versionId The version ID or status
+     */
+    abstract version(versionId: string): this;
+}
+
+type BaseSchema<T> = {
+    id: string;
+} & T;
+interface ModelCreateOptions {
+    /** Skip database-level validation (useful for draft documents) */
+    skipValidation?: boolean;
+}
+interface ModelUpdateOptions {
+    /** Skip database-level validation (useful for draft documents) */
+    skipValidation?: boolean;
+}
+declare abstract class Model<Schema> {
+    abstract create(data: Partial<BaseSchema<Schema>>, options?: ModelCreateOptions): Promise<BaseSchema<Schema>>;
+    abstract find(): Promise<BaseSchema<Schema>[]>;
+    abstract findById(id: string): Promise<BaseSchema<Schema> | null>;
+    abstract findOne(query: Partial<BaseSchema<Schema>>): Promise<BaseSchema<Schema> | null>;
+    abstract findMany(query: Partial<BaseSchema<Schema>>): Promise<BaseSchema<Schema>[]>;
+    abstract update(query: Partial<BaseSchema<Schema>>, data: Partial<BaseSchema<Schema>>, options?: ModelUpdateOptions): Promise<BaseSchema<Schema>>;
+    abstract delete(query: Partial<BaseSchema<Schema>>): Promise<boolean>;
+    /**
+     * Set the locale for subsequent operations
+     * @param locale The locale to use
+     */
+    abstract locale(locale: string): this;
+    /**
+     * Set the version for subsequent operations
+     * @param versionId The version ID or status ('draft', 'published', 'archived')
+     */
+    version(versionId: string): this;
+    /**
+     * Find all versions of a document
+     * @param documentId The document ID
+     */
+    findVersions(documentId: string): Promise<any[]>;
+    /**
+     * Find a specific version by ID
+     * @param versionId The version ID
+     */
+    findVersionById(versionId: string): Promise<any | null>;
+    /**
+     * Restore a version
+     * @param versionId The version ID to restore
+     */
+    restoreVersion(versionId: string): Promise<BaseSchema<Schema> | null>;
+    /**
+     * Create a query builder for advanced queries with sorting, pagination, and operators.
+     * The query builder inherits the current locale/version context.
+     *
+     * @example
+     * ```typescript
+     * const results = await model.query()
+     *   .where({ status: 'active', age: { $gte: 18 } })
+     *   .sort({ createdAt: -1 })
+     *   .limit(10)
+     *   .exec()
+     * ```
+     */
+    query(): QueryBuilder<Schema>;
+    /**
+     * Get access to the native database model/collection.
+     * Use with caution - bypasses Magnet abstractions like locale and versioning.
+     *
+     * @returns The underlying database model (e.g., Mongoose Model)
+     */
+    native(): unknown;
+}
+
+declare class Mixed {
+    static schemaName: 'Mixed';
+    defaultOptions: Record<string, any>;
+}
+
+declare function detectDatabaseAdapter(): 'mongoose' | 'typeorm';
+
+declare function getModelToken(schema: Type): string;
+
+declare const getSchemaToken: (schema: Type) => string;
+declare const getSettingToken: (setting: Type) => string;
+
+declare const RESOLVER_METADATA_KEY = "magnet:resolver";
+declare const RESOLVE_METADATA_KEY = "magnet:resolve";
+declare const SCHEMA_METADATA_KEY = "magnet:schema";
+declare const SCHEMA_OPTIONS_METADATA_KEY = "magnet:schema:options";
+declare const BASE_SCHEMA_METADATA_KEY = "magnet:schema:base";
+declare const PROP_METADATA_KEY = "magnet:schema:prop";
+declare const UI_METADATA_KEY = "magnet:schema:ui";
+declare const SETTING_METADATA_KEY = "magnet:setting";
+declare const INJECT_MODEL = "magnet:inject:model";
+declare const DESIGN_TYPE = "design:type";
+declare const DESIGN_META = "design:metadata";
+declare const DESIGN_PARAM_TYPES = "design:paramtypes";
+declare const DESIGN_RETURN_TYPE = "design:returntype";
+
+export { type AuthConfig, type AuthResult, AuthStrategy, type AuthUser, BASE_SCHEMA_METADATA_KEY, type BaseSchema, type BaseSchemaOptions, type ControllerMetadata, type DBConfig, DESIGN_META, DESIGN_PARAM_TYPES, DESIGN_RETURN_TYPE, DESIGN_TYPE, DatabaseAdapter, type DiscoveredController, type DiscoveredMethod, type DiscoveredSchema, type EnrichedPluginManifest, type FilterQuery, type FilterValue, INJECT_MODEL, type InitialConfig, InjectModel, type InternationalizationOptions, type JwtAuthConfig, type LocalStorageConfig, type LoginCredentials, MagnetModuleOptions, type MagnetModuleOptionsAsync, type MediaQueryOptions, type MethodMetadata, Mixed, Model, type ModelCreateOptions, type ModelUpdateOptions, type MongooseConfig, PROP_METADATA_KEY, type PaginatedMedia, type PaginatedResult, type PlaygroundOptions, type PluginConfig, type PluginFrontendManifest, type PluginHook, type PluginLifecycle, type PluginMetadata, type PluginModuleOptions, type PluginRouteDefinition, type PluginSettingsPage, type PluginSidebarItem, type ProjectionQuery, Prop, type PropOptions, QueryBuilder, type QueryOperator, type QueryOptions, type R2StorageConfig, RESOLVER_METADATA_KEY, RESOLVE_METADATA_KEY, type RegisterData, type RegisteredPluginInfo, Resolve, type ResolveInput, type ResolveOptions, Resolver, type ResolverInput, type ResolverOptions, type S3StorageConfig, SCHEMA_METADATA_KEY, SCHEMA_OPTIONS_METADATA_KEY, SETTING_METADATA_KEY, Schema, type SchemaMetadata, type SchemaOptions, type SchemaProperty, type SchemaPropertyValidation, type SchemaSetting, Setting, type SettingType, type SettingsFeatureOptions, type SortDirection, type SortQuery, StorageAdapter, type StorageConfig, type TransformOptions, type TypeORMConfig, UI, type UIBase, type UICombobox, type UIDecoratorOptions, type UIFieldMetadata, type UIMultiSelect, type UIPresentationFields, type UISelect, type UISelectItem, type UISide, type UITab, type UITable, type UITableColumn, type UITypes, UI_METADATA_KEY, type UploadOptions, type UploadResult, VERSION_METADATA_KEY, ValidationException, type Validations, Validators, Version, type VersionConfig, type VersionData, type VersionStatus, detectDatabaseAdapter, getModelToken, getSchemaOptions, getSchemaToken, getSettingToken };