import type { S3PayloadReference } from '../../../lib/runtime-web/runtime-awake';
/** Default maximum payload size before S3 indirection (128KB) */
export declare const DEFAULT_MAX_PAYLOAD_SIZE: number;
/** Default pre-signed URL expiration time in seconds (15 minutes) */
export declare const DEFAULT_PRESIGNED_URL_EXPIRATION = 900;
/**
 * Configuration for S3 payload handler.
 */
export interface S3PayloadHandlerConfig {
    /** S3 bucket name for payload storage */
    readonly bucketName: string;
    /** AWS region */
    readonly region: string;
    /** Maximum payload size in bytes before S3 indirection */
    readonly maxPayloadSize?: number;
    /** Pre-signed URL expiration time in seconds */
    readonly presignedUrlExpiration?: number;
}
/**
 * Payload type for S3 key generation.
 */
export type PayloadType = 'request-event' | 'request-context' | 'response-body';
/**
 * S3 Payload Handler for large payload storage and retrieval.
 *
 * Provides methods to:
 * - Check if a payload exceeds the size limit
 * - Upload large payloads to S3 with pre-signed URLs
 * - Download payloads from S3
 * - Generate S3 keys following the pattern: runtime-awake/<devId>/<requestId>/<type>
 *
 * @see Requirements 2.2, 15.1, 15.2, 15.3, 15.4, 15.5
 *
 * @example
 * ```typescript
 * const handler = new S3PayloadHandler({
 *   bucketName: 'my-app-dev-runtime-awake-payloads',
 *   region: 'us-east-1',
 * });
 *
 * // Check and upload if needed
 * const eventPayload = JSON.stringify(event);
 * if (handler.exceedsMaxSize(eventPayload)) {
 *   const ref = await handler.uploadPayload('dev123', 'req-456', 'request-event', eventPayload);
 *   // Use ref in MQTT message
 * }
 *
 * // Download payload
 * if (isS3PayloadReference(message.event)) {
 *   const event = await handler.downloadPayload(message.event);
 * }
 * ```
 */
export declare class S3PayloadHandler {
    private readonly s3Client;
    private readonly bucketName;
    private readonly maxPayloadSize;
    private readonly presignedUrlExpiration;
    /**
     * Create a new S3 payload handler.
     *
     * @param config - Handler configuration
     */
    constructor(config: S3PayloadHandlerConfig);
    /**
     * Check if a payload exceeds the maximum size limit.
     *
     * @param payload - Payload string to check
     * @returns True if payload exceeds the limit
     */
    exceedsMaxSize(payload: string): boolean;
    /**
     * Get the size of a payload in bytes.
     *
     * @param payload - Payload string
     * @returns Size in bytes
     */
    getPayloadSize(payload: string): number;
    /**
     * Generate an S3 key for a payload.
     *
     * Key pattern: runtime-awake/<devId>/<requestId>/<type>
     *
     * @param devId - Developer ID
     * @param requestId - Request ID
     * @param payloadType - Type of payload
     * @returns S3 key string
     *
     * @see Requirements 15.1
     */
    generateKey(devId: string, requestId: string, payloadType: PayloadType): string;
    /**
     * Upload a payload to S3 and return a reference.
     *
     * @param devId - Developer ID
     * @param requestId - Request ID
     * @param payloadType - Type of payload
     * @param payload - Payload string to upload
     * @returns S3 payload reference with pre-signed URL
     *
     * @see Requirements 15.1, 15.2, 15.4
     */
    uploadPayload(devId: string, requestId: string, payloadType: PayloadType, payload: string): Promise<S3PayloadReference>;
    /**
     * Download a payload from S3.
     *
     * @param ref - S3 payload reference
     * @returns Downloaded payload as parsed JSON
     *
     * @see Requirements 15.3, 15.5
     */
    downloadPayload<T = unknown>(ref: S3PayloadReference): Promise<T>;
    /**
     * Download a payload from S3 as raw string.
     *
     * @param ref - S3 payload reference
     * @returns Downloaded payload as string
     */
    downloadPayloadRaw(ref: S3PayloadReference): Promise<string>;
    /**
     * Check if a value is an S3 payload reference.
     *
     * Re-exported from messages.types for convenience.
     *
     * @param value - Value to check
     * @returns True if value is an S3PayloadReference
     */
    isReference(value: unknown): value is S3PayloadReference;
    /**
     * Conditionally upload a payload if it exceeds the size limit.
     *
     * Returns the original payload if under the limit, or an S3 reference if over.
     *
     * @param devId - Developer ID
     * @param requestId - Request ID
     * @param payloadType - Type of payload
     * @param payload - Payload to potentially upload
     * @returns Original payload or S3 reference
     */
    uploadIfNeeded<T>(devId: string, requestId: string, payloadType: PayloadType, payload: T): Promise<T | S3PayloadReference>;
    /**
     * Download a payload if it's an S3 reference, otherwise return as-is.
     *
     * @param payloadOrRef - Payload or S3 reference
     * @returns Downloaded payload or original value
     */
    downloadIfNeeded<T>(payloadOrRef: T | S3PayloadReference): Promise<T>;
    /**
     * Get the bucket name.
     *
     * @returns S3 bucket name
     */
    getBucketName(): string;
    /**
     * Get the maximum payload size.
     *
     * @returns Maximum payload size in bytes
     */
    getMaxPayloadSize(): number;
}
