vovk 3.0.0-draft.99 → 3.0.0

package/dist/index.d.ts

@@ -1,59 +1,25 @@
-import { createVovkApp } from './createVovkApp';
-import { HttpStatus as HttpStatus, HttpMethod as HttpMethod, type KnownAny, type VovkErrorResponse, type VovkRequest, type VovkBody, type VovkQuery, type VovkParams, type VovkReturnType, type VovkYieldType, type VovkControllerBody, type VovkControllerQuery, type VovkControllerParams, type VovkControllerYieldType, type VovkControllerOutput, type VovkSegmentSchema, type VovkControllerSchema, type VovkHandlerSchema, type VovkFullSchema, type VovkConfig, type VovkStrictConfig, type VovkEnv, type VovkValidationType } from './types';
-import { type VovkClient, type VovkClientOptions, type VovkClientFetcher, type VovkDefaultFetcherOptions, type VovkValidateOnClient, type VovkStreamAsyncIterable, createRPC, fetcher } from './client';
-import { HttpException } from './HttpException';
-import { createDecorator } from './createDecorator';
-import { StreamJSONResponse } from './StreamJSONResponse';
-import { generateStaticAPI } from './utils/generateStaticAPI';
-import { withValidation } from './utils/withValidation';
-export { type KnownAny, type VovkClient, type VovkClientFetcher, type VovkDefaultFetcherOptions, type VovkStreamAsyncIterable, type VovkValidateOnClient, type VovkSegmentSchema, type VovkErrorResponse, type VovkRequest, type VovkControllerBody, type VovkControllerQuery, type VovkControllerParams, type VovkControllerYieldType, type VovkControllerOutput, type VovkBody, type VovkQuery, type VovkParams, type VovkYieldType, type VovkReturnType, type VovkClientOptions, type VovkControllerSchema, type VovkHandlerSchema, type VovkFullSchema, type VovkConfig, type VovkStrictConfig, type VovkEnv, type VovkValidationType, StreamJSONResponse, HttpException, HttpStatus, HttpMethod, createVovkApp, createDecorator, createRPC, fetcher, generateStaticAPI, withValidation, };
-export declare const get: {
-    (givenPath?: string | undefined, options?: import("./types").DecoratorOptions | undefined): ReturnType<(givenPath?: string, options?: import("./types").DecoratorOptions) => (givenTarget: KnownAny, propertyKey: string) => void>;
-    auto: (options?: import("./types").DecoratorOptions) => (givenTarget: KnownAny, propertyKey: string) => void;
-}, post: {
-    (givenPath?: string | undefined, options?: import("./types").DecoratorOptions | undefined): ReturnType<(givenPath?: string, options?: import("./types").DecoratorOptions) => (givenTarget: KnownAny, propertyKey: string) => void>;
-    auto: (options?: import("./types").DecoratorOptions) => (givenTarget: KnownAny, propertyKey: string) => void;
-}, put: {
-    (givenPath?: string | undefined, options?: import("./types").DecoratorOptions | undefined): ReturnType<(givenPath?: string, options?: import("./types").DecoratorOptions) => (givenTarget: KnownAny, propertyKey: string) => void>;
-    auto: (options?: import("./types").DecoratorOptions) => (givenTarget: KnownAny, propertyKey: string) => void;
-}, patch: {
-    (givenPath?: string | undefined, options?: import("./types").DecoratorOptions | undefined): ReturnType<(givenPath?: string, options?: import("./types").DecoratorOptions) => (givenTarget: KnownAny, propertyKey: string) => void>;
-    auto: (options?: import("./types").DecoratorOptions) => (givenTarget: KnownAny, propertyKey: string) => void;
-}, del: {
-    (givenPath?: string | undefined, options?: import("./types").DecoratorOptions | undefined): ReturnType<(givenPath?: string, options?: import("./types").DecoratorOptions) => (givenTarget: KnownAny, propertyKey: string) => void>;
-    auto: (options?: import("./types").DecoratorOptions) => (givenTarget: KnownAny, propertyKey: string) => void;
-}, head: {
-    (givenPath?: string | undefined, options?: import("./types").DecoratorOptions | undefined): ReturnType<(givenPath?: string, options?: import("./types").DecoratorOptions) => (givenTarget: KnownAny, propertyKey: string) => void>;
-    auto: (options?: import("./types").DecoratorOptions) => (givenTarget: KnownAny, propertyKey: string) => void;
-}, options: {
-    (givenPath?: string | undefined, options?: import("./types").DecoratorOptions | undefined): ReturnType<(givenPath?: string, options?: import("./types").DecoratorOptions) => (givenTarget: KnownAny, propertyKey: string) => void>;
-    auto: (options?: import("./types").DecoratorOptions) => (givenTarget: KnownAny, propertyKey: string) => void;
-}, prefix: (givenPath?: string) => (givenTarget: KnownAny) => any, initVovk: (options: {
-    segmentName?: string;
-    controllers: Record<string, import("./types").StaticClass>;
-    exposeValidation?: boolean;
-    emitSchema?: boolean;
-    onError?: (err: Error, req: VovkRequest) => void | Promise<void>;
-}) => {
-    GET: (req: import("next/server").NextRequest, data: {
-        params: Promise<Record<string, string[]>>;
-    }) => Promise<Response>;
-    POST: (req: import("next/server").NextRequest, data: {
-        params: Promise<Record<string, string[]>>;
-    }) => Promise<Response>;
-    PUT: (req: import("next/server").NextRequest, data: {
-        params: Promise<Record<string, string[]>>;
-    }) => Promise<Response>;
-    PATCH: (req: import("next/server").NextRequest, data: {
-        params: Promise<Record<string, string[]>>;
-    }) => Promise<Response>;
-    DELETE: (req: import("next/server").NextRequest, data: {
-        params: Promise<Record<string, string[]>>;
-    }) => Promise<Response>;
-    HEAD: (req: import("next/server").NextRequest, data: {
-        params: Promise<Record<string, string[]>>;
-    }) => Promise<Response>;
-    OPTIONS: (req: import("next/server").NextRequest, data: {
-        params: Promise<Record<string, string[]>>;
-    }) => Promise<Response>;
-};
+export { HttpException } from './core/HttpException.js';
+export { createDecorator } from './core/createDecorator.js';
+export { controllersToStaticParams } from './core/controllersToStaticParams.js';
+export { multitenant } from './core/multitenant.js';
+export { JSONLinesResponder } from './core/JSONLinesResponder.js';
+export { toDownloadResponse } from './core/toDownloadResponse.js';
+export { get, post, put, patch, del, head, options, prefix, cloneControllerMetadata } from './core/decorators.js';
+export { progressive } from './client/progressive.js';
+export { fetcher, createFetcher } from './client/fetcher.js';
+export { initSegment } from './core/initSegment.js';
+export { operation } from './openapi/operation.js';
+export { createValidateOnClient } from './validation/createValidateOnClient.js';
+export { procedure } from './validation/procedure.js';
+export { ToModelOutput } from './tools/ToModelOutput.js';
+export { createTool } from './tools/createTool.js';
+export { deriveTools } from './tools/deriveTools.js';
+export { HttpStatus, HttpMethod } from './types/enums.js';
+export type { VovkBody, VovkQuery, VovkParams, VovkReturnType, VovkYieldType, VovkOutput, VovkIteration, } from './types/inference.js';
+export type { VovkRequest } from './types/request.js';
+export type { VovkJSONSchemaBase } from './types/json-schema.js';
+export type { VovkConfig } from './types/config.js';
+export type { VovkSchema } from './types/core.js';
+export type { VovkFetcher } from './types/client.js';
+export type { VovkValidateOnClient } from './types/validation.js';
+export type { VovkTool } from './types/tools.js';

