import { APIGatewayProxyEventV2WithRequestContext, APIGatewayEventRequestContextV2, Context, APIGatewayProxyResultV2, APIGatewayProxyHandlerV2, APIGatewayProxyStructuredResultV2 } from 'aws-lambda';

/**
 * Utility functions and types for AWS API Gateway Lambda integration.
 * This module provides type-safe wrappers and helpers for handling
 * API Gateway events and responses in AWS Lambda functions.
 */

/**
 * Extends the standard Error interface to include an optional HTTP status code.
 * This allows for standardized error handling with appropriate HTTP responses.
 */
interface HttpError extends Error {
    statusCode?: number;
}
/**
 * A type that enhances the standard API Gateway event by replacing the body property
 * with a strongly-typed version rather than the default string representation.
 *
 * @template TRequestBody - The type of the request body after parsing
 * @template TRequestContext - The type of the request context
 */
interface APIGatewayProxyEventPikaWithRequestContext<TRequestBody, TRequestContext> extends Omit<APIGatewayProxyEventV2WithRequestContext<TRequestContext>, 'body'> {
    body: TRequestBody;
}
/**
 * A specialized API Gateway event type that includes:
 * 1. A strongly-typed request body
 * 2. The standard API Gateway request context
 * 3. Additional path and httpMethod properties for routing
 *
 * @template TRequestBody - The type of the parsed request body (defaults to never if not provided)
 */
type APIGatewayProxyEventPika<TRequestBody = never> = APIGatewayProxyEventPikaWithRequestContext<TRequestBody, APIGatewayEventRequestContextV2> & {
    path: string;
    httpMethod: string;
    resource: string;
};
/**
 * A generic handler type for AWS Lambda functions.
 *
 * @template TEvent - The event type (input) for the handler
 * @template TResult - The result type (output) returned by the handler
 * @returns Either void or a Promise containing the result
 */
type HandlerPika<TEvent = unknown, TResult = unknown> = (event: TEvent, context: Context) => void | Promise<TResult>;
/**
 * A specialized handler type for API Gateway Lambda integrations with typed request and response.
 *
 * @template B - The request body type (defaults to never if not provided)
 * @template T - The response type (defaults to never if not provided)
 */
type APIGatewayProxyHandlerPika<B = never, T = never> = HandlerPika<APIGatewayProxyEventPika<B>, APIGatewayProxyResultV2<T>>;
/**
 * A higher-order function that wraps a typed Lambda handler to provide:
 * 1. Automatic JSON parsing of the request body
 * 2. Error handling with appropriate status codes
 * 3. Consistent response formatting
 *
 * @template TRequestBody - The expected type of the request body after parsing
 * @template TResponse - The expected type of the response
 * @param fn - The Lambda handler function to wrap
 * @returns A standard API Gateway Lambda handler with error handling and type safety
 */
declare function apiGatewayFunctionDecorator<TRequestBody, TResponse>(fn: APIGatewayProxyHandlerPika<TRequestBody, TResponse>): APIGatewayProxyHandlerV2<TResponse>;
/**
 * Creates a standardized API Gateway response object.
 * Handles both string and non-string body types by automatically stringifying as needed.
 *
 * @template T - The type of the response body
 * @param body - The response body to send
 * @param statusCode - The HTTP status code (defaults to 200 OK)
 * @returns A properly formatted API Gateway response object
 */
declare function toResponse<T>(body: T, statusCode?: number): APIGatewayProxyStructuredResultV2;
/**
 * Type definition for Lambda Function URL events with additional IAM authorization details.
 * Extends the standard API Gateway event with specific requestContext properties for
 * Function URL integration patterns.
 *
 * @template T - The request body type
 */
type LambdaFunctionUrlProxyEventPika<T = never> = APIGatewayProxyEventPika<T> & {
    requestContext: {
        authorizer?: {
            iam: {
                cognitoIdentity?: string;
                cognitoIdentityId?: string;
                userId?: string;
                user?: string;
                callerId?: string;
                caller?: string;
                accessKey?: string;
                principalOrgId?: string;
                accountId?: string;
                userArn?: string;
                [key: string]: any;
            };
        };
        identity?: {
            cognitoIdentity?: string;
            cognitoIdentityId?: string;
            user?: string;
            userId?: string;
            caller?: string;
            callerId?: string;
            accessKey?: string;
            principalOrgId?: string;
            accountId?: string;
            userArn?: string;
            [key: string]: any;
        };
    };
};
/**
 * Converts a Lambda Function URL event into a standardized API Gateway event.
 * This function ensures that IAM authorization details are properly mapped
 * from the authorizer to the identity property for consistent access patterns.
 *
 * Also, parses the body string into the generic type T if it exists and is a string
 *
 * This exists because the Lambda Function URL event has a different structure
 * than the API Gateway event and we almost never use Lambdas that are Function URL based
 * and so it's easier to just convert the event to a standard API Gateway event than
 * to handle the different event types.
 *
 * @template T - The request body type
 * @param event - The Lambda Function URL event to convert
 * @returns A standardized API Gateway event
 */
declare function convertFunctionUrlEventToStandardApiGatewayEvent<T>(event: LambdaFunctionUrlProxyEventPika<T>): APIGatewayProxyEventPika<T>;

export { type APIGatewayProxyEventPika, type APIGatewayProxyHandlerPika, type HandlerPika, type HttpError, type LambdaFunctionUrlProxyEventPika, apiGatewayFunctionDecorator, convertFunctionUrlEventToStandardApiGatewayEvent, toResponse };