@energica-city/shared-amplify-utils/dist/middleware/rest/RestErrors.d.ts

Shared utilities for AWS Amplify projects

import { type ErrorContext } from '../../error';
import type { RestResponse } from './types';
/**
 * REST-specific error codes for standardized error classification
 *
 * Provides consistent error codes for common REST API error scenarios
 * that map to appropriate HTTP status codes.
 */
export declare const RestErrorCodes: {
    /** Request validation failed - malformed or invalid data */
    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
    /** Authentication required or invalid credentials */
    readonly AUTHENTICATION_ERROR: "AUTHENTICATION_ERROR";
    /** Access denied - valid credentials but insufficient permissions */
    readonly AUTHORIZATION_ERROR: "AUTHORIZATION_ERROR";
    /** Requested resource not found */
    readonly NOT_FOUND: "NOT_FOUND";
    /** Resource conflict - duplicate or constraint violation */
    readonly CONFLICT: "CONFLICT";
    /** Malformed request or invalid parameters */
    readonly BAD_REQUEST: "BAD_REQUEST";
    /** Internal server error - unexpected failure */
    readonly INTERNAL_SERVER_ERROR: "INTERNAL_SERVER_ERROR";
    /** Service temporarily unavailable */
    readonly SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE";
    /** Rate limit exceeded */
    readonly TOO_MANY_REQUESTS: "TOO_MANY_REQUESTS";
};
/**
 * Enhanced REST error interface with HTTP-specific properties
 *
 * Extends the base Error interface with REST API specific
 * information including status codes and structured context.
 */
export interface RestError extends Error {
    /** HTTP status code for the error response */
    statusCode: number;
    /** Structured error code for client handling */
    code: string;
    /** Additional context information for debugging */
    context?: RestErrorContext;
    /** Original error that caused this REST error */
    originalError?: unknown;
}
/**
 * REST error context with HTTP-specific information
 *
 * Provides structured context for REST errors including
 * request details and HTTP metadata.
 */
export interface RestErrorContext extends ErrorContext {
    /** HTTP method of the failed request */
    method?: string;
    /** Request path that failed */
    path?: string;
    /** HTTP status code */
    statusCode?: number;
    /** Unique request identifier for tracing */
    requestId?: string;
    /** Request headers relevant to the error */
    headers?: Record<string, string>;
}
/**
 * Creates a REST-specific error with proper status code and error code
 *
 * Central function for creating standardized REST errors with
 * appropriate HTTP status codes and structured context.
 *
 * @param statusCode - HTTP status code for the error
 * @param code - REST error code from RestErrorCodes
 * @param message - Human-readable error message
 * @param context - Additional context and original error information
 * @throws Always throws - this function never returns
 */
export declare function throwRestError(statusCode: number, code: keyof typeof RestErrorCodes, message: string, context?: RestErrorContext & {
    originalError?: unknown;
}): never;
/**
 * Convenience functions for common REST error scenarios
 *
 * Provides pre-configured error throwing functions for standard
 * HTTP error cases with appropriate status codes and error codes.
 */
