@decaf-ts/for-nest 0.6.0 → 0.7.0

package/lib/types/interceptors/DecafRequestHandlerInterceptor.d.mts

@@ -0,0 +1,57 @@
+import { CallHandler, ExecutionContext, NestInterceptor } from "@nestjs/common";
+import { DecafHandlerExecutor, DecafRequestContext } from "../request/index.js";
+import { DecafServerCtx } from "../constants.js";
+import "../overrides";
+/**
+ * @description
+ * Interceptor responsible for executing all registered Decaf request handlers
+ * before the controller method is invoked.
+ *
+ * @summary
+ * The {@link DecafRequestHandlerInterceptor} integrates the Decaf request-handling pipeline
+ * into NestJS' interceptor mechanism. Before passing execution to the next handler in the
+ * NestJS chain, it delegates request processing to the {@link DecafHandlerExecutor}, which
+ * sequentially runs all registered {@link DecafRequestHandler} instances. This allows
+ * behaviors such as authentication, logging, tenant resolution, or metadata enrichment
+ * to occur prior to controller execution.
+ *
+ * @class DecafRequestHandlerInterceptor
+ *
+ * @example
+ * ```ts
+ * // Apply globally:
+ * app.useGlobalInterceptors(new DecafRequestHandlerInterceptor(executor));
+ *
+ * // Or in a module:
+ * @Module({
+ *   providers: [
+ *     DecafHandlerExecutor,
+ *     {
+ *       provide: APP_INTERCEPTOR,
+ *       useClass: DecafRequestHandlerInterceptor,
+ *     },
+ *   ],
+ * })
+ * export class AppModule {}
+ * ```
+ *
+ * @mermaid
+ * sequenceDiagram
+ *     participant Client
+ *     participant Interceptor
+ *     participant Executor
+ *     participant Controller
+ *
+ *     Client->>Interceptor: HTTP Request
+ *     Interceptor->>Executor: exec(request)
+ *     Executor-->>Interceptor: handlers completed
+ *     Interceptor->>Controller: next.handle()
+ *     Controller-->>Client: Response
+ */
+export declare class DecafRequestHandlerInterceptor implements NestInterceptor {
+    protected readonly requestContext: DecafRequestContext;
+    protected readonly executor: DecafHandlerExecutor;
+    constructor(requestContext: DecafRequestContext, executor: DecafHandlerExecutor);
+    protected contextualize(req: any): Promise<DecafServerCtx>;
+    intercept(context: ExecutionContext, next: CallHandler): Promise<import("rxjs").Observable<any>>;
+}

package/lib/types/interceptors/context.d.cts

@@ -0,0 +1,6 @@
+import { DecafServerCtx } from "../constants.cjs";
+import { FlagsOf } from "@decaf-ts/core";
+export declare abstract class RequestToContextTransformer<C extends DecafServerCtx> {
+    abstract from(req: any, ...args: any[]): Promise<FlagsOf<C>>;
+}
+export declare function requestToContextTransformer(flavour: string): (original: any) => any;

package/lib/types/interceptors/context.d.mts

@@ -0,0 +1,6 @@
+import { DecafServerCtx } from "../constants.js";
+import { FlagsOf } from "@decaf-ts/core";
+export declare abstract class RequestToContextTransformer<C extends DecafServerCtx> {
+    abstract from(req: any, ...args: any[]): Promise<FlagsOf<C>>;
+}
+export declare function requestToContextTransformer(flavour: string): (original: any) => any;

package/lib/types/interceptors/index.d.cts

@@ -0,0 +1,3 @@
+export * from "./DecafRequestHandlerInterceptor.cjs";
+export * from "./AuthInterceptor.cjs";
+export * from "./context.cjs";

package/lib/types/interceptors/index.d.mts

@@ -0,0 +1,3 @@
+export * from "./DecafRequestHandlerInterceptor.js";
+export * from "./AuthInterceptor.js";
+export * from "./context.js";

package/lib/types/module.d.cts

