import type { APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda';
import type { RuntimeAwakeRequest, S3PayloadReference } from '../../../lib/runtime-web/runtime-awake';
/**
 * Maximum payload size for MQTT messages (128KB).
 */
export declare const MQTT_PAYLOAD_SIZE_LIMIT: number;
/**
 * Error class for payload handling failures.
 */
export declare class PayloadHandlerError extends Error {
    readonly cause?: Error | undefined;
    constructor(message: string, cause?: Error | undefined);
}
/**
 * Configuration for the payload handler.
 */
export interface PayloadHandlerConfig {
    /** AWS region */
    readonly region: string;
    /** AWS profile (optional) */
    readonly profile?: string;
    /** S3 bucket name for large payloads */
    readonly payloadBucketName: string;
    /** Developer ID for S3 key prefix */
    readonly devId: string;
    /** Pre-signed URL expiration in seconds (default: 900 = 15 minutes) */
    readonly presignedUrlExpirationSeconds?: number;
}
/**
 * S3 Payload Handler for Awake Lambda Development.
 *
 * Handles download and upload of large payloads that exceed the 128KB MQTT limit.
 * Uses S3 as intermediate storage with pre-signed URLs for secure access.
 *
 * @see Requirements 2.3, 15.3
 *
 * @example
 * ```typescript
 * const handler = new S3PayloadHandler({
 *   region: 'us-east-1',
 *   payloadBucketName: 'my-app-dev-runtime-awake-payloads',
 *   devId: 'john.doe',
 * });
 *
 * // Download large event payload
 * const event = await handler.downloadEventPayload(request);
 *
 * // Upload large response payload
 * const reference = await handler.uploadResponsePayload(requestId, response);
 * ```
 */
export declare class S3PayloadHandler {
    private readonly config;
    private readonly s3Client;
    private readonly presignedUrlExpirationSeconds;
    /**
     * Create a new S3PayloadHandler.
     *
     * @param config - Payload handler configuration
     */
    constructor(config: PayloadHandlerConfig);
    /**
     * Download event payload from S3 if it's an S3 reference.
     *
     * Checks if the request event is an S3PayloadReference and downloads
     * the actual payload from S3. Returns the original event if not a reference.
     *
     * @param request - Live Dev request message
     * @returns The actual APIGatewayProxyEvent (downloaded from S3 if needed)
     * @throws PayloadHandlerError if download fails
     *
     * @see Requirements 2.3, 15.3
     */
    downloadEventPayload(request: RuntimeAwakeRequest): Promise<APIGatewayProxyEvent>;
    /**
     * Upload response payload to S3 if it exceeds the MQTT limit.
     *
     * Checks if the response payload exceeds 128KB and uploads it to S3.
     * Returns an S3PayloadReference if uploaded, or the original result if not needed.
     *
     * @param requestId - Request ID for S3 key generation
     * @param result - Handler result to potentially upload
     * @returns S3PayloadReference if uploaded, or original result
     * @throws PayloadHandlerError if upload fails
     *
     * @see Requirements 15.4
     */
    uploadResponsePayloadIfNeeded(requestId: string, result: APIGatewayProxyResult): Promise<APIGatewayProxyResult | S3PayloadReference>;
    /**
     * Download payload from S3 using reference.
     *
     * @param reference - S3 payload reference
     * @returns Downloaded payload as string
     * @throws PayloadHandlerError if download fails
     */
    downloadFromS3(reference: S3PayloadReference): Promise<string>;
    /**
     * Upload payload to S3.
     *
     * @param key - S3 object key
     * @param payload - Payload to upload
     * @throws PayloadHandlerError if upload fails
     */
    uploadToS3(key: string, payload: string): Promise<void>;
    /**
     * Generate a pre-signed URL for S3 object download.
     *
     * @param key - S3 object key
     * @returns Pre-signed URL
     */
    generatePresignedUrl(key: string): Promise<string>;
    /**
     * Generate S3 key for payload storage.
     *
     * Key pattern: `runtime-awake/<devId>/<requestId>/<type>`
     *
     * @param requestId - Request ID
     * @param type - Payload type ('request' or 'response')
     * @returns S3 object key
     */
    generateS3Key(requestId: string, type: 'request' | 'response'): string;
    /**
     * Check if a payload exceeds the MQTT size limit.
     *
     * @param payload - Payload to check (object or string)
     * @returns True if payload exceeds 128KB
     */
    static exceedsMqttLimit(payload: unknown): boolean;
    /**
     * Get the payload size in bytes.
     *
     * @param payload - Payload to measure (object or string)
     * @returns Size in bytes
     */
    static getPayloadSize(payload: unknown): number;
}
