zod-nest 0.2.0 → 0.4.0

package/dist/index.d.mts

@@ -1,5 +1,8 @@
 import { z } from 'zod';
 import { JSONSchema, $ZodTypes } from 'zod/v4/core';
+import { InternalServerErrorException, ExecutionContext, BadRequestException, ArgumentMetadata, LoggerService, PipeTransform, NestInterceptor, CallHandler, DynamicModule } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { Observable } from 'rxjs';
 
 /** OpenAPI 3.1 `$ref` prefix for entries in `components.schemas`. */
 declare const COMPONENTS_SCHEMAS_PREFIX = "#/components/schemas/";
@@ -115,4 +118,285 @@ declare const makeZodDtoMarker: (dtoId: string, io: Io) => ZodDtoMarker;
 /** Phase 2e (and tests) use this to discriminate a marker from a real schema. */
 declare const isZodDtoMarker: (value: unknown) => value is ZodDtoMarker;
 
-export { COMPONENTS_SCHEMAS_PREFIX, type CreateZodDtoOptions, type Io, type Override, type OverrideContext, type SchemaObject, type ToOpenApiOptions, type ToOpenApiResult, ZOD_DTO_SYMBOL, ZOD_NEST_DTO_EXTENSION, ZOD_NEST_ERROR_DUPLICATE_ID, ZOD_NEST_ERROR_EXTENSION, type ZodDto, type ZodDtoMarker, ZodNestError, type ZodNestRegistry, ZodNestUnrepresentableError, createRegistry, createZodDto, defaultRegistry, isZodDtoMarker, makeZodDtoMarker, toOpenApi };
+/**
+ * Runtime guard: is `value` a class returned by `createZodDto`?
+ *
+ * Used by the validation pipe (Phase 2c), the serializer interceptor (2d),
+ * and the doc merger (2e) to discriminate zod-nest DTOs from plain
+ * constructors, class-validator DTOs, primitives, and any other metatypes
+ * NestJS exposes via `ArgumentMetadata`.
+ */
+declare const isZodDto: (value: unknown) => value is ZodDto;
+
+/**
+ * Default exception thrown by `ZodSerializerInterceptor` in strict mode
+ * (i.e. when `@ZodResponse({ passthroughOnError: true })` is NOT set) on
+ * response-validation failure.
+ *
+ * Body shape (returned by `getResponse()`):
+ * ```
+ * {
+ *   statusCode: 500,
+ *   message: 'Response validation failed',
+ *   errors: z.treeifyError(zodError),
+ * }
+ * ```
+ *
+ * Carries `zodError` and `executionContext` so custom exception filters
+ * can introspect the original validation failure and the request that
+ * produced it.
+ */
+declare class ZodSerializationException extends InternalServerErrorException {
+    readonly zodError: z.ZodError;
+    readonly executionContext?: ExecutionContext;
+    constructor(zodError: z.ZodError, executionContext?: ExecutionContext);
+}
+
+/**
+ * Default exception thrown by `ZodValidationPipe` when input fails to parse.
+ *
+ * Body shape (returned by `getResponse()`):
+ * ```
+ * {
+ *   statusCode: 400,
+ *   message: 'Validation failed',
+ *   errors: z.treeifyError(zodError),
+ * }
+ * ```
+ *
+ * Carries `zodError` and `argMetadata` so custom exception filters can
+ * introspect the original validation failure.
+ */
+declare class ZodValidationException extends BadRequestException {
+    readonly zodError: z.ZodError;
+    readonly argMetadata?: ArgumentMetadata;
+    constructor(zodError: z.ZodError, argMetadata?: ArgumentMetadata);
+}
+
+interface ValidationLogContext {
+    /** Which side of the request emitted the failure. */
+    side: 'input' | 'output';
+    /** Severity to log at; the formatter does not decide this. */
+    severity: 'warn' | 'error';
+    /** Pre-formatted DTO label, e.g. `'UserDto'`, `'[UserDto]'`, `'[A, B]'`. */
+    dto: string;
+    /** Output side only — HTTP response status code. */
+    status?: number;
+    /** Output side only — `Controller.method` best-effort. */
+    handler?: string;
+    /** Input side only — `body` / `query` / `param` / `custom`. */
+    argType?: string;
+}
+type LogValidationFailure = (err: z.ZodError, value: unknown, ctx: ValidationLogContext) => void;
+
+/**
+ * Module-scope factory for the exception thrown by `ZodValidationPipe` on
+ * input validation failure. Mirrors the existing per-pipe option but lives
+ * at module scope; per-instance constructor arg wins.
+ */
+type CreateValidationException$1 = (err: z.ZodError, argMetadata: ArgumentMetadata) => unknown;
+/**
+ * Module-scope factory for the exception thrown by `ZodSerializerInterceptor`
+ * on output validation failure (strict mode only). Soft mode never calls
+ * this factory.
+ */
+type CreateSerializationException = (err: z.ZodError, executionContext: ExecutionContext) => unknown;
+/** Public options accepted by `ZodNestModule.forRoot()`. */
+interface ZodNestModuleOptions {
+    createValidationException?: CreateValidationException$1;
+    createSerializationException?: CreateSerializationException;
+    /**
+     * Failure-only validation logging. `true` enables both input and output;
+     * the granular form lets each side be toggled independently. Default: off.
+     */
+    validationLogs?: boolean | {
+        input?: boolean;
+        output?: boolean;
+    };
+    /** Override Nest's built-in `Logger` (e.g. pino/winston adapter). */
+    logger?: LoggerService;
+    /**
+     * Keys whose values get scrubbed from logged input/response objects.
+     * Matched case-insensitively at any depth. Supplying this option
+     * REPLACES the default list (no merge).
+     */
+    redactKeys?: readonly string[];
+    /**
+     * Maximum size in bytes (UTF-8) for any single logged value. Oversized
+     * values become `{ _truncated: true, _originalBytes, _preview }`.
+     */
+    maxLoggedValueBytes?: number;
+}
+/**
+ * Resolved options consumed by pipe + interceptor. `forRoot()` builds this
+ * once and stuffs it into a provider for the `ZOD_NEST_OPTIONS` injection
+ * token; downstream code never re-checks the raw `validationLogs` flag.
+ */
+interface NormalizedZodNestOptions {
+    createValidationException: CreateValidationException$1 | undefined;
+    createSerializationException: CreateSerializationException | undefined;
+    /** No-op when `validationLogs.input` resolved to false. */
+    logInputFailure: LogValidationFailure;
+    /** No-op when `validationLogs.output` resolved to false. */
+    logOutputFailure: LogValidationFailure;
+}
+declare const DEFAULT_REDACT_KEYS: readonly string[];
+declare const DEFAULT_MAX_LOGGED_VALUE_BYTES = 4096;
+/** DI token for `NormalizedZodNestOptions`. */
+declare const ZOD_NEST_OPTIONS: unique symbol;
+
+/**
+ * Build the exception thrown by `ZodValidationPipe` on validation failure.
+ * Receives Zod's error and the NestJS argument metadata; returns anything
+ * `throw`-able (typically a NestJS `HttpException` subclass).
+ */
+type CreateValidationException = (zodError: z.ZodError, argMetadata: ArgumentMetadata) => unknown;
+interface ZodValidationPipeOptions {
+    schema?: z.ZodType | ZodDto;
+    createValidationException?: CreateValidationException;
+}
+/**
+ * Constructor input for `ZodValidationPipe`. Discriminated at runtime:
+ * - `undefined` → metatype-driven (read DTO from handler arg's metatype)
+ * - a class with `[ZOD_DTO_SYMBOL]` → explicit DTO
+ * - a Zod schema (has `_zod` internals) → raw schema
+ * - anything else → options object
+ */
+type ZodValidationPipeArg = z.ZodType | ZodDto | ZodValidationPipeOptions;
+
+declare class ZodValidationPipe implements PipeTransform {
+    private readonly explicitSchema;
+    private readonly explicitDtoName;
+    private readonly createValidationException;
+    private readonly logInputFailure;
+    constructor(arg?: ZodValidationPipeArg, moduleOptions?: NormalizedZodNestOptions);
+    transform(value: unknown, metadata: ArgumentMetadata): Promise<unknown>;
+    private resolveSchema;
+    private resolveDtoLabel;
+    private static parseArg;
+}
+
+/**
+ * Public metadata key for the array of `ResponseVariant` records attached
+ * to handler methods by `@ZodResponse(...)`. Symbol.for() so external
+ * consumers (e.g. custom interceptors or doc builders) can read the same
+ * registry across realms.
+ */
+declare const ZOD_RESPONSES_METADATA_KEY: unique symbol;
+type ResponseVariantKind = 'single' | 'array' | 'tuple';
+/**
+ * Description payload accepted by `@ZodResponse(...)` and passed through to
+ * Phase 2e's `@ApiResponse(...)` emitter. String form is shorthand for
+ * `{ description }`; the object form lets users declare OpenAPI response
+ * `headers` / `links` alongside the description.
+ */
+type ZodResponseDescription = string | {
+    description: string;
+    headers?: Record<string, unknown>;
+    links?: Record<string, unknown>;
+};
+/**
+ * One variant record per `@ZodResponse(...)` call. `dto` is kept alongside
+ * `validationSchema` so Phase 2e can emit `@ApiResponse({ type })` without
+ * unwrapping the runtime-only `z.array(...)` / `z.tuple([...])` wrapper.
+ *
+ * `status` is `undefined` when the user didn't pass one explicitly — the
+ * effective status is resolved lazily by `resolveEffectiveStatus(variant,
+ * handler)` because `@ZodResponse` runs *before* NestJS' route decorators
+ * (`@Get`, `@Post`, ...) under TypeScript's bottom-up application order,
+ * so `METHOD_METADATA` is not yet set when the decorator evaluates.
+ */
+interface ResponseVariant {
+    status: number | undefined;
+    kind: ResponseVariantKind;
+    dto: ZodDto | readonly ZodDto[];
+    validationSchema: z.ZodType;
+    description?: ZodResponseDescription;
+    passthroughOnError: boolean;
+}
+
+/**
+ * Accepted shapes for `@ZodResponse({ type })`:
+ * - `Dto` → validates as `Dto.schema` (single-DTO response).
+ * - `[Dto]` (length 1) → validates as `z.array(Dto.schema)`; matches Nest's
+ *   `@ApiResponse({ isArray: true })` convention without minting a separate
+ *   `*sDto` id.
+ * - `[A, B, ...]` (length ≥ 2) → validates as `z.tuple([A.schema, B.schema, ...])`;
+ *   surfaces as an OpenAPI 3.1 `prefixItems` tuple in Phase 2e.
+ *
+ * Empty arrays and non-DTO elements throw `TypeError` at decoration time
+ * so typos surface at module load, not the first request.
+ */
+type ZodResponseType = ZodDto | readonly [ZodDto, ...ZodDto[]];
+interface ZodResponseOptions {
+    status?: number;
+    type: ZodResponseType;
+    description?: ZodResponseDescription;
+    passthroughOnError?: boolean;
+}
+/**
+ * Method-only decorator. Declares a typed response variant for the handler.
+ * Stack multiple decorations to declare per-status types; lookup at runtime
+ * is by `response.statusCode === variant.status`.
+ *
+ * The wrapped Zod schema (array / tuple) is built once at decoration time
+ * and stored on the variant record — no per-request schema construction.
+ */
+declare const ZodResponse: (opts: ZodResponseOptions) => MethodDecorator;
+
+declare class ZodSerializerInterceptor implements NestInterceptor {
+    private readonly reflector;
+    private readonly logOutputFailure;
+    private readonly createSerializationException;
+    constructor(reflector: Reflector, options?: NormalizedZodNestOptions);
+    intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+    private transform;
+}
+
+/**
+ * Compute the default HTTP status code for a handler when `@ZodResponse(...)`
+ * is invoked without an explicit `status`. Lookup order (highest → lowest):
+ *
+ * 1. `@HttpCode(n)` on the handler — explicit per-handler status override.
+ *    NestJS sets `HTTP_CODE_METADATA` to the numeric status when present.
+ * 2. HTTP method default — `POST` → `201`, everything else → `200`.
+ *
+ * The method default itself falls back to `200` when `METHOD_METADATA` is
+ * absent — pinned by tests so a future NestJS rename surfaces as a test
+ * failure rather than a silent regression.
+ */
+declare const defaultStatusFor: (handler: object) => number;
+/**
+ * Resolve the effective status code for a variant. Precedence chain:
+ *
+ * 1. Explicit `@ZodResponse({ status })` on the decorator call — `variant.status`.
+ * 2. `@HttpCode(n)` on the handler — read via `defaultStatusFor()` at runtime.
+ * 3. HTTP method default (POST → 201, others → 200) — also via `defaultStatusFor()`.
+ *
+ * Resolution is deferred to request time because `@ZodResponse` runs before
+ * NestJS' route + `@HttpCode` decorators — none of their metadata is set
+ * when the decorator evaluates.
+ */
+declare const resolveEffectiveStatus: (variant: ResponseVariant, handler: object) => number;
+
+/**
+ * Central wiring for the zod-nest pipe + interceptor. Call
+ * `ZodNestModule.forRoot(options?)` from your root `AppModule` to register
+ * `APP_PIPE` (`ZodValidationPipe`) and `APP_INTERCEPTOR`
+ * (`ZodSerializerInterceptor`) globally, with shared options for
+ * validation logging, redaction, and exception factories.
+ *
+ * `forRoot()` is optional — the pipe and interceptor also work as
+ * regular `APP_PIPE` / `APP_INTERCEPTOR` providers if you prefer to
+ * wire them manually; `@Optional()` injection of `ZOD_NEST_OPTIONS`
+ * falls through to safe defaults.
+ *
+ * Marked `global` so the `ZOD_NEST_OPTIONS` token is injectable from
+ * feature modules (e.g. a custom pipe that wants the same logger /
+ * redact list as the module-wired one).
+ */
+declare class ZodNestModule {
+    static forRoot(options?: ZodNestModuleOptions): DynamicModule;
+}
+
+export { COMPONENTS_SCHEMAS_PREFIX, type CreateSerializationException, type CreateValidationException, type CreateZodDtoOptions, DEFAULT_MAX_LOGGED_VALUE_BYTES, DEFAULT_REDACT_KEYS, type Io, type NormalizedZodNestOptions, type Override, type OverrideContext, type ResponseVariant, type ResponseVariantKind, type SchemaObject, type ToOpenApiOptions, type ToOpenApiResult, ZOD_DTO_SYMBOL, ZOD_NEST_DTO_EXTENSION, ZOD_NEST_ERROR_DUPLICATE_ID, ZOD_NEST_ERROR_EXTENSION, ZOD_NEST_OPTIONS, ZOD_RESPONSES_METADATA_KEY, type ZodDto, type ZodDtoMarker, ZodNestError, ZodNestModule, type ZodNestModuleOptions, type ZodNestRegistry, ZodNestUnrepresentableError, ZodResponse, type ZodResponseDescription, type ZodResponseOptions, type ZodResponseType, ZodSerializationException, ZodSerializerInterceptor, ZodValidationException, ZodValidationPipe, type ZodValidationPipeArg, type ZodValidationPipeOptions, createRegistry, createZodDto, defaultRegistry, defaultStatusFor, isZodDto, isZodDtoMarker, makeZodDtoMarker, resolveEffectiveStatus, toOpenApi };

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 import { z } from 'zod';
 import { JSONSchema, $ZodTypes } from 'zod/v4/core';
