vovk 3.0.0-draft.99 → 3.0.0

package/dist/openapi/operation.js

@@ -0,0 +1,19 @@
+import { createDecorator } from '../core/createDecorator.js';
+import { error } from './error.js';
+import { tool } from './tool.js';
+export const operationDecorator = createDecorator(null, (openAPIOperationObject = {}) => {
+    return (handlerSchema) => {
+        return {
+            ...handlerSchema,
+            operationObject: {
+                ...handlerSchema?.operationObject,
+                ...openAPIOperationObject,
+            },
+        };
+    };
+});
+/**
+ * OpenAPI operation decorator to add metadata to API operations. Also includes `error` and `tool` utilities.
+ * @see https://vovk.dev/openapi
+ */
+export const operation = Object.assign(operationDecorator, { error, tool });

package/dist/openapi/tool.d.ts

@@ -0,0 +1,2 @@
+import type { VovkToolOptions } from '../types/tools.js';
+export declare const tool: (toolOptions: VovkToolOptions) => (target: import("../types/utils.js").KnownAny, propertyKey: string) => void;

package/dist/openapi/tool.js

@@ -0,0 +1,12 @@
+import { createDecorator } from '../core/createDecorator.js';
+export const tool = createDecorator(null, (toolOptions) => {
+    return (handlerSchema) => {
+        return {
+            ...handlerSchema,
+            operationObject: {
+                ...handlerSchema?.operationObject,
+                'x-tool': toolOptions,
+            },
+        };
+    };
+});

package/dist/openapi/vovkSchemaToOpenAPI.d.ts

@@ -0,0 +1,21 @@
+import type { OpenAPIObject } from 'openapi3-ts/oas31';
+import type { VovkOutputConfig, VovkStrictConfig, VovkReadmeConfig, VovkSamplesConfig, VovkPackageJson } from '../types/config.js';
+import type { VovkSchema } from '../types/core.js';
+export declare function vovkSchemaToOpenAPI({ config, rootEntry, schema: fullSchema, outputConfigs, forceOutputConfigs, isBundle, segmentName: givenSegmentName, projectPackageJson, }: {
+    config: VovkStrictConfig | undefined;
+    rootEntry?: string;
+    schema: VovkSchema;
+    outputConfigs: VovkOutputConfig[];
+    forceOutputConfigs?: VovkOutputConfig[];
+    isBundle: boolean;
+    segmentName: string | null;
+    projectPackageJson: VovkPackageJson | undefined;
+}): {
+    readme: VovkReadmeConfig;
+    openAPIObject: OpenAPIObject;
+    samples: VovkSamplesConfig;
+    origin: string;
+    package: VovkPackageJson;
+    imports: VovkOutputConfig['imports'];
+    reExports: VovkOutputConfig['reExports'];
+};

package/dist/openapi/vovkSchemaToOpenAPI.js

