@nestia/sdk 12.0.0-dev.20260601.1 → 12.0.0-dev.20260619.1

package/src/module.ts

@@ -1,4 +1,4 @@
-export * from "./INestiaConfig";
-export * from "./NestiaSdkApplication";
-export * from "./NestiaSwaggerComposer";
-export * from "./decorators/OperationMetadata";
+export * from "./INestiaConfig";
+export * from "./NestiaSdkApplication";
+export * from "./NestiaSwaggerComposer";
+export * from "./decorators/OperationMetadata";

package/src/structures/INestiaProject.ts

@@ -1,10 +1,10 @@
-import { INestiaConfig } from "../INestiaConfig";
-import { INestiaSdkInput } from "./INestiaSdkInput";
-import { IReflectOperationError } from "./IReflectOperationError";
-
-export interface INestiaProject {
-  config: INestiaConfig;
-  input: INestiaSdkInput;
-  errors: IReflectOperationError[];
-  warnings: IReflectOperationError[];
-}
+import { INestiaConfig } from "../INestiaConfig";
+import { INestiaSdkInput } from "./INestiaSdkInput";
+import { IReflectOperationError } from "./IReflectOperationError";
+
+export interface INestiaProject {
+  config: INestiaConfig;
+  input: INestiaSdkInput;
+  errors: IReflectOperationError[];
+  warnings: IReflectOperationError[];
+}

package/src/structures/INestiaSdkInput.ts

@@ -1,20 +1,27 @@
-import { RouteInfo, VersionValue } from "@nestjs/common/interfaces";
-
-export interface INestiaSdkInput {
-  controllers: INestiaSdkInput.IController[];
-  globalPrefix?: {
-    prefix: string;
-    exclude?: Array<string | RouteInfo>;
-  };
-  versioning?: {
-    prefix: string;
-    defaultVersion?: VersionValue;
-  };
-}
-export namespace INestiaSdkInput {
-  export interface IController {
-    class: Function;
-    location: string;
-    prefixes: string[];
-  }
-}
+import { RequestMethod } from "@nestjs/common";
+import { VersionValue } from "@nestjs/common/interfaces";
+
+export interface INestiaSdkInput {
+  controllers: INestiaSdkInput.IController[];
+  globalPrefix?: {
+    prefix: string;
+    exclude?: INestiaSdkInput.IGlobalPrefixExclude[];
+  };
+  versioning?: {
+    prefix: string;
+    defaultVersion?: VersionValue;
+  };
+}
+export namespace INestiaSdkInput {
+  export interface IController {
+    class: Function;
+    location: string;
+    prefixes: string[];
+  }
+  export interface IGlobalPrefixExclude {
+    path: string;
+    method?: RequestMethod;
+    requestMethod?: RequestMethod;
+    pathRegex?: RegExp;
+  }
+}

package/src/structures/IOperationMetadata.ts

@@ -1,41 +1,41 @@
-import {
-  IMetadataComponents,
-  IMetadataSchema,
-  ValidationPipe,
-} from "@typia/interface";
-import { IJsDocTagInfo } from "typia";
-
-import { IReflectImport } from "./IReflectImport";
-import { IReflectType } from "./IReflectType";
-
-export interface IOperationMetadata {
-  parameters: IOperationMetadata.IParameter[];
-  success: IOperationMetadata.IResponse;
-  exceptions: IOperationMetadata.IResponse[];
-  description: string | null;
-  jsDocTags: IJsDocTagInfo[];
-}
-export namespace IOperationMetadata {
-  export interface IParameter extends IResponse {
-    name: string;
-    index: number;
-    description: string | null;
-    jsDocTags: IJsDocTagInfo[];
-  }
-  export interface IResponse {
-    type: IReflectType | null;
-    imports: IReflectImport[];
-    primitive: ValidationPipe<ISchema, IError>;
-    resolved: ValidationPipe<ISchema, IError>;
-  }
-
-  export interface ISchema {
-    components: IMetadataComponents;
-    metadata: IMetadataSchema;
-  }
-  export interface IError {
-    name: string;
-    accessor: string | null;
-    messages: string[];
-  }
-}
+import {
+  IMetadataComponents,
+  IMetadataSchema,
+  ValidationPipe,
+} from "@typia/interface";
+import { IJsDocTagInfo } from "typia";
+
+import { IReflectImport } from "./IReflectImport";
+import { IReflectType } from "./IReflectType";
+
+export interface IOperationMetadata {
+  parameters: IOperationMetadata.IParameter[];
+  success: IOperationMetadata.IResponse;
+  exceptions: IOperationMetadata.IResponse[];
+  description: string | null;
+  jsDocTags: IJsDocTagInfo[];
+}
+export namespace IOperationMetadata {
+  export interface IParameter extends IResponse {
+    name: string;
+    index: number;
+    description: string | null;
+    jsDocTags: IJsDocTagInfo[];
+  }
+  export interface IResponse {
+    type: IReflectType | null;
+    imports: IReflectImport[];
+    primitive: ValidationPipe<ISchema, IError>;
+    resolved: ValidationPipe<ISchema, IError>;
+  }
+
+  export interface ISchema {
+    components: IMetadataComponents;
+    metadata: IMetadataSchema;
+  }
+  export interface IError {
+    name: string;
+    accessor: string | null;
+    messages: string[];
+  }
+}

