/**
 * Error Response Types
 *
 * Dual-code error response system supporting both AWS standard codes
 * and legacy xBind codes for backward compatibility.
 *
 * @packageDocumentation
 */
/**
 * Standardized error response structure with dual-code support
 *
 * Supports multiple code formats:
 * - AWS standard codes (primary): InvalidParameterException, UnauthorizedException
 * - Legacy xBind codes (deprecated): XBIND_INVALID_SIGNATURE, XBIND_AUTH_FAILED
 * - gRPC status codes: INVALID_ARGUMENT, UNAUTHENTICATED
 * - HTTP status codes: 400, 401, 403, etc.
 *
 * @example
 * ```typescript
 * const error: ErrorResponse = {
 *   code: 'UnauthorizedException',
 *   legacyCode: 'XBIND_AUTH_FAILED',
 *   httpStatus: 401,
 *   grpcCode: 'UNAUTHENTICATED',
 *   message: 'Invalid signature',
 *   hint: 'Ensure DID signature is correct',
 *   docs: 'https://private.me/docs/xbind#authentication',
 *   requestId: 'req_abc123',
 *   timestamp: Date.now()
 * };
 * ```
 */
export interface ErrorResponse {
    /**
     * AWS standard error code (primary)
     *
     * Examples:
     * - InvalidParameterException
     * - UnauthorizedException
     * - ResourceNotFoundException
     * - InternalServerException
     * - ServiceUnavailableException
     * - ThrottlingException
     *
     * This is the primary code format. All new integrations should use this.
     */
    code: string;
    /**
     * Legacy xBind error code (deprecated)
     *
     * Examples:
     * - XBIND_INVALID_SIGNATURE
     * - XBIND_AUTH_FAILED
     * - XBIND_DID_NOT_FOUND
     * - XBIND_RATE_LIMIT
     *
     * Provided for backward compatibility only.
     * Will be removed in future major version.
     *
     * @deprecated Use `code` field instead
     */
    legacyCode?: string;
    /**
     * HTTP status code
     *
     * Standard HTTP status codes:
     * - 400: Bad Request (InvalidParameterException)
     * - 401: Unauthorized (UnauthorizedException)
     * - 403: Forbidden (AccessDeniedException)
     * - 404: Not Found (ResourceNotFoundException)
     * - 429: Too Many Requests (ThrottlingException)
     * - 500: Internal Server Error (InternalServerException)
     * - 503: Service Unavailable (ServiceUnavailableException)
     */
    httpStatus: number;
    /**
     * gRPC status code (optional)
     *
     * Examples:
     * - INVALID_ARGUMENT
     * - UNAUTHENTICATED
     * - PERMISSION_DENIED
     * - NOT_FOUND
     * - RESOURCE_EXHAUSTED
     * - INTERNAL
     * - UNAVAILABLE
     *
     * Provided for gRPC-based integrations.
     */
    grpcCode?: string;
    /**
     * Human-readable error message
     *
     * Should be clear and actionable. Avoid technical jargon where possible.
     *
     * Example: "Invalid signature" instead of "ECDSA verification failed"
     */
    message: string;
    /**
     * Developer hint for resolving the error (optional)
     *
     * Provides actionable guidance for fixing the issue.
     *
     * Example: "Ensure DID signature is correct and not expired"
     */
    hint?: string;
    /**
     * Documentation URL for detailed error information (optional)
     *
     * Links to relevant documentation section for this error type.
     *
     * Example: "https://private.me/docs/xbind#authentication"
     */
    docs?: string;
    /**
     * Request ID for correlation and debugging (optional)
     *
     * Unique identifier for this request. Used for:
     * - Log correlation across distributed systems
     * - Customer support troubleshooting
     * - Audit trail tracking
     *
     * Format: "req_" + random alphanumeric (e.g., "req_abc123def456")
     */
    requestId?: string;
    /**
     * Error timestamp in milliseconds since Unix epoch (optional)
     *
     * When the error occurred. Useful for:
     * - Time-based debugging
     * - Rate limit tracking
     * - Audit logs
     *
     * Format: Unix timestamp in milliseconds (Date.now())
     */
    timestamp?: number;
    /**
     * Correlation ID for distributed tracing (optional)
     *
     * Tracks a single logical operation across multiple services.
     * Different from requestId (per-request) - this spans multiple requests.
     *
     * Format: UUID or similar distributed trace ID
     *
     * Example: "trace_789xyz" spans: Auth request → DID lookup → Billing check
     */
    correlationId?: string;
}
/**
 * Error response with additional metadata for internal use
 *
 * Extends ErrorResponse with internal fields that should NOT be
 * exposed to external clients.
 *
 * @internal
 */
export interface InternalErrorResponse extends ErrorResponse {
    /**
     * Stack trace (internal only, never exposed externally)
     *
     * @internal
     */
    stack?: string;
    /**
     * Internal error code for debugging (internal only)
     *
     * @internal
     */
    internalCode?: string;
    /**
     * Service name that generated the error
     *
     * @internal
     */
    service?: string;
}
/**
 * Type guard to check if a value is an ErrorResponse
 *
 * @param value - Value to check
 * @returns True if value is an ErrorResponse
 *
 * @example
 * ```typescript
 * if (isErrorResponse(result)) {
 *   console.error(result.message);
 * }
 * ```
 */
export declare function isErrorResponse(value: unknown): value is ErrorResponse;
/**
 * Create a standardized error response
 *
 * @param params - Error response parameters
 * @returns Standardized ErrorResponse object
 *
 * @example
 * ```typescript
 * const error = createErrorResponse({
 *   code: 'UnauthorizedException',
 *   legacyCode: 'XBIND_AUTH_FAILED',
 *   httpStatus: 401,
 *   message: 'Invalid signature'
 * });
 * ```
 */
export declare function createErrorResponse(params: Omit<ErrorResponse, 'timestamp'> & {
    timestamp?: number;
}): ErrorResponse;