@@ -0,0 +1,250 @@
+import { createCodeSamples } from '../samples/createCodeSamples.js';
+import { schemaToObject } from '../samples/schemaToObject.js';
+import { resolveGeneratorConfigValues } from '../core/resolveGeneratorConfigValues.js';
+import { HttpStatus } from '../types/enums.js';
+function extractComponents(schema) {
+    if (!schema)
+        return [undefined, {}];
+    const components = {};
+    // Function to collect components and replace $refs recursively
+    const process = (obj, path = []) => {
+        if (!obj || typeof obj !== 'object')
+            return obj;
+        // Handle arrays
+        if (Array.isArray(obj)) {
+            return obj.map((item) => process(item, path));
+        }
+        // Create a copy to modify
+        const result = {};
+        Object.entries({ ...obj.definitions, ...obj.$defs }).forEach(([key, value]) => {
+            components[key] = process(value, [...path, key]);
+        });
+        // Process all properties
+        for (const [key, value] of Object.entries(obj ?? {})) {
+            // Skip already processed special properties
+            if (key === '$defs' || key === 'definitions')
+                continue;
+            if (key === '$ref' && typeof value === 'string') {
+                // Extract the component name from the reference
+                const refParts = value.split('/');
+                const refName = refParts[refParts.length - 1];
+                // Replace with component reference
+                result[key] = `#/components/schemas/${refName}`;
+            }
+            else {
+                // Recursively process other properties
+                result[key] = process(value, [...path, key]);
+            }
+        }
+        return result;
+    };
+    const processedSchema = process(schema);
+    return [processedSchema, components];
+}
+// returns OpenAPIObject along with resolved configs
+// TODO: Refactor and decompose
+export function vovkSchemaToOpenAPI({ config, rootEntry = 'api', schema: fullSchema, outputConfigs, forceOutputConfigs, isBundle, segmentName: givenSegmentName, projectPackageJson, }) {
+    const paths = {};
+    const components = {};
+    const { openAPIObject, samples: samplesConfig, package: packageJson, readme: readmeConfig, origin, imports, reExports, } = resolveGeneratorConfigValues({
+        config,
+        outputConfigs,
+        forceOutputConfigs,
+        isBundle,
+        segmentName: givenSegmentName ?? null,
+        projectPackageJson,
+    });
+    for (const [segmentName, segmentSchema] of givenSegmentName
+        ? [[givenSegmentName, fullSchema.segments[givenSegmentName]]]
+        : Object.entries(fullSchema.segments ?? {})) {
+        for (const c of Object.values(segmentSchema.controllers)) {
+            for (const [handlerName, h] of Object.entries(c.handlers ?? {})) {
+                if (h.operationObject && !h.misc?.isOpenAPIMixin) {
+                    const [queryValidation, queryComponents] = extractComponents(h?.validation?.query);
+                    const [bodyValidation, bodyComponents] = extractComponents(h?.validation?.body);
+                    const [paramsValidation, paramsComponents] = extractComponents(h?.validation?.params);
+                    const [outputValidation, outputComponents] = extractComponents(h?.validation?.output);
+                    const [iterationValidation, iterationComponents] = extractComponents(h?.validation?.iteration);
+                    // TODO: Handle name conflicts?
+                    Object.assign(components, queryComponents, bodyComponents, paramsComponents, outputComponents, iterationComponents);
+                    const { ts, rs, py } = createCodeSamples({
+                        package: packageJson,
+                        handlerName,
+                        handlerSchema: h,
+                        controllerSchema: c,
+                        config: samplesConfig,
+                    });
+                    const queryParameters = queryValidation && 'type' in queryValidation && 'properties' in queryValidation
+                        ? Object.entries(queryValidation.properties ?? {}).map(([propName, propSchema]) => ({
+                            name: propName,
+                            in: 'query',
+                            required: queryValidation.required ? queryValidation.required.includes(propName) : false,
+                            schema: propSchema,
+                        }))
+                        : null;
+                    const pathParameters = paramsValidation && 'type' in paramsValidation && 'properties' in paramsValidation
+                        ? Object.entries(paramsValidation.properties ?? {}).map(([propName, propSchema]) => ({
+                            name: propName,
+                            in: 'path',
+                            required: paramsValidation.required ? paramsValidation.required.includes(propName) : false,
+                            schema: propSchema,
+                        }))
+                        : null;
+                    const path = h.misc?.originalPath ??
+                        '/' + [rootEntry.replace(/^\/+|\/+$/g, ''), segmentName, c.prefix, h.path].filter(Boolean).join('/');
+                    paths[path] = paths[path] ?? {};
+                    const httpMethod = h.httpMethod.toLowerCase();
+                    paths[path][httpMethod] ??= {};
+                    paths[path][httpMethod] = {
+                        ...h.operationObject,
+                        ...paths[path][httpMethod],
+                        'x-codeSamples': [
+                            ...(paths[path][httpMethod]['x-codeSamples'] ?? []),
+                            ...(h.operationObject?.['x-codeSamples'] ?? []),
+                            {
+                                label: 'TypeScript RPC',
+                                lang: 'typescript',
+                                source: ts,
+                            },
+                            {
+                                label: 'Python RPC',
+                                lang: 'python',
+                                source: py,
+                            },
+                            {
+                                label: 'Rust RPC',
+                                lang: 'rust',
+                                source: rs,
+                            },
+                        ],
+                        ...(queryParameters || pathParameters
+                            ? {
+                                parameters: h.operationObject?.parameters ?? [...(queryParameters || []), ...(pathParameters || [])],
+                            }
+                            : {}),
+                        ...(paths[path][httpMethod].parameters
+                            ? {
+                                parameters: paths[path][httpMethod].parameters,
+                            }
+                            : {}),
+                        ...(outputValidation && 'type' in outputValidation
+                            ? {
+                                responses: {
+                                    200: {
+                                        description: 'description' in outputValidation ? outputValidation.description : 'Success',
+                                        content: {
+                                            'application/json': {
+                                                schema: outputValidation,
+                                            },
+                                        },
+                                    },
+                                    ...h.operationObject?.responses,
+                                },
+                            }
+                            : {}),
+                        ...(iterationValidation && 'type' in iterationValidation
+                            ? {
+                                responses: {
+                                    200: {
+                                        description: 'description' in iterationValidation ? iterationValidation.description : 'JSON Lines response',
+                                        content: {
+                                            'application/jsonl': {
+                                                schema: {
+                                                    ...iterationValidation,
+                                                    examples: iterationValidation.examples ?? [
+                                                        [
+                                                            JSON.stringify(schemaToObject(iterationValidation)),
+                                                            JSON.stringify(schemaToObject(iterationValidation)),
+                                                            JSON.stringify(schemaToObject(iterationValidation)),
+                                                        ].join('\n'),
+                                                    ],
+                                                },
+                                            },
+                                        },
+                                    },
+                                    ...h.operationObject?.responses,
+                                },
+                            }
+                            : {}),
+                        ...(paths[path][httpMethod].responses
+                            ? {
+                                responses: paths[path][httpMethod].responses,
+                            }
+                            : {}),
+                        ...(bodyValidation && 'type' in bodyValidation
+                            ? {
+                                requestBody: h.operationObject?.requestBody ?? {
+                                    description: 'description' in bodyValidation ? bodyValidation.description : 'Request body',
+                                    required: true,
+                                    content: bodyValidation['x-contentType']?.length
+                                        ? Object.fromEntries(bodyValidation['x-contentType'].map((ct) => [ct, { schema: bodyValidation }]))
+                                        : {
+                                            'application/json': {
+                                                schema: bodyValidation,
+                                            },
+                                        },
+                                },
+                            }
+                            : {}),
+                        ...(paths[path][httpMethod].requestBody
+                            ? {
+                                requestBody: paths[path][httpMethod].requestBody,
+                            }
+                            : {}),
+                        tags: paths[path][httpMethod].tags ?? h.operationObject?.tags,
+                    };
+                }
+            }
+        }
+    }
+    return {
+        readme: readmeConfig,
+        samples: samplesConfig,
+        package: packageJson,
+        imports,
+        reExports,
+        origin,
+        openAPIObject: {
+            ...openAPIObject,
+            components: {
+                ...openAPIObject?.components,
+                schemas: {
+                    ...(openAPIObject?.components?.schemas ?? components),
+                    HttpStatus: {
+                        type: 'integer',
+                        description: 'HTTP status code',
+                        enum: Object.keys(HttpStatus)
+                            .map((k) => HttpStatus[k])
+                            .filter(Boolean)
+                            .filter((v) => typeof v === 'number'),
+                    },
+                    VovkErrorResponse: {
+                        type: 'object',
+                        description: 'Vovk error response',
+                        properties: {
+                            cause: {
+                                description: 'Error cause of any shape',
+                            },
+                            statusCode: {
+                                $ref: '#/components/schemas/HttpStatus',
+                            },
+                            message: {
+                                type: 'string',
+                                description: 'Error message',
+                            },
+                            isError: {
+                                type: 'boolean',
+                                const: true,
+                                description: 'Indicates that this object represents an error',
+                            },
+                        },
+                        required: ['statusCode', 'message', 'isError'],
+                        additionalProperties: false,
+                    },
+                    ...openAPIObject?.components?.schemas,
+                },
+            },
+            paths,
+        },
+    };
+}

