import type { APIGatewayProxyEvent, APIGatewayProxyResult, Context } from 'aws-lambda';
import type { RuntimeAwakeResponse, RuntimeAwakeContext } from '../../../lib/runtime-web/runtime-awake';
import type { ProxyLambdaConfig, ProxyLambdaEnvironment, TimeoutConfig, DevIdResolutionResult } from './proxy-lambda.types';
/**
 * Generate a unique request ID using UUID v4.
 *
 * @returns Unique request ID string
 *
 * @see Requirements 1.2
 */
export declare function generateRequestId(): string;
/**
 * Compute the response timeout based on Lambda's remaining time.
 *
 * The response timeout is calculated as (Lambda timeout - buffer) to ensure
 * the Proxy Lambda can return a proper timeout response before Lambda kills it.
 *
 * @param context - Lambda context with getRemainingTimeInMillis()
 * @param bufferSeconds - Buffer time in seconds (default: 5)
 * @returns Timeout configuration
 *
 * @see Requirements 1.5, 16.1
 */
export declare function computeResponseTimeout(context: Context, bufferSeconds?: number): TimeoutConfig;
/**
 * Build the MQTT topic for request messages.
 *
 * @param devId - Developer ID
 * @param requestId - Request ID
 * @returns MQTT topic string
 *
 * @see Requirements 1.2, 3.2
 */
export declare function buildRequestTopic(devId: string, requestId: string): string;
/**
 * Build the MQTT topic for response messages.
 *
 * @param devId - Developer ID
 * @param requestId - Request ID
 * @returns MQTT topic string
 */
export declare function buildResponseTopic(devId: string, requestId: string): string;
/**
 * Validate that a topic matches the expected format.
 *
 * Topics must match: runtime/dev/<devId>/request/<requestId> or
 * runtime/dev/<devId>/response/<requestId>
 *
 * @param topic - Topic to validate
 * @returns True if topic is valid
 *
 * @see Requirements 1.2
 */
export declare function isValidTopic(topic: string): boolean;
/**
 * Build RuntimeAwakeContext from Lambda context.
 *
 * @param context - AWS Lambda context
 * @returns RuntimeAwakeContext for local handler
 *
 * @see Requirements 8.3, 8.4
 */
export declare function buildRuntimeAwakeContext(context: Context): RuntimeAwakeContext;
/**
 * Create an error response with proper structure.
 *
 * @param statusCode - HTTP status code
 * @param errorType - Error type for X-Error-Type header
 * @param message - Error message
 * @param requestId - Request ID for correlation
 * @returns API Gateway proxy result
 */
export declare function createErrorResponse(statusCode: number, errorType: string, message: string, requestId: string): APIGatewayProxyResult;
/**
 * Create a timeout response.
 *
 * Returns a 504 Gateway Timeout response with detailed debugging information
 * including the request ID, function name, elapsed time, and timeout configuration.
 *
 * @param requestId - Request ID for correlation
 * @param functionName - Lambda function name
 * @param elapsedMs - Elapsed time in milliseconds
 * @param timeoutMs - Optional configured timeout in milliseconds
 * @returns API Gateway proxy result
 *
 * @see Requirements 1.3, 5.3, 5.4
 */
export declare function createTimeoutResponse(requestId: string, functionName: string, elapsedMs: number, timeoutMs?: number): APIGatewayProxyResult;
/**
 * Create a no-session response.
 *
 * @param requestId - Request ID for correlation
 * @returns API Gateway proxy result
 *
 * @see Requirements 1.4
 */
export declare function createNoSessionResponse(requestId: string): APIGatewayProxyResult;
/**
 * Error response body structure for handler errors.
 *
 * @see Requirements 6.1, 6.4, 6.5
 */
