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

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

@@ -1,26 +1,64 @@
-import cors from "cors";
-import express from "express";
-import { Options as RateLimitOptions } from "express-rate-limit";
-import cookieParser from "cookie-parser";
-import compression from "compression";
-import { Options as QueryParserOptions } from "../utils/helpers/query-parser.helpers";
-import { ValidatorOptions } from "class-validator";
-import { MsDuration } from "../modules/auth/utils/helpers/auth.controller.helpers";
-import { OpenAPIV3 } from "openapi-types";
-import type { ApiReferenceConfiguration } from "@scalar/express-api-reference" with { "resolution-mode": "import" };
-import nodemailer from "nodemailer";
-import { ArkosRequestHandler } from ".";
-import { PrismaClient } from "../generated";
+import cors from 'cors';
+import express, { CookieOptions } from 'express';
+import { Options as RateLimitOptions } from 'express-rate-limit';
+import cookieParser from 'cookie-parser';
+import compression from 'compression';
+import { Options as QueryParserOptions } from '../utils/helpers/query-parser.helpers';
+import { ValidatorOptions } from 'class-validator';
+import { MsDuration } from '../modules/auth/utils/helpers/auth.controller.helpers';
+import { OpenAPIV3 } from 'openapi-types';
+import type { ApiReferenceConfiguration } from '@scalar/express-api-reference' with {
+    'resolution-mode': 'import'
+};
+import nodemailer from 'nodemailer';
+import { ArkosRequestHandler } from '.';
+import { PrismaClient } from '../generated';
+import { AuthenticateHookHandler, AuthenticateAfterHookHandler, AuthenticateErrorHookHandler, AuthorizeHookHandler, AuthorizeAfterHookHandler, AuthorizeErrorHookHandler } from './arkos-config/utils';
 /**
- * Defines the initial configs of the api to be loaded at startup when arkos.init() is called.
+ * Defines the initial configs of the api to be loaded at startup.
  */
 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
      *
      * @default "/api"
      */
-    globalPrefix?: string;
+    readonly globalPrefix?: string;
     /**
      * Allows to configure request configs
      */