package/dist/req/bufferBody.d.ts

@@ -0,0 +1 @@
+export declare function bufferBody<T extends Request>(req: T): Promise<T>;

package/dist/req/bufferBody.js

@@ -0,0 +1,30 @@
+export async function bufferBody(req) {
+    const buffer = await req.arrayBuffer();
+    Object.defineProperty(req, 'bodyUsed', {
+        get: () => false,
+        configurable: true,
+    });
+    Object.defineProperty(req, 'body', {
+        get: () => new ReadableStream({
+            start(controller) {
+                controller.enqueue(new Uint8Array(buffer.slice(0)));
+                controller.close();
+            },
+        }),
+        configurable: true,
+    });
+    req.json = async () => JSON.parse(new TextDecoder().decode(buffer));
+    req.text = async () => new TextDecoder().decode(buffer);
+    req.blob = async () => new Blob([buffer.slice(0)]);
+    req.arrayBuffer = async () => buffer.slice(0);
+    req.bytes = async () => new Uint8Array(buffer.slice(0));
+    req.formData = async () => {
+        const r = new Request('http://localhost', {
+            method: req.method,
+            headers: req.headers,
+            body: buffer.slice(0),
+        });
+        return r.formData();
+    };
+    return req;
+}

package/dist/req/parseBody.d.ts