package/dist/index.js

@@ -1,23 +1,23 @@
-"use strict";
-var _a;
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.initVovk = exports.prefix = exports.options = exports.head = exports.del = exports.patch = exports.put = exports.post = exports.get = exports.withValidation = exports.generateStaticAPI = exports.fetcher = exports.createRPC = exports.createDecorator = exports.createVovkApp = exports.HttpMethod = exports.HttpStatus = exports.HttpException = exports.StreamJSONResponse = void 0;
-const createVovkApp_1 = require("./createVovkApp");
-Object.defineProperty(exports, "createVovkApp", { enumerable: true, get: function () { return createVovkApp_1.createVovkApp; } });
-const types_1 = require("./types");
-Object.defineProperty(exports, "HttpStatus", { enumerable: true, get: function () { return types_1.HttpStatus; } });
-Object.defineProperty(exports, "HttpMethod", { enumerable: true, get: function () { return types_1.HttpMethod; } });
-const client_1 = require("./client");
-Object.defineProperty(exports, "createRPC", { enumerable: true, get: function () { return client_1.createRPC; } });
-Object.defineProperty(exports, "fetcher", { enumerable: true, get: function () { return client_1.fetcher; } });
-const HttpException_1 = require("./HttpException");
-Object.defineProperty(exports, "HttpException", { enumerable: true, get: function () { return HttpException_1.HttpException; } });
-const createDecorator_1 = require("./createDecorator");
-Object.defineProperty(exports, "createDecorator", { enumerable: true, get: function () { return createDecorator_1.createDecorator; } });
-const StreamJSONResponse_1 = require("./StreamJSONResponse");
-Object.defineProperty(exports, "StreamJSONResponse", { enumerable: true, get: function () { return StreamJSONResponse_1.StreamJSONResponse; } });
-const generateStaticAPI_1 = require("./utils/generateStaticAPI");
-Object.defineProperty(exports, "generateStaticAPI", { enumerable: true, get: function () { return generateStaticAPI_1.generateStaticAPI; } });
-const withValidation_1 = require("./utils/withValidation");
-Object.defineProperty(exports, "withValidation", { enumerable: true, get: function () { return withValidation_1.withValidation; } });
-_a = (0, createVovkApp_1.createVovkApp)(), exports.get = _a.get, exports.post = _a.post, exports.put = _a.put, exports.patch = _a.patch, exports.del = _a.del, exports.head = _a.head, exports.options = _a.options, exports.prefix = _a.prefix, exports.initVovk = _a.initVovk;
+// core
+export { HttpException } from './core/HttpException.js';
+export { createDecorator } from './core/createDecorator.js';
+export { controllersToStaticParams } from './core/controllersToStaticParams.js';
+export { multitenant } from './core/multitenant.js';
+export { JSONLinesResponder } from './core/JSONLinesResponder.js';
+export { toDownloadResponse } from './core/toDownloadResponse.js';
+export { get, post, put, patch, del, head, options, prefix, cloneControllerMetadata } from './core/decorators.js';
+// client
+export { progressive } from './client/progressive.js';
+export { fetcher, createFetcher } from './client/fetcher.js';
+export { initSegment } from './core/initSegment.js';
+// openapi
+export { operation } from './openapi/operation.js';
+// validation
+export { createValidateOnClient } from './validation/createValidateOnClient.js';
+export { procedure } from './validation/procedure.js';
+// tools
+export { ToModelOutput } from './tools/ToModelOutput.js';
+export { createTool } from './tools/createTool.js';
+export { deriveTools } from './tools/deriveTools.js';
+// types
+export { HttpStatus, HttpMethod } from './types/enums.js';

