@typia/interface 12.0.0-dev.20260225

package/src/http/IHttpConnection.ts

@@ -0,0 +1,200 @@
+/// <reference lib="dom" />
+
+/**
+ * HTTP connection configuration for remote server communication.
+ *
+ * `IHttpConnection` defines connection settings required to communicate with
+ * remote HTTP servers. This interface is primarily used by `@nestia/fetcher`
+ * and generated SDK functions to establish HTTP connections.
+ *
+ * The {@link host} property specifies the base URL of the target server, while
+ * {@link headers} allows passing custom HTTP headers with each request. For
+ * fine-grained control over fetch behavior, use {@link options} to configure
+ * caching, CORS, credentials, and other fetch API settings.
+ *
+ * In Node.js versions prior to 20 (which lack native fetch), provide a polyfill
+ * like `node-fetch` via the {@link fetch} property.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @author Seungjun We - https://github.com/SeungjunWe
+ */
+export interface IHttpConnection {
+  /**
+   * Base URL of the remote HTTP server.
+   *
+   * Must include protocol (http:// or https://) and may include port. Example:
+   * `"https://api.example.com"` or `"http://localhost:3000"`.
+   */
+  host: string;
+
+  /**
+   * Custom HTTP headers to send with every request.
+   *
+   * Common use cases include authentication tokens, API keys, and content
+   * negotiation headers. Values can be primitives or arrays.
+   */
+  headers?: Record<string, IHttpConnection.HeaderValue>;
+
+  /**
+   * Additional fetch API options.
+   *
+   * Configure caching, CORS mode, credentials handling, and other
+   * fetch-specific behaviors. These options are passed directly to the
+   * underlying fetch call.
+   */
+  options?: IHttpConnection.IOptions;
+
+  /**
+   * Custom fetch function implementation.
+   *
+   * For Node.js versions before 20 that lack native fetch support, provide a
+   * polyfill such as `node-fetch`. This allows the same connection
+   * configuration to work across all Node.js versions.
+   *
+   * @example
+   *   import fetch from "node-fetch";
+   *
+   *   const connection: IHttpConnection = {
+   *     host: "https://api.example.com",
+   *     fetch: fetch as any,
+   *   };
+   */
+  fetch?: typeof fetch;
+}
+export namespace IHttpConnection {
+  /**
+   * Fetch API request options.
+   *
+   * Subset of the standard `RequestInit` interface, excluding properties that
+   * are managed internally (body, headers, method). These options control
+   * caching, CORS, credentials, and request lifecycle behavior.
+   */
+  export interface IOptions {
+    /**
+     * Request cache mode.
+     *
+     * Controls how the request interacts with the browser's HTTP cache.
+     *
+     * - `"default"`: Standard browser caching behavior
+     * - `"no-store"`: Bypass cache completely, don't store response
+     * - `"reload"`: Bypass cache, but store response
+     * - `"no-cache"`: Validate with server before using cache
+     * - `"force-cache"`: Use cache even if stale
+     * - `"only-if-cached"`: Only use cache, fail if not cached
+     */
+    cache?:
+      | "default"
+      | "force-cache"
+      | "no-cache"
+      | "no-store"
+      | "only-if-cached"
+      | "reload";
+
+    /**
+     * Credentials inclusion mode.
+     *
+     * Controls whether cookies and HTTP authentication are sent.
+     *
+     * - `"omit"`: Never send credentials
+     * - `"same-origin"`: Send credentials only for same-origin requests
+     * - `"include"`: Always send credentials, even cross-origin
+     */
+    credentials?: "omit" | "same-origin" | "include";
+
+    /**
+     * Subresource integrity hash for verification.
+     *
+     * A cryptographic hash (e.g., `"sha256-abc123..."`) to verify the fetched
+     * resource hasn't been tampered with. The browser will reject responses
+     * that don't match the expected hash.
+     */
+    integrity?: string;
+
+    /**
+     * Whether to keep the connection alive after page unload.
+     *
+     * When `true`, the request can outlive the page that initiated it. Useful
+     * for analytics or logging requests that should complete even if the user
+     * navigates away.
+     */
+    keepalive?: boolean;
+
+    /**
+     * CORS (Cross-Origin Resource Sharing) mode.
+     *
+     * Controls cross-origin request behavior.
+     *
+     * - `"cors"`: Standard CORS request (requires server support)
+     * - `"no-cors"`: Limited cross-origin request (opaque response)
+     * - `"same-origin"`: Only allow same-origin requests
+     * - `"navigate"`: For navigation requests (used by browsers)
+     */
+    mode?: "cors" | "navigate" | "no-cors" | "same-origin";
+
+    /**
+     * HTTP redirect handling behavior.
+     *
+     * - `"follow"`: Automatically follow redirects (default)
+     * - `"error"`: Throw an error on redirect
+     * - `"manual"`: Return redirect response for manual handling
+     */
+    redirect?: "error" | "follow" | "manual";
+
+    /**
+     * Referrer URL to send with the request.
+     *
+     * Overrides the default referrer. Use empty string to suppress the referrer
+     * header entirely.
+     */
+    referrer?: string;
+
+    /**
+     * Policy for how much referrer information to include.
+     *
+     * Controls what referrer information is sent with requests. More
+     * restrictive policies improve privacy but may break some server-side
+     * analytics or security checks.
+     */
+    referrerPolicy?:
+      | ""
+      | "no-referrer"
+      | "no-referrer-when-downgrade"
+      | "origin"
+      | "origin-when-cross-origin"
+      | "same-origin"
+      | "strict-origin"
+      | "strict-origin-when-cross-origin"
+      | "unsafe-url";
+
+    /**
+     * AbortSignal for request cancellation.
+     *
+     * Connect to an AbortController to enable cancellation of in-flight
+     * requests. When the signal is aborted, the fetch promise rejects with an
+     * AbortError.
+     *
+     * @example
+     *   const controller = new AbortController();
+     *   const options = { signal: controller.signal };
+     *   // Later: controller.abort();
+     */
+    signal?: AbortSignal | null;
+  }
+
+  /**
+   * Allowed types for HTTP header values.
+   *
+   * Supports primitive types (string, boolean, number, bigint) and arrays of
+   * primitives. Arrays are typically joined with commas when sent as HTTP
+   * headers.
+   */
+  export type HeaderValue =
+    | string
+    | boolean
+    | number
+    | bigint
+    | Array<boolean>
+    | Array<number>
+    | Array<bigint>
+    | Array<string>;
+}