@@ -0,0 +1,8 @@
+import { DynamicModule } from "@nestjs/common";
+import { DecafModuleOptions } from "./types.cjs";
+/**
+ * @publicApi
+ */
+export declare class DecafModule {
+    static forRootAsync(options: DecafModuleOptions): Promise<DynamicModule>;
+}

package/lib/types/module.d.mts

@@ -0,0 +1,8 @@
+import { DynamicModule } from "@nestjs/common";
+import { DecafModuleOptions } from "./types.js";
+/**
+ * @publicApi
+ */
+export declare class DecafModule {
+    static forRootAsync(options: DecafModuleOptions): Promise<DynamicModule>;
+}

package/lib/types/overrides/Adapter.d.cts

@@ -0,0 +1,13 @@
+import "@decaf-ts/core";
+import type { Constructor } from "@decaf-ts/decoration";
+import { RequestToContextTransformer } from "../interceptors/context.cjs";
+import { ContextOf } from "@decaf-ts/core";
+declare module "@decaf-ts/core" {
+    namespace Adapter {
+        function transformerFor<A extends Adapter<any, any, any, any>>(adapter: A | string): Constructor<RequestToContextTransformer<ContextOf<A>>> | RequestToContextTransformer<ContextOf<A>>;
+        function flavoursToTransform(): string[] | undefined;
+    }
+    interface Context {
+        toResponse<RES = any>(res: RES): RES;
+    }
+}

package/lib/types/overrides/Adapter.d.mts

@@ -0,0 +1,13 @@
+import "@decaf-ts/core";
+import type { Constructor } from "@decaf-ts/decoration";
+import { RequestToContextTransformer } from "../interceptors/context.js";
+import { ContextOf } from "@decaf-ts/core";
+declare module "@decaf-ts/core" {
+    namespace Adapter {
+        function transformerFor<A extends Adapter<any, any, any, any>>(adapter: A | string): Constructor<RequestToContextTransformer<ContextOf<A>>> | RequestToContextTransformer<ContextOf<A>>;
+        function flavoursToTransform(): string[] | undefined;
+    }
+    interface Context {
+        toResponse<RES = any>(res: RES): RES;
+    }
+}

package/lib/types/overrides/ModelBuilderExtensions.d.cts

@@ -0,0 +1,8 @@
+import "@decaf-ts/decorator-validation";
+import { Constructor } from "@decaf-ts/decoration";
+declare module "@decaf-ts/decorator-validation" {
+    interface ModelBuilder<M> {
+        Auth(model: string | Constructor): ModelBuilder<M>;
+        decorateClass(decorator: ClassDecorator): ModelBuilder<M>;
+    }
+}

package/lib/types/overrides/ModelBuilderExtensions.d.mts

@@ -0,0 +1,8 @@
+import "@decaf-ts/decorator-validation";
+import { Constructor } from "@decaf-ts/decoration";
+declare module "@decaf-ts/decorator-validation" {
+    interface ModelBuilder<M> {
+        Auth(model: string | Constructor): ModelBuilder<M>;
+        decorateClass(decorator: ClassDecorator): ModelBuilder<M>;
+    }
+}

package/lib/types/overrides/constants.d.cts

@@ -0,0 +1,21 @@
+export declare const DECORATORS_PREFIX = "swagger";
+export declare const DECORATORS: {
+    API_OPERATION: string;
+    API_RESPONSE: string;
+    API_PRODUCES: string;
+    API_CONSUMES: string;
+    API_TAGS: string;
+    API_CALLBACKS: string;
+    API_PARAMETERS: string;
+    API_HEADERS: string;
+    API_MODEL_PROPERTIES: string;
+    API_MODEL_PROPERTIES_ARRAY: string;
+    API_SECURITY: string;
+    API_EXCLUDE_ENDPOINT: string;
+    API_EXCLUDE_CONTROLLER: string;
+    API_EXTRA_MODELS: string;
+    API_EXTENSION: string;
+    API_SCHEMA: string;
+    API_DEFAULT_GETTER: string;
+    API_LINK: string;
+};

package/lib/types/overrides/constants.d.mts

