nextly 0.0.1 → 0.0.2-alpha.1

package/dist/_dts-chunks/config.d-DNwsDnjs.d.ts

@@ -0,0 +1,2589 @@
+import { bc as BaseService, bd as Logger, be as BaseRegistryService, bf as DynamicCollectionRecord, bg as MigrationStatus, bh as PermissionSeedService, bi as BaseListOptions, bj as CollectionSource, bk as BaseListResult, bl as DynamicCollectionInsert, bm as FieldDefinition, bn as CollectionMetadataService, bo as CollectionEntryService, bp as RequestContext, bq as PaginatedResult, br as QueryOptions, P as FieldConfig, bs as HookRegistry, o as CollectionConfig, aQ as SingleConfig, t as ComponentConfig, bt as UserConfig, bu as EmailConfig, bv as UserService, bw as MediaService, bx as SingleRegistryService, by as SingleEntryService, bz as ComponentRegistryService, bA as ComponentDataService, bB as CollectionRelationshipService, bC as UserExtSchemaService, bD as EmailProviderService, bE as EmailTemplateService, bF as EmailService, bG as UserFieldDefinitionService, bH as RBACAccessControlService, bI as ApiKeyService, bJ as AuthService, bK as DatabaseInstance, bL as HookType, $ as HookHandler } from './collections-handler.d-DjgO74Wt.d.ts';
+import { DrizzleAdapter } from '@nextlyhq/adapter-drizzle';
+import { z } from 'zod';
+import { S as StoragePlugin, g as ImageProcessor } from './image-processor.d-OO1PmMrv.d.ts';
+import { TransactionContext } from '@nextlyhq/adapter-drizzle/types';
+import { M as MediaStorage } from './storage.d-BUhQ2we_.d.ts';
+
+/**
+ * CORS Middleware
+ *
+ * Origin-based Cross-Origin Resource Sharing enforcement for all API responses.
+ * Handles preflight (OPTIONS) requests and applies CORS headers to normal responses.
+ *
+ * Three origin modes:
+ * - `origin: []` (default) — same-origin only, no CORS headers set
+ * - `origin: ['*']` — wide-open access (development only), logs warning in production
+ * - `origin: ['https://example.com', ...]` — allowlist with dynamic origin reflection
+ *
+ * @module middleware/cors
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const cors = createCorsMiddleware({
+ *   origin: ['https://example.com', 'https://app.example.com'],
+ *   credentials: true,
+ * });
+ *
+ * // In request pipeline:
+ * const preflightResponse = cors.handlePreflight(request);
+ * if (preflightResponse) return preflightResponse;
+ *
+ * const response = await handler(request);
+ * return cors.applyHeaders(request, response);
+ * ```
+ */
+/**
+ * Configuration for CORS middleware.
+ *
+ * All fields are optional with secure defaults (same-origin only).
+ */
+interface CorsConfig {
+    /**
+     * Allowed origins.
+     * - `[]` (default): same-origin only — no CORS headers are set.
+     * - `['*']`: wide-open access. Logs a warning in production.
+     * - `['https://example.com', ...]`: allowlist with dynamic origin reflection.
+     *
+     * @default []
+     */
+    origin?: string[];
+    /**
+     * Allowed HTTP methods for preflight responses.
+     *
+     * @default ["GET", "POST", "PATCH", "DELETE", "OPTIONS"]
+     */
+    methods?: string[];
+    /**
+     * Headers the client is allowed to send.
+     *
+     * @default ["Content-Type", "Authorization"]
+     */
+    allowedHeaders?: string[];
+    /**
+     * Response headers exposed to client-side JavaScript.
+     *
+     * @default ["X-RateLimit-Limit", "X-RateLimit-Remaining", "X-RateLimit-Reset"]
+     */
+    exposedHeaders?: string[];
+    /**
+     * Whether to include credentials (cookies, Authorization header).
+     * Ignored when origin is `['*']` (CORS spec prohibits credentials with wildcard).
+     *
+     * @default true
+     */
+    credentials?: boolean;
+    /**
+     * Preflight cache duration in seconds.
+     *
+     * @default 86400 (24 hours)
+     */
+    maxAge?: number;
+}
+
+/**
+ * Rate Limiting Middleware
+ *
+ * Provides configurable rate limiting for API endpoints to protect
+ * against abuse and ensure fair resource usage.
+ *
+ * Features:
+ * - Pluggable store interface (in-memory default, Redis-compatible)
+ * - Separate read/write limits
+ * - Per-collection overrides
+ * - Skip function for admin users
+ * - Standard rate limit headers
+ *
+ * @module middleware/rate-limit
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * // Enable rate limiting in nextly.config.ts
+ * export default defineConfig({
+ *   rateLimit: {
+ *     enabled: true,
+ *     readLimit: 100,   // 100 GET requests per minute
+ *     writeLimit: 30,   // 30 POST/PATCH/DELETE per minute
+ *   },
+ * });
+ * ```
+ */
+/**
+ * Result from a rate limit check.
+ */
+interface RateLimitResult {
+    /** Whether the request is allowed */
+    allowed: boolean;
+    /** Maximum requests allowed in the window */
+    limit: number;
+    /** Remaining requests in current window */
+    remaining: number;
+    /** Unix timestamp (ms) when the window resets */
+    resetTime: number;
+}
+/**
+ * Pluggable store interface for rate limit state.
+ *
+ * Implement this interface to use Redis, Memcached, or other
+ * distributed stores for rate limiting in production.
+ *
+ * @example
+ * ```typescript
+ * import Redis from 'ioredis';
+ *
+ * class RedisRateLimitStore implements RateLimitStore {
+ *   private redis: Redis;
+ *
+ *   constructor(redis: Redis) {
+ *     this.redis = redis;
+ *   }
+ *
+ *   async increment(key: string, windowMs: number): Promise<RateLimitRecord> {
+ *     const now = Date.now();
+ *     const resetTime = now + windowMs;
+ *     const count = await this.redis.incr(key);
+ *     if (count === 1) {
+ *       await this.redis.pexpire(key, windowMs);
+ *     }
+ *     return { count, resetTime };
+ *   }
+ *
+ *   async reset(key: string): Promise<void> {
+ *     await this.redis.del(key);
+ *   }
+ * }
+ * ```
+ */
+interface RateLimitStore {
+    /**
+     * Increment the request count for a key.
+     *
+     * @param key - Unique identifier (e.g., IP address or user ID)
+     * @param windowMs - Time window in milliseconds
+     * @returns Record with current count and reset time
+     */
+    increment(key: string, windowMs: number): Promise<RateLimitRecord>;
+    /**
+     * Reset the request count for a key.
+     *
+     * @param key - Unique identifier to reset
+     */
+    reset(key: string): Promise<void>;
+}
+/**
+ * Record returned by store increment operation.
+ */
+interface RateLimitRecord {
+    /** Current request count in the window */
+    count: number;
+    /** Unix timestamp (ms) when the window resets */
+    resetTime: number;
+}
+/**
+ * Configuration for rate limiting.
+ */
+interface RateLimitConfig {
+    /**
+     * Enable rate limiting.
+     * @default true
+     */
+    enabled: boolean;
+    /**
+     * Maximum requests per window for read operations (GET).
+     * @default 100
+     */
+    readLimit?: number;
+    /**
+     * Maximum requests per window for write operations (POST, PATCH, PUT, DELETE).
+     * @default 30
+     */
+    writeLimit?: number;
+    /**
+     * Time window in milliseconds.
+     * @default 60000 (1 minute)
+     */
+    windowMs?: number;
+    /**
+     * Custom store for rate limit state.
+     * Defaults to in-memory store if not provided.
+     *
+     * @example
+     * ```typescript
+     * import { RedisRateLimitStore } from '@nextly/ratelimit-redis';
+     *
+     * rateLimit: {
+     *   enabled: true,
+     *   store: new RedisRateLimitStore(redisClient),
+     * }
+     * ```
+     */
+    store?: RateLimitStore;
+    /**
+     * Function to generate a unique key for rate limiting.
+     * Defaults to the trusted client IP address (see `trustProxy` /
+     * `trustedProxyIps`). Requests with no resolvable IP fall back to a
+     * shared `unknown` bucket so anonymous traffic is still rate-limited.
+     *
+     * @param request - The incoming request
+     * @returns A unique identifier string
+     */
+    keyGenerator?: (request: Request) => string;
+    /**
+     * When true, the default keyGenerator parses
+     * `X-Forwarded-For` (filtered through `trustedProxyIps`). When false
+     * (default), proxy headers are ignored — direct-internet deployments
+     * fall back to a single `unknown` bucket. Wired from
+     * `nextly.config.ts → security.trustProxy`.
+     *
+     * @default false
+     */
+    trustProxy?: boolean;
+    /**
+     * CIDR list of proxy IPs (from TRUSTED_PROXY_IPS).
+     * Used by the default keyGenerator to walk the X-Forwarded-For chain
+     * rightmost-first, returning the first non-proxy hop.
+     */
+    trustedProxyIps?: readonly string[];
+    /**
+     * Function to skip rate limiting for certain requests.
+     * Returns true to skip rate limiting.
+     *
+     * **Default**: skips the admin internal API (`/admin/api/*`). The
+     * rate limiter is meant to protect the public REST surface from
+     * anonymous abuse; admin routes are session-authed and already gated
+     * by `requireAdminAuth`/`requireCollectionAccess`, so applying the
+     * same per-IP cap to admin causes false positives during normal
+     * navigation (each admin page fires several parallel queries —
+     * `/me`, `/dashboard/stats`, `/schema/journal`, per-collection
+     * queries — and a handful of nav events trips the public default).
+     *
+     * Pass an explicit `skip` to override. If you want to rate-limit
+     * admin too (e.g. for insider-abuse defense), wrap the default:
+     *
+     * @param request - The incoming request
+     * @returns True to skip rate limiting
+     *
+     * @example
+     * ```typescript
+     * // Override: rate-limit everything, including admin
+     * skip: () => false
+     *
+     * // Override: skip admin AND internal service calls
+     * skip: (req) => {
+     *   const url = new URL(req.url);
+     *   if (url.pathname.startsWith("/admin/api/")) return true;
+     *   return req.headers.get("x-internal-key") === process.env.INTERNAL_KEY;
+     * }
+     * ```
+     */
+    skip?: (request: Request) => boolean | Promise<boolean>;
+    /**
+     * Per-collection rate limit overrides.
+     *
+     * @example
+     * ```typescript
+     * collections: {
+     *   'media': { readLimit: 50, writeLimit: 10 },  // Stricter for media
+     *   'logs': { readLimit: 200 },                   // More lenient for logs
+     * }
+     * ```
+     */
+    collections?: Record<string, {
+        readLimit?: number;
+        writeLimit?: number;
+    }>;
+    /**
+     * Custom handler for rate limit exceeded responses.
+     * If not provided, returns a standard 429 response.
+     *
+     * @param request - The rate-limited request
+     * @param result - The rate limit check result
+     * @returns A custom Response
+     */
+    handler?: (request: Request, result: RateLimitResult) => Response;
+}
+/**
+ * In-memory rate limit store.
+ *
+ * Suitable for development and single-instance deployments.
+ * For production with multiple instances, use a Redis-backed store.
+ *
+ * @internal
+ */
+declare class InMemoryRateLimitStore implements RateLimitStore {
+    private hits;
+    private cleanupInterval;
+    constructor();
+    increment(key: string, windowMs: number): Promise<RateLimitRecord>;
+    reset(key: string): Promise<void>;
+    /**
+     * Clean up expired records to prevent memory leaks.
+     */
+    private cleanup;
+    /**
+     * Destroy the store and stop cleanup interval.
+     * Call this when shutting down the application.
+     */
+    destroy(): void;
+    /**
+     * Get the current size of the store (for testing/monitoring).
+     */
+    get size(): number;
+}
+/**
+ * Create a rate limiter middleware function.
+ *
+ * @param config - Rate limiting configuration
+ * @returns Middleware function that checks rate limits
+ *
+ * @example
+ * ```typescript
+ * const rateLimiter = createRateLimiter({
+ *   enabled: true,
+ *   readLimit: 100,
+ *   writeLimit: 30,
+ * });
+ *
+ * // In route handler
+ * const rateLimitResponse = await rateLimiter(request);
+ * if (rateLimitResponse) {
+ *   return rateLimitResponse; // 429 Too Many Requests
+ * }
+ * // Continue with request handling
+ * ```
+ */
+declare function createRateLimiter(config: RateLimitConfig): (_request: Request) => Promise<Response | null>;
+/**
+ * Create rate limit headers for successful requests.
+ *
+ * Call this after checking rate limits to add headers to the response.
+ *
+ * @param result - The rate limit check result
+ * @returns Headers object to merge with response
+ *
+ * @example
+ * ```typescript
+ * const response = new Response(JSON.stringify(data), {
+ *   headers: {
+ *     'Content-Type': 'application/json',
+ *     ...createRateLimitHeaders(rateLimitResult),
+ *   },
+ * });
+ * ```
+ */
+declare function createRateLimitHeaders(result: RateLimitResult): Record<string, string>;
+
+/**
+ * Security Headers Middleware
+ *
+ * Response transformer that attaches security headers to every API response.
+ * Headers are pre-computed at initialization time for zero per-request overhead.
+ *
+ * All headers are individually configurable or disableable via
+ * `defineConfig({ security: { headers: { ... } } })`.
+ *
+ * @module middleware/security-headers
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * // Use with all defaults
+ * const applyHeaders = createSecurityHeadersMiddleware();
+ * const securedResponse = applyHeaders(response);
+ *
+ * // Customize specific headers
+ * const applyHeaders = createSecurityHeadersMiddleware({
+ *   contentSecurityPolicy: "default-src 'self'",
+ *   strictTransportSecurity: false, // Disable HSTS
+ * });
+ * ```
+ */
+/**
+ * Configuration for security response headers.
+ *
+ * Each header can be set to a custom string value or `false` to disable it.
+ * Omitted headers use their secure defaults.
+ *
+ * @example
+ * ```typescript
+ * const config: SecurityHeadersConfig = {
+ *   contentSecurityPolicy: "default-src 'self'",
+ *   strictTransportSecurity: false, // Disable HSTS
+ * };
+ * ```
+ */
+interface SecurityHeadersConfig {
+    /**
+     * Content-Security-Policy header value.
+     * Set to `false` to disable.
+     *
+     * The previous default `default-src 'none'; frame-ancestors 'none'`
+     * was a hard "block everything" — fine on a pure
+     * JSON response (CSP doesn't enforce on JSON) but instantly broke any
+     * HTML response, including the admin SPA. The new default is
+     * restrictive but lets a self-hosted Nextly admin UI run end-to-end:
+     *
+     *   default-src 'self';
+     *   script-src 'self';
+     *   style-src 'self' 'unsafe-inline';
+     *   img-src 'self' data: blob:;
+     *   font-src 'self' data:;
+     *   connect-src 'self';
+     *   frame-ancestors 'none';
+     *   base-uri 'self';
+     *   form-action 'self';
+     *   object-src 'none'
+     *
+     * To extend (e.g. for a CDN, analytics, or third-party fonts), pass
+     * an explicit string here — your value replaces the default entirely.
+     * To disable CSP entirely, set to `false`.
+     *
+     * @default see above
+     */
+    contentSecurityPolicy?: string | false;
+    /**
+     * X-Content-Type-Options header value.
+     * Set to `false` to disable.
+     *
+     * @default "nosniff"
+     */
+    xContentTypeOptions?: string | false;
+    /**
+     * X-Frame-Options header value.
+     * Set to `false` to disable.
+     *
+     * @default "DENY"
+     */
+    xFrameOptions?: string | false;
+    /**
+     * Strict-Transport-Security header value.
+     * Only applied when `NODE_ENV === 'production'` unless explicitly set.
+     * Set to `false` to disable entirely.
+     *
+     * @default "max-age=31536000; includeSubDomains"
+     */
+    strictTransportSecurity?: string | false;
+    /**
+     * Referrer-Policy header value.
+     * Set to `false` to disable.
+     *
+     * @default "strict-origin-when-cross-origin"
+     */
+    referrerPolicy?: string | false;
+    /**
+     * Permissions-Policy header value.
+     * Set to `false` to disable.
+     *
+     * @default "camera=(), microphone=(), geolocation=()"
+     */
+    permissionsPolicy?: string | false;
+}
+
+/**
+ * Admin Placement Constants
+ *
+ * Typed constants for valid admin sidebar placement sections.
+ * Plugin developers use these to declare where their plugin
+ * renders in the admin sidebar with full TypeScript autocomplete.
+ *
+ * @module plugins/admin-placement
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * import { definePlugin, AdminPlacement } from "nextly";
+ *
+ * export const analyticsPlugin = definePlugin({
+ *   name: "Analytics Dashboard",
+ *   admin: {
+ *     placement: AdminPlacement.USERS,
+ *     order: 60,
+ *     description: "User analytics and insights",
+ *   },
+ * });
+ * ```
+ */
+/**
+ * Valid sidebar placement sections for plugins.
+ *
+ * Use these constants when specifying `admin.placement` in a plugin definition.
+ * Each value maps to a built-in sidebar section in the admin UI.
+ *
+ * @example
+ * ```typescript
+ * // Place plugin items alongside collections
+ * admin: { placement: AdminPlacement.COLLECTIONS }
+ *
+ * // Place plugin items in the Users inner sidebar
+ * admin: { placement: AdminPlacement.USERS }
+ * ```
+ */
+declare const AdminPlacement: {
+    /** Plugin items appear in the Collections sidebar section */
+    readonly COLLECTIONS: "collections";
+    /** Plugin items appear in the Singles sidebar section */
+    readonly SINGLES: "singles";
+    /** Plugin items appear in the Users inner sidebar (alongside Users, User Fields, Roles) */
+    readonly USERS: "users";
+    /** Plugin items appear in the Settings inner sidebar (alongside General, API Keys, etc.) */
+    readonly SETTINGS: "settings";
+    /** Plugin items appear in the dedicated Plugins sidebar section (default) */
+    readonly PLUGINS: "plugins";
+    /** Plugin gets its own top-level icon in the sidebar (requires appearance.icon) */
+    readonly STANDALONE: "standalone";
+};
+/**
+ * Type representing valid admin sidebar placement values.
+ *
+ * Derived from the `AdminPlacement` constants object.
+ * Accepts: `"collections"` | `"singles"` | `"users"` | `"settings"` | `"plugins"` | `"standalone"`
+ */
+type AdminPlacement = (typeof AdminPlacement)[keyof typeof AdminPlacement];
+
+/**
+ * MetaService — small KV API over the `nextly_meta` table.
+ *
+ * Used for runtime flags that don't belong in collection schemas
+ * (e.g., `seed.completedAt`, `seed.skippedAt`). All values are JSON
+ * round-tripped: callers pass / receive JS values; the service
+ * handles serialisation. Pg/MySQL native JSON columns store the
+ * serialised string verbatim (no double-decoding on read since the
+ * service is the only writer).
+ *
+ * Cross-dialect: looks up the right Drizzle table via `this.dialect`.
+ */
+declare class MetaService extends BaseService {
+    constructor(adapter: DrizzleAdapter, logger: Logger);
+    private get table();
+    private get drizzle();
+    get<T = unknown>(key: string): Promise<T | null>;
+    set(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+    getAll(): Promise<Record<string, unknown>>;
+}
+
+/**
+ * Collection Registry Service
+ *
+ * Manages the `dynamic_collections` metadata table for both code-first
+ * and UI-created collections. Provides schema hash-based change detection
+ * for code-first collection syncing.
+ *
+ * Extends BaseRegistryService for shared CRUD, migration tracking, and utility patterns.
+ *
+ * @module services/collections/collection-registry-service
+ * @since 1.0.0
+ */
+
+/** Options for updating a collection. */
+interface UpdateCollectionOptions {
+    /** Source making the update. Used to enforce locking rules. */
+    source?: CollectionSource;
+}
+/** Input for registering a code-first collection during sync. */
+interface CodeFirstCollectionConfig {
+    slug: string;
+    labels: {
+        singular: string;
+        plural: string;
+    };
+    fields: DynamicCollectionInsert["fields"];
+    description?: string;
+    tableName?: string;
+    timestamps?: boolean;
+    /** Whether the collection has the Draft/Published status feature enabled. */
+    status?: boolean;
+    admin?: DynamicCollectionInsert["admin"];
+    configPath?: string;
+}
+/** Result of syncing code-first collections. */
+interface SyncResult {
+    created: string[];
+    updated: string[];
+    unchanged: string[];
+    errors: Array<{
+        slug: string;
+        error: string;
+    }>;
+}
+/** Options for listing collections. */
+interface ListCollectionsOptions$1 extends BaseListOptions {
+    source?: CollectionSource;
+    migrationStatus?: MigrationStatus;
+}
+/**
+ * Result of listing collections with pagination info.
+ *
+ * Declared as a `type` alias rather than an empty `interface` because the latter
+ * triggers @typescript-eslint/no-empty-object-type. We intentionally keep this
+ * named export so callers can import a domain-specific name even though it has
+ * no extra members today.
+ */
+type ListCollectionsResult = BaseListResult<DynamicCollectionRecord>;
+declare class CollectionRegistryService extends BaseRegistryService<DynamicCollectionRecord, MigrationStatus> {
+    protected readonly registryTableName = "dynamic_collections";
+    protected readonly resourceType = "Collection";
+    protected readonly tableNamePrefix = "dc_";
+    private permissionSeedService?;
+    constructor(adapter: DrizzleAdapter, logger: Logger);
+    protected getSearchColumns(): string[];
+    /** Set the PermissionSeedService for auto-seeding permissions on collection sync. */
+    setPermissionSeedService(service: PermissionSeedService): void;
+    getCollectionBySlug(slug: string): Promise<DynamicCollectionRecord | null>;
+    getCollection(slug: string): Promise<DynamicCollectionRecord>;
+    getAllCollections(options?: ListCollectionsOptions$1): Promise<DynamicCollectionRecord[]>;
+    listCollections(options?: ListCollectionsOptions$1): Promise<ListCollectionsResult>;
+    isLocked(slug: string): Promise<boolean>;
+    updateMigrationStatus(slug: string, status: MigrationStatus, migrationId?: string): Promise<void>;
+    updateMigrationStatusWithVerification(slug: string, tableName: string): Promise<{
+        verified: boolean;
+        status: MigrationStatus;
+    }>;
+    getPendingMigrations(): Promise<DynamicCollectionRecord[]>;
+    registerCollection(data: DynamicCollectionInsert): Promise<DynamicCollectionRecord>;
+    updateCollection(slug: string, data: Partial<DynamicCollectionInsert>, options?: UpdateCollectionOptions): Promise<DynamicCollectionRecord>;
+    deleteCollection(slug: string): Promise<void>;
+    syncCodeFirstCollections(configs: CodeFirstCollectionConfig[]): Promise<SyncResult>;
+    registerCollectionInTransaction(tx: TransactionContext, data: DynamicCollectionInsert): Promise<DynamicCollectionRecord>;
+    private seedPermissionsForCollection;
+    private labelsChanged;
+    protected deserializeRecord(record: DynamicCollectionRecord | Record<string, unknown>): DynamicCollectionRecord;
+}
+
+/**
+ * CollectionService - Unified service for collection operations
+ *
+ * This service provides a clean API for both collection metadata (CRUD on collections)
+ * and entry operations (CRUD on documents within collections). It follows the new
+ * service layer architecture with:
+ *
+ * - Exception-based error handling using NextlyError
+ * - RequestContext for user/locale context
+ * - PaginatedResult for list operations
+ * - Transaction-aware methods (*InTransaction) using adapter transactions
+ * - Database adapter abstraction for multi-DB support (PostgreSQL, MySQL, SQLite)
+ *
+ * Internally delegates to CollectionMetadataService and CollectionEntryService
+ * for the actual implementation, converting their return format to the new pattern.
+ *
+ * @example
+ * ```typescript
+ * import { CollectionService, NextlyError } from 'nextly';
+ *
+ * const service = new CollectionService(adapter, logger, metadataService, entryService);
+ *
+ * // Create a collection
+ * const collection = await service.createCollection({
+ *   name: 'posts',
+ *   label: 'Blog Posts',
+ *   fields: [...]
+ * }, context);
+ *
+ * // Create an entry
+ * const entry = await service.createEntry('posts', { title: 'Hello' }, context);
+ *
+ * // Error handling
+ * try {
+ *   const entry = await service.findEntryById('posts', 'nonexistent', context);
+ * } catch (error) {
+ *   if (NextlyError.is(error)) {
+ *     console.log(error.code); // 'NOT_FOUND'
+ *     console.log(error.statusCode); // 404
+ *   }
+ * }
+ *
+ * // Transaction support
+ * await service.withTransaction(async (tx) => {
+ *   const entry = await service.createEntryInTransaction(tx, 'posts', data, context);
+ *   await service.updateEntryInTransaction(tx, 'posts', entry.id, moreData, context);
+ * });
+ * ```
+ */
+
+/**
+ * Collection metadata returned from operations
+ */
+interface Collection {
+    id: string;
+    name: string;
+    label: string;
+    tableName: string;
+    description?: string;
+    icon?: string;
+    schemaDefinition: {
+        fields: FieldDefinition[];
+    };
+    createdBy?: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Input for creating a collection
+ */
+interface CreateCollectionInput {
+    name: string;
+    label: string;
+    description?: string;
+    icon?: string;
+    fields: FieldDefinition[];
+}
+/**
+ * Input for updating a collection
+ */
+interface UpdateCollectionInput {
+    label?: string;
+    description?: string;
+    icon?: string;
+    fields?: FieldDefinition[];
+}
+/**
+ * Options for listing collections
+ */
+interface ListCollectionsOptions {
+    page?: number;
+    limit?: number;
+    search?: string;
+    sortBy?: "slug" | "createdAt" | "updatedAt";
+    sortOrder?: "asc" | "desc";
+    includeSchema?: boolean;
+}
+/**
+ * Entry (document) within a collection
+ */
+interface CollectionEntry {
+    id: string;
+    [key: string]: unknown;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * CollectionService - Unified service for collection and entry operations
+ *
+ * Provides both collection metadata CRUD (create/update/delete collections)
+ * and entry CRUD (documents within collections) with:
+ *
+ * - Exception-based error handling (throws NextlyError)
+ * - Type-safe RequestContext
+ * - PaginatedResult for list operations
+ * - Database adapter abstraction for multi-DB support
+ * - Transaction support via adapter transactions
+ *
+ * @extends BaseService - Provides adapter access, transaction helpers, and WHERE clause builders
+ */
+declare class CollectionService extends BaseService {
+    private readonly metadataService;
+    private readonly entryService;
+    constructor(adapter: DrizzleAdapter, logger: Logger, metadataService: CollectionMetadataService, entryService: CollectionEntryService);
+    /**
+     * Register dynamic collection schemas for runtime use.
+     *
+     * This should be called during app initialization to register
+     * the generated Drizzle schema files for dynamic collections.
+     *
+     * @param schemas - Object mapping schema names to Drizzle table definitions
+     *
+     * @example
+     * ```typescript
+     * import * as dynamicSchemas from "@/db/schemas/dynamic";
+     *
+     * const service = getCollectionsService();
+     * service.registerDynamicSchemas(dynamicSchemas);
+     * ```
+     */
+    registerDynamicSchemas(schemas: Record<string, unknown>): void;
+    /**
+     * Create a new collection
+     *
+     * @param input - Collection creation data
+     * @param context - Request context with user info
+     * @returns Created collection
+     * @throws NextlyError if creation fails
+     *
+     * @example
+     * ```typescript
+     * const collection = await service.createCollection({
+     *   name: 'posts',
+     *   label: 'Blog Posts',
+     *   fields: [
+     *     { name: 'title', type: 'text', required: true },
+     *     { name: 'content', type: 'richText' },
+     *   ]
+     * }, context);
+     * ```
+     */
+    createCollection(input: CreateCollectionInput, context: RequestContext): Promise<Collection>;
+    /**
+     * List collections with pagination
+     *
+     * @param options - Pagination and filter options
+     * @param context - Request context
+     * @returns Paginated list of collections
+     * @throws NextlyError if listing fails
+     */
+    listCollections(options: ListCollectionsOptions | undefined, _context: RequestContext): Promise<PaginatedResult<Collection>>;
+    /**
+     * Get a single collection by name
+     *
+     * @param collectionName - Name of the collection
+     * @param context - Request context
+     * @returns Collection metadata
+     * @throws NextlyError with NOT_FOUND if collection doesn't exist
+     */
+    getCollection(collectionName: string, _context: RequestContext): Promise<Collection>;
+    /**
+     * Update a collection's metadata and/or schema
+     *
+     * @param collectionName - Name of the collection to update
+     * @param input - Update data
+     * @param context - Request context
+     * @returns Updated collection
+     * @throws NextlyError if update fails
+     */
+    updateCollection(collectionName: string, input: UpdateCollectionInput, _context: RequestContext): Promise<Collection>;
+    /**
+     * Delete a collection
+     *
+     * @param collectionName - Name of the collection to delete
+     * @param context - Request context
+     * @throws NextlyError if deletion fails
+     */
+    deleteCollection(collectionName: string, _context: RequestContext): Promise<void>;
+    /**
+     * Create a new entry in a collection
+     *
+     * @param collectionName - Name of the collection
+     * @param data - Entry data
+     * @param context - Request context with user info
+     * @returns Created entry
+     * @throws NextlyError if creation fails
+     *
+     * @example
+     * ```typescript
+     * const post = await service.createEntry('posts', {
+     *   title: 'Hello World',
+     *   content: 'My first post',
+     * }, context);
+     * ```
+     */
+    createEntry(collectionName: string, data: Record<string, unknown>, context: RequestContext): Promise<CollectionEntry>;
+    /**
+     * List entries in a collection
+     *
+     * @param collectionName - Name of the collection
+     * @param options - Query options (pagination, sort, where)
+     * @param context - Request context
+     * @returns Paginated list of entries
+     * @throws NextlyError if listing fails
+     */
+    listEntries(collectionName: string, options: QueryOptions | undefined, context: RequestContext): Promise<PaginatedResult<CollectionEntry>>;
+    /**
+     * Find an entry by ID
+     *
+     * @param collectionName - Name of the collection
+     * @param entryId - ID of the entry
+     * @param context - Request context
+     * @returns Entry data
+     * @throws NextlyError with NOT_FOUND if entry doesn't exist
+     */
+    findEntryById(collectionName: string, entryId: string, context: RequestContext): Promise<CollectionEntry>;
+    /**
+     * Update an entry
+     *
+     * @param collectionName - Name of the collection
+     * @param entryId - ID of the entry to update
+     * @param data - Update data
+     * @param context - Request context
+     * @returns Updated entry
+     * @throws NextlyError if update fails
+     */
+    updateEntry(collectionName: string, entryId: string, data: Record<string, unknown>, context: RequestContext): Promise<CollectionEntry>;
+    /**
+     * Delete an entry
+     *
+     * @param collectionName - Name of the collection
+     * @param entryId - ID of the entry to delete
+     * @param context - Request context
+     * @throws NextlyError if deletion fails
+     */
+    deleteEntry(collectionName: string, entryId: string, context: RequestContext): Promise<void>;
+    /**
+     * Create an entry within an existing transaction
+     *
+     * Use this when you need to coordinate multiple operations atomically.
+     *
+     * @param tx - Transaction context from adapter
+     * @param collectionName - Name of the collection
+     * @param data - Entry data
+     * @param context - Request context
+     * @returns Created entry
+     * @throws Error if underlying service doesn't support transaction context
+     *
+     * @example
+     * ```typescript
+     * await service.withTransaction(async (tx) => {
+     *   const entry = await service.createEntryInTransaction(tx, 'posts', data, context);
+     *   await service.updateEntryInTransaction(tx, 'posts', entry.id, moreData, context);
+     * });
+     * ```
+     */
+    createEntryInTransaction(tx: TransactionContext, collectionName: string, data: Record<string, unknown>, context: RequestContext): Promise<CollectionEntry>;
+    /**
+     * Update an entry within an existing transaction
+     *
+     * @param tx - Transaction context from adapter
+     * @param collectionName - Name of the collection
+     * @param entryId - ID of the entry to update
+     * @param data - Update data
+     * @param context - Request context
+     * @returns Updated entry
+     * @throws Error if underlying service doesn't support transaction context
+     */
+    updateEntryInTransaction(tx: TransactionContext, collectionName: string, entryId: string, data: Record<string, unknown>, context: RequestContext): Promise<CollectionEntry>;
+    /**
+     * Delete an entry within an existing transaction
+     *
+     * @param tx - Transaction context from adapter
+     * @param collectionName - Name of the collection
+     * @param entryId - ID of the entry to delete
+     * @param context - Request context
+     * @throws Error if underlying service doesn't support transaction context
+     */
+    deleteEntryInTransaction(tx: TransactionContext, collectionName: string, entryId: string, context: RequestContext): Promise<void>;
+    /**
+     * Translate a legacy CollectionServiceResult / MetadataServiceResult failure
+     * into a thrown NextlyError. Only used for non-404/403 cases — those have
+     * dedicated factory calls inline at each call site so identifiers can move
+     * cleanly to logContext.
+     *
+     * Per §13.8, the public message is generic for the matched factory; the
+     * inner legacy message moves to logContext for operators only and never
+     * reaches the wire.
+     */
+    private mapLegacyErrorToNextlyError;
+}
+
+/**
+ * ComponentSchemaService generates database schemas for component data tables (`comp_{slug}`).
+ * Supports PostgreSQL, MySQL, and SQLite dialects.
+ */
+
+type SupportedDialect = "postgresql" | "mysql" | "sqlite";
+declare class ComponentSchemaService {
+    private readonly dialect;
+    private readonly q;
+    constructor(dialect?: SupportedDialect);
+    /**
+     * Generate SQL migration for creating a new component data table.
+     */
+    generateMigrationSQL(tableName: string, fields: FieldConfig[]): string;
+    /**
+     * Generate ALTER TABLE migration for updating a component data table.
+     */
+    generateAlterTableMigration(tableName: string, oldFields: FieldConfig[], newFields: FieldConfig[]): string;
+    /**
+     * Generate DROP TABLE migration for a component data table.
+     */
+    generateDropTableMigration(tableName: string): {
+        migrationSQL: string;
+        migrationFileName: string;
+    };
+    /**
+     * Generate a Drizzle table object at runtime for querying component data.
+     */
+    generateRuntimeSchema(tableName: string, fields: FieldConfig[]): unknown;
+    private generatePostgresSchema;
+    private generateMySQLSchema;
+    private generateSQLiteSchema;
+    /**
+     * Generate TypeScript/Drizzle schema code for a component data table.
+     */
+    generateSchemaCode(tableName: string, componentSlug: string, fields: FieldConfig[]): string;
+    private generateColumnSQL;
+    private getColumnType;
+    private mapFieldToPostgresColumn;
+    private mapFieldToMySQLColumn;
+    private mapFieldToSQLiteColumn;
+    private mapFieldToDrizzleCode;
+    private mapFieldToPostgresCode;
+    private mapFieldToMySQLCode;
+    private mapFieldToSQLiteCode;
+    private getDialectConfig;
+    private collectRequiredImports;
+    private generateBaseColumnsCode;
+    private generateTimestampColumnsCode;
+    private fieldHasForeignKey;
+    private isFieldModified;
+    private buildFieldMap;
+    private getDefaultValueForType;
+    private formatDefaultValue;
+    private toSnakeCase;
+    private toPascalCase;
+}
+
+/**
+ * Activity Log Service
+ *
+ * Records and queries user activity (create/update/delete) across all
+ * collections. Designed for the dashboard activity feed — not a full
+ * audit log. Writes are fire-and-forget; failures never propagate to
+ * the caller.
+ *
+ * @module services/dashboard/activity-log-service
+ * @since 1.0.0
+ */
+
+/** The three mutation actions tracked in the activity log. */
+type ActivityLogAction = "create" | "update" | "delete";
+/** A single activity log record as returned by queries. */
+interface ActivityLogEntry {
+    id: string;
+    userId: string;
+    userName: string;
+    userEmail: string;
+    action: ActivityLogAction;
+    collection: string;
+    entryId: string | null;
+    entryTitle: string | null;
+    metadata: Record<string, unknown> | null;
+    createdAt: string;
+}
+/** Input for recording a new activity. */
+interface LogActivityInput {
+    userId: string;
+    userName: string;
+    userEmail: string;
+    action: ActivityLogAction;
+    collection: string;
+    entryId?: string;
+    entryTitle?: string;
+    metadata?: Record<string, unknown>;
+}
+/** Paginated activity log response. */
+interface ActivityLogResult {
+    activities: ActivityLogEntry[];
+    total: number;
+    hasMore: boolean;
+}
+/** Options for querying the activity log. */
+interface ActivityLogQueryOptions {
+    limit?: number;
+    offset?: number;
+    collection?: string;
+    userId?: string;
+}
+declare class ActivityLogService extends BaseService {
+    constructor(adapter: DrizzleAdapter, logger: Logger);
+    /**
+     * Record an activity log entry.
+     *
+     * Errors are caught and logged but never propagated — activity logging
+     * must never break a content operation.
+     */
+    logActivity(input: LogActivityInput): Promise<void>;
+    /**
+     * Query recent activity log entries with optional filters.
+     *
+     * Uses the `limit + 1` pattern to determine `hasMore` without a
+     * separate COUNT query. The `total` field uses a separate count query
+     * only when needed.
+     */
+    getRecentActivity(options?: ActivityLogQueryOptions): Promise<ActivityLogResult>;
+    /**
+     * Delete activity log records older than the specified number of days.
+     *
+     * @param olderThanDays - Delete records older than this many days (default: 90)
+     * @returns Number of deleted records
+     */
+    cleanupOldActivities(olderThanDays?: number): Promise<number>;
+    private countActivities;
+    private mapRow;
+}
+
+/**
+ * Dashboard Service
+ *
+ * Aggregates content-centric statistics, recent entries across collections,
+ * and project-wide metrics for the admin dashboard. Uses the database adapter
+ * directly for simple read-only aggregate queries — no hooks, access control,
+ * or relationship expansion needed for dashboard stats.
+ *
+ * @module services/dashboard/dashboard-service
+ * @since 1.0.0
+ */
+
+/** Content statistics for the hero stats row. */
+interface ContentStats {
+    totalEntries: number;
+    totalMedia: number;
+    contentTypes: number;
+    recentChanges24h: number;
+}
+/** Draft vs Published breakdown. */
+interface ContentStatus {
+    published: number;
+    draft: number;
+}
+/** Per-collection entry count for collection quick-links. */
+interface CollectionCount {
+    slug: string;
+    label: string;
+    group: string | null;
+    count: number;
+}
+/** Full dashboard stats response. */
+interface DashboardStatsResponse {
+    content: ContentStats;
+    status: ContentStatus;
+    collectionCounts: CollectionCount[];
+    users: number;
+    roles: number;
+    permissions: number;
+    components: number;
+    singles: number;
+    apiKeys: number;
+}
+/** A recently edited entry across any collection. */
+interface RecentEntry {
+    id: string;
+    title: string;
+    collectionSlug: string;
+    collectionLabel: string;
+    status: "published" | "draft" | "none";
+    updatedAt: string;
+}
+/** Response for the recent entries endpoint. */
+interface RecentEntriesResponse {
+    entries: RecentEntry[];
+}
+/** Single stat item for the project statistics grid. */
+interface ProjectStat {
+    key: string;
+    label: string;
+    value: number;
+}
+/** Response for the project stats endpoint. */
+interface ProjectStatsResponse {
+    stats: ProjectStat[];
+}
+declare class DashboardService extends BaseService {
+    constructor(adapter: DrizzleAdapter, logger: Logger);
+    /**
+     * Get aggregated dashboard statistics.
+     *
+     * Runs all count queries in parallel for fast response. Uses the database
+     * adapter directly for simple COUNT(*) queries.
+     */
+    getStats(options?: {
+        readableResources?: Set<string>;
+    }): Promise<DashboardStatsResponse>;
+    /**
+     * Get recently modified entries across all collections.
+     *
+     * Queries each registered collection for entries sorted by `updated_at DESC`,
+     * merges results, and returns the top N entries. Capped at 20 collections
+     * to prevent excessive DB queries on large installations.
+     *
+     * @param limit - Maximum number of entries to return (default: 5, max: 20)
+     */
+    getRecentEntries(limit?: number, readableResources?: Set<string>): Promise<RecentEntriesResponse>;
+    /**
+     * Get project-wide statistics for the stats grid.
+     *
+     * Returns an array of stat items for display in the 2×4 grid widget.
+     * Reuses the same data sources as `getStats()`.
+     */
+    getProjectStats(options?: {
+        readableResources?: Set<string>;
+    }): Promise<ProjectStatsResponse>;
+    private getRegisteredCollections;
+    private getRegisteredSingles;
+    /**
+     * Format a Date for raw-SQL bind parameters per dialect.
+     *
+     * Phase A follow-up (2026-05-01) — `BaseService.formatDateForDb()`
+     * returns the Date unchanged; that works for Drizzle's typed query
+     * builder (which converts based on column mode) but breaks raw
+     * `adapter.executeQuery(sql, [date])` paths on SQLite, where
+     * better-sqlite3 throws "can only bind numbers, strings, bigints,
+     * buffers, and null" on Date objects.
+     *
+     * Per-dialect format:
+     *   - SQLite: epoch SECONDS (matches Drizzle's `integer mode:"timestamp"`
+     *     storage, which is what every timestamp column in the schema uses).
+     *   - MySQL: 'YYYY-MM-DD HH:MM:SS' (DATETIME/TIMESTAMP format).
+     *   - PostgreSQL: ISO 8601 string (driver converts to timestamp natively).
+     *
+     * Helper kept local to this service since it's the only raw-query
+     * consumer; promote to BaseService if more services need it.
+     */
+    private dateForRawBind;
+    private countTable;
+    private countActiveApiKeys;
+    private countRecentChanges24h;
+    private countRegistryItems;
+    private getCollectionCounts;
+    /**
+     * Get draft vs published content breakdown across all collections.
+     *
+     * Collections without a `_status` or `status` field count all entries
+     * as published.
+     */
+    private getContentStatusBreakdown;
+    private countByStatus;
+    private getRecentFromCollection;
+}
+
+/**
+ * Shared type definitions for the General Settings schema.
+ *
+ * @module schemas/general-settings/types
+ * @since 1.0.0
+ */
+/**
+ * Full record type for the `site_settings` singleton row.
+ * The `id` is always `'default'`.
+ */
+interface GeneralSettingsRecord {
+    /** Always 'default' — enforces singleton pattern. */
+    id: string;
+    /** Display name for the application (used in admin UI title, email templates). */
+    applicationName: string | null;
+    /** Primary URL where the site is hosted (used for email links). */
+    siteUrl: string | null;
+    /** Primary email address for administrative notifications / default sender. */
+    adminEmail: string | null;
+    /** IANA timezone identifier, e.g. 'America/New_York'. */
+    timezone: string | null;
+    /** Date display format string, e.g. 'MM/DD/YYYY'. */
+    dateFormat: string | null;
+    /** Time display format: '12h' or '24h'. */
+    timeFormat: string | null;
+    /** URL of the logo image shown in the admin sidebar and auth pages. */
+    logoUrl: string | null;
+    /** JSON array of custom sidebar groups for admin navigation. */
+    customSidebarGroups: string | null;
+    /** JSON object mapping plugin slugs to their sidebar placement group overrides. */
+    pluginPlacements: string | null;
+    /** When the settings were last updated. */
+    updatedAt: Date;
+}
+/**
+ * Fields that can be updated via the settings form.
+ * Excludes immutable `id` and auto-managed `updatedAt`.
+ */
+type GeneralSettingsUpdate = Omit<GeneralSettingsRecord, "id" | "updatedAt">;
+
+/**
+ * General Settings Service
+ *
+ * Manages the `site_settings` singleton row — a single record
+ * (id = 'default') that stores application-level configuration:
+ * application name, site URL, admin email, timezone, and display formats.
+ *
+ * @module services/general-settings/general-settings-service
+ * @since 1.0.0
+ */
+
+interface CustomSidebarGroup {
+    slug: string;
+    name: string;
+    icon?: string;
+}
+declare class GeneralSettingsService extends BaseService {
+    private siteSettings;
+    constructor(adapter: DrizzleAdapter, logger: Logger);
+    private toRecord;
+    /**
+     * Retrieve the current general settings.
+     * Returns an all-null record if the singleton row has not been saved yet.
+     */
+    getSettings(): Promise<GeneralSettingsRecord>;
+    /**
+     * Get the configured IANA timezone identifier.
+     * Reads from the singleton row each call so updates are reflected
+     * consistently across long-lived runtime instances.
+     */
+    getTimezone(): Promise<string | null>;
+    /**
+     * Upsert the general settings singleton row.
+     * Only the provided fields are updated; omitted fields are left unchanged.
+     * If the row doesn't exist yet, it is created with the provided values.
+     */
+    updateSettings(data: Partial<GeneralSettingsUpdate>): Promise<GeneralSettingsRecord>;
+    /**
+     * Parse the stored JSON string into an array of custom sidebar groups.
+     * Returns an empty array if no groups are stored or JSON is invalid.
+     */
+    getCustomSidebarGroups(settings: GeneralSettingsRecord): CustomSidebarGroup[];
+    /**
+     * Replace all custom sidebar groups with the provided array.
+     * Persists as a JSON string in the `custom_sidebar_groups` column.
+     */
+    updateCustomSidebarGroups(groups: CustomSidebarGroup[]): Promise<CustomSidebarGroup[]>;
+}
+
+/**
+ * Service Registration for DI Container
+ *
+ * Provides the async entrypoint `registerServices()` that bootstraps the
+ * database adapter, media storage, and every Nextly domain service. The
+ * individual domain registrations live in `./registrations/` — this file
+ * is the orchestrator that stitches them together.
+ *
+ * **IMPORTANT:** `registerServices()` is async and must be awaited.
+ * The database adapter is created and connected during registration for
+ * fail-fast error handling and predictable initialization.
+ *
+ * @example
+ * ```typescript
+ * import { registerServices, getService } from 'nextly';
+ *
+ * await registerServices({
+ *   imageProcessor: getImageProcessor(),
+ *   logger: customLogger, // optional
+ * });
+ *
+ * const userService = getService('userService');
+ * const user = await userService.findById(userId, context);
+ * ```
+ */
+
+/**
+ * Configuration for service registration.
+ *
+ * **Database Configuration:** if `adapter` is provided, it is used
+ * directly. Otherwise, one is created from environment variables using
+ * `DB_DIALECT` and `DATABASE_URL`.
+ */
+interface NextlyServiceConfig {
+    /**
+     * Database adapter for multi-database support.
+     * If not provided, created automatically from environment variables.
+     */
+    adapter?: DrizzleAdapter;
+    /** Storage plugins for cloud storage providers (S3, Vercel Blob, etc.). */
+    storagePlugins?: StoragePlugin[];
+    /** Image processor for media operations. */
+    imageProcessor: ImageProcessor;
+    /** Optional logger instance. Defaults to `consoleLogger`. */
+    logger?: Logger;
+    /** Optional hook registry. When absent, hooks are disabled. */
+    hookRegistry?: HookRegistry;
+    /** Optional password hasher for user authentication. */
+    passwordHasher?: {
+        hash(password: string): Promise<string>;
+        verify(password: string, hash: string): Promise<boolean>;
+    };
+    /** Optional base path for collection file operations. */
+    basePath?: string;
+    /** Optional directory for dynamic collection schemas. */
+    schemasDir?: string;
+    /** Optional directory for dynamic collection migrations. */
+    migrationsDir?: string;
+    /** Plugins to initialize with Nextly. */
+    plugins?: PluginDefinition[];
+    /** Collection configurations. */
+    collections?: CollectionConfig[];
+    /** Single (global document) configurations. */
+    singles?: SingleConfig[];
+    /** Component (reusable field group) configurations. */
+    components?: ComponentConfig[];
+    /** User model extension configuration. */
+    users?: UserConfig;
+    /** Email system configuration. */
+    email?: EmailConfig;
+    /** API key authentication configuration with defaults applied. */
+    apiKeys?: SanitizedApiKeysConfig;
+    /** Security configuration (headers, CORS, uploads, sanitization). */
+    security?: SecurityConfig;
+    /**
+     * Admin panel configuration (branding, plugin overrides, devAutoLogin).
+     * Carried through from `nextly.config.ts` so handlers that read from the
+     * DI's "config" service can see admin-level toggles. Without this the
+     * admin object gets dropped during buildServiceConfig.
+     */
+    admin?: AdminConfig;
+    /**
+     * Authentication configuration (revealRegistrationConflict and friends).
+     * Same rationale as admin: carried through so handlers can read it.
+     */
+    auth?: AuthConfig;
+}
+/**
+ * Type-safe service map returned by `getService()`.
+ */
+interface ServiceMap {
+    adapter: DrizzleAdapter;
+    logger: Logger;
+    config: NextlyServiceConfig;
+    mediaStorage: MediaStorage;
+    collectionService: CollectionService;
+    collectionRegistryService: CollectionRegistryService;
+    userService: UserService;
+    mediaService: MediaService;
+    singleRegistryService: SingleRegistryService;
+    singleEntryService: SingleEntryService;
+    componentRegistryService: ComponentRegistryService;
+    componentSchemaService: ComponentSchemaService;
+    componentDataService: ComponentDataService;
+    relationshipService: CollectionRelationshipService;
+    userExtSchemaService: UserExtSchemaService;
+    emailProviderService: EmailProviderService;
+    emailTemplateService: EmailTemplateService;
+    emailService: EmailService;
+    userFieldDefinitionService: UserFieldDefinitionService;
+    permissionSeedService: PermissionSeedService;
+    rbacAccessControlService: RBACAccessControlService;
+    apiKeyService: ApiKeyService;
+    authService: AuthService;
+    generalSettingsService: GeneralSettingsService;
+    activityLogService: ActivityLogService;
+    dashboardService: DashboardService;
+    metaService: MetaService;
+}
+/**
+ * Register all Nextly services in the DI container.
+ *
+ * This function should be called once during application initialization.
+ * Services are registered as singletons and lazily initialized on first access.
+ *
+ * @param config - Service configuration with required dependencies
+ * @throws Error if called multiple times (use `clearServices()` first)
+ * @throws Error if database environment configuration is invalid
+ * @throws Error if database connection fails
+ */
+declare function registerServices(config: NextlyServiceConfig): Promise<void>;
+/**
+ * Get a service from the container with type safety.
+ * Services must be registered first via `registerServices()`.
+ */
+declare function getService<T extends keyof ServiceMap>(name: T): ServiceMap[T];
+/**
+ * Check if services have been registered.
+ */
+declare function isServicesRegistered(): boolean;
+/**
+ * Shutdown all services and cleanup resources. Should be called when
+ * shutting down the application to ensure proper cleanup of database
+ * connections and other resources.
+ */
+declare function shutdownServices(): Promise<void>;
+/**
+ * Clear all registered services. Primarily for testing or re-initialization
+ * with different configuration. For production shutdown, prefer
+ * `shutdownServices()` so resources are properly released.
+ */
+declare function clearServices(): void;
+
+/**
+ * Plugin Context System
+ *
+ * Provides a type-safe context for plugins to access Nextly services.
+ * Plugins receive this context during initialization, enabling them
+ * to interact with core services and register hooks.
+ *
+ * @module plugins/plugin-context
+ * @since 1.0.0
+ */
+
+/**
+ * Simplified hook registry interface for plugins.
+ *
+ * Provides only the methods plugins should use (register/unregister hooks).
+ * Internal methods like `execute()` and `clear()` are not exposed.
+ *
+ * @example
+ * ```typescript
+ * export const myPlugin = definePlugin({
+ *   name: 'my-plugin',
+ *
+ *   async init(nextly) {
+ *     // Register a beforeCreate hook
+ *     nextly.hooks.on('beforeCreate', 'posts', async (context) => {
+ *       context.data.slug = slugify(context.data.title);
+ *       return context.data;
+ *     });
+ *
+ *     // Register a global hook (all collections)
+ *     nextly.hooks.on('afterCreate', '*', async (context) => {
+ *       nextly.infra.logger.info(`Created ${context.collection}:${context.data?.id}`);
+ *     });
+ *   }
+ * });
+ * ```
+ */
+interface PluginHookRegistry {
+    /**
+     * Register a hook for a specific collection and hook type.
+     *
+     * @param hookType - Type of hook (beforeCreate, afterCreate, etc.)
+     * @param collection - Collection name or '*' for global hooks
+     * @param handler - Hook function to execute
+     *
+     * @example
+     * ```typescript
+     * // Collection-specific hook
+     * nextly.hooks.on('beforeCreate', 'users', async (context) => {
+     *   context.data.password = await bcrypt.hash(context.data.password, 10);
+     *   return context.data;
+     * });
+     *
+     * // Global hook (runs for all collections)
+     * nextly.hooks.on('afterDelete', '*', async (context) => {
+     *   console.log(`Deleted from ${context.collection}`);
+     * });
+     * ```
+     */
+    on<T = unknown>(hookType: HookType, collection: string, handler: HookHandler<T>): void;
+    /**
+     * Unregister a previously registered hook.
+     *
+     * @param hookType - Type of hook
+     * @param collection - Collection name or '*'
+     * @param handler - The exact handler function to remove
+     *
+     * @example
+     * ```typescript
+     * const myHook = async (context) => { ... };
+     *
+     * // Register
+     * nextly.hooks.on('beforeCreate', 'posts', myHook);
+     *
+     * // Later, unregister
+     * nextly.hooks.off('beforeCreate', 'posts', myHook);
+     * ```
+     */
+    off<T = unknown>(hookType: HookType, collection: string, handler: HookHandler<T>): void;
+}
+/**
+ * PluginContext - Type-safe context for plugin service access.
+ *
+ * Plugins receive this context during initialization, providing
+ * access to all Nextly services and infrastructure.
+ *
+ * The context is organized into logical groups:
+ * - `services`: Core business logic services (collections, users, media)
+ * - `infra`: Infrastructure components (database, logger)
+ * - `config`: Read-only configuration
+ * - `hooks`: Hook registration for lifecycle events
+ *
+ * @example
+ * ```typescript
+ * import { definePlugin } from 'nextly';
+ *
+ * export const myPlugin = definePlugin({
+ *   name: 'my-plugin',
+ *   version: '1.0.0',
+ *
+ *   async init(nextly) {
+ *     // Access services with full TypeScript autocomplete
+ *     const { collections, users, media } = nextly.services;
+ *
+ *     // Register hooks
+ *     nextly.hooks.on('beforeCreate', 'posts', async (context) => {
+ *       // Validate that author exists
+ *       const author = await users.findById(context.data.authorId, {});
+ *       if (!author) {
+ *         throw new Error('Author not found');
+ *       }
+ *       return context.data;
+ *     });
+ *
+ *     // Use infrastructure
+ *     nextly.infra.logger.info('MyPlugin initialized');
+ *   }
+ * });
+ * ```
+ */
+interface PluginContext {
+    /**
+     * Core services with full TypeScript autocomplete.
+     *
+     * Provides access to the unified service layer for:
+     * - Collections: CRUD operations on dynamic collections
+     * - Users: User management and authentication
+     * - Media: File upload and management
+     */
+    services: {
+        /** Collection service for CRUD operations on dynamic collections */
+        collections: CollectionService;
+        /** User service for user management */
+        users: UserService;
+        /** Media service for file operations */
+        media: MediaService;
+        /** Email service for sending emails via templates and providers */
+        email: EmailService;
+    };
+    /**
+     * Infrastructure access.
+     *
+     * Provides access to low-level infrastructure:
+     * - Database: Direct Drizzle database access (use with caution)
+     * - Logger: Logging interface for plugin diagnostics
+     */
+    infra: {
+        /** Drizzle database instance for direct queries */
+        db: DatabaseInstance;
+        /** Logger for plugin diagnostics */
+        logger: Logger;
+    };
+    /**
+     * Read-only configuration.
+     *
+     * Contains the Nextly service configuration.
+     * Configuration is frozen to prevent accidental modification.
+     */
+    config: Readonly<NextlyServiceConfig>;
+    /**
+     * Hook registration for lifecycle events.
+     *
+     * Allows plugins to register hooks that run before/after
+     * database operations on collections.
+     */
+    hooks: PluginHookRegistry;
+}
+/**
+ * Sidebar appearance customization for plugins.
+ *
+ * Allows plugin authors to customize how their plugin appears
+ * in the admin sidebar. All fields are optional — unset fields
+ * use sensible defaults (Package icon, plugin name as label).
+ *
+ * @example
+ * ```typescript
+ * admin: {
+ *   appearance: {
+ *     icon: "BarChart",       // Lucide icon name
+ *     label: "Analytics",     // Custom sidebar label
+ *     badge: "Beta",          // Badge text
+ *     badgeVariant: "secondary",
+ *   },
+ * }
+ * ```
+ */
+interface PluginAdminAppearance {
+    /** Lucide icon name for the plugin's sidebar entry */
+    icon?: string;
+    /** Custom label override (defaults to plugin name) */
+    label?: string;
+    /** Badge text shown next to the plugin name (e.g., "Beta", "New") */
+    badge?: string;
+    /** Badge variant for styling */
+    badgeVariant?: "default" | "secondary" | "destructive" | "outline";
+}
+/**
+ * Plugin admin configuration for sidebar placement and appearance.
+ *
+ * Allows plugins to declare their sidebar placement, sort order,
+ * appearance customization, and description for the plugin settings page.
+ *
+ * @example
+ * ```typescript
+ * import { definePlugin, AdminPlacement } from 'nextly';
+ *
+ * export const analyticsPlugin = definePlugin({
+ *   name: 'Analytics Dashboard',
+ *   admin: {
+ *     placement: AdminPlacement.USERS,
+ *     order: 60,
+ *     description: 'User analytics and insights',
+ *     appearance: {
+ *       icon: 'BarChart',
+ *       label: 'Analytics',
+ *       badge: 'Beta',
+ *       badgeVariant: 'secondary',
+ *     },
+ *   },
+ * });
+ * ```
+ */
+interface PluginAdminConfig {
+    /**
+     * Immutable sidebar placement for this plugin's items.
+     *
+     * Use `AdminPlacement` constants for TypeScript autocomplete:
+     * - `AdminPlacement.COLLECTIONS` (Collections section)
+     * - `AdminPlacement.SINGLES` (Singles section)
+     * - `AdminPlacement.USERS` (Users inner sidebar)
+     * - `AdminPlacement.SETTINGS` (Settings inner sidebar)
+     * - `AdminPlacement.PLUGINS` (Plugins section, default)
+     *
+     * If not set, falls back to `"plugins"`.
+     */
+    placement?: AdminPlacement;
+    /** Sort order when placed in a group (lower = higher position, default: 100) */
+    order?: number;
+    /**
+     * Position anchor for standalone plugins.
+     * Specifies which built-in sidebar section this plugin's icon appears after.
+     *
+     * Valid values: `"dashboard"` | `"collections"` | `"singles"` | `"media"` | `"plugins"` | `"users"`
+     *
+     * Only applies when `placement` is `AdminPlacement.STANDALONE`.
+     * If multiple standalone plugins share the same `after`, they are sorted by `order`.
+     * Defaults to `"plugins"` (after the Plugins icon).
+     *
+     * @example
+     * ```ts
+     * admin: {
+     *   placement: AdminPlacement.STANDALONE,
+     *   after: "collections", // icon appears right after Collections
+     *   order: 10,
+     * }
+     * ```
+     */
+    after?: "dashboard" | "collections" | "singles" | "media" | "plugins" | "users" | "settings";
+    /** Plugin description shown on the plugin settings page */
+    description?: string;
+    /** Sidebar appearance customization (icon, label, badge) */
+    appearance?: PluginAdminAppearance;
+}
+/**
+ * Plugin definition interface.
+ *
+ * Defines the structure of a Nextly plugin. Plugins can:
+ * - Initialize with access to PluginContext
+ * - Transform configuration before services are registered
+ *
+ * @example
+ * ```typescript
+ * import { definePlugin } from 'nextly';
+ *
+ * export const auditLogPlugin = definePlugin({
+ *   name: 'audit-log',
+ *   version: '1.0.0',
+ *
+ *   async init(nextly) {
+ *     // Log all create/update/delete operations
+ *     const logOperation = async (context) => {
+ *       nextly.infra.logger.info('Audit', {
+ *         collection: context.collection,
+ *         operation: context.operation,
+ *         user: context.user?.id,
+ *         timestamp: new Date().toISOString(),
+ *       });
+ *     };
+ *
+ *     nextly.hooks.on('afterCreate', '*', logOperation);
+ *     nextly.hooks.on('afterUpdate', '*', logOperation);
+ *     nextly.hooks.on('afterDelete', '*', logOperation);
+ *   }
+ * });
+ * ```
+ */
+interface PluginDefinition {
+    /**
+     * Unique plugin name.
+     * Used for identification and error messages.
+     */
+    name: string;
+    /**
+     * Plugin version (semver format recommended).
+     * Helps with debugging and compatibility checks.
+     */
+    version?: string;
+    /**
+     * Collections provided by this plugin.
+     *
+     * These collections are automatically merged with user collections
+     * in defineConfig(). Users don't need to manually spread plugin collections.
+     *
+     * @example
+     * ```typescript
+     * // Plugin definition
+     * const myPlugin: PluginDefinition = {
+     *   name: 'my-plugin',
+     *   collections: [FormsCollection, SubmissionsCollection],
+     * };
+     *
+     * // User config - collections are auto-merged
+     * export default defineConfig({
+     *   plugins: [myPlugin],
+     *   collections: [Posts, Users], // Plugin collections added automatically
+     * });
+     * ```
+     */
+    collections?: CollectionConfig[];
+    /**
+     * Admin configuration for sidebar placement and plugin metadata.
+     *
+     * Controls where the plugin's items appear in the sidebar
+     * and provides metadata for the plugin settings page.
+     */
+    admin?: PluginAdminConfig;
+    /**
+     * Plugin initialization function.
+     *
+     * Called after all services are registered.
+     * Receives PluginContext for service access and hook registration.
+     *
+     * @param context - PluginContext with services, infra, config, hooks
+     */
+    init?: (context: PluginContext) => Promise<void> | void;
+    /**
+     * Configuration transformer (advanced).
+     *
+     * Allows plugins to modify the config before service initialization.
+     * Use with caution - this runs before services are available.
+     *
+     * @param config - Current configuration
+     * @returns Modified configuration
+     */
+    config?: (config: NextlyServiceConfig) => NextlyServiceConfig;
+}
+/**
+ * Define a plugin with type safety.
+ *
+ * This is a helper function that provides TypeScript autocomplete
+ * when defining plugins. It simply returns the definition as-is.
+ *
+ * @param definition - Plugin definition
+ * @returns The same definition (for type inference)
+ *
+ * @example
+ * ```typescript
+ * import { definePlugin } from 'nextly';
+ *
+ * export const myPlugin = definePlugin({
+ *   name: 'my-plugin',
+ *   version: '1.0.0',
+ *
+ *   async init(nextly) {
+ *     // Full TypeScript autocomplete available
+ *     nextly.services.collections.listCollections();
+ *   }
+ * });
+ * ```
+ */
+declare function definePlugin(definition: PluginDefinition): PluginDefinition;
+/**
+ * Create a PluginContext from the DI container.
+ *
+ * This factory function creates a PluginContext by retrieving
+ * services from the container. It should be called after
+ * `registerServices()` has been invoked.
+ *
+ * The config is frozen to prevent accidental modification.
+ *
+ * @param getServiceFn - Function to get services from container
+ * @param hookRegistry - Hook registry for plugin hook registration
+ * @returns Fully initialized PluginContext
+ *
+ * @example
+ * ```typescript
+ * import { getService, getHookRegistry } from 'nextly';
+ *
+ * // Create context for plugin initialization
+ * const context = createPluginContext(getService, getHookRegistry());
+ *
+ * // Initialize plugins
+ * for (const plugin of plugins) {
+ *   await plugin.init?.(context);
+ * }
+ * ```
+ */
+declare function createPluginContext(getServiceFn: <T extends "collectionService" | "userService" | "mediaService" | "emailService" | "db" | "logger" | "config">(name: T) => T extends "collectionService" ? CollectionService : T extends "userService" ? UserService : T extends "mediaService" ? MediaService : T extends "emailService" ? EmailService : T extends "db" ? DatabaseInstance : T extends "logger" ? Logger : T extends "config" ? NextlyServiceConfig : never, hookRegistry: {
+    register: (hookType: HookType, collection: string, handler: HookHandler) => void;
+    unregister: (hookType: HookType, collection: string, handler: HookHandler) => void;
+}): PluginContext;
+
+/**
+ * Security Configuration Zod Schema
+ *
+ * Validates the `security` block in `defineConfig()`. Covers four sub-sections:
+ * - `headers` — Security response headers (CSP, HSTS, X-Frame-Options, etc.)
+ * - `cors` — Cross-Origin Resource Sharing configuration
+ * - `uploads` — File upload MIME type restrictions
+ * - `sanitization` — Input sanitization toggles
+ *
+ * All fields are optional with secure defaults applied at config resolution time.
+ *
+ * @module schemas/security-config
+ * @since 1.0.0
+ */
+
+/**
+ * Validates the `security.headers` block.
+ *
+ * Each header accepts a custom string value or `false` to disable it.
+ * Omitted headers use their secure defaults (see `security-headers.ts`).
+ */
+declare const SecurityHeadersConfigSchema: z.ZodObject<{
+    contentSecurityPolicy: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<false>]>>;
+    xContentTypeOptions: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<false>]>>;
+    xFrameOptions: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<false>]>>;
+    strictTransportSecurity: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<false>]>>;
+    referrerPolicy: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<false>]>>;
+    permissionsPolicy: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<false>]>>;
+}, z.core.$strip>;
+/**
+ * Validates the `security.cors` block.
+ *
+ * Controls Cross-Origin Resource Sharing behaviour for all API responses.
+ * Default: same-origin only (empty `origin` array).
+ */
+declare const CorsConfigSchema: z.ZodObject<{
+    origin: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    methods: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    allowedHeaders: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    exposedHeaders: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    credentials: z.ZodOptional<z.ZodBoolean>;
+    maxAge: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * Validates the `security.uploads` block.
+ *
+ * Controls MIME type restrictions and SVG serving behaviour for file uploads.
+ */
+declare const UploadSecurityConfigSchema: z.ZodObject<{
+    additionalMimeTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    allowedMimeTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    svgCsp: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * Validates the `security.sanitization` block.
+ *
+ * Controls which sanitization features are active. All default to `true`.
+ */
+declare const SanitizationConfigSchema: z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    stripHtmlFromText: z.ZodOptional<z.ZodBoolean>;
+    validateCssValues: z.ZodOptional<z.ZodBoolean>;
+    validateUrlProtocols: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * Request body / multipart size caps. Each field accepts a byte count
+ * or a human-readable suffix (`"1mb"`, `"500kb"`). String shorthand
+ * is parsed at runtime; the schema stays permissive.
+ */
+declare const SecurityLimitsConfigSchema: z.ZodObject<{
+    json: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    multipart: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    fileSize: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    fileCount: z.ZodOptional<z.ZodNumber>;
+    fieldCount: z.ZodOptional<z.ZodNumber>;
+    fieldSize: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+}, z.core.$strip>;
+/**
+ * Validates the full `security` namespace in `defineConfig()`.
+ *
+ * @example
+ * ```typescript
+ * import { SecurityConfigSchema } from '@nextly/schemas/security-config';
+ *
+ * const parsed = SecurityConfigSchema.parse({
+ *   headers: { contentSecurityPolicy: "default-src 'self'" },
+ *   cors: { origin: ['https://example.com'] },
+ *   sanitization: { enabled: true },
+ *   trustProxy: true,
+ *   limits: { multipart: "100mb" },
+ * });
+ * ```
+ */
+/**
+ * Per-IP rate limit on auth write endpoints (`/auth/login`,
+ * `/auth/register`, `/auth/forgot-password`, `/auth/reset-password`).
+ * Layered on top of the per-user lockout so an attacker can't cycle
+ * usernames at full speed from one IP.
+ *
+ * The limiter shares one bucket across the four endpoints per IP so an
+ * attacker can't reset their budget by switching paths. Set
+ * `requestsPerHour` to `0` to disable (test/dev only).
+ */
+declare const AuthRateLimitConfigSchema: z.ZodObject<{
+    requestsPerHour: z.ZodOptional<z.ZodNumber>;
+    windowMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const SecurityConfigSchema: z.ZodObject<{
+    headers: z.ZodOptional<z.ZodObject<{
+        contentSecurityPolicy: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<false>]>>;
+        xContentTypeOptions: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<false>]>>;
+        xFrameOptions: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<false>]>>;
+        strictTransportSecurity: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<false>]>>;
+        referrerPolicy: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<false>]>>;
+        permissionsPolicy: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<false>]>>;
+    }, z.core.$strip>>;
+    cors: z.ZodOptional<z.ZodObject<{
+        origin: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        methods: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        allowedHeaders: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        exposedHeaders: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        credentials: z.ZodOptional<z.ZodBoolean>;
+        maxAge: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    uploads: z.ZodOptional<z.ZodObject<{
+        additionalMimeTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        allowedMimeTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        svgCsp: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    sanitization: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        stripHtmlFromText: z.ZodOptional<z.ZodBoolean>;
+        validateCssValues: z.ZodOptional<z.ZodBoolean>;
+        validateUrlProtocols: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    limits: z.ZodOptional<z.ZodObject<{
+        json: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        multipart: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        fileSize: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        fileCount: z.ZodOptional<z.ZodNumber>;
+        fieldCount: z.ZodOptional<z.ZodNumber>;
+        fieldSize: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    }, z.core.$strip>>;
+    authRateLimit: z.ZodOptional<z.ZodObject<{
+        requestsPerHour: z.ZodOptional<z.ZodNumber>;
+        windowMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    trustProxy: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type SecurityConfigInput = z.infer<typeof SecurityConfigSchema>;
+type SecurityHeadersConfigInput = z.infer<typeof SecurityHeadersConfigSchema>;
+type CorsConfigInput = z.infer<typeof CorsConfigSchema>;
+type UploadSecurityConfigInput = z.infer<typeof UploadSecurityConfigSchema>;
+type SanitizationConfigInput = z.infer<typeof SanitizationConfigSchema>;
+type SecurityLimitsConfigInput = z.infer<typeof SecurityLimitsConfigSchema>;
+type AuthRateLimitConfigInput = z.infer<typeof AuthRateLimitConfigSchema>;
+
+/**
+ * Nextly Config Types
+ *
+ * Canonical home for the public Nextly configuration interfaces and the
+ * pure sanitization helper that fills in defaults. User-facing modules
+ * like `src/collections/config/define-config.ts` re-export these types
+ * and delegate the "fill defaults" step to `sanitizeConfig()`.
+ *
+ * @module shared/types/config
+ * @since 1.0.0
+ */
+
+/**
+ * TypeScript code generation configuration.
+ *
+ * Controls how TypeScript types are generated for collections.
+ */
+interface TypeScriptConfig {
+    /**
+     * Path to the generated TypeScript file.
+     * Can be absolute or relative to the project root.
+     *
+     * @default './src/types/generated/payload-types.ts'
+     */
+    outputFile?: string;
+    /**
+     * Whether to add module augmentation declarations.
+     * When `true`, generates `declare module` blocks for type inference.
+     *
+     * @default true
+     */
+    declare?: boolean;
+}
+/**
+ * Database schema and migration configuration.
+ *
+ * Controls where Drizzle schemas and migration files are generated.
+ */
+interface DatabaseConfig {
+    /**
+     * Directory for generated Drizzle schema files.
+     * Each collection generates a separate schema file.
+     *
+     * @default './src/db/schemas/collections'
+     */
+    schemasDir?: string;
+    /**
+     * Directory for generated migration files.
+     * Migrations are created via CLI commands.
+     *
+     * @default './src/db/migrations'
+     */
+    migrationsDir?: string;
+}
+/**
+ * Rate limiting configuration for API protection.
+ *
+ * Protects against abuse by limiting the number of requests
+ * per time window. Enabled by default (100 read / 30 write per minute).
+ * Opt out with `rateLimit: { enabled: false }`.
+ */
+interface RateLimitingConfig {
+    /**
+     * Enable rate limiting.
+     * @default true
+     */
+    enabled: boolean;
+    /**
+     * Maximum requests per window for read operations (GET).
+     * @default 100
+     */
+    readLimit?: number;
+    /**
+     * Maximum requests per window for write operations (POST, PATCH, PUT, DELETE).
+     * @default 30
+     */
+    writeLimit?: number;
+    /**
+     * Time window in milliseconds.
+     * @default 60000 (1 minute)
+     */
+    windowMs?: number;
+    /**
+     * Custom store for rate limit state.
+     * Defaults to in-memory store if not provided.
+     *
+     * For production with multiple instances, use a Redis-backed store.
+     */
+    store?: RateLimitStore;
+    /**
+     * Function to generate a unique key for rate limiting.
+     * Defaults to using the client IP address.
+     */
+    keyGenerator?: (request: Request) => string;
+    /**
+     * Function to skip rate limiting for certain requests.
+     * Returns true to skip rate limiting.
+     */
+    skip?: (request: Request) => boolean | Promise<boolean>;
+    /**
+     * Per-collection rate limit overrides.
+     */
+    collections?: Record<string, {
+        readLimit?: number;
+        writeLimit?: number;
+    }>;
+}
+/**
+ * Sanitized rate limiting configuration with defaults applied.
+ */
+interface SanitizedRateLimitingConfig {
+    /** Rate limiting is enabled */
+    enabled: true;
+    /** Maximum requests per window for read operations (GET) */
+    readLimit: number;
+    /** Maximum requests per window for write operations (POST, PATCH, PUT, DELETE) */
+    writeLimit: number;
+    /** Time window in milliseconds */
+    windowMs: number;
+    /** Custom store for rate limit state (optional) */
+    store?: RateLimitStore;
+    /** Function to generate a unique key for rate limiting (optional) */
+    keyGenerator?: (request: Request) => string;
+    /** Function to skip rate limiting for certain requests (optional) */
+    skip?: (request: Request) => boolean | Promise<boolean>;
+    /** Per-collection rate limit overrides (optional) */
+    collections?: Record<string, {
+        readLimit?: number;
+        writeLimit?: number;
+    }>;
+}
+/**
+ * API key configuration.
+ *
+ * Controls per-key rate limiting for API key authentication.
+ * All fields are optional — omitting the block entirely uses built-in defaults.
+ */
+interface ApiKeysConfig {
+    /**
+     * Per-key rate limiting settings.
+     * Omit to use defaults (1 000 req/hour, 1-hour window).
+     */
+    rateLimit?: {
+        /**
+         * Maximum requests an API key may make per sliding window.
+         * Must be a positive integer.
+         * @default 1000
+         */
+        requestsPerHour?: number;
+        /**
+         * Sliding window duration in milliseconds.
+         * @default 3_600_000 (1 hour)
+         */
+        windowMs?: number;
+    };
+}
+/**
+ * Sanitized API key configuration with all defaults applied.
+ */
+interface SanitizedApiKeysConfig {
+    rateLimit: {
+        /** Maximum requests per sliding window. */
+        requestsPerHour: number;
+        /** Sliding window duration in milliseconds. */
+        windowMs: number;
+    };
+}
+/**
+ * Security configuration for Nextly.
+ *
+ * Controls security headers, CORS, file upload restrictions, and
+ * input sanitization. All sub-sections are optional — secure defaults
+ * are applied by the respective middleware factories at runtime.
+ */
+interface SecurityConfig {
+    /**
+     * Security response headers configuration.
+     *
+     * Controls CSP, X-Content-Type-Options, X-Frame-Options, HSTS,
+     * Referrer-Policy, and Permissions-Policy headers on API responses.
+     * Each header can be set to a custom string or `false` to disable.
+     * Omitted headers use secure defaults.
+     */
+    headers?: SecurityHeadersConfig;
+    /**
+     * Cross-Origin Resource Sharing (CORS) configuration.
+     *
+     * Default: same-origin only (no CORS headers). Use `origin: ['*']`
+     * for development or provide an explicit allowlist for production.
+     */
+    cors?: CorsConfig;
+    /**
+     * File upload security configuration.
+     *
+     * Controls MIME type allowlist and SVG serving behaviour.
+     * Default: common safe MIME types allowed, HTML/JS blocked,
+     * SVG served with restrictive CSP.
+     */
+    uploads?: UploadSecurityConfigInput;
+    /**
+     * Input sanitization configuration.
+     *
+     * Controls HTML tag stripping for plain-text fields, CSS value
+     * validation in rich text, and URL protocol validation.
+     * All features enabled by default.
+     */
+    sanitization?: SanitizationConfigInput;
+    /**
+     * Request body / multipart size caps. Each numeric field accepts
+     * either a byte count or a human-readable suffix (`"1mb"`,
+     * `"500kb"`). Defaults: json 1mb / multipart 50mb / fileSize 10mb /
+     * fileCount 10 / fieldCount 50 / fieldSize 100kb.
+     */
+    limits?: {
+        json?: string | number;
+        multipart?: string | number;
+        fileSize?: string | number;
+        fileCount?: number;
+        fieldCount?: number;
+        fieldSize?: string | number;
+    };
+    /**
+     * Per-IP rate limit on `/auth/login`, `/auth/register`,
+     * `/auth/forgot-password`, `/auth/reset-password`. One shared
+     * bucket per IP across all four endpoints so credential-
+     * stuffing from a single source can't cycle paths to refill its
+     * budget. Layered on top of the per-user lockout, not in place of.
+     *
+     * Set `requestsPerHour: 0` to disable the per-IP envelope (test /
+     * dev only — leaves the deployment exposed to credential-stuffing).
+     *
+     * @default `{ requestsPerHour: 30, windowMs: 3_600_000 }`
+     */
+    authRateLimit?: {
+        requestsPerHour?: number;
+        windowMs?: number;
+    };
+    /**
+     * Trust reverse-proxy headers when resolving the client IP.
+     *
+     * When `true`, `X-Forwarded-For` (filtered through the
+     * `TRUSTED_PROXY_IPS` env-var CIDR list) is used to determine the
+     * client IP for rate limiting, refresh-token binding, and audit
+     * logging. When `false` (default), proxy headers are ignored —
+     * direct-internet deployments fall back to a single `unknown`
+     * bucket so an attacker cannot rotate `X-Forwarded-For` to bypass
+     * per-IP throttles.
+     *
+     * Audit: closes C4 (XFF blindly trusted across rate-limit / auth flows).
+     *
+     * @default false
+     */
+    trustProxy?: boolean;
+}
+/**
+ * Resolved (HSL-triplet) color overrides for the admin UI.
+ * These are derived from AdminBrandingColors after server-side hex conversion.
+ */
+interface AdminBrandingColors {
+    /** Hex color for the primary brand color, e.g. "#6366f1". Replaces blue-500. */
+    primary?: string;
+    /** Hex color for the accent brand color, e.g. "#f59e0b". Replaces cyan-500. */
+    accent?: string;
+}
+/**
+ * Branding configuration for the Nextly admin UI.
+ */
+interface AdminBrandingConfig {
+    /**
+     * URL of a logo image to display in the sidebar.
+     * Can be an absolute URL or a path served from your Next.js public folder.
+     * When set, the logo image is shown instead of the text logo.
+     *
+     * @example "/logo.svg" or "https://cdn.example.com/logo.png"
+     */
+    logoUrl?: string;
+    /**
+     * URL of the light-mode logo image.
+     * Used when `logoUrl` is not set.
+     */
+    logoUrlLight?: string;
+    /**
+     * URL of the dark-mode logo image.
+     * Used when `logoUrl` is not set.
+     */
+    logoUrlDark?: string;
+    /**
+     * Text label shown in the sidebar header.
+     * Replaces the default "Nextly" label.
+     * Also used as the `alt` attribute when `logoUrl` is set.
+     *
+     * @default "Nextly"
+     */
+    logoText?: string;
+    /**
+     * URL of a custom favicon to inject into the admin page.
+     */
+    favicon?: string;
+    /**
+     * Custom brand colors for the admin UI.
+     * Accept 6-digit hex values only (e.g. "#6366f1").
+     * Foreground colors are calculated automatically to ensure WCAG AA contrast.
+     */
+    colors?: AdminBrandingColors;
+    /**
+     * Toggle visibility of builder-related navigation (Collections/Singles/Components builders).
+     *
+     * This is evaluated at runtime via the `/api/admin-meta` response.
+     *
+     * Default behavior follows `NODE_ENV`:
+     * - `production` => hidden
+     * - `development` / `test` => visible
+     *
+     * Precedence:
+     * 1) `admin.branding.showBuilder` (this field)
+     * 2) `NODE_ENV` default mapping
+     *
+     * @default `process.env.NODE_ENV !== "production"`
+     */
+    showBuilder?: boolean;
+}
+/**
+ * Per-plugin overrides for sidebar placement and appearance.
+ *
+ * The host developer can override any subset of a plugin's admin config
+ * without modifying the plugin's source code. Uses shallow merge —
+ * only specified fields override the plugin author's defaults.
+ */
+interface PluginOverride {
+    /** Override the plugin's sidebar placement */
+    placement?: AdminPlacement;
+    /** Override the plugin's sort order */
+    order?: number;
+    /** Override the position anchor for standalone plugins (which built-in section to appear after) */
+    after?: "dashboard" | "collections" | "singles" | "media" | "plugins" | "users" | "settings";
+    /** Override or extend the plugin's sidebar appearance (shallow-merged) */
+    appearance?: Partial<PluginAdminAppearance>;
+}
+/**
+ * Top-level admin UI configuration for the Nextly admin panel.
+ */
+interface AdminConfig {
+    /** Branding customizations: logo, colors, favicon. */
+    branding?: AdminBrandingConfig;
+    /**
+     * Per-plugin overrides for sidebar placement and appearance.
+     *
+     * Keys are plugin slugs (derived from plugin name, e.g., "form-builder").
+     * Values are partial overrides - only specified fields are changed.
+     */
+    pluginOverrides?: Record<string, PluginOverride>;
+    /**
+     * Development-only auto-login.
+     *
+     * When set in dev (NODE_ENV !== "production"), the admin auth gate
+     * issues a real session cookie for the named user on the first
+     * /admin visit if no session is present. Same JWT-signing codepath
+     * the real login flow uses; the only difference is the trigger.
+     *
+     * Hard-blocked when NODE_ENV === "production": Nextly's runtime
+     * ignores this field with a console warning so a misconfigured prod
+     * deploy can't silently auto-login users.
+     *
+     * Useful for the contributor playground and for local development
+     * of your own Nextly project to skip the manual login step.
+     *
+     * @example
+     * admin: {
+     *   devAutoLogin: { email: "dev@nextly.local", password: "dev" },
+     * }
+     *
+     * DO NOT enable in production deployments.
+     */
+    devAutoLogin?: false | {
+        /** Email address of the user to auto-login as. The user must exist (auto-login does not create users). */
+        email: string;
+        /**
+         * Optional. Used only as a label in dev logs. Auto-login does
+         * not verify the password - it bypasses the password-check
+         * codepath entirely since the contributor configured this.
+         */
+        password?: string;
+    };
+}
+/**
+ * Authentication configuration for Nextly.
+ *
+ * PR 5 (unified-error-system): introduces the `revealRegistrationConflict`
+ * opt-in flag. Default behaviour is silent-success on duplicate-email
+ * registration to prevent account enumeration via the registration form
+ * (spec §13.2). Some products (e.g. internal admin tools where every user
+ * is known) prefer an explicit "email already in use" message — flip this
+ * to `true` to opt into the legacy reveal-on-conflict behaviour.
+ */
+interface AuthConfig {
+    /**
+     * Whether `/auth/register` should respond with an explicit
+     * `DUPLICATE` / "An account already exists for this email." error when
+     * the submitted email is already registered.
+     *
+     * Default: `false`. The registration endpoint instead returns the same
+     * "If this email is available, we've sent a confirmation link." success
+     * shape it would on a fresh signup, regardless of whether the email
+     * existed. The duplicate is logged for operators.
+     *
+     * Set to `true` only if your threat model genuinely doesn't care about
+     * email enumeration (e.g. a closed admin tool with controlled signup).
+     */
+    revealRegistrationConflict?: boolean;
+}
+/**
+ * Sanitized auth configuration with all defaults applied.
+ */
+interface SanitizedAuthConfig {
+    /** Whether to reveal duplicate-email registrations on the wire. Defaults to false. */
+    revealRegistrationConflict: boolean;
+}
+/**
+ * Complete Nextly configuration interface.
+ *
+ * This is the main configuration object for a Nextly application,
+ * typically exported from `nextly.config.ts` at the project root.
+ */
+interface NextlyConfig {
+    /** Array of collection configurations. */
+    collections?: CollectionConfig[];
+    /** Array of Single configurations. */
+    singles?: SingleConfig[];
+    /** Array of Component configurations. */
+    components?: ComponentConfig[];
+    /** User model extension configuration. */
+    users?: UserConfig;
+    /** Email provider and template configuration. */
+    email?: EmailConfig;
+    /** TypeScript type generation configuration. */
+    typescript?: TypeScriptConfig;
+    /** Database schema and migration configuration. */
+    db?: DatabaseConfig;
+    /**
+     * Rate limiting configuration for API protection.
+     *
+     * Enabled by default (100 read / 30 write per minute). Opt out with `enabled: false`.
+     */
+    rateLimit?: RateLimitingConfig;
+    /**
+     * API key authentication configuration.
+     *
+     * Controls per-key rate limiting applied when requests authenticate via
+     * `Authorization: Bearer nx_live_...`. Session-based requests are unaffected.
+     */
+    apiKeys?: ApiKeysConfig;
+    /**
+     * Authentication configuration.
+     *
+     * Currently exposes the `revealRegistrationConflict` opt-in flag (PR 5,
+     * spec §13.2). Future auth-related options (token TTLs, lockout policy,
+     * etc.) will land here so the wire surface has a single canonical home.
+     */
+    auth?: AuthConfig;
+    /** Storage plugins for cloud storage providers. */
+    storage?: StoragePlugin[];
+    /** Plugins to extend Nextly functionality. */
+    plugins?: PluginDefinition[];
+    /** Security configuration for headers, CORS, uploads, and sanitization. */
+    security?: SecurityConfig;
+    /** Admin UI customization. */
+    admin?: AdminConfig;
+}
+/**
+ * Normalized Nextly configuration with all defaults applied.
+ *
+ * This type represents the config after `sanitizeConfig()` has processed it,
+ * with all array-valued and default-bearing fields filled in.
+ *
+ * Returned by `defineConfig()` and consumed by `getNextly()`, the DI
+ * registration pipeline, and downstream services.
+ */
+interface SanitizedNextlyConfig {
+    /** Array of collection configurations (empty array if none provided). */
+    collections: CollectionConfig[];
+    /** Array of Single configurations (empty array if none provided). */
+    singles: SingleConfig[];
+    /** Array of Component configurations (empty array if none provided). */
+    components: ComponentConfig[];
+    /** User model extension configuration. Undefined if no user config provided. */
+    users?: UserConfig;
+    /** Email provider and template configuration. Undefined if no email config provided. */
+    email?: EmailConfig;
+    /** TypeScript configuration with defaults applied. */
+    typescript: Required<TypeScriptConfig>;
+    /** Database configuration with defaults applied. */
+    db: Required<DatabaseConfig>;
+    /**
+     * Rate limiting configuration.
+     * Built automatically unless `rateLimit: { enabled: false }` is set.
+     */
+    rateLimit?: SanitizedRateLimitingConfig;
+    /**
+     * API key configuration with defaults applied.
+     * Undefined if omitted from defineConfig() (built-in defaults used).
+     */
+    apiKeys?: SanitizedApiKeysConfig;
+    /**
+     * Auth configuration with defaults applied. Always present after
+     * sanitization; the `revealRegistrationConflict` flag falls back to
+     * `false` (silent-success on duplicate email).
+     */
+    auth: SanitizedAuthConfig;
+    /** Storage plugins for cloud storage providers (empty array if none configured). */
+    storage: StoragePlugin[];
+    /** Plugins to extend Nextly functionality (empty array if none configured). */
+    plugins: PluginDefinition[];
+    /** Security configuration for headers, CORS, uploads, and sanitization. */
+    security?: SecurityConfig;
+    /** Admin UI customization config. */
+    admin?: AdminConfig;
+}
+/**
+ * Fill defaults on a raw `NextlyConfig` and return a `SanitizedNextlyConfig`.
+ *
+ * This is a pure transformation — it does **not** validate slug uniqueness,
+ * component nesting depth, or user-field constraints. Callers that need
+ * validation (like `defineConfig()`) should validate first and then call
+ * this helper.
+ *
+ * After this step, downstream code can rely on `collections`, `singles`,
+ * `components`, `storage`, `plugins`, `typescript`, and `db` being present
+ * and nil-check-free.
+ *
+ * Validates that `apiKeys.rateLimit.requestsPerHour` and `apiKeys.rateLimit.windowMs`
+ * are positive, because accepting those values without a bound would silently
+ * disable rate limiting in production.
+ *
+ * @param config - Raw Nextly configuration
+ * @returns Sanitized configuration with defaults applied
+ * @throws Error if `apiKeys.rateLimit` values are invalid
+ */
+declare function sanitizeConfig(config: NextlyConfig): SanitizedNextlyConfig;
+
+export { isServicesRegistered as $, SecurityConfigSchema as F, InMemoryRateLimitStore as I, SecurityHeadersConfigSchema as J, SecurityLimitsConfigSchema as M, UploadSecurityConfigSchema as Q, clearServices as V, createPluginContext as W, createRateLimitHeaders as X, createRateLimiter as Y, definePlugin as Z, getService as _, registerServices as a0, shutdownServices as a1, AdminPlacement as h, AuthRateLimitConfigSchema as j, CollectionService as l, CorsConfigSchema as o, sanitizeConfig as s, SanitizationConfigSchema as z };
+export type { AdminBrandingColors as A, SecurityConfig as B, Collection as C, DatabaseConfig as D, SecurityConfigInput as E, SecurityHeadersConfig as G, SecurityHeadersConfigInput as H, SecurityLimitsConfigInput as K, ListCollectionsOptions as L, NextlyConfig as N, UploadSecurityConfigInput as O, PluginAdminAppearance as P, RateLimitRecord as R, SanitizedNextlyConfig as S, TypeScriptConfig as T, UpdateCollectionInput as U, RateLimitStore as a, RateLimitingConfig as b, SanitizedRateLimitingConfig as c, NextlyServiceConfig as d, ServiceMap as e, AdminBrandingConfig as f, AdminConfig as g, AuthRateLimitConfigInput as i, CollectionEntry as k, CorsConfig as m, CorsConfigInput as n, CreateCollectionInput as p, PluginAdminConfig as q, PluginContext as r, PluginDefinition as t, PluginHookRegistry as u, PluginOverride as v, RateLimitConfig as w, RateLimitResult as x, SanitizationConfigInput as y };