arkos 2.0.0-next.3 → 2.0.0-next.30

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

@@ -1,43 +1,35 @@
-import { ModelGroupRelationFields } from "./utils/helpers/base.service.helpers";
-import { PrismaClient } from "../../generated";
-import { CountFilters, CreateData, CreateManyData, CreateManyOptions, CreateOptions, DeleteManyFilters, DeleteOneFilters, FindManyFilters, FindManyOptions, FindOneFilters, FindOneOptions, GetPayload, Models, UpdateManyData, UpdateManyFilters, UpdateManyOptions, UpdateOneData, UpdateOneFilters, UpdateOneOptions } from "./types/base.service.types";
-import { ServiceHookContext } from "../../components/arkos-service-hook/types";
-export interface ServiceOperationHooks {
-    beforeOperation?: (params: any) => void | Promise<void>;
-    afterOperation?: (result: any, params: any) => void | Promise<void>;
-    beforePrisma?: (prismaArgs: any, params: any) => any | Promise<any>;
-    afterPrisma?: (result: any, params: any) => any | Promise<any>;
-}
+import { ModelGroupRelationFields } from './utils/helpers/base.service.helpers';
+import { PrismaClient } from '../../generated';
+import { CountFilters, CreateData, CreateManyData, CreateManyOptions, CreateOptions, DeleteManyFilters, DeleteOneFilters, FindManyFilters, FindManyOptions, FindOneFilters, FindOneOptions, GetPayload, Models, UpdateManyData, UpdateManyFilters, UpdateManyOptions, UpdateOneData, UpdateOneFilters, UpdateOneOptions } from './types/base.service.types';
+import { ServiceHookContext } from './types/base.service.types';
+import { ArkosPrismaInput } from '../../types/arkos-prisma-input';
 /**
  * Base service class for handling CRUD operations on a specific model.
  * This class provides standard implementation of data operations that can be extended
  * by model-specific service classes.
  *
- * @class BaseService
+ * @class ArkosPrismaService
  *
  * @example
  * ```ts
- * import { BaseService } from "arkos/services";
+ * import { ArkosPrismaService } from "arkos/services";
  *
- * export class UserService extends BaseService<"user"> {}
+ * export class UserService extends ArkosPrismaService<"user"> {}
  *
  * const userService = new UserService("user");
  * ```
  *
- * @see {@link https://www.arkosjs.com/docs/api-reference/the-base-service-class}
+ * @see {@link https://www.arkosjs.com/docs/reference/base-service}
  * @see {@link https://www.arkosjs.com/docs/guide/accessing-request-context-in-services}
  */
-export declare class BaseService<TModelName extends keyof Models = keyof Models> {
+export declare class ArkosPrismaService<TModelName extends keyof Models = keyof Models> {
     modelName: TModelName;
     relationFields: ModelGroupRelationFields;
-    prisma: PrismaClient;
+    private prismaInstace?;
     constructor(modelName: TModelName);
-    private getServiceHook;
+    get prisma(): PrismaClient;
     private executeOperation;
     private executeTransactionOperation;
-    private executeHooks;
-    private buildHookParams;
-    private buildTransactionHookParams;
     private handlePasswordHashing;
     private processRelationFieldsInBody;
     private buildPrismaArgs;
@@ -59,7 +51,7 @@ export declare class BaseService<TModelName extends keyof Models = keyof Models>
      * });
      * ```
      */
-    createOne<TOptions extends CreateOptions<TModelName>>(data: CreateData<TModelName>, queryOptions?: TOptions, context?: ServiceHookContext): Promise<GetPayload<TModelName, TOptions>>;
+    createOne<TOptions extends CreateOptions<TModelName>>(data: CreateData<TModelName> | ArkosPrismaInput<CreateData<TModelName>>, queryOptions?: TOptions, context?: ServiceHookContext): Promise<GetPayload<TModelName, TOptions>>;
     /**
      * Creates multiple records in the database.
      *
@@ -75,7 +67,7 @@ export declare class BaseService<TModelName extends keyof Models = keyof Models>
      * ]);
      * ```
      */