package/src/http/IHttpLlmApplication.ts

@@ -0,0 +1,83 @@
+import { OpenApi } from "../openapi/OpenApi";
+import { ILlmSchema } from "../schema/ILlmSchema";
+import { IHttpLlmFunction } from "./IHttpLlmFunction";
+import { IHttpMigrateRoute } from "./IHttpMigrateRoute";
+
+/**
+ * LLM function calling application from OpenAPI document.
+ *
+ * `IHttpLlmApplication` is a collection of {@link IHttpLlmFunction} schemas
+ * converted from {@link OpenApi.IDocument} by `HttpLlm.application()`. Each
+ * OpenAPI operation becomes an LLM-callable function.
+ *
+ * Successful conversions go to {@link functions}, failed ones to {@link errors}
+ * with detailed error messages. Common failure causes:
+ *
+ * - Unsupported schema features (tuples, `oneOf` with incompatible types)
+ * - Missing required fields in OpenAPI document
+ * - Operations marked with `x-samchon-human: true`
+ *
+ * Configure behavior via {@link IHttpLlmApplication.IConfig}:
+ *
+ * - {@link IHttpLlmApplication.IConfig.separate}: Split LLM vs human parameters
+ * - {@link IHttpLlmApplication.IConfig.maxLength}: Function name length limit
+ * - {@link ILlmSchema.IConfig.strict}: OpenAI structured output mode
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export interface IHttpLlmApplication {
+  /** Successfully converted LLM function schemas. */
+  functions: IHttpLlmFunction[];
+
+  /** Operations that failed conversion. */
+  errors: IHttpLlmApplication.IError[];
+
+  /** Configuration used for composition. */
+  config: IHttpLlmApplication.IConfig;
+}
+export namespace IHttpLlmApplication {
+  /** Configuration for HTTP LLM application composition. */
+  export interface IConfig extends ILlmSchema.IConfig {
+    /**
+     * Separates parameters into LLM and human parts.
+     *
+     * Use for file uploads or sensitive data that LLM cannot handle. Return
+     * `true` for human-composed, `false` for LLM-composed.
+     *
+     * @default null
+     */
+    separate: null | ((schema: ILlmSchema) => boolean);
+
+    /**
+     * Maximum function name length. Truncated or UUID if exceeded.
+     *
+     * @default 64
+     */
+    maxLength: number;
+
+    /**
+     * Whether to disallow superfluous properties.
+     *
+     * @default false
+     */
+    equals: boolean;
+  }
+
+  /** Composition error for an operation. */
+  export interface IError {
+    /** HTTP method of the failed operation. */
+    method: "get" | "post" | "put" | "patch" | "delete" | "head";
+
+    /** Path of the failed operation. */
+    path: string;
+
+    /** Error messages describing the failure. */
+    messages: string[];
+
+    /** Returns source {@link OpenApi.IOperation}. */
+    operation: () => OpenApi.IOperation;
+
+    /** Returns source route. Undefined if error occurred at migration level. */
+    route: () => IHttpMigrateRoute | undefined;
+  }
+}