package/dist/internal.d.ts

@@ -0,0 +1,17 @@
+export { deepExtend } from './utils/deepExtend.js';
+export { resolveGeneratorConfigValues } from './core/resolveGeneratorConfigValues.js';
+export { createCodeSamples } from './samples/createCodeSamples.js';
+export { withValidationLibrary } from './validation/withValidationLibrary.js';
+export { operation } from './openapi/operation.js';
+export { openAPIToVovkSchema } from './openapi/openAPIToVovkSchema/index.js';
+export { vovkSchemaToOpenAPI } from './openapi/vovkSchemaToOpenAPI.js';
+export { readableStreamToAsyncIterable } from './client/defaultStreamHandler.js';
+export { VovkSchemaIdEnum } from './types/enums.js';
+export type { VovkToolDerived, VovkToolNonDerived } from './types/tools.js';
+export type { MCPModelOutput } from './tools/toModelOutputMCP.js';
+export type { VovkErrorResponse, VovkMetaSchema, VovkSegmentSchema, VovkControllerSchema, VovkHandlerSchema, VovkValidationType, } from './types/core.js';
+export type { VovkTypedProcedure } from './types/validation.js';
+export type { VovkOutputConfig, VovkReadmeConfig, VovkSamplesConfig, VovkPackageJson, VovkOpenAPIMixin, VovkOpenAPIMixinNormalized, VovkStrictConfig, VovkBundleConfig, VovkSegmentConfig, } from './types/config.js';
+export type { VovkOperationObject } from './types/operation.js';
+export type { VovkRPCModule, VovkFetcherOptions, VovkStreamAsyncIterable } from './types/client.js';
+export type { IsAny, IsNotAny } from './types/utils.js';

