/**
 * Response Middleware for Standardized API Envelopes
 *
 * Provides Fastify hooks and helpers for wrapping responses in the standard
 * API envelope format, adding request context, and handling errors consistently.
 *
 * @packageDocumentation
 */
import type { FastifyInstance, FastifyRequest, FastifyReply, FastifyError } from 'fastify';
import { type TraceContext } from '../common/trace.js';
import { type HttpStatusCode } from './response.js';
/** Header name for request ID tracking */
export declare const REQUEST_ID_HEADER = "X-Request-ID";
/**
 * Extended request interface with trace context
 */
declare module 'fastify' {
    interface FastifyRequest {
        traceContext?: TraceContext;
    }
}
/**
 * Response context stored on request for middleware use
 */
export interface ResponseContext {
    /** Unique request identifier */
    requestId: string;
    /** Trace ID from distributed tracing context */
    traceId?: string | undefined;
    /** Request start time for duration tracking */
    startTime: number;
}
/**
 * Augment FastifyRequest with response context
 */
declare module 'fastify' {
    interface FastifyRequest {
        responseContext?: ResponseContext;
    }
}
/**
 * Register response middleware hooks on a Fastify instance
 *
 * This middleware:
 * 1. Adds request/trace context to each request
 * 2. Provides a standardized error handler
 * 3. Optionally wraps all responses in the standard envelope
 *
 * @param server - The Fastify instance
 * @param options - Middleware configuration options
 *
 * @example
 * ```typescript
 * const server = Fastify();
 * registerResponseMiddleware(server, { wrapAllResponses: false });
 * ```
 */
export declare function registerResponseMiddleware(server: FastifyInstance, options?: {
    /** Whether to automatically wrap all responses in the envelope (default: false) */
    wrapAllResponses?: boolean;
}): void;
/**
 * Create a standardized error handler for Fastify
 *
 * @param env - The environment (development, staging, production)
 * @returns Fastify error handler function
 */
export declare function createStandardErrorHandler(env: string): (error: FastifyError, request: FastifyRequest, reply: FastifyReply) => Promise<void>;
/**
 * Helper to send a standardized success response
 *
 * @param reply - Fastify reply object
 * @param data - Response data
 * @param status - HTTP status code (default: 200)
 * @param request - Optional request for context
 */
export declare function sendSuccess<T>(reply: FastifyReply, data: T, status?: HttpStatusCode, request?: FastifyRequest): FastifyReply;
/**
 * Helper to send a standardized error response
 *
 * @param reply - Fastify reply object
 * @param code - Error code
 * @param message - Error message
 * @param status - HTTP status code
 * @param details - Optional error details
 * @param request - Optional request for context
 */
export declare function sendError(reply: FastifyReply, code: string, message: string, status: HttpStatusCode, details?: Record<string, unknown>, request?: FastifyRequest): FastifyReply;
/**
 * Helper to send a paginated response
 *
 * @param reply - Fastify reply object
 * @param items - Array of items
 * @param pagination - Pagination information
 * @param request - Optional request for context
 */
export declare function sendPaginated<T>(reply: FastifyReply, items: T[], pagination: {
    page: number;
    pageSize: number;
    totalItems: number;
}, request?: FastifyRequest): FastifyReply;
/**
 * Helper to send a cursor-paginated response
 *
 * @param reply - Fastify reply object
 * @param items - Array of items
 * @param cursor - Cursor pagination info
 * @param request - Optional request for context
 */
export declare function sendCursorPaginated<T>(reply: FastifyReply, items: T[], cursor: {
    nextCursor?: string | undefined;
    prevCursor?: string | undefined;
    hasMore: boolean;
}, request?: FastifyRequest): FastifyReply;
/**
 * Helper to send a "not found" error response
 *
 * @param reply - Fastify reply object
 * @param resourceType - Type of resource that was not found
 * @param request - Optional request for context
 */
export declare function sendNotFound(reply: FastifyReply, resourceType: string, request?: FastifyRequest): FastifyReply;
/**
 * Helper to send a validation error response
 *
 * @param reply - Fastify reply object
 * @param message - Validation error message
 * @param errors - Validation error details
 * @param request - Optional request for context
 */
export declare function sendValidationError(reply: FastifyReply, message: string, errors?: Record<string, unknown>, request?: FastifyRequest): FastifyReply;
/**
 * Helper to send a forbidden error response
 *
 * @param reply - Fastify reply object
 * @param message - Forbidden error message
 * @param request - Optional request for context
 */
export declare function sendForbidden(reply: FastifyReply, message?: string, request?: FastifyRequest): FastifyReply;
/**
 * Helper to send an unauthorized error response
 *
 * @param reply - Fastify reply object
 * @param message - Unauthorized error message
 * @param request - Optional request for context
 */
export declare function sendUnauthorized(reply: FastifyReply, message?: string, request?: FastifyRequest): FastifyReply;
/**
 * Helper to send a conflict error response
 *
 * @param reply - Fastify reply object
 * @param message - Conflict error message
 * @param request - Optional request for context
 */
export declare function sendConflict(reply: FastifyReply, message: string, request?: FastifyRequest): FastifyReply;
//# sourceMappingURL=response-middleware.d.ts.map