package/src/http/IHttpLlmController.ts

@@ -0,0 +1,96 @@
+import { IHttpConnection } from "./IHttpConnection";
+import { IHttpLlmApplication } from "./IHttpLlmApplication";
+import { IHttpLlmFunction } from "./IHttpLlmFunction";
+import { IHttpResponse } from "./IHttpResponse";
+
+/**
+ * Controller of HTTP LLM function calling.
+ *
+ * `IHttpLlmController` is a controller for registering OpenAPI operations as
+ * LLM function calling tools. It contains {@link IHttpLlmApplication} with
+ * {@link IHttpLlmFunction function calling schemas}, {@link name identifier},
+ * and {@link connection} to the API server.
+ *
+ * You can create this controller with {@link HttpLlm.controller} function,
+ * and register it to MCP server with {@link registerMcpControllers}:
+ *
+ * ```typescript
+ * import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+ * import { HttpLlm } from "@typia/utils";
+ * import { registerMcpControllers } from "@typia/mcp";
+ *
+ * const server = new McpServer({ name: "my-server", version: "1.0.0" });
+ * registerMcpControllers({
+ *   server,
+ *   controllers: [
+ *     HttpLlm.controller({
+ *       name: "shopping",
+ *       document: await fetch(
+ *         "https://shopping-be.wrtn.io/editor/swagger.json",
+ *       ).then((r) => r.json()),
+ *       connection: {
+ *         host: "https://shopping-be.wrtn.io",
+ *         headers: {
+ *           Authorization: "Bearer ********",
+ *         },
+ *       },
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * For TypeScript class-based controller, use {@link ILlmController} instead.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export interface IHttpLlmController {
+  /** Protocol discriminator. */
+  protocol: "http";
+
+  /** Identifier name of the controller. */
+  name: string;
+
+  /** Application schema of function calling. */
+  application: IHttpLlmApplication;
+
+  /**
+   * Connection to the server.
+   *
+   * Connection to the API server including the URL and headers.
+   */
+  connection: IHttpConnection;
+
+  /**
+   * Executor of the API function.
+   *
+   * Default executor is {@link HttpLlm.execute} function, and you can override
+   * it with your own function.
+   *
+   * @param props Properties of the API function call
+   * @returns HTTP response of the API function call
+   */
+  execute?:
+    | undefined
+    | ((props: {
+        /** Connection to the server. */
+        connection: IHttpConnection;
+
+        /** Application schema. */
+        application: IHttpLlmApplication;
+
+        /** Function schema. */
+        function: IHttpLlmFunction;
+
+        /**
+         * Arguments of the function calling.
+         *
+         * It is an object of key-value pairs of the API function's parameters.
+         * The property keys are composed by below rules:
+         *
+         * - Parameter names
+         * - Query parameter as an object type if exists
+         * - Body parameter if exists
+         */
+        arguments: object;
+      }) => Promise<IHttpResponse>);
+}

package/src/http/IHttpLlmFunction.ts