package/src/structures/IReflectController.ts

@@ -1,15 +1,18 @@
-import type { VERSION_NEUTRAL } from "@nestjs/common/interfaces";
-
-import { IReflectHttpOperation } from "./IReflectHttpOperation";
-import { IReflectWebSocketOperation } from "./IReflectWebSocketOperation";
-
-export interface IReflectController {
-  class: Function;
-  prefixes: string[];
-  paths: string[];
-  file: string;
-  versions: Array<string | typeof VERSION_NEUTRAL> | undefined;
-  operations: Array<IReflectHttpOperation | IReflectWebSocketOperation>;
-  security: Record<string, string[]>[];
-  tags: string[];
-}
+import type { VERSION_NEUTRAL } from "@nestjs/common/interfaces";
+
+import { IReflectHttpOperation } from "./IReflectHttpOperation";
+import { IReflectMcpOperation } from "./IReflectMcpOperation";
+import { IReflectWebSocketOperation } from "./IReflectWebSocketOperation";
+
+export interface IReflectController {
+  class: Function;
+  prefixes: string[];
+  paths: string[];
+  file: string;
+  versions: Array<string | typeof VERSION_NEUTRAL> | undefined;
+  operations: Array<
+    IReflectHttpOperation | IReflectWebSocketOperation | IReflectMcpOperation
+  >;
+  security: Record<string, string[]>[];
+  tags: string[];
+}

package/src/structures/IReflectHttpOperation.ts

@@ -1,26 +1,26 @@
-import { VERSION_NEUTRAL } from "@nestjs/common/interfaces";
-import { IJsDocTagInfo } from "typia";
-
-import { IReflectHttpOperationException } from "./IReflectHttpOperationException";
-import { IReflectHttpOperationParameter } from "./IReflectHttpOperationParameter";
-import { IReflectHttpOperationSuccess } from "./IReflectHttpOperationSuccess";
-import { IReflectImport } from "./IReflectImport";
-
-export interface IReflectHttpOperation {
-  protocol: "http";
-  function: Function;
-  name: string;
-  method: string;
-  paths: string[];
-  versions: Array<string | typeof VERSION_NEUTRAL> | undefined;
-  parameters: IReflectHttpOperationParameter[];
-  success: IReflectHttpOperationSuccess;
-  exceptions: Record<string, IReflectHttpOperationException>;
-  security: Record<string, string[]>[];
-  tags: string[];
-  imports: IReflectImport[];
-  operationId: string | undefined;
-  description: string | null;
-  jsDocTags: IJsDocTagInfo[];
-  extensions?: Record<string, any>;
-}
+import { VERSION_NEUTRAL } from "@nestjs/common/interfaces";
+import { IJsDocTagInfo } from "typia";
+
+import { IReflectHttpOperationException } from "./IReflectHttpOperationException";
+import { IReflectHttpOperationParameter } from "./IReflectHttpOperationParameter";
+import { IReflectHttpOperationSuccess } from "./IReflectHttpOperationSuccess";
+import { IReflectImport } from "./IReflectImport";
+
+export interface IReflectHttpOperation {
+  protocol: "http";
+  function: Function;
+  name: string;
+  method: string;
+  paths: string[];
+  versions: Array<string | typeof VERSION_NEUTRAL> | undefined;
+  parameters: IReflectHttpOperationParameter[];
+  success: IReflectHttpOperationSuccess;
+  exceptions: Record<string, IReflectHttpOperationException>;
+  security: Record<string, string[]>[];
+  tags: string[];
+  imports: IReflectImport[];
+  operationId: string | undefined;
+  description: string | null;
+  jsDocTags: IJsDocTagInfo[];
+  extensions?: Record<string, any>;
+}

