@fishka/express 0.9.5 → 0.9.7

package/dist/esm/api.types.d.ts

@@ -0,0 +1,83 @@
+import { ValueAssertion } from '@fishka/assertions';
+export type UrlTokensValidator = Record<string, ValueAssertion<string>>;
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(status: number, message: string, details?: Record<string, unknown> | undefined);
+}
+/**
+ * Asserts that a condition is true, throwing an HttpError with the specified status code if false.
+ * This function is designed for HTTP-specific validation where you want to throw appropriate HTTP status codes.
+ *
+ * @param condition - The condition to check. If false, an HttpError will be thrown.
+ * @param status - The HTTP status code to use in the HttpError (e.g., 400 for Bad Request, 404 for Not Found).
+ * @param message - The error message to include in the HttpError.
+ *
+ * @throws {HttpError} If the condition is false, throws an HttpError with the specified status and message.
+ *
+ * @example
+ * ```typescript
+ * // Validate required parameter
+ * assertHttp(typeof userId === 'string', HTTP_BAD_REQUEST, 'User ID must be a string');
+ *
+ * // Validate resource existence
+ * assertHttp(user !== null, HTTP_NOT_FOUND, 'User not found');
+ *
+ * // Validate authorization
+ * assertHttp(user.isAdmin, HTTP_FORBIDDEN, 'Admin access required');
+ *
+ * // Validate authentication
+ * assertHttp(req.headers.authorization, HTTP_UNAUTHORIZED, 'Authorization header required');
+ * ```
+ *
+ * @see {@link HttpError}
+ * @see {@link HTTP_BAD_REQUEST}
+ * @see {@link HTTP_NOT_FOUND}
+ * @see {@link HTTP_FORBIDDEN}
+ * @see {@link HTTP_UNAUTHORIZED}
+ */
+export declare function assertHttp(condition: boolean, status: number, message: string): void;
+export interface ApiResponse<ResponseEntity = unknown> {
+    /** Result of the call. A single entity for non-paginated ${by-id} requests or an array for list queries. */
+    result: ResponseEntity;
+    /**
+     * Unique ID of the request.
+     * Automatically added to every API response.
+     * May be passed via 'x-request-id' header from client.
+     */
+    requestId?: string;
+    /**
+     * Response status code. Same as HTTP response status.
+     * Default: 200 for successful responses or 500 for internal server errors.
+     */
+    status?: number;
+    /** Optional error message. */
+    error?: string;
+    /** Optional structured error details. */
+    details?: Record<string, unknown>;
+    /** Offset in the result set. Save as 'offset' query parameter. */
+    offset?: number;
+    /** Number of results requested. Same as 'limit' query parameter. */
+    limit?: number;
+}
+/** Converts an API response value into a standardized ApiResponse structure. */
+export declare function response<T = unknown>(result: T): ApiResponse<T>;
+/** Globally identified URL (path or query) parameter info. */
+export interface UrlParameterInfo {
+    /** Optional global validator for this parameter. */
+    validator?: ValueAssertion<string>;
+    /** Description for documentation. */
+    description?: string;
+}
+/**
+ * Default documentation and validation for URL parameters.
+ * @Internal
+ */
+export declare const URL_PARAMETER_INFO: Record<string, UrlParameterInfo>;
+/** Registers a new URL parameter. */
+export declare function registerUrlParameter(name: string, info: UrlParameterInfo): void;
+/**
+ * Asserts that the value is a registered URL parameter name.
+ * @Internal
+ */
+export declare function assertUrlParameter(name: unknown): asserts name is string;

package/dist/esm/api.types.js

@@ -1,13 +1,48 @@
 import { assertString, assertTruthy } from '@fishka/assertions';
+import { HTTP_BAD_REQUEST } from './http-status-codes';
 export class HttpError extends Error {
     constructor(status, message, details) {
         super(message);
         this.status = status;
         this.details = details;
-        // Restore prototype chain for instanceof checks
+        // Restore the prototype chain for instanceof checks.
         Object.setPrototypeOf(this, HttpError.prototype);
     }
 }