package/dist/internal.js

@@ -0,0 +1,10 @@
+// internal exports for other packages and tests
+export { deepExtend } from './utils/deepExtend.js';
+export { resolveGeneratorConfigValues } from './core/resolveGeneratorConfigValues.js';
+export { createCodeSamples } from './samples/createCodeSamples.js';
+export { withValidationLibrary } from './validation/withValidationLibrary.js';
+export { operation } from './openapi/operation.js';
+export { openAPIToVovkSchema } from './openapi/openAPIToVovkSchema/index.js';
+export { vovkSchemaToOpenAPI } from './openapi/vovkSchemaToOpenAPI.js';
+export { readableStreamToAsyncIterable } from './client/defaultStreamHandler.js';
+export { VovkSchemaIdEnum } from './types/enums.js';

package/dist/openapi/error.d.ts

@@ -0,0 +1,2 @@
+import { HttpStatus } from '../types/enums.js';
+export declare const error: (status: HttpStatus, message: string) => (target: import("../types/utils.js").KnownAny, propertyKey: string) => void;

package/dist/openapi/error.js

@@ -0,0 +1,97 @@
+import { HttpStatus } from '../types/enums.js';
+import { createDecorator } from '../core/createDecorator.js';
+const statusDisplayText = {
+    [HttpStatus.NULL]: 'Error',
+    [HttpStatus.CONTINUE]: 'Continue',
+    [HttpStatus.SWITCHING_PROTOCOLS]: 'Switching Protocols',
+    [HttpStatus.PROCESSING]: 'Processing',
+    [HttpStatus.EARLYHINTS]: 'Early Hints',
+    [HttpStatus.OK]: 'OK',
+    [HttpStatus.CREATED]: 'Created',
+    [HttpStatus.ACCEPTED]: 'Accepted',
+    [HttpStatus.NON_AUTHORITATIVE_INFORMATION]: 'Non Authoritative Information',
+    [HttpStatus.NO_CONTENT]: 'No Content',
+    [HttpStatus.RESET_CONTENT]: 'Reset Content',
+    [HttpStatus.PARTIAL_CONTENT]: 'Partial Content',
+    [HttpStatus.AMBIGUOUS]: 'Ambiguous',
+    [HttpStatus.MOVED_PERMANENTLY]: 'Moved Permanently',
+    [HttpStatus.FOUND]: 'Found',
+    [HttpStatus.SEE_OTHER]: 'See Other',
+    [HttpStatus.NOT_MODIFIED]: 'Not Modified',
+    [HttpStatus.TEMPORARY_REDIRECT]: 'Temporary Redirect',
+    [HttpStatus.PERMANENT_REDIRECT]: 'Permanent Redirect',
+    [HttpStatus.BAD_REQUEST]: 'Bad Request',
+    [HttpStatus.UNAUTHORIZED]: 'Unauthorized',
+    [HttpStatus.PAYMENT_REQUIRED]: 'Payment Required',
+    [HttpStatus.FORBIDDEN]: 'Forbidden',
+    [HttpStatus.NOT_FOUND]: 'Not Found',
+    [HttpStatus.METHOD_NOT_ALLOWED]: 'Method Not Allowed',
+    [HttpStatus.NOT_ACCEPTABLE]: 'Not Acceptable',
+    [HttpStatus.PROXY_AUTHENTICATION_REQUIRED]: 'Proxy Authentication Required',
+    [HttpStatus.REQUEST_TIMEOUT]: 'Request Timeout',
+    [HttpStatus.CONFLICT]: 'Conflict',
+    [HttpStatus.GONE]: 'Gone',
+    [HttpStatus.LENGTH_REQUIRED]: 'Length Required',
+    [HttpStatus.PRECONDITION_FAILED]: 'Precondition Failed',
+    [HttpStatus.PAYLOAD_TOO_LARGE]: 'Payload Too Large',
+    [HttpStatus.URI_TOO_LONG]: 'URI Too Long',
+    [HttpStatus.UNSUPPORTED_MEDIA_TYPE]: 'Unsupported Media Type',
+    [HttpStatus.REQUESTED_RANGE_NOT_SATISFIABLE]: 'Requested Range Not Satisfiable',
+    [HttpStatus.EXPECTATION_FAILED]: 'Expectation Failed',
+    [HttpStatus.I_AM_A_TEAPOT]: 'I am a teapot',
+    [HttpStatus.MISDIRECTED]: 'Misdirected',
+    [HttpStatus.UNPROCESSABLE_ENTITY]: 'Unprocessable Entity',
+    [HttpStatus.FAILED_DEPENDENCY]: 'Failed Dependency',
+    [HttpStatus.PRECONDITION_REQUIRED]: 'Precondition Required',
+    [HttpStatus.TOO_MANY_TRequestS]: 'Too Many Requests',
+    [HttpStatus.INTERNAL_SERVER_ERROR]: 'Internal Server Error',
+    [HttpStatus.NOT_IMPLEMENTED]: 'Not Implemented',
+    [HttpStatus.BAD_GATEWAY]: 'Bad Gateway',
+    [HttpStatus.SERVICE_UNAVAILABLE]: 'Service Unavailable',
+    [HttpStatus.GATEWAY_TIMEOUT]: 'Gateway Timeout',
+    [HttpStatus.HTTP_VERSION_NOT_SUPPORTED]: 'HTTP Version Not Supported',
+};
+export const error = createDecorator(null, (status, message) => {
+    return (handlerSchema) => {
+        return {
+            ...handlerSchema,
+            operationObject: {
+                ...handlerSchema?.operationObject,
+                responses: {
+                    ...handlerSchema?.operationObject?.responses,
+                    [status]: {
+                        description: `${status} ${statusDisplayText[status]}`,
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    allOf: [
+                                        {
+                                            $ref: '#/components/schemas/VovkErrorResponse',
+                                        },
+                                        {
+                                            type: 'object',
+                                            properties: {
+                                                message: {
+                                                    type: 'string',
+                                                    enum: [
+                                                        message,
+                                                        ...(handlerSchema?.operationObject?.responses?.[status]?.content?.['application/json']
+                                                            ?.schema?.allOf?.[1]?.properties?.message?.enum ?? []),
+                                                    ],
+                                                },
+                                                statusCode: {
+                                                    type: 'integer',
+                                                    enum: [status],
+                                                },
+                                            },
+                                        },
+                                    ],
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        };
+    };
+});

package/dist/openapi/openAPIToVovkSchema/applyComponentsSchemas.d.ts

@@ -0,0 +1,3 @@
+import type { ComponentsObject } from 'openapi3-ts/oas31';
+import type { VovkJSONSchemaBase } from '../../types/json-schema.js';
+export declare function applyComponentsSchemas(schema: VovkJSONSchemaBase, components: ComponentsObject['schemas'], mixinName: string): VovkJSONSchemaBase | VovkJSONSchemaBase[];

package/dist/openapi/openAPIToVovkSchema/applyComponentsSchemas.js

@@ -0,0 +1,65 @@
+import { camelCase } from '../../utils/camelCase.js';
+import { upperFirst } from '../../utils/upperFirst.js';
+// fast clone JSON object while ignoring Date, RegExp, and Function types
+function cloneJSON(obj) {
+    if (obj === null || typeof obj !== 'object')
+        return obj;
+    if (Array.isArray(obj))
+        return obj.map(cloneJSON);
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (value instanceof Date || value instanceof RegExp || typeof value === 'function')
+            continue;
+        result[key] = cloneJSON(value);
+    }
+    return result;
+}
+export function applyComponentsSchemas(schema, components, mixinName) {
+    const key = 'components/schemas';
+    if (!components || !Object.keys(components).length)
+        return schema;
+    // Create a deep copy of the schema
+    const result = cloneJSON(schema);
+    // Initialize $defs if it doesn't exist
+    result.$defs = result.$defs || {};
+    // Set to track components we've added to $defs
+    const addedComponents = new Set();
+    // Process a schema object and replace $refs
+    function processSchema(obj) {
+        if (!obj || typeof obj !== 'object')
+            return obj;
+        // Handle arrays first - they don't have $ref
+        if (Array.isArray(obj)) {
+            return obj.map((item) => processSchema(item));
+        }
+        // Now we know it's an object, so we can safely access $ref
+        const newObj = { ...obj };
+        const $ref = newObj.$ref;
+        if ($ref && typeof $ref === 'string' && $ref.startsWith(`#/${key}/`)) {
+            const componentName = $ref.replace(`#/${key}/`, '');
+            if (components[componentName]) {
+                newObj.$ref = `#/$defs/${componentName}`;
+                newObj['x-tsType'] ??= `Mixins.${upperFirst(camelCase(mixinName))}.${upperFirst(camelCase(componentName))}`;
+            }
+            else {
+                delete newObj.$ref; // Remove $ref if component not found (Telegram API has Type $refs that is not defined in components)
+            }
+            // Add the component to $defs if not already added
+            if (!addedComponents.has(componentName) && components[componentName]) {
+                addedComponents.add(componentName);
+                if (result.$defs) {
+                    result.$defs[componentName] = processSchema(cloneJSON(components[componentName]));
+                }
+            }
+        }
+        // Process properties recursively
+        for (const key in newObj) {
+            if (Object.prototype.hasOwnProperty.call(newObj, key)) {
+                newObj[key] = processSchema(newObj[key]);
+            }
+        }
+        return newObj;
+    }
+    // Process the main schema
+    return processSchema(result);
+}

package/dist/openapi/openAPIToVovkSchema/index.d.ts

@@ -0,0 +1,5 @@
+import type { VovkSchema } from '../../types/core.js';
+import type { VovkOpenAPIMixinNormalized } from '../../types/config.js';
+export declare function openAPIToVovkSchema({ apiRoot, source: { object: openAPIObject }, getModuleName, getMethodName, errorMessageKey, segmentName, }: VovkOpenAPIMixinNormalized & {
+    segmentName?: string;
+}): VovkSchema;

package/dist/openapi/openAPIToVovkSchema/index.js

@@ -0,0 +1,153 @@
+import { applyComponentsSchemas } from './applyComponentsSchemas.js';
+import { inlineRefs } from './inlineRefs.js';
+import { VovkSchemaIdEnum } from '../../types/enums.js';
+import { schemaToTsType } from '../../samples/schemaToTsType.js';
+function getTsTypeString(contentType, schema) {
+    const tsTypes = new Set(contentType.flatMap((ct) => {
+        switch (ct) {
+            case 'application/json':
+                return [schemaToTsType(schema)];
+            case 'multipart/form-data':
+                return ['FormData', schemaToTsType(schema)];
+            case 'application/x-www-form-urlencoded':
+                return ['FormData', 'URLSearchParams', schemaToTsType(schema)];
+            case 'text/plain':
+                return ['string'];
+            default:
+                return ['Blob', 'ArrayBuffer', 'Uint8Array'];
+        }
+    }));
+    return [...tsTypes].join(' | ') || schemaToTsType(schema);
+}
+export function openAPIToVovkSchema({ apiRoot, source: { object: openAPIObject }, getModuleName, getMethodName, errorMessageKey, segmentName, }) {
+    segmentName = segmentName ?? '';
+    const forceApiRoot = apiRoot ||
+        (openAPIObject.servers?.[0]?.url ??
+            ('host' in openAPIObject
+                ? `https://${openAPIObject.host}${'basePath' in openAPIObject ? openAPIObject.basePath : ''}`
+                : null));
+    if (!forceApiRoot) {
+        throw new Error('API root URL is required in OpenAPI configuration');
+    }
+    const { paths, ...noPathsOpenAPIObject } = openAPIObject;
+    const schema = {
+        $schema: VovkSchemaIdEnum.SCHEMA,
+        segments: {
+            [segmentName]: {
+                $schema: VovkSchemaIdEnum.SEGMENT,
+                emitSchema: true,
+                segmentName,
+                segmentType: 'mixin',
+                controllers: {},
+                forceApiRoot,
+                meta: {
+                    openAPIObject: noPathsOpenAPIObject,
+                },
+            },
+        },
+    };
+    const segment = schema.segments[segmentName];
+    return Object.entries(paths ?? {}).reduce((acc, [path, operations]) => {
+        Object.entries(operations ?? {})
+            .filter(([, operation]) => operation && typeof operation === 'object')
+            .forEach(([method, operation]) => {
+            const rpcModuleName = getModuleName({
+                method: method.toUpperCase(),
+                path,
+                openAPIObject,
+                operationObject: operation,
+            });
+            const handlerName = getMethodName({
+                method: method.toUpperCase(),
+                path,
+                openAPIObject,
+                operationObject: operation,
+            });
+            segment.controllers[rpcModuleName] ??= {
+                rpcModuleName,
+                handlers: {},
+            };
+            const parameters = inlineRefs(operation.parameters ?? [], openAPIObject);
+            const queryProperties = parameters?.filter((p) => p.in === 'query') ?? null;
+            const pathProperties = parameters?.filter((p) => p.in === 'path') ?? null;
+            const query = queryProperties?.length
+                ? {
+                    type: 'object',
+                    properties: Object.fromEntries(queryProperties.map((p) => [p.name, p.schema])),
+                    required: queryProperties.filter((p) => p.required).map((p) => p.name),
+                }
+                : null;
+            const params = pathProperties?.length
+                ? {
+                    type: 'object',
+                    properties: Object.fromEntries(pathProperties.map((p) => [p.name, p.schema])),
+                    required: pathProperties.filter((p) => p.required).map((p) => p.name),
+                }
+                : null;
+            const requestBodyContent = inlineRefs(operation.requestBody, openAPIObject)?.content ?? {};
+            const contentTypes = [
+                'application/json',
+                'multipart/form-data',
+                'application/x-www-form-urlencoded',
+                'text/plain',
+                'application/octet-stream',
+            ];
+            const bodySchemas = contentTypes
+                .map((contentType) => requestBodyContent[contentType]?.schema
+                ? { ...requestBodyContent[contentType].schema, 'x-contentType': [contentType] }
+                : null)
+                .filter(Boolean);
+            const body = !bodySchemas.length
+                ? null
+                : bodySchemas.length === 1
+                    ? {
+                        ...bodySchemas[0],
+                        'x-tsType': getTsTypeString(bodySchemas[0]['x-contentType'] ?? [], bodySchemas[0]),
+                    }
+                    : {
+                        anyOf: bodySchemas,
+                        'x-tsType': getTsTypeString(bodySchemas.flatMap((s) => s['x-contentType'] ?? []), { anyOf: bodySchemas }),
+                    };
+            const output = operation.responses?.['200']?.content?.['application/json']?.schema ??
+                operation.responses?.['201']?.content?.['application/json']?.schema ??
+                null;
+            const iteration = operation.responses?.['200']?.content?.['application/jsonl']?.schema ??
+                operation.responses?.['201']?.content?.['application/jsonl']?.schema ??
+                operation.responses?.['200']?.content?.['application/jsonlines']?.schema ??
+                operation.responses?.['201']?.content?.['application/jsonlines']?.schema ??
+                null;
+            if (errorMessageKey) {
+                operation['x-errorMessageKey'] = errorMessageKey;
+            }
+            const componentsSchemas = openAPIObject.components?.schemas ??
+                ('definitions' in openAPIObject ? openAPIObject.definitions : {});
+            segment.controllers[rpcModuleName].handlers[handlerName] = {
+                httpMethod: method.toUpperCase(),
+                path,
+                operationObject: operation,
+                misc: {
+                    isOpenAPIMixin: true,
+                    originalPath: path,
+                },
+                validation: {
+                    ...(query && {
+                        query: applyComponentsSchemas(query, componentsSchemas, segmentName),
+                    }),
+                    ...(params && {
+                        params: applyComponentsSchemas(params, componentsSchemas, segmentName),
+                    }),
+                    ...(body && {
+                        body: applyComponentsSchemas(body, componentsSchemas, segmentName),
+                    }),
+                    ...(output && {
+                        output: applyComponentsSchemas(output, componentsSchemas, segmentName),
+                    }),
+                    ...(iteration && {
+                        iteration: applyComponentsSchemas(iteration, componentsSchemas, segmentName),
+                    }),
+                },
+            };
+        });
+        return acc;
+    }, schema);
+}

package/dist/openapi/openAPIToVovkSchema/inlineRefs.d.ts

@@ -0,0 +1,9 @@
+import type { OpenAPIObject } from 'openapi3-ts/oas31';
+/**
+ * Resolves $ref references at the first level only (except for components/schemas references)
+ * For arrays, checks each item at the first level
+ * @param obj - The object to process (may contain $ref properties)
+ * @param openAPIObject - The complete OpenAPI document containing definitions
+ * @returns The object with resolved references (except components/schemas)
+ */
+export declare function inlineRefs<T extends object>(obj: unknown, openAPIObject: OpenAPIObject): T | null;

package/dist/openapi/openAPIToVovkSchema/inlineRefs.js

@@ -0,0 +1,99 @@
+/**
+ * Resolves $ref references at the first level only (except for components/schemas references)
+ * For arrays, checks each item at the first level
+ * @param obj - The object to process (may contain $ref properties)
+ * @param openAPIObject - The complete OpenAPI document containing definitions
+ * @returns The object with resolved references (except components/schemas)
+ */
+export function inlineRefs(obj, openAPIObject) {
+    // Handle null or undefined
+    if (obj === null || obj === undefined) {
+        return null;
+    }
+    // Handle arrays - check each item for $ref at first level only
+    if (Array.isArray(obj)) {
+        return obj.map((item) => {
+            // Only resolve if item is an object with $ref
+            if (item && typeof item === 'object' && '$ref' in item && typeof item.$ref === 'string') {
+                // Skip components/schemas references
+                if (item.$ref.startsWith('#/components/schemas/')) {
+                    return item;
+                }
+                // Resolve the reference
+                const resolved = resolveRef(item.$ref, openAPIObject);
+                // If resolution successful, return resolved value (with any additional properties merged)
+                if (resolved !== undefined) {
+                    // If there are additional properties besides $ref, merge them
+                    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+                    const { $ref: _$ref, ...additionalProps } = item;
+                    if (Object.keys(additionalProps).length > 0) {
+                        return { ...resolved, ...additionalProps };
+                    }
+                    return resolved;
+                }
+            }
+            // Return item as-is if not a resolvable $ref
+            return item;
+        });
+    }
+    // Handle non-objects (primitives)
+    if (typeof obj !== 'object') {
+        return obj;
+    }
+    // Check if object has a $ref property at the first level
+    if ('$ref' in obj && typeof obj.$ref === 'string') {
+        // Check if the reference points to components/schemas
+        if (obj.$ref.startsWith('#/components/schemas/')) {
+            // Return as-is for schema references
+            return obj;
+        }
+        // Resolve the reference
+        const resolved = resolveRef(obj.$ref, openAPIObject);
+        // If resolution successful, return resolved value (with any additional properties merged)
+        if (resolved !== undefined) {
+            // If there are additional properties besides $ref, merge them
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            const { $ref: _$ref, ...additionalProps } = obj;
+            if (Object.keys(additionalProps).length > 0) {
+                return { ...resolved, ...additionalProps };
+            }
+            return resolved;
+        }
+    }
+    // For regular objects without $ref, return as-is (no recursion)
+    return obj;
+}
+/**
+ * Resolves a JSON Reference ($ref) to its target value
+ * @param ref - The reference string (e.g., "#/components/parameters/id")
+ * @param openAPIObject - The complete OpenAPI document
+ * @returns The resolved value or undefined if not found
+ */
+function resolveRef(ref, openAPIObject) {
+    // Handle only local references (starting with #)
+    if (!ref.startsWith('#/')) {
+        // eslint-disable-next-line no-console
+        console.warn(`External references are not supported: ${ref}`);
+        return undefined;
+    }
+    // Remove the leading # and split the path
+    const path = ref
+        .substring(1)
+        .split('/')
+        .filter((p) => p !== '');
+    // Navigate through the object following the path
+    let current = openAPIObject;
+    for (const segment of path) {
+        // Decode the segment (handles encoded characters like ~0 for ~ and ~1 for /)
+        const decodedSegment = segment.replace(/~1/g, '/').replace(/~0/g, '~');
+        if (current && typeof current === 'object' && decodedSegment in current) {
+            current = current[decodedSegment];
+        }
+        else {
+            // eslint-disable-next-line no-console
+            console.warn(`Could not resolve reference: ${ref}`);
+            return undefined;
+        }
+    }
+    return current;
+}

package/dist/openapi/operation.d.ts

@@ -0,0 +1,10 @@
+import type { VovkOperationObject } from '../types/operation.js';
+export declare const operationDecorator: (openAPIOperationObject?: VovkOperationObject | undefined) => (target: import("../types/utils.js").KnownAny, propertyKey: string) => void;
+/**
+ * OpenAPI operation decorator to add metadata to API operations. Also includes `error` and `tool` utilities.
+ * @see https://vovk.dev/openapi
+ */
+export declare const operation: ((openAPIOperationObject?: VovkOperationObject | undefined) => (target: import("../types/utils.js").KnownAny, propertyKey: string) => void) & {
+    error: (status: import("../index.js").HttpStatus, message: string) => (target: import("../types/utils.js").KnownAny, propertyKey: string) => void;
+    tool: (toolOptions: import("../types/tools.js").VovkToolOptions) => (target: import("../types/utils.js").KnownAny, propertyKey: string) => void;
+};