arkos 2.0.0-next.13 → 2.0.0-next.16

package/dist/types/exports/error-handler/index.d.ts

@@ -1,3 +1,4 @@
 import catchAsync from "../../modules/error-handler/utils/catch-async";
 import AppError from "../../modules/error-handler/utils/app-error";
+export * from "../../modules/error-handler/utils/errors";
 export { catchAsync, AppError };

package/dist/types/modules/auth/auth.service.d.ts

@@ -2,6 +2,7 @@ import { User } from "../../types";
 import { ArkosRequest, ArkosRequestHandler } from "../../types";
 import { AuthJwtPayload, AccessAction, AccessControlConfig, AuthenticationControlConfig, DetailedAccessControlRule } from "../../types/auth";
 import { MsDuration } from "./utils/helpers/auth.controller.helpers";
+import { CookieOptions } from "express";
 /**
  * Handles various authentication-related tasks such as JWT signing, password hashing, and verifying user credentials.
  */
@@ -66,12 +67,7 @@ export declare class AuthService {
      * res.cookie('jwt', token, cookieOptions);
      * ```
      */
-    getJwtCookieOptions(req: ArkosRequest): {
-        expires: Date;
-        httpOnly: boolean;
-        secure: boolean;
-        sameSite: "none" | "strict" | "lax";
-    };
+    getJwtCookieOptions(req: ArkosRequest): CookieOptions;
     /**
      * Is used by default internally by Arkos under `BaseService` class to check if the password is already hashed.
      *

package/dist/types/modules/base/base.service.d.ts

@@ -30,8 +30,9 @@ export interface ServiceOperationHooks {
 export declare class BaseService<TModelName extends keyof Models = keyof Models> {
     modelName: TModelName;
     relationFields: ModelGroupRelationFields;
-    prisma: PrismaClient;
+    private prismaInstace?;
     constructor(modelName: TModelName);
+    get prisma(): PrismaClient;
     private getServiceHook;
     private executeOperation;
     private executeTransactionOperation;

package/dist/types/modules/error-handler/utils/app-error.d.ts

@@ -5,7 +5,6 @@
  *
  * @property {number} statusCode - HTTP status code of the error.
  * @property {string} status - Status message derived from the status code (`fail` for 4xx, `error` for 5xx).
- * @property {boolean} [missing=false] - Flag to indicate if a resource is missing.
  * @property {boolean} isOperational - Indicates if the error is operational (intended for client visibility).
  * @property {string} [code] - Optional error code for categorization.
  * @property {Record<string, any>} [meta] - Additional metadata related to the error.
@@ -33,7 +32,6 @@
 declare class AppError extends Error {
     statusCode: number;
     status: string;
-    missing?: boolean;
     isOperational: boolean;
     code?: string;
     meta?: Record<string, any>;

package/dist/types/modules/error-handler/utils/error-handler.helpers.d.ts

@@ -8,7 +8,7 @@ export declare function handleConnectionTimeoutError(_: AppError): AppError;
 export declare function handleDatabaseNotFoundError(_: AppError): AppError;
 export declare function handleFieldValueTooLargeError(err: AppError): AppError;
 export declare function handleRecordNotFoundError(_: AppError): AppError;
-export declare function handleUniqueConstraintError(err: AppError): AppError;
+export declare function handleUniqueConstraintError(err: any): AppError;
 export declare function handleForeignKeyConstraintError(_: AppError): AppError;
 export declare function handleConstraintFailedError(err: AppError): AppError;
 export declare function handleSchemaCreationFailedError(_: AppError): AppError;

package/dist/types/modules/error-handler/utils/errors.d.ts

@@ -0,0 +1,176 @@
+import AppError from "./app-error";
+/**
+ * 400 - Bad Request
+ * @example throw new BadRequestError("Invalid input", "InvalidInput", { field: "email" })
+ */
+export declare class BadRequestError extends AppError {
+    constructor(message?: string, code?: string, meta?: Record<string, any>);
+}
+/**
+ * 401 - Unauthorized
+ * @example throw new UnauthorizedError("Invalid token", "InvalidToken")
+ */
+export declare class UnauthorizedError extends AppError {
+    constructor(message?: string, code?: string, meta?: Record<string, any>);
+}
+/**
+ * 402 - Payment Required
+ * @example throw new PaymentRequiredError("Subscription expired", "PaymentRequired")
+ */
+export declare class PaymentRequiredError extends AppError {
+    constructor(message?: string, code?: string, meta?: Record<string, any>);
+}
+/**
+ * 403 - Forbidden
+ * @example throw new ForbiddenError("Access denied", "Forbidden", { resource: "admin" })
+ */
+export declare class ForbiddenError extends AppError {
+    constructor(message?: string, code?: string, meta?: Record<string, any>);
+}
+/**
+ * 404 - Not Found
+ * @example throw new NotFoundError("User not found", "NotFound", { id: 123 })
+ */
+export declare class NotFoundError extends AppError {
+    constructor(message?: string, code?: string, meta?: Record<string, any>);
+}
+/**
+ * 405 - Method Not Allowed
+ * @example throw new MethodNotAllowedError("POST not allowed", "MethodNotAllowed")
+ */
+export declare class MethodNotAllowedError extends AppError {
+    constructor(message?: string, code?: string, meta?: Record<string, any>);
+}
+/**
+ * 406 - Not Acceptable
+ * @example throw new NotAcceptableError("Unsupported format", "NotAcceptable")
+ */
+export declare class NotAcceptableError extends AppError {
+    constructor(message?: string, code?: string, meta?: Record<string, any>);
+}
+/**
+ * 408 - Request Timeout
+ * @example throw new RequestTimeoutError("Upload took too long", "RequestTimeout")
+ */
+export declare class RequestTimeoutError extends AppError {
+    constructor(message?: string, code?: string, meta?: Record<string, any>);
+}
+/**
+ * 409 - Conflict
+ * @example throw new ConflictError("Duplicate entry", "Conflict", { field: "email" })
+ */
+export declare class ConflictError extends AppError {
+    constructor(message?: string, code?: string, meta?: Record<string, any>);
+}
+/**
+ * 410 - Gone
+ * @example throw new GoneError("Resource deleted", "Gone")
+ */
+export declare class GoneError extends AppError {
+    constructor(message?: string, code?: string, meta?: Record<string, any>);
+}
+/**
+ * 411 - Length Required
+ * @example throw new LengthRequiredError("Content-Length missing", "LengthRequired")
+ */
+export declare class LengthRequiredError extends AppError {
+    constructor(message?: string, code?: string, meta?: Record<string, any>);
+}
+/**
+ * 412 - Precondition Failed
+ * @example throw new PreconditionFailedError("ETag mismatch", "PreconditionFailed")
+ */
+export declare class PreconditionFailedError extends AppError {
+    constructor(message?: string, code?: string, meta?: Record<string, any>);
+}
+/**
+ * 413 - Payload Too Large
+ * @example throw new PayloadTooLargeError("File exceeds 10MB", "PayloadTooLarge", { max: "10MB" })
+ */
+export declare class PayloadTooLargeError extends AppError {
+    constructor(message?: string, code?: string, meta?: Record<string, any>);
+}
+/**
+ * 414 - URI Too Long
+ * @example throw new UriTooLongError("Query string too long", "UriTooLong")
+ */
+export declare class UriTooLongError extends AppError {
+    constructor(message?: string, code?: string, meta?: Record<string, any>);
+}
+/**
+ * 415 - Unsupported Media Type
+ * @example throw new UnsupportedMediaTypeError("Expected JSON", "UnsupportedMediaType")
+ */
+export declare class UnsupportedMediaTypeError extends AppError {
+    constructor(message?: string, code?: string, meta?: Record<string, any>);
+}
+/**
+ * 416 - Range Not Satisfiable
+ * @example throw new RangeNotSatisfiableError("Invalid byte range", "RangeNotSatisfiable")
+ */
+export declare class RangeNotSatisfiableError extends AppError {
+    constructor(message?: string, code?: string, meta?: Record<string, any>);
+}
+/**
+ * 417 - Expectation Failed
+ * @example throw new ExpectationFailedError("Expect header failed", "ExpectationFailed")
+ */
+export declare class ExpectationFailedError extends AppError {
+    constructor(message?: string, code?: string, meta?: Record<string, any>);
+}
+/**
+ * 418 - I'm a teapot
+ * @example throw new ImATeapotError("Cannot brew coffee", "ImATeapot")
+ */
+export declare class ImATeapotError extends AppError {
+    constructor(message?: string, code?: string, meta?: Record<string, any>);
+}
+/**
+ * 422 - Unprocessable Content
+ * @example throw new UnprocessableContentError("Validation failed", "ValidationFailed", { errors: [...] })
+ */
+export declare class UnprocessableContentError extends AppError {
+    constructor(message?: string, code?: string, meta?: Record<string, any>);
+}
+/**
+ * 429 - Too Many Requests
+ * @example throw new TooManyRequestsError("Rate limit exceeded", "RateLimitExceeded", { retryAfter: 60 })
+ */
+export declare class TooManyRequestsError extends AppError {
+    constructor(message?: string, code?: string, meta?: Record<string, any>);
+}
+/**
+ * 500 - Internal Server Error
+ * @example throw new InternalServerError("Database connection failed", "DatabaseError")
+ */
+export declare class InternalServerError extends AppError {
+    constructor(message?: string, code?: string, meta?: Record<string, any>);
+}
+/**
+ * 501 - Not Implemented
+ * @example throw new NotImplementedError("Feature coming soon", "NotImplemented")
+ */
+export declare class NotImplementedError extends AppError {
+    constructor(message?: string, code?: string, meta?: Record<string, any>);
+}
+/**
+ * 502 - Bad Gateway
+ * @example throw new BadGatewayError("Upstream timeout", "BadGateway")
+ */
+export declare class BadGatewayError extends AppError {
+    constructor(message?: string, code?: string, meta?: Record<string, any>);
+}
+/**
+ * 503 - Service Unavailable
+ * @example throw new ServiceUnavailableError("Maintenance mode", "ServiceUnavailable", { retryAfter: 300 })
+ */
+export declare class ServiceUnavailableError extends AppError {
+    constructor(message?: string, code?: string, meta?: Record<string, any>);
+}
+/**
+ * 504 - Gateway Timeout
+ * @example throw new GatewayTimeoutError("Upstream timeout", "GatewayTimeout")
+ */
+export declare class GatewayTimeoutError extends AppError {
+    constructor(message?: string, code?: string, meta?: Record<string, any>);
+}

package/dist/types/modules/error-handler/utils/multer-error-handler.d.ts

@@ -0,0 +1,7 @@
+import multer from "multer";
+import AppError from "./app-error";
+declare class MulterErrorHandler {
+    handle(err: multer.MulterError): AppError;
+}
+declare const multerErrorHandler: MulterErrorHandler;
+export default multerErrorHandler;

package/dist/types/modules/file-upload/file-upload.controller.d.ts

@@ -2,7 +2,6 @@
  * Handles file uploads and allows to be extended via route hooks.
  */
 export declare class FileUploadController {
-    private handleUploadError;
     private getRouteHook;
     private getAfterHook;
     /**

package/dist/types/modules/swagger/utils/helpers/get-swagger-default-configs.d.ts

@@ -1,2 +1,48 @@
-import { ArkosConfig } from "../../../../exports";
-export default function getSwaggerDefaultConfig(defaultModelsPaths: Record<string, any>): ArkosConfig["swagger"];
+export default function getSwaggerDefaultConfig(defaultModelsPaths: Record<string, any>): {
+    endpoint: string;
+    mode: string;
+    strict: boolean;
+    options: {
+        definition: {
+            openapi: string;
+            info: {
+                title: string;
+                version: string;
+                description: string;
+            };
+            servers: {
+                url: string;
+                description: string;
+            }[];
+            paths: Record<string, any>;
+            components: {
+                securitySchemes: {
+                    BearerAuth: {
+                        type: string;
+                        scheme: string;
+                        bearerFormat: string;
+                    };
+                };
+            };
+            security: never[];
+        };
+        apis: string[];
+        deepLinking: boolean;
+        tryItOutEnabled: boolean;
+        persistAuthorization: boolean;
+    };
+    scalarApiReferenceConfiguration: {
+        theme: string;
+        darkMode: boolean;
+        layout: string;
+        showSidebar: boolean;
+        hideDownloadButton: boolean;
+        cdn: string;
+        metaData: {
+            title: string;
+            description: string;
+        };
+        pageTitle: string;
+        customCss: string;
+    };
+};

package/dist/types/types/arkos-prisma-input.d.ts

@@ -131,9 +131,10 @@ type StripPrismaFilters<T> = T extends {
     OR?: any;
 } | {
     NOT?: any;
-} ? never : T;
+} ? Omit<T, "equals" | "in" | "notIn" | "lt" | "lte" | "gt" | "gte" | "AND" | "OR" | "NOT"> : T;
+type StripToScalar<T> = T extends string | number | boolean | Date | null | undefined ? T : never;
 type FlattenRelations<T> = {
-    [K in keyof T]: IsArrayRelation<T[K]> extends true ? FlattenArrayRelation<T[K]> : IsObjectRelation<T[K]> extends true ? XOR<FlattenObjectRelation<T[K]>, T[K]> : StripPrismaFilters<T[K]> extends never ? never : T[K] extends object ? T[K] extends Date | null | undefined ? T[K] : FlattenRelations<StripPrismaFilters<T[K]>> : StripPrismaFilters<T[K]>;
+    [K in keyof T]: IsArrayRelation<T[K]> extends true ? FlattenArrayRelation<T[K]> | undefined : IsObjectRelation<T[K]> extends true ? XOR<FlattenObjectRelation<T[K]> | undefined, T[K]> : StripPrismaFilters<T[K]> extends never ? never : T[K] extends object ? T[K] extends Date | null | undefined ? T[K] : FlattenRelations<StripPrismaFilters<T[K]>> | undefined : StripToScalar<T[K]> extends never ? StripPrismaFilters<T[K]> : StripToScalar<T[K]>;
 };
 /**
  * Flattens Prisma relation inputs into a simpler, developer-friendly format

package/dist/types/types/index.d.ts

@@ -140,27 +140,6 @@ export type UserRole = User extends {
     role: infer R;
 } ? R : string;
 export interface ArkosRequest<P extends Record<string, any> = any, ResBody = any, ReqBody = any, Query extends Record<string, any> = any> extends Request<P, ResBody, ReqBody, Query> {
-    /**
-     * Request signals used to control Arkos's built-in request handling pipeline.
-     *
-     * @since v1.6.0-beta
-     */
-    signals?: {
-        /**
-         * When set to `true` in a `before` hook, Arkos skips its built-in logic for the current pipeline step (e.g. CRUD, authentication, authorization).
-         * Automatically reset to `false` after the step completes.
-         *
-         * @example
-         * ```ts
-         * before: (req, res, next) => {
-         *   req.user = myCustomAuth(req);
-         *   req.signals.skip = true;
-         *   next();
-         * }
-         * ```
-         */
-        skip?: boolean;
-    };
     /**
      * Authenticated user
      */

package/dist/types/types/new-arkos-config.d.ts

@@ -1,5 +1,5 @@
 import cors from "cors";
-import express from "express";
+import express, { CookieOptions } from "express";
 import { Options as RateLimitOptions } from "express-rate-limit";
 import cookieParser from "cookie-parser";
 import compression from "compression";
@@ -16,6 +16,41 @@ import { AuthenticateHookHandler, AuthenticateAfterHookHandler, AuthenticateErro
  * Defines the initial configs of the api to be loaded at startup when arkos.init() is called.
  */
 export type ArkosConfig = {
+    /**
+     * Configuration for resolving your Arkos application's source files at runtime.
+     *
+     * @since 1.6.1-canary.2
+     *
+     */
+    source?: {
+        /**
+         * The entry point file of your Arkos application, resolved at runtime.
+         *
+         * This should point to the file where `app.listen()` or `app.listen(server)`
+         * is called to start the HTTP server.
+         *
+         * Supports both TypeScript and JavaScript projects.
+         *
+         * @type {string}
+         *
+         * @default "src/app.ts" (TypeScript) | "src/app.js" (JavaScript)
+         *
+         * @since 1.6.1-canary.2
+         *
+         * @example
+         * ```ts
+         * // TypeScript project
+         * entryPoint: "src/app.ts"
+         *
+         * // JavaScript project
+         * entryPoint: "src/app.js"
+         *
+         * // Custom path
+         * entryPoint: "src/server/main.ts"
+         * ```
+         */
+        entryPoint?: string;
+    };
     /**
      * The global prefixer for the whole application
      *
@@ -297,20 +332,42 @@ export type ArkosConfig = {
                 /**
                  * Whether the cookie should be marked as secure (sent only over HTTPS).
                  * Defaults to `true` in production and `false` in development.
+                 *
+                 * @env `JWT_COOKIE_SECURE`
                  */
                 secure?: boolean;
                 /**
                  * Whether the cookie should be marked as HTTP-only.
                  * Default is `true` to prevent access via JavaScript.
+                 *
+                 * @env `JWT_COOKIE_HTTP_ONLY`
                  */
                 httpOnly?: boolean;
                 /**
                  * Controls the SameSite attribute of the cookie.
                  * Defaults to "none" in production and "lax" in development.
                  * Options: "lax" | "strict" | "none"
+                 *
+                 * @env `JWT_COOKIE_SAME_SITE`
                  */
                 sameSite?: "lax" | "strict" | "none";
-            };
+                /**
+                 * Expiry date of the cookie in GMT. If not specified (undefined), creates a session cookie.
+                 *
+                 * @default `now() + authentication.jwt.expireIn | JWT_EXPIRES_IN`
+                 *
+                 * @since 1.5.11-beta
+                 */
+                expires?: Date | undefined;
+                /**
+                 * Domain for the cookie. Use a leading dot (e.g. `.example.com`) to include all subdomains.
+                 *
+                 * @env `JWT_COOKIE_DOMAIN`
+                 *
+                 * @since 1.5.11-beta
+                 */
+                domain?: string | undefined;
+            } & Omit<CookieOptions, "secure" | "httpOnly" | "sameSite" | "expires" | "domain">;
         };
     };
     /** Allows to customize and toggle the built-in validation, by default it is set to `false`. If true is passed it will use validation with the default resolver set to `class-validator` if you intend to change the resolver to `zod` do the following:
@@ -385,9 +442,15 @@ export type ArkosConfig = {
     /**
      * Defines file upload configurations
      *
-     * See [www.arkosjs.com/docs/core-concepts/file-upload#costum-configurations](https://www.arkosjs.com/docs/core-concepts/file-upload#costum-configurations)
+     * See {@link https://www.arkosjs.com/docs/guides/file-handling/file-uploads/setup}
      */
     fileUpload?: {
+        /**
+         * Disables built-in file upload
+         *
+         * @since 1.5.11-beta
+         */
+        enabled?: boolean;
         /**
          * Defiens the base file upload directory, default is set to /uploads (on root directory)
          *
@@ -501,25 +564,35 @@ export type ArkosConfig = {
         /**
          * Configuration for CORS (Cross-Origin Resource Sharing).
          *
-         * @property {string | string[] | "all"} [allowedOrigins] - List of allowed origins. If set to `"all"`, all origins are accepted.
-         * @property {import('cors').CorsOptions} [options] - Additional CORS options passed directly to the `cors` middleware.
-         * @property {import('cors').CorsOptionsDelegate} [customHandler] - A custom middleware function that overrides the default behavior.
+         * Accepts:
+         * - `false` — disables CORS middleware entirely.
+         * - `cors.CorsOptions` — passed directly to the `cors` middleware.
+         * - `cors.CorsOptionsDelegate` — a delegate function passed directly to the `cors` middleware.
+         * - `ArkosRequestHandler` — a full Express middleware that replaces the cors middleware entirely.
+         * - An object with deprecated `allowedOrigins`, `options`, and `customHandler` properties.
          *
-         * @remarks
-         * If `customHandler` is provided, both `allowedOrigins` and `options` will be ignored in favor of the custom logic.
+         * In development, defaults to `origin: true, credentials: true`.
+         * In production, defaults to `origin: "*"` (equivalent to plain `cors()`).
          *
          * See https://www.npmjs.com/package/cors
          */
-        cors?: false | {
+        cors?: false | cors.CorsOptions | cors.CorsOptionsDelegate | {
             /**
-             * Defines allowed origins to acess the API.
+             * Defines allowed origins to access the API.
+             *
+             * @deprecated Use `cors: { origin: string | string[] }` (cors.CorsOptions) directly instead.
+             */
+            allowedOrigins?: string | string[] | "*" | true;
+            /**
+             * Additional cors options.
+             *
+             * @deprecated Pass cors.CorsOptions directly instead: `cors: { origin: "...", credentials: true }`.
              */
-            allowedOrigins?: string | string[] | "*";
             options?: cors.CorsOptions;
             /**
-             * If you would like to override the entire middleware
+             * If you would like to override the entire middleware.
              *
-             * see
+             * @deprecated Pass the handler directly instead: `cors: myCorsHandler`.
              */
             customHandler?: cors.CorsOptionsDelegate;
         } | ArkosRequestHandler;
@@ -534,7 +607,10 @@ export type ArkosConfig = {
          *
          * See [www.npmjs.com/package/cookie-parser](https://www.npmjs.com/package/cookie-parser) for further details.
          */
-        cookieParser?: false | Parameters<typeof cookieParser> | ArkosRequestHandler;
+        cookieParser?: false | {
+            secret?: string | string[];
+            options?: Parameters<typeof cookieParser>[1];
+        } | ArkosRequestHandler;
         /**
        * Options to define how query must be parsed.
        *
@@ -867,4 +943,97 @@ export type ArkosConfig = {
          */
         instance: PrismaClient;
     };
+    /**
+     * Allows to suppress specific warnings emitted by Arkos at startup or runtime.
+     *
+     * @since 1.5.10-beta
+     */
+    warnings?: {
+        /**
+         * Suppresses specific warning messages.
+         */
+        suppress?: {
+            /**
+             * Suppresses Prisma-related warnings.
+             */
+            prisma?: {
+                /**
+                 * Suppresses the warning emitted when no Prisma instance is found.
+                 */
+                noInstanceFound?: boolean;
+                /**
+                 * Suppresses the warning emitted when no Prisma schema is found.
+                 */
+                noSchemaFound?: boolean;
+            };
+        };
+    };
+    /**
+     * Defines static file serving configurations.
+     *
+     * Arkos will automatically serve files from the configured folder using `express.static`.
+     * If the folder does not exist at startup, a warning will be emitted.
+     *
+     * **Note:** The static files route is **not** prefixed with the `globalPrefix`.
+     *
+     * @since 1.7.0-canary.16
+     *
+     * @example
+     * ```ts
+     * import { defineConfig } from "arkos"
+     *
+     * export default defineConfig({
+     *   staticFiles: {
+     *     folder: "assets",
+     *     prefix: "/static",
+     *   }
+     * })   */
+    staticFiles?: {
+        /**
+         * Whether to enable static file serving.
+         *
+         * Set to `false` to disable static file serving entirely and suppress
+         * the warning when the folder is not found.
+         *
+         * @default true
+         */
+        enabled?: boolean;
+        /**
+         * The folder to serve static files from, relative to the project root.
+         *
+         * @default "public"
+         */
+        folder?: string;
+        /**
+         * The URL path prefix under which static files will be served.
+         *
+         * **Note:** This is not affected by `globalPrefix`.
+         *
+         * @default "/"
+         *
+         * @example "/static" // files served at /static/image.png
+         */
+        prefix?: string;
+        /**
+         * Options passed directly to `express.static()`.
+         *
+         * By passing custom options, they will be deep merged with the defaults.
+         *
+         * #### Default:
+         * ```ts
+         * {
+         *   maxAge: "1y",
+         *   etag: true,
+         *   lastModified: true,
+         *   dotfiles: "ignore",
+         *   fallthrough: true,
+         *   index: false,
+         *   cacheControl: true,
+         * }
+         * ```
+         *
+         * @see {@link https://expressjs.com/en/4x/api.html#express.static}
+         */
+        expressStatic?: Parameters<typeof express.static>[1];
+    };
 };