@@ -0,0 +1,21 @@
+export declare const DECORATORS_PREFIX = "swagger";
+export declare const DECORATORS: {
+    API_OPERATION: string;
+    API_RESPONSE: string;
+    API_PRODUCES: string;
+    API_CONSUMES: string;
+    API_TAGS: string;
+    API_CALLBACKS: string;
+    API_PARAMETERS: string;
+    API_HEADERS: string;
+    API_MODEL_PROPERTIES: string;
+    API_MODEL_PROPERTIES_ARRAY: string;
+    API_SECURITY: string;
+    API_EXCLUDE_ENDPOINT: string;
+    API_EXCLUDE_CONTROLLER: string;
+    API_EXTRA_MODELS: string;
+    API_EXTENSION: string;
+    API_SCHEMA: string;
+    API_DEFAULT_GETTER: string;
+    API_LINK: string;
+};

package/lib/types/overrides/decoration.d.cts

@@ -0,0 +1,30 @@
+import { Type } from "@nestjs/common";
+import type { EnumSchemaAttributes } from "@nestjs/swagger/dist/interfaces/enum-schema-attributes.interface";
+import type { SchemaObjectMetadata } from "@nestjs/swagger/dist/interfaces/schema-object-metadata.interface";
+import { type SwaggerEnumType } from "@nestjs/swagger/dist/types/swagger-enum.type";
+export declare const isUndefined: (obj: any) => obj is undefined;
+export declare function getEnumValues(enumType: SwaggerEnumType | (() => SwaggerEnumType)): string[] | number[];
+export declare function getEnumType(values: (string | number)[]): "string" | "number";
+export declare function createPropertyDecorator<T extends Record<string, any> = any>(metakey: string, metadata: T, overrideExisting?: boolean): PropertyDecorator;
+export type ApiPropertyCommonOptions = SchemaObjectMetadata & {
+    "x-enumNames"?: string[];
+    /**
+     * Lazy function returning the type for which the decorated property
+     * can be used as an id
+     *
+     * Use together with @ApiDefaultGetter on the getter route of the type
+     * to generate OpenAPI link objects
+     *
+     * @see [Swagger link objects](https://swagger.io/docs/specification/links/)
+     */
+    link?: () => Type<unknown> | Function;
+};
+export type ApiPropertyOptions = ApiPropertyCommonOptions | (ApiPropertyCommonOptions & {
+    enumName: string;
+    enumSchema?: EnumSchemaAttributes;
+});
+/**
+ * @publicApi
+ */
+export declare function ApiProperty(options?: ApiPropertyOptions): PropertyDecorator;
+export declare function createApiPropertyDecorator(options?: ApiPropertyOptions, overrideExisting?: boolean): PropertyDecorator;

package/lib/types/overrides/decoration.d.mts

@@ -0,0 +1,30 @@
+import { Type } from "@nestjs/common";
+import type { EnumSchemaAttributes } from "@nestjs/swagger/dist/interfaces/enum-schema-attributes.interface";
+import type { SchemaObjectMetadata } from "@nestjs/swagger/dist/interfaces/schema-object-metadata.interface";
+import { type SwaggerEnumType } from "@nestjs/swagger/dist/types/swagger-enum.type";
+export declare const isUndefined: (obj: any) => obj is undefined;
+export declare function getEnumValues(enumType: SwaggerEnumType | (() => SwaggerEnumType)): string[] | number[];
+export declare function getEnumType(values: (string | number)[]): "string" | "number";
+export declare function createPropertyDecorator<T extends Record<string, any> = any>(metakey: string, metadata: T, overrideExisting?: boolean): PropertyDecorator;
+export type ApiPropertyCommonOptions = SchemaObjectMetadata & {
+    "x-enumNames"?: string[];
+    /**
+     * Lazy function returning the type for which the decorated property
+     * can be used as an id
+     *
+     * Use together with @ApiDefaultGetter on the getter route of the type
+     * to generate OpenAPI link objects
+     *
+     * @see [Swagger link objects](https://swagger.io/docs/specification/links/)
+     */
+    link?: () => Type<unknown> | Function;
+};
+export type ApiPropertyOptions = ApiPropertyCommonOptions | (ApiPropertyCommonOptions & {
+    enumName: string;
+    enumSchema?: EnumSchemaAttributes;
+});
+/**
+ * @publicApi
+ */
+export declare function ApiProperty(options?: ApiPropertyOptions): PropertyDecorator;
+export declare function createApiPropertyDecorator(options?: ApiPropertyOptions, overrideExisting?: boolean): PropertyDecorator;