export declare const RestErrors: {
    /**
     * Throws a validation error (400 Bad Request)
     *
     * Used when request data fails validation or is malformed.
     *
     * @param message - Description of the validation failure
     * @param context - Request context and validation details
     * @param originalError - Original validation error if available
     * @throws Always throws validation error
     */
    validation(message: string, context?: RestErrorContext, originalError?: unknown): never;
    /**
     * Throws an authentication error (401 Unauthorized)
     *
     * Used when authentication is required or credentials are invalid.
     *
     * @param message - Description of the authentication failure
     * @param context - Request context and authentication details
     * @param originalError - Original authentication error if available
     * @throws Always throws authentication error
     */
    authentication(message: string, context?: RestErrorContext, originalError?: unknown): never;
    /**
     * Throws an authorization error (403 Forbidden)
     *
     * Used when user is authenticated but lacks required permissions.
     *
     * @param message - Description of the authorization failure
     * @param context - Request context and permission details
     * @param originalError - Original authorization error if available
     * @throws Always throws authorization error
     */
    authorization(message: string, context?: RestErrorContext, originalError?: unknown): never;
    /**
     * Throws a not found error (404 Not Found)
     *
     * Used when requested resource does not exist.
     *
     * @param message - Description of what was not found
     * @param context - Request context and resource details
     * @param originalError - Original lookup error if available
     * @throws Always throws not found error
     */
    notFound(message: string, context?: RestErrorContext, originalError?: unknown): never;
    /**
     * Throws a conflict error (409 Conflict)
     *
     * Used when request conflicts with current resource state.
     *
     * @param message - Description of the conflict
     * @param context - Request context and conflict details
     * @param originalError - Original conflict error if available
     * @throws Always throws conflict error
     */
    conflict(message: string, context?: RestErrorContext, originalError?: unknown): never;
    /**
     * Throws a bad request error (400 Bad Request)
     *
     * Used when request is malformed or contains invalid parameters.
     *
     * @param message - Description of the bad request
     * @param context - Request context and parameter details
     * @param originalError - Original parsing error if available
     * @throws Always throws bad request error
     */
    badRequest(message: string, context?: RestErrorContext, originalError?: unknown): never;
    /**
     * Throws a rate limit error (429 Too Many Requests)
     *
     * Used when client has exceeded rate limiting thresholds.
     *
     * @param message - Description of the rate limit violation
     * @param context - Request context and rate limit details
     * @param originalError - Original rate limiting error if available
     * @throws Always throws rate limit error
     */
    tooManyRequests(message: string, context?: RestErrorContext, originalError?: unknown): never;
    /**
     * Throws a service unavailable error (503 Service Unavailable)
     *
     * Used when service is temporarily unavailable or under maintenance.
     *
     * @param message - Description of the service unavailability
     * @param context - Request context and service status details
     * @param originalError - Original service error if available
     * @throws Always throws service unavailable error
     */
    serviceUnavailable(message: string, context?: RestErrorContext, originalError?: unknown): never;
    /**
     * Throws an internal server error (500 Internal Server Error)
     *
     * Used when an unexpected error occurs on the server side.
     *
     * @param message - Description of the internal error
     * @param context - Request context and error details
     * @param originalError - Original internal error if available
     * @throws Always throws internal server error
     */
    internal(message: string, context?: RestErrorContext, originalError?: unknown): never;
};
/**
 * Checks if an error is a REST error with status code
 *
 * Type guard function to determine if an unknown error object
 * is a properly structured REST error with HTTP status code.
 *
 * @param error - Unknown error object to check
 * @returns True if error is a REST error with status code and code properties
 */
export declare function isRestError(error: unknown): error is RestError;
/**
 * Maps REST error codes to HTTP status codes and response formatting
 *
 * Provides centralized mapping between REST error codes and their
 * corresponding HTTP status codes for consistent error handling.
 */
export declare const RestErrorMapping: {
    readonly VALIDATION_ERROR: {
        readonly statusCode: 400;
        readonly title: "Validation Error";
        readonly description: "Request data failed validation";
    };
    readonly AUTHENTICATION_ERROR: {
        readonly statusCode: 401;
        readonly title: "Authentication Error";
        readonly description: "Authentication required or invalid credentials";
    };
    readonly AUTHORIZATION_ERROR: {
        readonly statusCode: 403;
        readonly title: "Authorization Error";
        readonly description: "Access denied - insufficient permissions";
    };
    readonly NOT_FOUND: {
        readonly statusCode: 404;
        readonly title: "Not Found";
        readonly description: "Requested resource not found";
    };
    readonly CONFLICT: {
        readonly statusCode: 409;
        readonly title: "Conflict";
        readonly description: "Resource conflict or constraint violation";
    };
    readonly BAD_REQUEST: {
        readonly statusCode: 400;
        readonly title: "Bad Request";
        readonly description: "Malformed request or invalid parameters";
    };
    readonly TOO_MANY_REQUESTS: {
        readonly statusCode: 429;
        readonly title: "Too Many Requests";
        readonly description: "Rate limit exceeded";
    };
    readonly INTERNAL_SERVER_ERROR: {
        readonly statusCode: 500;
        readonly title: "Internal Server Error";
        readonly description: "Unexpected server error occurred";
    };
    readonly SERVICE_UNAVAILABLE: {
        readonly statusCode: 503;
        readonly title: "Service Unavailable";
        readonly description: "Service temporarily unavailable";
    };
};
/**
 * Creates a standardized error response for REST errors
 *
 * Converts REST errors into properly formatted API Gateway responses
 * with consistent structure and appropriate HTTP status codes.
 *
 * @param error - REST error with code and context
 * @param requestId - Request ID for response tracking
 * @returns API Gateway response object with error details
 */
export declare function createRestErrorResponse(error: RestError, requestId: string): RestResponse;
/**
 * Checks if an error code is a known REST error code
 *
 * Determines if an error code is recognized and can be
 * handled gracefully by the error response system.
 *
 * @param code - Error code to check
 * @returns True if code is a known REST error code
 */
export declare function isKnownRestErrorCode(code: string): code is keyof typeof RestErrorCodes;
//# sourceMappingURL=RestErrors.d.ts.map