export interface HandlerErrorBody {
    error: {
        type: string;
        message: string;
        requestId: string;
        timestamp: string;
        stackTrace: string[];
    };
}
/**
 * Create an error response from a RuntimeAwakeErrorResponse.
 *
 * This function extracts errorType, errorMessage, and stackTrace from the error response,
 * maps the error type to an appropriate HTTP status code, and distinguishes between
 * handler errors (thrown by user code) and infrastructure errors (internal proxy errors).
 *
 * @param errorType - The error type from the error response
 * @param errorMessage - The error message
 * @param stackTrace - The stack trace as an array of strings
 * @param requestId - Request ID for correlation
 * @returns API Gateway proxy result with proper error structure
 *
 * @see Requirements 6.1, 6.2, 6.3, 6.4, 6.5
 *
 * @example
 * ```typescript
 * const response = createHandlerErrorResponse(
 *   'ValidationError',
 *   'Invalid input: email is required',
 *   ['at validateInput (/app/src/validators.ts:42:15)', ...],
 *   'abc-123'
 * );
 * // Returns 400 with X-Error-Type: handler-error
 * ```
 */
export declare function createHandlerErrorResponse(errorType: string, errorMessage: string, stackTrace: string[], requestId: string): APIGatewayProxyResult;
/**
 * Parse configuration from environment variables.
 *
 * @param env - Environment variables
 * @returns Proxy Lambda configuration
 */
export declare function parseConfigFromEnvironment(env: Partial<ProxyLambdaEnvironment>): ProxyLambdaConfig;
/**
 * Header name for Dev_ID in requests.
 */
export declare const DEV_ID_HEADER = "x-runtime-awake-id";
/**
 * Resolve Dev_ID from request using priority order.
 *
 * Resolution priority:
 * 1. X-Runtime-Awake-Id header (case-insensitive)
 * 2. API Gateway authorizer context (devId field)
 * 3. LIVE_DEV_DEV_ID environment variable
 *
 * @param event - API Gateway proxy event
 * @param defaultDevId - Default Dev_ID from environment (optional)
 * @returns Resolution result with devId and source, or null if no valid Dev_ID found
 *
 * @see Requirements 9.1, 9.2, 9.3, 9.4, 9.5
 *
 * @example
 * ```typescript
 * const result = resolveDevId(event, process.env.LIVE_DEV_DEV_ID);
 * if (result) {
 *   console.log(`Dev_ID: ${result.devId} from ${result.source}`);
 * } else {
 *   console.error('No valid Dev_ID found');
 * }
 * ```
 */
export declare function resolveDevId(event: APIGatewayProxyEvent, defaultDevId?: string): DevIdResolutionResult | null;
/**
 * Create an error response for invalid Dev_ID.
 *
 * @param requestId - Request ID for correlation
 * @returns API Gateway proxy result with 400 status
 *
 * @see Requirements 9.5
 */
export declare function createInvalidDevIdResponse(requestId: string): APIGatewayProxyResult;
/**
 * Proxy Lambda Handler for Awake Lambda Development.
 *
 * Intercepts incoming Lambda invocations and routes them to local development
 * environments via AWS IoT Core MQTT. Handles:
 * - Session checking via Session Registry
 * - MQTT publish/subscribe for request/response
 * - Large payload S3 indirection
 * - Fallback behavior when no session exists
 * - Timeout handling
 *
 * @see Requirements 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7
 *
 * @example
 * ```typescript
 * const proxyLambda = new ProxyLambda(config);
 *
 * export const handler = async (event: APIGatewayProxyEvent, context: Context) => {
 *   return proxyLambda.handle(event, context);
 * };
 * ```
 */