@@ -0,0 +1,93 @@
+import { OpenApi } from "../openapi/OpenApi";
+import { ILlmSchema } from "../schema/ILlmSchema";
+import { IValidation } from "../schema/IValidation";
+import { IHttpMigrateRoute } from "./IHttpMigrateRoute";
+
+/**
+ * LLM function calling schema from OpenAPI operation.
+ *
+ * `IHttpLlmFunction` represents a single HTTP endpoint converted to LLM
+ * function calling format. Generated from {@link OpenApi.IOperation} as part of
+ * {@link IHttpLlmApplication}.
+ *
+ * Key properties:
+ *
+ * - {@link name}: Function name (max 64 chars for OpenAI compatibility)
+ * - {@link parameters}: Input schema with path/query/body merged
+ * - {@link output}: Response schema (undefined if void)
+ * - {@link description}: Critical for LLM function selection
+ * - {@link validate}: Built-in argument validator for error feedback
+ *
+ * The {@link validate} function is essential: LLMs make frequent type errors
+ * (e.g., `"123"` instead of `123`). Validate and retry improves success rate
+ * from ~50% to 99%.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export interface IHttpLlmFunction {
+  /** HTTP method of the endpoint. */
+  method: "get" | "post" | "patch" | "put" | "delete";
+
+  /** Path of the endpoint. */
+  path: string;
+
+  /**
+   * Function name composed from {@link IHttpMigrateRoute.accessor}.
+   *
+   * @maxLength 64
+   */
+  name: string;
+
+  /**
+   * Parameter schema.
+   *
+   * With keyword mode: single object with pathParameters, query, body merged.
+   * Without keyword mode: array of [pathParameters..., query?, body?].
+   */
+  parameters: ILlmSchema.IParameters;
+
+  /**
+   * Separated parameters when {@link IHttpLlmApplication.IConfig.separate} is
+   * set.
+   */
+  separated?: IHttpLlmFunction.ISeparated;
+
+  /** Return type schema. Undefined if void. */
+  output?: ILlmSchema | undefined;
+
+  /** Function description for LLM context. Critical for function selection. */
+  description?: string | undefined;
+
+  /** Whether the function is deprecated. */
+  deprecated?: boolean | undefined;
+
+  /** Category tags from {@link OpenApi.IOperation.tags}. */
+  tags?: string[];
+
+  /**
+   * Validates LLM-composed arguments.
+   *
+   * LLMs frequently make type errors. Use this to provide validation feedback
+   * and retry. Success rate improves from ~50% to 99% on retry.
+   */
+  validate: (args: unknown) => IValidation<unknown>;
+
+  /** Returns the source {@link OpenApi.IOperation}. */
+  operation: () => OpenApi.IOperation;
+
+  /** Returns the source {@link IHttpMigrateRoute}. */
+  route: () => IHttpMigrateRoute;
+}
+export namespace IHttpLlmFunction {
+  /** Collection of separated parameters. */
+  export interface ISeparated {
+    /** Parameters for LLM composition. Always at least empty object. */
+    llm: ILlmSchema.IParameters;
+
+    /** Parameters for human composition. */
+    human: ILlmSchema.IParameters | null;
+
+    /** Validates separated LLM arguments. */
+    validate?: ((args: unknown) => IValidation<unknown>) | undefined;
+  }
+}

package/src/http/IHttpMigrateApplication.ts

@@ -0,0 +1,48 @@
+import { OpenApi } from "../openapi/OpenApi";
+import { IHttpMigrateRoute } from "./IHttpMigrateRoute";
+
+/**
+ * Migrated application from OpenAPI document.
+ *
+ * `IHttpMigrateApplication` converts OpenAPI operations into callable HTTP
+ * routes via `HttpMigration.application()`. Unlike {@link IHttpLlmApplication}
+ * which targets LLM function calling, this focuses on SDK/client code
+ * generation with full HTTP semantics.
+ *
+ * Each {@link IHttpMigrateRoute} represents a single API endpoint with:
+ *
+ * - Resolved path parameters (`:id` format)
+ * - Combined query/header schemas as objects
+ * - Request/response body with content type
+ * - Accessor path for RPC-style function naming
+ *
+ * Failed operations go to {@link errors} with detailed messages.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export interface IHttpMigrateApplication {
+  /** Successfully migrated routes. */
+  routes: IHttpMigrateRoute[];
+
+  /** Operations that failed migration. */
+  errors: IHttpMigrateApplication.IError[];
+
+  /** Returns source OpenAPI document. */
+  document: () => OpenApi.IDocument;
+}
+export namespace IHttpMigrateApplication {
+  /** Migration error for an operation. */
+  export interface IError {
+    /** Returns source operation. */
+    operation: () => OpenApi.IOperation;
+
+    /** HTTP method. */
+    method: "head" | "get" | "post" | "put" | "patch" | "delete";
+
+    /** Operation path. */
+    path: string;
+
+    /** Error messages. */
+    messages: string[];
+  }
+}

package/src/http/IHttpMigrateRoute.ts