+import { InternalServerErrorException, ExecutionContext, BadRequestException, ArgumentMetadata, LoggerService, PipeTransform, NestInterceptor, CallHandler, DynamicModule } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { Observable } from 'rxjs';
 
 /** OpenAPI 3.1 `$ref` prefix for entries in `components.schemas`. */
 declare const COMPONENTS_SCHEMAS_PREFIX = "#/components/schemas/";
@@ -115,4 +118,285 @@ declare const makeZodDtoMarker: (dtoId: string, io: Io) => ZodDtoMarker;
 /** Phase 2e (and tests) use this to discriminate a marker from a real schema. */
 declare const isZodDtoMarker: (value: unknown) => value is ZodDtoMarker;
 
-export { COMPONENTS_SCHEMAS_PREFIX, type CreateZodDtoOptions, type Io, type Override, type OverrideContext, type SchemaObject, type ToOpenApiOptions, type ToOpenApiResult, ZOD_DTO_SYMBOL, ZOD_NEST_DTO_EXTENSION, ZOD_NEST_ERROR_DUPLICATE_ID, ZOD_NEST_ERROR_EXTENSION, type ZodDto, type ZodDtoMarker, ZodNestError, type ZodNestRegistry, ZodNestUnrepresentableError, createRegistry, createZodDto, defaultRegistry, isZodDtoMarker, makeZodDtoMarker, toOpenApi };
+/**
+ * Runtime guard: is `value` a class returned by `createZodDto`?
+ *
+ * Used by the validation pipe (Phase 2c), the serializer interceptor (2d),
+ * and the doc merger (2e) to discriminate zod-nest DTOs from plain
+ * constructors, class-validator DTOs, primitives, and any other metatypes
+ * NestJS exposes via `ArgumentMetadata`.
+ */
+declare const isZodDto: (value: unknown) => value is ZodDto;
+
+/**
+ * Default exception thrown by `ZodSerializerInterceptor` in strict mode
+ * (i.e. when `@ZodResponse({ passthroughOnError: true })` is NOT set) on
+ * response-validation failure.
+ *
+ * Body shape (returned by `getResponse()`):
+ * ```
+ * {
+ *   statusCode: 500,
+ *   message: 'Response validation failed',
+ *   errors: z.treeifyError(zodError),
+ * }
+ * ```
+ *
+ * Carries `zodError` and `executionContext` so custom exception filters
+ * can introspect the original validation failure and the request that
+ * produced it.
+ */
+declare class ZodSerializationException extends InternalServerErrorException {
+    readonly zodError: z.ZodError;
+    readonly executionContext?: ExecutionContext;
+    constructor(zodError: z.ZodError, executionContext?: ExecutionContext);
+}
+
+/**
+ * Default exception thrown by `ZodValidationPipe` when input fails to parse.
+ *
+ * Body shape (returned by `getResponse()`):
+ * ```
+ * {
+ *   statusCode: 400,
+ *   message: 'Validation failed',
+ *   errors: z.treeifyError(zodError),
+ * }
+ * ```
+ *
+ * Carries `zodError` and `argMetadata` so custom exception filters can
+ * introspect the original validation failure.
+ */
+declare class ZodValidationException extends BadRequestException {
+    readonly zodError: z.ZodError;
+    readonly argMetadata?: ArgumentMetadata;
+    constructor(zodError: z.ZodError, argMetadata?: ArgumentMetadata);
+}
+
+interface ValidationLogContext {
+    /** Which side of the request emitted the failure. */
+    side: 'input' | 'output';
+    /** Severity to log at; the formatter does not decide this. */
+    severity: 'warn' | 'error';
+    /** Pre-formatted DTO label, e.g. `'UserDto'`, `'[UserDto]'`, `'[A, B]'`. */
+    dto: string;
+    /** Output side only — HTTP response status code. */
+    status?: number;
+    /** Output side only — `Controller.method` best-effort. */
+    handler?: string;
+    /** Input side only — `body` / `query` / `param` / `custom`. */
+    argType?: string;
+}
+type LogValidationFailure = (err: z.ZodError, value: unknown, ctx: ValidationLogContext) => void;
+
+/**
+ * Module-scope factory for the exception thrown by `ZodValidationPipe` on
+ * input validation failure. Mirrors the existing per-pipe option but lives
+ * at module scope; per-instance constructor arg wins.
+ */
+type CreateValidationException$1 = (err: z.ZodError, argMetadata: ArgumentMetadata) => unknown;
+/**
+ * Module-scope factory for the exception thrown by `ZodSerializerInterceptor`
+ * on output validation failure (strict mode only). Soft mode never calls
+ * this factory.
+ */
+type CreateSerializationException = (err: z.ZodError, executionContext: ExecutionContext) => unknown;
+/** Public options accepted by `ZodNestModule.forRoot()`. */
+interface ZodNestModuleOptions {
+    createValidationException?: CreateValidationException$1;
+    createSerializationException?: CreateSerializationException;
+    /**
+     * Failure-only validation logging. `true` enables both input and output;
+     * the granular form lets each side be toggled independently. Default: off.
+     */
+    validationLogs?: boolean | {
+        input?: boolean;
+        output?: boolean;
+    };
+    /** Override Nest's built-in `Logger` (e.g. pino/winston adapter). */
+    logger?: LoggerService;
+    /**
+     * Keys whose values get scrubbed from logged input/response objects.
+     * Matched case-insensitively at any depth. Supplying this option
+     * REPLACES the default list (no merge).
+     */
+    redactKeys?: readonly string[];
+    /**
+     * Maximum size in bytes (UTF-8) for any single logged value. Oversized
+     * values become `{ _truncated: true, _originalBytes, _preview }`.
+     */
+    maxLoggedValueBytes?: number;
+}
+/**
+ * Resolved options consumed by pipe + interceptor. `forRoot()` builds this
+ * once and stuffs it into a provider for the `ZOD_NEST_OPTIONS` injection
+ * token; downstream code never re-checks the raw `validationLogs` flag.
+ */
+interface NormalizedZodNestOptions {
+    createValidationException: CreateValidationException$1 | undefined;
+    createSerializationException: CreateSerializationException | undefined;
+    /** No-op when `validationLogs.input` resolved to false. */
+    logInputFailure: LogValidationFailure;
+    /** No-op when `validationLogs.output` resolved to false. */
+    logOutputFailure: LogValidationFailure;
+}
+declare const DEFAULT_REDACT_KEYS: readonly string[];
+declare const DEFAULT_MAX_LOGGED_VALUE_BYTES = 4096;
+/** DI token for `NormalizedZodNestOptions`. */
+declare const ZOD_NEST_OPTIONS: unique symbol;
+
+/**
+ * Build the exception thrown by `ZodValidationPipe` on validation failure.
+ * Receives Zod's error and the NestJS argument metadata; returns anything
+ * `throw`-able (typically a NestJS `HttpException` subclass).
+ */
+type CreateValidationException = (zodError: z.ZodError, argMetadata: ArgumentMetadata) => unknown;
+interface ZodValidationPipeOptions {
+    schema?: z.ZodType | ZodDto;
+    createValidationException?: CreateValidationException;
+}
+/**
+ * Constructor input for `ZodValidationPipe`. Discriminated at runtime:
+ * - `undefined` → metatype-driven (read DTO from handler arg's metatype)
+ * - a class with `[ZOD_DTO_SYMBOL]` → explicit DTO
+ * - a Zod schema (has `_zod` internals) → raw schema
+ * - anything else → options object
+ */
+type ZodValidationPipeArg = z.ZodType | ZodDto | ZodValidationPipeOptions;
+
+declare class ZodValidationPipe implements PipeTransform {
+    private readonly explicitSchema;
+    private readonly explicitDtoName;
+    private readonly createValidationException;
+    private readonly logInputFailure;
+    constructor(arg?: ZodValidationPipeArg, moduleOptions?: NormalizedZodNestOptions);
+    transform(value: unknown, metadata: ArgumentMetadata): Promise<unknown>;
+    private resolveSchema;
+    private resolveDtoLabel;
+    private static parseArg;
+}
+
+/**
+ * Public metadata key for the array of `ResponseVariant` records attached
+ * to handler methods by `@ZodResponse(...)`. Symbol.for() so external
+ * consumers (e.g. custom interceptors or doc builders) can read the same
+ * registry across realms.
+ */
+declare const ZOD_RESPONSES_METADATA_KEY: unique symbol;
+type ResponseVariantKind = 'single' | 'array' | 'tuple';
+/**
+ * Description payload accepted by `@ZodResponse(...)` and passed through to
+ * Phase 2e's `@ApiResponse(...)` emitter. String form is shorthand for
+ * `{ description }`; the object form lets users declare OpenAPI response
+ * `headers` / `links` alongside the description.
+ */
+type ZodResponseDescription = string | {
+    description: string;
+    headers?: Record<string, unknown>;
+    links?: Record<string, unknown>;
+};
+/**
+ * One variant record per `@ZodResponse(...)` call. `dto` is kept alongside
+ * `validationSchema` so Phase 2e can emit `@ApiResponse({ type })` without
+ * unwrapping the runtime-only `z.array(...)` / `z.tuple([...])` wrapper.
+ *
+ * `status` is `undefined` when the user didn't pass one explicitly — the
+ * effective status is resolved lazily by `resolveEffectiveStatus(variant,
+ * handler)` because `@ZodResponse` runs *before* NestJS' route decorators
+ * (`@Get`, `@Post`, ...) under TypeScript's bottom-up application order,
+ * so `METHOD_METADATA` is not yet set when the decorator evaluates.
+ */
+interface ResponseVariant {
+    status: number | undefined;
+    kind: ResponseVariantKind;
+    dto: ZodDto | readonly ZodDto[];
+    validationSchema: z.ZodType;
+    description?: ZodResponseDescription;
+    passthroughOnError: boolean;
+}
+
+/**
+ * Accepted shapes for `@ZodResponse({ type })`:
+ * - `Dto` → validates as `Dto.schema` (single-DTO response).
+ * - `[Dto]` (length 1) → validates as `z.array(Dto.schema)`; matches Nest's
+ *   `@ApiResponse({ isArray: true })` convention without minting a separate
+ *   `*sDto` id.
+ * - `[A, B, ...]` (length ≥ 2) → validates as `z.tuple([A.schema, B.schema, ...])`;
+ *   surfaces as an OpenAPI 3.1 `prefixItems` tuple in Phase 2e.
+ *
+ * Empty arrays and non-DTO elements throw `TypeError` at decoration time
+ * so typos surface at module load, not the first request.
+ */
+type ZodResponseType = ZodDto | readonly [ZodDto, ...ZodDto[]];
+interface ZodResponseOptions {
+    status?: number;
+    type: ZodResponseType;
+    description?: ZodResponseDescription;
+    passthroughOnError?: boolean;
+}
+/**
+ * Method-only decorator. Declares a typed response variant for the handler.
+ * Stack multiple decorations to declare per-status types; lookup at runtime
+ * is by `response.statusCode === variant.status`.
+ *
+ * The wrapped Zod schema (array / tuple) is built once at decoration time
+ * and stored on the variant record — no per-request schema construction.
+ */
+declare const ZodResponse: (opts: ZodResponseOptions) => MethodDecorator;
+
+declare class ZodSerializerInterceptor implements NestInterceptor {
+    private readonly reflector;
+    private readonly logOutputFailure;
+    private readonly createSerializationException;
+    constructor(reflector: Reflector, options?: NormalizedZodNestOptions);
+    intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+    private transform;
+}
+
+/**
+ * Compute the default HTTP status code for a handler when `@ZodResponse(...)`
+ * is invoked without an explicit `status`. Lookup order (highest → lowest):
+ *
+ * 1. `@HttpCode(n)` on the handler — explicit per-handler status override.
+ *    NestJS sets `HTTP_CODE_METADATA` to the numeric status when present.
+ * 2. HTTP method default — `POST` → `201`, everything else → `200`.
+ *
+ * The method default itself falls back to `200` when `METHOD_METADATA` is
+ * absent — pinned by tests so a future NestJS rename surfaces as a test
+ * failure rather than a silent regression.
+ */
+declare const defaultStatusFor: (handler: object) => number;
+/**
+ * Resolve the effective status code for a variant. Precedence chain:
+ *
+ * 1. Explicit `@ZodResponse({ status })` on the decorator call — `variant.status`.
+ * 2. `@HttpCode(n)` on the handler — read via `defaultStatusFor()` at runtime.
+ * 3. HTTP method default (POST → 201, others → 200) — also via `defaultStatusFor()`.
+ *
+ * Resolution is deferred to request time because `@ZodResponse` runs before
+ * NestJS' route + `@HttpCode` decorators — none of their metadata is set
+ * when the decorator evaluates.
+ */
+declare const resolveEffectiveStatus: (variant: ResponseVariant, handler: object) => number;
+
+/**
+ * Central wiring for the zod-nest pipe + interceptor. Call
+ * `ZodNestModule.forRoot(options?)` from your root `AppModule` to register
+ * `APP_PIPE` (`ZodValidationPipe`) and `APP_INTERCEPTOR`
+ * (`ZodSerializerInterceptor`) globally, with shared options for
+ * validation logging, redaction, and exception factories.
+ *
+ * `forRoot()` is optional — the pipe and interceptor also work as
+ * regular `APP_PIPE` / `APP_INTERCEPTOR` providers if you prefer to
+ * wire them manually; `@Optional()` injection of `ZOD_NEST_OPTIONS`
+ * falls through to safe defaults.
+ *
+ * Marked `global` so the `ZOD_NEST_OPTIONS` token is injectable from
+ * feature modules (e.g. a custom pipe that wants the same logger /
+ * redact list as the module-wired one).
+ */
+declare class ZodNestModule {
+    static forRoot(options?: ZodNestModuleOptions): DynamicModule;
+}
+
+export { COMPONENTS_SCHEMAS_PREFIX, type CreateSerializationException, type CreateValidationException, type CreateZodDtoOptions, DEFAULT_MAX_LOGGED_VALUE_BYTES, DEFAULT_REDACT_KEYS, type Io, type NormalizedZodNestOptions, type Override, type OverrideContext, type ResponseVariant, type ResponseVariantKind, type SchemaObject, type ToOpenApiOptions, type ToOpenApiResult, ZOD_DTO_SYMBOL, ZOD_NEST_DTO_EXTENSION, ZOD_NEST_ERROR_DUPLICATE_ID, ZOD_NEST_ERROR_EXTENSION, ZOD_NEST_OPTIONS, ZOD_RESPONSES_METADATA_KEY, type ZodDto, type ZodDtoMarker, ZodNestError, ZodNestModule, type ZodNestModuleOptions, type ZodNestRegistry, ZodNestUnrepresentableError, ZodResponse, type ZodResponseDescription, type ZodResponseOptions, type ZodResponseType, ZodSerializationException, ZodSerializerInterceptor, ZodValidationException, ZodValidationPipe, type ZodValidationPipeArg, type ZodValidationPipeOptions, createRegistry, createZodDto, defaultRegistry, defaultStatusFor, isZodDto, isZodDtoMarker, makeZodDtoMarker, resolveEffectiveStatus, toOpenApi };