/**
 * API Error Handling
 *
 * Provides standardized error classes, error handler middleware,
 * and error serialization for consistent API error responses.
 *
 * @packageDocumentation
 */
import type { FastifyError, FastifyRequest, FastifyReply } from 'fastify';
import { ZodError } from 'zod';
import type { VorionErrorResponse } from '../common/contracts/output.js';
/**
 * Standard error codes for API responses
 */
export declare enum ErrorCode {
    VALIDATION_ERROR = "VALIDATION_ERROR",
    INVALID_INPUT = "INVALID_INPUT",
    INVALID_PARAMS = "INVALID_PARAMS",
    INVALID_QUERY = "INVALID_QUERY",
    MISSING_FIELD = "MISSING_FIELD",
    INVALID_FORMAT = "INVALID_FORMAT",
    PAYLOAD_TOO_LARGE = "PAYLOAD_TOO_LARGE",
    INJECTION_DETECTED = "INJECTION_DETECTED",
    UNAUTHORIZED = "UNAUTHORIZED",
    TOKEN_INVALID = "TOKEN_INVALID",
    TOKEN_EXPIRED = "TOKEN_EXPIRED",
    TOKEN_REVOKED = "TOKEN_REVOKED",
    MISSING_AUTH = "MISSING_AUTH",
    FORBIDDEN = "FORBIDDEN",
    INSUFFICIENT_PERMISSIONS = "INSUFFICIENT_PERMISSIONS",
    TENANT_MISMATCH = "TENANT_MISMATCH",
    NOT_FOUND = "NOT_FOUND",
    RESOURCE_NOT_FOUND = "RESOURCE_NOT_FOUND",
    INTENT_NOT_FOUND = "INTENT_NOT_FOUND",
    POLICY_NOT_FOUND = "POLICY_NOT_FOUND",
    ESCALATION_NOT_FOUND = "ESCALATION_NOT_FOUND",
    CONFLICT = "CONFLICT",
    RESOURCE_EXISTS = "RESOURCE_EXISTS",
    INVALID_STATE = "INVALID_STATE",
    RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED",
    QUOTA_EXCEEDED = "QUOTA_EXCEEDED",
    INTERNAL_ERROR = "INTERNAL_ERROR",
    DATABASE_ERROR = "DATABASE_ERROR",
    EXTERNAL_SERVICE_ERROR = "EXTERNAL_SERVICE_ERROR",
    TIMEOUT = "TIMEOUT",
    SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE"
}
/**
 * Base API error class
 */
export declare class ApiError extends Error {
    readonly code: ErrorCode;
    readonly statusCode: number;
    readonly details?: Record<string, unknown>;
    readonly retryAfter?: number;
    constructor(code: ErrorCode, message: string, details?: Record<string, unknown>, retryAfter?: number);
    /**
     * Serialize to VorionErrorResponse format
     */
    toResponse(requestId: string, includeDetails?: boolean): VorionErrorResponse;
}
/**
 * Not Found error (404)
 */
export declare class NotFoundError extends ApiError {
    constructor(resource?: string, message?: string, details?: Record<string, unknown>);
}
/**
 * Validation error (400)
 */
export declare class ValidationError extends ApiError {
    constructor(message?: string, details?: Record<string, unknown>);
    /**
     * Create from Zod error
     */
    static fromZodError(error: ZodError): ValidationError;
}
/**
 * Authentication error (401)
 */
export declare class AuthError extends ApiError {
    constructor(message?: string, code?: ErrorCode, details?: Record<string, unknown>);
    static tokenInvalid(message?: string): AuthError;
    static tokenExpired(message?: string): AuthError;
    static tokenRevoked(message?: string): AuthError;
    static missingAuth(message?: string): AuthError;
}
/**
 * Rate limit error (429)
 */
export declare class RateLimitError extends ApiError {
    constructor(message: string, retryAfter: number, details?: Record<string, unknown>);
}
/**
 * Conflict error (409)
 */
export declare class ConflictError extends ApiError {
    constructor(message?: string, details?: Record<string, unknown>);
    static invalidState(currentState: string, allowedStates: string[]): ConflictError;
}
/**
 * Forbidden error (403)
 */
export declare class ForbiddenError extends ApiError {
    constructor(message?: string, details?: Record<string, unknown>);
    static insufficientPermissions(requiredPermission: string): ForbiddenError;
    static tenantMismatch(): ForbiddenError;
}
/**
 * Internal server error (500)
 */
export declare class InternalError extends ApiError {
    constructor(message?: string, details?: Record<string, unknown>);
}
/**
 * Get status code for an error code
 */
export declare function getStatusForErrorCode(code: ErrorCode): number;
/**
 * Check if an error is an API error
 */
export declare function isApiError(error: unknown): error is ApiError;
/**
 * Create error response from any error
 */
export declare function createErrorResponse(error: unknown, requestId: string, isProduction?: boolean): {
    response: VorionErrorResponse;
    statusCode: number;
};
/**
 * Create standard error handler middleware for Fastify
 *
 * @param options - Error handler options
 * @returns Fastify error handler
 */
export declare function createErrorHandler(options?: {
    /** Include stack traces in non-production */
    includeStack?: boolean;
    /** Custom error transform */
    transformError?: (error: unknown) => unknown;
}): (error: FastifyError, request: FastifyRequest, reply: FastifyReply) => Promise<void>;
/**
 * Wrap an async handler to catch and format errors
 */
export declare function wrapHandler<T>(handler: (request: FastifyRequest, reply: FastifyReply) => Promise<T>): (request: FastifyRequest, reply: FastifyReply) => Promise<T | VorionErrorResponse>;
//# sourceMappingURL=errors.d.ts.map