package controllers

// ==========================================================
// VIRTUAL HANDLERS (Middleware-Only Routes)
// ==========================================================

// Login godoc
// @Summary      User Login
// @Description  Authenticates a user and returns a refresh token (via cookie)
// @Tags         auth
// @Accept       json
// @Produce      json
// @Param        credentials  body      dtos.LoginRequest  true  "Login Credentials"
// @Success      200          {object}  swaggMessageResponse  "Sets HttpOnly refresh cookie"
// @Failure      401          {object}  swaggError401
// @Router       /auth/log-in [post]
func _() {}

// Logout godoc
// @Summary      User Logout
// @Description  Logs out the user by clearing the refresh token cookie
// @Tags         auth
// @Produce      json
// @Success      200          {object}  swaggMessageResponse  "Clears HttpOnly refresh cookie"
// @Failure      401          {object}  swaggError401
// @Security     BearerAuth
// @Router       /auth/logout [post]
func _() {}

// RefreshToken godoc
// @Summary      Refresh Access Token
// @Description  Uses the refresh token cookie to generate a new short-lived access token
// @Tags         auth
// @Produce      json
// @Success      200          {object}  swaggMessageResponse  "Returns the new JWT Access Token"
// @Failure      401          {object}  swaggError401
// @Router       /auth/refresh [post]
func _() {}

// IsLoggedIn godoc
// @Summary      Check Auth Status
// @Description  Validates the current access token
// @Tags         auth
// @Produce      json
// @Success      200          {string}  string "OK"
// @Failure      401          {object}  swaggError401
// @Security     BearerAuth
// @Router       /users/is-logged-in [get]
func _() {}

// GetPrivateTrackUrl godoc
// @Summary      Get Private Track URL
// @Description  Generates a presigned GET URL for a private track's audio file
// @Tags         tracks
// @Accept       json
// @Produce      json
// @Param        request  body      dtos.GetPrivateTrackUploadUrl  true  "Track Audio File Data"
// @Success      200      {string}  string "Presigned URL"
// @Failure      400      {object}  swaggError400
// @Failure      401      {object}  swaggError401
// @Failure      403      {object}  swaggError403
// @Failure      500      {object}  swaggError500
// @Security     BearerAuth
// @Router       /tracks/url [post]
func _() {}

// ==========================================================
// SWAGGER-ONLY ERROR DEFINITIONS
// ==========================================================

type swaggError400 struct {
	Error string `json:"error" example:"Bad Request: Invalid format or missing fields"`
}
type swaggError401 struct {
	Error string `json:"error" example:"Unauthorized: Missing, invalid, or expired Bearer token"`
}
type swaggError403 struct {
	Error string `json:"error" example:"Forbidden: You do not have permission to modify this resource"`
}
type swaggError404 struct {
	Error string `json:"error" example:"Not Found: The requested resource does not exist"`
}
type swaggError422 struct {
	Error string `json:"error" example:"Unprocessable Entity: Validation failed"`
}
type swaggError500 struct {
	Error string `json:"error" example:"Internal Server Error: Database context error"`
}

// ==========================================================
// SWAGGER-ONLY SUCCESS DEFINITIONS (gin.H outputs)
// ==========================================================

type swaggMessageResponse struct {
	Message string `json:"message" example:"Operation completed successfully"`
}

type swaggIsFriendResponse struct {
	IsFriend bool `json:"is_friend" example:"true"`
}

type swaggFriendsResponse struct {
	// We use an empty interface internally for swagger to break the pointer cycle issue
	Friends []interface{} `json:"friends"`
}