+/**
+ * Asserts that a condition is true, throwing an HttpError with the specified status code if false.
+ * This function is designed for HTTP-specific validation where you want to throw appropriate HTTP status codes.
+ *
+ * @param condition - The condition to check. If false, an HttpError will be thrown.
+ * @param status - The HTTP status code to use in the HttpError (e.g., 400 for Bad Request, 404 for Not Found).
+ * @param message - The error message to include in the HttpError.
+ *
+ * @throws {HttpError} If the condition is false, throws an HttpError with the specified status and message.
+ *
+ * @example
+ * ```typescript
+ * // Validate required parameter
+ * assertHttp(typeof userId === 'string', HTTP_BAD_REQUEST, 'User ID must be a string');
+ *
+ * // Validate resource existence
+ * assertHttp(user !== null, HTTP_NOT_FOUND, 'User not found');
+ *
+ * // Validate authorization
+ * assertHttp(user.isAdmin, HTTP_FORBIDDEN, 'Admin access required');
+ *
+ * // Validate authentication
+ * assertHttp(req.headers.authorization, HTTP_UNAUTHORIZED, 'Authorization header required');
+ * ```
+ *
+ * @see {@link HttpError}
+ * @see {@link HTTP_BAD_REQUEST}
+ * @see {@link HTTP_NOT_FOUND}
+ * @see {@link HTTP_FORBIDDEN}
+ * @see {@link HTTP_UNAUTHORIZED}
+ */
+export function assertHttp(condition, status, message) {
+    assertTruthy(condition, () => new HttpError(status, message));
+}
 /** Converts an API response value into a standardized ApiResponse structure. */
 export function response(result) {
     return { result };
@@ -27,5 +62,5 @@ export function registerUrlParameter(name, info) {
  */
 export function assertUrlParameter(name) {
     assertString(name, 'Url parameter name must be a string');
-    assertTruthy(URL_PARAMETER_INFO[name], `Invalid URL parameter: '${name}'. Please register it using 'registerUrlParameter('${name}', ...)'`);
+    assertHttp(URL_PARAMETER_INFO[name] !== undefined, HTTP_BAD_REQUEST, `Invalid URL parameter: '${name}'. Please register it using 'registerUrlParameter('${name}', ...)'`);
 }

package/dist/esm/auth/auth-strategy.d.ts

@@ -0,0 +1,42 @@
+import { ExpressRequest } from '../utils/express.utils';
+import { AuthStrategy, AuthUser } from './auth.types';
+/**
+ * Basic authentication strategy using username/password validation.
+ * Parses HTTP Basic Authorization header and validates credentials.
+ *
+ * Example usage:
+ * ```
+ * const strategy = new BasicAuthStrategy(
+ *   async (username, password) => {
+ *     const user = await db.users.findByUsername(username);
+ *     if (user && await bcrypt.compare(password, user.hash)) {
+ *       return user;
+ *     }
+ *     return null;
+ *   }
+ * );
+ * ```
+ */
+export declare class BasicAuthStrategy<User extends AuthUser = AuthUser> implements AuthStrategy<{
+    username: string;
+    password: string;
+}, User> {
+    private readonly verifyFn;
+    constructor(verifyFn: (username: string, password: string) => Promise<User | null>);
+    /**
+     * Extracts username and password from Basic auth header.
+     * Expected format: "Basic base64(username:password)"
+     * Returns undefined if header is missing or not Basic.
+     */
+    extractCredentials(req: ExpressRequest): {
+        username: string;
+        password: string;
+    } | undefined;
+    /**
+     * Validates the extracted credentials using the provided validation function.
+     */
+    validateCredentials({ username, password }: {
+        username: string;
+        password: string;
+    }): Promise<User>;
+}

package/dist/esm/auth/auth-strategy.js

@@ -1,5 +1,5 @@
 import { HttpError } from '../api.types';
-import { UNAUTHORIZED_STATUS } from '../http.types';
+import { HTTP_UNAUTHORIZED } from '../http-status-codes';
 /**
  * Basic authentication strategy using username/password validation.
  * Parses HTTP Basic Authorization header and validates credentials.
@@ -51,7 +51,7 @@ export class BasicAuthStrategy {
     async validateCredentials({ username, password }) {
         const user = await this.verifyFn(username, password);
         if (!user) {
-            throw new HttpError(UNAUTHORIZED_STATUS, 'Invalid username or password');
+            throw new HttpError(HTTP_UNAUTHORIZED, 'Invalid username or password');
         }
         return user;
     }

package/dist/esm/auth/auth.types.d.ts

@@ -0,0 +1,42 @@
+import { ExpressRequest } from '../utils/express.utils';
+/**
+ * Interface representing the authenticated user.
+ * Users of the library should use module augmentation to add fields to this interface.
+ *
+ * Example:
+ * ```ts
+ * declare module '@fishka/express' {
+ *   interface AuthUser {
+ *     id: string;
+ *     roles: string[];
+ *   }
+ * }
+ * ```
+ */
+export interface AuthUser {
+}
+/**
+ * Generic authentication strategy interface.
+ * Allows users to implement custom authentication logic.
+ *
+ * @template Credentials - The type of credentials extracted from the request
+ * @template User - The type of the authenticated user/entity
+ */
+export interface AuthStrategy<Credentials = unknown, User extends AuthUser = AuthUser> {
+    /**
+     * Extracts credentials from the Express request.
+     * This might parse Authorization headers, cookies, API keys, etc.
+     *
+     * @param req - Express request object
+     * @returns Extracted credentials, or undefined if not found/applicable
+     */
+    extractCredentials(req: ExpressRequest): Credentials | undefined;
+    /**
+     * Validates the extracted credentials and returns the authenticated user/entity.
+     *
+     * @param credentials - Credentials to validate
+     * @returns Authenticated user/entity
+     * @throws Error if credentials are invalid
+     */
+    validateCredentials(credentials: Credentials): Promise<User>;
+}

package/dist/esm/auth/auth.utils.d.ts

@@ -0,0 +1,31 @@
+import { EndpointMiddleware, RequestContext } from '../router';
+import { AuthStrategy, AuthUser } from './auth.types';
+/**
+ * Creates a middleware that enforces authentication using the provided strategy.
+ * The authenticated user is stored in the context under the 'authUser' key.
+ *
+ * @template User - Type of the authenticated user
+ * @param strategy - Authentication strategy to use
+ * @param onSuccess - Optional callback to process authenticated user
+ * @returns a middleware that enforces authentication
+ */
+export declare function createAuthMiddleware<User extends AuthUser = AuthUser>(strategy: AuthStrategy<unknown, User>, onSuccess?: (user: User, context: RequestContext) => void): EndpointMiddleware;
+/**
+ * Extracts the authenticated user from the request context.
+ * Throws if the user is not present (i.e., authentication was not performed).
+ *
+ * @template User - Type of the authenticated user
+ * @param context - Request context
+ * @returns The authenticated user
+ * @throws Error if user is not found in context
+ */
+export declare function getAuthUser<User extends AuthUser = AuthUser>(context: RequestContext): User;
+/**
+ * Safely extracts the authenticated user from the request context.
+ * Returns undefined if the user is not present.
+ *
+ * @template User - Type of the authenticated user
+ * @param context - Request context
+ * @returns The authenticated user, or undefined if not found
+ */
+export declare function tryGetAuthUser<User extends AuthUser = AuthUser>(context: RequestContext): User | undefined;

package/dist/esm/auth/auth.utils.js

@@ -1,5 +1,5 @@
 import { HttpError } from '../api.types';
-import { UNAUTHORIZED_STATUS } from '../http.types';
+import { HTTP_UNAUTHORIZED } from '../http-status-codes';
 /**
  * Creates a middleware that enforces authentication using the provided strategy.
  * The authenticated user is stored in the context under the 'authUser' key.
@@ -16,7 +16,7 @@ export function createAuthMiddleware(strategy, onSuccess) {
         // If no credentials found (and strategy returned undefined), we must deny access here.
         // In a composite strategy scenario, we might want to try the next strategy, but this helper is for a single strategy enforcement.
         if (!credentials) {
-            throw new HttpError(UNAUTHORIZED_STATUS, 'No credentials provided or invalid format');
+            throw new HttpError(HTTP_UNAUTHORIZED, 'No credentials provided or invalid format');
         }
         // Validate credentials and get authenticated user
         const user = await strategy.validateCredentials(credentials);
@@ -42,7 +42,7 @@ export function createAuthMiddleware(strategy, onSuccess) {
 export function getAuthUser(context) {
     const user = context.authUser;
     if (!user) {
-        throw new HttpError(UNAUTHORIZED_STATUS, 'User not found in context. Did you add auth middleware?');
+        throw new HttpError(HTTP_UNAUTHORIZED, 'User not found in context. Did you add auth middleware?');
     }
     return user;
 }

package/dist/esm/auth/bearer-auth-strategy.d.ts

@@ -0,0 +1,38 @@
+import { ExpressRequest } from '../utils/express.utils';
+import { AuthStrategy, AuthUser } from './auth.types';
+/**
+ * Bearer authentication strategy (commonly used for JWTs).
+ * Extracts the token from the 'Authorization: Bearer <token>' header.
+ *
+ * The validation logic is delegated to the `verifyFn`, which can:
+ * - Validate a JWT signature locally.
+ * - Call an external API/website to verify the token (Introspection/UserInfo).
+ *
+ * Example usage:
+ * ```ts
+ * const strategy = new BearerAuthStrategy(async (token) => {
+ *   // Call external website to validate
+ *   const response = await fetch('https://auth.example.com/verify', {
+ *     headers: { Authorization: `Bearer ${token}` }
+ *   });
+ *   if (!response.ok) return null;
+ *   return await response.json();
+ * });
+ * ```
+ */
+export declare class BearerAuthStrategy<User extends AuthUser = AuthUser> implements AuthStrategy<string, User> {
+    private readonly verifyFn;
+    /**
+     * @param verifyFn Function to validate the token. Returns the user if valid, or null if invalid.
+     */
+    constructor(verifyFn: (token: string) => Promise<User | null>);
+    /**
+     * Extracts the Bearer token from the Authorization header.
+     * Returns undefined if the header is missing or not a Bearer token.
+     */
+    extractCredentials(req: ExpressRequest): string | undefined;
+    /**
+     * Validates the extracted token using the provided verification function.
+     */
+    validateCredentials(token: string): Promise<User>;
+}

package/dist/esm/auth/bearer-auth-strategy.js

@@ -1,5 +1,5 @@
 import { HttpError } from '../api.types';
-import { UNAUTHORIZED_STATUS } from '../http.types';
+import { HTTP_UNAUTHORIZED } from '../http-status-codes';
 /**
  * Bearer authentication strategy (commonly used for JWTs).
  * Extracts the token from the 'Authorization: Bearer <token>' header.
@@ -48,7 +48,7 @@ export class BearerAuthStrategy {
     async validateCredentials(token) {
         const user = await this.verifyFn(token);
         if (!user) {
-            throw new HttpError(UNAUTHORIZED_STATUS, 'Invalid token');
+            throw new HttpError(HTTP_UNAUTHORIZED, 'Invalid token');
         }
         return user;
     }

package/dist/esm/config.d.ts

@@ -0,0 +1,23 @@
+export interface GlobalExpressApiConfig {
+    /**
+     * Whether to trust and use the request ID from the request header.
+     * If true, the middleware will look for 'x-request-id' and use it.
+     * If false, a new UUID will always be generated.
+     * Default: true
+     */
+    trustRequestIdHeader: boolean;
+}
+/**
+ * Configure global @fishka/express settings.
+ * @param config Partial configuration to merge with current settings
+ */
+export declare function configureExpressApi(config: Partial<GlobalExpressApiConfig>): void;
+/**
+ * Get current Express API configuration.
+ */
+export declare function getExpressApiConfig(): GlobalExpressApiConfig;
+/**
+ * Reset API configuration to defaults.
+ * Useful for testing.
+ */
+export declare function resetExpressApiConfig(): void;

package/dist/esm/error-handling.d.ts

@@ -0,0 +1,9 @@
+import { NextFunction } from 'express';
+import { ExpressFunction, ExpressRequest, ExpressResponse } from './utils/express.utils';
+/** Catches all kinds of unprocessed exceptions thrown from a single route. */
+export declare function catchRouteErrors(fn: ExpressFunction): ExpressFunction;
+/**
+ * Catches all errors in Express.js and is installed as global middleware.
+ * Note that individual routes are wrapped with 'catchRouteErrors' middleware.
+ */
+export declare function catchAllMiddleware(error: unknown, _: ExpressRequest, res: ExpressResponse, next: NextFunction): Promise<void>;

package/dist/esm/error-handling.js

@@ -1,6 +1,6 @@
 import { getMessageFromError } from '@fishka/assertions';
 import { HttpError } from './api.types';
-import { BAD_REQUEST_STATUS, INTERNAL_ERROR_STATUS } from './http.types';
+import { HTTP_BAD_REQUEST, HTTP_INTERNAL_SERVER_ERROR } from './http-status-codes';
 import { getRequestLocalStorage } from './thread-local/thread-local-storage';
 import { wrapAsApiResponse } from './utils/conversion.utils';
 function buildApiResponse(error) {
@@ -20,7 +20,7 @@ function buildApiResponse(error) {
         response = {
             ...wrapAsApiResponse(undefined),
             error: errorMessage && errorMessage.length > 0 ? errorMessage : 'Internal error',
-            status: INTERNAL_ERROR_STATUS,
+            status: HTTP_INTERNAL_SERVER_ERROR,
         };
     }
     if (requestId) {
@@ -36,7 +36,7 @@ export function catchRouteErrors(fn) {
         }
         catch (error) {
             const apiResponse = buildApiResponse(error);
-            if (apiResponse.status >= INTERNAL_ERROR_STATUS) {
+            if (apiResponse.status >= HTTP_INTERNAL_SERVER_ERROR) {
                 console.error(`catchRouteErrors: ${req.path}`, error);
             }
             else {
@@ -59,7 +59,7 @@ export async function catchAllMiddleware(error, _, res, next) {
     // Report as critical. This kind of error should never happen.
     console.error('catchAllMiddleware:', getMessageFromError(error));
     const apiResponse = error instanceof SyntaxError // JSON body parsing error.
-        ? buildApiResponse(`${BAD_REQUEST_STATUS}: Failed to parse request: ${error.message}`)
+        ? buildApiResponse(`${HTTP_BAD_REQUEST}: Failed to parse request: ${error.message}`)
         : buildApiResponse(error);
     res.status(apiResponse.status);
     res.send(apiResponse);

package/dist/esm/http-status-codes.d.ts

@@ -0,0 +1,179 @@
+/** The request has succeeded (200) */
+export declare const HTTP_OK = 200;
+/** The request has been fulfilled, and a new resource is created (201) */
+export declare const HTTP_CREATED = 201;
+/** The request has been accepted for processing, but the processing is not yet complete (202) */
+export declare const HTTP_ACCEPTED = 202;
+/** The server successfully processed the request, and is not returning any content (204) */
+export declare const HTTP_NO_CONTENT = 204;
+/** The request has been successfully processed, but is returning no content (205) */
+export declare const HTTP_RESET_CONTENT = 205;
+/** The server is delivering only part of the resource due to a range header sent by the client (206) */
+export declare const HTTP_PARTIAL_CONTENT = 206;
+/** The IM used the server processed a request successfully, but the response is transformed (226) */
+export declare const HTTP_IM_USED = 226;
+/** The resource has been moved permanently to a new URL (301) */
+export declare const HTTP_MOVED_PERMANENTLY = 301;
+/** The resource is available at a different URL (302) */
+export declare const HTTP_FOUND = 302;
+/** The resource has not been modified since the last request (304) */
+export declare const HTTP_NOT_MODIFIED = 304;
+/** The server could not understand the request due to invalid syntax (400) */
+export declare const HTTP_BAD_REQUEST = 400;
+/** The client must authenticate itself to get the requested response (401) */
+export declare const HTTP_UNAUTHORIZED = 401;
+/** The client does not have access rights to the content (403) */
+export declare const HTTP_FORBIDDEN = 403;
+/** The server cannot find the requested resource (404) */
+export declare const HTTP_NOT_FOUND = 404;
+/** The request method is known by the server but is not supported by the target resource (405) */
+export declare const HTTP_METHOD_NOT_ALLOWED = 405;
+/** The client must authenticate using a proxy (407) */
+export declare const HTTP_PROXY_AUTHENTICATION_REQUIRED = 407;
+/** The server timed out waiting for the request (408) */
+export declare const HTTP_REQUEST_TIMEOUT = 408;
+/** The request conflicts with the current state of the server (409) */
+export declare const HTTP_CONFLICT = 409;
+/** The resource requested is no longer available and will not be available again (410) */
+export declare const HTTP_GONE = 410;
+/** The request does not meet the preconditions that the server requires (412) */
+export declare const HTTP_PRECONDITION_FAILED = 412;
+/** The client sent a request that is too large for the server to process (413) */
+export declare const HTTP_PAYLOAD_TOO_LARGE = 413;
+/** The URI requested by the client is too long for the server to process (414) */
+export declare const HTTP_URI_TOO_LONG = 414;
+/** The media format of the requested data is not supported by the server (415) */
+export declare const HTTP_UNSUPPORTED_MEDIA_TYPE = 415;
+/** The range specified by the client cannot be fulfilled (416) */
+export declare const HTTP_RANGE_NOT_SATISFIABLE = 416;
+/** The expectation given in the request header could not be met by the server (417) */
+export declare const HTTP_EXPECTATION_FAILED = 417;
+/** The server refuses to brew coffee because it is a teapot (418) - an Easter egg from RFC 2324 */
+export declare const HTTP_IM_A_TEAPOT = 418;
+/** The request was well-formed but was unable to be followed due to semantic errors (422) */
+export declare const HTTP_UNPROCESSABLE_ENTITY = 422;
+/** The resource that is being accessed is locked (423) */
+export declare const HTTP_LOCKED = 423;
+/** The resource requested is dependent on another resource that has failed (424) */
+export declare const HTTP_FAILED_DEPENDENCY = 424;
+/** The server is unwilling to risk processing a request that might be replayed (425) */
+export declare const HTTP_TOO_EARLY = 425;
+/** The client needs to upgrade its protocol (426) */
+export declare const HTTP_UPGRADE_REQUIRED = 426;
+/** The server requires the request to be conditional (428) */
+export declare const HTTP_PRECONDITION_REQUIRED = 428;
+/** The client has sent too many requests in a given amount of time (429) */
+export declare const HTTP_TOO_MANY_REQUESTS = 429;
+/** The request header fields are too large (431) */
+export declare const HTTP_REQUEST_HEADER_FIELDS_TOO_LARGE = 431;
+/** The client closed the connection with the server before the request was completed (444) */
+export declare const HTTP_CONNECTION_CLOSED_WITHOUT_RESPONSE = 444;
+/** The client requested an unavailable legal action (451) */
+export declare const HTTP_UNAVAILABLE_FOR_LEGAL_REASONS = 451;
+/** The server encountered an internal error and was unable to complete the request (500) */
+export declare const HTTP_INTERNAL_SERVER_ERROR = 500;
+/** The request method is not supported by the server and cannot be handled (501) */
+export declare const HTTP_NOT_IMPLEMENTED = 501;
+/** The server, while acting as a gateway or proxy, received an invalid response from the upstream server (502) */
+export declare const HTTP_BAD_GATEWAY = 502;
+/** The server is not ready to handle the request, typically due to temporary overload or maintenance (503) */
+export declare const HTTP_SERVICE_UNAVAILABLE = 503;
+/** The server, while acting as a gateway or proxy, did not get a response in time from the upstream server (504) */
+export declare const HTTP_GATEWAY_TIMEOUT = 504;
+/**
+ * An object containing common HTTP status codes.
+ * These constants can be used to improve code readability and maintainability.
+ * @deprecated Use individual HTTP_* constants for better tree-shaking
+ */
+export declare const HttpStatusCode: {
+    /** The request has succeeded (200) */
+    OK: number;
+    /** The request has been fulfilled, and a new resource is created (201) */
+    CREATED: number;
+    /** The request has been accepted for processing, but the processing is not yet complete (202) */
+    ACCEPTED: number;
+    /** The server successfully processed the request, and is not returning any content (204) */
+    NO_CONTENT: number;
+    /** The request has been successfully processed, but is returning no content (205) */
+    RESET_CONTENT: number;
+    /** The server is delivering only part of the resource due to a range header sent by the client (206) */
+    PARTIAL_CONTENT: number;
+    /** The IM used the server processed a request successfully, but the response is transformed (226) */
+    IM_USED: number;
+    /** The resource has been moved permanently to a new URL (301) */
+    MOVED_PERMANENTLY: number;
+    /** The resource is available at a different URL (302) */
+    FOUND: number;
+    /** The resource has not been modified since the last request (304) */
+    NOT_MODIFIED: number;
+    /** The server could not understand the request due to invalid syntax (400) */
+    BAD_REQUEST: number;
+    /** The client must authenticate itself to get the requested response (401) */
+    UNAUTHORIZED: number;
+    /** The client does not have access rights to the content (403) */
+    FORBIDDEN: number;
+    /** The server cannot find the requested resource (404) */
+    NOT_FOUND: number;
+    /** The request method is known by the server but is not supported by the target resource (405) */
+    METHOD_NOT_ALLOWED: number;
+    /** The client must authenticate using a proxy (407) */
+    PROXY_AUTHENTICATION_REQUIRED: number;
+    /** The server timed out waiting for the request (408) */
+    REQUEST_TIMEOUT: number;
+    /** The request conflicts with the current state of the server (409) */
+    CONFLICT: number;
+    /** The resource requested is no longer available and will not be available again (410) */
+    GONE: number;
+    /** The request does not meet the preconditions that the server requires (412) */
+    PRECONDITION_FAILED: number;
+    /** The client sent a request that is too large for the server to process (413) */
+    PAYLOAD_TOO_LARGE: number;
+    /** The URI requested by the client is too long for the server to process (414) */
+    URI_TOO_LONG: number;
+    /** The media format of the requested data is not supported by the server (415) */
+    UNSUPPORTED_MEDIA_TYPE: number;
+    /** The range specified by the client cannot be fulfilled (416) */
+    RANGE_NOT_SATISFIABLE: number;
+    /** The expectation given in the request header could not be met by the server (417) */
+    EXPECTATION_FAILED: number;
+    /** The server refuses to brew coffee because it is a teapot (418) - an Easter egg from RFC 2324 */
+    IM_A_TEAPOT: number;
+    /** The request was well-formed but was unable to be followed due to semantic errors (422) */
+    UNPROCESSABLE_ENTITY: number;
+    /** The resource that is being accessed is locked (423) */
+    LOCKED: number;
+    /** The resource requested is dependent on another resource that has failed (424) */
+    FAILED_DEPENDENCY: number;
+    /** The server is unwilling to risk processing a request that might be replayed (425) */
+    TOO_EARLY: number;
+    /** The client needs to upgrade its protocol (426) */
+    UPGRADE_REQUIRED: number;
+    /** The server requires the request to be conditional (428) */
+    PRECONDITION_REQUIRED: number;
+    /** The client has sent too many requests in a given amount of time (429) */
+    TOO_MANY_REQUESTS: number;
+    /** The request header fields are too large (431) */
+    REQUEST_HEADER_FIELDS_TOO_LARGE: number;
+    /** The client closed the connection with the server before the request was completed (444) */
+    CONNECTION_CLOSED_WITHOUT_RESPONSE: number;
+    /** The client requested an unavailable legal action (451) */
+    UNAVAILABLE_FOR_LEGAL_REASONS: number;
+    /** The server encountered an internal error and was unable to complete the request (500) */
+    INTERNAL_SERVER_ERROR: number;
+    /** The request method is not supported by the server and cannot be handled (501) */
+    NOT_IMPLEMENTED: number;
+    /** The server, while acting as a gateway or proxy, received an invalid response from the upstream server (502) */
+    BAD_GATEWAY: number;
+    /** The server is not ready to handle the request, typically due to temporary overload or maintenance (503) */
+    SERVICE_UNAVAILABLE: number;
+    /** The server, while acting as a gateway or proxy, did not get a response in time from the upstream server (504) */
+    GATEWAY_TIMEOUT: number;
+};
+/**
+ * Returns the reason phrase corresponding to the given HTTP status code.
+ * This is useful for converting status codes into human-readable messages.
+ *
+ * @param statusCode - The HTTP status code for which to get the reason phrase.
+ * @returns The reason phrase associated with the given status code, or "Unknown Status Code" if the status code is not recognized.
+ */
+export declare const getHttpStatusCodeReasonPhrase: (statusCode: number) => string;