package/src/structures/IReflectHttpOperationException.ts

@@ -1,18 +1,18 @@
-import { MetadataFactory } from "../internal/legacy";
-import { IMetadataComponents, IMetadataSchema } from "@typia/interface";
-
-import { IReflectType } from "./IReflectType";
-
-export interface IReflectHttpOperationException {
-  // BASIC PROPERTIES
-  status: number | "2XX" | "3XX" | "4XX" | "5XX";
-  description: string | null;
-  example?: any;
-  examples?: Record<string, any>;
-
-  // REFLECTED PROPERTIES
-  type: IReflectType;
-  metadata: IMetadataSchema;
-  components: IMetadataComponents;
-  validate: MetadataFactory.Validator;
-}
+import { MetadataFactory } from "../internal/legacy";
+import { IMetadataComponents, IMetadataSchema } from "@typia/interface";
+
+import { IReflectType } from "./IReflectType";
+
+export interface IReflectHttpOperationException {
+  // BASIC PROPERTIES
+  status: number | "2XX" | "3XX" | "4XX" | "5XX";
+  description: string | null;
+  example?: any;
+  examples?: Record<string, any>;
+
+  // REFLECTED PROPERTIES
+  type: IReflectType;
+  metadata: IMetadataSchema;
+  components: IMetadataComponents;
+  validate: MetadataFactory.Validator;
+}

package/src/structures/IReflectHttpOperationParameter.ts

