@classytic/arc 1.1.0 → 2.1.2

package/dist/index-B4t03KQ0.d.ts

@@ -1,1366 +0,0 @@
-import { ClientSession, Model, Document, Types } from 'mongoose';
-import { FastifyPluginAsync, FastifyRequest, FastifyReply, RouteHandlerMethod, FastifyInstance } from 'fastify';
-import { U as UserBase, P as PermissionCheck } from './types-B99TBmFV.js';
-
-/**
- * Repository Interface - Database-Agnostic CRUD Operations
- *
- * This is the standard interface that all repositories must implement.
- * MongoKit Repository already implements this interface.
- *
- * @example
- * ```typescript
- * import type { CrudRepository } from '@classytic/arc';
- *
- * // Your repository automatically satisfies this interface
- * const userRepo: CrudRepository<UserDocument> = new Repository(UserModel);
- * ```
- */
-
-/**
- * Query options for read operations
- */
-interface QueryOptions {
-    /** MongoDB session for transactions */
-    session?: ClientSession;
-    /** Field selection - include or exclude fields */
-    select?: string | string[] | Record<string, 0 | 1>;
-    /** Relations to populate - string, array, or Mongoose populate options */
-    populate?: string | string[] | Record<string, unknown>;
-    /** Return plain JS objects instead of Mongoose documents */
-    lean?: boolean;
-    /** Allow additional adapter-specific options */
-    [key: string]: unknown;
-}
-/**
- * Pagination parameters for list operations
- */
-interface PaginationParams<TDoc = unknown> {
-    /** Filter criteria */
-    filters?: Partial<TDoc> & Record<string, unknown>;
-    /** Sort specification - string ("-createdAt") or object ({ createdAt: -1 }) */
-    sort?: string | Record<string, 1 | -1>;
-    /** Page number (1-indexed) */
-    page?: number;
-    /** Items per page */
-    limit?: number;
-    /** Allow additional options (select, populate, etc.) */
-    [key: string]: unknown;
-}
-/**
- * Paginated result from list operations
- */
-interface PaginatedResult<TDoc> {
-    /** Documents for current page */
-    docs: TDoc[];
-    /** Current page number */
-    page: number;
-    /** Items per page */
-    limit: number;
-    /** Total document count */
-    total: number;
-    /** Total page count */
-    pages: number;
-    /** Has next page */
-    hasNext: boolean;
-    /** Has previous page */
-    hasPrev: boolean;
-}
-/**
- * Standard CRUD Repository Interface
- *
- * Defines the contract for data access operations.
- * All database adapters (MongoKit, Prisma, etc.) implement this interface.
- *
- * @typeParam TDoc - The document/entity type
- */
-interface CrudRepository<TDoc> {
-    /**
-     * Get paginated list of documents
-     */
-    getAll(params?: PaginationParams<TDoc>, options?: QueryOptions): Promise<PaginatedResult<TDoc>>;
-    /**
-     * Get single document by ID
-     */
-    getById(id: string, options?: QueryOptions): Promise<TDoc | null>;
-    /**
-     * Create new document
-     */
-    create(data: Partial<TDoc>, options?: {
-        session?: ClientSession;
-        [key: string]: unknown;
-    }): Promise<TDoc>;
-    /**
-     * Update document by ID
-     */
-    update(id: string, data: Partial<TDoc>, options?: QueryOptions): Promise<TDoc | null>;
-    /**
-     * Delete document by ID
-     */
-    delete(id: string, options?: {
-        session?: ClientSession;
-        [key: string]: unknown;
-    }): Promise<{
-        success: boolean;
-        message: string;
-    }>;
-}
-/**
- * Extract document type from a repository
- *
- * @example
- * ```typescript
- * type UserDoc = InferDoc<typeof userRepository>;
- * // UserDoc is now the document type of userRepository
- * ```
- */
-type InferDoc<R> = R extends CrudRepository<infer T> ? T : never;
-
-/**
- * Define a resource with database adapter
- *
- * This is the MAIN entry point for creating Arc resources.
- * The adapter provides both repository and schema metadata.
- */
-declare function defineResource<TDoc = AnyRecord>(config: ResourceConfig<TDoc>): ResourceDefinition<TDoc>;
-interface ResolvedResourceConfig<TDoc = AnyRecord> extends ResourceConfig<TDoc> {
-    _appliedPresets?: string[];
-    _controllerOptions?: {
-        slugField?: string;
-        parentField?: string;
-        [key: string]: unknown;
-    };
-}
-declare class ResourceDefinition<TDoc = AnyRecord> {
-    readonly name: string;
-    readonly displayName: string;
-    readonly tag: string;
-    readonly prefix: string;
-    readonly adapter?: DataAdapter<TDoc>;
-    readonly controller?: IController<TDoc>;
-    readonly schemaOptions: RouteSchemaOptions;
-    readonly customSchemas: CrudSchemas;
-    readonly permissions: ResourcePermissions;
-    readonly additionalRoutes: AdditionalRoute[];
-    readonly middlewares: MiddlewareConfig;
-    readonly disableDefaultRoutes: boolean;
-    readonly disabledRoutes: CrudRouteKey[];
-    readonly organizationScoped: boolean;
-    readonly events: Record<string, EventDefinition>;
-    readonly _appliedPresets: string[];
-    constructor(config: ResolvedResourceConfig<TDoc>);
-    /** Get repository from adapter (if available) */
-    get repository(): RepositoryLike | CrudRepository<TDoc> | undefined;
-    /** Get model from adapter (if available) */
-    get model(): Model<Document> | unknown | undefined;
-    _validateControllerMethods(): void;
-    toPlugin(): FastifyPluginAsync;
-    /**
-     * Get event definitions for registry
-     */
-    getEvents(): Array<{
-        name: string;
-        module: string;
-        schema?: AnyRecord;
-        description?: string;
-    }>;
-    /**
-     * Get resource metadata
-     */
-    getMetadata(): ResourceMetadata;
-}
-
-/**
- * Resource Registry
- *
- * Singleton that tracks all registered resources for introspection.
- */
-
-interface RegisterOptions {
-    module?: string;
-    /** Pre-generated OpenAPI schemas */
-    openApiSchemas?: OpenApiSchemas;
-}
-declare class ResourceRegistry {
-    private _resources;
-    private _frozen;
-    constructor();
-    /**
-     * Register a resource
-     */
-    register(resource: ResourceDefinition<unknown>, options?: RegisterOptions): this;
-    /**
-     * Get resource by name
-     */
-    get(name: string): RegistryEntry | undefined;
-    /**
-     * Get all resources
-     */
-    getAll(): RegistryEntry[];
-    /**
-     * Get resources by module
-     */
-    getByModule(moduleName: string): RegistryEntry[];
-    /**
-     * Get resources by preset
-     */
-    getByPreset(presetName: string): RegistryEntry[];
-    /**
-     * Check if resource exists
-     */
-    has(name: string): boolean;
-    /**
-     * Get registry statistics
-     */
-    getStats(): RegistryStats;
-    /**
-     * Get full introspection data
-     */
-    getIntrospection(): IntrospectionData;
-    /**
-     * Freeze registry (prevent further registrations)
-     */
-    freeze(): void;
-    /**
-     * Check if frozen
-     */
-    isFrozen(): boolean;
-    /**
-     * Unfreeze registry (for testing)
-     */
-    _unfreeze(): void;
-    /**
-     * Clear all resources (for testing)
-     */
-    _clear(): void;
-    /**
-     * Group by key
-     */
-    private _groupBy;
-}
-declare const resourceRegistry: ResourceRegistry;
-
-/**
- * Hook System
- *
- * Lifecycle hooks for resource operations.
- * Allows intercepting and modifying data at various points.
- */
-
-type HookPhase = 'before' | 'after';
-type HookOperation = 'create' | 'update' | 'delete' | 'read' | 'list';
-interface HookContext<T = AnyRecord> {
-    resource: string;
-    operation: HookOperation;
-    phase: HookPhase;
-    data?: T;
-    result?: T | T[];
-    user?: UserBase;
-    context?: RequestContext;
-    meta?: AnyRecord;
-}
-type HookHandler<T = AnyRecord> = (ctx: HookContext<T>) => void | Promise<void> | T | Promise<T>;
-interface HookRegistration {
-    resource: string;
-    operation: HookOperation;
-    phase: HookPhase;
-    handler: HookHandler;
-    priority: number;
-}
-interface HookSystemOptions {
-    /** Custom logger for error reporting. Defaults to console.error */
-    logger?: {
-        error: (message: string, ...args: unknown[]) => void;
-    };
-}
-declare class HookSystem {
-    private hooks;
-    private logger;
-    constructor(options?: HookSystemOptions);
-    /**
-     * Generate hook key
-     */
-    private getKey;
-    /**
-     * Register a hook
-     * Supports both object parameter and positional arguments
-     */
-    register<T = AnyRecord>(resourceOrOptions: string | {
-        resource: string;
-        operation: HookOperation;
-        phase: HookPhase;
-        handler: HookHandler<T>;
-        priority?: number;
-    }, operation?: HookOperation, phase?: HookPhase, handler?: HookHandler<T>, priority?: number): () => void;
-    /**
-     * Register before hook
-     */
-    before<T = AnyRecord>(resource: string, operation: HookOperation, handler: HookHandler<T>, priority?: number): () => void;
-    /**
-     * Register after hook
-     */
-    after<T = AnyRecord>(resource: string, operation: HookOperation, handler: HookHandler<T>, priority?: number): () => void;
-    /**
-     * Execute hooks for a given context
-     */
-    execute<T = AnyRecord>(ctx: HookContext<T>): Promise<T | undefined>;
-    /**
-     * Execute before hooks
-     */
-    executeBefore<T = AnyRecord>(resource: string, operation: HookOperation, data: T, options?: {
-        user?: UserBase;
-        context?: RequestContext;
-        meta?: AnyRecord;
-    }): Promise<T>;
-    /**
-     * Execute after hooks
-     * Errors in after hooks are logged but don't fail the request
-     */
-    executeAfter<T = AnyRecord>(resource: string, operation: HookOperation, result: T | T[], options?: {
-        user?: UserBase;
-        context?: RequestContext;
-        meta?: AnyRecord;
-    }): Promise<void>;
-    /**
-     * Get all registered hooks
-     */
-    getAll(): HookRegistration[];
-    /**
-     * Get hooks for a specific resource
-     */
-    getForResource(resource: string): HookRegistration[];
-    /**
-     * Clear all hooks
-     */
-    clear(): void;
-    /**
-     * Clear hooks for a specific resource
-     */
-    clearResource(resource: string): void;
-}
-/**
- * Create a new isolated HookSystem instance
- *
- * Use this for:
- * - Test isolation (parallel test suites)
- * - Multiple app instances with independent hooks
- *
- * @example
- * const hooks = createHookSystem();
- * await app.register(arcCorePlugin, { hookSystem: hooks });
- *
- * @example With custom logger
- * const hooks = createHookSystem({ logger: fastify.log });
- */
-declare function createHookSystem(options?: HookSystemOptions): HookSystem;
-declare const hookSystem: HookSystem;
-/**
- * Register a before create hook
- */
-declare function beforeCreate<T = AnyRecord>(resource: string, handler: HookHandler<T>, priority?: number): () => void;
-/**
- * Register an after create hook
- */
-declare function afterCreate<T = AnyRecord>(resource: string, handler: HookHandler<T>, priority?: number): () => void;
-/**
- * Register a before update hook
- */
-declare function beforeUpdate<T = AnyRecord>(resource: string, handler: HookHandler<T>, priority?: number): () => void;
-/**
- * Register an after update hook
- */
-declare function afterUpdate<T = AnyRecord>(resource: string, handler: HookHandler<T>, priority?: number): () => void;
-/**
- * Register a before delete hook
- */
-declare function beforeDelete<T = AnyRecord>(resource: string, handler: HookHandler<T>, priority?: number): () => void;
-/**
- * Register an after delete hook
- */
-declare function afterDelete<T = AnyRecord>(resource: string, handler: HookHandler<T>, priority?: number): () => void;
-
-/**
- * Handler Types - Controller and Route Handler Definitions
- *
- * Two handler patterns supported:
- * 1. ControllerHandler - Arc's standard pattern (receives context object)
- * 2. FastifyHandler - Fastify native pattern (receives request, reply)
- *
- * Use `wrapHandler: true` for ControllerHandler, `wrapHandler: false` for FastifyHandler.
- */
-
-/**
- * Request context passed to controller handlers
- */
-interface IRequestContext {
-    /** Route parameters (e.g., { id: '123' }) */
-    params: Record<string, string>;
-    /** Query string parameters */
-    query: Record<string, unknown>;
-    /** Request body */
-    body: unknown;
-    /** Authenticated user or null */
-    user: UserBase | null;
-    /** Request headers */
-    headers: Record<string, string | undefined>;
-    /** Organization ID (for multi-tenant apps) */
-    organizationId?: string;
-    /** Additional metadata and custom fields */
-    metadata?: Record<string, unknown>;
-}
-/**
- * Standard response from controller handlers
- */
-interface IControllerResponse<T = unknown> {
-    /** Operation success status */
-    success: boolean;
-    /** Response data */
-    data?: T;
-    /** Error message (when success is false) */
-    error?: string;
-    /** HTTP status code (default: 200 for success, 400 for error) */
-    status?: number;
-    /** Additional metadata */
-    meta?: Record<string, unknown>;
-    /** Error details (for debugging) */
-    details?: Record<string, unknown>;
-}
-/**
- * Controller handler - Arc's standard pattern
- *
- * Receives a request context object, returns IControllerResponse.
- * Use with `wrapHandler: true` in additionalRoutes.
- *
- * @example
- * ```typescript
- * const createProduct: ControllerHandler<Product> = async (req) => {
- *   const product = await productRepo.create(req.body);
- *   return { success: true, data: product, status: 201 };
- * };
- *
- * additionalRoutes: [{
- *   method: 'POST',
- *   path: '/products',
- *   handler: createProduct,
- *   permissions: requireAuth(),
- *   wrapHandler: true,  // Arc wraps this into Fastify handler
- * }]
- * ```
- */
-type ControllerHandler<T = unknown> = (req: IRequestContext) => Promise<IControllerResponse<T>>;
-/**
- * Fastify native handler
- *
- * Standard Fastify request/reply pattern.
- * Use with `wrapHandler: false` in additionalRoutes.
- *
- * @example
- * ```typescript
- * const downloadFile: FastifyHandler = async (request, reply) => {
- *   const file = await getFile(request.params.id);
- *   reply.header('Content-Type', file.mimeType);
- *   return reply.send(file.buffer);
- * };
- *
- * additionalRoutes: [{
- *   method: 'GET',
- *   path: '/files/:id/download',
- *   handler: downloadFile,
- *   permissions: requireAuth(),
- *   wrapHandler: false,  // Use as-is, no wrapping
- * }]
- * ```
- */
-type FastifyHandler = (request: FastifyRequest, reply: FastifyReply) => Promise<void> | void;
-/**
- * Union type for route handlers
- */
-type RouteHandler = ControllerHandler | FastifyHandler;
-/**
- * Controller interface for CRUD operations (strict)
- */
-interface IController<TDoc = unknown> {
-    list(req: IRequestContext): Promise<IControllerResponse<{
-        docs: TDoc[];
-        total: number;
-    }>>;
-    get(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
-    create(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
-    update(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
-    delete(req: IRequestContext): Promise<IControllerResponse<{
-        message: string;
-    }>>;
-}
-/**
- * Flexible controller interface - accepts controllers with any handler style
- * Use this when your controller uses Fastify native handlers
- */
-interface ControllerLike {
-    list?: unknown;
-    get?: unknown;
-    create?: unknown;
-    update?: unknown;
-    delete?: unknown;
-    [key: string]: unknown;
-}
-
-type AnyRecord = Record<string, unknown>;
-type ObjectId = Types.ObjectId | string;
-/**
- * Flexible user type that accepts any object with id/ID properties.
- * Use this instead of `any` when dealing with user objects.
- * Re-exports UserBase from permissions module for convenience.
- * The actual user structure is defined by your app's auth system.
- */
-type UserLike = UserBase & {
-    /** User email (optional) */
-    email?: string;
-};
-/**
- * Extract user ID from a user object (supports both id and _id)
- */
-declare function getUserId(user: UserLike | null | undefined): string | undefined;
-
-type CrudController<TDoc> = IController<TDoc>;
-interface ApiResponse<T = unknown> {
-    success: boolean;
-    data?: T;
-    error?: string;
-    message?: string;
-    meta?: Record<string, unknown>;
-}
-interface UserOrganization {
-    userId: string;
-    organizationId: string;
-    [key: string]: unknown;
-}
-interface JWTPayload {
-    sub: string;
-    [key: string]: unknown;
-}
-interface RequestContext {
-    operation?: string;
-    user?: unknown;
-    organizationId?: string;
-    filters?: Record<string, unknown>;
-    [key: string]: unknown;
-}
-/**
- * Controller-level query options - parsed from request query string
- * Includes pagination, filtering, and context data
- */
-interface ControllerQueryOptions {
-    page?: number;
-    limit?: number;
-    sort?: string | Record<string, 1 | -1>;
-    /** Simple populate (comma-separated string or array) */
-    populate?: string | string[] | Record<string, unknown>;
-    /**
-     * Advanced populate options (Mongoose-compatible)
-     * When set, takes precedence over simple `populate`
-     */
-    populateOptions?: PopulateOption[];
-    select?: string | string[] | Record<string, 0 | 1>;
-    filters?: Record<string, unknown>;
-    search?: string;
-    lean?: boolean;
-    after?: string;
-    user?: unknown;
-    organizationId?: string;
-    context?: Record<string, unknown>;
-    /** Allow additional options */
-    [key: string]: unknown;
-}
-/**
- * Mongoose-compatible populate option for advanced field selection
- * Used when you need to select specific fields from populated documents
- *
- * @example
- * ```typescript
- * // URL: ?populate[author][select]=name,email
- * // Generates: { path: 'author', select: 'name email' }
- * ```
- */
-interface PopulateOption {
-    /** Field path to populate */
-    path: string;
-    /** Fields to select (space-separated) */
-    select?: string;
-    /** Filter conditions for populated documents */
-    match?: Record<string, unknown>;
-    /** Query options (limit, sort, skip) */
-    options?: {
-        limit?: number;
-        sort?: Record<string, 1 | -1>;
-        skip?: number;
-    };
-    /** Nested populate configuration */
-    populate?: PopulateOption;
-}
-/**
- * Parsed query result from QueryParser
- * Includes pagination, sorting, filtering, etc.
- *
- * The index signature allows custom query parsers (like MongoKit's QueryParser)
- * to add additional fields without breaking Arc's type system.
- */
-interface ParsedQuery {
-    filters?: Record<string, unknown>;
-    limit?: number;
-    sort?: string | Record<string, 1 | -1>;
-    /** Simple populate (comma-separated string or array) */
-    populate?: string | string[] | Record<string, unknown>;
-    /**
-     * Advanced populate options (Mongoose-compatible)
-     * When set, takes precedence over simple `populate`
-     * @example [{ path: 'author', select: 'name email' }]
-     */
-    populateOptions?: PopulateOption[];
-    search?: string;
-    page?: number;
-    after?: string;
-    select?: string | string[] | Record<string, 0 | 1>;
-    /** Allow additional fields from custom query parsers */
-    [key: string]: unknown;
-}
-/**
- * Query Parser Interface
- * Implement this to create custom query parsers
- *
- * @example MongoKit QueryParser
- * ```typescript
- * import { QueryParser } from '@classytic/mongokit';
- * const queryParser = new QueryParser();
- * ```
- */
-interface QueryParserInterface {
-    parse(query: Record<string, unknown> | null | undefined): ParsedQuery;
-    /**
-     * Optional: Export OpenAPI schema for query parameters
-     * Use this to document query parameters in OpenAPI/Swagger
-     */
-    getQuerySchema?(): {
-        type: 'object';
-        properties: Record<string, unknown>;
-        required?: string[];
-    };
-}
-interface FastifyRequestExtras {
-    user?: unknown;
-    organizationId?: string;
-}
-interface RequestWithExtras extends Omit<FastifyRequest, 'user'> {
-    /**
-     * Arc metadata - set by createCrudRouter
-     * Contains resource configuration and schema options
-     */
-    arc?: {
-        resourceName?: string;
-        schemaOptions?: RouteSchemaOptions;
-        permissions?: ResourcePermissions;
-    };
-    user?: unknown;
-    organizationId?: string;
-    context?: Record<string, unknown>;
-    _policyFilters?: Record<string, unknown>;
-    fieldMask?: string[];
-    _ownershipCheck?: Record<string, unknown>;
-}
-type FastifyWithAuth = FastifyInstance & {
-    authenticate: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
-};
-/**
- * Arc core decorator interface
- * Added by arcCorePlugin to provide instance-scoped hooks and registry
- */
-interface ArcDecorator {
-    /** Instance-scoped hook system */
-    hooks: HookSystem;
-    /** Instance-scoped resource registry */
-    registry: ResourceRegistry;
-    /** Whether event emission is enabled */
-    emitEvents: boolean;
-}
-/**
- * Events decorator interface
- * Added by eventPlugin to provide event pub/sub
- */
-interface EventsDecorator {
-    /** Publish an event */
-    publish: <T>(type: string, payload: T, meta?: Partial<{
-        id: string;
-        timestamp: Date;
-    }>) => Promise<void>;
-    /** Subscribe to events */
-    subscribe: (pattern: string, handler: (event: unknown) => void | Promise<void>) => Promise<() => void>;
-    /** Get transport name */
-    transportName: string;
-}
-/**
- * Fastify instance with Arc decorators
- * Arc adds these decorators via plugins/presets
- */
-type FastifyWithDecorators = FastifyInstance & {
-    arc?: ArcDecorator;
-    events?: EventsDecorator;
-    authenticate?: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
-    organizationScoped?: (options?: {
-        required?: boolean;
-    }) => RouteHandlerMethod;
-    [key: string]: unknown;
-};
-interface OwnershipCheck {
-    field: string;
-    userField?: string;
-}
-
-interface ResourceConfig<TDoc = AnyRecord> {
-    name: string;
-    displayName?: string;
-    tag?: string;
-    prefix?: string;
-    adapter?: DataAdapter<TDoc>;
-    /** Controller instance - accepts any object with CRUD methods */
-    controller?: IController<TDoc> | ControllerLike | Record<string, any> | object;
-    queryParser?: unknown;
-    permissions?: ResourcePermissions;
-    schemaOptions?: RouteSchemaOptions;
-    openApiSchemas?: OpenApiSchemas;
-    customSchemas?: Partial<CrudSchemas>;
-    presets?: Array<string | PresetResult | {
-        name: string;
-        [key: string]: unknown;
-    }>;
-    hooks?: ResourceHooks;
-    middlewares?: MiddlewareConfig;
-    additionalRoutes?: AdditionalRoute[];
-    disableCrud?: boolean;
-    disableDefaultRoutes?: boolean;
-    disabledRoutes?: CrudRouteKey[];
-    organizationScoped?: boolean;
-    module?: string;
-    events?: Record<string, EventDefinition>;
-    skipValidation?: boolean;
-    skipRegistry?: boolean;
-    _appliedPresets?: string[];
-}
-/**
- * Resource-level permissions
- * ONLY PermissionCheck functions allowed - no string arrays
- */
-interface ResourcePermissions {
-    list?: PermissionCheck;
-    get?: PermissionCheck;
-    create?: PermissionCheck;
-    update?: PermissionCheck;
-    delete?: PermissionCheck;
-}
-interface ResourceHooks {
-    beforeCreate?: (data: AnyRecord) => Promise<AnyRecord> | AnyRecord;
-    afterCreate?: (doc: AnyRecord) => Promise<void> | void;
-    beforeUpdate?: (id: string, data: AnyRecord) => Promise<AnyRecord> | AnyRecord;
-    afterUpdate?: (doc: AnyRecord) => Promise<void> | void;
-    beforeDelete?: (id: string) => Promise<void> | void;
-    afterDelete?: (id: string) => Promise<void> | void;
-}
-/**
- * Additional route definition for custom endpoints
- */
-interface AdditionalRoute {
-    /** HTTP method */
-    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-    /** Route path (relative to resource prefix) */
-    path: string;
-    /**
-     * Handler - string (controller method name) or function
-     * Function can be Fastify handler or any (request, reply) => Promise<any>
-     */
-    handler: string | RouteHandlerMethod | ((request: any, reply: any) => any);
-    /** Permission check - REQUIRED */
-    permissions: PermissionCheck;
-    /**
-     * Handler type - REQUIRED, no auto-detection
-     * true = ControllerHandler (receives context object)
-     * false = FastifyHandler (receives request, reply)
-     */
-    wrapHandler: boolean;
-    /** OpenAPI summary */
-    summary?: string;
-    /** OpenAPI description */
-    description?: string;
-    /** OpenAPI tags */
-    tags?: string[];
-    /**
-     * Custom route-level middleware
-     * Can be an array of handlers or a function that receives fastify and returns handlers
-     * @example
-     * // Direct array
-     * preHandler: [myMiddleware]
-     * // Function that receives fastify (for accessing decorators)
-     * preHandler: (fastify) => [fastify.customerContext({ required: true })]
-     */
-    preHandler?: RouteHandlerMethod[] | ((fastify: any) => RouteHandlerMethod[]);
-    /** Fastify route schema */
-    schema?: Record<string, unknown>;
-}
-interface RouteSchemaOptions {
-    hiddenFields?: string[];
-    readonlyFields?: string[];
-    requiredFields?: string[];
-    optionalFields?: string[];
-    excludeFields?: string[];
-    fieldRules?: Record<string, {
-        systemManaged?: boolean;
-        [key: string]: unknown;
-    }>;
-    query?: Record<string, unknown>;
-}
-interface FieldRule {
-    field: string;
-    required?: boolean;
-    readonly?: boolean;
-    hidden?: boolean;
-}
-/**
- * CRUD Route Schemas (Fastify Native Format)
- *
- * @example
- * {
- *   list: {
- *     querystring: { type: 'object', properties: { page: { type: 'number' } } },
- *     response: { 200: { type: 'object', properties: { docs: { type: 'array' } } } }
- *   },
- *   create: {
- *     body: { type: 'object', properties: { name: { type: 'string' } } },
- *     response: { 201: { type: 'object' } }
- *   }
- * }
- */
-interface CrudSchemas {
-    /** GET / - List all resources */
-    list?: {
-        querystring?: Record<string, unknown>;
-        response?: Record<number, unknown>;
-        [key: string]: unknown;
-    };
-    /** GET /:id - Get single resource */
-    get?: {
-        params?: Record<string, unknown>;
-        response?: Record<number, unknown>;
-        [key: string]: unknown;
-    };
-    /** POST / - Create resource */
-    create?: {
-        body?: Record<string, unknown>;
-        response?: Record<number, unknown>;
-        [key: string]: unknown;
-    };
-    /** PATCH /:id - Update resource */
-    update?: {
-        params?: Record<string, unknown>;
-        body?: Record<string, unknown>;
-        response?: Record<number, unknown>;
-        [key: string]: unknown;
-    };
-    /** DELETE /:id - Delete resource */
-    delete?: {
-        params?: Record<string, unknown>;
-        response?: Record<number, unknown>;
-        [key: string]: unknown;
-    };
-    [key: string]: unknown;
-}
-interface OpenApiSchemas {
-    entity?: unknown;
-    createBody?: unknown;
-    updateBody?: unknown;
-    params?: unknown;
-    listQuery?: unknown;
-    /**
-     * Explicit response schema for OpenAPI documentation.
-     * If provided, this will be used as-is for the response schema.
-     * If not provided, response schema is auto-generated from createBody.
-     *
-     * Note: This is for OpenAPI docs only - does NOT affect Fastify serialization.
-     *
-     * @example
-     * response: {
-     *   type: 'object',
-     *   properties: {
-     *     _id: { type: 'string' },
-     *     name: { type: 'string' },
-     *     email: { type: 'string' },
-     *     // Exclude password, include virtuals
-     *     fullName: { type: 'string' },
-     *   }
-     * }
-     */
-    response?: unknown;
-    [key: string]: unknown;
-}
-/** Handler for middleware functions */
-type MiddlewareHandler = (request: RequestWithExtras, reply: FastifyReply) => Promise<unknown>;
-type CrudRouteKey = 'list' | 'get' | 'create' | 'update' | 'delete';
-interface MiddlewareConfig {
-    list?: MiddlewareHandler[];
-    get?: MiddlewareHandler[];
-    create?: MiddlewareHandler[];
-    update?: MiddlewareHandler[];
-    delete?: MiddlewareHandler[];
-    [key: string]: MiddlewareHandler[] | undefined;
-}
-/**
- * JWT utilities provided to authenticator
- * Arc provides these helpers, app uses them as needed
- */
-interface JwtContext {
-    /** Verify a JWT token and return decoded payload */
-    verify: <T = Record<string, unknown>>(token: string) => T;
-    /** Sign a payload and return JWT token */
-    sign: (payload: Record<string, unknown>, options?: {
-        expiresIn?: string;
-    }) => string;
-    /** Decode without verification (for inspection) */
-    decode: <T = Record<string, unknown>>(token: string) => T | null;
-}
-/**
- * Context passed to app's authenticator function
- */
-interface AuthenticatorContext {
-    /** JWT utilities (available if jwt.secret provided) */
-    jwt: JwtContext | null;
-    /** Fastify instance for advanced use cases */
-    fastify: FastifyInstance;
-}
-/**
- * App-provided authenticator function
- *
- * Arc calls this for every non-public route.
- * App has FULL control over authentication logic.
- *
- * @example
- * ```typescript
- * // Simple JWT auth
- * authenticate: async (request, { jwt }) => {
- *   const token = request.headers.authorization?.split(' ')[1];
- *   if (!token || !jwt) return null;
- *   const decoded = jwt.verify(token);
- *   return userRepo.findById(decoded.id);
- * }
- *
- * // Multi-strategy (JWT + API Key)
- * authenticate: async (request, { jwt }) => {
- *   const apiKey = request.headers['x-api-key'];
- *   if (apiKey) {
- *     const result = await apiKeyService.verify(apiKey);
- *     if (result) return { _id: result.userId, isApiKey: true };
- *   }
- *   const token = request.headers.authorization?.split(' ')[1];
- *   if (token && jwt) {
- *     const decoded = jwt.verify(token);
- *     return userRepo.findById(decoded.id);
- *   }
- *   return null;
- * }
- * ```
- */
-type Authenticator = (request: FastifyRequest, context: AuthenticatorContext) => Promise<any | null> | any | null;
-/**
- * Token pair returned by issueTokens helper
- */
-interface TokenPair {
-    /** Access token (JWT) */
-    accessToken: string;
-    /** Refresh token (JWT with longer expiry) */
-    refreshToken?: string;
-    /** Access token expiry in seconds */
-    expiresIn: number;
-    /** Refresh token expiry in seconds */
-    refreshExpiresIn?: number;
-    /** Token type (always 'Bearer') */
-    tokenType: 'Bearer';
-}
-/**
- * Auth helpers available on fastify.auth
- *
- * @example
- * ```typescript
- * // In login handler
- * const user = await userRepo.findByEmail(email);
- * if (!user || !await bcrypt.compare(password, user.password)) {
- *   return reply.code(401).send({ error: 'Invalid credentials' });
- * }
- *
- * const tokens = fastify.auth.issueTokens({
- *   id: user._id,
- *   email: user.email,
- *   roles: user.roles,
- * });
- *
- * return { success: true, ...tokens, user };
- * ```
- */
-interface AuthHelpers {
-    /** JWT utilities (if configured) */
-    jwt: JwtContext | null;
-    /**
-     * Issue access + refresh tokens for a user
-     * App calls this after validating credentials
-     */
-    issueTokens: (payload: Record<string, unknown>, options?: {
-        expiresIn?: string;
-        refreshExpiresIn?: string;
-    }) => TokenPair;
-    /**
-     * Verify a refresh token and return decoded payload
-     */
-    verifyRefreshToken: <T = Record<string, unknown>>(token: string) => T;
-}
-interface ServiceContext {
-    user?: unknown;
-    organizationId?: string;
-    requestId?: string;
-    select?: string[] | Record<string, 0 | 1>;
-    populate?: string | string[];
-    lean?: boolean;
-}
-interface PresetHook {
-    operation: 'create' | 'update' | 'delete' | 'read' | 'list';
-    phase: 'before' | 'after';
-    handler: (ctx: any) => void | Promise<void> | AnyRecord | Promise<AnyRecord>;
-    priority?: number;
-}
-interface PresetResult {
-    name: string;
-    additionalRoutes?: AdditionalRoute[] | ((permissions: ResourcePermissions) => AdditionalRoute[]);
-    middlewares?: MiddlewareConfig;
-    schemaOptions?: RouteSchemaOptions;
-    controllerOptions?: Record<string, unknown>;
-    hooks?: PresetHook[];
-}
-type PresetFunction = (config: ResourceConfig) => PresetResult;
-interface GracefulShutdownOptions {
-    timeout?: number;
-    onShutdown?: () => Promise<void> | void;
-    signals?: NodeJS.Signals[];
-    logEvents?: boolean;
-}
-interface RequestIdOptions {
-    headerName?: string;
-    generator?: () => string;
-}
-interface HealthOptions {
-    path?: string;
-    check?: () => Promise<any>;
-}
-interface HealthCheck {
-    healthy: boolean;
-    timestamp: string;
-    [key: string]: unknown;
-}
-/**
- * Auth Plugin Options - Clean, Minimal Configuration
- *
- * Arc provides JWT infrastructure and calls your authenticator.
- * You control ALL authentication logic.
- *
- * @example
- * ```typescript
- * // Minimal: just JWT (uses default jwtVerify)
- * auth: {
- *   jwt: { secret: process.env.JWT_SECRET },
- * }
- *
- * // With custom authenticator (recommended)
- * auth: {
- *   jwt: { secret: process.env.JWT_SECRET },
- *   authenticate: async (request, { jwt }) => {
- *     const token = request.headers.authorization?.split(' ')[1];
- *     if (!token) return null;
- *     const decoded = jwt.verify(token);
- *     return userRepo.findById(decoded.id);
- *   },
- * }
- *
- * // Multi-strategy (JWT + API Key)
- * auth: {
- *   jwt: { secret: process.env.JWT_SECRET },
- *   authenticate: async (request, { jwt }) => {
- *     // Try API key first (faster)
- *     const apiKey = request.headers['x-api-key'];
- *     if (apiKey) {
- *       const result = await apiKeyService.verify(apiKey);
- *       if (result) return { _id: result.userId, isApiKey: true };
- *     }
- *     // Try JWT
- *     const token = request.headers.authorization?.split(' ')[1];
- *     if (token) {
- *       const decoded = jwt.verify(token);
- *       return userRepo.findById(decoded.id);
- *     }
- *     return null;
- *   },
- *   onFailure: (request, reply) => {
- *     reply.code(401).send({
- *       success: false,
- *       error: 'Authentication required',
- *       message: 'Use Bearer token or X-API-Key header',
- *     });
- *   },
- * }
- * ```
- */
-interface AuthPluginOptions {
-    /**
-     * JWT configuration (optional but recommended)
-     * If provided, jwt utilities are available in authenticator context
-     */
-    jwt?: {
-        /** JWT secret (required for JWT features) */
-        secret: string;
-        /** Access token expiry (default: '15m') */
-        expiresIn?: string;
-        /** Refresh token secret (defaults to main secret) */
-        refreshSecret?: string;
-        /** Refresh token expiry (default: '7d') */
-        refreshExpiresIn?: string;
-        /** Additional @fastify/jwt sign options */
-        sign?: Record<string, unknown>;
-        /** Additional @fastify/jwt verify options */
-        verify?: Record<string, unknown>;
-    };
-    /**
-     * Custom authenticator function (recommended)
-     *
-     * Arc calls this for non-public routes.
-     * Return user object to authenticate, null/undefined to reject.
-     *
-     * If not provided and jwt.secret is set, uses default jwtVerify.
-     */
-    authenticate?: Authenticator;
-    /**
-     * Custom auth failure handler
-     * Customize the 401 response when authentication fails
-     */
-    onFailure?: (request: FastifyRequest, reply: FastifyReply, error?: Error) => void | Promise<void>;
-    /**
-     * Property name to store user on request (default: 'user')
-     */
-    userProperty?: string;
-}
-interface OrgScopeOptions {
-    enabled?: boolean;
-    header?: string;
-    headerName?: string;
-    queryParam?: string;
-    bypassRoles?: string[];
-    userOrgsPath?: string;
-    validateMembership?: (user: unknown, orgId: string) => Promise<boolean> | boolean;
-}
-interface IntrospectionPluginOptions {
-    path?: string;
-    prefix?: string;
-    enabled?: boolean;
-    authRoles?: string[];
-}
-interface CrudRouterOptions {
-    /** Route prefix */
-    prefix?: string;
-    /** Permission checks for CRUD operations */
-    permissions?: ResourcePermissions;
-    /** OpenAPI tag for grouping routes */
-    tag?: string;
-    /** JSON schemas for CRUD operations */
-    schemas?: Partial<CrudSchemas>;
-    /** Middlewares for each CRUD operation */
-    middlewares?: MiddlewareConfig;
-    /** Additional custom routes (from presets or user-defined) */
-    additionalRoutes?: AdditionalRoute[];
-    /** Disable all default CRUD routes */
-    disableDefaultRoutes?: boolean;
-    /** Disable specific CRUD routes */
-    disabledRoutes?: CrudRouteKey[];
-    /** Enable organization-scoped filtering */
-    organizationScoped?: boolean;
-    /** Resource name for lifecycle hooks */
-    resourceName?: string;
-    /** Schema generation options */
-    schemaOptions?: RouteSchemaOptions;
-}
-interface ResourceMetadata {
-    name: string;
-    displayName?: string;
-    tag?: string;
-    prefix: string;
-    module?: string;
-    permissions?: ResourcePermissions;
-    presets: string[];
-    additionalRoutes?: AdditionalRoute[];
-    routes: Array<{
-        method: string;
-        path: string;
-        handler?: string;
-        operation?: string;
-        summary?: string;
-    }>;
-    events?: string[];
-}
-interface RegistryEntry extends ResourceMetadata {
-    plugin: unknown;
-    adapter?: {
-        type: string;
-        name: string;
-    } | null;
-    events?: string[];
-    disableDefaultRoutes?: boolean;
-    openApiSchemas?: OpenApiSchemas;
-    registeredAt?: string;
-}
-interface RegistryStats {
-    total?: number;
-    totalResources: number;
-    byTag?: Record<string, number>;
-    byModule?: Record<string, number>;
-    presetUsage?: Record<string, number>;
-    totalRoutes?: number;
-    totalEvents?: number;
-}
-interface IntrospectionData {
-    resources: ResourceMetadata[];
-    stats: RegistryStats;
-    generatedAt?: string;
-}
-interface EventDefinition {
-    name: string;
-    handler: (data: unknown) => Promise<void> | void;
-    schema?: Record<string, unknown>;
-    description?: string;
-}
-interface ConfigError {
-    field: string;
-    message: string;
-    code?: string;
-}
-interface ValidationResult$1 {
-    valid: boolean;
-    errors: ConfigError[];
-}
-interface ValidateOptions {
-    strict?: boolean;
-}
-
-/**
- * Infer document type from DataAdapter or ResourceConfig
- */
-type InferDocType<T> = T extends DataAdapter<infer D> ? D : T extends ResourceConfig<infer D> ? D : never;
-type InferResourceDoc<T> = T extends ResourceConfig<infer D> ? D : never;
-type TypedResourceConfig<TDoc> = ResourceConfig<TDoc>;
-type TypedController<TDoc> = IController<TDoc>;
-type TypedRepository<TDoc> = CrudRepository<TDoc>;
-interface BaseControllerOptions {
-    /** Query parser instance */
-    queryParser: QueryParserInterface;
-    /** Schema generation options */
-    schemaOptions?: RouteSchemaOptions;
-    /** Maximum items per page */
-    maxLimit?: number;
-    /** Default items per page */
-    defaultLimit?: number;
-    /** Default sort field */
-    defaultSort?: string;
-    /** Resource name for hooks */
-    resourceName?: string;
-    /** Disable event emission */
-    disableEvents?: boolean;
-}
-
-/**
- * Data Adapter Interface - Database Abstraction Layer
- *
- * Core abstraction that allows Arc to work with any database.
- * This is the ONLY contract between Arc and data persistence.
- */
-
-/**
- * Minimal repository interface for flexible adapter compatibility
- * Accepts any object with CRUD method names
- */
-interface RepositoryLike {
-    getAll: unknown;
-    getById: unknown;
-    create: unknown;
-    update: unknown;
-    delete: unknown;
-    [key: string]: unknown;
-}
-interface DataAdapter<TDoc = unknown> {
-    /**
-     * Repository implementing CRUD operations
-     * Accepts CrudRepository, MongoKit Repository, or any compatible object
-     */
-    repository: CrudRepository<TDoc> | RepositoryLike;
-    /** Adapter identifier for introspection */
-    readonly type: 'mongoose' | 'prisma' | 'drizzle' | 'typeorm' | 'custom';
-    /** Human-readable name */
-    readonly name: string;
-    /**
-     * Generate OpenAPI schemas for CRUD operations
-     *
-     * This method allows each adapter to generate schemas specific to its ORM/database.
-     * For example, Mongoose adapter can use mongokit to generate schemas from Mongoose models.
-     *
-     * @param options - Schema generation options (field rules, populate settings, etc.)
-     * @returns OpenAPI schemas for CRUD operations or null if not supported
-     */
-    generateSchemas?(options?: RouteSchemaOptions): OpenApiSchemas | null;
-    /** Extract schema metadata for OpenAPI/introspection */
-    getSchemaMetadata?(): SchemaMetadata | null;
-    /** Validate data against schema before persistence */
-    validate?(data: unknown): Promise<ValidationResult> | ValidationResult;
-    /** Health check for database connection */
-    healthCheck?(): Promise<boolean>;
-    /** Close/cleanup resources */
-    close?(): Promise<void>;
-}
-interface SchemaMetadata {
-    name: string;
-    fields: Record<string, FieldMetadata>;
-    indexes?: Array<{
-        fields: string[];
-        unique?: boolean;
-        sparse?: boolean;
-    }>;
-    relations?: Record<string, RelationMetadata>;
-}
-interface FieldMetadata {
-    type: 'string' | 'number' | 'boolean' | 'date' | 'object' | 'array' | 'objectId' | 'enum';
-    required?: boolean;
-    unique?: boolean;
-    default?: unknown;
-    enum?: Array<string | number>;
-    min?: number;
-    max?: number;
-    minLength?: number;
-    maxLength?: number;
-    pattern?: string;
-    description?: string;
-    ref?: string;
-    array?: boolean;
-}
-interface RelationMetadata {
-    type: 'one-to-one' | 'one-to-many' | 'many-to-many';
-    target: string;
-    foreignKey?: string;
-    through?: string;
-}
-interface ValidationResult {
-    valid: boolean;
-    errors?: Array<{
-        field: string;
-        message: string;
-        code?: string;
-    }>;
-}
-type AdapterFactory<TDoc> = (config: unknown) => DataAdapter<TDoc>;
-
-export { type InferDocType as $, type AnyRecord as A, type CrudController as B, type ControllerQueryOptions as C, type DataAdapter as D, type FieldRule as E, type FieldMetadata as F, type CrudSchemas as G, HookSystem as H, type IController as I, type JWTPayload as J, type AdditionalRoute as K, type PresetFunction as L, type MiddlewareConfig as M, type EventDefinition as N, type OwnershipCheck as O, type PaginatedResult as P, type QueryParserInterface as Q, type RouteSchemaOptions as R, type ServiceContext as S, type ResourceMetadata as T, type UserOrganization as U, type ValidationResult as V, type RegistryEntry as W, type RegistryStats as X, type IntrospectionData as Y, type OrgScopeOptions as Z, type CrudRouterOptions as _, type IRequestContext as a, type InferResourceDoc as a0, type TypedResourceConfig as a1, type TypedController as a2, type TypedRepository as a3, type ConfigError as a4, type ValidationResult$1 as a5, type ValidateOptions as a6, type HealthCheck as a7, type HealthOptions as a8, type GracefulShutdownOptions as a9, createHookSystem as aA, beforeCreate as aB, afterCreate as aC, beforeUpdate as aD, afterUpdate as aE, beforeDelete as aF, afterDelete as aG, type HookPhase as aH, type HookOperation as aI, type HookRegistration as aJ, type HookSystemOptions as aK, type RequestIdOptions as aa, hookSystem as ab, type HookContext as ac, type HookHandler as ad, type ParsedQuery as ae, type OpenApiSchemas as af, type AdapterFactory as ag, type ObjectId as ah, type UserLike as ai, getUserId as aj, type PopulateOption as ak, type ArcDecorator as al, type EventsDecorator as am, type ResourcePermissions as an, type ResourceHooks as ao, type MiddlewareHandler as ap, type JwtContext as aq, type AuthenticatorContext as ar, type Authenticator as as, type TokenPair as at, type PresetHook as au, type BaseControllerOptions as av, type PaginationParams as aw, type InferDoc as ax, type ControllerHandler as ay, type FastifyHandler as az, type RequestContext as b, type IControllerResponse as c, type RequestWithExtras as d, type CrudRouteKey as e, type PresetResult as f, type AuthHelpers as g, type AuthPluginOptions as h, type IntrospectionPluginOptions as i, ResourceRegistry as j, type RegisterOptions as k, type ResourceConfig as l, type SchemaMetadata as m, type RelationMetadata as n, type RepositoryLike as o, defineResource as p, ResourceDefinition as q, resourceRegistry as r, type ApiResponse as s, type ControllerLike as t, type FastifyRequestExtras as u, type FastifyWithAuth as v, type FastifyWithDecorators as w, type QueryOptions as x, type CrudRepository as y, type RouteHandler as z };