-    createMany<TOptions extends CreateManyOptions<TModelName>>(data: CreateManyData<TModelName>, queryOptions?: TOptions, context?: ServiceHookContext): Promise<GetPayload<TModelName, TOptions>[]>;
+    createMany<TOptions extends CreateManyOptions<TModelName>>(data: CreateManyData<TModelName> | ArkosPrismaInput<CreateManyData<TModelName>>, queryOptions?: TOptions, context?: ServiceHookContext): Promise<GetPayload<TModelName, TOptions>[]>;
     /**
      * Counts records matching the specified filters.
      *
@@ -147,7 +139,7 @@ export declare class BaseService<TModelName extends keyof Models = keyof Models>
      * );
      * ```
      */
-    updateOne<TOptions extends UpdateOneOptions<TModelName>>(filters: UpdateOneFilters<TModelName>, data: UpdateOneData<TModelName>, queryOptions?: TOptions, context?: ServiceHookContext): Promise<GetPayload<TModelName, TOptions>>;
+    updateOne<TOptions extends UpdateOneOptions<TModelName>>(filters: UpdateOneFilters<TModelName>, data: UpdateOneData<TModelName> | ArkosPrismaInput<UpdateOneData<TModelName>>, queryOptions?: TOptions, context?: ServiceHookContext): Promise<GetPayload<TModelName, TOptions>>;
     /**
      * Updates a single record matching the specified id.
      *
@@ -161,7 +153,7 @@ export declare class BaseService<TModelName extends keyof Models = keyof Models>
      * const updated = await userService.updateById("user-123", { name: "John Updated" });
      * ```
      */
-    updateById<TOptions extends UpdateOneOptions<TModelName>>(id: string | number, data: UpdateOneData<TModelName>, queryOptions?: TOptions, context?: ServiceHookContext): Promise<GetPayload<TModelName, TOptions>>;
+    updateById<TOptions extends UpdateOneOptions<TModelName>>(id: string | number, data: UpdateOneData<TModelName> | ArkosPrismaInput<UpdateOneData<TModelName>>, queryOptions?: TOptions, context?: ServiceHookContext): Promise<GetPayload<TModelName, TOptions>>;
     /**
      * Updates multiple records matching the specified filters.
      *
@@ -178,7 +170,7 @@ export declare class BaseService<TModelName extends keyof Models = keyof Models>
      * );
      * ```
      */
-    updateMany<TOptions extends UpdateManyOptions<TModelName>>(filters: UpdateManyFilters<TModelName>, data: UpdateManyData<TModelName>, queryOptions?: TOptions, context?: ServiceHookContext): Promise<{
+    updateMany<TOptions extends UpdateManyOptions<TModelName>>(filters: UpdateManyFilters<TModelName>, data: UpdateManyData<TModelName> | ArkosPrismaInput<UpdateManyData<TModelName>>, queryOptions?: TOptions, context?: ServiceHookContext): Promise<{
         count: number;
     }>;
     /**
@@ -234,7 +226,7 @@ export declare class BaseService<TModelName extends keyof Models = keyof Models>
      * ]);
      * ```
      */
-    batchUpdate<TOptions extends UpdateOneOptions<TModelName>>(dataArray: UpdateOneData<TModelName>[], queryOptions?: TOptions, context?: ServiceHookContext): Promise<GetPayload<TModelName, TOptions>[]>;
+    batchUpdate<TOptions extends UpdateOneOptions<TModelName>>(dataArray: UpdateOneData<TModelName>[] | ArkosPrismaInput<UpdateOneData<TModelName>>[], queryOptions?: TOptions, context?: ServiceHookContext): Promise<GetPayload<TModelName, TOptions>[]>;
     /**
      * Performs multiple delete operations in a single transaction.
      *

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

@@ -1,5 +1,16 @@
 import { ExtractPrismaData, ExtractPrismaFilters, ExtractPrismaQueryOptions, PrismaModels } from "../../../generated";
+import { User } from "../../../types";
 export type Models = PrismaModels<any>;
+export interface ServiceHookContext {
+    /**
+     * The authenticated user making the request.
+     */
+    user?: User;
+    /**
+     * The access token from the request for authorization.
+     */
+    accessToken?: string;
+}
 export type Delegate<TModelName extends keyof Models> = Models[TModelName]["Delegate"];
 export type CreateData<TModelName extends keyof Models> = ExtractPrismaData<Models[TModelName]["CreateArgs"]>;
 export type CreateOptions<TModelName extends keyof Models> = ExtractPrismaQueryOptions<Models[TModelName]["CreateArgs"], "data">;