@@ -1,79 +1,79 @@
-import { MetadataFactory } from "../internal/legacy";
-import {
-  IJsDocTagInfo,
-  IMetadataComponents,
-  IMetadataSchema,
-} from "@typia/interface";
-
-import { IReflectType } from "./IReflectType";
-
-export type IReflectHttpOperationParameter =
-  | IReflectHttpOperationParameter.IBody
-  | IReflectHttpOperationParameter.IHeaders
-  | IReflectHttpOperationParameter.IParam
-  | IReflectHttpOperationParameter.IQuery;
-export namespace IReflectHttpOperationParameter {
-  export interface IBody extends IBase<"body"> {
-    contentType:
-      | "application/json"
-      | "application/x-www-form-urlencoded"
-      | "multipart/form-data"
-      | "text/plain";
-    encrypted: boolean;
-  }
-  export interface IHeaders extends IBase<"headers"> {
-    field: string | null;
-  }
-  export interface IParam extends IBase<"param"> {
-    field: string;
-  }
-  export interface IQuery extends IBase<"query"> {
-    field: string | null;
-  }
-  interface IBase<Category extends string> {
-    category: Category;
-    name: string;
-    index: number;
-    type: IReflectType;
-    metadata: IMetadataSchema;
-    components: IMetadataComponents;
-    validate: MetadataFactory.Validator;
-    example?: any;
-    examples?: Record<string, any>;
-    description: string | null;
-    jsDocTags: IJsDocTagInfo[];
-  }
-
-  /** @internal */
-  export type IPreconfigured =
-    | IPreconfigured.IBody
-    | IPreconfigured.IHeaders
-    | IPreconfigured.IParam
-    | IPreconfigured.IQuery;
-
-  /** @internal */
-  export namespace IPreconfigured {
-    export interface IBody extends IBase<"body"> {
-      field?: string;
-      encrypted?: boolean;
-      contentType:
-        | "application/json"
-        | "application/x-www-form-urlencoded"
-        | "multipart/form-data"
-        | "text/plain";
-    }
-    export interface IHeaders extends IBase<"headers"> {
-      field?: string;
-    }
-    export interface IParam extends IBase<"param"> {
-      field?: string;
-    }
-    export interface IQuery extends IBase<"query"> {
-      field?: string;
-    }
-    interface IBase<Category extends string> {
-      category: Category;
-      index: number;
-    }
-  }
-}
+import { MetadataFactory } from "../internal/legacy";
+import {
+  IJsDocTagInfo,
+  IMetadataComponents,
+  IMetadataSchema,
+} from "@typia/interface";
+
+import { IReflectType } from "./IReflectType";
+
+export type IReflectHttpOperationParameter =
+  | IReflectHttpOperationParameter.IBody
+  | IReflectHttpOperationParameter.IHeaders
+  | IReflectHttpOperationParameter.IParam
+  | IReflectHttpOperationParameter.IQuery;
+export namespace IReflectHttpOperationParameter {
+  export interface IBody extends IBase<"body"> {
+    contentType:
+      | "application/json"
+      | "application/x-www-form-urlencoded"
+      | "multipart/form-data"
+      | "text/plain";
+    encrypted: boolean;
+  }
+  export interface IHeaders extends IBase<"headers"> {
+    field: string | null;
+  }
+  export interface IParam extends IBase<"param"> {
+    field: string;
+  }
+  export interface IQuery extends IBase<"query"> {
+    field: string | null;
+  }
+  interface IBase<Category extends string> {
+    category: Category;
+    name: string;
+    index: number;
+    type: IReflectType;
+    metadata: IMetadataSchema;
+    components: IMetadataComponents;
+    validate: MetadataFactory.Validator;
+    example?: any;
+    examples?: Record<string, any>;
+    description: string | null;
+    jsDocTags: IJsDocTagInfo[];
+  }
+
+  /** @internal */
+  export type IPreconfigured =
+    | IPreconfigured.IBody
+    | IPreconfigured.IHeaders
+    | IPreconfigured.IParam
+    | IPreconfigured.IQuery;
+
+  /** @internal */
+  export namespace IPreconfigured {
+    export interface IBody extends IBase<"body"> {
+      field?: string;
+      encrypted?: boolean;
+      contentType:
+        | "application/json"
+        | "application/x-www-form-urlencoded"
+        | "multipart/form-data"
+        | "text/plain";
+    }
+    export interface IHeaders extends IBase<"headers"> {
+      field?: string;
+    }
+    export interface IParam extends IBase<"param"> {
+      field?: string;
+    }
+    export interface IQuery extends IBase<"query"> {
+      field?: string;
+    }
+    interface IBase<Category extends string> {
+      category: Category;
+      index: number;
+    }
+  }
+}

package/src/structures/IReflectHttpOperationSuccess.ts

@@ -1,21 +1,18 @@
-import { MetadataFactory } from "../internal/legacy";
-import { IMetadataComponents, IMetadataSchema } from "@typia/interface";
-
-import { IReflectType } from "./IReflectType";
-
-export interface IReflectHttpOperationSuccess {
-  type: IReflectType;
-  status: number;
-  contentType:
-    | "application/json"
-    | "text/plain"
-    | "application/x-www-form-urlencoded"
-    | "application/json"
-    | null;
-  encrypted: boolean;
-  components: IMetadataComponents;
-  metadata: IMetadataSchema;
-  validate: MetadataFactory.Validator;
-  example?: any;
-  examples?: Record<string, any>;
-}
+import { IMetadataComponents, IMetadataSchema } from "@typia/interface";
+
+import { MetadataFactory } from "../internal/legacy";
+import { HttpResponseContentTypeUtil } from "../utils/HttpResponseContentTypeUtil";
+import { IReflectType } from "./IReflectType";
+
+export interface IReflectHttpOperationSuccess {
+  type: IReflectType;
+  status: number;
+  contentType: HttpResponseContentTypeUtil.Response;
+  binary: boolean;
+  encrypted: boolean;
+  components: IMetadataComponents;
+  metadata: IMetadataSchema;
+  validate: MetadataFactory.Validator;
+  example?: any;
+  examples?: Record<string, any>;
+}

package/src/structures/IReflectImport.ts

@@ -1,6 +1,6 @@
-export interface IReflectImport {
-  file: string;
-  asterisk: string | null;
-  default: string | null;
-  elements: string[];
-}
+export interface IReflectImport {
+  file: string;
+  asterisk: string | null;
+  default: string | null;
+  elements: string[];
+}

package/src/structures/IReflectMcpOperation.ts