package/lib/types/overrides/helpers.d.cts

@@ -0,0 +1,11 @@
+export declare const isConstructor: (val: any) => boolean;
+export declare const METADATA_FACTORY_NAME = "_OPENAPI_METADATA_FACTORY";
+export declare const METHOD_METADATA = "method";
+export declare function createMethodDecorator<T = any>(metakey: string, metadata: T, { overrideExisting }?: {
+    overrideExisting: boolean;
+}): MethodDecorator;
+export declare function createClassDecorator<T extends Array<any> = any>(metakey: string, metadata?: T): ClassDecorator;
+export declare function createPropertyDecorator<T extends Record<string, any> = any>(metakey: string, metadata: T, overrideExisting?: boolean): PropertyDecorator;
+export declare function createMixedDecorator<T = any>(metakey: string, metadata: T): MethodDecorator & ClassDecorator;
+export declare function createParamDecorator<T extends Record<string, any> = any>(metadata: T, initial: Partial<T>): MethodDecorator & ClassDecorator;
+export declare function getTypeIsArrayTuple(input: Function | [Function] | undefined | string | Record<string, any>, isArrayFlag: boolean): [Function | undefined, boolean];

package/lib/types/overrides/helpers.d.mts

@@ -0,0 +1,11 @@
+export declare const isConstructor: (val: any) => boolean;
+export declare const METADATA_FACTORY_NAME = "_OPENAPI_METADATA_FACTORY";
+export declare const METHOD_METADATA = "method";
+export declare function createMethodDecorator<T = any>(metakey: string, metadata: T, { overrideExisting }?: {
+    overrideExisting: boolean;
+}): MethodDecorator;
+export declare function createClassDecorator<T extends Array<any> = any>(metakey: string, metadata?: T): ClassDecorator;
+export declare function createPropertyDecorator<T extends Record<string, any> = any>(metakey: string, metadata: T, overrideExisting?: boolean): PropertyDecorator;
+export declare function createMixedDecorator<T = any>(metakey: string, metadata: T): MethodDecorator & ClassDecorator;
+export declare function createParamDecorator<T extends Record<string, any> = any>(metadata: T, initial: Partial<T>): MethodDecorator & ClassDecorator;
+export declare function getTypeIsArrayTuple(input: Function | [Function] | undefined | string | Record<string, any>, isArrayFlag: boolean): [Function | undefined, boolean];

package/lib/types/overrides/index.d.cts

@@ -0,0 +1,6 @@
+import "./overrides";
+export * from "./Adapter.cjs";
+export * from "./constants.cjs";
+export * from "./decoration.cjs";
+export * from "./overrides.cjs";
+export * from "./ModelBuilderExtensions.cjs";

package/lib/types/overrides/index.d.mts

@@ -0,0 +1,6 @@
+import "./overrides";
+export * from "./Adapter.js";
+export * from "./constants.js";
+export * from "./decoration.js";
+export * from "./overrides.js";
+export * from "./ModelBuilderExtensions.js";

package/lib/types/overrides/overrides.d.cts

@@ -0,0 +1 @@
+export {};

package/lib/types/overrides/overrides.d.mts

@@ -0,0 +1 @@
+export {};

package/lib/types/ram/RamRequestTransformer.d.cts

@@ -0,0 +1,5 @@
+import { RequestToContextTransformer } from "../interceptors/context.cjs";
+export declare class RamTransformer implements RequestToContextTransformer<any> {
+    constructor();
+    from(req: any, ..._args: any[]): Promise<any>;
+}