package/dist/types/modules/base/utils/error-prettifier.d.ts

@@ -96,6 +96,14 @@ export declare class ErrorPrettifier {
      * @returns Class-validator style constraint name
      */
     private mapZodToConstraintName;
+    /**
+     * Maps a Zod `invalid_format` format (e.g. "email", "uuid", "regex") to a
+     * class-validator style constraint name.
+     *
+     * @param format - The format reported by Zod
+     * @returns Class-validator style constraint name
+     */
+    private mapZodFormatToConstraintName;
     /**
      * Prettifies Zod ZodError.
      * Handles nested paths and multiple issues per field.

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

@@ -40,7 +40,7 @@ export declare function throwErrorIfApiActionIsInvalid(apiAction: string): void;
  * @param {string[]} ignoreActions - Optional list of apiAction values to ignore.
  * @returns {Record<string, any>} The transformed data with appropriate Prisma operations applied.
  */
-export declare function handleRelationFieldsInBody(body: Record<string, any>, relationFields: ModelGroupRelationFields, ignoreActions?: string[], isRelation?: boolean): Record<string, any>;
+export declare function handleRelationFieldsInBody(body: Record<string, any>, relationFields: ModelGroupRelationFields, ignoreActions?: string[], isRelation?: boolean, parentOperation?: "create" | "update" | null): Record<string, any>;
 export type ModelGroupRelationFields = ReturnType<typeof getGroupedModelReations>;
 declare function getGroupedModelReations(modelName: string): {
     singular: PrismaField[] | undefined;

package/dist/types/modules/base/utils/model-openapi-generator.d.ts

@@ -0,0 +1,12 @@
+import { ArkosRouteConfig } from "../../../exports";
+import { PrismaQueryOptions } from "../../../exports/prisma";
+import { RouterEndpoint } from "../../../types/router-config";
+import { ExtendedOperationObject } from "../../../utils/arkos-router/types/openapi-config";
+declare class ModelOpenAPIGenerator {
+    private getModel;
+    private getAuthErrorResponses;
+    private resolvePrismaQueryOptions;
+    getOpenApiConfig(endpointRouterConfig: Omit<ArkosRouteConfig, "path"> | undefined, endpoint: RouterEndpoint, modelNameInKebab: string, prismaQueryOptions?: PrismaQueryOptions<any>): Partial<ExtendedOperationObject>;
+}
+declare const modelOpenAPIGenerator: ModelOpenAPIGenerator;
+export default modelOpenAPIGenerator;

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

@@ -21,11 +21,13 @@ export type SMTPConnectionOptions = {
     secure?: boolean;
     auth?: SMTPAuthOptions;
     name?: string;
+    user?: string;
+    pass?: string;
 };
 /**
  * A service class to handle email-related tasks, including sending emails.
  *
- * See the api reference [www.arkosjs.com/docs/api-reference/the-email-service-class](https://www.arkosjs.com/docs/api-reference/the-email-service-class)
+ * See the api reference [www.arkosjs.com/docs/reference/the-email-service-class](https://www.arkosjs.com/docs/reference/the-email-service-class)
  */
 export declare class EmailService {
     transporter: Transporter | null;

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/catch-async.d.ts

@@ -1,4 +1,4 @@
-import { ArkosRequestHandler, ArkosErrorRequestHandler } from "../../../types";
+import { ArkosAnyRequestHandler } from "../../../types";
 /**
  * Used to wrap request handlers and middleware for automatic catch async errors and throw to next to invoke the global error handler
  *
@@ -16,7 +16,7 @@ import { ArkosRequestHandler, ArkosErrorRequestHandler } from "../../../types";
  * })
  * ```
  */
-declare const catchAsync: (fn: ArkosRequestHandler | ArkosErrorRequestHandler, options?: {
+declare const catchAsync: (fn: ArkosAnyRequestHandler, options?: {
     type: "error" | "normal";
 }) => any;
 export type CatchAsyncReturnType = ReturnType<typeof catchAsync>;

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

@@ -1,10 +1,4 @@
 import AppError from "./app-error";
-export interface PrismaError {
-    code?: string;
-    message: string;
-    meta?: Record<string, any>;
-    name?: string;
-}
 export declare function handleJWTError(): AppError;
 export declare function handleJWTExpired(): AppError;
 export declare function handlePrismaClientValidationError(err: AppError): AppError;
@@ -12,37 +6,18 @@ export declare function handleAuthenticationError(_: AppError): AppError;
 export declare function handleServerNotReachableError(_: AppError): AppError;
 export declare function handleConnectionTimeoutError(_: AppError): AppError;
 export declare function handleDatabaseNotFoundError(_: AppError): AppError;
-export declare function handleEnvironmentVariableError(err: 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 handleInvalidFieldValueError(err: AppError): AppError;
-export declare function handleInvalidFieldProvidedError(err: AppError): AppError;
-export declare function handleDataValidationError(_: AppError): AppError;
-export declare function handleQueryParsingError(err: AppError): AppError;
-export declare function handleInvalidQueryFormatError(err: AppError): AppError;
-export declare function handleRawQueryExecutionError(_: AppError): AppError;
-export declare function handleNullConstraintViolationError(err: AppError): AppError;
 export declare function handleSchemaCreationFailedError(_: AppError): AppError;
 export declare function handleMigrationAlreadyAppliedError(err: AppError): AppError;
 export declare function handleMigrationScriptFailedError(err: AppError): AppError;
 export declare function handleVersionMismatchError(_: AppError): AppError;
-export declare function handleMigrationFileReadError(err: AppError): AppError;
-export declare function handleSchemaDriftError(_: AppError): AppError;
-export declare function handleSchemaSyntaxError(_: AppError): AppError;
-export declare function handleClientTypeError(_: AppError): AppError;
-export declare function handleDynamicQueryError(_: AppError): AppError;
-export declare function handleRelationLoadingError(err: AppError): AppError;
-export declare function handleBinaryError(err: AppError): AppError;
-export declare function handleNetworkError(_: AppError): AppError;
-export declare function handleUnhandledPromiseError(_: AppError): AppError;
-export declare function handleDataTypeError(err: AppError): AppError;
-export declare function handleEmptyResultError(_: AppError): AppError;
 export declare function handleNonExistingRecord(err: {
     meta?: Record<string, any>;
     [x: string]: any;
 }): AppError;
+export declare function handleDriverAdapterError(err: any): AppError | null;
 export declare function handlePrismaClientInitializationError(_: any): AppError;
-export declare function handleRequiredRelationViolationError(err: 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/get-handled-error.d.ts

@@ -0,0 +1 @@
+export declare function getHandledError(err: any): 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;
     /**
@@ -33,7 +32,13 @@ export declare class FileUploadController {
 /**
  * Controller instance responsible for handling file upload operations.
  *
- * @see {@link https://www.arkosjs.com/docs/api-reference/file-upload-controller-object}
+ * @remarks
+ * This controller handles various file upload operations including validation,
+ * storage, and response management.
+ *
+ * @instance
+ * @constant
+ * @see {@link https://www.arkosjs.com/docs/reference/file-upload-controller-object}
  */
 declare const fileUploadController: FileUploadController;
 export default fileUploadController;

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

@@ -1,5 +1,6 @@
 import multer from "multer";
 import { ArkosNextFunction, ArkosRequest, ArkosRequestHandler, ArkosResponse } from "../../types";
+import { ImageOptimizationOptions } from "./utils/helpers/file-upload.helpers";
 /**
  * Service to handle file uploads, including single and multiple file uploads,
  * file validation (type, size), and file deletion.
@@ -60,12 +61,7 @@ export declare class FileUploadService {
      * @param {object} options - Optional parameters for image processing
      * @returns {Promise<string|string[]>} URL or array of URLs to the uploaded files
      */
-    upload(req: ArkosRequest, res: ArkosResponse, next: ArkosNextFunction, options?: {
-        format?: string;
-        width?: number;
-        height?: number;
-        resizeTo?: number;
-    }): Promise<string | string[] | null>;
+    upload(req: ArkosRequest, res: ArkosResponse, next: ArkosNextFunction, options?: ImageOptimizationOptions): Promise<string | string[] | null>;
     /**
      * Deletes a file based on filename and file type from request parameters
      * @param {string} fileName - The name of the file to delete

package/dist/types/modules/file-upload/utils/file-upload-json-schema-generator.d.ts

@@ -0,0 +1,12 @@
+import { FileUploadRouterEndpoint } from "../../../types/router-config";
+import { ArkosRouteConfig } from "../../../exports";
+import { ExtendedOperationObject } from "../../../utils/arkos-router/types/openapi-config";
+declare class FileUploadJsonSchemaGenerator {
+    private formatBytes;
+    private getFileTypeDescription;
+    private getMultipartRequestBody;
+    private getImageQueryParameters;
+    getOpenApiConfig(endpointRouterConfig: Omit<ArkosRouteConfig, "path"> | undefined, endpoint: FileUploadRouterEndpoint): Partial<ExtendedOperationObject>;
+}
+declare const fileUploadJsonSchemaGenerator: FileUploadJsonSchemaGenerator;
+export default fileUploadJsonSchemaGenerator;

package/dist/types/modules/file-upload/utils/helpers/file-upload.helpers.d.ts

@@ -12,7 +12,27 @@ export declare function generateRelativePath(filePath: string, uploadDir: string
  * Handles basic file processing for non-image files
  */
 export declare const processFile: (req: ArkosRequest, filePath: string) => string;
+/**
+ * Options accepted by the image optimizer. Numeric values may arrive as
+ * strings from query parameters and are normalized internally.
+ */
+export interface ImageOptimizationOptions {
+    /** Set to `false` to skip optimization and keep the original bytes as-is. */
+    optimize?: boolean;
+    format?: string;
+    quality?: number | string;
+    width?: number | string;
+    height?: number | string;
+    resizeTo?: number | string;
+    fit?: "cover" | "contain" | "fill" | "inside" | "outside";
+    withoutEnlargement?: boolean;
+}
+/**
+ * Optimizes an image file in place using Sharp. Returns the resulting file
+ * path, which may use a different extension when a format is requested.
+ */
+export declare const optimizeImage: (filePath: string, options?: ImageOptimizationOptions) => Promise<string>;
 /**
  * Processes image files using Sharp for resizing and format conversion
  */
-export declare const processImage: (req: ArkosRequest, next: ArkosNextFunction, filePath: string, options: Record<string, any>) => Promise<string | null>;
+export declare const processImage: (req: ArkosRequest, next: ArkosNextFunction, filePath: string, options?: ImageOptimizationOptions) => Promise<string | null>;

package/dist/types/modules/file-upload/utils/helpers/serve-upload-dir.d.ts

@@ -0,0 +1,43 @@
+import express from "express";
+import type { UploadPrepare } from "../../../../types/upload";
+import { IArkosRouter } from "../../../../utils/arkos-router/types";
+export type ServeUploadDirOptions = {
+    /**
+     * Public URL folder, relative to the file upload `baseRoute`.
+     *
+     * @default `"/" + dir`
+     */
+    urlPath?: string;
+    /**
+     * Resolves the disk parameters for this folder. Required for every dynamic
+     * folder (`:param` in `dir`). It may be async and may throw to deny the
+     * request.
+     */
+    prepare?: UploadPrepare;
+    /**
+     * Options passed to `express.static`.
+     */
+    expressStatic?: Parameters<typeof express.static>[1];
+    /**
+     * Allow files in nested folders.
+     *
+     * @default false
+     */
+    recursive?: boolean;
+};
+/**
+ * Serves a folder from the upload directory.
+ *
+ * Authentication belongs on the router mount:
+ *
+ * ```ts
+ * fileUploadRouter.use(
+ *   { authentication: fileUploadPolicy.View },
+ *   arkos.serveUploadDir("/storage/acme", { urlPath: "/private/files" })
+ * );
+ * ```
+ *
+ * When the resolved `dir` is a file, the route serves that file directly.
+ * When it is a directory, the remainder of the request URL is served from it.
+ */
+export declare function serveUploadDir(dir: string, options?: ServeUploadDirOptions): IArkosRouter;

package/dist/types/modules/file-upload/utils/helpers/upload-path.helper.d.ts

@@ -0,0 +1,14 @@
+export declare const DEFAULT_UPLOAD_DIRS: readonly ["images", "videos", "documents", "files"];
+export declare function isSafeUploadSegment(segment: string, allowParam?: boolean): boolean;
+export declare function assertSafeUploadPath(value: string, options?: {
+    allowParams?: boolean;
+    label?: string;
+}): string;
+export declare function normalizeUploadDir(dir: string): string;
+export declare function normalizeUploadUrlPath(urlPath: string): string;
+export declare function isSafeUploadParam(value: unknown): value is string;
+export declare function isPathInside(base: string, target: string): boolean;
+export declare function resolveUploadPath(root: string, relative: string, options?: {
+    strictSegments?: boolean;
+}): string | null;
+export declare function isRealPathInside(base: string, target: string): Promise<boolean>;

package/dist/types/modules/file-upload/utils/helpers/upload-serving-validation.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Validates the upload serving registrations collected while building the
+ * routers. Must run once, after every router has been constructed.
+ */
+export declare function validateUploadServingConfig(): void;

package/dist/types/modules/file-upload/utils/helpers/upload-serving.registry.d.ts

@@ -0,0 +1,31 @@
+import type { UploadUrlPath } from "../../../../types/upload";
+export type UploadWriteRegistration = {
+    dir?: string;
+    urlPath?: UploadUrlPath;
+    serve?: boolean;
+    route: string;
+    hasPrepare?: boolean;
+    type?: "single" | "array" | "fields";
+};
+export type UploadServeRegistration = {
+    dir: string;
+    urlPath: string;
+    dirParams: string[];
+    pathParams: string[];
+    recursive: boolean;
+    dynamic: boolean;
+    hasPrepare: boolean;
+};
+export declare class UploadServingRegistry {
+    private writeRegistrations;
+    private serveRegistrations;
+    private findFileServingEnabled;
+    registerWrite(registration: UploadWriteRegistration): void;
+    registerServe(registration: UploadServeRegistration): void;
+    getWriteRegistrations(): UploadWriteRegistration[];
+    getServeRegistrations(): UploadServeRegistration[];
+    setFindFileServingEnabled(enabled: boolean): void;
+    isFindFileServingEnabled(): boolean;
+    reset(): void;
+}
+export declare const uploadServingRegistry: UploadServingRegistry;

package/dist/types/modules/swagger/swagger.router.d.ts

@@ -1,6 +1,5 @@
-import { Router } from "express";
 import { ArkosNextFunction, ArkosRequest, ArkosResponse } from "../../exports";
 import { Arkos } from "../../types/arkos";
 import { UserArkosConfig } from "../../utils/define-config";
-export declare function getSwaggerRouter(arkosConfig: UserArkosConfig, app: Arkos): Router;
+export declare function getSwaggerRouter(arkosConfig: UserArkosConfig, app: Arkos): import("../../exports").IArkosRouter;
 export declare function scalarMiddleware(scalarHandler: any, swaggerSpecification: object, swaggerConfigs: any): (req: ArkosRequest, res: ArkosResponse, next: ArkosNextFunction) => Promise<any>;