@gzl10/nexus-sdk 0.12.7 → 0.13.0

package/dist/index.d.ts

@@ -1,2257 +1,29 @@
 import { Knex } from 'knex';
 export { Knex } from 'knex';
-import { Request, Router, RequestHandler, Response } from 'express';
 export { CookieOptions, NextFunction, Request, RequestHandler, Response, Router } from 'express';
-import { Logger } from 'pino';
+import { E as EntityType, D as DisplayMode, C as Category, a as EntityDefinition, b as CollectionEntityDefinition, R as ReferenceEntityDefinition, c as EventEntityDefinition, d as ConfigEntityDefinition, T as TempEntityDefinition, V as ViewEntityDefinition, e as TreeEntityDefinition, f as DagEntityDefinition, S as SingleEntityDefinition, A as ActionDefinition, g as ExternalEntityDefinition, h as VirtualEntityDefinition, i as ComputedEntityDefinition } from './entity-kPgsCMdR.js';
+export { w as AbilityLike, $ as ActionEntityDefinition, ab as ActionEntityService, aN as ActionInjection, aG as AdaptersContext, aP as AppManifest, y as AuthRequest, o as BaseAuthRequest, a0 as BaseEntityService, ai as BaseMailService, ae as BaseRolesService, p as BaseUser, af as BaseUsersService, B as BatchConfig, n as BatchLogEntry, m as BatchProgressEvent, aW as CATEGORIES, aX as CATEGORY_ORDER, t as CaslAction, aM as CategoryMeta, a1 as CollectionEntityService, a8 as ComputedEntityService, aD as ConfigContext, a5 as ConfigEntityService, at as ContextCache, aq as ContextCrypto, ax as ContextHelpers, as as ContextLRUCache, ar as ContextLRUCacheOptions, aw as ContextSocket, aA as CoreContext, ak as CoreServices, ad as CreateEntityServiceOptions, aL as CustomRouteDefinition, I as DatabaseAdapter, aB as DbContext, aE as EngineContext, W as EntityAction, v as EntityCaslConfig, az as EntityController, ay as EntityHandler, H as EntityQuery, ac as EntityServiceHooks, ap as EventEmitterLike, a3 as EventEntityService, a9 as ExternalEntityService, z as FilterOperators, G as FilterValue, x as ForbiddenErrorConstructor, F as ForbiddenErrorInstance, aI as HttpMethod, aj as LoggerReporter, M as ModuleAbilities, aH as ModuleContext, aO as ModuleManifest, ao as ModuleMiddlewares, U as ModuleRequirements, r as PaginatedResult, P as PaginationParams, q as PaginationParamsWithOffset, aR as PluginConfigField, aS as PluginConfigSchema, aQ as PluginEnvVar, aU as PluginManifest, aT as PluginSetupInfo, an as RateLimitOptions, a6 as ReferenceEntityService, aV as RegisterPluginOptions, Z as RetentionPolicy, u as RolePermission, aJ as RouteParameterDefinition, aK as RouteResponseDefinition, aC as RuntimeContext, j as SSEHelper, l as SSEOptions, k as SSESender, Q as SchemaAdapter, O as SchemaAlterTableBuilder, K as SchemaColumnBuilder, J as SchemaColumnInfo, N as SchemaForeignKeyBuilder, L as SchemaTableBuilder, Y as SeedConfig, ag as SendMailOptions, ah as SendMailResult, aF as ServicesContext, a4 as SingleEntityService, av as SocketIOBroadcastOperator, au as SocketIOServer, X as StandaloneAction, a2 as TempEntityService, _ as TempRetentionPolicy, am as ValidateSchemas, s as ValidationDetail, al as ValidationSchema, a7 as ViewEntityService, aa as VirtualEntityService } from './entity-kPgsCMdR.js';
+import { L as LocalizedString, I as InputType, F as FieldCondition, a as FieldMeta } from './field-CngHXora.js';
+export { A as AuthProviderInfo, b as AuthProviderService, C as ConditionalBoolean, D as DbType, E as EntityIndex, c as FieldDbConfig, i as FieldDefinition, f as FieldOptions, d as FieldRelation, h as FieldStorageConfig, e as FieldValidationConfig, g as getCountLabel, k as refMaster, j as refOptions, r as resolveLocalized } from './field-CngHXora.js';
+import 'pino';
 
 /**
- * Type guards and utilities for EntityDefinitions
- */
-
-/**
- * Entities that persist in the local DB with their own table.
- * Excludes: action, external, virtual, computed, single (uses shared table).
- */
-type PersistentEntityDefinition = CollectionEntityDefinition | ReferenceEntityDefinition | EventEntityDefinition | ConfigEntityDefinition | TempEntityDefinition | ViewEntityDefinition;
-/**
- * Entities without local persistence (read-only or without DB)
- */
-type NonPersistentEntityDefinition = ActionEntityDefinition | ExternalEntityDefinition | VirtualEntityDefinition | ComputedEntityDefinition;
-/**
- * Type guard to check whether an entity persists in the local DB with its own table
- */
-declare function isPersistentEntity(entity: EntityDefinition): entity is PersistentEntityDefinition;
-/**
- * Type guard to check whether it is a singleton (uses shared sys_settings table)
- */
-declare function isSingletonEntity(entity: EntityDefinition): entity is SingleEntityDefinition;
-/**
- * Type guard to check whether an entity has its own table (for migrations)
- */
-declare function hasTable(entity: EntityDefinition): entity is PersistentEntityDefinition;
-/**
- * Gets an entity name in singular PascalCase.
- * 'cms_posts' → 'Post', 'rol_role_permissions' → 'RolePermission'
- */
-declare function getEntityName(entity: EntityDefinition): string;
-/**
- * Gets the CASL subject for an entity
- */
-declare function getEntitySubject(entity: PersistentEntityDefinition): string;
-
-/**
- * @gzl10/nexus-sdk
- *
- * SDK types for creating Nexus plugins and modules.
- * Use this package to define plugin/module manifests without
- * depending on the full @gzl10/nexus-backend package.
- */
-/**
- * Discriminated union of all entity types
- *
- * | Type       | Persistence | CRUD            | Primary use                      |
- * |------------|-------------|-----------------|----------------------------------|
- * | collection | Yes (DB)    | Full            | Business data (users, posts)     |
- * | single     | Yes (DB)    | Update/Read     | Global config (site_config)      |
- * | external   | No          | Read            | External data (stripe_customers) |
- * | virtual    | No          | Read            | Orchestration (unified_customers)|
- * | computed   | No/optional | Read            | KPIs, stats                      |
- * | view       | Yes/virtual | Read            | Optimized reads (projections)    |
- * | reference  | Yes         | Read (admin)    | Catalogs (countries, currencies) |
- * | config     | Yes         | Update/Read     | Per-module config                |
- * | event      | Yes         | Append          | Audit logs (audit_logs)          |
- * | temp       | No (TTL)    | Read/Write      | Cache, sessions (otp_codes)      |
- * | action     | No          | Execute         | Operations, workflows            |
- */
-
-type KnexCreateTableBuilder = Knex.CreateTableBuilder;
-type KnexAlterTableBuilder = Knex.AlterTableBuilder;
-type KnexTransaction = Knex.Transaction;
-/**
- * Base authenticated request with user and CASL abilities (generic).
- * Use AuthRequest for the pre-typed version.
- */
-interface BaseAuthRequest<TUser = unknown, TAbility = unknown> extends Request {
-    user: TUser;
-    ability: TAbility;
-}
-/**
- * Base user without a password for plugin use.
- * Used to type relations with users (e.g., author, created_by).
- * Note: Multi-role support - roles are loaded via user_roles pivot table.
- */
-interface BaseUser {
-    id: string;
-    name: string;
-    email: string;
-    created_at: Date;
-    updated_at: Date;
-    created_by: string | null;
-    updated_by: string | null;
-    /** Extensibility: allows custom user properties */
-    [key: string]: unknown;
-}
-/**
- * Pagination parameters for queries
- */
-interface PaginationParams {
-    page: number;
-    limit: number;
-}
-/**
- * Generic paginated result
- */
-interface PaginatedResult<T> {
-    items: T[];
-    total: number;
-    page: number;
-    limit: number;
-    totalPages: number;
-    hasNext: boolean;
-}
-/**
- * Standard validation error detail for API responses
- */
-interface ValidationDetail {
-    path: string;
-    message: string;
-}
-/**
- * Localized string supporting multiple languages.
- * Can be a simple string (single language) or object with language codes.
- *
- * @example
- * // Simple string (backward compatible)
- * label: 'Users'
- *
- * // Multi-language object
- * label: { en: 'Users', es: 'Usuarios' }
- */
-type LocalizedString = string | Record<string, string>;
-/**
- * Resolves a LocalizedString to the appropriate language.
- * Falls back to 'en', then first available, then empty string.
- *
- * @param value - The localized string to resolve
- * @param locale - The target locale (e.g., 'en', 'es')
- * @returns The resolved string for the given locale
- */
-declare function resolveLocalized(value: LocalizedString | undefined, locale: string): string;
-/**
- * Gets the appropriate label based on count (pluralization).
- * Returns labelPlural for count !== 1, label otherwise.
- *
- * @param label - Singular form
- * @param labelPlural - Plural form (optional, defaults to label)
- * @param count - The count to determine singular/plural
- * @param locale - The target locale
- * @returns The resolved string for the given count and locale
- */
-declare function getCountLabel(label: LocalizedString | undefined, labelPlural: LocalizedString | undefined, count: number, locale: string): string;
-/**
- * Database column types for Knex migrations.
- *
- * Maps to SQL column types:
- * - `string` → VARCHAR(size) - Use with `db.size` for length
- * - `text` → TEXT - Unlimited length text
- * - `integer` → INTEGER - Whole numbers
- * - `decimal` → DECIMAL(p,s) - Use with `db.precision` for scale
- * - `boolean` → BOOLEAN - True/false values
- * - `date` → DATE - Date without time
- * - `datetime` → DATETIME/TIMESTAMP - Date with time
- * - `json` → JSON/JSONB - Structured data (use for LocalizedString)
- * - `uuid` → UUID - Universally unique identifier
- * - `array` → Virtual only - No database column generated
- *
- * @example
- * ```typescript
- * db: { type: 'string', size: 100 }      // VARCHAR(100)
- * db: { type: 'decimal', precision: [10, 2] } // DECIMAL(10,2)
- * db: { type: 'json', nullable: false }  // JSON NOT NULL
- * ```
- */
-type DbType = 'string' | 'text' | 'integer' | 'decimal' | 'boolean' | 'date' | 'datetime' | 'json' | 'uuid' | 'array';
-/**
- * UI input types that determine which form component renders.
- *
- * **Text inputs:**
- * - `text` → NInput - Single line text
- * - `email` → NInput with email validation
- * - `password` → NInput with password mask
- * - `url` → NInput with URL validation
- * - `tel` → NInput for phone numbers
- *
- * **Numeric inputs:**
- * - `number` → NInputNumber - Integer values
- * - `decimal` → NInputNumber with decimal precision
- *
- * **Rich text:**
- * - `textarea` → NInput multiline
- * - `markdown` → MarkdownInput with preview
- * - `json` → JsonInput with syntax highlighting
- *
- * **Selection:**
- * - `select` → NSelect - Single selection dropdown
- * - `multiselect` → NSelect with multiple - Multiple selection
- * - `transfer` → NTransfer - Dual list selection
- * - `tags` → NSelect with tags - Free-form tags input
- *
- * **Boolean:**
- * - `checkbox` → NCheckbox
- * - `switch` → NSwitch - Toggle switch
- *
- * **Date/Time:**
- * - `date` → NDatePicker - Date only
- * - `datetime` → NDatePicker with time
- *
- * **Files:**
- * - `file` → FileInput - Single file upload
- * - `fileArray` → FileInput multiple - Multiple files
- * - `image` → ImageInput - Single image with preview
- * - `imageArray` → ImageInput multiple - Image gallery
- *
- * **Other:**
- * - `icon` → IconPicker - Icon selection from library
- *
- * @see {@link FieldOptions} for select/multiselect configuration
- * @see {@link FieldStorageConfig} for file/image configuration
- */
-type InputType = 'text' | 'email' | 'password' | 'url' | 'tel' | 'number' | 'decimal' | 'textarea' | 'markdown' | 'json' | 'select' | 'multiselect' | 'transfer' | 'tags' | 'checkbox' | 'switch' | 'date' | 'datetime' | 'file' | 'fileArray' | 'image' | 'imageArray' | 'icon';
-/**
- * Database column configuration for Knex migrations.
- *
- * @example
- * ```typescript
- * // String with max length
- * db: { type: 'string', size: 100, nullable: false }
- *
- * // Decimal with precision
- * db: { type: 'decimal', precision: [10, 2] }
- *
- * // UUID with auto-generation
- * db: { type: 'uuid', defaultFn: 'uuid' }
- *
- * // Virtual field (no column in DB)
- * db: { type: 'array', virtual: true }
- * ```
- */
-interface FieldDbConfig {
-    /** Column type for the database */
-    type: DbType;
-    /** If true, no database column is created (for computed/virtual fields like role_ids) */
-    virtual?: boolean;
-    /** String length for VARCHAR columns */
-    size?: number;
-    /** Precision and scale for DECIMAL: [precision, scale] e.g., [10, 2] for DECIMAL(10,2) */
-    precision?: [number, number];
-    /** Allow NULL values. Inferred from `required` if not specified */
-    nullable?: boolean;
-    /** Create unique constraint on this column */
-    unique?: boolean;
-    /** Static default value for the column */
-    default?: unknown;
-    /** Database function for default value: 'now' for timestamps, 'uuid' for auto-generated UUIDs */
-    defaultFn?: 'now' | 'uuid';
-    /** Create index on this column for faster queries */
-    index?: boolean;
-}
-/**
- * Foreign key relationship configuration.
- *
- * Defines how this field references another table in the database.
- * Used for both migrations (FK constraint) and UI (dropdown options).
- *
- * @example
- * ```typescript
- * // Basic relation to users table
- * relation: { table: 'users' }
- *
- * // With cascade delete
- * relation: { table: 'categories', onDelete: 'CASCADE' }
- *
- * // Reference non-id column
- * relation: { table: 'countries', column: 'code' }
- * ```
- */
-interface FieldRelation {
-    /** Target table name */
-    table: string;
-    /** Target column name (default: 'id') */
-    column?: string;
-    /** Action when referenced row is deleted */
-    onDelete?: 'CASCADE' | 'RESTRICT' | 'SET NULL' | 'NO ACTION';
-    /** Action when referenced row's key is updated */
-    onUpdate?: 'CASCADE' | 'RESTRICT' | 'SET NULL' | 'NO ACTION';
-}
-/**
- * Validation rules for runtime and form validation.
- *
- * Used to generate Zod schemas for API validation and
- * form validation rules in the UI.
- *
- * @example
- * ```typescript
- * // String length constraints
- * validation: { min: 1, max: 200 }
- *
- * // Email format
- * validation: { format: 'email' }
- *
- * // Regex pattern
- * validation: { pattern: '^[a-z0-9-]+$' }
- *
- * // Enum values
- * validation: { enum: ['draft', 'published', 'archived'] }
- * ```
- */
-interface FieldValidationConfig {
-    /** Minimum value (numbers) or minimum length (strings) */
-    min?: number;
-    /** Maximum value (numbers) or maximum length (strings) */
-    max?: number;
-    /** Regular expression pattern for validation */
-    pattern?: string;
-    /** Predefined format validation */
-    format?: 'email' | 'url' | 'uuid' | 'slug';
-    /** Allowed values (creates enum constraint) */
-    enum?: string[];
-}
-/**
- * Configuration for select, multiselect, and dropdown fields.
- *
- * Options can be loaded from:
- * - Static array defined in the field
- * - Dynamic endpoint (API call)
- * - Related entity via `relation` config
- *
- * @example
- * ```typescript
- * // Static options
- * options: {
- *   static: [
- *     { value: 'draft', label: { en: 'Draft', es: 'Borrador' } },
- *     { value: 'published', label: { en: 'Published', es: 'Publicado' } }
- *   ]
- * }
- *
- * // Dynamic from API
- * options: {
- *   endpoint: '/api/categories',
- *   valueField: 'id',
- *   labelField: 'name'
- * }
- *
- * // Allow creating new options (combobox)
- * options: { allowCreate: true, endpoint: '/api/tags' }
- * ```
- */
-interface FieldOptions {
-    /** API endpoint for dynamic options (GET request) */
-    endpoint?: string;
-    /** Field to use as option value (default: 'id') */
-    valueField?: string;
-    /** Field to use as option label (default: 'name') */
-    labelField?: string;
-    /** Static list of options */
-    static?: Array<{
-        value: string;
-        label: LocalizedString;
-    }>;
-    /** Allow creating new options on-the-fly (renders combobox) */
-    allowCreate?: boolean;
-}
-/**
- * Storage configuration for file and image upload fields.
- *
- * Controls upload behavior, file validation, and image processing.
- *
- * @example
- * ```typescript
- * // Image with thumbnails
- * storage: {
- *   accept: 'image/*',
- *   maxSize: 5 * 1024 * 1024, // 5MB
- *   folder: 'avatars',
- *   thumbnails: [{ width: 100, height: 100 }, { width: 300, height: 300 }]
- * }
- *
- * // PDF documents with deduplication
- * storage: {
- *   accept: 'application/pdf',
- *   maxSize: 20 * 1024 * 1024, // 20MB
- *   folder: 'documents',
- *   dedupe: true
- * }
- *
- * // Multiple images
- * storage: {
- *   accept: 'image/*',
- *   maxFiles: 10,
- *   folder: 'gallery'
- * }
- * ```
- */
-interface FieldStorageConfig {
-    /** Accepted MIME types (e.g., 'image/*', 'application/pdf', 'image/png,image/jpeg') */
-    accept?: string;
-    /** Maximum file size in bytes (default: 10MB = 10485760) */
-    maxSize?: number;
-    /** Maximum number of files for array types (fileArray, imageArray) */
-    maxFiles?: number;
-    /** Folder/prefix in storage bucket (e.g., 'avatars', 'documents/contracts') */
-    folder?: string;
-    /** Thumbnail sizes to auto-generate for images. Creates resized versions on upload */
-    thumbnails?: Array<{
-        width: number;
-        height: number;
-    }>;
-    /** Enable SHA256 hash deduplication - if identical file exists, reuse it instead of uploading again */
-    dedupe?: boolean;
-}
-/**
- * Field metadata for UI behavior and data operations.
- *
- * Controls how the field behaves in tables, forms, exports, and searches.
- *
- * @example
- * ```typescript
- * // Searchable and sortable title field
- * meta: { searchable: true, sortable: true, exportable: true }
- *
- * // Audit field (auto-populated)
- * meta: { auditField: 'created_by', showInForm: false }
- *
- * // Show only in edit form, not create
- * meta: { showInForm: 'edit' }
- *
- * // Hidden from tables but visible in forms
- * meta: { showInDisplay: false }
- * ```
- */
-interface FieldMeta {
-    /** Enable sorting by this field in table columns */
-    sortable?: boolean;
-    /** Include this field in search/filter operations */
-    searchable?: boolean;
-    /** Include this field in CSV/Excel exports */
-    exportable?: boolean;
-    /** Mark as audit field (auto-populated with user ID on create/update) */
-    auditField?: 'created_by' | 'updated_by';
-    /** Show in display components (Table, List, Masonry). Default: true */
-    showInDisplay?: boolean;
-    /** Show in forms. Use 'create'/'edit' for conditional display. Default: true */
-    showInForm?: boolean | 'create' | 'edit';
-}
-/**
- * Conditional boolean - can be static or evaluated at runtime based on record
- * Functions are evaluated in backend before serializing to DTO
- */
-type ConditionalBoolean = boolean | ((record: Record<string, unknown>) => boolean);
-/**
- * Complete field definition for entity fields.
- *
- * This is the core building block for defining entity schemas in Nexus.
- * Contains all the information needed for:
- * - **UI**: Form inputs, table columns, list displays
- * - **Database**: Knex migrations, column types, constraints
- * - **Validation**: Zod schemas, runtime validation rules
- *
- * @example
- * ```typescript
- * const titleField: FieldDefinition = {
- *   name: 'title',
- *   label: { en: 'Title', es: 'Título' },
- *   input: 'text',
- *   required: true,
- *   db: { type: 'string', nullable: false },
- *   validation: { min: 1, max: 200 }
- * }
- * ```
- *
- * @see {@link FieldDefinitionDTO} for the serializable API response version
- * @see {@link EntityDefinition} for the parent entity structure
- */
-interface FieldDefinition {
-    /**
-     * Field identifier used as the database column name.
-     * Should be snake_case for database compatibility.
-     * @example 'title', 'created_at', 'author_id'
-     */
-    name: string;
-    /**
-     * Human-readable label displayed in forms, tables, and lists.
-     * Supports localization with `{ en: '...', es: '...' }` format.
-     */
-    label: LocalizedString;
-    /**
-     * Input type that determines which UI component renders this field.
-     * @see {@link InputType} for all available input types
-     */
-    input: InputType;
-    /**
-     * Placeholder text shown in empty input fields.
-     * Supports localization.
-     */
-    placeholder?: LocalizedString;
-    /**
-     * Help text displayed below the input field.
-     * Use for additional guidance or format hints.
-     */
-    hint?: LocalizedString;
-    /**
-     * Controls field visibility in the UI.
-     * - `true`: Always hidden
-     * - `false`: Always visible
-     * - `(record) => boolean`: Dynamic based on record values
-     * @example hidden: (record) => record.type === 'draft'
-     */
-    hidden?: ConditionalBoolean;
-    /**
-     * Controls whether the field is read-only in forms.
-     * - `true`: Always disabled
-     * - `false`: Always editable
-     * - `(record) => boolean`: Dynamic based on record values
-     * @example disabled: (record) => record.status === 'published'
-     */
-    disabled?: ConditionalBoolean;
-    /**
-     * Marks the field as required for form validation.
-     * - `true`: Always required
-     * - `false`: Always optional
-     * - `(record) => boolean`: Dynamic based on record values
-     * @example required: (record) => record.is_featured === true
-     */
-    required?: ConditionalBoolean;
-    /**
-     * Default value used when creating new records.
-     * Type should match the field's expected data type.
-     */
-    defaultValue?: unknown;
-    /**
-     * Database column configuration for Knex migrations.
-     * Optional for virtual fields, actions, or external data sources.
-     * @see {@link FieldDbConfig}
-     */
-    db?: FieldDbConfig;
-    /**
-     * Foreign key relationship configuration.
-     * Defines how this field relates to another entity's table.
-     * @see {@link FieldRelation}
-     */
-    relation?: FieldRelation;
-    /**
-     * Validation rules applied during form submission and API requests.
-     * Used to generate Zod schemas for runtime validation.
-     * @see {@link FieldValidationConfig}
-     */
-    validation?: FieldValidationConfig;
-    /**
-     * Configuration for select inputs and relationship dropdowns.
-     * Defines static options or dynamic data sources.
-     * @see {@link FieldOptions}
-     */
-    options?: FieldOptions;
-    /**
-     * Storage configuration for file and image inputs.
-     * Defines upload constraints, folders, and thumbnail generation.
-     * @see {@link FieldStorageConfig}
-     */
-    storage?: FieldStorageConfig;
-    /**
-     * Additional metadata for categorization and UI organization.
-     * @see {@link FieldMeta}
-     */
-    meta?: FieldMeta;
-    /**
-     * Additional props passed directly to the form input component.
-     * Allows customization of Naive UI component behavior.
-     * @example inputProps: { rows: 5, showCount: true }
-     */
-    inputProps?: Record<string, unknown>;
-    /**
-     * Additional props passed to display components (table columns, list items).
-     * Use `order` prop to control field position in tables.
-     * @example displayProps: { order: 1, width: 200 }
-     */
-    displayProps?: Record<string, unknown>;
-}
-/**
- * Composite table index definition for database migrations.
- *
- * Creates multi-column indexes for optimized queries.
- *
- * @example
- * ```typescript
- * // Composite index for frequent queries
- * indexes: [{ columns: ['tenant_id', 'created_at'] }]
- *
- * // Unique constraint on multiple columns
- * indexes: [{ columns: ['user_id', 'role_id'], unique: true }]
- * ```
- */
-interface EntityIndex {
-    /** Column names to include in the composite index */
-    columns: string[];
-    /** Create unique constraint on the column combination */
-    unique?: boolean;
-}
-/**
- * Standard CASL authorization actions.
- *
- * - `manage` - Full access (superuser wildcard, includes all actions)
- * - `create` - Create new records
- * - `read` - Read/view records
- * - `update` - Modify existing records
- * - `delete` - Remove records
- * - `execute` - Execute actions/operations on records
- *
- * @see {@link RolePermission} for role-based permission configuration
- * @see https://casl.js.org/v6/en/guide/intro
- */
-type CaslAction = 'manage' | 'create' | 'read' | 'update' | 'delete' | 'execute';
-/**
- * Ownership condition for CASL permissions.
- *
- * Automatically generates conditions that restrict access to records
- * owned by the current user.
- *
- * @example
- * ```typescript
- * // Users can only edit their own posts
- * ownership: { field: 'author_id' }
- * // Generates: { author_id: user.id }
- *
- * // Match against user's email instead of id
- * ownership: { field: 'owner_email', userField: 'email' }
- * // Generates: { owner_email: user.email }
- * ```
- */
-interface OwnershipCondition {
-    /** Entity field that contains the owner reference (e.g., 'author_id', 'created_by') */
-    field: string;
-    /** User property to compare against (default: 'id'). Use 'email' for email-based ownership */
-    userField?: string;
-}
-/**
- * CASL permission definition for a specific role.
- *
- * Defines what actions a role can perform on an entity,
- * optionally with conditions and field restrictions.
- *
- * @example
- * ```typescript
- * // Editor can read and update, but not delete
- * EDITOR: {
- *   actions: ['read', 'update'],
- *   fields: ['title', 'content', 'status']
- * }
- *
- * // Viewer can only read published items
- * VIEWER: {
- *   actions: ['read'],
- *   conditions: { status: 'published' }
- * }
- *
- * // Deny delete for everyone except admin
- * EDITOR: {
- *   actions: ['delete'],
- *   inverted: true
- * }
- * ```
- */
-interface RolePermission {
-    /** Actions this role can perform on the entity */
-    actions: CaslAction[];
-    /** CASL conditions to filter which records the permission applies to */
-    conditions?: Record<string, unknown>;
-    /** Restrict permission to specific fields. null = all fields allowed */
-    fields?: string[] | null;
-    /** If true, this is a denial rule (cannot) instead of allow (can) */
-    inverted?: boolean;
-}
-/**
- * CASL authorization configuration for an entity.
- *
- * Defines role-based access control (RBAC) using CASL.
- * Permissions are evaluated at runtime for each request.
- *
- * @example
- * ```typescript
- * casl: {
- *   subject: 'BlogPost',
- *   ownership: { field: 'author_id' },
- *   permissions: {
- *     ADMIN: { actions: ['manage'] },
- *     EDITOR: { actions: ['read', 'create', 'update'] },
- *     AUTHOR: { actions: ['read', 'update', 'delete'] }, // with ownership
- *     VIEWER: { actions: ['read'], conditions: { status: 'published' } }
- *   },
- *   sensitiveFields: ['internal_notes', 'analytics']
- * }
- * ```
- *
- * @see https://casl.js.org/v6/en/guide/intro
- */
-interface EntityCaslConfig {
-    /** CASL subject name. Default: inferred from table (e.g., 'cms_posts' → 'CmsPost') */
-    subject?: string;
-    /** Ownership configuration for automatic user-based filtering */
-    ownership?: OwnershipCondition;
-    /** Role-based permissions. Keys are role names (ADMIN, EDITOR, VIEWER, etc.) */
-    permissions?: Record<string, RolePermission>;
-    /** Fields excluded from 'read' permission unless explicitly granted. Use for PII or internal data */
-    sensitiveFields?: string[];
-}
-/**
- * Action linked to an entity record.
- * Defines operations that act on existing records.
- *
- * Generated route: GET|POST /{entityRoutePrefix}/{key}/:id
- *
- * @example
- * ```typescript
- * actions: [{
- *   key: 'download',
- *   label: 'Download File',
- *   icon: 'mdi:download',
- *   method: 'GET',
- *   select: ['id', 'filename', 'mimetype'],
- *   handler: async (ctx, input, _req, res) => {
- *     const { _record: file, _authUserId } = input
- *     // file and _authUserId are injected automatically
- *   }
- * }]
- * ```
- */
-interface EntityAction {
-    /** Unique key for the route (e.g., 'download' → /download/:id) */
-    key: string;
-    /** Label for the UI */
-    label: LocalizedString;
-    /** Iconify icon (default: 'mdi:play') */
-    icon?: string;
-    /** HTTP method (default: 'POST') */
-    method?: 'GET' | 'POST' | 'DELETE' | 'PUT' | 'PATCH';
-    /** Fields to select from the record (default: all) */
-    select?: string[];
-    /** Body validation schema (optional) */
-    inputSchema?: ValidationSchema;
-    /** Output schema (documentation) */
-    outputSchema?: ValidationSchema;
-    /** Custom middleware (e.g., multer) */
-    middleware?: (ctx: ModuleContext) => RequestHandler | RequestHandler[];
-    /**
-     * Handler - receives _record and _authUserId automatically.
-     * @param ctx - Module context
-     * @param input - Validated body + _record + _authUserId
-     * @param req - Express Request
-     * @param res - Express Response (for streams, custom headers)
-     */
-    handler: (ctx: ModuleContext, input: unknown, req?: Request, res?: Response) => Promise<unknown>;
-    /**
-     * Skip authentication for this action.
-     * Use for public endpoints like thumbnails, previews, etc.
-     * @default false
-     */
-    skipAuth?: boolean;
-    /**
-     * CASL permissions specific to this action.
-     * If not defined, it inherits permissions from the parent entity.
-     * Ignored if skipAuth is true.
-     */
-    casl?: {
-        /** CASL action (default: 'execute') */
-        action?: string;
-        /** Additional conditions */
-        conditions?: Record<string, unknown>;
-    };
-}
-/**
- * Base properties shared by all EntityDefinition types.
- *
- * @internal This interface is not exported directly. Use specific entity types instead.
- * @see {@link CollectionEntityDefinition}
- * @see {@link SingleEntityDefinition}
- * @see {@link ReferenceEntityDefinition}
- */
-interface BaseEntityDefinition {
-    /** Database table name with module prefix (e.g., 'cms_posts', 'auth_users') */
-    table: string;
-    /** Display name for the UI (singular form) */
-    label: LocalizedString;
-    /** Display name for the UI (plural form, used in navigation menus and list headers) */
-    labelPlural?: LocalizedString;
-    /** Field definitions keyed by field name. See {@link FieldDefinition} */
-    fields: Record<string, FieldDefinition>;
-    /** CASL authorization configuration for role-based access control */
-    casl?: EntityCaslConfig;
-    /** API route prefix. Default: inferred from table name (e.g., 'cms_posts' → '/cms-posts') */
-    routePrefix?: string;
-    /** UI sidebar ordering. Lower values appear first (default: 999) */
-    order?: number;
-    /** UI display mode: 'table' for data grids, 'list' for cards, 'masonry' for image galleries */
-    displayMode?: DisplayMode;
-    /** If true, hides from UI sidebar but entity remains accessible via API */
-    hidden?: boolean;
-}
-/**
- * Collection entity - the most common entity type with full CRUD operations.
- *
- * Use for business data like users, posts, orders, products, etc.
- * This is the default type when `type` is not specified.
- *
- * @example
- * ```typescript
- * const posts: CollectionEntityDefinition = {
- *   type: 'collection', // optional, default
- *   table: 'cms_posts',
- *   label: { en: 'Post', es: 'Publicación' },
- *   labelField: 'title',
- *   timestamps: true,
- *   audit: true,
- *   softDelete: true,
- *   fields: { ... }
- * }
- * ```
- */
-interface CollectionEntityDefinition extends BaseEntityDefinition {
-    /** Entity type. Default: 'collection' */
-    type?: 'collection';
-    /** Field used as display label in dropdowns, references, and breadcrumbs (e.g., 'name', 'title') */
-    labelField: string;
-    /** Auto-add created_at and updated_at timestamp columns */
-    timestamps?: boolean;
-    /** Auto-add created_by and updated_by user reference columns */
-    audit?: boolean;
-    /** Composite database indexes for query optimization */
-    indexes?: EntityIndex[];
-    /** Use soft delete (deleted_at column) instead of physical DELETE */
-    softDelete?: boolean;
-    /** Custom actions that operate on entity records (e.g., download, publish, archive) */
-    actions?: EntityAction[];
-    /** Show "Create" button in UI. Set false for entities created only via API/actions */
-    allowCreate?: boolean;
-    /** Allow editing in UI. Set false for read-only display entities */
-    allowEdit?: boolean;
-}
-/**
- * Singleton entity - stores a single record in the shared sys_settings table.
- *
- * Perfect for application-wide configuration like site settings, SMTP config,
- * feature flags, etc. Data is stored as JSON in a key-value format.
- *
- * @example
- * ```typescript
- * const siteConfig: SingleEntityDefinition = {
- *   type: 'single',
- *   key: 'site_config',
- *   label: { en: 'Site Configuration', es: 'Configuración del Sitio' },
- *   defaults: { siteName: 'My App', maintenanceMode: false },
- *   fields: {
- *     siteName: { name: 'siteName', label: 'Site Name', input: 'text', ... },
- *     logo: { name: 'logo', label: 'Logo', input: 'image', ... }
- *   }
- * }
- * // Stored in sys_settings: { key: 'site_config', value: '{"siteName":"My App","logo":"..."}' }
- * ```
- */
-interface SingleEntityDefinition {
-    /** Entity type identifier */
-    type: 'single';
-    /** Unique key in sys_settings table (e.g., 'site_config', 'smtp_settings', 'feature_flags') */
-    key: string;
-    /** Display name for the UI (singular form) */
-    label: LocalizedString;
-    /** Display name for the UI (plural form) */
-    labelPlural?: LocalizedString;
-    /** Field definitions describing the JSON structure */
-    fields: Record<string, FieldDefinition>;
-    /** Default values applied when the setting is first accessed */
-    defaults?: Record<string, unknown>;
-    /** CASL authorization for read/update operations */
-    casl?: EntityCaslConfig;
-    /** API route prefix. Default: inferred from key */
-    routePrefix?: string;
-    /** Custom actions for this singleton (e.g., 'test-smtp', 'reset-defaults') */
-    actions?: EntityAction[];
-}
-/**
- * Reference entity - read-only catalogs for lookups and dropdowns.
- *
- * Use for relatively static data like countries, currencies, categories, statuses.
- * Data can be seeded from code and optionally edited by admins.
- *
- * @example
- * ```typescript
- * const countries: ReferenceEntityDefinition = {
- *   type: 'reference',
- *   table: 'ref_countries',
- *   label: { en: 'Country', es: 'País' },
- *   labelField: 'name',
- *   seed: [
- *     { code: 'US', name: 'United States' },
- *     { code: 'ES', name: 'Spain' }
- *   ],
- *   allowAdminEdit: true,
- *   fields: { ... }
- * }
- * ```
- */
-interface ReferenceEntityDefinition extends BaseEntityDefinition {
-    /** Entity type identifier */
-    type: 'reference';
-    /** Field used as display label in dropdowns (e.g., 'name', 'title') */
-    labelField: string;
-    /** Auto-add created_at and updated_at timestamp columns */
-    timestamps?: boolean;
-    /** Composite database indexes */
-    indexes?: EntityIndex[];
-    /** Initial seed data inserted on first migration/startup */
-    seed?: Array<Record<string, unknown>>;
-    /** Allow admin users to edit reference data. Default: false (read-only) */
-    allowAdminEdit?: boolean;
-}
-/**
- * Event entity - append-only logs for audit trails and analytics.
- *
- * Records can only be created (appended), never updated or deleted.
- * Supports automatic retention policies to prevent unbounded growth.
- *
- * @example
- * ```typescript
- * const auditLogs: EventEntityDefinition = {
- *   type: 'event',
- *   table: 'sys_audit_logs',
- *   label: { en: 'Audit Log', es: 'Log de Auditoría' },
- *   labelField: 'action',
- *   timestamps: true,
- *   retention: { days: 90, maxRows: 100000 },
- *   fields: {
- *     action: { name: 'action', label: 'Action', input: 'text', ... },
- *     user_id: { name: 'user_id', label: 'User', input: 'select', ... },
- *     payload: { name: 'payload', label: 'Data', input: 'json', ... }
- *   }
- * }
- * ```
- */
-interface EventEntityDefinition extends BaseEntityDefinition {
-    /** Entity type identifier */
-    type: 'event';
-    /** Field used as display label in event lists (e.g., 'action', 'event_type') */
-    labelField: string;
-    /** Auto-add created_at column. Set false if you define timestamp fields explicitly */
-    timestamps?: boolean;
-    /** Automatic data retention to limit table growth */
-    retention?: {
-        /** Delete records older than N days */
-        days?: number;
-        /** Keep only the most recent N records (FIFO) */
-        maxRows?: number;
-    };
-}
-/**
- * Action entity - standalone commands/operations without data persistence.
- *
- * Use for operations like sending emails, generating reports, triggering workflows.
- * For actions that operate on existing records, use {@link EntityAction} instead.
- *
- * @example
- * ```typescript
- * const sendEmail: ActionEntityDefinition = {
- *   type: 'action',
- *   label: { en: 'Send Email', es: 'Enviar Email' },
- *   icon: 'mdi:email-send',
- *   fields: {
- *     to: { name: 'to', label: 'To', input: 'email', required: true },
- *     subject: { name: 'subject', label: 'Subject', input: 'text', required: true },
- *     body: { name: 'body', label: 'Body', input: 'markdown' }
- *   },
- *   handler: async (ctx, input) => {
- *     await ctx.services.mail.send(input)
- *     return { success: true }
- *   }
- * }
- * ```
- */
-interface ActionEntityDefinition {
-    /** Entity type identifier */
-    type: 'action';
-    /** Display name for the action button/form */
-    label: LocalizedString;
-    /** Iconify icon identifier (default: 'mdi:play') */
-    icon?: string;
-    /** Form fields for action input. These don't create database columns */
-    fields: Record<string, FieldDefinition>;
-    /** Zod schema for validating input before execution */
-    inputSchema?: ValidationSchema;
-    /** Zod schema documenting the response structure */
-    outputSchema?: ValidationSchema;
-    /** HTTP method for the action endpoint (default: 'POST') */
-    method?: 'GET' | 'POST' | 'DELETE' | 'PUT' | 'PATCH';
-    /** Custom middleware (e.g., multer for file uploads). Returns single or array of handlers */
-    middleware?: (ctx: ModuleContext) => RequestHandler | RequestHandler[];
-    /** Handler function that executes the action logic. Input includes _authUserId if authenticated */
-    handler?: (ctx: ModuleContext, input: unknown, req?: Request, res?: Response) => Promise<unknown>;
-    /** HTTP status code for success response. Default: 200, use 201 for resource creation */
-    successStatus?: number;
-    /** CASL authorization configuration */
-    casl?: EntityCaslConfig;
-    /** API route prefix for the action endpoint */
-    routePrefix?: string;
-    /** UI sidebar ordering. Lower values appear first (default: 999) */
-    order?: number;
-}
-/**
- * External entity - read-only data from external APIs.
- *
- * Use for integrating third-party services like Stripe customers, GitHub repos,
- * or any external REST API. Data is fetched on-demand through adapters.
- *
- * @example
- * ```typescript
- * const stripeCustomers: ExternalEntityDefinition = {
- *   type: 'external',
- *   label: { en: 'Stripe Customer', es: 'Cliente Stripe' },
- *   labelField: 'email',
- *   adapter: 'stripe',
- *   source: { endpoint: 'customers' },
- *   cache: { ttl: 300, invalidateOn: ['stripe.customer.*'] },
- *   fields: {
- *     id: { name: 'id', label: 'ID', input: 'text' },
- *     email: { name: 'email', label: 'Email', input: 'email' },
- *     name: { name: 'name', label: 'Name', input: 'text' }
- *   }
- * }
- * ```
- */
-interface ExternalEntityDefinition {
-    /** Entity type identifier */
-    type: 'external';
-    /** Display name for the UI (singular form) */
-    label: LocalizedString;
-    /** Display name for the UI (plural form) */
-    labelPlural?: LocalizedString;
-    /** Field used as display label in lists and references */
-    labelField: string;
-    /** Field definitions mapping to the external API response structure */
-    fields: Record<string, FieldDefinition>;
-    /** Registered adapter name that handles API communication (e.g., 'stripe', 'github', 'salesforce') */
-    adapter: string;
-    /** Configuration passed to the adapter */
-    source?: {
-        /** API endpoint or resource path */
-        endpoint?: string;
-        /** Additional adapter-specific configuration */
-        [key: string]: unknown;
-    };
-    /** Response caching to reduce API calls */
-    cache?: {
-        /** Cache time-to-live in seconds */
-        ttl: number;
-        /** Field used to generate unique cache keys */
-        key?: string;
-        /** Event patterns that invalidate cached data (e.g., ['stripe.customer.*']) */
-        invalidateOn?: string[];
-    };
-    /** CASL authorization for read operations */
-    casl?: EntityCaslConfig;
-    /** API route prefix */
-    routePrefix?: string;
-    /** UI sidebar ordering (default: 999) */
-    order?: number;
-    /** UI display mode: 'table', 'list', or 'masonry' */
-    displayMode?: DisplayMode;
-}
-/**
- * Virtual entity - data aggregation across multiple sources.
- *
- * Use to create unified views combining local entities, external APIs, or computed data.
- * Read-only, no persistence - data is resolved on each request.
- *
- * @example
- * ```typescript
- * const unifiedContacts: VirtualEntityDefinition = {
- *   type: 'virtual',
- *   label: { en: 'Contact', es: 'Contacto' },
- *   labelField: 'name',
- *   sources: ['crm_contacts', 'stripe_customers'],
- *   resolver: (sources, ctx) => {
- *     const contacts = sources.crm_contacts.map(c => ({ ...c, source: 'crm' }))
- *     const customers = sources.stripe_customers.map(c => ({ ...c, source: 'stripe' }))
- *     return [...contacts, ...customers]
- *   },
- *   fields: { ... }
- * }
- * ```
- */
-interface VirtualEntityDefinition {
-    /** Entity type identifier */
-    type: 'virtual';
-    /** Display name for the UI (singular form) */
-    label: LocalizedString;
-    /** Display name for the UI (plural form) */
-    labelPlural?: LocalizedString;
-    /** Field used as display label in lists and references */
-    labelField: string;
-    /** Unified field definitions for the combined schema */
-    fields: Record<string, FieldDefinition>;
-    /** Entity or table names to fetch data from */
-    sources: string[];
-    /** Custom function to combine and transform data from all sources */
-    resolver?: (sources: Record<string, unknown[]>, ctx: ModuleContext) => unknown[] | Promise<unknown[]>;
-    /** CASL authorization for read operations */
-    casl?: EntityCaslConfig;
-    /** API route prefix */
-    routePrefix?: string;
-    /** UI sidebar ordering (default: 999) */
-    order?: number;
-    /** UI display mode: 'table', 'list', or 'masonry' */
-    displayMode?: DisplayMode;
-}
-/**
- * Computed entity - dynamically calculated data like KPIs, statistics, and metrics.
- *
- * Use for dashboards, reports, and analytics that derive from other data sources.
- * Read-only, computed on-demand with optional caching.
- *
- * @example
- * ```typescript
- * const salesMetrics: ComputedEntityDefinition = {
- *   type: 'computed',
- *   label: { en: 'Sales Metrics', es: 'Métricas de Ventas' },
- *   isSingle: true, // returns single record with all metrics
- *   cache: { ttl: 60, invalidateOn: ['db.orders.*'] },
- *   compute: async (ctx) => [{
- *     totalSales: await ctx.db('orders').sum('total'),
- *     orderCount: await ctx.db('orders').count(),
- *     avgOrderValue: await ctx.db('orders').avg('total')
- *   }],
- *   fields: {
- *     totalSales: { name: 'totalSales', label: 'Total Sales', input: 'number' },
- *     orderCount: { name: 'orderCount', label: 'Orders', input: 'number' },
- *     avgOrderValue: { name: 'avgOrderValue', label: 'Avg Order', input: 'decimal' }
- *   }
- * }
- * ```
- */
-interface ComputedEntityDefinition {
-    /** Entity type identifier */
-    type: 'computed';
-    /** Display name for the UI (singular form) */
-    label: LocalizedString;
-    /** Display name for the UI (plural form) */
-    labelPlural?: LocalizedString;
-    /** Field used as display label (optional for computed entities) */
-    labelField?: string;
-    /** Field definitions for the computed result structure */
-    fields: Record<string, FieldDefinition>;
-    /** Function that computes and returns the data. Receives query params from URL */
-    compute?: (ctx: ModuleContext, params?: Record<string, unknown>) => Promise<unknown[]>;
-    /** Caching to avoid recomputation on every request */
-    cache?: {
-        /** Cache time-to-live in seconds. 0 = no caching */
-        ttl: number;
-        /** Event patterns that trigger cache invalidation */
-        invalidateOn?: string[];
-    };
-    /** If true, returns single object instead of array (for dashboards, system info) */
-    isSingle?: boolean;
-    /** CASL authorization for read operations */
-    casl?: EntityCaslConfig;
-    /** API route prefix */
-    routePrefix?: string;
-    /** UI sidebar ordering (default: 999) */
-    order?: number;
-    /** UI display mode: 'table', 'list', or 'masonry' */
-    displayMode?: DisplayMode;
-}
-/**
- * View entity - read-only database view or projection.
- *
- * Use for optimized read patterns, denormalized data, or SQL VIEWs.
- * Can reference actual database views or define virtual queries.
- *
- * @example
- * ```typescript
- * const orderSummary: ViewEntityDefinition = {
- *   type: 'view',
- *   table: 'v_order_summary', // actual SQL VIEW
- *   label: { en: 'Order Summary', es: 'Resumen de Pedidos' },
- *   labelField: 'order_number',
- *   sourceEntity: 'orders',
- *   query: (db) => db('orders')
- *     .select('orders.*', 'customers.name as customer_name')
- *     .join('customers', 'orders.customer_id', 'customers.id'),
- *   fields: { ... }
- * }
- * ```
- */
-interface ViewEntityDefinition {
-    /** Entity type identifier */
-    type: 'view';
-    /** Database table or SQL VIEW name */
-    table: string;
-    /** Display name for the UI (singular form) */
-    label: LocalizedString;
-    /** Display name for the UI (plural form) */
-    labelPlural?: LocalizedString;
-    /** Field used as display label in lists and references */
-    labelField: string;
-    /** Field definitions for the view columns */
-    fields: Record<string, FieldDefinition>;
-    /** Source entity this view derives from (for documentation) */
-    sourceEntity?: string;
-    /** SQL query string or Knex query builder function to define the view */
-    query?: string | ((db: Knex) => Knex.QueryBuilder);
-    /** CASL authorization for read operations */
-    casl?: EntityCaslConfig;
-    /** API route prefix */
-    routePrefix?: string;
-    /** UI sidebar ordering (default: 999) */
-    order?: number;
-}
-/**
- * Config entity - scoped configuration settings.
- *
- * Similar to single entity but with scoping support for multi-tenant,
- * per-module, or per-user configurations.
- *
- * @example
- * ```typescript
- * const moduleConfig: ConfigEntityDefinition = {
- *   type: 'config',
- *   table: 'module_configs',
- *   label: { en: 'Module Config', es: 'Config de Módulo' },
- *   scope: 'module',
- *   scopeField: 'module_name',
- *   defaults: { enableFeatureX: false, maxItems: 100 },
- *   timestamps: true,
- *   fields: {
- *     module_name: { name: 'module_name', label: 'Module', input: 'text' },
- *     enableFeatureX: { name: 'enableFeatureX', label: 'Feature X', input: 'switch' },
- *     maxItems: { name: 'maxItems', label: 'Max Items', input: 'number' }
- *   }
- * }
- * ```
- */
-interface ConfigEntityDefinition extends BaseEntityDefinition {
-    /** Entity type identifier */
-    type: 'config';
-    /** Field that identifies the configuration scope (e.g., 'module_name', 'tenant_id', 'user_id') */
-    scopeField?: string;
-    /** Configuration scope level: 'global', 'module', 'tenant', or 'user' */
-    scope?: 'global' | 'module' | 'tenant' | 'user';
-    /** Default values applied when config is first accessed */
-    defaults?: Record<string, unknown>;
-    /** Auto-add updated_at timestamp column */
-    timestamps?: boolean;
-    /** Auto-add updated_by user reference column */
-    audit?: boolean;
-}
-/**
- * Temporary entity - short-lived data with automatic expiration.
- *
- * Use for OTP codes, session tokens, password reset links, cache entries.
- * Records are automatically deleted after TTL expires.
- *
- * @example
- * ```typescript
- * const otpCodes: TempEntityDefinition = {
- *   type: 'temp',
- *   table: 'auth_otp_codes',
- *   label: { en: 'OTP Code', es: 'Código OTP' },
- *   ttl: 300, // 5 minutes
- *   indexes: [{ columns: ['user_id', 'code'] }],
- *   fields: {
- *     user_id: { name: 'user_id', label: 'User', input: 'select', ... },
- *     code: { name: 'code', label: 'Code', input: 'text', ... },
- *     expires_at: { name: 'expires_at', label: 'Expires', input: 'datetime', ... }
- *   }
- * }
- * ```
- */
-interface TempEntityDefinition extends BaseEntityDefinition {
-    /** Entity type identifier */
-    type: 'temp';
-    /** Time-to-live in seconds. Records are deleted after this duration */
-    ttl: number;
-    /** Field that stores the expiration timestamp (default: 'expires_at') */
-    ttlField?: string;
-    /** Field used as display label in lists (optional for temp entities) */
-    labelField?: string;
-    /** Database indexes for efficient lookups */
-    indexes?: EntityIndex[];
-}
-/**
- * All available entity type identifiers.
- *
- * @see {@link EntityDefinition} for the full discriminated union with documentation
- */
-type EntityType = 'collection' | 'single' | 'external' | 'virtual' | 'computed' | 'view' | 'reference' | 'config' | 'event' | 'temp' | 'action';
-/**
- * Display mode for entity list views in the UI.
- *
- * - `table` - Data grid with columns, sorting, filtering (default)
- * - `list` - Card-based vertical list
- * - `masonry` - Pinterest-style image gallery grid
- */
-type DisplayMode = 'table' | 'list' | 'masonry';
-/**
- * Union of all entity definitions
- *
- * | Type       | Persistence | CRUD            | Primary use                      |
- * |------------|-------------|-----------------|----------------------------------|
- * | collection | Yes (DB)    | Full            | Business data (users, posts)     |
- * | single     | Yes (DB)    | Update/Read     | Global config (site_config)      |
- * | external   | No          | Read            | External data (stripe_customers) |
- * | virtual    | No          | Read            | Orchestration (unified_customers)|
- * | computed   | No/optional | Read            | KPIs, stats                      |
- * | view       | Yes/virtual | Read            | Optimized reads (projections)    |
- * | reference  | Yes         | Read (admin)    | Catalogs (countries, currencies) |
- * | config     | Yes         | Update/Read     | Per-module config                |
- * | event      | Yes         | Append          | Audit logs (audit_logs)          |
- * | temp       | No (TTL)    | Read/Write      | Cache, sessions (otp_codes)      |
- * | action     | No          | Execute         | Operations, workflows            |
- */
-type EntityDefinition = CollectionEntityDefinition | SingleEntityDefinition | ExternalEntityDefinition | VirtualEntityDefinition | ComputedEntityDefinition | ViewEntityDefinition | ReferenceEntityDefinition | ConfigEntityDefinition | EventEntityDefinition | TempEntityDefinition | ActionEntityDefinition;
-/**
- * Requirements that must be met to activate a module.
- *
- * Modules with unmet requirements are skipped during initialization.
- *
- * @example
- * ```typescript
- * requirements: {
- *   env: ['STRIPE_SECRET_KEY', 'STRIPE_WEBHOOK_SECRET'],
- *   modules: ['auth', 'storage']
- * }
- * ```
- */
-interface ModuleRequirements {
-    /** Environment variables that must be defined */
-    env?: string[];
-    /** Other modules that must be loaded first */
-    modules?: string[];
-}
-/**
- * Generic interface for CASL ability.
- *
- * Provides permission checking without directly depending on @casl/ability package.
- * Used in request objects for authorization checks.
- *
- * @example
- * ```typescript
- * if (req.ability.can('update', post)) {
- *   // User can update this post
- * }
- * if (req.ability.cannot('delete', post)) {
- *   throw new ForbiddenError('Cannot delete post')
- * }
- * ```
- */
-interface AbilityLike {
-    /** Check if action is allowed on subject */
-    can: (action: string, subject: unknown) => boolean;
-    /** Check if action is denied on subject */
-    cannot: (action: string, subject: unknown) => boolean;
-}
-/**
- * CASL ForbiddenError instance for throwing permission errors.
- */
-interface ForbiddenErrorInstance {
-    /** Throws ForbiddenError if action is not allowed on subject */
-    throwUnlessCan: (action: string, subject: unknown) => void;
-}
-/**
- * CASL ForbiddenError constructor for creating error instances.
- */
-interface ForbiddenErrorConstructor {
-    /** Creates a ForbiddenErrorInstance bound to an ability */
-    from: (ability: any) => ForbiddenErrorInstance;
-}
-/**
- * CASL abilities API available in module context.
- *
- * Allows modules to use CASL for authorization without importing @casl/ability directly.
- *
- * @example
- * ```typescript
- * // In module handler
- * const ability = ctx.abilities.defineAbilityFor(user)
- * ctx.abilities.ForbiddenError.from(ability).throwUnlessCan('update', post)
- * ```
- */
-interface ModuleAbilities {
-    /** Creates CASL ability instance for a user based on their roles */
-    defineAbilityFor: (user: {
-        id: string;
-    } | null, ...args: unknown[]) => unknown;
-    /** Serializes CASL rules for client-side authorization (frontend) */
-    packRules: (ability: unknown) => unknown[];
-    /** Wraps an object as CASL subject for instance-level permission checks */
-    subject: (type: string, object: Record<string, unknown>) => unknown;
-    /** ForbiddenError constructor for throwUnlessCan pattern */
-    ForbiddenError: ForbiddenErrorConstructor;
-}
-/**
- * Pre-typed authenticated request with BaseUser and AbilityLike.
- *
- * Use this type for route handlers that require authentication.
- *
- * @example
- * ```typescript
- * const handler = async (req: AuthRequest, res: Response) => {
- *   const userId = req.user.id
- *   if (req.ability.can('read', 'Post')) { ... }
- * }
- * ```
- */
-type AuthRequest = BaseAuthRequest<BaseUser, AbilityLike>;
-/**
- * Helper utilities available in module context.
- *
- * Provides common operations for migrations, ID generation, and path resolution.
- */
-interface ContextHelpers {
-    /** Generates a unique UUID v4 identifier */
-    generateId: () => string;
-    /** Adds created_at and updated_at columns to a table during migration */
-    addTimestamps: (table: Knex.CreateTableBuilder, db: Knex) => void;
-    /** Adds created_by and updated_by columns if they don't exist */
-    addAuditFieldsIfMissing: (db: Knex, tableName: string) => Promise<void>;
-    /** Adds is_default boolean field for config tables */
-    addConfigDefaultField: (db: Knex, tableName: string) => Promise<void>;
-    /** Adds a column only if it doesn't exist. Returns true if column was added */
-    addColumnIfMissing: (db: Knex, tableName: string, columnName: string, columnBuilder: (table: Knex.AlterTableBuilder) => void) => Promise<boolean>;
-    /** Gets the path to the nexus-backend library directory */
-    getLibPath: () => string;
-    /** Gets the path to the user's project root directory */
-    getProjectPath: () => string;
-    /** Returns current timestamp formatted for the DB driver (MySQL: 'YYYY-MM-DD HH:MM:SS', others: ISO 8601) */
-    nowTimestamp: (db: Knex) => string;
-    /** Formats a Date object for the current DB driver */
-    formatTimestamp: (db: Knex, date?: Date) => string;
-    /**
-     * Safely parses JSON with automatic error logging.
-     * Returns fallback value if parsing fails instead of throwing.
-     * @param jsonString - JSON string to parse
-     * @param fallback - Value to return if parsing fails
-     * @param context - Optional context for logging (e.g. { notificationId: 'x', context: 'markAsRead' })
-     */
-    safeJsonParse: <T>(jsonString: string, fallback: T, context?: Record<string, unknown>) => T;
-}
-/**
- * Cryptographic utilities for password handling.
- *
- * Uses bcrypt with cost factor 12 for secure password hashing.
- */
-interface ContextCrypto {
-    /** Hashes a password using bcrypt (cost factor 12) */
-    hashPassword: (password: string) => Promise<string>;
-    /** Verifies password against bcrypt hash (timing-safe comparison) */
-    verifyPassword: (password: string, hash: string) => Promise<boolean>;
-    /** Pre-computed dummy hash for timing-safe comparison when user doesn't exist */
-    DUMMY_HASH: string;
-}
-/**
- * Socket.IO real-time communication API.
- *
- * Provides access to WebSocket connections for real-time features.
- * Only available if Socket.IO is initialized in the backend configuration.
- */
-/**
- * Socket.IO Server interface (minimal type-safe subset)
- * Avoids importing socket.io package as dependency in SDK
- */
-interface SocketIOServer {
-    /** Emits event to a specific room */
-    to(room: string): SocketIOBroadcastOperator;
-    /** Emits event to a specific room (alias for to) */
-    in(room: string): SocketIOBroadcastOperator;
-    /** Emits event to all connected clients */
-    emit(event: string, ...args: unknown[]): boolean;
-    /** Access to all connected sockets */
-    sockets: {
-        sockets: Map<string, unknown>;
-    };
-}
-/**
- * Socket.IO Broadcast Operator interface (minimal type-safe subset)
- */
-interface SocketIOBroadcastOperator {
-    /** Emits event to all sockets in the room */
-    emit(event: string, ...args: unknown[]): void;
-    /** Fetches all sockets in the room */
-    fetchSockets(): Promise<unknown[]>;
-}
-interface ContextSocket {
-    /** Gets the Socket.IO server instance. Throws if not initialized */
-    getIO: () => SocketIOServer;
-    /** Checks if Socket.IO server is running */
-    isInitialized: () => boolean;
-    /** Checks if a specific user has active WebSocket connections */
-    isUserConnected: (userId: string) => boolean;
-    /** Gets the number of active sockets for a user (multiple tabs/devices) */
-    getUserSocketCount: (userId: string) => number;
-    /** Gets array of all connected user IDs */
-    getConnectedUsers: () => string[];
-    /** Joins a user to a custom room (all their sockets) */
-    joinUserToRoom: (userId: string, room: string) => boolean;
-    /** Removes a user from a custom room (all their sockets) */
-    removeUserFromRoom: (userId: string, room: string) => boolean;
-    /** Joins a specific socket to a room */
-    joinSocketToRoom: (socketId: string, room: string) => boolean;
-    /** Removes a specific socket from a room */
-    removeSocketFromRoom: (socketId: string, room: string) => boolean;
-    /** Gets all user IDs in a room */
-    getRoomMembers: (room: string) => Promise<string[]>;
-    /** Gets the number of sockets in a room */
-    getRoomSize: (room: string) => Promise<number>;
-    /** Gets all custom rooms a user is in (excluding system rooms) */
-    getUserRooms: (userId: string) => string[];
-    /** Checks if a room has any members */
-    roomExists: (room: string) => Promise<boolean>;
-    /** Emits an event to a specific room */
-    emitToRoom: (room: string, event: string, data: unknown) => boolean;
-    /** Emits an event to a specific user (all their sockets) */
-    emitToUser: (userId: string, event: string, data: unknown) => boolean;
-    /** Emits an event to all users with a specific role */
-    emitToRole: (roleId: string, event: string, data: unknown) => boolean;
-    /** Emits an event to all connected sockets */
-    emitToAll: (event: string, data: unknown) => boolean;
-    /** Emits an event to all authenticated users */
-    emitToAuthenticated: (event: string, data: unknown) => boolean;
-    /** Broadcasts to a room except specific user(s) */
-    broadcastToRoom: (room: string, exceptUserIds: string | string[], event: string, data: unknown) => boolean;
-}
-/**
- * Application manifest with module and plugin registry.
- *
- * Represents either the core nexus-backend manifest or a user project manifest.
- */
-interface AppManifest {
-    /** Package name from package.json */
-    name: string;
-    /** Package version from package.json */
-    version: string;
-    /** Registered modules in this application */
-    modules: ModuleManifest[];
-    /** Registered plugins (only present in user manifest) */
-    plugins?: PluginManifest[];
-}
-/**
- * Engine API for runtime introspection of modules and plugins.
- *
- * Provides access to the complete registry of loaded components.
- */
-interface ContextEngine {
-    /** Gets all registered modules (core + user) */
-    getModules: () => ModuleManifest[];
-    /** Gets all registered plugins */
-    getPlugins: () => PluginManifest[];
-    /** Gets CASL subjects defined by a specific module */
-    getModuleSubjects: (mod: ModuleManifest) => string[];
-    /** Gets all CASL subjects registered across all modules */
-    getRegisteredSubjects: () => string[];
-    /** Gets modules from nexus-backend core (auth, users, storage, etc.) */
-    getCoreModules: () => ModuleManifest[];
-    /** Gets modules from user project and plugins */
-    getUserModules: () => ModuleManifest[];
-    /** Gets the nexus-backend library manifest */
-    getCoreManifest: () => AppManifest;
-    /** Gets the user project manifest. Returns null in standalone development mode */
-    getUserManifest: () => AppManifest | null;
-    /** Returns true if running as a library inside a user project */
-    hasUserApp: () => boolean;
-}
-/**
- * Generic validation schema interface compatible with Zod.
- *
- * Any object with a parse() method that throws on invalid data works.
- */
-interface ValidationSchema {
-    /** Parses and validates data. Throws on validation failure */
-    parse: (data: unknown) => unknown;
-}
-/**
- * Schemas for the validation middleware.
- *
- * Validates request body, query parameters, and URL parameters.
- */
-interface ValidateSchemas {
-    /** Schema for request body (req.body) */
-    body?: ValidationSchema;
-    /** Schema for query parameters (req.query) */
-    query?: ValidationSchema;
-    /** Schema for URL parameters (req.params) */
-    params?: ValidationSchema;
-}
-/**
- * Configuration options for rate limiting middleware.
- */
-interface RateLimitOptions {
-    /** Time window duration in milliseconds (default: 60000 = 1 minute) */
-    windowMs?: number;
-    /** Maximum requests allowed per window (default: 100) */
-    max?: number;
-    /** Error message when rate limit is exceeded */
-    message?: string;
-}
-/**
- * Middleware factories available in module context.
- *
- * Provides common Express middlewares for validation, rate limiting, etc.
- */
-interface ModuleMiddlewares {
-    /** Creates validation middleware for body/query/params */
-    validate: (schemas: ValidateSchemas) => RequestHandler;
-    /** Creates rate limiting middleware */
-    rateLimit: (options?: RateLimitOptions) => RequestHandler;
-    /** Extensible: additional middlewares can be registered */
-    [key: string]: RequestHandler | ((...args: any[]) => RequestHandler) | undefined;
-}
-/**
- * Minimal EventEmitter interface compatible with EventEmitter2.
- *
- * Used for inter-module communication and event-driven architecture.
- */
-interface EventEmitterLike {
-    /** Emits an event with arguments. Returns true if listeners exist */
-    emit: (event: string, ...args: unknown[]) => boolean;
-    /** Registers an event listener */
-    on: (event: string, listener: (...args: unknown[]) => void) => this;
-    /** Removes an event listener */
-    off: (event: string, listener: (...args: unknown[]) => void) => this;
-    /** Registers a one-time event listener */
-    once: (event: string, listener: (...args: unknown[]) => void) => this;
-    /** Registers a listener for all events (EventEmitter2 feature) */
-    onAny?: (listener: (event: string, ...args: unknown[]) => void) => this;
-}
-/**
- * Error reporter interface for external monitoring services.
- *
- * Compatible with Sentry, GlitchTip, or any error tracking service.
- */
-interface LoggerReporter {
-    /** Captures and reports an exception to the monitoring service */
-    captureException: (error: Error, context?: Record<string, unknown>) => void;
-}
-/**
- * Filter operators for advanced filtering
- *
- * @example
- * // Simple equality (shorthand)
- * { status: 'active' }
- *
- * // With operators
- * { name: { $contains: 'john' } }
- * { age: { $gte: 18 } }
- * { email: { $startswith: 'admin' } }
- *
- * // Array (IN operator shorthand)
- * { status: ['active', 'pending'] }
- */
-interface FilterOperators {
-    /** Equal (default if no operator) */
-    $eq?: unknown;
-    /** Not equal */
-    $ne?: unknown;
-    /** Greater than */
-    $gt?: number | string | Date;
-    /** Greater than or equal */
-    $gte?: number | string | Date;
-    /** Less than */
-    $lt?: number | string | Date;
-    /** Less than or equal */
-    $lte?: number | string | Date;
-    /** Contains (LIKE %value%) */
-    $contains?: string;
-    /** Starts with (LIKE value%) */
-    $startswith?: string;
-    /** Ends with (LIKE %value) */
-    $endswith?: string;
-    /** In array */
-    $in?: unknown[];
-    /** Not in array */
-    $nin?: unknown[];
-    /** Is null (true = IS NULL, false = IS NOT NULL) */
-    $isnull?: boolean;
-}
-/**
- * Filter value can be:
- * - Primitive (shorthand for $eq)
- * - Array (shorthand for $in)
- * - Object with operators
- */
-type FilterValue = string | number | boolean | null | unknown[] | FilterOperators;
-/**
- * Query parameters for entity list operations
- *
- * @example
- * // Simple filters
- * { filters: { status: 'active' } }
- *
- * // With operators (see FilterOperators)
- * { filters: { name: { $contains: 'john' }, age: { $gte: 18 } } }
- */
-interface EntityQuery {
-    page?: number;
-    limit?: number;
-    sort?: string;
-    order?: 'asc' | 'desc';
-    search?: string;
-    /** Filters with optional operators - use FilterValue type for type safety */
-    filters?: Record<string, unknown>;
-}
-/**
- * Role management service interface.
- *
- * Provides CRUD operations for roles. Used internally by UsersService.
- */
-interface BaseRolesService {
-    /** Gets paginated list of all roles */
-    findAll(query?: EntityQuery): Promise<PaginatedResult<unknown>>;
-    /** Gets a role by its ID */
-    findById(id: string): Promise<unknown>;
-    /** Gets a role by its name (e.g., 'ADMIN', 'EDITOR') */
-    findByName(name: string): Promise<unknown | undefined>;
-    /** Creates a new role */
-    create(data: Record<string, unknown>, userId?: string): Promise<unknown>;
-    /** Updates an existing role */
-    update(id: string, data: Record<string, unknown>, userId?: string): Promise<unknown>;
-    /** Deletes a role by ID */
-    delete(id: string): Promise<void>;
-}
-/**
- * User management service interface.
- *
- * Provides user CRUD and role assignment operations.
- * The backend extends this with concrete types (UserWithRole, etc.).
- */
-interface BaseUsersService {
-    /** Gets paginated list of users */
-    findAll(query?: EntityQuery): Promise<PaginatedResult<unknown>>;
-    /** Gets a user by ID without role information */
-    findById(id: string): Promise<unknown>;
-    /** Gets a user by ID including their assigned roles */
-    findByIdWithRoles(id: string): Promise<unknown | null>;
-    /** Creates a new user */
-    create(data: Record<string, unknown>, userId?: string): Promise<unknown>;
-    /** Updates an existing user */
-    update(id: string, data: Record<string, unknown>, userId?: string): Promise<unknown>;
-    /** Deletes a user by ID */
-    delete(id: string): Promise<void>;
-    /** Gets array of role IDs for a user */
-    getRoleIds(userId: string): Promise<string[]>;
-    /** Gets array of role names for a user (e.g., ['ADMIN', 'EDITOR']) */
-    getRoleNames(userId: string): Promise<string[]>;
-    /** Gets full role objects for a user */
-    getUserRoles(userId: string): Promise<unknown[]>;
-    /** Assigns a single role to a user (adds to existing roles) */
-    assignRole(userId: string, roleId: string): Promise<void>;
-    /** Removes a single role from a user */
-    removeRole(userId: string, roleId: string): Promise<void>;
-    /** Replaces all user roles with the provided list */
-    setRoles(userId: string, roleIds: string[]): Promise<void>;
-    /** Nested roles service for direct role management */
-    roles: BaseRolesService;
-}
-/**
- * Email sending options.
- *
- * Supports both simple text emails and rich HTML templates with actions.
- */
-interface SendMailOptions {
-    /** Recipient email address(es) */
-    to: string | string[];
-    /** Email subject line */
-    subject: string;
-    /** Title for email template (displayed prominently) */
-    title?: string;
-    /** Plain text message for simple emails */
-    message?: string;
-    /** Full HTML content (overrides template) */
-    html?: string;
-    /** Plain text fallback (generated from HTML if not provided) */
-    text?: string;
-    /** Sender email address (uses default if not provided) */
-    from?: string;
-    /** Reply-to email address */
-    replyTo?: string;
-    /** CTA buttons for email template */
-    actions?: Array<{
-        label: string;
-        url: string;
-    }>;
-    /** Logo URL for email header */
-    logoUrl?: string;
-    /** File attachments */
-    attachments?: Array<{
-        filename: string;
-        content: Buffer | string;
-        contentType?: string;
-    }>;
-}
-/**
- * Result from sending an email.
- */
-interface SendMailResult {
-    /** Unique message ID from the mail server */
-    messageId: string;
-    /** Email addresses that accepted the message */
-    accepted: string[];
-    /** Email addresses that rejected the message */
-    rejected: string[];
-}
-/**
- * Email service interface for sending emails.
- */
-interface BaseMailService {
-    /** Sends an email. Returns null if mail service is not configured */
-    send(options: SendMailOptions): Promise<SendMailResult | null>;
-    /** Verifies SMTP connection is working */
-    verify(): Promise<boolean>;
-}
-/**
- * Core services available via ctx.services.
- *
- * Modules can extend this with additional services.
- */
-interface CoreServices {
-    /** Error logging and reporting service */
-    logger?: LoggerReporter;
-    /** User management service */
-    users?: BaseUsersService;
-    /** Email sending service */
-    mail?: BaseMailService;
-    /** Extensible: additional services registered by modules */
-    [key: string]: unknown;
-}
-/**
- * Base interface for all entity services.
- *
- * Provides read operations common to all entity types.
- */
-interface BaseEntityService<T = unknown> {
-    /** Gets paginated list of records with optional filtering/sorting */
-    findAll(query?: EntityQuery): Promise<PaginatedResult<T>>;
-    /** Gets a single record by ID. Returns null if not found */
-    findById(id: string): Promise<T | null>;
-    /** The entity definition this service operates on */
-    readonly definition: EntityDefinition;
-}
-/**
- * Service for Collection entities with full CRUD operations.
- *
- * @see {@link CollectionEntityDefinition}
- */
-interface CollectionEntityService<T = unknown> extends BaseEntityService<T> {
-    /** Creates a new record. userId is used for audit fields */
-    create(data: Partial<T>, userId?: string): Promise<T>;
-    /** Updates an existing record by ID */
-    update(id: string, data: Partial<T>, userId?: string): Promise<T>;
-    /** Deletes a record by ID (soft delete if configured) */
-    delete(id: string): Promise<void>;
-}
-/**
- * Service for Temp entities with automatic TTL expiration.
- *
- * @see {@link TempEntityDefinition}
- */
-interface TempEntityService<T = unknown> extends BaseEntityService<T> {
-    /** Creates a temporary record with automatic expiration */
-    create(data: Partial<T>): Promise<T>;
-    /** Updates a record. Optionally extends TTL from current time */
-    update(id: string, data: Partial<T>, extendTtl?: boolean): Promise<T>;
-    /** Deletes a record immediately */
-    delete(id: string): Promise<void>;
-    /** Extends the TTL of a record by additional seconds */
-    extendTtl(id: string, additionalSeconds?: number): Promise<T>;
-    /** Removes all expired records. Returns count of deleted records */
-    cleanup(): Promise<number>;
-    /** Gets remaining TTL in seconds. Returns null if expired or not found */
-    getRemainingTtl(id: string): Promise<number | null>;
-    /** Checks if a record exists and hasn't expired */
-    isValid(id: string): Promise<boolean>;
-}
-/**
- * Service for Event entities (append-only audit logs).
- *
- * @see {@link EventEntityDefinition}
- */
-interface EventEntityService<T = unknown> extends BaseEntityService<T> {
-    /** Creates a new event record (append-only) */
-    create(data: Partial<T>): Promise<T>;
-    /** Alias for create - appends a new event */
-    append(data: Partial<T>): Promise<T>;
-    /** Runs retention policy cleanup. Returns count of deleted records */
-    runRetentionCleanup(): Promise<number>;
-    /** Queries events within a date range */
-    findByDateRange(start: Date, end: Date, query?: EntityQuery): Promise<PaginatedResult<T>>;
-}
-/**
- * Service for Single entities (global configuration).
- *
- * @see {@link SingleEntityDefinition}
- */
-interface SingleEntityService<T = unknown> extends BaseEntityService<T> {
-    /** Gets the single record (creates with defaults if not exists) */
-    get(): Promise<T | null>;
-    /** Updates the single record */
-    update(data: Partial<T>, userId?: string): Promise<T>;
-}
-/**
- * Service for Config entities (scoped key-value configuration).
- *
- * @see {@link ConfigEntityDefinition}
- */
-interface ConfigEntityService<T = unknown> extends BaseEntityService<T> {
-    /** Gets configuration value by key */
-    get(key: string): Promise<T | null>;
-    /** Sets configuration value for a key */
-    set(key: string, value: unknown, userId?: string): Promise<T>;
-    /** Gets all configuration as key-value object */
-    getAll(): Promise<Record<string, unknown>>;
-}
-/**
- * Service for Reference entities (read-only catalogs).
- * @see {@link ReferenceEntityDefinition}
- */
-type ReferenceEntityService<T = unknown> = BaseEntityService<T>;
-/**
- * Service for View entities (SQL views, read-only).
- * @see {@link ViewEntityDefinition}
- */
-type ViewEntityService<T = unknown> = BaseEntityService<T>;
-/**
- * Service for Computed entities (dynamically calculated data).
- * @see {@link ComputedEntityDefinition}
- */
-type ComputedEntityService<T = unknown> = BaseEntityService<T>;
-/**
- * Service for External entities (external API data).
- * @see {@link ExternalEntityDefinition}
- */
-type ExternalEntityService<T = unknown> = BaseEntityService<T>;
-/**
- * Service for Virtual entities (aggregated from multiple sources).
- * @see {@link VirtualEntityDefinition}
- */
-type VirtualEntityService<T = unknown> = BaseEntityService<T>;
-/**
- * Service for Action entities (command execution).
- *
- * @see {@link ActionEntityDefinition}
- */
-interface ActionEntityService<T = unknown> {
-    /** Executes the action with provided input data */
-    execute(data: Partial<T>): Promise<unknown>;
-    /** The action definition this service implements */
-    readonly definition: EntityDefinition;
-}
-/**
- * Hooks to customize entity service behavior.
- * Allows plugins to add logic without inheritance.
- */
-interface EntityServiceHooks<T = unknown> {
-    /**
-     * Runs before creating a record.
-     * @param data Data to insert
-     * @returns Modified data
-     */
-    beforeCreate?: (data: Partial<T>) => Promise<Partial<T>> | Partial<T>;
-    /**
-     * Runs after creating a record.
-     * @param record Created record
-     */
-    afterCreate?: (record: T) => Promise<void> | void;
-    /**
-     * Runs before updating a record.
-     * @param id Record ID
-     * @param data Data to update
-     * @returns Modified data
-     */
-    beforeUpdate?: (id: string, data: Partial<T>) => Promise<Partial<T>> | Partial<T>;
-    /**
-     * Runs after updating a record.
-     * @param record Updated record
-     */
-    afterUpdate?: (record: T) => Promise<void> | void;
-    /**
-     * Runs before deleting a record.
-     * @param id Record ID
-     */
-    beforeDelete?: (id: string) => Promise<void> | void;
-    /**
-     * Runs after deleting a record.
-     * @param id Deleted ID
-     */
-    afterDelete?: (id: string) => Promise<void> | void;
-    /**
-     * Runs after getting a record by ID.
-     * @param record Retrieved record (or null)
-     * @returns Modified record
-     */
-    afterFindById?: (record: T | null) => Promise<T | null> | T | null;
-    /**
-     * Runs after retrieving a paginated list.
-     * @param result Paginated result
-     * @returns Modified result
-     */
-    afterFindAll?: (result: PaginatedResult<T>) => Promise<PaginatedResult<T>> | PaginatedResult<T>;
-}
-/**
- * Options for createEntityService
- */
-interface CreateEntityServiceOptions<T = unknown> {
-    /** Hooks to customize behavior */
-    hooks?: EntityServiceHooks<T>;
-}
-/**
- * Express route handler type for entity operations.
- */
-type EntityHandler = (req: Request, res: Response) => Promise<void>;
-/**
- * Entity controller with CRUD operation handlers.
- *
- * Generated by `createEntityController` with built-in CASL authorization.
- */
-interface EntityController {
-    /** GET / - List all records with pagination */
-    list: EntityHandler;
-    /** GET /:id - Get single record by ID */
-    get: EntityHandler;
-    /** POST / - Create new record (collection entities) */
-    create?: EntityHandler;
-    /** PUT /:id - Update existing record */
-    update?: EntityHandler;
-    /** DELETE /:id - Delete record */
-    delete?: EntityHandler;
-    /** POST /:id/:action - Execute entity action */
-    execute?: EntityHandler;
-}
-/**
- * Module context providing access to all Nexus services and utilities.
- *
- * Injected into module lifecycle functions (init, routes, migrate, seed).
- *
- * @example
- * ```typescript
- * const myModule: ModuleManifest = {
- *   name: 'my-module',
- *   routes: (ctx) => {
- *     const router = ctx.createRouter()
- *     router.get('/hello', (req, res) => res.json({ message: 'Hello!' }))
- *     return router
- *   }
- * }
- * ```
- */
-interface ModuleContext {
-    /** Knex database connection for queries and transactions */
-    db: Knex;
-    /** Pino logger instance for structured logging */
-    logger: Logger;
-    /** Helper utilities for migrations and common operations */
-    helpers: ContextHelpers;
-    /** Cryptographic utilities (password hashing) */
-    crypto: ContextCrypto;
-    /** Socket.IO API for real-time communication */
-    socket: ContextSocket;
-    /** Engine API for module/plugin introspection */
-    engine: ContextEngine;
-    /** Factory for creating Express routers */
-    createRouter: () => Router;
-    /** Middleware factories (validate, rateLimit, etc.) */
-    middleware: ModuleMiddlewares;
-    /** Resolved application configuration from env and config files */
-    config: Record<string, unknown>;
-    /** HTTP error constructors for consistent error responses */
-    errors: {
-        /** Generic application error with status code */
-        AppError: new (message: string, statusCode?: number, details?: unknown) => Error & {
-            details?: unknown;
-        };
-        /** 404 Not Found error */
-        NotFoundError: new (message?: string) => Error;
-        /** 401 Unauthorized error */
-        UnauthorizedError: new (message?: string) => Error;
-        /** 403 Forbidden error */
-        ForbiddenError: new (message?: string) => Error;
-        /** 409 Conflict error */
-        ConflictError: new (message?: string) => Error;
-        /** 400 Validation error with field details */
-        ValidationError: new (message?: string, details?: ValidationDetail[]) => Error & {
-            details: ValidationDetail[];
-        };
-    };
-    /** CASL abilities API for authorization */
-    abilities: ModuleAbilities;
-    /** Event emitter for inter-module communication */
-    events: EventEmitterLike;
-    /** Registers a service in the internal registry */
-    registerService(name: string, service: unknown): void;
-    /** Gets a service from the registry with type safety (throws if not found) */
-    getService<T = unknown>(serviceName: string): T;
-    /** Gets an optional service from the registry (returns undefined if not found) */
-    getOptionalService<T = unknown>(serviceName: string): T | undefined;
-    /** Checks if a service is available without throwing */
-    hasService(serviceName: string): boolean;
-    /** Creates entity service based on definition type (auto-detects) */
-    createEntityService<T = unknown>(definition: EntityDefinition, options?: CreateEntityServiceOptions<T>): BaseEntityService<T>;
-    /** Creates entity controller with CASL authorization and validation */
-    createEntityController(service: BaseEntityService, definition: EntityDefinition): EntityController;
-    /** Creates Express router with standard CRUD routes */
-    createEntityRouter(controller: EntityController, definition: EntityDefinition): Router;
-}
-/**
- * Module manifest defining a Nexus module.
- *
- * Modules are the core building blocks of Nexus applications.
- * Each module can define entities, routes, migrations, and services.
- *
- * @example
- * ```typescript
- * const postsModule: ModuleManifest = {
- *   name: 'posts',
- *   label: { en: 'Posts', es: 'Publicaciones' },
- *   icon: 'mdi:post',
- *   category: 'content',
- *   definitions: [postsEntity, categoriesEntity],
- *   routes: (ctx) => {
- *     const router = ctx.createRouter()
- *     // Custom routes here
- *     return router
- *   }
- * }
- * ```
- */
-interface ModuleManifest {
-    /** Unique module identifier (e.g., 'users', 'posts', 'cms') */
-    name: string;
-    /** Display name for UI (singular). Optional if module belongs to a plugin */
-    label?: LocalizedString;
-    /** Display name for UI (plural, used in menus and lists) */
-    labelPlural?: LocalizedString;
-    /** Iconify MDI icon identifier (e.g., 'mdi:account-group') */
-    icon?: string;
-    /** Module description for documentation */
-    description?: LocalizedString;
-    /** Module type: 'core' (built-in), 'plugin' (from plugin), 'auth-plugin', or 'custom' */
-    type?: 'core' | 'plugin' | 'auth-plugin' | 'custom';
-    /** Category for sidebar grouping */
-    category: Category;
-    /** Other module names that must be loaded before this one */
-    dependencies?: string[];
-    /** Requirements that must be met to enable this module */
-    required?: ModuleRequirements;
-    /** Database migration function. Usually auto-generated from entity definitions */
-    migrate?: (ctx: ModuleContext) => Promise<void>;
-    /** Seed function for initial/reference data */
-    seed?: (ctx: ModuleContext) => Promise<void>;
-    /** Initialization function called on app startup */
-    init?: (ctx: ModuleContext) => void;
-    /** Factory function returning Express router with custom routes */
-    routes?: (ctx: ModuleContext) => Router;
-    /** API route prefix. Default: `/{name}` */
-    routePrefix?: string;
-    /** Entity definitions - single source of truth for DB, validation, UI, and CASL */
-    definitions?: EntityDefinition[];
-}
-/**
- * Available categories for organizing modules in the UI sidebar.
- *
- * @see {@link CATEGORIES} for metadata (labels, icons, order)
- */
-type Category = 'content' | 'data' | 'assets' | 'messaging' | 'jobs' | 'ai' | 'analytics' | 'integrations' | 'commerce' | 'security' | 'legal' | 'settings';
-/**
- * Metadata for a category including display information.
- */
-interface CategoryMeta {
-    /** Localized display label */
-    label: LocalizedString;
-    /** Iconify MDI icon identifier */
-    icon: string;
-    /** Sort order in sidebar (lower = first) */
-    order: number;
-}
-/**
- * Registry of all categories with their metadata.
- *
- * Used by the UI to render the sidebar navigation.
- */
-declare const CATEGORIES: Record<Category, CategoryMeta>;
-/**
- * Categories sorted by their display order for sidebar rendering.
+ * API DTOs (serializable versions for frontend consumption)
  */