package/lib/types/ram/RamRequestTransformer.d.mts

@@ -0,0 +1,5 @@
+import { RequestToContextTransformer } from "../interceptors/context.js";
+export declare class RamTransformer implements RequestToContextTransformer<any> {
+    constructor();
+    from(req: any, ..._args: any[]): Promise<any>;
+}

package/lib/types/ram/index.d.cts

@@ -0,0 +1 @@
+export * from "./RamRequestTransformer.cjs";

package/lib/types/ram/index.d.mts

@@ -0,0 +1 @@
+export * from "./RamRequestTransformer.js";

package/lib/types/request/DecafAuthHandler.d.cts

@@ -0,0 +1,10 @@
+import { ExecutionContext } from "@nestjs/common";
+import { AuthHandler } from "../types.cjs";
+export declare class DecafAuthHandler implements AuthHandler {
+    protected parseRequest(req: any): string;
+    authorize(ctx: ExecutionContext, resource: string): Promise<void>;
+}
+export declare class DecafRoleAuthHandler extends DecafAuthHandler {
+    constructor();
+    authorize(ctx: ExecutionContext, resource: string): Promise<any>;
+}

package/lib/types/request/DecafAuthHandler.d.mts

@@ -0,0 +1,10 @@
+import { ExecutionContext } from "@nestjs/common";
+import { AuthHandler } from "../types.js";
+export declare class DecafAuthHandler implements AuthHandler {
+    protected parseRequest(req: any): string;
+    authorize(ctx: ExecutionContext, resource: string): Promise<void>;
+}
+export declare class DecafRoleAuthHandler extends DecafAuthHandler {
+    constructor();
+    authorize(ctx: ExecutionContext, resource: string): Promise<any>;
+}

package/lib/types/request/DecafHandlerExecutor.d.cts

@@ -0,0 +1,52 @@
+import { DecafRequestContext } from "./DecafRequestContext.cjs";
+import { type DecafRequestHandler } from "../types.cjs";
+/**
+ * @description
+ * Executes all registered {@link DecafRequestHandler} instances for the current request,
+ * providing them with a shared {@link DecafRequestContext}.
+ *
+ * @summary
+ * The {@link DecafHandlerExecutor} class is responsible for orchestrating and executing
+ * a sequence of request handlers. Each handler receives the same request-scoped context,
+ * allowing coordinated processing such as authentication, metadata extraction, auditing,
+ * and custom pipeline behavior. Handlers are injected via the {@link DECAF_HANDLERS} token,
+ * ensuring extensibility and loose coupling.
+ *
+ * @class DecafHandlerExecutor
+ *
+ * @example
+ * ```ts
+ * // Example handler:
+ * class AuthHandler implements DecafRequestHandler {
+ *   async handle(context: DecafRequestContext, req: Request) {
+ *     const token = req.headers["authorization"];
+ *     const result = MyService.doSomething(token);
+ *     context.set("my-key", result);
+ *   }
+ * }
+ *
+ * // Executor usage in a request:
+ * await executor.exec(request);
+ * // All handlers will run in sequence
+ * ```
+ *
+ * @mermaid
+ * sequenceDiagram
+ *     participant Client
+ *     participant Executor
+ *     participant HandlerA
+ *     participant HandlerB
+ *
+ *     Client->>Executor: exec(req)
+ *     Executor->>HandlerA: handle(context, req)
+ *     HandlerA-->>Executor: completed
+ *     Executor->>HandlerB: handle(context, req)
+ *     HandlerB-->>Executor: completed
+ *     Executor-->>Client: processing finished
+ */
+export declare class DecafHandlerExecutor {
+    private readonly handlers;
+    private readonly context;
+    constructor(handlers: DecafRequestHandler[], context: DecafRequestContext);
+    exec(req: Request, res: Response): Promise<void>;
+}

package/lib/types/request/DecafHandlerExecutor.d.mts

