@magnet-cms/common 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -1,494 +1,2627 @@
-import { Type, DynamicModule, ValidationError } from '@nestjs/common';
+import { Type, OnModuleDestroy, DynamicModule, ValidationError as ValidationError$1 } 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 = {
+/**
+ * Event System Type Definitions
+ *
+ * Type-safe event system for decoupled communication between modules.
+ * Used by: Activity logging, Webhooks, Auth events, RBAC events, etc.
+ */
+/**
+ * All event names in the system
+ * Adding new events requires updating this union
+ */
+type EventName = 'content.created' | 'content.updated' | 'content.deleted' | 'content.published' | 'content.unpublished' | 'content.version.created' | 'content.version.restored' | 'user.created' | 'user.updated' | 'user.deleted' | 'user.registered' | 'user.login' | 'user.logout' | 'user.logout_all' | 'user.password_changed' | 'user.password_reset_requested' | 'user.password_reset' | 'user.password_reset_completed' | 'user.email_verification_requested' | 'user.email_verified' | 'user.session_revoked' | 'auth.token_refreshed' | 'auth.session_created' | 'auth.session_revoked' | 'auth.failed_login_attempt' | 'role.created' | 'role.updated' | 'role.deleted' | 'role.permissions_updated' | 'role.user_assigned' | 'settings.updated' | 'settings.group_updated' | 'media.uploaded' | 'media.deleted' | 'media.folder_created' | 'media.folder_deleted' | 'api_key.created' | 'api_key.revoked' | 'api_key.used' | 'webhook.created' | 'webhook.updated' | 'webhook.deleted' | 'webhook.delivery_success' | 'webhook.delivery_failed' | 'plugin.initialized' | 'plugin.destroyed' | 'notification.created' | 'system.startup' | 'system.shutdown';
+/**
+ * Base event payload with common fields
+ */
+interface BaseEventPayload {
+    /** Timestamp when event was emitted */
+    timestamp: Date;
+    /** User who triggered the event (if applicable) */
+    userId?: string;
+    /** IP address of the request (if applicable) */
+    ipAddress?: string;
+    /** Request ID for tracing */
+    requestId?: string;
+}
+/**
+ * Content event payload
+ */
+interface ContentEventPayload extends BaseEventPayload {
+    schema: string;
+    documentId: string;
+    locale?: string;
+}
+/**
+ * Content version event payload
+ */
+interface ContentVersionEventPayload extends ContentEventPayload {
+    version: number;
+    previousVersion?: number;
+}
+/**
+ * Field change record
+ */
+interface FieldChange {
+    field: string;
+    oldValue: unknown;
+    newValue: unknown;
+}
+/**
+ * User event payload
+ */
+interface UserEventPayload extends BaseEventPayload {
+    targetUserId: string;
+    email?: string;
+}
+/**
+ * Auth event payload
+ */
+interface AuthEventPayload extends BaseEventPayload {
+    userId: string;
+}
+/**
+ * Failed login event payload
+ */
+interface FailedLoginEventPayload extends BaseEventPayload {
+    email: string;
+    reason: 'invalid_password' | 'user_not_found' | 'account_locked' | 'email_not_verified';
+}
+/**
+ * Role event payload
+ */
+interface RoleEventPayload extends BaseEventPayload {
+    roleId: string;
+    roleName: string;
+}
+/**
+ * Settings event payload
+ */
+interface SettingsEventPayload extends BaseEventPayload {
     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 = {
+    oldValue: unknown;
+    newValue: unknown;
+}
+/**
+ * Settings group event payload
+ */
+interface SettingsGroupEventPayload extends BaseEventPayload {
+    group: string;
+    changes: Array<{
+        key: string;
+        oldValue: unknown;
+        newValue: unknown;
+    }>;
+}
+/**
+ * Media event payload
+ */
+interface MediaEventPayload extends BaseEventPayload {
+    fileId: string;
+    filename: string;
+    mimeType: string;
+    size: number;
+    folder?: string;
+}
+/**
+ * Media folder event payload
+ */
+interface MediaFolderEventPayload extends BaseEventPayload {
+    folderId: string;
+    folderName: string;
+    parentFolder?: string;
+}
+/**
+ * API Key event payload
+ */
+interface ApiKeyEventPayload extends BaseEventPayload {
+    apiKeyId: string;
     name: string;
+}
+/**
+ * Webhook event payload
+ */
+interface WebhookEventPayload extends BaseEventPayload {
+    webhookId: string;
+    url: string;
+    events: string[];
+}
+/**
+ * Webhook delivery event payload
+ */
+interface WebhookDeliveryEventPayload extends BaseEventPayload {
+    webhookId: string;
+    deliveryId: string;
+    event: string;
+    statusCode?: number;
+    duration?: number;
+}
+/**
+ * Plugin event payload
+ */
+interface PluginEventPayload extends BaseEventPayload {
+    pluginName: string;
+    version: string;
+}
+/**
+ * System event payload
+ */
+interface SystemEventPayload extends BaseEventPayload {
+    version: string;
+    environment: string;
+}
+/**
+ * Notification created event payload
+ */
+interface NotificationEventPayload extends BaseEventPayload {
+    notificationId: string;
+    targetUserId: 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[];
-};
-
+    channels: string[];
+}
 /**
- * Authenticated user returned from auth strategies
+ * Event payload map - maps event names to their payload types
  */
-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;
+interface EventPayloadMap {
+    'content.created': ContentEventPayload;
+    'content.updated': ContentEventPayload & {
+        changes: FieldChange[];
+    };
+    'content.deleted': ContentEventPayload;
+    'content.published': ContentEventPayload;
+    'content.unpublished': ContentEventPayload;
+    'content.version.created': ContentVersionEventPayload;
+    'content.version.restored': ContentVersionEventPayload;
+    'user.created': UserEventPayload;
+    'user.updated': UserEventPayload & {
+        changes: string[];
+    };
+    'user.deleted': UserEventPayload;
+    'user.registered': UserEventPayload & {
+        name?: string;
+    };
+    'user.login': UserEventPayload & {
+        sessionId?: string;
+    };
+    'user.logout': UserEventPayload & {
+        sessionId?: string;
+    };
+    'user.logout_all': UserEventPayload;
+    'user.password_changed': UserEventPayload;
+    'user.password_reset_requested': UserEventPayload & {
+        token?: string;
+        plainToken?: string;
+    };
+    'user.password_reset': UserEventPayload;
+    'user.password_reset_completed': UserEventPayload;
+    'user.email_verification_requested': UserEventPayload & {
+        name?: string;
+        verificationToken?: string;
+    };
+    'user.email_verified': UserEventPayload;
+    'user.session_revoked': UserEventPayload & {
+        sessionId: string;
+    };
+    'auth.token_refreshed': AuthEventPayload;
+    'auth.session_created': AuthEventPayload & {
+        sessionId: string;
+    };
+    'auth.session_revoked': AuthEventPayload & {
+        sessionId: string;
+        reason: string;
+    };
+    'auth.failed_login_attempt': FailedLoginEventPayload;
+    'role.created': RoleEventPayload;
+    'role.updated': RoleEventPayload;
+    'role.deleted': RoleEventPayload;
+    'role.permissions_updated': RoleEventPayload & {
+        permissions: string[];
+    };
+    'role.user_assigned': RoleEventPayload & {
+        assignedUserId: string;
+    };
+    'settings.updated': SettingsEventPayload;
+    'settings.group_updated': SettingsGroupEventPayload;
+    'media.uploaded': MediaEventPayload;
+    'media.deleted': MediaEventPayload;
+    'media.folder_created': MediaFolderEventPayload;
+    'media.folder_deleted': MediaFolderEventPayload;
+    'api_key.created': ApiKeyEventPayload;
+    'api_key.revoked': ApiKeyEventPayload & {
+        reason?: string;
+    };
+    'api_key.used': ApiKeyEventPayload & {
+        endpoint: string;
+    };
+    'webhook.created': WebhookEventPayload;
+    'webhook.updated': WebhookEventPayload;
+    'webhook.deleted': WebhookEventPayload;
+    'webhook.delivery_success': WebhookDeliveryEventPayload;
+    'webhook.delivery_failed': WebhookDeliveryEventPayload & {
+        error: string;
+    };
+    'plugin.initialized': PluginEventPayload;
+    'plugin.destroyed': PluginEventPayload;
+    'notification.created': NotificationEventPayload;
+    'system.startup': SystemEventPayload;
+    'system.shutdown': SystemEventPayload;
 }
 /**
- * Login credentials (strategy-specific)
+ * Get payload type for an event name
  */
-interface LoginCredentials {
-    email: string;
-    password: string;
-    [key: string]: unknown;
+type EventPayload<E extends EventName> = EventPayloadMap[E];
+/**
+ * Event handler function type
+ */
+type EventHandler<E extends EventName> = (payload: EventPayload<E>) => Promise<void> | void;
+/**
+ * Event handler options
+ */
+interface EventHandlerOptions {
+    /** Priority (lower runs first, default 100) */
+    priority?: number;
+    /** Whether handler should run async (non-blocking) */
+    async?: boolean;
+    /** Handler name for debugging */
+    name?: string;
 }
 /**
- * Registration data (strategy-specific)
+ * Required event handler options (after defaults applied)
  */
-interface RegisterData {
-    email: string;
-    password: string;
+interface RequiredEventHandlerOptions {
+    priority: number;
+    async: boolean;
     name: string;
-    role?: string;
-    [key: string]: unknown;
 }
 /**
- * Authentication result containing access token
+ * Registered handler with metadata
  */
-interface AuthResult {
-    access_token: string;
-    refresh_token?: string;
-    expires_in?: number;
-    token_type?: string;
+interface RegisteredHandler<E extends EventName> {
+    handler: EventHandler<E>;
+    options: RequiredEventHandlerOptions;
 }
 /**
- * JWT-specific configuration
+ * Event history entry for debugging
  */
-interface JwtAuthConfig {
-    /** JWT secret key */
-    secret: string;
-    /** Token expiration time (e.g., '7d', '1h') */
-    expiresIn?: string;
+interface EventHistoryEntry {
+    event: EventName;
+    payload: BaseEventPayload;
+    timestamp: Date;
 }
 /**
- * Auth configuration for MagnetModuleOptions
+ * Event handler metadata (used by @OnEvent decorator)
  */
-interface AuthConfig {
-    /** Strategy name to use (default: 'jwt') */
-    strategy?: string;
-    /** JWT-specific configuration */
-    jwt?: JwtAuthConfig;
-    /** Allow extensible config for custom strategies */
-    [key: string]: unknown;
+interface EventHandlerMetadata {
+    event: EventName;
+    options: EventHandlerOptions;
 }
+
 /**
- * Abstract base class for authentication strategies.
- * Similar to StorageAdapter, custom strategies must extend this class.
+ * Metadata key for event handler registration
+ */
+declare const EVENT_HANDLER_METADATA = "magnet:event_handler";
+/**
+ * Decorator to mark a method as an event handler
+ *
+ * Event handlers are automatically discovered and registered with the EventService
+ * on module initialization.
+ *
+ * @param event - The event name to listen for
+ * @param options - Optional handler configuration
  *
  * @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
+ * @Injectable()
+ * export class ActivityService {
+ *   @OnEvent('content.created', { priority: 10 })
+ *   async logContentCreated(payload: EventPayload<'content.created'>): Promise<void> {
+ *     await this.createActivityLog(payload)
  *   }
  *
- *   async validateCredentials(email: string, password: string): Promise<AuthUser | null> {
- *     // Validate user credentials
+ *   // Async handlers run in the background and don't block the request
+ *   @OnEvent('user.login', { priority: 50, async: true })
+ *   async sendWelcomeEmail(payload: EventPayload<'user.login'>): Promise<void> {
+ *     await this.emailService.sendWelcome(payload.targetUserId)
  *   }
  * }
  * ```
  */
-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;
-}
+declare function OnEvent(event: EventName, options?: EventHandlerOptions): MethodDecorator;
 
 /**
- * Plugin metadata for the @Plugin decorator
+ * Base options shared by all field decorators
  */
-interface PluginMetadata {
-    /** Unique plugin identifier (e.g., 'content-builder') */
-    name: string;
-    /** Human-readable description */
+interface BaseFieldOptions {
+    /** Field is required */
+    required?: boolean;
+    /** Field must be unique */
+    unique?: boolean;
+    /** Default value */
+    default?: unknown;
+    /** Admin UI tab placement */
+    tab?: string;
+    /** Admin UI group within tab */
+    group?: string;
+    /** Field label in admin UI */
+    label?: string;
+    /** Field description/help text */
     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>;
+    /** Field placeholder text */
+    placeholder?: string;
+    /** Hide field in admin UI */
+    hidden?: boolean;
+    /** Make field read-only in admin UI */
+    readonly?: boolean;
+    /** Field display order */
+    order?: number;
+    /** Show field in sidebar (instead of main content area) */
+    side?: boolean;
+    /** Display fields in a row layout */
+    row?: boolean;
+    /** Enable internationalization for this field */
+    intl?: boolean;
 }
 /**
- * Route definition for plugin frontend
+ * Text field options
  */
-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[];
+interface TextFieldOptions extends BaseFieldOptions {
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    transform?: 'none' | 'lowercase' | 'uppercase' | 'trim';
 }
 /**
- * Sidebar item for plugin frontend
+ * Number field options
  */
-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;
+interface NumberFieldOptions extends BaseFieldOptions {
+    min?: number;
+    max?: number;
+    integer?: boolean;
+    step?: number;
+    default?: number;
 }
 /**
- * Settings page for plugin
+ * Boolean field options
  */
-interface PluginSettingsPage {
-    /** Settings group identifier */
-    groupId: string;
-    /** Display title */
-    title: string;
-    /** Description */
-    description?: string;
-    /** Component identifier */
-    componentId: string;
+interface BooleanFieldOptions extends BaseFieldOptions {
+    default?: boolean;
+    style?: 'switch' | 'checkbox';
 }
 /**
- * Frontend manifest exposed by plugins via discovery
+ * Date field options
  */
-interface PluginFrontendManifest {
-    /** Plugin identifier */
-    pluginName: string;
-    /** Routes to register */
-    routes?: PluginRouteDefinition[];
-    /** Sidebar items */
-    sidebar?: PluginSidebarItem[];
-    /** Settings pages */
-    settings?: PluginSettingsPage[];
-    /** Required permissions */
-    permissions?: string[];
+interface DateFieldOptions extends BaseFieldOptions {
+    min?: Date | string;
+    max?: Date | string;
+    default?: Date | string | 'now' | (() => Date);
 }
 /**
- * Enriched plugin manifest with bundle URL for runtime loading
- * Returned by GET /plugins/manifests endpoint
+ * DateTime field options
  */
-interface EnrichedPluginManifest extends PluginFrontendManifest {
-    /** URL to load the plugin's frontend bundle */
-    bundleUrl: string;
+interface DateTimeFieldOptions extends DateFieldOptions {
+    timezone?: string;
 }
 /**
- * Plugin configuration passed to MagnetModule.forRoot
+ * Rich text field options
  */
-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;
+interface RichTextFieldOptions extends BaseFieldOptions {
+    toolbar?: 'minimal' | 'standard' | 'full';
+    maxLength?: number;
 }
 /**
- * Hook definition for plugins
+ * Markdown field options
  */
-interface PluginHook {
-    instance: unknown;
-    methodName: string | symbol;
+interface MarkdownFieldOptions extends BaseFieldOptions {
+    preview?: boolean;
+    maxLength?: number;
 }
 /**
- * Options for PluginModule.forRoot
+ * Code field options
  */
-interface PluginModuleOptions {
-    plugins: PluginConfig[];
+interface CodeFieldOptions extends BaseFieldOptions {
+    language?: string;
+    lineNumbers?: boolean;
 }
 /**
- * Registered plugin info returned from API
+ * JSON field options
  */
-interface RegisteredPluginInfo {
-    name: string;
-    description?: string;
-    version?: string;
-    dependencies?: string[];
-    frontend?: PluginFrontendManifest;
-    options?: Record<string, unknown>;
+interface JSONFieldOptions extends BaseFieldOptions {
+    /** Optional JSON schema for validation */
+    schema?: 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')
- *   }
- * }
- * ```
+ * Select option item
  */
-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 SelectOptionItem {
+    label: string;
+    value: string | number;
 }
-
-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[];
+/**
+ * Select field options
+ */
+interface SelectFieldOptions extends BaseFieldOptions {
+    options: ReadonlyArray<SelectOptionItem> | ReadonlyArray<string | number>;
+    default?: string | number | (string | number)[];
+    multiple?: boolean;
 }
-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;
+/**
+ * Enum field options - generic preserves enum type
+ */
+interface EnumFieldOptions<E extends Record<string, string | number> = Record<string, string | number>> extends BaseFieldOptions {
+    enum: E;
+    default?: E[keyof E];
+    multiple?: boolean;
 }
-interface R2StorageConfig extends S3StorageConfig {
-    /** Cloudflare account ID */
-    accountId: string;
+/**
+ * Tags field options
+ */
+interface TagsFieldOptions extends BaseFieldOptions {
+    suggestions?: string[];
+    maxTags?: number;
+    allowCreate?: boolean;
 }
-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;
+/**
+ * Relationship field options
+ */
+interface RelationshipFieldOptions extends BaseFieldOptions {
+    /** Reference schema name */
+    ref: string;
+    /** Allow multiple selections */
+    multiple?: boolean;
+    /** Fields to display in selection */
+    displayFields?: string[];
 }
-interface UploadOptions {
-    /** Target folder for the file */
+/**
+ * Image field options
+ */
+interface ImageFieldOptions extends BaseFieldOptions {
     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>;
+    maxSize?: number;
+    formats?: ReadonlyArray<'jpg' | 'jpeg' | 'png' | 'gif' | 'webp' | 'svg'>;
+    dimensions?: {
+        minWidth?: number;
+        maxWidth?: number;
+        minHeight?: number;
+        maxHeight?: number;
+    };
+}
+/**
+ * File field options
+ */
+interface FileFieldOptions extends BaseFieldOptions {
+    folder?: string;
+    maxSize?: number;
+    accept?: string[];
+}
+/**
+ * Gallery field options
+ */
+interface GalleryFieldOptions extends ImageFieldOptions {
+    maxItems?: number;
+}
+/**
+ * Slug field options
+ */
+interface SlugFieldOptions extends BaseFieldOptions {
+    /** Field to generate slug from */
+    from: string;
+    unique?: boolean;
+}
+/**
+ * Email field options
+ */
+interface EmailFieldOptions extends BaseFieldOptions {
+    pattern?: string;
+}
+/**
+ * URL field options
+ */
+interface URLFieldOptions extends BaseFieldOptions {
+    protocols?: string[];
+}
+/**
+ * Phone field options
+ */
+interface PhoneFieldOptions extends BaseFieldOptions {
+    defaultCountry?: string;
+}
+/**
+ * Address field options
+ */
+interface AddressFieldOptions extends BaseFieldOptions {
+    provider?: 'google' | 'mapbox' | 'none';
+}
+/**
+ * Color field options
+ */
+interface ColorFieldOptions extends BaseFieldOptions {
+    format?: 'hex' | 'rgb' | 'hsl';
+    presets?: string[];
+}
+/**
+ * Object field options
+ */
+interface ObjectFieldOptions extends BaseFieldOptions {
+    /** Optional schema for validation */
+    schema?: unknown;
+}
+/**
+ * All field type identifiers
+ */
+type FieldTypeId = 'text' | 'number' | 'boolean' | 'date' | 'datetime' | 'richtext' | 'markdown' | 'code' | 'json' | 'select' | 'enum' | 'tags' | 'image' | 'file' | 'gallery' | 'slug' | 'email' | 'url' | 'phone' | 'address' | 'color' | 'object' | 'array' | 'blocks' | 'relationship' | 'textarea';
+/**
+ * Field type definition for array items
+ */
+interface ArrayItemType {
+    type: FieldTypeId;
+    options?: BaseFieldOptions;
+}
+/**
+ * Array field options - generic preserves item type
+ */
+interface ArrayFieldOptions extends BaseFieldOptions {
+    of: ArrayItemType;
+    minItems?: number;
+    maxItems?: number;
+}
+/**
+ * Block type definition
+ */
+interface BlockTypeDefinition {
+    name: string;
+    label: string;
+    fields: Record<string, FieldTypeId>;
+}
+/**
+ * Blocks field options
+ */
+interface BlocksFieldOptions extends BaseFieldOptions {
+    types: string[];
+    maxBlocks?: number;
+}
+/**
+ * Textarea field options
+ */
+interface TextareaFieldOptions extends BaseFieldOptions {
+    minLength?: number;
+    maxLength?: number;
+    rows?: number;
+}
+/**
+ * Field metadata stored via reflection
+ */
+interface FieldMetadata<T extends BaseFieldOptions = BaseFieldOptions> {
+    /** Field type identifier */
+    type: FieldTypeId;
+    /** Typed options for this field */
+    options: T;
+    /** Property key */
+    propertyKey: string | symbol;
+    /** Target class */
+    target: Type<unknown>;
+    /** Design type from TypeScript metadata */
+    designType?: unknown;
+}
+/**
+ * Map of field type IDs to their option interfaces
+ */
+interface FieldOptionsMap {
+    text: TextFieldOptions;
+    number: NumberFieldOptions;
+    boolean: BooleanFieldOptions;
+    date: DateFieldOptions;
+    datetime: DateTimeFieldOptions;
+    richtext: RichTextFieldOptions;
+    markdown: MarkdownFieldOptions;
+    code: CodeFieldOptions;
+    json: JSONFieldOptions;
+    select: SelectFieldOptions;
+    enum: EnumFieldOptions;
+    tags: TagsFieldOptions;
+    image: ImageFieldOptions;
+    file: FileFieldOptions;
+    gallery: GalleryFieldOptions;
+    slug: SlugFieldOptions;
+    email: EmailFieldOptions;
+    url: URLFieldOptions;
+    phone: PhoneFieldOptions;
+    address: AddressFieldOptions;
+    color: ColorFieldOptions;
+    object: ObjectFieldOptions;
+    array: ArrayFieldOptions;
+    blocks: BlocksFieldOptions;
+    relationship: RelationshipFieldOptions;
+    textarea: TextareaFieldOptions;
+}
+/**
+ * Type guard to check if a value is a FieldMetadata
+ */
+declare function isFieldMetadata(value: unknown): value is FieldMetadata;
+/**
+ * Type guard to check if field type is valid
+ */
+declare function isValidFieldType(type: unknown): type is FieldTypeId;
+
+/**
+ * Type-safe field decorator factory.
+ *
+ * Creates a property decorator that:
+ * 1. Stores field metadata under FIELD_METADATA_KEY
+ * 2. Emits legacy Prop metadata for backwards compatibility
+ * 3. Emits legacy UI metadata for backwards compatibility
+ * 4. Applies the adapter-specific Prop decorator
+ *
+ * @param type - The field type identifier
+ * @param defaultOptions - Default options to merge with user-provided options
+ * @returns A function that creates a PropertyDecorator
+ */
+declare function createFieldDecorator<T extends BaseFieldOptions>(type: FieldTypeId, defaultOptions?: Partial<T>): (options?: T) => PropertyDecorator;
+/**
+ * Get all field metadata for a class.
+ *
+ * @param target - The class constructor
+ * @returns Array of field metadata entries
+ */
+declare function getFieldMetadata(target: Type<unknown>): FieldMetadata[];
+/**
+ * Get field metadata for a specific property.
+ *
+ * @param target - The class constructor
+ * @param propertyKey - The property name
+ * @returns The field metadata or undefined
+ */
+declare function getFieldMetadataForProperty(target: Type<unknown>, propertyKey: string | symbol): FieldMetadata | undefined;
+
+type ResolverOptions = {
+    schema: Type;
+};
+type ResolverInput = (() => Type) | ResolverOptions;
+type ResolveOptions = {
+    type: Type | Type[];
+    isArray?: boolean;
+    description?: string;
+};
+type ResolveInput = (() => Type | Type[]) | (() => Type)[] | ResolveOptions;
+/**
+ * Property default value - can be a primitive, object, array, or factory function
+ */
+type PropDefaultValue = string | number | boolean | null | Record<string, unknown> | unknown[] | (() => unknown);
+type PropOptions = {
+    type?: Type | Type[];
+    description?: string;
+    required?: boolean;
+    unique?: boolean;
+    default?: PropDefaultValue;
+    nullable?: boolean;
+    intl?: boolean;
+    hidden?: boolean;
+    readonly?: boolean;
+    ref?: string;
+};
+type BaseSchemaOptions = {
+    timestamps?: boolean;
+};
+type SchemaIndexOption = {
+    keys: Record<string, 1 | -1>;
+    unique?: boolean;
+};
+type SchemaOptions = {
+    versioning?: boolean;
+    i18n?: boolean;
+    /**
+     * Whether the schema is visible in the Content Manager.
+     * Set to false for system schemas that have dedicated admin pages.
+     * @default true
+     */
+    visible?: boolean;
+    /**
+     * Compound indexes (adapter-specific).
+     * Mongoose: schema.index(keys, { unique })
+     */
+    indexes?: SchemaIndexOption[];
+};
+
+/**
+ * Map field type and options to legacy Prop decorator options.
+ * This ensures backwards compatibility with existing adapters.
+ */
+declare function mapFieldTypeToProp(type: FieldTypeId, options: BaseFieldOptions): PropOptions;
+
+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;
+    placeholder?: 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;
+
+/**
+ * Map field type and options to legacy UI decorator options.
+ * This ensures backwards compatibility with existing admin UI.
+ */
+declare function mapFieldTypeToUI(type: FieldTypeId, options: BaseFieldOptions): UIDecoratorOptions;
+
+/**
+ * Field decorator namespace with full type safety.
+ *
+ * Each decorator combines @Prop and @UI functionality into a single,
+ * semantic decorator. Validation remains explicit via Field.Validators().
+ *
+ * @example
+ * ```typescript
+ * @Schema({ slug: 'posts' })
+ * export class Post {
+ *   @Field.Text({ required: true, tab: 'General' })
+ *   @Field.Validators(IsString(), Length(1, 200))
+ *   title: string
+ *
+ *   @Field.Slug({ from: 'title', unique: true })
+ *   slug: string
+ *
+ *   @Field.RichText({ toolbar: 'full' })
+ *   content?: string
+ *
+ *   @Field.Relationship({ ref: 'users', multiple: false })
+ *   author: string
+ * }
+ * ```
+ */
+declare const Field: {
+    /**
+     * Text field - single line text input
+     *
+     * @example
+     * ```typescript
+     * @Field.Text({ required: true, maxLength: 200 })
+     * title: string
+     * ```
+     */
+    readonly Text: (options?: TextFieldOptions | undefined) => PropertyDecorator;
+    /**
+     * Number field - numeric input
+     *
+     * @example
+     * ```typescript
+     * @Field.Number({ min: 0, max: 100, integer: true })
+     * quantity: number
+     * ```
+     */
+    readonly Number: (options?: NumberFieldOptions | undefined) => PropertyDecorator;
+    /**
+     * Boolean field - true/false toggle
+     *
+     * @example
+     * ```typescript
+     * @Field.Boolean({ default: false, style: 'switch' })
+     * isPublished: boolean
+     * ```
+     */
+    readonly Boolean: (options?: BooleanFieldOptions | undefined) => PropertyDecorator;
+    /**
+     * Date field - date picker (without time)
+     *
+     * @example
+     * ```typescript
+     * @Field.Date({ min: '2024-01-01' })
+     * publishDate: Date
+     * ```
+     */
+    readonly Date: (options?: DateFieldOptions | undefined) => PropertyDecorator;
+    /**
+     * DateTime field - date and time picker
+     *
+     * @example
+     * ```typescript
+     * @Field.DateTime({ timezone: 'UTC' })
+     * scheduledAt: Date
+     * ```
+     */
+    readonly DateTime: (options?: DateTimeFieldOptions | undefined) => PropertyDecorator;
+    /**
+     * RichText field - WYSIWYG editor
+     *
+     * @example
+     * ```typescript
+     * @Field.RichText({ toolbar: 'full' })
+     * content: string
+     * ```
+     */
+    readonly RichText: (options?: RichTextFieldOptions | undefined) => PropertyDecorator;
+    /**
+     * Markdown field - markdown editor with preview
+     *
+     * @example
+     * ```typescript
+     * @Field.Markdown({ preview: true })
+     * description: string
+     * ```
+     */
+    readonly Markdown: (options?: MarkdownFieldOptions | undefined) => PropertyDecorator;
+    /**
+     * Code field - code editor with syntax highlighting
+     *
+     * @example
+     * ```typescript
+     * @Field.Code({ language: 'typescript' })
+     * snippet: string
+     * ```
+     */
+    readonly Code: (options?: CodeFieldOptions | undefined) => PropertyDecorator;
+    /**
+     * JSON field - JSON editor
+     *
+     * @example
+     * ```typescript
+     * @Field.JSON()
+     * metadata: Record<string, unknown>
+     * ```
+     */
+    readonly JSON: (options?: JSONFieldOptions | undefined) => PropertyDecorator;
+    /**
+     * Textarea field - multi-line text input
+     *
+     * @example
+     * ```typescript
+     * @Field.Textarea({ rows: 5 })
+     * summary: string
+     * ```
+     */
+    readonly Textarea: (options?: TextareaFieldOptions | undefined) => PropertyDecorator;
+    /**
+     * Select field - dropdown selection
+     *
+     * @example
+     * ```typescript
+     * @Field.Select({
+     *   options: [
+     *     { label: 'Draft', value: 'draft' },
+     *     { label: 'Published', value: 'published' }
+     *   ],
+     *   default: 'draft'
+     * })
+     * status: string
+     * ```
+     */
+    readonly Select: (options: SelectFieldOptions) => PropertyDecorator;
+    /**
+     * Enum field - dropdown from TypeScript enum
+     *
+     * @example
+     * ```typescript
+     * enum Status { Draft = 'draft', Published = 'published' }
+     *
+     * @Field.Enum({ enum: Status, default: Status.Draft })
+     * status: Status
+     * ```
+     */
+    readonly Enum: <E extends Record<string, string | number>>(options: EnumFieldOptions<E>) => PropertyDecorator;
+    /**
+     * Tags field - multi-value tag input
+     *
+     * @example
+     * ```typescript
+     * @Field.Tags({ suggestions: ['tech', 'news'], maxTags: 5 })
+     * tags: string[]
+     * ```
+     */
+    readonly Tags: (options?: TagsFieldOptions | undefined) => PropertyDecorator;
+    /**
+     * Image field - single image upload
+     *
+     * @example
+     * ```typescript
+     * @Field.Image({ folder: 'covers', formats: ['jpg', 'png', 'webp'] })
+     * coverImage: string
+     * ```
+     */
+    readonly Image: (options?: ImageFieldOptions | undefined) => PropertyDecorator;
+    /**
+     * File field - single file upload
+     *
+     * @example
+     * ```typescript
+     * @Field.File({ folder: 'documents', accept: ['application/pdf'] })
+     * attachment: string
+     * ```
+     */
+    readonly File: (options?: FileFieldOptions | undefined) => PropertyDecorator;
+    /**
+     * Gallery field - multiple image upload
+     *
+     * @example
+     * ```typescript
+     * @Field.Gallery({ maxItems: 10 })
+     * images: string[]
+     * ```
+     */
+    readonly Gallery: (options?: GalleryFieldOptions | undefined) => PropertyDecorator;
+    /**
+     * Slug field - auto-generated URL-friendly string
+     *
+     * @example
+     * ```typescript
+     * @Field.Slug({ from: 'title', unique: true })
+     * slug: string
+     * ```
+     */
+    readonly Slug: (options?: SlugFieldOptions | undefined) => PropertyDecorator;
+    /**
+     * Email field - email input with validation pattern
+     *
+     * @example
+     * ```typescript
+     * @Field.Email({ required: true })
+     * @Field.Validators(IsEmail())
+     * email: string
+     * ```
+     */
+    readonly Email: (options?: EmailFieldOptions | undefined) => PropertyDecorator;
+    /**
+     * URL field - URL input
+     *
+     * @example
+     * ```typescript
+     * @Field.URL({ protocols: ['https'] })
+     * @Field.Validators(IsUrl())
+     * website: string
+     * ```
+     */
+    readonly URL: (options?: URLFieldOptions | undefined) => PropertyDecorator;
+    /**
+     * Phone field - phone number input
+     *
+     * @example
+     * ```typescript
+     * @Field.Phone({ defaultCountry: 'US' })
+     * phone: string
+     * ```
+     */
+    readonly Phone: (options?: PhoneFieldOptions | undefined) => PropertyDecorator;
+    /**
+     * Address field - address input with optional geocoding
+     *
+     * @example
+     * ```typescript
+     * @Field.Address({ provider: 'google' })
+     * address: string
+     * ```
+     */
+    readonly Address: (options?: AddressFieldOptions | undefined) => PropertyDecorator;
+    /**
+     * Color field - color picker
+     *
+     * @example
+     * ```typescript
+     * @Field.Color({ format: 'hex', presets: ['#ff0000', '#00ff00'] })
+     * brandColor: string
+     * ```
+     */
+    readonly Color: (options?: ColorFieldOptions | undefined) => PropertyDecorator;
+    /**
+     * Object field - nested object structure
+     *
+     * @example
+     * ```typescript
+     * @Field.Object()
+     * metadata: { key: string; value: string }
+     * ```
+     */
+    readonly Object: (options?: ObjectFieldOptions | undefined) => PropertyDecorator;
+    /**
+     * Array field - array of items
+     *
+     * @example
+     * ```typescript
+     * @Field.Array({ of: { type: 'text' }, maxItems: 10 })
+     * items: string[]
+     * ```
+     */
+    readonly Array: (options: ArrayFieldOptions) => PropertyDecorator;
+    /**
+     * Blocks field - flexible content blocks
+     *
+     * @example
+     * ```typescript
+     * @Field.Blocks({ types: ['paragraph', 'image', 'quote'] })
+     * content: Block[]
+     * ```
+     */
+    readonly Blocks: (options?: BlocksFieldOptions | undefined) => PropertyDecorator;
+    /**
+     * Relationship field - reference to another schema
+     *
+     * @example
+     * ```typescript
+     * @Field.Relationship({ ref: 'users', multiple: false })
+     * author: string
+     *
+     * @Field.Relationship({ ref: 'categories', multiple: true })
+     * categories: string[]
+     * ```
+     */
+    readonly Relationship: (options?: RelationshipFieldOptions | undefined) => PropertyDecorator;
+    /**
+     * Validators - apply class-validator decorators
+     *
+     * This is an alias for the existing @Validators decorator,
+     * keeping validation explicit and using familiar class-validator syntax.
+     *
+     * @example
+     * ```typescript
+     * @Field.Text({ required: true })
+     * @Field.Validators(IsString(), Length(1, 200), IsNotEmpty())
+     * title: string
+     * ```
+     */
+    readonly Validators: (...validators: PropertyDecorator[]) => <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;
+};
+/**
+ * Type for the Field namespace
+ */
+type FieldNamespace = typeof Field;
+
+/**
+ * Role-Based Access Control (RBAC) Type Definitions
+ *
+ * Type-safe permission and role management system.
+ * Used by: Permission guards, Role service, Admin UI permission matrix
+ */
+/**
+ * Permission source - where the permission was discovered from
+ */
+type PermissionSource = 'schema' | 'controller' | 'plugin' | 'manual';
+/**
+ * Permission definition - represents a single permission in the system
+ */
+interface PermissionDefinition {
+    /** Unique permission identifier (e.g., 'content.posts.create') */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Description for admin UI */
+    description?: string;
+    /** Group for organization (e.g., 'Content', 'Users', 'Settings') */
+    group?: string;
+    /** Schema name if auto-generated from schema */
+    schema?: string;
+    /** API identifier (e.g., 'api::posts', 'plugin::playground') */
+    apiId?: string;
+    /** Source of this permission */
+    source?: PermissionSource;
+    /** Controller name if discovered from controller */
+    controller?: string;
+    /** Method name if discovered from controller */
+    method?: string;
+    /** Plugin name if from plugin */
+    plugin?: string;
+}
+/**
+ * Permission item with checked state (for UI)
+ */
+interface PermissionItem {
+    /** Permission identifier */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Description */
+    description: string;
+    /** Whether this permission is enabled */
+    checked?: boolean;
+}
+/**
+ * Permission group for UI display
+ */
+interface PermissionGroup {
+    /** Group identifier */
+    id: string;
+    /** Display name */
+    name: string;
+    /** API identifier */
+    apiId?: string;
+    /** Permissions in this group */
+    permissions: PermissionItem[];
+}
+/**
+ * Permissions categorized by type
+ */
+interface CategorizedPermissions {
+    /** Permissions for collection types (schemas) */
+    collectionTypes: PermissionGroup[];
+    /** Permissions from controllers (@RequirePermission) - grouped by controller */
+    controllers: PermissionGroup[];
+    /** Permissions from plugins */
+    plugins: PermissionGroup[];
+    /** System permissions (users, settings, etc.) */
+    system: PermissionGroup[];
+}
+/**
+ * Role definition
+ */
+interface Role {
+    /** Unique role identifier */
+    id: string;
+    /** Role slug (e.g., 'admin', 'authenticated', 'editor') */
+    name: string;
+    /** Human-readable name */
+    displayName: string;
+    /** Role description */
+    description?: string;
+    /** Array of permission IDs */
+    permissions: string[];
+    /** Whether this is a system role (cannot be deleted) */
+    isSystem: boolean;
+    /** When the role was created */
+    createdAt: Date;
+    /** When the role was last updated */
+    updatedAt?: Date;
+}
+/**
+ * Role with resolved permission details for UI
+ */
+interface RoleWithPermissions extends Role {
+    /** Collection type permissions */
+    collectionTypes: PermissionGroup[];
+    /** Controller permissions (grouped by controller) */
+    controllers: PermissionGroup[];
+    /** Plugin permissions */
+    plugins: PermissionGroup[];
+    /** System permissions */
+    system: PermissionGroup[];
+}
+/**
+ * Default system role names
+ */
+type SystemRoleName = 'admin' | 'authenticated' | 'public';
+/**
+ * System role configuration
+ */
+interface SystemRoleConfig {
+    name: SystemRoleName;
+    displayName: string;
+    description: string;
+    permissions: string[];
+}
+/**
+ * Options for @RequirePermission decorator
+ */
+interface PermissionOptions {
+    /** Permission identifier (e.g., 'content.posts.create') */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Description for admin UI */
+    description?: string;
+    /** Group for organization */
+    group?: string;
+}
+/**
+ * Resolved permission after template substitution
+ */
+interface ResolvedPermission extends PermissionOptions {
+    /** Original template (if any) */
+    template?: string;
+}
+/**
+ * Create role request
+ */
+interface CreateRoleDto {
+    /** Role slug (lowercase, no spaces) */
+    name: string;
+    /** Human-readable name */
+    displayName: string;
+    /** Role description */
+    description?: string;
+    /** Initial permissions */
+    permissions?: string[];
+}
+/**
+ * Update role request
+ */
+interface UpdateRoleDto {
+    /** Human-readable name */
+    displayName?: string;
+    /** Role description */
+    description?: string;
+}
+/**
+ * Update role permissions request
+ */
+interface UpdatePermissionsDto {
+    /** Array of permission IDs to set */
+    permissions: string[];
+}
+/**
+ * Duplicate role request
+ */
+interface DuplicateRoleDto {
+    /** Name for the new role */
+    name: string;
+    /** Display name for the new role */
+    displayName?: string;
+}
+/**
+ * Assign role to user request
+ */
+interface AssignRoleDto {
+    /** Role name to assign */
+    roleName: string;
+}
+/**
+ * Permission check result
+ */
+interface PermissionCheckResult {
+    /** Whether permission is granted */
+    granted: boolean;
+    /** The permission that was checked */
+    permission: string;
+    /** User's role name */
+    role?: string;
+    /** Reason if denied */
+    reason?: string;
+}
+/**
+ * Role audit log entry
+ */
+interface RoleAuditEntry {
+    /** Action performed */
+    action: 'created' | 'updated' | 'permissions_updated' | 'deleted' | 'duplicated';
+    /** When the action occurred */
+    timestamp: Date;
+    /** User who performed the action */
+    userId?: string;
+    /** User name for display */
+    userName?: string;
+    /** Changed permissions (for permissions_updated) */
+    permissions?: {
+        added: string[];
+        removed: string[];
+    };
+}
+/**
+ * RBAC module options
+ */
+interface RBACModuleOptions {
+    /** Whether RBAC is enabled */
+    enabled?: boolean;
+    /** Default role for new users */
+    defaultRole?: string;
+    /** Whether to allow public (unauthenticated) access */
+    allowPublicAccess?: boolean;
+    /** Whether to cache permission checks */
+    cachePermissions?: boolean;
+    /** Cache TTL in seconds */
+    cacheTTL?: number;
+}
+
+/**
+ * Decorator to mark controller methods with required permissions
+ *
+ * The guard will check if the authenticated user's role has the specified permission.
+ * Supports dynamic placeholders like `{schema}` which are resolved at runtime.
+ *
+ * @param options - Permission configuration
+ *
+ * @example
+ * ```typescript
+ * // Static permission
+ * @Post()
+ * @RequirePermission({
+ *   id: 'content.posts.create',
+ *   name: 'Create Posts',
+ *   description: 'Create new blog posts',
+ *   group: 'Content'
+ * })
+ * async create(@Body() data: CreatePostDto) { ... }
+ *
+ * // Dynamic permission with schema placeholder
+ * @Get(':schema')
+ * @RequirePermission({
+ *   id: 'content.{schema}.find',
+ *   name: 'Find',
+ *   description: 'List entries',
+ * })
+ * async list(@Param('schema') schema: string) { ... }
+ * ```
+ */
+declare function RequirePermission(options: PermissionOptions): MethodDecorator;
+/**
+ * Decorator to mark methods that check permissions manually
+ *
+ * This decorator only stores the permission ID for metadata discovery.
+ * The actual permission check must be done in the method implementation.
+ *
+ * @param permission - Permission ID to check
+ *
+ * @example
+ * ```typescript
+ * @Get('sensitive-data')
+ * @HasPermission('admin.sensitive.read')
+ * async getSensitiveData(): Promise<SensitiveData> {
+ *   // Permission is checked by guard
+ *   return this.service.getSensitiveData()
+ * }
+ * ```
+ */
+declare function HasPermission(permission: string): MethodDecorator;
+/**
+ * Decorator to provide additional permission metadata
+ *
+ * Can be combined with @RequirePermission for extra configuration.
+ *
+ * @param options - Additional permission options
+ */
+declare function PermissionMeta(options: Partial<PermissionOptions>): MethodDecorator;
+/**
+ * Helper to extract permission metadata from a method
+ */
+declare function getPermissionMetadata(target: object, propertyKey: string | symbol): PermissionOptions | undefined;
+/**
+ * Helper to check if a method has permission decorator
+ */
+declare function hasPermissionDecorator(target: object, propertyKey: string | symbol): boolean;
+
+type SettingType = 'string' | 'boolean' | 'number' | 'object' | 'array';
+/**
+ * Settings object type for nested settings
+ */
+interface SettingObject {
+    [key: string]: SettingValue;
+}
+/**
+ * Settings value types - union of all possible setting values
+ * This replaces `any` in settings-related code
+ */
+type SettingValue = string | number | boolean | string[] | number[] | SettingObject | null;
+interface SchemaSetting {
+    key: string;
+    value: SettingValue;
+    type: SettingType | string;
+}
+interface SettingsFeatureOptions<T = unknown> {
+    group: string;
+    schema: new () => T;
+}
+/**
+ * Settings update payload for a single setting
+ */
+interface SettingsUpdatePayload {
+    group: string;
+    key: string;
+    value: SettingValue;
+}
+/**
+ * Settings bulk update payload
+ */
+interface SettingsBulkUpdatePayload {
+    settings: Array<{
+        key: string;
+        value: SettingValue;
+    }>;
+}
+/**
+ * Settings record type for typed settings groups
+ */
+type SettingsRecord = Record<string, SettingValue>;
+/**
+ * Section variant for special styling (e.g., danger zone)
+ */
+type SettingSectionVariant = 'default' | 'danger';
+/**
+ * Section definition for grouping settings fields visually
+ */
+interface SettingSectionDefinition {
+    /** Unique section identifier */
+    name: string;
+    /** Display label for the section */
+    label: string;
+    /** Icon identifier (lucide icon name) */
+    icon?: string;
+    /** Description of the section */
+    description?: string;
+    /** Display order within the settings group */
+    order?: number;
+    /** Visual variant for the section */
+    variant?: SettingSectionVariant;
+}
+/**
+ * Options for the @Settings() class decorator
+ */
+interface SettingsDecoratorOptions {
+    /** Unique group identifier for this settings class */
+    group: string;
+    /** Display label in admin UI */
+    label: string;
+    /** Icon identifier for admin UI */
+    icon?: string;
+    /** Description of what these settings control */
+    description?: string;
+    /** Display order in settings list */
+    order?: number;
+    /** Section definitions for grouping fields visually */
+    sections?: SettingSectionDefinition[];
+}
+/**
+ * Base options for Setting field decorators
+ */
+interface SettingFieldBaseOptions {
+    /** Display label in admin UI */
+    label: string;
+    /** Help text/description */
+    description?: string;
+    /** Default value */
+    default?: SettingValue;
+    /** Display order */
+    order?: number;
+    /** Hide from admin UI */
+    hidden?: boolean;
+    /** Make read-only in admin UI */
+    readonly?: boolean;
+    /** Section this field belongs to (references section name) */
+    section?: string;
+}
+/**
+ * Text setting field options
+ */
+interface SettingTextOptions extends SettingFieldBaseOptions {
+    default?: string;
+    minLength?: number;
+    maxLength?: number;
+    placeholder?: string;
+}
+/**
+ * Number setting field options
+ */
+interface SettingNumberOptions extends SettingFieldBaseOptions {
+    default?: number;
+    min?: number;
+    max?: number;
+    step?: number;
+}
+/**
+ * Boolean setting field options
+ */
+interface SettingBooleanOptions extends SettingFieldBaseOptions {
+    default?: boolean;
+}
+/**
+ * Select setting field options
+ */
+interface SettingSelectOptions extends SettingFieldBaseOptions {
+    options: ReadonlyArray<{
+        label: string;
+        value: string;
+    }> | ReadonlyArray<string>;
+    default?: string | string[];
+    /** Enable multi-select mode */
+    multiple?: boolean;
+}
+/**
+ * Secret setting field options (for API keys, passwords, etc.)
+ */
+interface SettingSecretOptions extends SettingFieldBaseOptions {
+    /** Mask value in UI (show only last 4 characters) */
+    masked?: boolean;
+}
+/**
+ * Image setting field options
+ */
+interface SettingImageOptions extends SettingFieldBaseOptions {
+    folder?: string;
+    maxSize?: number;
+}
+/**
+ * JSON setting field options
+ */
+interface SettingJSONOptions extends SettingFieldBaseOptions {
+    default?: SettingObject;
+}
+/**
+ * Setting field type identifiers
+ */
+type SettingFieldTypeId = 'text' | 'number' | 'boolean' | 'select' | 'secret' | 'image' | 'json' | 'textarea';
+/**
+ * Setting field metadata stored via reflection
+ */
+interface SettingFieldMetadata<T extends SettingFieldBaseOptions = SettingFieldBaseOptions> {
+    /** Field type identifier */
+    type: SettingFieldTypeId;
+    /** Typed options for this field */
+    options: T;
+    /** Property key */
+    propertyKey: string | symbol;
+}
+/**
+ * Type guard to check if a value is SettingFieldMetadata
+ */
+declare function isSettingFieldMetadata(value: unknown): value is SettingFieldMetadata;
+
+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?: unknown[];
+};
+type SchemaProperty = {
+    name: string;
+    type: string;
+    isArray: boolean;
+    unique: boolean;
+    required: boolean;
+    validations: SchemaPropertyValidation[];
+    ui?: UIDecoratorOptions;
+    ref?: string;
+};
+type SchemaMetadata = {
+    name: string;
+    className?: string;
+    apiName?: string;
+    displayName?: string;
+    properties: SchemaProperty[];
+    options?: SchemaOptions;
+    /** Settings-specific options (only present for settings schemas) */
+    settingsOptions?: SettingsDecoratorOptions;
+};
+
+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;
+}
+/**
+ * Supabase-specific auth configuration
+ */
+interface SupabaseAuthConfig {
+    /** Supabase project URL */
+    supabaseUrl: string;
+    /** Supabase anon/public key */
+    supabaseKey: string;
+    /** Default role for new users */
+    defaultRole?: string;
+}
+/**
+ * Auth configuration for MagnetModuleOptions
+ */
+interface AuthConfig {
+    /** Strategy name to use (default: 'jwt') */
+    strategy?: string;
+    /** JWT-specific configuration */
+    jwt?: JwtAuthConfig;
+    /** Supabase-specific configuration (when strategy: 'supabase') */
+    supabaseUrl?: string;
+    /** Supabase anon/public key */
+    supabaseKey?: string;
+    /** Supabase service role key (required for admin operations like listUsers) */
+    supabaseServiceKey?: string;
+    /** Default role for new Supabase users */
+    defaultRole?: string;
+    /** Allow extensible config for custom strategies */
+    [key: string]: unknown;
+}
+/**
+ * Information about the active authentication strategy, including
+ * whether it's an external provider and what OAuth providers it has configured.
+ *
+ * Returned by `AuthStrategy.getAuthInfo()` for external adapters (Supabase, Clerk, etc.).
+ */
+interface ExternalAuthInfo {
+    /** Strategy identifier (e.g., 'supabase', 'clerk', 'jwt') */
+    strategy: string;
+    /** Whether authentication is handled by an external provider */
+    isExternal: boolean;
+    /** List of OAuth provider names configured in the external service (e.g., ['google', 'github']) */
+    providers: string[];
+    /** Additional provider-specific settings (e.g., disable_signup, autoconfirm) */
+    providerSettings?: Record<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>;
+    /**
+     * Check if any users exist in the system (optional)
+     * Strategies that manage their own user storage should implement this.
+     * If not implemented, AuthService will fall back to checking the local database.
+     * @returns true if users exist, false otherwise
+     */
+    hasUsers?(): Promise<boolean>;
+    /**
+     * Get information about the auth strategy and its configured providers (optional).
+     * External adapters (Supabase, Clerk) implement this to report which OAuth
+     * providers are configured on their side. If not implemented, the strategy
+     * is assumed to be built-in (JWT).
+     * @returns Auth info including strategy name, external flag, and provider list
+     */
+    getAuthInfo?(): Promise<ExternalAuthInfo>;
+    /**
+     * Get the Passport strategy name (for guards)
+     * Returns the name to use with AuthGuard()
+     */
+    getPassportStrategyName(): string;
+}
+
+/**
+ * SMTP configuration for Nodemailer adapter
+ */
+interface NodemailerConfig {
+    /** SMTP server hostname */
+    host: string;
+    /** SMTP server port (default: 587) */
+    port?: number;
+    /** Use TLS (default: true for port 465, false otherwise) */
+    secure?: boolean;
+    /** SMTP authentication credentials */
+    auth: {
+        /** SMTP username */
+        user: string;
+        /** SMTP password */
+        pass: string;
+    };
+    /** Connection timeout in milliseconds */
+    connectionTimeout?: number;
+    /** Greeting timeout in milliseconds */
+    greetingTimeout?: number;
+    /** Socket timeout in milliseconds */
+    socketTimeout?: number;
+}
+/**
+ * Resend API configuration
+ */
+interface ResendConfig {
+    /** Resend API key */
+    apiKey: string;
+}
+/**
+ * Email adapter name type — extensible for custom adapters
+ */
+type EmailAdapterName = 'nodemailer' | 'resend' | (string & {});
+/**
+ * Email system configuration for MagnetModuleOptions
+ */
+interface EmailConfig {
+    /** Which email adapter to use */
+    adapter: EmailAdapterName;
+    /** Nodemailer SMTP configuration (when adapter is 'nodemailer') */
+    nodemailer?: NodemailerConfig;
+    /** Resend API configuration (when adapter is 'resend') */
+    resend?: ResendConfig;
+    /** Default email settings */
+    defaults?: {
+        /** Default sender email address */
+        from?: string;
+        /** Default reply-to address */
+        replyTo?: string;
+    };
+}
+/**
+ * Email attachment
+ */
+interface EmailAttachment {
+    /** Attachment filename */
+    filename: string;
+    /** Attachment content (Buffer, string, or URL) */
+    content: Buffer | string;
+    /** MIME type of the attachment */
+    contentType?: string;
+    /** Content disposition (default: 'attachment') */
+    disposition?: 'attachment' | 'inline';
+    /** Content ID for inline attachments */
+    cid?: string;
+}
+/**
+ * Options for sending an email
+ */
+interface SendEmailOptions {
+    /** Recipient email address(es) */
+    to: string | string[];
+    /** Sender email address (overrides default) */
+    from?: string;
+    /** Email subject line */
+    subject: string;
+    /** HTML body content */
+    html?: string;
+    /** Plain text body content */
+    text?: string;
+    /** Reply-to address (overrides default) */
+    replyTo?: string;
+    /** CC recipients */
+    cc?: string | string[];
+    /** BCC recipients */
+    bcc?: string | string[];
+    /** Email attachments */
+    attachments?: EmailAttachment[];
+    /** Custom headers */
+    headers?: Record<string, string>;
+    /** Tags for categorization (supported by some providers) */
+    tags?: Array<{
+        name: string;
+        value: string;
+    }>;
+}
+/**
+ * Result of sending an email
+ */
+interface SendEmailResult {
+    /** Provider-assigned message ID */
+    id?: string;
+    /** Whether the email was accepted for delivery */
+    accepted: boolean;
+    /** List of accepted recipient addresses */
+    acceptedAddresses?: string[];
+    /** List of rejected recipient addresses */
+    rejectedAddresses?: string[];
+    /** Error message if sending failed */
+    error?: string;
+}
+/**
+ * Abstract base class for email adapters.
+ *
+ * All email providers must extend this class and implement the abstract methods.
+ * Follows the same pattern as `StorageAdapter` and `DatabaseAdapter`.
+ *
+ * @example
+ * ```typescript
+ * export class NodemailerEmailAdapter extends EmailAdapter {
+ *   readonly name = 'nodemailer'
+ *
+ *   async send(options: SendEmailOptions): Promise<SendEmailResult> {
+ *     // Send via SMTP using Nodemailer
+ *   }
+ *
+ *   async sendBatch(emails: SendEmailOptions[]): Promise<SendEmailResult[]> {
+ *     return Promise.all(emails.map(email => this.send(email)))
+ *   }
+ *
+ *   async verify(): Promise<boolean> {
+ *     // Test SMTP connection
+ *   }
+ * }
+ * ```
+ */
+declare abstract class EmailAdapter {
+    /**
+     * Unique identifier for this adapter
+     */
+    abstract readonly name: string;
+    /**
+     * Send a single email
+     * @param options - Email send options (to, subject, html, etc.)
+     * @returns Result with delivery status
+     */
+    abstract send(options: SendEmailOptions): Promise<SendEmailResult>;
+    /**
+     * Send multiple emails in batch
+     * @param emails - Array of email options
+     * @returns Array of results (one per email)
+     */
+    abstract sendBatch(emails: SendEmailOptions[]): Promise<SendEmailResult[]>;
+    /**
+     * Verify the adapter connection/configuration
+     * @returns true if the adapter is properly configured and can send emails
+     */
+    abstract verify(): Promise<boolean>;
+    /**
+     * Optional cleanup/disconnect method
+     */
+    dispose?(): Promise<void>;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+    /**
+     * Execute with pagination info
+     * @param page Page number (1-indexed)
+     * @param perPage Items per page
+     * @returns Data array with pagination metadata
+     */
+    abstract paginate(page?: number, perPage?: number): Promise<PaginatedResult<BaseSchema<Schema>>>;
+    /**
+     * Select specific fields to return (inclusion)
+     * @param projection Field selection (1 to include, 0 to exclude)
+     */
+    abstract select(projection: ProjectionQuery<Schema>): this;
+    /**
+     * Exclude specific fields from results
+     * @param fields Array of field names to exclude
+     */
+    exclude(fields: (keyof Schema | string)[]): this;
+    /**
+     * 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;
+    /**
+     * 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>;
+}
+
+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;
+}
+/**
+ * Version document type for history/versioning
+ */
+interface VersionDocument {
+    /** ID of the original document */
+    documentId: string;
+    /** Unique version identifier */
+    versionId: string;
+    /** Name of the schema/collection */
+    schemaName: string;
+    /** Version status */
+    status: 'draft' | 'published' | 'archived';
+    /** Snapshot of the document data at this version */
+    data: Record<string, unknown>;
+    /** When this version was created */
+    createdAt: Date;
+    /** Who created this version */
+    createdBy?: string;
+    /** Type of change that created this version */
+    changeType?: 'create' | 'update' | 'restore';
+}
+/**
+ * Native access wrapper - provides type-safe native operations
+ */
+interface NativeAccess<T> {
+    /**
+     * Raw database/ORM instance (type varies by adapter)
+     * For Mongoose: Model<Document>
+     * For Drizzle: { db, table }
+     */
+    readonly raw: unknown;
+    /**
+     * Execute raw query (adapter-specific syntax)
+     * @param query - The raw query string
+     * @param params - Query parameters
+     */
+    rawQuery<R = unknown>(query: string, params?: unknown[]): Promise<R>;
+    /**
+     * Get adapter name for adapter-specific code
+     */
+    readonly adapterName: AdapterName;
+}
+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
+     * @returns Cloned model instance with locale set
+     */
+    abstract locale(locale: string): this;
+    /**
+     * Get current locale
+     */
+    getLocale(): string;
+    /**
+     * Set the version for subsequent operations
+     * @param versionId The version ID or status ('draft', 'published', 'archived')
+     * @returns Same instance (chainable)
+     */
+    version(versionId: string): this;
+    /**
+     * Check if versioning is enabled for this model
+     */
+    isVersioningEnabled(): boolean;
+    /**
+     * Create a version snapshot of a document
+     * @param documentId The document ID
+     * @param data The data to version
+     * @returns Version record or null if versioning disabled
+     */
+    createVersion(documentId: string, data: Partial<Schema>): Promise<VersionDocument | null>;
+    /**
+     * Find all versions of a document
+     * @param documentId The document ID
+     */
+    findVersions(documentId: string): Promise<VersionDocument[]>;
+    /**
+     * Find a specific version by ID
+     * @param versionId The version ID
+     */
+    findVersionById(versionId: string): Promise<VersionDocument | null>;
+    /**
+     * Restore a document to a specific 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 Typed native access object
+     */
+    native(): NativeAccess<Schema>;
+    /**
+     * Get schema name
+     */
+    getSchemaName(): string;
+    /**
+     * Get schema metadata
+     */
+    getMetadata(): SchemaMetadata;
+}
+
+declare class Mixed {
+    static schemaName: 'Mixed';
+    defaultOptions: Record<string, unknown>;
+}
+
+type MongooseConfig = {
+    uri: string;
+};
+/**
+ * Drizzle ORM configuration for SQL databases.
+ * Supports PostgreSQL, MySQL, and SQLite through Drizzle ORM.
+ */
+type DrizzleConfig = {
+    /** Database connection string */
+    connectionString: string;
+    /** SQL dialect to use */
+    dialect: 'postgresql' | 'mysql' | 'sqlite';
+    /** Database driver to use (auto-detected if not specified) */
+    driver?: 'pg' | 'neon' | 'mysql2' | 'better-sqlite3';
+    /** Enable debug logging */
+    debug?: boolean;
+    /**
+     * Migration configuration. If omitted, falls back to legacy CREATE TABLE IF NOT EXISTS behavior.
+     */
+    migrations?: {
+        /** Migration mode — 'auto' for development, 'manual' for production */
+        mode?: 'auto' | 'manual';
+        /** Directory where migration files are stored (default: './migrations') */
+        directory?: string;
+        /** Table name for tracking applied migrations (default: '_magnet_migrations') */
+        tableName?: string;
+        /** Whether to run each migration in a transaction (default: true) */
+        transactional?: boolean;
+    };
+};
+type DBConfig = MongooseConfig | DrizzleConfig;
+/**
+ * Database model instance type - the native model from the adapter
+ * This could be a Mongoose Model, Drizzle table, or other adapter-specific type
+ */
+type DatabaseModelInstance = unknown;
+/**
+ * Model class constructor returned by adapter.model()
+ */
+type ModelClass<T> = new () => Model<T>;
+/**
+ * Supported adapter names
+ */
+type AdapterName = 'mongoose' | 'drizzle' | 'prisma' | 'typeorm';
+/**
+ * Features an adapter may support
+ */
+type AdapterFeature = 'transactions' | 'nested-transactions' | 'json-queries' | 'full-text-search' | 'geospatial' | 'change-streams' | 'migrations';
+/**
+ * Database types supported by adapters
+ */
+type DatabaseType = 'mongodb' | 'postgresql' | 'mysql' | 'sqlite' | 'mssql';
+/**
+ * Adapter capability declaration
+ */
+interface AdapterCapabilities {
+    /** Supported database types */
+    databases: DatabaseType[];
+    /** Supported features */
+    features: AdapterFeature[];
+    /** Whether adapter handles its own versioning */
+    handlesVersioning: boolean;
+    /** Whether adapter supports lazy table/collection creation */
+    supportsLazyCreation: boolean;
+}
+/**
+ * Database adapter contract - all adapters MUST implement this interface
+ */
+declare abstract class DatabaseAdapter implements OnModuleDestroy {
+    /**
+     * Adapter identifier
+     */
+    abstract readonly name: AdapterName;
+    /**
+     * Connect to database and return NestJS dynamic module.
+     * @param config - Database configuration (MongooseConfig or DrizzleConfig)
+     */
+    abstract connect(config: DBConfig): DynamicModule;
+    /**
+     * Register schemas as features
+     */
+    abstract forFeature(schemas: Type | Type[]): DynamicModule;
+    /**
+     * Create a Model class for the given native model instance
+     * @param modelInstance - The native model instance from the database driver
+     * @returns A Model class constructor that can be instantiated
+     */
+    abstract model<T>(modelInstance: DatabaseModelInstance): ModelClass<T>;
+    /**
+     * Get injection token for a schema
+     */
+    abstract token(schema: string): string;
+    /**
+     * Cleanup on module destroy
+     */
+    abstract onModuleDestroy(): Promise<void>;
+    /**
+     * Check if adapter supports a feature
+     */
+    abstract supports(feature: AdapterFeature): boolean;
+    /**
+     * Get adapter capabilities
+     */
+    abstract getCapabilities(): AdapterCapabilities;
+}
+
+/**
+ * Plugin metadata for the @Plugin decorator
+ */
+interface PluginMetadata {
+    /** Unique plugin identifier (e.g., 'playground') */
+    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 SupabaseStorageConfig {
+    /** Supabase project URL */
+    supabaseUrl: string;
+    /** Supabase service role key (required for storage operations) */
+    supabaseKey: string;
+    /** Storage bucket name */
+    bucket: string;
+    /** Public URL for the bucket (optional, uses Supabase URL if not provided) */
+    publicUrl?: string;
+}
+interface StorageConfig {
+    /** Storage adapter to use */
+    adapter: 'local' | 's3' | 'r2' | 'supabase';
+    /** Local storage configuration */
+    local?: LocalStorageConfig;
+    /** S3 storage configuration */
+    s3?: S3StorageConfig;
+    /** R2 storage configuration */
+    r2?: R2StorageConfig;
+    /** Supabase storage configuration */
+    supabase?: SupabaseStorageConfig;
+}
+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 */
@@ -564,489 +2697,1549 @@ interface PaginatedMedia<T = UploadResult> {
     /** Total number of pages */
     totalPages: number;
 }
-declare abstract class StorageAdapter {
+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>;
+}
+
+type VaultAdapterType = 'db' | 'hashicorp' | 'supabase';
+/**
+ * Token-based authentication for HashiCorp Vault.
+ * Token is read from VAULT_TOKEN env var.
+ */
+interface VaultTokenAuth {
+    type: 'token';
+    token: string;
+}
+/**
+ * AppRole-based authentication for HashiCorp Vault.
+ */
+interface VaultAppRoleAuth {
+    type: 'appRole';
+    roleId: string;
+    secretId?: string;
+}
+type VaultAuthConfig = VaultTokenAuth | VaultAppRoleAuth;
+/**
+ * Configuration for the HashiCorp Vault adapter.
+ */
+interface HashiCorpVaultConfig {
+    /** Vault server URL (e.g., 'https://vault.example.com:8200'). Defaults to VAULT_ADDR env var. */
+    url?: string;
+    /** Authentication configuration. Defaults to VAULT_TOKEN env var. */
+    auth?: VaultAuthConfig;
+    /** Secrets engine mount path (default: 'secret') */
+    mountPath?: string;
+    /** Vault Enterprise namespace (optional) */
+    namespace?: string;
+}
+/**
+ * Configuration for the Supabase Vault adapter.
+ */
+interface SupabaseVaultConfig {
+    /** Supabase project URL */
+    supabaseUrl: string;
+    /** Supabase service role key (required for vault operations) */
+    supabaseServiceKey: string;
+}
+/**
+ * Top-level vault configuration passed to MagnetModuleOptions.
+ */
+interface VaultConfig {
+    /** Vault adapter to use (default: 'db') */
+    adapter?: VaultAdapterType;
+    /** Cache TTL in seconds (default: 300) */
+    cacheTtl?: number;
+    /** HashiCorp Vault adapter configuration */
+    hashicorp?: HashiCorpVaultConfig;
+    /** Supabase Vault adapter configuration */
+    supabase?: SupabaseVaultConfig;
+}
+/**
+ * Abstract base class for vault adapters.
+ *
+ * All adapters encrypt secrets at rest. Implementations determine
+ * the storage backend (app DB, HashiCorp Vault, Supabase Vault).
+ */
+declare abstract class VaultAdapter {
+    /**
+     * Retrieve a secret value by key.
+     * @returns The decrypted string value or null if not found
+     */
+    abstract get(key: string): Promise<string | null>;
+    /**
+     * Store or update a secret.
+     *
+     * @param key - Secret identifier
+     * @param value - Plaintext value to encrypt and store
+     * @param description - Optional human-readable description (stored unencrypted)
+     */
+    abstract set(key: string, value: string, description?: string): Promise<void>;
+    /**
+     * Delete a secret by key.
+     */
+    abstract delete(key: string): Promise<void>;
+    /**
+     * List all secrets with their metadata, optionally filtered by prefix.
+     */
+    abstract list(prefix?: string): Promise<VaultSecretMeta[]>;
+    /**
+     * Check the health of the vault backend.
+     */
+    abstract healthCheck(): Promise<boolean>;
+}
+/** Lightweight metadata returned by list() — does not include the secret value. */
+interface VaultSecretMeta {
+    name: string;
+    description?: string;
+    /** ISO date string when the secret was last updated (adapter-dependent) */
+    lastUpdated?: string;
+}
+interface VaultStatusResponse {
+    /** Whether the vault adapter is healthy */
+    healthy: boolean;
+    /** The adapter type in use */
+    adapter: VaultAdapterType;
+    /** Whether VAULT_MASTER_KEY is set (db adapter only) */
+    masterKeyConfigured?: boolean;
+}
+interface VaultSecretListResponse {
+    secrets: VaultSecretMeta[];
+}
+
+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;
+}
+interface AdminConfig {
+    /** Enable static admin serving (default true when omitted) */
+    enabled?: boolean;
+    /** Path to serve admin UI (default: '/admin') */
+    path?: string;
+    /** Custom path to admin dist folder */
+    distPath?: string;
+}
+declare class MagnetModuleOptions {
+    db: DBConfig;
+    jwt: {
+        secret: string;
+    };
+    /**
+     * Auth configuration (optional, uses JWT by default)
+     */
+    auth?: AuthConfig;
+    internationalization?: InternationalizationOptions;
+    playground?: PlaygroundOptions;
+    storage?: StorageConfig;
+    /**
+     * Email adapter configuration
+     * @example
+     * email: { adapter: 'nodemailer', nodemailer: { host: 'smtp.example.com', port: 587, auth: { user: 'user', pass: 'pass' } } }
+     */
+    email?: EmailConfig;
+    /**
+     * Plugins to load with the Magnet module
+     */
+    plugins?: PluginConfig[];
+    /**
+     * Admin panel configuration (enabled by default when omitted).
+     * @example
+     * // Explicit enable (same as omitting `admin`)
+     * admin: true
+     *
+     * // Custom path
+     * admin: { enabled: true, path: '/dashboard' }
+     *
+     * // Disable (for API-only mode)
+     * admin: false
+     */
+    admin?: boolean | AdminConfig;
+    /**
+     * RBAC (Role-Based Access Control) configuration
+     * @example
+     * rbac: { enabled: true, defaultRole: 'authenticated' }
+     */
+    rbac?: RBACModuleOptions;
+    /**
+     * Vault configuration for encrypted secrets management.
+     * Uses the built-in DB adapter by default (requires VAULT_MASTER_KEY env var).
+     * @example
+     * vault: { adapter: 'db' }
+     * vault: { adapter: 'hashicorp', hashicorp: { url: 'https://vault.example.com:8200' } }
+     */
+    vault?: VaultConfig;
+    constructor({ db, jwt, auth, internationalization, playground, storage, email, plugins, admin, rbac, vault, }: MagnetModuleOptions);
+}
+type MagnetModuleOptionsAsync = {
+    useFactory: (...args: unknown[]) => 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: unknown[];
+}[];
+
+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;
+}
+
+/** Log severity levels, ordered from most critical to most verbose. */
+type LogLevel = 'error' | 'warn' | 'info' | 'debug' | 'verbose';
+/** Structured metadata attached to a log entry. */
+interface LogMetadata {
+    operation?: string;
+    schema?: string;
+    resourceId?: string;
+    duration?: number;
+    method?: string;
+    path?: string;
+    statusCode?: number;
+    [key: string]: unknown;
+}
+/** Serialized error information for structured logging. */
+interface ErrorLogData {
+    name: string;
+    message: string;
+    code?: string;
+    stack?: string;
+}
+/** A single structured log entry. */
+interface LogEntry {
+    level: LogLevel;
+    message: string;
+    timestamp: string;
+    context: string;
+    requestId?: string;
+    userId?: string;
+    metadata?: LogMetadata;
+    error?: ErrorLogData;
+}
+/** Configuration for MagnetLogger, read from environment variables. */
+interface LoggerConfig {
+    /** Minimum log level to output. Default: 'info' */
+    level: LogLevel;
+    /** Output format. Default: 'pretty' */
+    format: 'json' | 'pretty';
+    /** Whether to include timestamps. Default: true */
+    timestamps: boolean;
+    /** Whether to include error stack traces. Default: true */
+    stackTraces: boolean;
+    /** Field names to redact from metadata. */
+    redactFields: string[];
+}
+
+/**
+ * Notification System Type Definitions
+ *
+ * Shared types used by core backend and admin client for the notifications system.
+ */
+/**
+ * Available notification delivery channels.
+ * - `platform`: Persists notification in DB, shown in admin drawer.
+ * - `email`: Sends an email to the user (requires an adapter registered).
+ */
+type NotificationChannel = 'platform' | 'email';
+/**
+ * Result of delivering a notification via a single channel.
+ */
+interface NotificationChannelResult {
+    channel: NotificationChannel;
+    success: boolean;
+    error?: string;
+}
+/**
+ * Interface that any notification channel adapter must implement.
+ * Register adapters in `NotificationModule.forRoot({ adapters: [...] })`.
+ */
+interface NotificationChannelAdapter {
+    /** Which channel this adapter handles */
+    readonly channel: NotificationChannel;
     /**
-     * Initialize the storage adapter (create directories, check connections)
+     * Deliver a notification to a recipient.
+     * @param payload - Notification data to send
+     * @param recipient - Target user info (userId always present; email populated when available)
      */
-    abstract initialize(): Promise<void>;
+    send(payload: NotificationSendPayload, recipient: NotificationRecipient): Promise<NotificationChannelResult>;
+}
+/**
+ * Minimal notification data passed to channel adapters for delivery.
+ */
+interface NotificationSendPayload {
+    id: string;
+    type: string;
+    title: string;
+    message: string;
+    href?: string;
+    metadata?: Record<string, unknown>;
+    createdAt: Date;
+}
+/**
+ * Recipient info resolved when delivering a notification.
+ */
+interface NotificationRecipient {
+    userId: string;
+    email?: string;
+    name?: string;
+}
+/**
+ * DTO used to send a notification through NotificationService.notify().
+ */
+interface NotifyDto {
+    /** Target user ID. Can be a single user or a list for bulk delivery. */
+    userId: string | string[];
     /**
-     * Upload a file to storage
-     * @param file - File buffer or readable stream
-     * @param originalFilename - Original filename from user
-     * @param options - Upload options
+     * Which channels to deliver to.
+     * Defaults to `['platform']` when not specified.
      */
-    abstract upload(file: Buffer | Readable, originalFilename: string, options?: UploadOptions): Promise<UploadResult>;
+    channels?: NotificationChannel[];
     /**
-     * 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
+     * Notification category / type identifier.
+     * Useful for filtering and icon mapping in the UI.
      */
-    abstract uploadChunked(stream: Readable, originalFilename: string, totalSize: number, options?: UploadOptions): Promise<UploadResult>;
+    type: string;
+    /** Short title shown in the notification list. */
+    title: string;
+    /** Longer description or body of the notification. */
+    message: string;
+    /** Optional link the user will be taken to when clicking the notification. */
+    href?: string;
     /**
-     * Delete a file from storage
-     * @param path - Storage path or key of the file
+     * Additional arbitrary metadata stored with the notification.
+     * Not shown directly in UI but available for custom logic.
      */
-    abstract delete(path: string): Promise<boolean>;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Options for querying a user's notifications.
+ */
+interface NotificationQueryOptions {
+    /** Filter to only unread notifications. */
+    unreadOnly?: boolean;
+    /** Maximum number of results. Defaults to 20. */
+    limit?: number;
+    /** Number of results to skip for pagination. */
+    offset?: number;
+}
+/**
+ * Paginated response for notification lists.
+ */
+interface PaginatedNotifications<T> {
+    items: T[];
+    total: number;
+    unreadCount: number;
+    limit: number;
+    offset: number;
+}
+
+/**
+ * Result of a cache health check
+ */
+interface CacheHealthResult {
+    /** Whether the cache adapter is healthy and reachable */
+    healthy: boolean;
+    /** Optional message with details about the health status */
+    message?: string;
+}
+/**
+ * Abstract base class for cache adapters.
+ *
+ * All cache providers must extend this class and implement the abstract methods.
+ * Follows the same pattern as `StorageAdapter`, `EmailAdapter`, and `DatabaseAdapter`.
+ *
+ * @example
+ * ```typescript
+ * export class MemoryCacheAdapter extends CacheAdapter {
+ *   readonly name = 'memory'
+ *
+ *   async get<T>(key: string): Promise<T | null> {
+ *     // Return cached value or null
+ *   }
+ *
+ *   async set<T>(key: string, value: T, ttl?: number): Promise<void> {
+ *     // Store value with optional TTL in seconds
+ *   }
+ *
+ *   // ... other methods
+ * }
+ * ```
+ */
+declare abstract class CacheAdapter {
     /**
-     * Delete multiple files from storage
-     * @param paths - Array of storage paths or keys
+     * Unique identifier for this adapter
      */
-    abstract deleteMany(paths: string[]): Promise<{
-        deleted: number;
-        failed: string[];
-    }>;
+    abstract readonly name: string;
     /**
-     * Get the public URL for a file
-     * @param path - Storage path or key
-     * @param transform - Optional transform options for images
+     * Retrieve a cached value by key.
+     * @param key - Cache key
+     * @returns The cached value, or null if not found or expired
      */
-    abstract getUrl(path: string, transform?: TransformOptions): string;
+    abstract get<T>(key: string): Promise<T | null>;
     /**
-     * Get a readable stream for a file
-     * @param path - Storage path or key
+     * Store a value in the cache.
+     * @param key - Cache key
+     * @param value - Value to cache (must be JSON-serializable)
+     * @param ttl - Time-to-live in seconds. If omitted, uses adapter default.
      */
-    abstract getStream(path: string): Promise<Readable>;
+    abstract set<T>(key: string, value: T, ttl?: number): Promise<void>;
     /**
-     * Get the file as a buffer
-     * @param path - Storage path or key
+     * Remove a value from the cache by key.
+     * @param key - Cache key to delete
      */
-    abstract getBuffer(path: string): Promise<Buffer>;
+    abstract delete(key: string): Promise<void>;
     /**
-     * Check if a file exists
-     * @param path - Storage path or key
+     * Remove all cache entries matching a glob pattern.
+     * Supports `*` wildcards (e.g., `content:posts:*` removes all post entries).
+     * @param pattern - Glob pattern to match keys against
      */
-    abstract exists(path: string): Promise<boolean>;
+    abstract deleteByPattern(pattern: string): Promise<void>;
     /**
-     * Get a transformed version of an image
-     * @param path - Storage path or key
-     * @param options - Transform options
+     * Check if a key exists in the cache (and has not expired).
+     * @param key - Cache key to check
+     * @returns true if the key exists and is not expired
      */
-    abstract transform(path: string, options: TransformOptions): Promise<Buffer>;
+    abstract has(key: string): Promise<boolean>;
     /**
-     * Move/rename a file
-     * @param path - Current storage path or key
-     * @param newPath - New storage path or key
+     * Remove all entries from the cache.
+     * For Redis, only clears keys within this adapter's key prefix.
      */
-    move?(path: string, newPath: string): Promise<UploadResult>;
+    abstract clear(): Promise<void>;
     /**
-     * Copy a file
-     * @param path - Source storage path or key
-     * @param newPath - Destination storage path or key
+     * Check the health of the cache backend.
+     * @returns Health result with status and optional message
      */
-    copy?(path: string, newPath: string): Promise<UploadResult>;
+    abstract healthCheck(): Promise<CacheHealthResult>;
     /**
-     * Generate a signed URL for temporary access (for S3/R2)
-     * @param path - Storage path or key
-     * @param expiresIn - Expiration time in seconds
+     * Optional cleanup/disconnect method.
+     * Called when the module is destroyed.
      */
-    signedUrl?(path: string, expiresIn?: number): Promise<string>;
+    dispose?(): Promise<void>;
 }
 
-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;
+/**
+ * Declares a required or optional environment variable for an adapter/plugin.
+ * Used by MagnetModule to validate all env vars before NestJS bootstraps.
+ */
+interface EnvVarRequirement {
+    /** Environment variable name (e.g., 'DATABASE_URL') */
+    name: string;
+    /** Whether this env var is required for the adapter to function */
+    required: boolean;
+    /** Human-readable description shown in error messages */
+    description?: string;
 }
-declare class MagnetModuleOptions {
-    db: DBConfig;
-    jwt: {
-        secret: string;
+/**
+ * Global configuration options passed as the second argument to MagnetModule.forRoot().
+ * Contains cross-cutting settings that don't belong to any specific adapter.
+ *
+ * @example
+ * ```typescript
+ * MagnetModule.forRoot([...providers], {
+ *   jwt: { secret: 'my-secret' },
+ *   admin: true,
+ *   rbac: { enabled: true },
+ * })
+ * ```
+ */
+interface MagnetGlobalOptions {
+    /** JWT configuration for authentication */
+    jwt?: {
+        /** JWT signing secret. Auto-resolved from JWT_SECRET env var if not provided. */
+        secret?: string;
+        /** Token expiration time (e.g., '7d', '1h'). Default: '7d' */
+        expiresIn?: string;
     };
     /**
-     * Auth configuration (optional, uses JWT by default)
+     * Admin panel configuration (enabled by default when omitted).
+     * @example admin: false // API-only / headless
+     * @example admin: { enabled: true, path: '/dashboard' }
      */
-    auth?: AuthConfig;
+    admin?: boolean | AdminConfig;
+    /** RBAC (Role-Based Access Control) configuration */
+    rbac?: RBACModuleOptions;
+    /** Internationalization settings */
     internationalization?: InternationalizationOptions;
+    /** Global Playground (schema builder) settings */
     playground?: PlaygroundOptions;
-    storage?: StorageConfig;
+}
+/**
+ * Base interface for all Magnet providers.
+ * Every adapter and plugin declares its environment variable requirements.
+ */
+interface BaseMagnetProvider {
+    /** Environment variables this provider needs */
+    envVars: EnvVarRequirement[];
+}
+/**
+ * Database adapter provider.
+ * Returned by database adapter `.forRoot()` methods.
+ */
+interface DatabaseMagnetProvider extends BaseMagnetProvider {
+    type: 'database';
+    /** The database adapter instance */
+    adapter: DatabaseAdapter;
+    /** Resolved database configuration */
+    config: DBConfig;
+}
+/**
+ * Storage adapter provider.
+ * Returned by storage adapter `.forRoot()` methods.
+ */
+interface StorageMagnetProvider extends BaseMagnetProvider {
+    type: 'storage';
+    /** The storage adapter instance */
+    adapter: StorageAdapter;
+    /** Adapter-specific resolved configuration */
+    config?: Record<string, unknown>;
+}
+/**
+ * Email adapter provider.
+ * Returned by email adapter `.forRoot()` methods.
+ */
+interface EmailMagnetProvider extends BaseMagnetProvider {
+    type: 'email';
+    /** The email adapter instance */
+    adapter: EmailAdapter;
+    /** Default email settings */
+    defaults?: {
+        from?: string;
+        replyTo?: string;
+    };
+}
+/**
+ * Vault adapter provider.
+ * Returned by vault adapter `.forRoot()` methods.
+ *
+ * Supports two patterns:
+ * - Direct `adapter` for adapters that don't need NestJS DI (e.g., HashiCorp)
+ * - `adapterFactory` for adapters that need ModuleRef (e.g., built-in DB vault)
+ */
+interface VaultMagnetProvider extends BaseMagnetProvider {
+    type: 'vault';
+    /** Direct adapter instance (for adapters that don't need DI) */
+    adapter?: VaultAdapter;
+    /** Factory function for adapters that need NestJS ModuleRef */
+    adapterFactory?: (moduleRef: unknown) => VaultAdapter;
+    /** Vault configuration */
+    config?: {
+        cacheTtl?: number;
+    };
+}
+/**
+ * Auth strategy provider.
+ * Returned by auth adapter `.forRoot()` methods.
+ */
+interface AuthMagnetProvider extends BaseMagnetProvider {
+    type: 'auth';
+    /** Auth configuration including strategy name */
+    config: AuthConfig;
+}
+/**
+ * Plugin provider.
+ * Returned by plugin `.forRoot()` methods.
+ */
+interface PluginMagnetProvider extends BaseMagnetProvider {
+    type: 'plugin';
+    /** The @Plugin() decorated class */
+    plugin: Type<unknown>;
+    /** Plugin-specific options (injected via PLUGIN_OPTIONS token) */
+    options?: Record<string, unknown>;
+}
+/**
+ * Cache adapter provider.
+ * Returned by cache adapter `.forRoot()` methods.
+ *
+ * When not provided, CacheModule defaults to the built-in MemoryCacheAdapter.
+ *
+ * @example
+ * ```typescript
+ * MagnetModule.forRoot([
+ *   RedisCacheAdapter.forRoot(), // or omit for in-memory default
+ * ])
+ * ```
+ */
+interface CacheMagnetProvider extends BaseMagnetProvider {
+    type: 'cache';
+    /** The cache adapter instance */
+    adapter: CacheAdapter;
+}
+/**
+ * Discriminated union of all provider types.
+ * Each adapter/plugin `.forRoot()` returns one of these variants.
+ *
+ * @example
+ * ```typescript
+ * const providers: MagnetProvider[] = [
+ *   MongooseDatabaseAdapter.forRoot(),
+ *   StripePlugin.forRoot({ currency: 'usd' }),
+ * ]
+ * MagnetModule.forRoot(providers, { admin: true })
+ * ```
+ */
+type MagnetProvider = DatabaseMagnetProvider | StorageMagnetProvider | EmailMagnetProvider | VaultMagnetProvider | AuthMagnetProvider | PluginMagnetProvider | CacheMagnetProvider;
+
+declare function Resolver(optionsOrFn: ResolverInput): ClassDecorator;
+
+declare function Resolve(optionsOrFn: ResolveInput): MethodDecorator;
+
+/**
+ * Options for the @ExtendUser decorator
+ */
+interface ExtendUserOptions {
     /**
-     * Plugins to load with the Magnet module
+     * Whether to include timestamps (createdAt, updatedAt)
+     * @default true
      */
-    plugins?: PluginConfig[];
-    constructor({ db, jwt, auth, internationalization, playground, storage, plugins, }: MagnetModuleOptions);
+    timestamps?: boolean;
 }
-type MagnetModuleOptionsAsync = {
-    useFactory: (...args: any[]) => Promise<MagnetModuleOptions> | MagnetModuleOptions;
-    inject?: Type[];
-    imports?: Type[];
-};
+/**
+ * Marks a class as a User extension.
+ *
+ * The decorated class will inherit base User fields (id, email, password, role, etc.)
+ * and can add additional custom fields using Field decorators.
+ *
+ * @example
+ * ```typescript
+ * @ExtendUser()
+ * export class User {
+ *   // Base fields inherited: id, email, password, role, createdAt, updatedAt
+ *
+ *   @Field.Text({ required: true })
+ *   @Field.Validators(IsString(), Length(1, 50))
+ *   firstName: string
+ *
+ *   @Field.Text({ required: true })
+ *   @Field.Validators(IsString(), Length(1, 50))
+ *   lastName: string
+ *
+ *   @Field.Image({ folder: 'avatars' })
+ *   avatar?: string
+ *
+ *   get fullName() {
+ *     return `${this.firstName} ${this.lastName}`
+ *   }
+ * }
+ * ```
+ */
+declare function ExtendUser(options?: ExtendUserOptions): ClassDecorator;
+/**
+ * Check if a class is marked as a User extension
+ */
+declare function isUserExtension(target: Function): boolean;
+/**
+ * Get ExtendUser options from a class
+ */
+declare function getExtendUserOptions(target: Function): ExtendUserOptions | undefined;
 
-type DiscoveredController = {
-    path: string;
-    schema: string;
-    methods: DiscoveredMethod[];
-};
-type DiscoveredMethod = {
-    name: string;
-    method: string;
-};
-type DiscoveredSchema = {
-    name: string;
-    tableName: string;
-    target: string | object;
-};
+declare function Prop(options?: PropOptions): PropertyDecorator;
 
-type Validations = {
-    type: string;
-    name: string;
-    constraints: any[];
-}[];
+declare function Schema(options?: SchemaOptions): ClassDecorator;
+declare function getSchemaOptions(target: Function): SchemaOptions;
 
-type VersionStatus = 'draft' | 'published' | 'archived';
-interface VersionConfig {
+declare function Setting(): ClassDecorator;
+
+/**
+ * Enhanced Settings class decorator.
+ *
+ * Marks a class as a settings schema with group, label, and icon configuration.
+ *
+ * @example
+ * ```typescript
+ * @Settings({ group: 'general', label: 'General Settings', icon: 'settings' })
+ * export class GeneralSettings {
+ *   @SettingField.Text({ label: 'Site Name' })
+ *   siteName: string = 'My Site'
+ *
+ *   @SettingField.Boolean({ label: 'Maintenance Mode' })
+ *   maintenanceMode: boolean = false
+ * }
+ * ```
+ */
+declare function Settings(options: SettingsDecoratorOptions): ClassDecorator;
+/**
+ * Get settings options from a class
+ */
+declare function getSettingsOptions(target: Function): SettingsDecoratorOptions | undefined;
+/**
+ * Get all setting field metadata from a class
+ */
+declare function getSettingFields(target: Function): SettingFieldMetadata[];
+/**
+ * SettingField decorator namespace.
+ *
+ * Provides type-safe field decorators for settings classes.
+ *
+ * @example
+ * ```typescript
+ * @Settings({ group: 'email', label: 'Email Settings', icon: 'mail' })
+ * export class EmailSettings {
+ *   @SettingField.Select({
+ *     label: 'Provider',
+ *     options: ['smtp', 'sendgrid', 'resend'],
+ *     default: 'smtp'
+ *   })
+ *   provider: string = 'smtp'
+ *
+ *   @SettingField.Secret({ label: 'API Key', masked: true })
+ *   apiKey?: string
+ * }
+ * ```
+ */
+declare const SettingField: {
     /**
-     * Maximum number of versions to keep per document
+     * Text setting field
      */
-    max?: number;
+    readonly Text: (options: SettingTextOptions) => PropertyDecorator;
     /**
-     * Enable drafts mode for this schema
+     * Number setting field
      */
-    drafts?: boolean | {
-        /**
-         * Auto-publish drafts after a certain time
-         */
-        autoPublish?: boolean;
-        /**
-         * Require approval before publishing
-         */
-        requireApproval?: boolean;
-    };
-}
-interface VersionData<T> {
+    readonly Number: (options: SettingNumberOptions) => PropertyDecorator;
     /**
-     * Document ID this version belongs to
+     * Boolean setting field (toggle/switch)
      */
-    documentId: string;
+    readonly Boolean: (options: SettingBooleanOptions) => PropertyDecorator;
     /**
-     * Version ID
+     * Select setting field (dropdown)
      */
-    versionId: string;
+    readonly Select: (options: SettingSelectOptions) => PropertyDecorator;
     /**
-     * Version status
+     * Secret setting field (encrypted, masked in UI)
      */
-    status: VersionStatus;
+    readonly Secret: (options: SettingSecretOptions) => PropertyDecorator;
     /**
-     * Version data
+     * Image setting field
      */
-    data: T;
+    readonly Image: (options: SettingImageOptions) => PropertyDecorator;
     /**
-     * Version created at
+     * JSON setting field
      */
-    createdAt: Date;
+    readonly JSON: (options: SettingJSONOptions) => PropertyDecorator;
     /**
-     * Version created by
+     * Textarea setting field (multi-line text)
      */
-    createdBy?: string;
+    readonly Textarea: (options: SettingTextOptions) => PropertyDecorator;
+};
+/**
+ * Type for the SettingField namespace
+ */
+type SettingFieldNamespace = typeof SettingField;
+
+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;
+
+/**
+ * Error codes for programmatic error handling
+ * Organized by category for easy identification
+ */
+declare enum ErrorCode {
+    VALIDATION_FAILED = 1000,
+    REQUIRED_FIELD_MISSING = 1001,
+    INVALID_FORMAT = 1002,
+    VALUE_OUT_OF_RANGE = 1003,
+    UNIQUE_CONSTRAINT_VIOLATION = 1004,
+    AUTHENTICATION_REQUIRED = 2000,
+    INVALID_CREDENTIALS = 2001,
+    TOKEN_EXPIRED = 2002,
+    TOKEN_INVALID = 2003,
+    ACCOUNT_LOCKED = 2004,
+    EMAIL_NOT_VERIFIED = 2005,
+    PERMISSION_DENIED = 3000,
+    INSUFFICIENT_PERMISSIONS = 3001,
+    ROLE_NOT_FOUND = 3002,
+    PERMISSION_NOT_FOUND = 3003,
+    RESOURCE_NOT_FOUND = 4000,
+    SCHEMA_NOT_FOUND = 4001,
+    DOCUMENT_NOT_FOUND = 4002,
+    USER_NOT_FOUND = 4003,
+    FILE_NOT_FOUND = 4004,
+    VERSION_NOT_FOUND = 4005,
+    DATABASE_ERROR = 5000,
+    CONNECTION_FAILED = 5001,
+    QUERY_FAILED = 5002,
+    TRANSACTION_FAILED = 5003,
+    DUPLICATE_KEY = 5004,
+    PLUGIN_ERROR = 6000,
+    PLUGIN_NOT_FOUND = 6001,
+    PLUGIN_INITIALIZATION_FAILED = 6002,
+    HOOK_EXECUTION_FAILED = 6003,
+    EXTERNAL_SERVICE_ERROR = 7000,
+    STORAGE_ERROR = 7001,
+    EMAIL_SERVICE_ERROR = 7002,
+    WEBHOOK_DELIVERY_FAILED = 7003,
+    INTERNAL_ERROR = 9000,
+    CONFIGURATION_ERROR = 9001,
+    UNEXPECTED_ERROR = 9999
+}
+/**
+ * Operation types for error metadata
+ */
+type OperationType = 'create' | 'read' | 'update' | 'delete' | 'publish';
+/**
+ * Error metadata for additional context
+ */
+interface ErrorMetadata {
+    /** Schema/collection name */
+    schema?: string;
+    /** Field name that caused the error */
+    field?: string;
+    /** Document/resource ID */
+    resourceId?: string;
+    /** Operation being performed */
+    operation?: OperationType;
+    /** Additional context */
+    context?: Record<string, unknown>;
+}
+/**
+ * Validation error detail
+ */
+interface ValidationErrorDetail {
+    field: string;
+    message: string;
+    constraint?: string;
+    value?: unknown;
+}
+/**
+ * Standard error response structure for API consumers
+ */
+interface ErrorResponse {
+    error: {
+        code: ErrorCode;
+        message: string;
+        name: string;
+        timestamp: string;
+        metadata?: ErrorMetadata;
+        details?: ValidationErrorDetail[];
+    };
+}
+/**
+ * Base error class for all Magnet errors
+ * Provides consistent error handling with codes, metadata, and serialization
+ */
+declare abstract class MagnetError extends Error {
+    abstract readonly code: ErrorCode;
+    abstract readonly httpStatus: number;
+    readonly timestamp: Date;
+    readonly metadata: ErrorMetadata;
+    constructor(message: string, metadata?: ErrorMetadata);
     /**
-     * Version notes
+     * Convert to API response format
      */
-    notes?: string;
+    toResponse(): ErrorResponse;
+    /**
+     * Convert to JSON for logging
+     */
+    toJSON(): Record<string, unknown>;
 }
 
-type SettingType = 'string' | 'boolean' | 'number' | 'object' | 'array';
-interface SchemaSetting {
-    key: string;
+/**
+ * Interface for class-validator error format
+ */
+interface ClassValidatorError {
+    property: string;
+    value?: unknown;
+    constraints?: Record<string, string>;
+    children?: ClassValidatorError[];
+}
+/**
+ * Validation error with field-level details
+ * Used for form validation and input validation failures
+ */
+declare class ValidationError extends MagnetError {
+    readonly code = ErrorCode.VALIDATION_FAILED;
+    readonly httpStatus = 400;
+    readonly details: ValidationErrorDetail[];
+    constructor(message: string, details: ValidationErrorDetail[], metadata?: ErrorMetadata);
+    /**
+     * Create ValidationError from class-validator errors
+     */
+    static fromClassValidator(errors: ClassValidatorError[]): ValidationError;
+    toResponse(): ErrorResponse;
+}
+/**
+ * Required field missing error
+ */
+declare class RequiredFieldError extends MagnetError {
+    readonly code = ErrorCode.REQUIRED_FIELD_MISSING;
+    readonly httpStatus = 400;
+    constructor(field: string, metadata?: ErrorMetadata);
+}
+/**
+ * Invalid format error (e.g., invalid email, invalid URL)
+ */
+declare class InvalidFormatError extends MagnetError {
+    readonly code = ErrorCode.INVALID_FORMAT;
+    readonly httpStatus = 400;
+    constructor(field: string, expectedFormat: string, metadata?: ErrorMetadata);
+}
+/**
+ * Value out of range error
+ */
+declare class ValueOutOfRangeError extends MagnetError {
+    readonly code = ErrorCode.VALUE_OUT_OF_RANGE;
+    readonly httpStatus = 400;
+    constructor(field: string, min?: number, max?: number, metadata?: ErrorMetadata);
+}
+
+/**
+ * Authentication required error
+ * Thrown when a request requires authentication but none is provided
+ */
+declare class AuthenticationRequiredError extends MagnetError {
+    readonly code = ErrorCode.AUTHENTICATION_REQUIRED;
+    readonly httpStatus = 401;
+    constructor(message?: string, metadata?: ErrorMetadata);
+}
+/**
+ * Invalid credentials error
+ * Thrown when email/password combination is incorrect
+ */
+declare class InvalidCredentialsError extends MagnetError {
+    readonly code = ErrorCode.INVALID_CREDENTIALS;
+    readonly httpStatus = 401;
+    constructor(message?: string, metadata?: ErrorMetadata);
+}
+/**
+ * Token expired error
+ * Thrown when a JWT or refresh token has expired
+ */
+declare class TokenExpiredError extends MagnetError {
+    readonly code = ErrorCode.TOKEN_EXPIRED;
+    readonly httpStatus = 401;
+    constructor(message?: string, metadata?: ErrorMetadata);
+}
+/**
+ * Token invalid error
+ * Thrown when a JWT or refresh token is malformed or invalid
+ */
+declare class TokenInvalidError extends MagnetError {
+    readonly code = ErrorCode.TOKEN_INVALID;
+    readonly httpStatus = 401;
+    constructor(message?: string, metadata?: ErrorMetadata);
+}
+/**
+ * Account locked error
+ * Thrown when an account is temporarily locked due to too many failed attempts
+ */
+declare class AccountLockedError extends MagnetError {
+    readonly code = ErrorCode.ACCOUNT_LOCKED;
+    readonly httpStatus = 423;
+    readonly unlockAt?: Date;
+    constructor(message?: string, unlockAt?: Date, metadata?: ErrorMetadata);
+}
+/**
+ * Email not verified error
+ * Thrown when an action requires email verification
+ */
+declare class EmailNotVerifiedError extends MagnetError {
+    readonly code = ErrorCode.EMAIL_NOT_VERIFIED;
+    readonly httpStatus = 403;
+    constructor(message?: string, metadata?: ErrorMetadata);
+}
+/**
+ * Permission denied error
+ * Thrown when user lacks permission for an action
+ */
+declare class PermissionDeniedError extends MagnetError {
+    readonly code = ErrorCode.PERMISSION_DENIED;
+    readonly httpStatus = 403;
+    readonly requiredPermission?: string;
+    constructor(message?: string, requiredPermission?: string, metadata?: ErrorMetadata);
+}
+/**
+ * Insufficient permissions error
+ * Thrown when user has some permissions but not enough
+ */
+declare class InsufficientPermissionsError extends MagnetError {
+    readonly code = ErrorCode.INSUFFICIENT_PERMISSIONS;
+    readonly httpStatus = 403;
+    readonly requiredPermissions: string[];
+    constructor(requiredPermissions: string[], metadata?: ErrorMetadata);
+}
+/**
+ * Role not found error
+ */
+declare class RoleNotFoundError extends MagnetError {
+    readonly code = ErrorCode.ROLE_NOT_FOUND;
+    readonly httpStatus = 404;
+    constructor(roleName: string, metadata?: ErrorMetadata);
+}
+/**
+ * Permission not found error
+ * Thrown when assigning invalid permission IDs to a role
+ */
+declare class PermissionNotFoundError extends MagnetError {
+    readonly code = ErrorCode.PERMISSION_NOT_FOUND;
+    readonly httpStatus = 400;
+    readonly invalidPermissionIds: string[];
+    constructor(invalidPermissionIds: string[], metadata?: ErrorMetadata);
+}
+
+/**
+ * Resource not found error
+ * Generic error for any resource type
+ */
+declare class ResourceNotFoundError extends MagnetError {
+    readonly code = ErrorCode.RESOURCE_NOT_FOUND;
+    readonly httpStatus = 404;
+    constructor(resourceType: string, identifier: string, metadata?: ErrorMetadata);
+}
+/**
+ * Schema not found error
+ * Thrown when a schema/collection doesn't exist
+ */
+declare class SchemaNotFoundError extends MagnetError {
+    readonly code = ErrorCode.SCHEMA_NOT_FOUND;
+    readonly httpStatus = 404;
+    constructor(schemaName: string, metadata?: ErrorMetadata);
+}
+/**
+ * Document not found error
+ * Thrown when a document doesn't exist in a schema
+ */
+declare class DocumentNotFoundError extends MagnetError {
+    readonly code = ErrorCode.DOCUMENT_NOT_FOUND;
+    readonly httpStatus = 404;
+    constructor(schema: string, id: string, metadata?: ErrorMetadata);
+}
+/**
+ * User not found error
+ */
+declare class UserNotFoundError extends MagnetError {
+    readonly code = ErrorCode.USER_NOT_FOUND;
+    readonly httpStatus = 404;
+    constructor(identifier: string, metadata?: ErrorMetadata);
+}
+/**
+ * File not found error
+ */
+declare class FileNotFoundError extends MagnetError {
+    readonly code = ErrorCode.FILE_NOT_FOUND;
+    readonly httpStatus = 404;
+    constructor(path: string, metadata?: ErrorMetadata);
+}
+/**
+ * Version not found error
+ * Thrown when a specific version of a document doesn't exist
+ */
+declare class VersionNotFoundError extends MagnetError {
+    readonly code = ErrorCode.VERSION_NOT_FOUND;
+    readonly httpStatus = 404;
+    constructor(schema: string, documentId: string, versionId: string, metadata?: ErrorMetadata);
+}
+
+/**
+ * Generic database error
+ * Used when a database operation fails
+ */
+declare class DatabaseError extends MagnetError {
+    readonly code = ErrorCode.DATABASE_ERROR;
+    readonly httpStatus = 500;
+    readonly originalError?: unknown;
+    constructor(message: string, originalError?: unknown, metadata?: ErrorMetadata);
+}
+/**
+ * Database connection failed error
+ */
+declare class ConnectionFailedError extends MagnetError {
+    readonly code = ErrorCode.CONNECTION_FAILED;
+    readonly httpStatus = 503;
+    constructor(message?: string, metadata?: ErrorMetadata);
+}
+/**
+ * Query failed error
+ */
+declare class QueryFailedError extends MagnetError {
+    readonly code = ErrorCode.QUERY_FAILED;
+    readonly httpStatus = 500;
+    readonly query?: string;
+    constructor(message: string, query?: string, metadata?: ErrorMetadata);
+}
+/**
+ * Transaction failed error
+ */
+declare class TransactionFailedError extends MagnetError {
+    readonly code = ErrorCode.TRANSACTION_FAILED;
+    readonly httpStatus = 500;
+    constructor(message?: string, metadata?: ErrorMetadata);
+}
+/**
+ * Duplicate key error
+ * Thrown when attempting to insert a duplicate value for a unique field
+ */
+declare class DuplicateKeyError extends MagnetError {
+    readonly code = ErrorCode.DUPLICATE_KEY;
+    readonly httpStatus = 409;
+    constructor(field: string, value: unknown, metadata?: ErrorMetadata);
+}
+
+/**
+ * Generic plugin error
+ */
+declare class PluginError extends MagnetError {
+    readonly code = ErrorCode.PLUGIN_ERROR;
+    readonly httpStatus = 500;
+    constructor(pluginName: string, message: string, metadata?: ErrorMetadata);
+}
+/**
+ * Plugin not found error
+ */
+declare class PluginNotFoundError extends MagnetError {
+    readonly code = ErrorCode.PLUGIN_NOT_FOUND;
+    readonly httpStatus = 404;
+    constructor(pluginName: string, metadata?: ErrorMetadata);
+}
+/**
+ * Plugin initialization error
+ * Thrown when a plugin fails to initialize
+ */
+declare class PluginInitializationError extends MagnetError {
+    readonly code = ErrorCode.PLUGIN_INITIALIZATION_FAILED;
+    readonly httpStatus = 500;
+    constructor(pluginName: string, reason: string, metadata?: ErrorMetadata);
+}
+/**
+ * Hook execution error
+ * Thrown when a plugin hook fails to execute
+ */
+declare class HookExecutionError extends MagnetError {
+    readonly code = ErrorCode.HOOK_EXECUTION_FAILED;
+    readonly httpStatus = 500;
+    constructor(hookName: string, pluginName: string, reason: string, metadata?: ErrorMetadata);
+}
+
+/**
+ * Generic external service error
+ */
+declare class ExternalServiceError extends MagnetError {
+    readonly code = ErrorCode.EXTERNAL_SERVICE_ERROR;
+    readonly httpStatus = 502;
+    constructor(serviceName: string, message: string, metadata?: ErrorMetadata);
+}
+/**
+ * Storage service error
+ */
+declare class StorageError extends MagnetError {
+    readonly code = ErrorCode.STORAGE_ERROR;
+    readonly httpStatus = 502;
+    constructor(message: string, metadata?: ErrorMetadata);
+}
+/**
+ * Email service error
+ */
+declare class EmailServiceError extends MagnetError {
+    readonly code = ErrorCode.EMAIL_SERVICE_ERROR;
+    readonly httpStatus = 502;
+    constructor(message: string, metadata?: ErrorMetadata);
+}
+/**
+ * Webhook delivery error
+ */
+declare class WebhookDeliveryError extends MagnetError {
+    readonly code = ErrorCode.WEBHOOK_DELIVERY_FAILED;
+    readonly httpStatus = 502;
+    readonly webhookUrl: string;
+    readonly statusCode?: number;
+    constructor(webhookUrl: string, reason: string, statusCode?: number, metadata?: ErrorMetadata);
+}
+
+/**
+ * Internal error
+ * Used for unexpected server errors
+ */
+declare class InternalError extends MagnetError {
+    readonly code = ErrorCode.INTERNAL_ERROR;
+    readonly httpStatus = 500;
+    constructor(message?: string, metadata?: ErrorMetadata);
+}
+/**
+ * Configuration error
+ * Used when application configuration is invalid
+ */
+declare class ConfigurationError extends MagnetError {
+    readonly code = ErrorCode.CONFIGURATION_ERROR;
+    readonly httpStatus = 500;
+    constructor(message: string, metadata?: ErrorMetadata);
+}
+/**
+ * Unexpected error
+ * Used as a fallback for unknown error types
+ */
+declare class UnexpectedError extends MagnetError {
+    readonly code = ErrorCode.UNEXPECTED_ERROR;
+    readonly httpStatus = 500;
+    readonly originalError?: unknown;
+    constructor(message?: string, originalError?: unknown, metadata?: ErrorMetadata);
+}
+
+/**
+ * Context for error conversion
+ */
+interface ErrorContext {
+    schema?: string;
+    operation?: string;
+}
+/**
+ * Convert MongoDB/Mongoose errors to typed Magnet errors
+ * @param error - The original error from Mongoose
+ * @param context - Optional context about the operation
+ * @returns A typed MagnetError
+ */
+declare function fromMongooseError(error: unknown, context?: ErrorContext): MagnetError;
+/**
+ * Convert Drizzle/PostgreSQL errors to typed Magnet errors
+ * @param error - The original error from Drizzle
+ * @param context - Optional context about the operation
+ * @returns A typed MagnetError
+ */
+declare function fromDrizzleError(error: unknown, context?: ErrorContext): MagnetError;
+/**
+ * Check if an error is a MagnetError
+ */
+declare function isMagnetError(error: unknown): error is MagnetError;
+/**
+ * Wrap an unknown error as a MagnetError
+ * If already a MagnetError, returns it unchanged
+ */
+declare function wrapError(error: unknown, fallbackMessage?: string): MagnetError;
+
+declare class ValidationException extends Error {
+    readonly errors: ValidationError$1[];
+    constructor(errors: ValidationError$1[]);
+}
+
+type SupportedAdapter = 'mongoose' | 'drizzle';
+/**
+ * Detect the database adapter based on configuration or installed packages.
+ *
+ * With the provider-based API, the adapter is typically auto-registered:
+ * importing `@magnet-cms/adapter-db-mongoose` or `@magnet-cms/adapter-db-drizzle`
+ * calls `setDatabaseAdapter()` as a module-level side effect, so detection
+ * happens automatically before any `@Schema()` decorators evaluate.
+ *
+ * Detection priority:
+ * 1. Cached value from `setDatabaseAdapter()` (set by adapter package import side effect)
+ * 2. Configuration-based: If `connectionString` or `dialect` is present, use drizzle
+ * 3. Configuration-based: If `uri` is present, use mongoose
+ * 4. Package-based: Check which adapter packages are installed (mongoose > drizzle)
+ *
+ * @param dbConfig - Optional database configuration to determine adapter from
+ */
+declare function detectDatabaseAdapter(dbConfig?: DBConfig): SupportedAdapter;
+/**
+ * Explicitly set the database adapter.
+ *
+ * With the provider-based API, this is called automatically as a side effect
+ * when importing an adapter package (e.g., `@magnet-cms/adapter-db-drizzle`).
+ * Manual calls are no longer needed in typical user code.
+ *
+ * @internal Called by adapter package index.ts as module-level side effect
+ */
+declare function setDatabaseAdapter(adapter: SupportedAdapter): void;
+/**
+ * Clear the cached adapter (useful for testing)
+ */
+declare function clearAdapterCache(): void;
+
+/**
+ * Get model injection token for any adapter
+ * @param schema Schema class or schema name
+ * @returns Injection token string
+ */
+declare function getModelToken(schema: Type | string): string;
+/**
+ * Get adapter injection token
+ * @returns Injection token for the database adapter
+ */
+declare function getAdapterToken(): string;
+declare function registerModel(token: string, model: unknown): void;
+declare function getRegisteredModel<T>(token: string): T | undefined;
+
+declare const getSchemaToken: (schema: Type) => string;
+declare const getSettingToken: (setting: Type) => string;
+
+/**
+ * Type guard utilities for safe type narrowing
+ * Use these instead of type assertions (as any, as unknown as T)
+ */
+/**
+ * Check if value is a non-null object
+ */
+declare function isObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Check if value has a specific property
+ */
+declare function hasProperty<K extends string>(value: unknown, key: K): value is Record<K, unknown>;
+/**
+ * Check if value has multiple properties
+ */
+declare function hasProperties<K extends string>(value: unknown, keys: K[]): value is Record<K, unknown>;
+/**
+ * Check if value is a string
+ */
+declare function isString(value: unknown): value is string;
+/**
+ * Check if value is a number
+ */
+declare function isNumber(value: unknown): value is number;
+/**
+ * Check if value is a boolean
+ */
+declare function isBoolean(value: unknown): value is boolean;
+/**
+ * Check if value is an array
+ */
+declare function isArray(value: unknown): value is unknown[];
+/**
+ * Check if value is a string array
+ */
+declare function isStringArray(value: unknown): value is string[];
+/**
+ * Check if value is a function
+ */
+declare function isFunction(value: unknown): value is Function;
+/**
+ * Check if value is a valid document with ID
+ */
+declare function isDocument(value: unknown): value is {
+    id: string;
+    [key: string]: unknown;
+};
+/**
+ * Check if error is a MongoDB CastError
+ */
+declare function isCastError(error: unknown): error is {
+    name: 'CastError';
+    path: string;
     value: unknown;
-    type: SettingType | string;
-}
-interface SettingsFeatureOptions<T = unknown> {
-    group: string;
-    schema: new () => T;
-}
-
+};
 /**
- * Query operator types for MongoDB-style queries
+ * Check if error is a MongoDB duplicate key error
  */
-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;
+declare function isDuplicateKeyError(error: unknown): error is {
+    code: 11000;
+    keyValue: Record<string, unknown>;
 };
 /**
- * Filter value that supports both direct values and operators
+ * Check if error is a Mongoose validation error
  */
-type FilterValue<T> = T | QueryOperator<T>;
+declare function isValidationError(error: unknown): error is {
+    name: 'ValidationError';
+    errors: Record<string, unknown>;
+};
 /**
- * Full filter query type with logical operators
+ * Check if error is a PostgreSQL unique constraint violation
  */
-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>[];
+declare function isPostgresUniqueError(error: unknown): error is {
+    code: string;
+    detail?: string;
 };
 /**
- * Sort direction
+ * Check if an object has a method
  */
-type SortDirection = 1 | -1 | 'asc' | 'desc';
+declare function hasMethod<K extends string>(value: unknown, methodName: K): value is Record<K, Function>;
 /**
- * Sort specification
+ * Check if value has setLocale method (for i18n documents)
  */
-type SortQuery<Schema> = {
-    [K in keyof Schema]?: SortDirection;
+declare function hasSetLocale<T>(value: T): value is T & {
+    setLocale: (locale: string) => T;
 };
 /**
- * Projection specification for field selection
+ * Check if value has toString method that returns string
  */
-type ProjectionQuery<Schema> = {
-    [K in keyof Schema]?: 0 | 1 | boolean;
+declare function hasToString(value: unknown): value is {
+    toString(): string;
 };
 /**
- * Query execution options
+ * Assert value is defined (not null or undefined)
+ * Throws if value is null or undefined
  */
-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;
-}
+declare function assertDefined<T>(value: T | null | undefined, message?: string): asserts value is T;
 /**
- * Paginated query result
+ * Assert condition is true
+ * Throws if condition is false
  */
-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";
+declare function assert(condition: boolean, message?: string): asserts condition;
 /**
- * Decorator to enable versioning for a schema
- * @param config Version configuration
+ * Safely get a string ID from a document that might have _id or id
+ * Returns undefined if no valid ID found
  */
-declare function Version(config?: VersionConfig): ClassDecorator;
-
-declare function InjectModel(model: Type): ParameterDecorator;
-
-declare class ValidationException extends Error {
-    readonly errors: ValidationError[];
-    constructor(errors: ValidationError[]);
-}
-
+declare function getDocumentId(doc: unknown): string | undefined;
 /**
- * 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()
- * ```
+ * Type guard for checking if an object matches a record with string values
  */
-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 function isStringRecord(value: unknown): value is Record<string, string>;
 
-declare const getSchemaToken: (schema: Type) => string;
-declare const getSettingToken: (setting: Type) => string;
+/**
+ * Check if value is a version document
+ */
+declare function isVersionDocument(value: unknown): value is VersionDocument;
 
 declare const RESOLVER_METADATA_KEY = "magnet:resolver";
 declare const RESOLVE_METADATA_KEY = "magnet:resolve";
@@ -1055,11 +4248,18 @@ 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 FIELD_METADATA_KEY = "magnet:schema:field";
 declare const SETTING_METADATA_KEY = "magnet:setting";
+declare const SETTINGS_OPTIONS_METADATA_KEY = "magnet:settings:options";
+declare const SETTING_FIELD_METADATA_KEY = "magnet:settings:field";
+declare const EXTEND_USER_METADATA_KEY = "magnet:extend:user";
+declare const PERMISSION_METADATA_KEY = "magnet:permission";
+declare const PERMISSION_OPTIONS_METADATA_KEY = "magnet:permission:options";
+declare const RESOLVED_PERMISSION_KEY = "magnet:permission:resolved";
 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 };
+export { AccountLockedError, type AdapterCapabilities, type AdapterFeature, type AdapterName, type AddressFieldOptions, type AdminConfig, type ApiKeyEventPayload, type ArrayFieldOptions, type ArrayItemType, type AssignRoleDto, type AuthConfig, type AuthEventPayload, type AuthMagnetProvider, type AuthResult, AuthStrategy, type AuthUser, AuthenticationRequiredError, BASE_SCHEMA_METADATA_KEY, type BaseEventPayload, type BaseFieldOptions, type BaseSchema, type BaseSchemaOptions, type BlockTypeDefinition, type BlocksFieldOptions, type BooleanFieldOptions, CacheAdapter, type CacheHealthResult, type CacheMagnetProvider, type CategorizedPermissions, type CodeFieldOptions, type ColorFieldOptions, ConfigurationError, ConnectionFailedError, type ContentEventPayload, type ContentVersionEventPayload, type ControllerMetadata, type CreateRoleDto, type DBConfig, DESIGN_META, DESIGN_PARAM_TYPES, DESIGN_RETURN_TYPE, DESIGN_TYPE, DatabaseAdapter, DatabaseError, type DatabaseMagnetProvider, type DatabaseModelInstance, type DatabaseType, type DateFieldOptions, type DateTimeFieldOptions, type DiscoveredController, type DiscoveredMethod, type DiscoveredSchema, DocumentNotFoundError, type DrizzleConfig, DuplicateKeyError, type DuplicateRoleDto, EVENT_HANDLER_METADATA, EXTEND_USER_METADATA_KEY, EmailAdapter, type EmailAdapterName, type EmailAttachment, type EmailConfig, type EmailFieldOptions, type EmailMagnetProvider, EmailNotVerifiedError, EmailServiceError, type EnrichedPluginManifest, type EnumFieldOptions, type EnvVarRequirement, ErrorCode, type ErrorLogData, type ErrorMetadata, type ErrorResponse, type EventHandler, type EventHandlerMetadata, type EventHandlerOptions, type EventHistoryEntry, type EventName, type EventPayload, type EventPayloadMap, ExtendUser, type ExtendUserOptions, type ExternalAuthInfo, ExternalServiceError, FIELD_METADATA_KEY, type FailedLoginEventPayload, Field, type FieldChange, type FieldMetadata, type FieldNamespace, type FieldOptionsMap, type FieldTypeId, type FileFieldOptions, FileNotFoundError, type FilterQuery, type FilterValue, type GalleryFieldOptions, HasPermission, type HashiCorpVaultConfig, HookExecutionError, INJECT_MODEL, type ImageFieldOptions, type InitialConfig, InjectModel, InsufficientPermissionsError, InternalError, type InternationalizationOptions, InvalidCredentialsError, InvalidFormatError, type JSONFieldOptions, type JwtAuthConfig, type LocalStorageConfig, type LogEntry, type LogLevel, type LogMetadata, type LoggerConfig, type LoginCredentials, MagnetError, type MagnetGlobalOptions, MagnetModuleOptions, type MagnetModuleOptionsAsync, type MagnetProvider, type MarkdownFieldOptions, type MediaEventPayload, type MediaFolderEventPayload, type MediaQueryOptions, type MethodMetadata, Mixed, Model, type ModelClass, type ModelCreateOptions, type ModelUpdateOptions, type MongooseConfig, type NativeAccess, type NodemailerConfig, type NotificationChannel, type NotificationChannelAdapter, type NotificationChannelResult, type NotificationEventPayload, type NotificationQueryOptions, type NotificationRecipient, type NotificationSendPayload, type NotifyDto, type NumberFieldOptions, type ObjectFieldOptions, OnEvent, type OperationType, PERMISSION_METADATA_KEY, PERMISSION_OPTIONS_METADATA_KEY, PROP_METADATA_KEY, type PaginatedMedia, type PaginatedNotifications, type PaginatedResult, type PermissionCheckResult, type PermissionDefinition, PermissionDeniedError, type PermissionGroup, type PermissionItem, PermissionMeta, PermissionNotFoundError, type PermissionOptions, type PermissionSource, type PhoneFieldOptions, type PlaygroundOptions, type PluginConfig, PluginError, type PluginEventPayload, type PluginFrontendManifest, type PluginHook, PluginInitializationError, type PluginLifecycle, type PluginMagnetProvider, type PluginMetadata, type PluginModuleOptions, PluginNotFoundError, type PluginRouteDefinition, type PluginSettingsPage, type PluginSidebarItem, type ProjectionQuery, Prop, type PropDefaultValue, type PropOptions, QueryBuilder, QueryFailedError, type QueryOperator, type QueryOptions, type R2StorageConfig, type RBACModuleOptions, RESOLVED_PERMISSION_KEY, RESOLVER_METADATA_KEY, RESOLVE_METADATA_KEY, type RegisterData, type RegisteredHandler, type RegisteredPluginInfo, type RelationshipFieldOptions, RequirePermission, type RequiredEventHandlerOptions, RequiredFieldError, type ResendConfig, Resolve, type ResolveInput, type ResolveOptions, type ResolvedPermission, Resolver, type ResolverInput, type ResolverOptions, ResourceNotFoundError, type RichTextFieldOptions, type Role, type RoleAuditEntry, type RoleEventPayload, RoleNotFoundError, type RoleWithPermissions, type S3StorageConfig, SCHEMA_METADATA_KEY, SCHEMA_OPTIONS_METADATA_KEY, SETTINGS_OPTIONS_METADATA_KEY, SETTING_FIELD_METADATA_KEY, SETTING_METADATA_KEY, Schema, type SchemaIndexOption, type SchemaMetadata, SchemaNotFoundError, type SchemaOptions, type SchemaProperty, type SchemaPropertyValidation, type SchemaSetting, type SelectFieldOptions, type SelectOptionItem, type SendEmailOptions, type SendEmailResult, Setting, type SettingBooleanOptions, SettingField, type SettingFieldBaseOptions, type SettingFieldMetadata, type SettingFieldNamespace, type SettingFieldTypeId, type SettingImageOptions, type SettingJSONOptions, type SettingNumberOptions, type SettingObject, type SettingSecretOptions, type SettingSectionDefinition, type SettingSectionVariant, type SettingSelectOptions, type SettingTextOptions, type SettingType, type SettingValue, Settings, type SettingsBulkUpdatePayload, type SettingsDecoratorOptions, type SettingsEventPayload, type SettingsFeatureOptions, type SettingsGroupEventPayload, type SettingsRecord, type SettingsUpdatePayload, type SlugFieldOptions, type SortDirection, type SortQuery, StorageAdapter, type StorageConfig, StorageError, type StorageMagnetProvider, type SupabaseAuthConfig, type SupabaseStorageConfig, type SupabaseVaultConfig, type SupportedAdapter, type SystemEventPayload, type SystemRoleConfig, type SystemRoleName, type TagsFieldOptions, type TextFieldOptions, type TextareaFieldOptions, TokenExpiredError, TokenInvalidError, TransactionFailedError, type TransformOptions, 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 URLFieldOptions, UnexpectedError, type UpdatePermissionsDto, type UpdateRoleDto, type UploadOptions, type UploadResult, type UserEventPayload, UserNotFoundError, VERSION_METADATA_KEY, ValidationError, type ValidationErrorDetail, ValidationException, type Validations, Validators, ValueOutOfRangeError, VaultAdapter, type VaultAdapterType, type VaultAppRoleAuth, type VaultAuthConfig, type VaultConfig, type VaultMagnetProvider, type VaultSecretListResponse, type VaultSecretMeta, type VaultStatusResponse, type VaultTokenAuth, Version, type VersionConfig, type VersionData, type VersionDocument, VersionNotFoundError, type VersionStatus, WebhookDeliveryError, type WebhookDeliveryEventPayload, type WebhookEventPayload, assert, assertDefined, clearAdapterCache, createFieldDecorator, detectDatabaseAdapter, fromDrizzleError, fromMongooseError, getAdapterToken, getDocumentId, getExtendUserOptions, getFieldMetadata, getFieldMetadataForProperty, getModelToken, getPermissionMetadata, getRegisteredModel, getSchemaOptions, getSchemaToken, getSettingFields, getSettingToken, getSettingsOptions, hasMethod, hasPermissionDecorator, hasProperties, hasProperty, hasSetLocale, hasToString, isArray, isBoolean, isCastError, isDocument, isDuplicateKeyError, isFieldMetadata, isFunction, isMagnetError, isNumber, isObject, isPostgresUniqueError, isSettingFieldMetadata, isString, isStringArray, isStringRecord, isUserExtension, isValidFieldType, isValidationError, isVersionDocument, mapFieldTypeToProp, mapFieldTypeToUI, registerModel, setDatabaseAdapter, wrapError };