-declare const CATEGORY_ORDER: Category[];
-/**
- * Plugin manifest defining a distributable Nexus plugin package.
- *
- * Plugins bundle one or more modules into a reusable package.
- * Distributed via npm (e.g., @gzl10/nexus-plugin-cms).
- *
- * @example
- * ```typescript
- * const cmsPlugin: PluginManifest = {
- *   name: '@gzl10/nexus-plugin-cms',
- *   code: 'CMS',
- *   label: { en: 'CMS', es: 'CMS' },
- *   category: 'content',
- *   version: '1.0.0',
- *   description: { en: 'Content Management System', es: 'Sistema de Gestión de Contenidos' },
- *   modules: [postsModule, categoriesModule, tagsModule]
- * }
- * ```
- */
-interface PluginManifest {
-    /** Plugin npm package name (e.g., '@gzl10/nexus-plugin-cms') */
-    name: string;
-    /** Short code prefix for tables (3-4 uppercase chars, e.g., 'CMS'). Applied to all modules */
-    code: string;
-    /** Display label (singular). Inherited by modules without explicit label */
-    label: LocalizedString;
-    /** Display label (plural, for menus) */
-    labelPlural?: LocalizedString;
-    /** Iconify MDI icon. Inherited by modules without explicit icon */
-    icon?: string;
-    /** Category for sidebar grouping. Inherited by modules without explicit category */
-    category: Category;
-    /** Plugin version following SemVer (e.g., '1.0.0') */
-    version: string;
-    /** Plugin description for documentation */
-    description: LocalizedString;
-    /** Modules bundled in this plugin */
-    modules: ModuleManifest[];
-}
+
 /**
  * Serializable field definition for API responses.
- *
- * Unlike {@link FieldDefinition}, this contains no functions (ConditionalBoolean
- * resolved to static boolean). Some fields may be omitted for security.
- *
- * @see {@link FieldDefinition} for the full server-side definition
  */
 interface FieldDefinitionDTO {
-    /** Field identifier */
     name: string;
-    /** Display label */
     label: LocalizedString;
-    /** Input type for form rendering */
     input: InputType;
-    /** Placeholder text */
     placeholder?: LocalizedString;
-    /** Help text */
     hint?: LocalizedString;
-    /** Whether field is hidden (resolved from ConditionalBoolean) */
-    hidden?: boolean;
-    /** Whether field is disabled (resolved from ConditionalBoolean) */
-    disabled?: boolean;
-    /** Whether field is required (resolved from ConditionalBoolean) */
-    required?: boolean;
-    /** Default value for form creation */
+    hidden?: boolean | FieldCondition;
+    disabled?: boolean | FieldCondition;
+    required?: boolean | FieldCondition;
     defaultValue?: unknown;
-    /** Database config (may be partially omitted for security) */
     db?: {
         type: string;
         nullable?: boolean;
@@ -2259,14 +31,12 @@ interface FieldDefinitionDTO {
         unique?: boolean;
         index?: boolean;
     };
-    /** Relationship config (table name may be omitted for security) */
     relation?: {
         table?: string;
         column?: string;
         labelField?: string;
         onDelete?: string;
     };
-    /** Validation rules */
     validation?: {
         min?: number;
         max?: number;
@@ -2274,7 +44,6 @@ interface FieldDefinitionDTO {
         format?: string;
         enum?: string[];
     };
-    /** Select/dropdown options configuration */
     options?: {
         endpoint?: string;
         valueField?: string;
@@ -2282,10 +51,10 @@ interface FieldDefinitionDTO {
         static?: Array<{
             value: string;
             label: LocalizedString;
+            icon?: string;
         }>;
         allowCreate?: boolean;
     };
-    /** Storage configuration for file uploads */
     storage?: {
         accept?: string;
         maxSize?: number;
@@ -2296,145 +65,461 @@ interface FieldDefinitionDTO {
             height: number;
         }>;
         dedupe?: boolean;
+        isPublic?: boolean;
     };
-    /** Field metadata */
     meta?: FieldMeta;
-    /** Props for input components */
     inputProps?: Record<string, unknown>;
-    /** Props for display components */
     displayProps?: Record<string, unknown>;
 }
+/**
+ * Serializable action definition for API responses.
+ */
+interface ActionDefinitionDTO {
+    key: string;
+    label: LocalizedString;
+    icon?: string;
+    scope?: 'module' | 'entity' | 'row';
+    method?: 'GET' | 'POST' | 'DELETE' | 'PUT' | 'PATCH';
+    fields?: Record<string, FieldDefinitionDTO>;
+    order?: number;
+    /** Whether this is a batch action with SSE progress */
+    batch?: boolean;
+    /** Timeout in ms for batch actions */
+    batchTimeout?: number;
+    /** Whether to show action result in a modal */
+    showResult?: boolean;
+}
 /**
  * Serializable entity definition for API responses.
- *
- * Flattened structure without discriminated union.
- * Sensitive information may be omitted for security.
- *
- * @see {@link EntityDefinition} for the full server-side definition
  */
 interface EntityDefinitionDTO {
-    /** Unique entity identifier (auto-generated at registration) */
     id: string;
-    /** Table name (may be omitted for security) */
     table?: string;
-    /** Key for single entities */
     key?: string;
-    /** Entity type */
     type: EntityType;
-    /** Display label (singular) */
     label: LocalizedString;
-    /** Display label (plural) */
     labelPlural?: LocalizedString;
-    /** Field used as display label */
     labelField?: string;
-    /** Iconify icon */
     icon?: string;
-    /** API route prefix */
     routePrefix?: string;
-    /** UI sort order */
     order?: number;
-    /** Field definitions */
     fields: Record<string, FieldDefinitionDTO>;
-    /** Total field count */
     fieldsCount: number;
-    /** Has created_at/updated_at columns */
     hasTimestamps: boolean;
-    /** Has created_by/updated_by columns */
     hasAudit: boolean;
-    /** CASL subject name */
     caslSubject?: string;
-    /** Returns single record instead of array */
     isSingle?: boolean;
-    /** UI display mode */
     displayMode?: DisplayMode;
-    /** Show create button in UI */
+    defaultDisplayMode?: DisplayMode;
+    availableDisplayModes?: DisplayMode[];
+    hasSearchableFields?: boolean;
+    hasSortableFields?: boolean;
+    sortableFieldOptions?: Array<{
+        value: string;
+        label: string;
+    }>;
+    defaultSort?: {
+        field: string;
+        order: 'asc' | 'desc';
+    };
     allowCreate?: boolean;
-    /** Allow editing in UI */
     allowEdit?: boolean;
-    /** Hidden from UI sidebar */
+    allowDelete?: boolean;
     hidden?: boolean;
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** Whether this standalone action entity is a batch action with SSE progress */
+    batch?: boolean;
+    /** Timeout in ms for batch standalone action entities */
+    batchTimeout?: number;
+    actions?: ActionDefinitionDTO[];
 }
 /**
  * Serializable module for API responses.
  */
 interface ModuleDTO {
-    /** Module identifier */
     name: string;
-    /** Display label */
     label: LocalizedString;
-    /** Display label (plural) */
     labelPlural?: LocalizedString;
-    /** Iconify icon */
     icon?: string;
-    /** Module description */
     description?: LocalizedString;
-    /** Module type */
     type: string;
-    /** Sidebar category */
     category?: Category;
-    /** Module dependencies */
     dependencies: string[];
-    /** API route prefix */
     routePrefix: string;
-    /** CASL subjects defined by this module */
     subjects: string[];
-    /** Entity definitions */
     definitions: EntityDefinitionDTO[];
-    /** Has custom routes */
     hasRoutes: boolean;
-    /** Has migrations */
     hasMigrate: boolean;
-    /** Has seed data */
     hasSeed: boolean;
-    /** Has init function */
     hasInit: boolean;
 }
+/**
+ * Setup information DTO (without postInstall function).
+ */
+interface PluginSetupInfoDTO {
+    steps?: LocalizedString[];
+    docsUrl?: string;
+    prerequisites?: LocalizedString[];
+    caveats?: LocalizedString[];
+}
 /**
  * Serializable plugin for API responses.
  */
 interface PluginDTO {
-    /** Plugin package name */
     name: string;
-    /** Plugin code prefix */
     code: string;
-    /** Display label */
     label: LocalizedString;
-    /** Display label (plural) */
     labelPlural?: LocalizedString;
-    /** Iconify icon */
     icon?: string;
-    /** Sidebar category */
     category?: Category;
-    /** Plugin version */
     version: string;
-    /** Plugin description */
     description: LocalizedString;
-    /** Modules in this plugin */
     modules: ModuleDTO[];
+    envVars?: Array<{
+        name: string;
+        description: LocalizedString;
+        required: boolean;
+        default?: string;
+        example?: string;
+        pattern?: string;
+        sensitive?: boolean;
+    }>;
+    peerDependencies?: Record<string, string>;
+    setup?: PluginSetupInfoDTO;
+}
+/**
+ * Plugin state persisted in database
+ */
+interface PluginStateDTO {
+    name: string;
+    enabled: boolean;
+    installed_at: string;
+    enabled_at: string | null;
+    disabled_at: string | null;
+    installed_version: string;
+    installed_by: string | null;
+    config: Record<string, unknown>;
+}
+/**
+ * Plugin available in npm registry (for store)
+ */
+interface PluginStoreItemDTO {
+    name: string;
+    version: string;
+    description: string;
+    keywords: string[];
+    repository: string | null;
+    compatibility: 'compatible' | 'incompatible' | 'unknown';
+    installed: boolean;
+    installedVersion: string | null;
+    enabled: boolean | null;
+}
+/**
+ * Result of install/uninstall action
+ */
+interface PluginActionResult {
+    success: boolean;
+    message: string;
+    restarting?: boolean;
 }
 /**
  * Application manifest DTO (core or user app).
  */
 interface ManifestDTO {
-    /** Application name */
     name: string;
-    /** Application version */
     version: string;
-    /** Registered modules */
     modules: ModuleDTO[];
-    /** Registered plugins */
     plugins?: PluginDTO[];
 }
 /**
  * Combined manifest DTO with both core and user manifests.
  */
 interface CombinedManifestDTO {
-    /** Core nexus-backend manifest */
     core: ManifestDTO;
-    /** User project manifest (null in standalone mode) */
     user: ManifestDTO | null;
-    /** Whether running with a user project */
     hasUserApp: boolean;
 }
 
-export { type AbilityLike, type ActionEntityDefinition, type ActionEntityService, type AppManifest, type AuthRequest, type BaseAuthRequest, type BaseEntityService, type BaseMailService, type BaseRolesService, type BaseUser, type BaseUsersService, CATEGORIES, CATEGORY_ORDER, type CaslAction, type Category, type CategoryMeta, type CollectionEntityDefinition, type CollectionEntityService, type CombinedManifestDTO, type ComputedEntityDefinition, type ComputedEntityService, type ConditionalBoolean, type ConfigEntityDefinition, type ConfigEntityService, type ContextCrypto, type ContextEngine, type ContextHelpers, type ContextSocket, type CoreServices, type CreateEntityServiceOptions, type DbType, type DisplayMode, type EntityAction, type EntityCaslConfig, type EntityController, type EntityDefinition, type EntityDefinitionDTO, type EntityHandler, type EntityIndex, type EntityQuery, type EntityServiceHooks, type EntityType, type EventEmitterLike, type EventEntityDefinition, type EventEntityService, type ExternalEntityDefinition, type ExternalEntityService, type FieldDbConfig, type FieldDefinition, type FieldDefinitionDTO, type FieldMeta, type FieldOptions, type FieldRelation, type FieldStorageConfig, type FieldValidationConfig, type FilterOperators, type FilterValue, type ForbiddenErrorConstructor, type ForbiddenErrorInstance, type InputType, type KnexAlterTableBuilder, type KnexCreateTableBuilder, type KnexTransaction, type LocalizedString, type LoggerReporter, type ManifestDTO, type ModuleAbilities, type ModuleContext, type ModuleDTO, type ModuleManifest, type ModuleMiddlewares, type ModuleRequirements, type NonPersistentEntityDefinition, type OwnershipCondition, type PaginatedResult, type PaginationParams, type PersistentEntityDefinition, type PluginDTO, type PluginManifest, type RateLimitOptions, type ReferenceEntityDefinition, type ReferenceEntityService, type RolePermission, type SendMailOptions, type SendMailResult, type SingleEntityDefinition, type SingleEntityService, type SocketIOBroadcastOperator, type SocketIOServer, type TempEntityDefinition, type TempEntityService, type ValidateSchemas, type ValidationDetail, type ValidationSchema, type ViewEntityDefinition, type ViewEntityService, type VirtualEntityDefinition, type VirtualEntityService, getCountLabel, getEntityName, getEntitySubject, hasTable, isPersistentEntity, isSingletonEntity, resolveLocalized };
+/**
+ * Type guards and utilities for EntityDefinitions
+ */
+
+/**
+ * Entities that persist in the local DB with their own table.
+ * Excludes: action, external, virtual, computed, single (uses shared table).
+ */
+type PersistentEntityDefinition = CollectionEntityDefinition | ReferenceEntityDefinition | EventEntityDefinition | ConfigEntityDefinition | TempEntityDefinition | ViewEntityDefinition | TreeEntityDefinition | DagEntityDefinition;
+/**
+ * Entities without local persistence (read-only or without DB)
+ */
+type NonPersistentEntityDefinition = (ActionDefinition & {
+    type: 'action';
+}) | ExternalEntityDefinition | VirtualEntityDefinition | ComputedEntityDefinition;
+/**
+ * Type guard to check whether an entity persists in the local DB with its own table
+ */
+declare function isPersistentEntity(entity: EntityDefinition): entity is PersistentEntityDefinition;
+/**
+ * Type guard to check whether it is a singleton (uses shared sys_settings table)
+ */
+declare function isSingletonEntity(entity: EntityDefinition): entity is SingleEntityDefinition;
+/**
+ * Type guard to check whether an entity has its own table (for migrations)
+ */
+declare function hasTable(entity: EntityDefinition): entity is PersistentEntityDefinition;
+/**
+ * Gets an entity name in singular PascalCase.
+ * 'cms_posts' → 'Post', 'rol_role_permissions' → 'RolePermission'
+ */
+declare function getEntityName(entity: EntityDefinition): string;
+/**
+ * Gets the CASL subject for an entity
+ */
+declare function getEntitySubject(entity: PersistentEntityDefinition): string;
+
+/**
+ * OIDC Types for Authentication Plugins
+ *
+ * Shared types for OpenID Connect authentication providers.
+ * Used by plugins like @gzl10/nexus-plugin-pocketid and @gzl10/nexus-plugin-google-auth.
+ */
+/**
+ * OIDC Discovery Document
+ * @see https://openid.net/specs/openid-connect-discovery-1_0.html
+ */
+interface OidcDiscoveryDocument {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    userinfo_endpoint: string;
+    jwks_uri: string;
+    end_session_endpoint?: string;
+    scopes_supported?: string[];
+    response_types_supported?: string[];
+    grant_types_supported?: string[];
+    subject_types_supported?: string[];
+    id_token_signing_alg_values_supported?: string[];
+}
+/**
+ * OIDC Tokens from token endpoint
+ */
+interface OidcTokens {
+    access_token: string;
+    token_type: string;
+    expires_in?: number;
+    refresh_token?: string;
+    id_token?: string;
+    scope?: string;
+}
+/**
+ * ID Token claims after validation
+ */
+interface IdTokenClaims {
+    iss: string;
+    sub: string;
+    aud: string | string[];
+    exp: number;
+    iat: number;
+    nonce?: string;
+    auth_time?: number;
+    azp?: string;
+    at_hash?: string;
+    email?: string;
+    email_verified?: boolean;
+    name?: string;
+    /** Google Workspace hosted domain */
+    hd?: string;
+}
+/**
+ * OIDC UserInfo response
+ */
+interface OidcUserInfo {
+    sub: string;
+    name?: string;
+    given_name?: string;
+    family_name?: string;
+    preferred_username?: string;
+    email?: string;
+    email_verified?: boolean;
+    picture?: string;
+    locale?: string;
+    updated_at?: number;
+}
+/**
+ * Authorization URL parameters
+ */
+interface AuthorizationParams {
+    clientId: string;
+    redirectUri: string;
+    scopes: string[];
+    state: string;
+    nonce: string;
+    responseType?: string;
+    /** Google Workspace hosted domain (hd parameter) */
+    hostedDomain?: string;
+}
+/**
+ * Token exchange parameters
+ */
+interface TokenExchangeParams {
+    tokenEndpoint: string;
+    clientId: string;
+    clientSecret: string;
+    code: string;
+    redirectUri: string;
+}
+/**
+ * ID Token validation config
+ */
+interface TokenValidationConfig {
+    jwksUri: string;
+    issuer: string;
+    clientId: string;
+    nonce?: string;
+}
+/**
+ * OIDC state stored temporarily during auth flow
+ */
+interface OidcState {
+    state: string;
+    nonce: string;
+    redirectUri: string;
+    createdAt: number;
+    /** User ID if linking existing account */
+    linkUserId?: string;
+}
+/**
+ * Session result after successful authentication
+ */
+interface SessionResult {
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: number;
+    user: {
+        id: string;
+        email: string;
+        name?: string;
+    };
+}
+
+/**
+ * OIDC Client interface
+ */
+interface OidcClient {
+    /** Discover OIDC endpoints from issuer */
+    discover(issuerUrl: string): Promise<OidcDiscoveryDocument>;
+    /** Build authorization URL for redirect */
+    buildAuthorizationUrl(authorizationEndpoint: string, params: AuthorizationParams): string;
+    /** Exchange authorization code for tokens */
+    exchangeCode(params: TokenExchangeParams): Promise<OidcTokens>;
+    /** Get user info from access token */
+    getUserInfo(accessToken: string, userInfoEndpoint: string): Promise<OidcUserInfo>;
+    /** Validate ID token using JWKS */
+    validateIdToken(idToken: string, config: TokenValidationConfig): Promise<IdTokenClaims>;
+}
+/**
+ * Create OIDC client instance
+ */
+declare function createOidcClient(): OidcClient;
+/**
+ * Get shared OIDC client instance (singleton)
+ */
+declare function getOidcClient(): OidcClient;
+
+/**
+ * OIDC State Manager
+ *
+ * Manages OIDC state/nonce storage with TTL expiration.
+ * Used for CSRF protection during authentication flows.
+ *
+ * Note: In-memory implementation. For production with multiple
+ * instances, consider Redis or database storage.
+ */
+
+/**
+ * State manager interface
+ */
+interface StateManager<T extends OidcState = OidcState> {
+    /** Store state data */
+    store(state: string, data: T): void;
+    /** Verify and retrieve state (returns null if expired/invalid) */
+    verify(state: string): T | null;
+    /** Clear state after use */
+    clear(state: string): void;
+    /** Get TTL in milliseconds */
+    getTtl(): number;
+}
+/**
+ * Create in-memory state manager
+ *
+ * @param ttlMs - Time-to-live in milliseconds (default: 10 minutes)
+ */
+declare function createStateManager<T extends OidcState = OidcState>(ttlMs?: number): StateManager<T>;
+
+/**
+ * Domain Filter for OIDC Authentication
+ *
+ * Validates email domains against an allowlist.
+ * Used to restrict authentication to specific domains.
+ */
+/**
+ * Domain filter options
+ */
+interface DomainFilterOptions {
+    /** Throw error if domain not allowed (default: true) */
+    throwOnForbidden?: boolean;
+}
+/**
+ * Domain filter result
+ */
+interface DomainFilterResult {
+    allowed: boolean;
+    domain: string;
+}
+/**
+ * Check if email domain is in allowed list
+ *
+ * @param email - User email address
+ * @param allowedDomainsJson - JSON array of allowed domains (null = all allowed)
+ * @returns Domain filter result
+ *
+ * @example
+ * // Allow specific domains
+ * const result = checkAllowedDomain('user@example.com', '["example.com", "test.com"]')
+ * // result: { allowed: true, domain: 'example.com' }
+ *
+ * @example
+ * // Allow all domains
+ * const result = checkAllowedDomain('user@any.com', null)
+ * // result: { allowed: true, domain: 'any.com' }
+ */
+declare function checkAllowedDomain(email: string, allowedDomainsJson: string | null): DomainFilterResult;
+/**
+ * Assert email domain is allowed (throws if not)
+ *
+ * @param email - User email address
+ * @param allowedDomainsJson - JSON array of allowed domains
+ * @param errorClass - Error class to throw (default: Error)
+ * @throws Error if domain is not allowed
+ */
+declare function assertAllowedDomain(email: string, allowedDomainsJson: string | null, errorClass?: new (message: string) => Error): void;
+
+/**
+ * @module nexus-sdk
+ * @description SDK types for creating Nexus plugins and modules without full backend dependency
+ *
+ * @gzl10/nexus-sdk
+ *
+ * Use this package to define plugin/module manifests without
+ * depending on the full @gzl10/nexus-backend package.
+ *
+ * @remarks
+ * Types are organized in submodules under ./types/ for maintainability.
+ * This barrel file re-exports everything for backwards compatibility.
+ */
+
+type KnexCreateTableBuilder = Knex.CreateTableBuilder;
+type KnexAlterTableBuilder = Knex.AlterTableBuilder;
+type KnexTransaction = Knex.Transaction;
+
+export { ActionDefinition, type ActionDefinitionDTO, type AuthorizationParams, Category, CollectionEntityDefinition, type CombinedManifestDTO, ComputedEntityDefinition, ConfigEntityDefinition, DagEntityDefinition, DisplayMode, type DomainFilterOptions, type DomainFilterResult, EntityDefinition, type EntityDefinitionDTO, EntityType, EventEntityDefinition, ExternalEntityDefinition, FieldCondition, type FieldDefinitionDTO, FieldMeta, type IdTokenClaims, InputType, type KnexAlterTableBuilder, type KnexCreateTableBuilder, type KnexTransaction, LocalizedString, type ManifestDTO, type ModuleDTO, type NonPersistentEntityDefinition, type OidcClient, type OidcDiscoveryDocument, type OidcState, type OidcTokens, type OidcUserInfo, type PersistentEntityDefinition, type PluginActionResult, type PluginDTO, type PluginSetupInfoDTO, type PluginStateDTO, type PluginStoreItemDTO, ReferenceEntityDefinition, type SessionResult, SingleEntityDefinition, type StateManager, TempEntityDefinition, type TokenExchangeParams, type TokenValidationConfig, TreeEntityDefinition, ViewEntityDefinition, VirtualEntityDefinition, assertAllowedDomain, checkAllowedDomain, createOidcClient, createStateManager, getEntityName, getEntitySubject, getOidcClient, hasTable, isPersistentEntity, isSingletonEntity };