@@ -0,0 +1,52 @@
+import { DecafRequestContext } from "./DecafRequestContext.js";
+import { type DecafRequestHandler } from "../types.js";
+/**
+ * @description
+ * Executes all registered {@link DecafRequestHandler} instances for the current request,
+ * providing them with a shared {@link DecafRequestContext}.
+ *
+ * @summary
+ * The {@link DecafHandlerExecutor} class is responsible for orchestrating and executing
+ * a sequence of request handlers. Each handler receives the same request-scoped context,
+ * allowing coordinated processing such as authentication, metadata extraction, auditing,
+ * and custom pipeline behavior. Handlers are injected via the {@link DECAF_HANDLERS} token,
+ * ensuring extensibility and loose coupling.
+ *
+ * @class DecafHandlerExecutor
+ *
+ * @example
+ * ```ts
+ * // Example handler:
+ * class AuthHandler implements DecafRequestHandler {
+ *   async handle(context: DecafRequestContext, req: Request) {
+ *     const token = req.headers["authorization"];
+ *     const result = MyService.doSomething(token);
+ *     context.set("my-key", result);
+ *   }
+ * }
+ *
+ * // Executor usage in a request:
+ * await executor.exec(request);
+ * // All handlers will run in sequence
+ * ```
+ *
+ * @mermaid
+ * sequenceDiagram
+ *     participant Client
+ *     participant Executor
+ *     participant HandlerA
+ *     participant HandlerB
+ *
+ *     Client->>Executor: exec(req)
+ *     Executor->>HandlerA: handle(context, req)
+ *     HandlerA-->>Executor: completed
+ *     Executor->>HandlerB: handle(context, req)
+ *     HandlerB-->>Executor: completed
+ *     Executor-->>Client: processing finished
+ */
+export declare class DecafHandlerExecutor {
+    private readonly handlers;
+    private readonly context;
+    constructor(handlers: DecafRequestHandler[], context: DecafRequestContext);
+    exec(req: Request, res: Response): Promise<void>;
+}

package/lib/types/request/DecafRequestContext.d.cts

@@ -0,0 +1,11 @@
+import { DecafServerCtx } from "../constants.cjs";
+export declare class DecafRequestContext<C extends DecafServerCtx = DecafServerCtx> {
+    private readonly req;
+    private _ctx?;
+    uuid: string | Promise<string>;
+    constructor(req: Request);
+    get request(): Record<string | symbol, any>;
+    put(record: Record<any, any>): void;
+    applyCtx(ctx: C): void;
+    get ctx(): C;
+}

package/lib/types/request/DecafRequestContext.d.mts

@@ -0,0 +1,11 @@
+import { DecafServerCtx } from "../constants.js";
+export declare class DecafRequestContext<C extends DecafServerCtx = DecafServerCtx> {
+    private readonly req;
+    private _ctx?;
+    uuid: string | Promise<string>;
+    constructor(req: Request);
+    get request(): Record<string | symbol, any>;
+    put(record: Record<any, any>): void;
+    applyCtx(ctx: C): void;
+    get ctx(): C;
+}

package/lib/types/request/DecafResponseInterceptor.d.cts

@@ -0,0 +1,8 @@
+import { NestInterceptor, ExecutionContext, CallHandler } from "@nestjs/common";
+import { Observable } from "rxjs";
+import { DecafRequestContext } from "./DecafRequestContext.cjs";
+export declare class DecafResponseInterceptor implements NestInterceptor {
+    protected ctx: DecafRequestContext;
+    constructor(ctx: DecafRequestContext);
+    intercept(context: ExecutionContext, next: CallHandler): Observable<any>;
+}

package/lib/types/request/DecafResponseInterceptor.d.mts

@@ -0,0 +1,8 @@
+import { NestInterceptor, ExecutionContext, CallHandler } from "@nestjs/common";
+import { Observable } from "rxjs";
+import { DecafRequestContext } from "./DecafRequestContext.js";
+export declare class DecafResponseInterceptor implements NestInterceptor {
+    protected ctx: DecafRequestContext;
+    constructor(ctx: DecafRequestContext);
+    intercept(context: ExecutionContext, next: CallHandler): Observable<any>;
+}