@@ -0,0 +1,38 @@
+import ts from "typescript";
+
+import { IReflectImport } from "./IReflectImport";
+import { IReflectMcpOperationParameter } from "./IReflectMcpOperationParameter";
+import { IReflectType } from "./IReflectType";
+
+/**
+ * Reflected operation metadata for a method decorated with `@McpRoute`.
+ *
+ * Produced by {@link ReflectMcpOperationAnalyzer.analyze}; consumed by
+ * {@link TypedMcpRouteAnalyzer.analyze} to produce the final
+ * {@link ITypedMcpRoute}.
+ */
+export interface IReflectMcpOperation {
+  protocol: "mcp";
+  name: string;
+  toolName: string;
+  title: string | null;
+  toolDescription: string | null;
+  inputSchema: object;
+  outputSchema: object | null;
+  annotations: IReflectMcpOperation.IAnnotations | null;
+  function: Function;
+  parameters: IReflectMcpOperationParameter[];
+  returnType: IReflectType | null;
+  imports: IReflectImport[];
+  description: string | null;
+  jsDocTags: ts.JSDocTagInfo[];
+}
+
+export namespace IReflectMcpOperation {
+  export interface IAnnotations {
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+  }
+}

package/src/structures/IReflectMcpOperationParameter.ts

@@ -0,0 +1,27 @@
+import { IJsDocTagInfo } from "typia";
+
+import { IReflectImport } from "./IReflectImport";
+import { IReflectType } from "./IReflectType";
+
+/**
+ * Parameter descriptor for an MCP tool method. Reflected from
+ * `"nestia/McpRoute/Parameters"` metadata plus compile-time type information
+ * collected by the nestia transformer.
+ */
+export interface IReflectMcpOperationParameter {
+  category: "params";
+  name: string;
+  index: number;
+  type: IReflectType;
+  imports: IReflectImport[];
+  description: string | null;
+  jsDocTags: IJsDocTagInfo[];
+}
+
+export namespace IReflectMcpOperationParameter {
+  /** @internal */
+  export interface IPreconfigured {
+    category: "params";
+    index: number;
+  }
+}

package/src/structures/IReflectOperationError.ts

@@ -1,26 +1,26 @@
-import { IComparable } from "tstl";
-
-import { IOperationMetadata } from "../structures/IOperationMetadata";
-
-export interface IReflectOperationError {
-  file: string;
-  class: string;
-  function: string | null;
-  from: string | null;
-  contents: Array<string | IOperationMetadata.IError>;
-}
-export namespace IReflectOperationError {
-  export class Key implements Pick<IComparable<Key>, "less"> {
-    public constructor(public readonly error: IReflectOperationError) {}
-
-    public less(obj: Key): boolean {
-      if (this.error.file !== obj.error.file)
-        return this.error.file < obj.error.file;
-      else if (this.error.class !== obj.error.class)
-        return this.error.class < obj.error.class;
-      else if (this.error.function !== obj.error.function)
-        return (this.error.function ?? "") < (obj.error.function ?? "");
-      return (this.error.from ?? "") < (obj.error.from ?? "");
-    }
-  }
-}
+import { IComparable } from "tstl";
+
+import { IOperationMetadata } from "../structures/IOperationMetadata";
+
+export interface IReflectOperationError {
+  file: string;
+  class: string;
+  function: string | null;
+  from: string | null;
+  contents: Array<string | IOperationMetadata.IError>;
+}
+export namespace IReflectOperationError {
+  export class Key implements Pick<IComparable<Key>, "less"> {
+    public constructor(public readonly error: IReflectOperationError) {}
+
+    public less(obj: Key): boolean {
+      if (this.error.file !== obj.error.file)
+        return this.error.file < obj.error.file;
+      else if (this.error.class !== obj.error.class)
+        return this.error.class < obj.error.class;
+      else if (this.error.function !== obj.error.function)
+        return (this.error.function ?? "") < (obj.error.function ?? "");
+      return (this.error.from ?? "") < (obj.error.from ?? "");
+    }
+  }
+}

package/src/structures/IReflectType.ts

@@ -1,4 +1,4 @@
-export interface IReflectType {
-  name: string;
-  typeArguments?: IReflectType[];
-}
+export interface IReflectType {
+  name: string;
+  typeArguments?: IReflectType[];
+}