express-zod-api 28.7.4 → 29.0.0-beta.2

package/dist/index.d.ts

@@ -3,7 +3,14 @@ import { HttpError } from "http-errors";
 import express, { CookieOptions, IRouter, NextFunction, Request, RequestHandler, Response } from "express";
 import http from "node:http";
 import { ServerOptions } from "node:https";
-import { OpenApiBuilder, ReferenceObject, SchemaObject, TagObject } from "openapi3-ts/oas31";
+import {
+  InfoObject,
+  OpenApiBuilder,
+  ReferenceObject,
+  SchemaObjectValue,
+  ServerObject,
+  TagObject,
+} from "openapi3-ts/oas32";
 import { RequestOptions, ResponseOptions } from "node-mocks-http";
 import compression from "compression";
 import fileUpload from "express-fileupload";
@@ -11,12 +18,12 @@ import cookieParser from "cookie-parser";
 import { ListenOptions } from "node:net";
 import { AugmentedRequest, Options, RateLimitInfo, RateLimitRequestHandler } from "express-rate-limit";
 import ts from "typescript";
-declare const methods: ("get" | "post" | "put" | "delete" | "patch")[];
-declare const clientMethods: ("get" | "post" | "put" | "delete" | "patch" | "head")[];
+declare const methods: ("get" | "post" | "put" | "delete" | "patch" | "query")[];
+declare const clientMethods: ("get" | "post" | "put" | "delete" | "patch" | "head" | "query")[];
 /**
  * @desc Methods supported by the framework API to produce Endpoints on EndpointsFactory.
  * @see BuildProps
- * @example "get" | "post" | "put" | "delete" | "patch"
+ * @example "get" | "post" | "put" | "delete" | "patch" | "query"
  * */
 type Method = (typeof methods)[number];
 /**
@@ -148,181 +155,6 @@ type FinalInputSchema<FIN extends IOSchema | undefined, BIN extends IOSchema> =
   FIN extends IOSchema ? FIN : BIN,
   BIN
 >;
-type LogicalOr<T> = {
-  or: T[];
-};
-type LogicalAnd<T> = {
-  and: T[];
-};
-type LogicalContainer<T> = LogicalOr<T | LogicalAnd<T>> | LogicalAnd<T | LogicalOr<T>> | T;
-interface BasicSecurity {
-  type: "basic";
-}
-interface BearerSecurity {
-  type: "bearer";
-  format?: "JWT" | string;
-}
-interface InputSecurity<K extends string> {
-  type: "input";
-  name: K;
-}
-interface HeaderSecurity {
-  type: "header";
-  name: string;
-}
-interface CookieSecurity {
-  type: "cookie";
-  name: string;
-}
-/**
- * @see https://swagger.io/docs/specification/authentication/openid-connect-discovery/
- * @desc available scopes has to be provided via the specified URL
- */
-interface OpenIdSecurity {
-  type: "openid";
-  url: string;
-}
-interface AuthUrl {
-  /**
-   * @desc The authorization URL to use for this flow. Can be relative to the API server URL.
-   * @see https://swagger.io/docs/specification/api-host-and-base-path/
-   */
-  authorizationUrl: string;
-}
-interface TokenUrl {
-  /** @desc The token URL to use for this flow. Can be relative to the API server URL. */
-  tokenUrl: string;
-}
-interface RefreshUrl {
-  /** @desc The URL to be used for obtaining refresh tokens. Can be relative to the API server URL. */
-  refreshUrl?: string;
-}
-interface Scopes<K extends string> {
-  /** @desc The available scopes for the OAuth2 security and their short descriptions. Optional. */
-  scopes?: Record<K, string>;
-}
-type AuthCodeFlow<S extends string> = AuthUrl & TokenUrl & RefreshUrl & Scopes<S>;
-type ImplicitFlow<S extends string> = AuthUrl & RefreshUrl & Scopes<S>;
-type PasswordFlow<S extends string> = TokenUrl & RefreshUrl & Scopes<S>;
-type ClientCredFlow<S extends string> = TokenUrl & RefreshUrl & Scopes<S>;
-/**
- * @see https://swagger.io/docs/specification/authentication/oauth2/
- */
-interface OAuth2Security<S extends string> {
-  type: "oauth2";
-  flows?: {
-    /** @desc Authorization Code flow (previously called accessCode in OpenAPI 2.0) */
-    authorizationCode?: AuthCodeFlow<S>;
-    /** @desc Implicit flow */
-    implicit?: ImplicitFlow<S>;
-    /** @desc Resource Owner Password flow */
-    password?: PasswordFlow<S>;
-    /** @desc Client Credentials flow (previously called application in OpenAPI 2.0) */
-    clientCredentials?: ClientCredFlow<S>;
-  };
-}
-/**
- * @desc Middleware security schema descriptor
- * @param K is an optional input field used by InputSecurity
- * @param S is an optional union of scopes used by OAuth2Security
- * */
-type Security<K extends string = string, S extends string = string> =
-  | BasicSecurity
-  | BearerSecurity
-  | InputSecurity<K>
-  | HeaderSecurity
-  | CookieSecurity
-  | OpenIdSecurity
-  | OAuth2Security<S>;
-type Handler$2<IN, CTX, RET> = (params: {
-  /** @desc The inputs from the enabled input sources validated against the input schema of the Middleware. */
-  input: IN;
-  /**
-   * @desc The returns of the previously executed Middlewares (typed when chaining Middlewares).
-   * @link https://github.com/RobinTail/express-zod-api/discussions/1250
-   * */
-  ctx: CTX;
-  /** @link https://expressjs.com/en/5x/api.html#req */
-  request: Request;
-  /** @link https://expressjs.com/en/5x/api.html#res */
-  response: Response;
-  /** @desc The instance of the configured logger. */
-  logger: ActualLogger;
-}) => Promise<RET>;
-declare abstract class AbstractMiddleware {
-  abstract execute(params: {
-    input: unknown;
-    ctx: FlatObject;
-    request: Request;
-    response: Response;
-    logger: ActualLogger;
-  }): Promise<FlatObject>;
-}
-/**
- * @desc A Middleware that validates its input schema, executes its handler, and returns context properties available to
- *       next middlewares and the Endpoint handler. Can also declare security schemas for Documentation.
- * @see EndpointsFactory#addMiddleware
- * */
-declare class Middleware<
-  CTX extends FlatObject,
-  RET extends FlatObject,
-  SCO extends string,
-  IN extends IOSchema | undefined = undefined,
-> extends AbstractMiddleware {
-  constructor({
-    input,
-    security,
-    handler,
-  }: {
-    /**
-     * @desc Input schema of the Middleware, combining properties from all the enabled input sources
-     * @default undefined
-     * @see defaultInputSources
-     * */
-    input?: IN;
-    /**
-     * @desc Declaration of the security schemas implemented within the handler (used by Documentation).
-     * @see Documentation
-     * */
-    security?: LogicalContainer<Security<Extract<keyof z.input<IN>, string>, SCO>>;
-    /** @desc The handler returning a context available to Endpoints. */
-    handler: Handler$2<z.output<IN>, CTX, RET>;
-  });
-  /** @throws InputValidationError */
-  execute({
-    input,
-    ...rest
-  }: {
-    input: unknown;
-    ctx: CTX;
-    request: Request;
-    response: Response;
-    logger: ActualLogger;
-  }): Promise<RET>;
-}
-/**
- * @desc A wrapper around native Express middlewares that converts them into the framework's Middleware instances.
- *       Optionally, a `provider` can extend the context, and a `transformer` can convert caught errors.
- * @see EndpointsFactory#addExpressMiddleware
- * */
-declare class ExpressMiddleware<R extends Request, S extends Response, RET extends FlatObject> extends Middleware<
-  FlatObject,
-  RET,
-  string
-> {
-  constructor(
-    nativeMw: (request: R, response: S, next: NextFunction) => any,
-    {
-      provider,
-      transformer,
-    }?: {
-      /** @desc Extracts context properties from request and response after the native middleware execution. */
-      provider?: (request: R, response: S) => RET | Promise<RET>;
-      /** @desc Transforms errors caught from the native middleware before they propagate further. */
-      transformer?: (err: Error) => Error;
-    },
-  );
-}
 type ResultSchema<R extends Result> = R extends Result<infer S> ? S : never;
 type DiscriminatedResult =
   | {
@@ -338,7 +170,7 @@ type DiscriminatedResult =
  * @example Error —> InternalServerError(500)
  * */
 declare const ensureHttpError: (error: Error) => HttpError;
-type Handler$1<RES = unknown> = (
+type Handler$2<RES = unknown> = (
   params: DiscriminatedResult & {
     /** null in case of failure to parse or to find the matching endpoint (error: not found) */
     input: FlatObject | null;
@@ -357,8 +189,8 @@ type Result<S extends z.ZodType = z.ZodType> = S | ApiResponse<S> | ApiResponse<
 /** @desc A function that lazily produces a Result definition. */
 type LazyResult<R extends Result, A extends unknown[] = []> = (...args: A) => R;
 declare abstract class AbstractResultHandler {
-  protected constructor(handler: Handler$1);
-  execute(...params: Parameters<Handler$1>): Promise<void>;
+  protected constructor(handler: Handler$2);
+  execute(...params: Parameters<Handler$2>): Promise<void>;
 }
 /**
  * @desc The entity responsible to respond consistently. Accepts positive and negative Result definitions.
@@ -372,7 +204,7 @@ declare class ResultHandler<POS extends Result, NEG extends Result> extends Abst
     /** @desc A description of the API response in case of error (schema, status code, MIME type) */
     negative: NEG | LazyResult<NEG>;
     /** @desc The actual implementation to transmit the response in any case */
-    handler: Handler$1<z.output<ResultSchema<POS> | ResultSchema<NEG>>>;
+    handler: Handler$2<z.output<ResultSchema<POS> | ResultSchema<NEG>>>;
   });
 }
 /**
@@ -414,90 +246,21 @@ declare const arrayResultHandler: ResultHandler<
     mimeType: string;
   }
 >;
-type OriginalStatic = typeof express.static;
-declare class ServeStatic {
-  constructor(...params: Parameters<OriginalStatic>);
-}
 /** @desc Returns child logger for the given request (if configured) or the configured logger otherwise */
 type GetLogger = (request?: Request) => ActualLogger;
-/**
- * @example { v1: { books: { ":bookId": getBookEndpoint } } }
- * @example { "v1/books/:bookId": getBookEndpoint }
- * @example { "get /v1/books/:bookId": getBookEndpoint }
- * @example { v1: { "patch /books/:bookId": changeBookEndpoint } }
- * @example { dependsOnMethod: { get: retrieveEndpoint, post: createEndpoint } }
- * @see CommonConfig.recognizeMethodDependentRoutes
- * */
-interface Routing {
-  [K: string]: Routing | AbstractEndpoint | ServeStatic;
-}
-type Handler<IN, OUT, CTX> = (params: {
-  /** @desc The inputs from the enabled input sources validated against the final input schema (incl. Middlewares) */
-  input: IN;
-  /** @desc The returns of the assigned Middlewares */
-  ctx: CTX;
-  /** @desc The instance of the configured logger */
-  logger: ActualLogger;
-}) => Promise<OUT>;
-declare abstract class AbstractEndpoint {
-  /** @desc Enables nested routes within the path assigned to the subject */
-  nest(routing: Routing): Routing;
-  /** @desc Marks the route as deprecated (makes a copy of the endpoint) */
-  abstract deprecated(): this;
-  abstract execute(params: {
-    request: Request;
-    response: Response;
-    logger: ActualLogger;
-    config: CommonConfig;
-  }): Promise<void>;
-}
-declare class Endpoint<IN extends IOSchema, OUT extends IOSchema, CTX extends FlatObject> extends AbstractEndpoint {
-  constructor(def: {
-    deprecated?: boolean;
-    middlewares?: AbstractMiddleware[];
-    inputSchema: IN;
-    outputSchema: OUT;
-    handler: Handler<z.output<IN>, z.input<OUT>, CTX>;
-    resultHandler: AbstractResultHandler;
-    description?: string;
-    summary?: string;
-    getOperationId?: (method: ClientMethod) => string | undefined;
-    methods?: Method[];
-    scopes?: string[];
-    tags?: string[];
-  });
-  deprecated(): this;
-  execute({
-    request,
-    response,
-    logger,
-    config,
-  }: {
-    request: Request;
-    response: Response;
-    logger: ActualLogger;
-    config: CommonConfig;
-  }): Promise<undefined>;
-}
 type InputSource = keyof Pick<Request, "query" | "body" | "files" | "params" | "headers" | "cookies" | "signedCookies">;
 type InputSources = Record<Method, InputSource[]>;
-type Headers = Record<string, string>;
-type HeadersProvider = (params: {
-  /** @desc The default headers to be overridden. */
-  defaultHeaders: Headers;
-  request: Request;
-  endpoint: AbstractEndpoint;
-  logger: ActualLogger;
-}) => Headers | Promise<Headers>;
 type ChildLoggerProvider = (params: { request: Request; parent: ActualLogger }) => ActualLogger | Promise<ActualLogger>;
 type LogAccess = (request: Request, logger: ActualLogger) => void;
 interface CommonConfig {
   /**
    * @desc Enables cross-origin resource sharing.
+   * @desc You can provide custom middleware or the `cors` package.
+   * @example cors({ origin: "https://example.com" }) // import cors from "cors"
    * @link https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS
-   * @desc You can override the default CORS headers by setting up a provider function here.
+   * @link https://www.npmjs.com/package/cors
    */
-  cors: boolean | HeadersProvider;
+  cors: boolean | RequestHandler;
   /**
    * @desc Controls how to respond to a request to an existing endpoint with an invalid HTTP method.
    * @example true — respond with status code 405 and "Allow" header containing a list of valid methods
@@ -599,12 +362,11 @@ interface GracefulOptions {
   /** @desc The hook to call after the server was closed, but before terminating the process. */
   beforeExit?: () => void | Promise<void>;
 }
-/** @todo consider removing Promise to make createServer sync in next major */
 type ServerHook = (params: {
   app: IRouter;
   /** @desc Returns child logger for the given request (if configured) or the configured logger otherwise */
   getLogger: GetLogger;
-}) => void | Promise<void>;
+}) => void;
 interface HttpConfig {
   /** @desc Port, UNIX socket or custom options. */
   listen: number | string | ListenOptions;
@@ -619,7 +381,7 @@ interface ServerConfig extends CommonConfig {
   /** @desc HTTPS server configuration. */
   https?: HttpsConfig;
   /**
-   * @desc Custom JSON parser.
+   * @desc Custom JSON parser applied to all incoming requests.
    * @default express.json()
    * @link https://expressjs.com/en/5x/api.html#express.json
    * */
@@ -651,19 +413,25 @@ interface ServerConfig extends CommonConfig {
    */
   queryParser?: "simple" | "extended" | ((query: string) => object);
   /**
-   * @desc Custom raw parser (assigns Buffer to request body)
+   * @desc Custom parser for Buffer payloads applied to all incoming requests.
    * @default express.raw()
    * @link https://expressjs.com/en/5x/api.html#express.raw
    * */
   rawParser?: RequestHandler;
   /**
-   * @desc Custom parser for URL Encoded requests used for submitting HTML forms
+   * @desc Custom parser for URL Encoded requests applied to all incoming requests.
    * @default express.urlencoded()
    * @link https://expressjs.com/en/5x/api.html#express.urlencoded
    * */
   formParser?: RequestHandler;
   /**
-   * @desc A code to execute before processing the Routing of your API (and before parsing).
+   * @desc A code to execute before the installation of parsers (compression, cookies, CORS, body).
+   * @example ({ app }) => { app.use(helmet()); }
+   * */
+  beforeParsers?: ServerHook;
+  /**
+   * @desc A code to execute before processing the Routing of your API.
+   * @desc Runs after compression, cookies, CORS and body parsers are installed.
    * @desc This can be a good place for express middlewares establishing their own routes.
    * @desc It can help to avoid making a DIY solution based on the attachRouting() approach.
    * @example ({ app }) => { app.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument)); }
@@ -685,6 +453,199 @@ interface AppConfig extends CommonConfig {
 }
 declare function createConfig(config: ServerConfig): ServerConfig;
 declare function createConfig(config: AppConfig): AppConfig;
+type LogicalOr<T> = {
+  or: T[];
+};
+type LogicalAnd<T> = {
+  and: T[];
+};
+type LogicalContainer<T> = LogicalOr<T | LogicalAnd<T>> | LogicalAnd<T | LogicalOr<T>> | T;
+interface BasicSecurity {
+  type: "basic";
+}
+interface BearerSecurity {
+  type: "bearer";
+  format?: "JWT" | string;
+}
+interface InputSecurity<K extends string> {
+  type: "input";
+  name: K;
+}
+interface HeaderSecurity {
+  type: "header";
+  name: string;
+}
+interface CookieSecurity {
+  type: "cookie";
+  name: string;
+}
+/**
+ * @see https://swagger.io/docs/specification/authentication/openid-connect-discovery/
+ * @desc available scopes has to be provided via the specified URL
+ */
+interface OpenIdSecurity {
+  type: "openid";
+  url: string;
+}
+interface AuthUrl {
+  /**
+   * @desc The authorization URL to use for this flow. Can be relative to the API server URL.
+   * @see https://swagger.io/docs/specification/api-host-and-base-path/
+   */
+  authorizationUrl: string;
+}
+interface DeviceAuthUrl {
+  /** @desc The device authorization URL to use for this flow (RFC 8628). Can be relative to the API server URL. */
+  deviceAuthorizationUrl: string;
+}
+interface TokenUrl {
+  /** @desc The token URL to use for this flow. Can be relative to the API server URL. */
+  tokenUrl: string;
+}
+interface RefreshUrl {
+  /** @desc The URL to be used for obtaining refresh tokens. Can be relative to the API server URL. */
+  refreshUrl?: string;
+}
+interface Scopes<K extends string> {
+  /** @desc The available scopes for the OAuth2 security and their short descriptions. Optional. */
+  scopes?: Record<K, string>;
+}
+type AuthCodeFlow<S extends string> = AuthUrl & TokenUrl & RefreshUrl & Scopes<S>;
+type ImplicitFlow<S extends string> = AuthUrl & RefreshUrl & Scopes<S>;
+type PasswordFlow<S extends string> = TokenUrl & RefreshUrl & Scopes<S>;
+type ClientCredFlow<S extends string> = TokenUrl & RefreshUrl & Scopes<S>;
+type DeviceAuthFlow<S extends string> = DeviceAuthUrl & TokenUrl & RefreshUrl & Scopes<S>;
+/**
+ * @see https://swagger.io/docs/specification/authentication/oauth2/
+ */
+interface OAuth2Security<S extends string> {
+  type: "oauth2";
+  /**
+   * @desc URL to OAuth 2.0 Authorization Server metadata document
+   * @link https://www.rfc-editor.org/rfc/rfc8414
+   * */
+  oauth2MetadataUrl?: string;
+  flows?: {
+    /** @desc Authorization Code flow (previously called accessCode in OpenAPI 2.0) */
+    authorizationCode?: AuthCodeFlow<S>;
+    /** @desc Implicit flow */
+    implicit?: ImplicitFlow<S>;
+    /** @desc Resource Owner Password flow */
+    password?: PasswordFlow<S>;
+    /** @desc Client Credentials flow (previously called application in OpenAPI 2.0) */
+    clientCredentials?: ClientCredFlow<S>;
+    /**
+     * @desc Device Authorization flow (OAuth 2.0 Device Authorization Grant)
+     * @link https://oauth.net/2/device-flow/
+     * */
+    deviceAuthorization?: DeviceAuthFlow<S>;
+  };
+}
+/**
+ * @desc Middleware security schema descriptor
+ * @param K is an optional input field used by InputSecurity
+ * @param S is an optional union of scopes used by OAuth2Security
+ * */
+type Security<K extends string = string, S extends string = string> = (
+  | BasicSecurity
+  | BearerSecurity
+  | InputSecurity<K>
+  | HeaderSecurity
+  | CookieSecurity
+  | OpenIdSecurity
+  | OAuth2Security<S>
+) & {
+  deprecated?: boolean;
+};
+type Handler$1<IN, CTX, RET> = (params: {
+  /** @desc The inputs from the enabled input sources validated against the input schema of the Middleware. */
+  input: IN;
+  /**
+   * @desc The returns of the previously executed Middlewares (typed when chaining Middlewares).
+   * @link https://github.com/RobinTail/express-zod-api/discussions/1250
+   * */
+  ctx: CTX;
+  /** @link https://expressjs.com/en/5x/api.html#req */
+  request: Request;
+  /** @link https://expressjs.com/en/5x/api.html#res */
+  response: Response;
+  /** @desc The instance of the configured logger. */
+  logger: ActualLogger;
+}) => Promise<RET>;
+declare abstract class AbstractMiddleware {
+  abstract execute(params: {
+    input: unknown;
+    ctx: FlatObject;
+    request: Request;
+    response: Response;
+    logger: ActualLogger;
+  }): Promise<FlatObject>;
+}
+/**
+ * @desc A Middleware that validates its input schema, executes its handler, and returns context properties available to
+ *       next middlewares and the Endpoint handler. Can also declare security schemas for Documentation.
+ * @see EndpointsFactory#addMiddleware
+ * */
+declare class Middleware<
+  CTX extends FlatObject,
+  RET extends FlatObject,
+  SCO extends string,
+  IN extends IOSchema | undefined = undefined,
+> extends AbstractMiddleware {
+  constructor({
+    input,
+    security,
+    handler,
+  }: {
+    /**
+     * @desc Input schema of the Middleware, combining properties from all the enabled input sources
+     * @default undefined
+     * @see defaultInputSources
+     * */
+    input?: IN;
+    /**
+     * @desc Declaration of the security schemas implemented within the handler (used by Documentation).
+     * @see Documentation
+     * */
+    security?: LogicalContainer<Security<Extract<keyof z.input<IN>, string>, SCO>>;
+    /** @desc The handler returning a context available to Endpoints. */
+    handler: Handler$1<z.output<IN>, CTX, RET>;
+  });
+  /** @throws InputValidationError */
+  execute({
+    input,
+    ...rest
+  }: {
+    input: unknown;
+    ctx: CTX;
+    request: Request;
+    response: Response;
+    logger: ActualLogger;
+  }): Promise<RET>;
+}
+/**
+ * @desc A wrapper around native Express middlewares that converts them into the framework's Middleware instances.
+ *       Optionally, a `provider` can extend the context, and a `transformer` can convert caught errors.
+ * @see EndpointsFactory#addExpressMiddleware
+ * */
+declare class ExpressMiddleware<R extends Request, S extends Response, RET extends FlatObject> extends Middleware<
+  FlatObject,
+  RET,
+  string
+> {
+  constructor(
+    nativeMw: (request: R, response: S, next: NextFunction) => any,
+    {
+      provider,
+      transformer,
+    }?: {
+      /** @desc Extracts context properties from request and response after the native middleware execution. */
+      provider?: (request: R, response: S) => RET | Promise<RET>;
+      /** @desc Transforms errors caught from the native middleware before they propagate further. */
+      transformer?: (err: Error) => Error;
+    },
+  );
+}
 /**
  * @desc Directives shared by both request and response Cache-Control headers.
  * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control#cache_directives
@@ -853,6 +814,69 @@ declare const createCacheMiddleware: (defaultPolicy?: CachePolicy) => Middleware
   string,
   undefined
 >;
+type OriginalStatic = typeof express.static;
+declare class ServeStatic {
+  constructor(...params: Parameters<OriginalStatic>);
+}
+/**
+ * @example { v1: { books: { ":bookId": getBookEndpoint } } }
+ * @example { "v1/books/:bookId": getBookEndpoint }
+ * @example { "get /v1/books/:bookId": getBookEndpoint }
+ * @example { v1: { "patch /books/:bookId": changeBookEndpoint } }
+ * @example { dependsOnMethod: { get: retrieveEndpoint, post: createEndpoint } }
+ * @see CommonConfig.recognizeMethodDependentRoutes
+ * */
+interface Routing {
+  [K: string]: Routing | AbstractEndpoint | ServeStatic;
+}
+type Handler<IN, OUT, CTX> = (params: {
+  /** @desc The inputs from the enabled input sources validated against the final input schema (incl. Middlewares) */
+  input: IN;
+  /** @desc The returns of the assigned Middlewares */
+  ctx: CTX;
+  /** @desc The instance of the configured logger */
+  logger: ActualLogger;
+}) => Promise<OUT>;
+declare abstract class AbstractEndpoint {
+  /** @desc Enables nested routes within the path assigned to the subject */
+  nest(routing: Routing): Routing;
+  /** @desc Marks the route as deprecated (makes a copy of the endpoint) */
+  abstract deprecated(): this;
+  abstract execute(params: {
+    request: Request;
+    response: Response;
+    logger: ActualLogger;
+    config: CommonConfig;
+  }): Promise<void>;
+}
+declare class Endpoint<IN extends IOSchema, OUT extends IOSchema, CTX extends FlatObject> extends AbstractEndpoint {
+  constructor(def: {
+    deprecated?: boolean;
+    middlewares?: AbstractMiddleware[];
+    inputSchema: IN;
+    outputSchema: OUT;
+    handler: Handler<z.output<IN>, z.input<OUT>, CTX>;
+    resultHandler: AbstractResultHandler;
+    description?: string;
+    summary?: string;
+    getOperationId?: (method: ClientMethod) => string | undefined;
+    methods?: Method[];
+    scopes?: string[];
+    tags?: string[];
+  });
+  deprecated(): this;
+  execute({
+    request,
+    response,
+    logger,
+    config,
+  }: {
+    request: Request;
+    response: Response;
+    logger: ActualLogger;
+    config: CommonConfig;
+  }): Promise<undefined>;
+}
 /**
  * @desc Creates a Middleware providing cookie-setting convenience methods.
  * @param baseOptions — Default options applied to every setCookie / clearCookie call.
@@ -1108,13 +1132,13 @@ declare const attachRouting: (
 declare const createServer: (
   config: ServerConfig,
   routing: Routing,
-) => Promise<{
+) => {
   app: import("express-serve-static-core").Express;
   logger: AbstractLogger | BuiltinLogger;
   servers: http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>[];
-}>;
+};
 interface ReqResCommons {
-  makeRef: (key: object | string, value: SchemaObject | ReferenceObject, proposedName?: string) => ReferenceObject;
+  makeRef: (key: object | string, value: SchemaObjectValue | ReferenceObject, proposedName?: string) => ReferenceObject;
   path: string;
   method: ClientMethod;
 }
@@ -1127,22 +1151,16 @@ type Depicter = (
     jsonSchema: z.core.JSONSchema.BaseSchema;
   },
   oasCtx: OpenAPIContext,
-) => z.core.JSONSchema.BaseSchema | SchemaObject;
+) => z.core.JSONSchema.BaseSchema | SchemaObjectValue;
 /** @desc Using defaultIsHeader when returns null or undefined */
 type IsHeader = (name: string, method: ClientMethod, path: string) => boolean | null | undefined;
 type BrandHandling = Record<string | symbol, Depicter>;
-declare const depictTags: (
-  tags: Partial<
-    Record<
-      Tag,
-      | string
-      | {
-          description: string;
-          url?: string;
-        }
-    >
-  >,
-) => TagObject[];
+interface TagDetails extends Pick<TagObject, "summary" | "description" | "externalDocs" | "kind"> {
+  /** @desc shorthand for externalDocs.url */
+  url?: string;
+  parent?: Tag;
+}
+declare const depictTags: (tags: Partial<Record<Tag, string | TagDetails>>) => TagObject[];
 /** @desc Ensures the summary string does not exceed the limit */
 declare const trimSummary: (summary?: string, limit?: number) => string | undefined;
 type Component = `${ResponseVariant}Response` | "requestParameter" | "requestBody";
@@ -1154,9 +1172,10 @@ type Descriptor = (
 ) => string;
 type Summarizer = (params: { summary?: string; description?: string; trim: typeof trimSummary }) => string | undefined;
 interface DocumentationParams {
-  title: string;
-  version: string;
-  serverUrl: string | [string, ...string[]];
+  /** @desc At least title and version properties are required */
+  info: InfoObject;
+  /** @desc Server URL(s) or their complete definitions */
+  server: string | [string, ...string[]] | ServerObject | [ServerObject, ...ServerObject[]];
   routing: Routing;
   config: CommonConfig;
   /**
@@ -1396,11 +1415,6 @@ declare class Integration extends IntegrationBase {
     noBodySchema,
     hasHeadMethod,
   }: IntegrationParams);
-  /**
-   * @deprecated use `new Integration()` without `typescript` option on its argument
-   * @todo remove in the next major — no longer needed
-   * */
-  static create(params: Omit<IntegrationParams, "typescript">): Promise<Integration>;
   print(printerOptions?: ts.PrinterOptions): string;
   printFormatted({ printerOptions, format: userDefined }?: FormattedPrintingOptions): Promise<string>;
 }