@@ -0,0 +1,4 @@
+/** Application MIME types that are parsed as text by parseBody. */
+export declare const textTypes: readonly ["application/xml", "application/xhtml+xml", "application/javascript", "application/x-javascript", "application/ecmascript", "application/yaml", "application/x-yaml", "application/graphql", "application/sql", "application/toml", "application/x-ndjson", "application/ndjson", "application/jsonl", "application/jsonlines", "application/x-jsonlines"];
+export declare const textSuffixPattern: RegExp;
+export declare function parseBody(req: Request): Promise<Record<string, unknown> | FormData | URLSearchParams | string | File>;

package/dist/req/parseBody.js

@@ -0,0 +1,49 @@
+import { parseForm } from './parseForm.js';
+const formTypes = ['multipart/form-data', 'application/x-www-form-urlencoded'];
+/** Application MIME types that are parsed as text by parseBody. */
+export const textTypes = [
+    'application/xml',
+    'application/xhtml+xml',
+    'application/javascript',
+    'application/x-javascript',
+    'application/ecmascript',
+    'application/yaml',
+    'application/x-yaml',
+    'application/graphql',
+    'application/sql',
+    'application/toml',
+    'application/x-ndjson',
+    'application/ndjson',
+    'application/jsonl',
+    'application/jsonlines',
+    'application/x-jsonlines',
+];
+export const textSuffixPattern = /\+(xml|text|yaml|json-seq)\b/;
+const includes = (ct, types) => types.some((t) => ct.includes(t));
+export async function parseBody(req) {
+    const contentType = req.headers?.get('content-type');
+    // application/json or +json suffix types (e.g. application/ld+json, application/vnd.api+json) → object
+    if (!contentType || contentType.includes('application/json') || contentType.includes('+json')) {
+        const body = await req.json();
+        req.json = () => Promise.resolve(body);
+        return body;
+    }
+    // multipart/form-data → FormData
+    if (includes(contentType, formTypes)) {
+        const body = await req.formData();
+        req.formData = () => Promise.resolve(body);
+        return parseForm(body);
+    }
+    // text/* or known text-based application types → string
+    if (contentType.startsWith('text/') || includes(contentType, textTypes) || textSuffixPattern.test(contentType)) {
+        const body = await req.text();
+        req.text = () => Promise.resolve(body);
+        return body;
+    }
+    // Everything else (octet-stream, image/*, video/*, application/pdf, etc.) → File
+    const disposition = req.headers?.get('content-disposition');
+    const fileName = disposition?.match(/filename="(.+?)"/)?.[1] ?? 'file';
+    const body = await req.blob();
+    req.blob = () => Promise.resolve(body);
+    return new File([body], fileName, { type: contentType });
+}

package/dist/req/parseForm.d.ts

@@ -0,0 +1 @@
+export declare function parseForm<T>(body: FormData): Promise<T>;

package/dist/req/parseForm.js

@@ -0,0 +1,24 @@
+export async function parseForm(body) {
+    const formData = {};
+    for (const [key, value] of body.entries()) {
+        const existing = formData[key];
+        if (value instanceof File) {
+            if (existing) {
+                formData[key] = Array.isArray(existing) ? [...existing, value] : [existing, value];
+            }
+            else {
+                formData[key] = value;
+            }
+        }
+        else {
+            const str = value.toString();
+            if (existing) {
+                formData[key] = Array.isArray(existing) ? [...existing, str] : [existing, str];
+            }
+            else {
+                formData[key] = str;
+            }
+        }
+    }
+    return formData;
+}

package/dist/{utils → req}/parseQuery.d.ts

@@ -1,4 +1,3 @@
-import type { KnownAny } from '../types';
 /**
  * Deserialize a bracket-based query string into an object.
  *
@@ -22,4 +21,4 @@ import type { KnownAny } from '../types';
  * @param queryString - The raw query string (e.g. location.search.slice(1))
  * @returns           - A nested object representing the query params
  */
-export default function parseQuery(queryString: string): Record<string, KnownAny>;
+export declare function parseQuery(queryString: string): Record<string, unknown>;

package/dist/{utils → req}/parseQuery.js