@@ -0,0 +1,165 @@
+import { OpenApi } from "../openapi/OpenApi";
+
+/**
+ * HTTP route converted from OpenAPI operation.
+ *
+ * `IHttpMigrateRoute` represents a single API endpoint with all
+ * request/response schemas resolved and ready for code generation. Contains
+ * {@link parameters} for URL path variables, {@link query} for query strings,
+ * {@link headers}, {@link body} for request payload, and
+ * {@link success}/{@link exceptions} for responses.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export interface IHttpMigrateRoute {
+  /** HTTP method. Operations with other methods are ignored. */
+  method: "head" | "get" | "post" | "put" | "patch" | "delete";
+
+  /** Original path from OpenAPI document. */
+  path: string;
+
+  /** Emended path with `:param` format, always starts with `/`. */
+  emendedPath: string;
+
+  /**
+   * Accessor path for generated RPC function.
+   *
+   * Namespaces from static path segments, function name from method +
+   * parameters. `delete` becomes `erase` to avoid reserved keyword.
+   */
+  accessor: string[];
+
+  /** Path parameters only. */
+  parameters: IHttpMigrateRoute.IParameter[];
+
+  /** Combined headers as single object. Null if none. */
+  headers: IHttpMigrateRoute.IHeaders | null;
+
+  /** Combined query parameters as single object. Null if none. */
+  query: IHttpMigrateRoute.IQuery | null;
+
+  /** Request body metadata. Null if none. */
+  body: IHttpMigrateRoute.IBody | null;
+
+  /** Success response (200/201). Null if void return. */
+  success: IHttpMigrateRoute.ISuccess | null;
+
+  /** Exception responses keyed by status code. */
+  exceptions: Record<string, IHttpMigrateRoute.IException>;
+
+  /** Returns description comment for the RPC function. */
+  comment: () => string;
+
+  /** Returns source {@link OpenApi.IOperation}. */
+  operation: () => OpenApi.IOperation;
+}
+export namespace IHttpMigrateRoute {
+  /** Path parameter metadata. */
+  export interface IParameter {
+    /** Parameter name in path template. */
+    name: string;
+
+    /** Parameter variable key. */
+    key: string;
+
+    /** Parameter type schema. */
+    schema: OpenApi.IJsonSchema;
+
+    /** Returns source parameter definition. */
+    parameter: () => OpenApi.IOperation.IParameter;
+  }
+
+  /** Headers metadata. */
+  export interface IHeaders {
+    /** Combined headers parameter name. */
+    name: string;
+
+    /** Headers variable key. */
+    key: string;
+
+    /** Combined headers schema. */
+    schema: OpenApi.IJsonSchema;
+
+    /** Returns title. */
+    title: () => string | undefined;
+
+    /** Returns description. */
+    description: () => string | undefined;
+
+    /** Returns example value. */
+    example: () => any | undefined;
+
+    /** Returns named examples. */
+    examples: () => Record<string, any> | undefined;
+  }
+
+  /** Query parameters metadata. */
+  export interface IQuery {
+    /** Combined query parameter name. */
+    name: string;
+
+    /** Query variable key. */
+    key: string;
+
+    /** Combined query schema. */
+    schema: OpenApi.IJsonSchema;
+
+    /** Returns title. */
+    title: () => string | undefined;
+
+    /** Returns description. */
+    description: () => string | undefined;
+
+    /** Returns example value. */
+    example: () => any | undefined;
+
+    /** Returns named examples. */
+    examples: () => Record<string, any> | undefined;
+  }
+
+  /** Request body metadata. */
+  export interface IBody {
+    /** Body parameter name. */
+    name: string;
+
+    /** Body variable key. */
+    key: string;
+
+    /** Content media type. */
+    type:
+      | "text/plain"
+      | "application/json"
+      | "application/x-www-form-urlencoded"
+      | "multipart/form-data";
+
+    /** Body type schema. */
+    schema: OpenApi.IJsonSchema;
+
+    /** Returns description. */
+    description: () => string | undefined;
+
+    /** Returns source media type definition. */
+    media: () => OpenApi.IOperation.IMediaType;
+
+    /** Nestia encryption flag. */
+    "x-nestia-encrypted"?: boolean;
+  }
+
+  /** Success response metadata. */
+  export interface ISuccess extends IBody {
+    /** HTTP status code. */
+    status: string;
+  }
+
+  /** Exception response metadata. */
+  export interface IException {
+    /** Exception type schema. */
+    schema: OpenApi.IJsonSchema;
+
+    /** Returns source response definition. */
+    response: () => OpenApi.IOperation.IResponse;
+
+    /** Returns source media type definition. */
+    media: () => OpenApi.IOperation.IMediaType;
+  }
+}