@@ -66,16 +104,139 @@ export type ArkosConfig = {
     /**
      * Defines authentication related configurations, by default is undefined.
      *
-     * See [www.arkosjs.com/docs/core-concepts/authentication-system](https://www.arkosjs.com/docs/core-concepts/authentication-system) for details.
+     * See [www.arkosjs.com/docs/core-concepts/authentication/setup](https://www.arkosjs.com/docs/core-concepts/authentication/setup) for details.
      */
     authentication?: {
+        /**
+         * Lifecycle hooks for the built-in authentication and authorization pipeline.
+         *
+         * These hooks only apply to **auto-generated Arkos routes**. On custom routes using
+         * `authService.authenticate` directly, chain them manually as standard middlewares.
+         *
+         * Hooks run as standard Express middlewares — call `next()` to continue or
+         * `next(error)` to abort and forward to the global error handler.
+         *
+         * @see {@link https://www.arkosjs.com/docs/core-concepts/authentication/hooks}
+         */
+        hooks?: {
+            authenticate?: {
+                /**
+                 * Runs before JWT extraction and verification.
+                 *
+                 * @example
+                 * ```ts
+                 * before: ({ req, skip, action, resource, rule }) => {
+                 *   req.authContext = { startedAt: Date.now() };
+                 * }
+                 * ```
+                 *
+                 * @example Skip core logic entirely (e.g. custom auth)
+                 * ```ts
+                 * before: ({ req, skip, action, resource, rule }) => {
+                 *   req.user = myCustomAuth(req);
+                 *   skip();
+                 * }
+                 * ```
+                 */
+                before?: AuthenticateHookHandler | AuthenticateHookHandler[];
+                /**
+                 * Runs after `req.user` has been set.
+                 *
+                 * @example
+                 * ```ts
+                 * after: ({ req }) => {
+                 *   if (!req.user.hasChangedPassword) {
+                 *     throw new AppError("Password change required.", 403, "PasswordChangeRequired");
+                 *   }
+                 * }
+                 * ```
+                 */
+                after?: AuthenticateAfterHookHandler | AuthenticateAfterHookHandler[];
+                /**
+                 * Runs when authentication throws — invalid token, expired token, user not found, etc.
+                 * Throw to forward to the global error handler, or call `skip()` to suppress and jump to `after` hooks.
+                 *
+                 * @example
+                 * ```ts
+                 * onError: ({ req, error, skip, action, resource, rule }) => {
+                 *   console.warn(`Auth failed:`, error);
+                 *   throw error;
+                 * }
+                 * ```
+                 *
+                 * @example Suppress error and continue
+                 * ```ts
+                 * onError: ({ req, skip, action, resource, rule }) => {
+                 *   req.user = guestUser;
+                 *   skip();
+                 * }
+                 * ```
+                 */
+                onError?: AuthenticateErrorHookHandler | AuthenticateErrorHookHandler[];
+            };
+            authorize?: {
+                /**
+                 * Runs before the role/permission check.
+                 *
+                 * @example
+                 * ```ts
+                 * before: ({ req }) => {
+                 *   if (req.headers["x-elevated-access"] === process.env.ELEVATION_KEY) {
+                 *     req.user.role = "admin";
+                 *   }
+                 * }
+                 * ```
+                 *
+                 * @example Skip permission check entirely
+                 * ```ts
+                 * before: ({ req, skip, action, resource, rule }) => {
+                 *   req.user.role = myCustomRoleResolver(req);
+                 *   skip();
+                 * }
+                 * ```
+                 */
+                before?: AuthorizeHookHandler | AuthorizeHookHandler[];
+                /**
+                 * Runs after the permission check passes.
+                 *
+                 * @example
+                 * ```ts
+                 * after: ({ req }) => {
+                 *   auditLog.record({ userId: req.user.id, path: req.path });
+                 * }
+                 * ```
+                 */
+                after?: AuthorizeAfterHookHandler | AuthorizeAfterHookHandler[];
+                /**
+                 * Runs when the user lacks sufficient permissions (403).
+                 * Throw to forward to the global error handler, or call `skip()` to suppress and jump to `after` hooks.
+                 *
+                 * @example
+                 * ```ts
+                 * onError: ({ req, error, action, resource, rule }) => {
+                 *   auditLog.record({ userId: req.user?.id, reason: "insufficient_permissions" });
+                 *   throw error;
+                 * }
+                 * ```
+                 *
+                 * @example Suppress error and continue
+                 * ```ts
+                 * onError: ({ req, skip, action, resource, rule }) => {
+                 *   req.user.role = "guest";
+                 *   skip();
+                 * }
+                 * ```
+                 */
+                onError?: AuthorizeErrorHookHandler | AuthorizeErrorHookHandler[];
+            };
+        };
         enabled?: boolean;
         /**
          * Defines whether to use Static or Dynamic Role-Based Acess Control
          *
-         * Visit [www.arkosjs.com/docs/core-concepts/authentication-system](https://www.arkosjs.com/docs/core-concepts/authentication-system) for more details.
+         * Visit [www.arkosjs.com/docs/core-concepts/authentication/setup](https://www.arkosjs.com/docs/core-concepts/authentication/setup) for more details.
          */
-        mode: "static" | "dynamic";
+        mode: 'static' | 'dynamic';
         /**
          * Defines auth login related configurations to customize the api.
          */
@@ -96,7 +257,7 @@ export type ArkosConfig = {
              * POST /api/auth/login?usernameField=email
              * ```
              *
-             * See more at [www.arkosjs.com/docs/core-concepts/authentication-system#login-with-different-fileds](https://www.arkosjs.com/docs/core-concepts/authentication-system#login-with-different-fileds)
+             * See more at [www.arkosjs.com/docs/core-concepts/authentication/setup#login-with-different-fileds](https://www.arkosjs.com/docs/core-concepts/authentication/setup#login-with-different-fileds)
              *
              * By specifing here another field for username, for example passing "email", "companyCode" or something else your json will be like:
              *
@@ -111,20 +272,7 @@ export type ArkosConfig = {
              */
             allowedUsernames?: string[];
             /** Defines wether to send the access token in response after login or only send as cookie, defeault is both.*/
-            sendAccessTokenThrough?: "cookie-only" | "response-only" | "both";
-        };
-        /**
-         * Specifies the regex pattern used by the authentication system to enforce password strength requirements.
-         *
-         * **Important**: If using validation libraries like Zod or class-validator, this will be completely overwritten.
-         *
-         * **Default**: ```/^(?=.*[A-Z])(?=.*[a-z])(?=.*\d).+$/``` - Ensures the password contains at least one uppercase letter, one lowercase letter, and one numeric digit.
-         *
-         * **message**: (Optional) A custom error message to display when the password does not meet the required strength criteria.
-         */
-        passwordValidation?: {
-            regex: RegExp;
-            message?: string;
+            sendAccessTokenThrough?: 'cookie-only' | 'response-only' | 'both';
         };
         /**
          * Allows to specify the request rate limit for all authentication endpoints but `/api/users/me`.
@@ -172,36 +320,55 @@ 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";
-            };
+                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:
      *
      *```ts
-     * // src/app.ts
-     * import arkos from 'arkos'
-     *
-     * arkos.init({
+     * const config = defineConfig({
      *    validation: {
      *        resolver: "zod"
      *    }
      * })
      * ```
      *
-     * @See [www.arkosjs.com/docs/core-concepts/request-data-validation](https://www.arkosjs.com/docs/core-concepts/request-data-validation) for more details.
+     * @See [www.arkosjs.com/docs/guides/validation/setup](https://www.arkosjs.com/docs/guides/validation/setup) for more details.
      */
     validation?: {
         /**
@@ -225,10 +392,12 @@ export type ArkosConfig = {
          * })
          *
          * ```
+         *
+         * @since 1.4.0-beta
          */
         strict?: boolean;
     } & ({
-        resolver: "class-validator";
+        resolver: 'class-validator';
         /**
          * ValidatorOptions to used while validating request data.
          *
@@ -242,7 +411,10 @@ export type ArkosConfig = {
          */
         validationOptions?: ValidatorOptions;
     } | {
-        resolver: "zod";
+        resolver: 'zod' | 'hybrid';
+        /**
+         * @since v1.5.0-beta
+         */
         validationOptions?: {
             /**
              * Throws an error for know whitelisted fields
@@ -255,9 +427,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)
          *
@@ -281,6 +459,17 @@ export type ArkosConfig = {
          *
          */
         baseRoute?: string;
+        /**
+         * Controls how uploaded files are served.
+         *
+         * - `"all"`: serves every directory under `baseUploadDir` (default, backwards compatible).
+         * - `"registered"`: serves only `images`, `videos`, `documents` and `files`.
+         *   Any other directory must be registered with `arkos.serveUploadDir()`.
+         *
+         * @default "all"
+         * @since 1.8.0-rc
+         */
+        serving?: "all" | "registered";
         /**
          * Defines options for `express.static(somePath, someOptions)`
          *
@@ -292,7 +481,7 @@ export type ArkosConfig = {
               etag: true,
               lastModified: true,
               dotfiles: "ignore",
-              fallthrough: true,
+              fallthrough: false,
               index: false,
               cacheControl: true,
             }
@@ -312,7 +501,7 @@ export type ArkosConfig = {
          * Passing an object without overriding everything will only cause it
          * to be deepmerged with the default options.
          *
-         * See [www.arkosjs.com/docs/api-reference/default-supported-upload-files](https://www.arkosjs.com/docs/api-reference/default-supported-upload-files) for detailed explanation about default values.
+         * See [www.arkosjs.com/docs/reference/default-supported-upload-files](https://www.arkosjs.com/docs/reference/default-supported-upload-files) for detailed explanation about default values.
          * ```
          */
         restrictions?: {
@@ -371,25 +560,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;
@@ -404,7 +603,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.
        *
@@ -467,7 +669,7 @@ export type ArkosConfig = {
          *
          * See documentation: https://www.arkosjs.com/docs/guide/security#strict-mode
          */
-        strict?: boolean | "no-bulk";
+        strict?: boolean | 'no-bulk';
         /**
          * Replace the default welcome endpoint handler
          * @param req Express request object
@@ -479,7 +681,7 @@ export type ArkosConfig = {
     /**
      * Allows to configure email configurations for sending emails through `emailService`
      *
-     * See [www.arkosjs.com/docs/core-concepts/sending-emails](https://www.arkosjs.com/docs/core-concepts/sending-emails)
+     * See [www.arkosjs.com/docs/guides/email-service](https://www.arkosjs.com/docs/guides/email-service)
      */
     email?: {
         /**
@@ -522,14 +724,9 @@ export type ArkosConfig = {
      * **Usage**
      *
      * ```ts
-     * // src/app.ts
-     *
-     * import arkos from "arkos"
-     *
-     *  arkos.init({
+     * const config = defineConfig({
      *    // other configs
      *    swagger: {
-     *      mode: "zod",
      *      options: {
      *        defintion: {
      *          info: {
@@ -542,13 +739,18 @@ export type ArkosConfig = {
      *  }
      * })
      * ```
-     * @see {@link https://www.arkosjs.com/docs/core-concepts/open-api-documentation}
+     * @see {@link https://www.arkosjs.com/docs/guides/open-api-documentation/setup}
      */
     swagger?: {
         /**
          * By default Arkos will disable API Documentation when the project is built `npm run build`, it does not matter what node environment is set. If you want to use it even after the `arkos build` command just set this to `true`.
          * */
         enableAfterBuild?: boolean;
+        /**
+         * Whether to require superUser authentication to access docs in production.
+         * Default: true after build
+         */
+        authenticate?: boolean;
         /**
          * Endpoint where the Swagger UI will be available.
          *
@@ -607,7 +809,7 @@ export type ArkosConfig = {
                  *
                  * @default [{ url: "http://localhost:8000", description: "Development server" }]
                  *
-                 * This can be overridden automatically by Arkos based on CLI, .env, or `arkos.init()`.
+                 * This can be overridden automatically by Arkos based on CLI, .env, or config.
                  */
                 servers?: {
                     /**
@@ -709,7 +911,7 @@ export type ArkosConfig = {
          */
         requests?: {
             level?: 0 | 1 | 2 | 3;
-            filter?: ("Query" | "Body" | "Params" | "TransformedQuery" | "ServiceArgs" | "PrismaFinalQueryArgs")[];
+            filter?: ('Query' | 'Body' | 'Params' | 'TransformedQuery' | 'ServiceArgs' | 'PrismaFinalQueryArgs')[];
         };
     };
     /**
@@ -732,4 +934,109 @@ export type ArkosConfig = {
          */
         instance: PrismaClient;
     };
+    /**
+     * Allows to suppress specific warnings emitted by Arkos at startup or runtime.
+     *
+     * @since 1.5.10-beta
+     */
+    warnings?: {
+        /**
+         * File upload related warning controls.
+         *
+         * @since 1.8.0-rc
+         */
+        fileUpload?: {
+            /**
+             * Suppresses the startup warning about URL parameters that are not used
+             * by the disk folder template.
+             */
+            suppressUnusedUrlParams?: boolean;
+        };
+        /**
+         * 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];
+    };
 };