@@ -1,6 +1,3 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.default = parseQuery;
 /**
  * Parse a bracket-based key (e.g. "z[d][0][x]" or "arr[]")
  * into an array of path segments (strings or special push-markers).
@@ -135,7 +132,7 @@ function setValue(obj, path, value) {
  * @param queryString - The raw query string (e.g. location.search.slice(1))
  * @returns           - A nested object representing the query params
  */
-function parseQuery(queryString) {
+export function parseQuery(queryString) {
     const result = {};
     if (!queryString)
         return result;
@@ -145,7 +142,7 @@ function parseQuery(queryString) {
         .split('&');
     for (const pair of pairs) {
         const [rawKey, rawVal = ''] = pair.split('=');
-        const decodedKey = decodeURIComponent(rawKey || '');
+        const decodedKey = decodeURIComponent(rawKey);
         const decodedVal = decodeURIComponent(rawVal);
         // Parse bracket notation
         const pathSegments = parseKey(decodedKey);

package/dist/req/reqMeta.d.ts

@@ -0,0 +1,2 @@
+import type { VovkRequest } from '../types/request.js';
+export declare function reqMeta<T = Record<'mcpOutput' | 'xMetaHeader' | (string & {}), unknown>>(req: Partial<VovkRequest>, meta?: T | null): T;

package/dist/{utils → req}/reqMeta.js

@@ -1,8 +1,5 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.default = reqMeta;
 const metaMap = new WeakMap();
-function reqMeta(req, meta) {
+export function reqMeta(req, meta) {
     if (meta) {
         metaMap.set(req, { ...metaMap.get(req), ...meta });
     }

package/dist/req/reqQuery.d.ts

@@ -0,0 +1,2 @@
+import type { VovkRequest } from '../types/request.js';
+export declare function reqQuery<T extends object | undefined>(req: VovkRequest<unknown, T>): T;

package/dist/req/reqQuery.js

@@ -0,0 +1,4 @@
+import { parseQuery } from './parseQuery.js';
+export function reqQuery(req) {
+    return parseQuery(req.nextUrl.search);
+}

package/dist/req/validateContentType.d.ts

@@ -0,0 +1 @@
+export declare function validateContentType(request: Request | undefined, allowed: string[]): Response | null;

package/dist/req/validateContentType.js

@@ -0,0 +1,32 @@
+import { HttpException } from '../core/HttpException.js';
+import { HttpStatus } from '../types/enums.js';
+export function validateContentType(request, allowed) {
+    // Wildcard — skip validation
+    if (!request?.headers || allowed.includes('*/*'))
+        return null;
+    const raw = request.headers.get('content-type');
+    if (!raw) {
+        throw new HttpException(HttpStatus.UNSUPPORTED_MEDIA_TYPE, 'Missing Content-Type header', { allowed });
+    }
+    // Handle comma-separated content types and strip parameters like charset, boundary
+    const contentTypes = raw
+        .split(',')
+        .map((part) => part.split(';')[0].trim().toLowerCase())
+        .filter(Boolean);
+    const match = contentTypes.some((contentType) => allowed.some((pattern) => {
+        const normalized = pattern.toLowerCase();
+        // Partial wildcard: image/*, text/*, etc.
+        if (normalized.endsWith('/*')) {
+            const prefix = normalized.slice(0, -1);
+            return contentType.startsWith(prefix);
+        }
+        return contentType === normalized;
+    }));
+    if (!match) {
+        throw new HttpException(HttpStatus.UNSUPPORTED_MEDIA_TYPE, `Unsupported media type: ${contentTypes.join(', ')}`, {
+            contentTypes,
+            allowed,
+        });
+    }
+    return null;
+}

package/dist/samples/createCodeSamples.d.ts

@@ -0,0 +1,20 @@
+import type { VovkControllerSchema, VovkHandlerSchema } from '../types/core.js';
+import type { VovkSamplesConfig } from '../types/config.js';
+export type CodeSamplePackageJson = {
+    name?: string;
+    version?: string;
+    description?: string;
+    rs_name?: string;
+    py_name?: string;
+};
+export declare function createCodeSamples({ handlerName, handlerSchema, controllerSchema, package: packageJson, config, }: {
+    handlerName: string;
+    handlerSchema: VovkHandlerSchema;
+    controllerSchema: VovkControllerSchema;
+    package?: CodeSamplePackageJson;
+    config: VovkSamplesConfig;
+}): {
+    ts: string;
+    py: string;
+    rs: string;
+};