export declare class ProxyLambda {
    private readonly config;
    private readonly sessionRegistry;
    private readonly s3Client;
    private readonly iotClient;
    private readonly maxPayloadSize;
    /** Pending response promises keyed by requestId */
    private readonly pendingResponses;
    /**
     * Create a new ProxyLambda instance.
     *
     * @param config - Proxy Lambda configuration
     */
    constructor(config: ProxyLambdaConfig);
    /**
     * Handle an incoming Lambda invocation.
     *
     * Main entry point for the Proxy Lambda. Checks for active session,
     * routes request to local CLI via MQTT, and returns the response.
     *
     * @param event - API Gateway proxy event
     * @param context - Lambda context
     * @returns API Gateway proxy result
     *
     * @see Requirements 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 9.1, 9.2, 9.3, 9.5
     */
    handle(event: APIGatewayProxyEvent, context: Context): Promise<APIGatewayProxyResult>;
    /**
     * Check for an active developer session.
     *
     * Session lookup follows this priority:
     * 1. Query exact function name match first
     * 2. Fall back to wildcard ('*') session
     * 3. Validate TTL expiration (handled by SessionRegistry)
     *
     * @param requestId - Request ID for logging
     * @param devId - Developer ID to check session for
     * @returns Active session or null
     *
     * @see Requirements 1.1, 4.1, 4.2, 4.3, 6.3, 9.1, 9.2, 9.3
     */
    private checkSession;
    /**
     * Handle the case when no active session exists.
     *
     * Either executes the original handler (fallback mode 'execute')
     * or returns a 503 error (fallback mode 'error').
     *
     * @param event - Original event
     * @param context - Lambda context
     * @param requestId - Request ID
     * @returns API Gateway proxy result
     *
     * @see Requirements 1.3, 1.4, 4.4, 4.5
     */
    private handleNoSession;
    /**
     * Execute the original handler as fallback.
     *
     * Invokes the original Lambda handler when no session exists and
     * fallback mode is 'execute'. Returns the handler result to API Gateway.
     *
     * @param event - Original event
     * @param context - Lambda context
     * @param requestId - Request ID
     * @returns API Gateway proxy result
     *
     * @see Requirements 1.3, 4.4
     */
    private executeFallback;
    /**
     * Route request to local CLI via MQTT.
     *
     * @param event - Original event
     * @param context - Lambda context
     * @param session - Active session
     * @param requestId - Request ID
     * @param startTime - Request start timestamp
     * @returns API Gateway proxy result
     *
     * @see Requirements 1.2, 2.1, 2.2
     */
    private routeToLocal;
    /**
     * Prepare the RuntimeAwakeRequest message.
     *
     * Handles large payload S3 indirection if needed.
     *
     * @param event - Original event
     * @param context - Lambda context
     * @param session - Active session
     * @param requestId - Request ID
     * @param timeoutConfig - Timeout configuration
     * @returns RuntimeAwakeRequest message
     *
     * @see Requirements 2.2, 15.1, 15.2
     */
    private prepareRequest;
    /**
     * Upload a large payload to S3 and return a reference.
     *
     * @param devId - Developer ID
     * @param requestId - Request ID
     * @param payloadType - Type of payload (request-event, response-body)
     * @param payload - Payload string
     * @returns S3 payload reference
     * @throws S3UploadError if upload fails
     *
     * @see Requirements 3.1, 3.2, 3.3, 3.5
     */
    private uploadLargePayload;
    /**
     * Publish request to MQTT topic.
     *
     * @param devId - Developer ID
     * @param requestId - Request ID
     * @param request - Request message
     *
     * @see Requirements 2.1
     */
    private publishRequest;
    /**
     * Wait for response from local CLI.
     *
     * This is a simplified implementation that uses polling.
     * A production implementation would use MQTT subscribe.
     *
     * @param devId - Developer ID
     * @param requestId - Request ID
     * @param timeoutConfig - Timeout configuration
     * @param functionName - Function name for logging
     * @param startTime - Request start time
     * @returns Response from local CLI
     *
     * @see Requirements 1.5, 1.6
     */
    private waitForResponse;
    /**
     * Resolve a pending response.
     *
     * Called when a response message is received from MQTT.
     *
     * @param requestId - Request ID
     * @param response - Response message
     */
    resolveResponse(requestId: string, response: RuntimeAwakeResponse): void;
    /**
     * Process response from local CLI.
     *
     * Handles S3 payload download if needed and converts to API Gateway result.
     *
     * @param response - Response from local CLI
     * @param requestId - Request ID
     * @returns API Gateway proxy result
     *
     * @see Requirements 15.5, 17.1, 17.2, 17.3
     */
    private processResponse;
    /**
     * Download a large payload from S3.
     *
     * @param ref - S3 payload reference
     * @returns Downloaded payload
     * @throws S3DownloadError if download fails
     *
     * @see Requirements 3.4, 3.5
     */
    private downloadLargePayload;
}
/**
 * Create a Proxy Lambda handler from environment configuration.
 *
 * Factory function for creating a Proxy Lambda handler that reads
 * configuration from environment variables.
 *
 * @returns Lambda handler function
 *
 * @example
 * ```typescript
 * export const handler = createProxyLambdaHandler();
 * ```
 */
export declare function createProxyLambdaHandler(): (event: APIGatewayProxyEvent, context: Context) => Promise<APIGatewayProxyResult>;