package/lib/types/request/index.d.cts

@@ -0,0 +1,4 @@
+export * from "./DecafAuthHandler.cjs";
+export * from "./DecafRequestContext.cjs";
+export * from "./DecafHandlerExecutor.cjs";
+export * from "./DecafResponseInterceptor.cjs";

package/lib/types/request/index.d.mts

@@ -0,0 +1,4 @@
+export * from "./DecafAuthHandler.js";
+export * from "./DecafRequestContext.js";
+export * from "./DecafHandlerExecutor.js";
+export * from "./DecafResponseInterceptor.js";

package/lib/types/types.d.cts

@@ -0,0 +1,88 @@
+import { Adapter, ConfigOf, ContextOf } from "@decaf-ts/core";
+import { Constructor } from "@decaf-ts/decoration";
+import { ExecutionContext, Type } from "@nestjs/common";
+import { RequestToContextTransformer } from "./interceptors/context.cjs";
+import { DecafRequestContext } from "./request/index.cjs";
+export interface DecafRequestHandler<C extends DecafRequestContext = DecafRequestContext> {
+    handle(context: C, req: Request, res: Response): Promise<void>;
+}
+export interface ObserverEventsOptions {
+    /**
+     * Enables or disables SSE stream events globally
+     */
+    enableObserverEvents?: boolean;
+    /**
+     * List of adapter flavours that will emit stream events
+     * If omitted, all registered flavours may be used
+     */
+    observerFlavours?: any[];
+    /**
+     * SSE endpoint path
+     * @default "/events"
+     */
+    observerApiPath?: string;
+}
+/**
+ * @publicApi
+ */
+export type DecafModuleOptions<CONF = any, A extends Adapter<CONF, any, any, any> = Adapter<CONF, any, any, any>> = {
+    conf: [
+        Constructor<A>,
+        ConfigOf<A>,
+        ...args: any[] | [
+            ...any[],
+            (RequestToContextTransformer<ContextOf<A>> | Constructor<RequestToContextTransformer<ContextOf<A>>>)
+        ]
+    ][];
+    alias?: string;
+    autoControllers: boolean;
+    autoServices?: boolean;
+    observerOptions?: ObserverEventsOptions;
+    aggregations?: boolean;
+    handlers?: Type<DecafRequestHandler>[];
+    initialization?: () => Promise<void>;
+};
+/**
+ * Abstraction used by the {@link AuthInterceptor} to authorize decaf models.
+ *
+ * // costumauthHandler.ts
+ *
+ * @example
+ * export class CustomAuthHandler implements AuthHandler {
+ *   async authorize(ctx: ExecutionContext, resource: string) {
+ *     const req = ctx.switchToHttp().getRequest();
+ *     const userRole = req.headers.authorization?.split(" ")[1] as string;
+ *     if (!userRole) throw new AuthorizationError("Unauthenticated");
+ *     const roles = Metadata.get(Model.get(resource)!, AuthRole);
+ *     if (!roles.includes(userRole)) {
+ *       throw new AuthorizationError("Unauthorized");
+ *     }
+ *   }
+ * }
+ *
+ * // auth.module.ts
+ *
+ * @Global()
+ * @Module({
+ *  providers: [
+ *    AuthInterceptor,
+ *    CustomAuthHandler,
+ *    {
+ *      provide: AUTH_HANDLER,
+ *      useClass: CustomAuthHandler, //swap this to use another provider
+ *    },
+ *  ],
+ *  exports: [AUTH_HANDLER, AuthInterceptor],
+ * })
+ * export class AuthModule {}
+ */
+export interface AuthHandler {
+    /**
+     * Inspect the request context and ensure the caller can access the model.
+     * Implementations should throw an {@link AuthorizationError} on denial.
+     *
+     * @param ctx - Nest execution context that exposes the request/response.
+     * @param model - Model name or constructor being accessed.
+     */
+    authorize(ctx: ExecutionContext, model: string | Constructor): Promise<void> | void;
+}