package/dist/types/types/router-config.d.ts

@@ -63,7 +63,7 @@ type FileUploadRouterConfig = {
     [K in FileUploadRouterEndpoint]?: Omit<ArkosRouteConfig, "path" | "uploads">;
 };
 /**
- * @deprecated use RouteHook instead
+ * @deprecated use 'import { RouteHook } from "arkos"' instead
  */
 export type RouterConfig<T extends string = string> = T extends "auth" ? AuthRouterConfig : T extends "file-upload" ? FileUploadRouterConfig : BaseRouterConfig;
 /**

package/dist/types/utils/arkos-router/arkos-router-openapi-manager.d.ts

@@ -1,6 +1,7 @@
 import { OpenAPIV3 } from "openapi-types";
 import { UploadConfig } from "./types/upload-config";
 declare class ArkosRouterOpenAPIManager {
+    private resolveSchemaFieldName;
     /**
      * Generates OpenAPI schema for file upload fields in multipart/form-data requests.
      * Converts upload configuration into OpenAPI-compliant schema and merges with existing body schema.
@@ -20,9 +21,21 @@ declare class ArkosRouterOpenAPIManager {
      *
      * @example
      * // Multiple fields upload
-     * addUploadFields({ type: 'fields', fields: [{ name: 'avatar', maxCount: 1 }, { name: 'resume', maxCount: 1 }] })
+     * addUploadFields({
+     *   type: 'fields',
+     *   fields: [
+     *     { name: 'avatar', type: 'single', uploadDir: 'images' },
+     *     { name: 'gallery', type: 'array', maxCount: 6, uploadDir: 'gallery' },
+     *     { name: 'banners[][images]', type: 'array', maxCount: 5, uploadDir: 'banners' }
+     *   ]
+     * })
      */
     addUploadFields(uploadConfig: UploadConfig, existingSchema?: OpenAPIV3.SchemaObject): OpenAPIV3.SchemaObject;
+    /**
+     * Builds the OpenAPI property schema for a single field entry.
+     * Legacy entries (no type) are treated as array.
+     */
+    private buildFieldSchema;
     /**
      * Validates that a user-defined multipart/form-data schema includes all required upload fields
      * with correct types, formats, and required flags.