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

Shared utilities for AWS Amplify projects

import type { RestInputWithModels, RestEvent } from './types';
/**
 * Builds standardized log context for REST operations
 * @param input - REST input containing event and context
 * @param additionalContext - Additional context to merge
 * @returns Combined context object with REST operation details
 */
export declare function buildRestContext(input: RestInputWithModels, additionalContext?: Record<string, unknown>): Record<string, unknown>;
/**
 * Extracts basic event information for logging purposes
 * @param event - API Gateway REST event
 * @returns Object containing essential event information
 */
export declare function extractEventInfo(event: RestEvent): Record<string, unknown>;
/**
 * Safely parses JSON body with error handling and logging
 * @param body - Raw request body string
 * @param context - Logging context for error reporting
 * @returns Parsed JSON object or null if parsing fails
 */
export declare function parseJsonBody(body: string | undefined, context: Record<string, unknown>): unknown;
/**
 * Parses JSON body with fallback value for error cases
 * @param body - Raw request body string
 * @param fallback - Value to return if parsing fails
 * @returns Parsed JSON object or fallback value
 */
export declare function parseJsonBodyWithFallback<T = unknown>(body: string | undefined, fallback: T): unknown | T;
/**
 * Configures structured logging for REST middleware operations
 * @param input - REST input containing event and context
 * @param forceStructuredLogging - Whether to force structured logging mode
 * @param defaultContext - Default context to include in all logs
 */
export declare function setupStructuredLogging(input: RestInputWithModels, forceStructuredLogging?: boolean, defaultContext?: Record<string, unknown>): void;
/**
 * Safely extracts error message from unknown error types
 * @param error - Error of unknown type
 * @returns String representation of the error message
 */
export declare function getErrorMessage(error: unknown): string;
/**
 * Extracts stack trace from error if available
 * @param error - Error of unknown type
 * @returns Stack trace string or undefined if not available
 */
export declare function getErrorStack(error: unknown): string | undefined;
/**
 * Builds validation error context with REST event information
 * @param event - REST event that caused the validation error
 * @param errorCode - Error code identifier (defaults to 'VALIDATION_ERROR')
 * @param statusCode - HTTP status code (defaults to 400)
 * @param additionalContext - Additional context to include
 * @returns Context object with REST event details and error information
 */
export declare function buildValidationErrorContext(event: RestEvent, errorCode?: string, statusCode?: number, additionalContext?: Record<string, unknown>): Record<string, unknown>;
/**
 * Validates and extracts basic request information with error context
 * @param input - REST input containing event and context
 * @param operation - Operation name for logging context
 * @returns Object containing event, context, and request ID
 */
export declare function validateBasicRequestInfo(input: RestInputWithModels, operation: string): {
    event: RestEvent;
    context: Record<string, unknown>;
    requestId: string;
};
/**
 * Configuration interface for validation error creation
 */
export interface ValidationErrorConfig {
    /** Error message */
    message: string;
    /** REST event that caused the validation error */
    event: RestEvent;
    /** Error code identifier (defaults to 'VALIDATION_ERROR') */
    errorCode?: string;
    /** HTTP status code (defaults to 400) */
    statusCode?: number;
    /** Additional context to include */
    additionalContext?: Record<string, unknown>;
}
/**
 * Creates standardized validation errors with REST context
 * @param config - Validation error configuration
 * @returns Error object with code, statusCode, and context properties
 */
export declare function createValidationError(config: ValidationErrorConfig): Error & {
    code: string;
    statusCode: number;
};
/**
 * Configuration interface for error response creation
 */
export interface ErrorResponseConfig {
    /** HTTP status code */
    statusCode: number;
    /** Error code identifier */
    code: string;
    /** Error message */
    message: string;
    /** Request ID for tracking (optional) */
    requestId?: string;
    /** Additional data to include in response */
    additionalData?: Record<string, unknown>;
}
/**
 * Creates standardized error response in API Gateway format
 * @param config - Error response configuration
 * @returns API Gateway response object with error details
 */
export declare function createErrorResponse(config: ErrorResponseConfig): {
    statusCode: number;
    headers: Record<string, string>;
    body: string;
};
/**
 * Extracts request ID from multiple possible sources
 * @param event - REST event
 * @param context - Lambda context (optional)
 * @returns Request ID string or generated fallback
 */
export declare function getRequestId(event: RestEvent, context?: {
    awsRequestId?: string;
}): string;
/**
 * Creates standardized success response in API Gateway format
 * @param data - Response data
 * @param statusCode - HTTP status code (defaults to 200)
 * @param requestId - Request ID for tracking
 * @param meta - Additional metadata
 * @returns API Gateway response object with success data
 */
export declare function createSuccessResponse<T = unknown>(data: T, statusCode?: number, requestId?: string, meta?: Record<string, unknown>): {
    statusCode: number;
    headers: Record<string, string>;
    body: string;
};
/**
 * Common HTTP status codes for REST APIs
 */
export declare const HTTP_STATUS: {
    readonly OK: 200;
    readonly CREATED: 201;
    readonly NO_CONTENT: 204;
    readonly BAD_REQUEST: 400;
    readonly UNAUTHORIZED: 401;
    readonly FORBIDDEN: 403;
    readonly NOT_FOUND: 404;
    readonly METHOD_NOT_ALLOWED: 405;
    readonly CONFLICT: 409;
    readonly UNPROCESSABLE_ENTITY: 422;
    readonly INTERNAL_SERVER_ERROR: 500;
    readonly SERVICE_UNAVAILABLE: 503;
};
/**
 * Comprehensive error codes for REST API responses
 */
export declare const ERROR_CODES: {
    readonly BAD_REQUEST: "BAD_REQUEST";
    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
    readonly UNPROCESSABLE_ENTITY: "UNPROCESSABLE_ENTITY";
    readonly UNAUTHORIZED: "UNAUTHORIZED";
    readonly AUTHENTICATION_ERROR: "AUTHENTICATION_ERROR";
    readonly FORBIDDEN: "FORBIDDEN";
    readonly AUTHORIZATION_ERROR: "AUTHORIZATION_ERROR";
    readonly NOT_FOUND: "NOT_FOUND";
    readonly CONFLICT: "CONFLICT";
    readonly METHOD_NOT_ALLOWED: "METHOD_NOT_ALLOWED";
    readonly INTERNAL_SERVER_ERROR: "INTERNAL_SERVER_ERROR";
    readonly SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE";
};
/** Environment detection helper */
export declare const isDevelopment: boolean;
/**
 * Common middleware initialization helper that sets up logging and context
 * @param input - REST input with event and context
 * @param config - Configuration options for initialization
 * @returns Initialized input, context, and request ID
 */
export declare function initializeRestMiddleware<T extends RestInputWithModels>(input: T, config?: {
    defaultContext?: Record<string, unknown>;
    forceStructuredLogging?: boolean;
    operation?: string;
}): {
    input: RestInputWithModels;
    context: Record<string, unknown>;
    requestId: string;
};
//# sourceMappingURL=utils.d.ts.map