labels.go

Documentation: github.com/xanzy/go-gitlab

     1  //
     2  // Copyright 2021, Sander van Harmelen
     3  //
     4  // Licensed under the Apache License, Version 2.0 (the "License");
     5  // you may not use this file except in compliance with the License.
     6  // You may obtain a copy of the License at
     7  //
     8  //     http://www.apache.org/licenses/LICENSE-2.0
     9  //
    10  // Unless required by applicable law or agreed to in writing, software
    11  // distributed under the License is distributed on an "AS IS" BASIS,
    12  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13  // See the License for the specific language governing permissions and
    14  // limitations under the License.
    15  //
    16  
    17  package gitlab
    18  
    19  import (
    20  	"encoding/json"
    21  	"fmt"
    22  	"net/http"
    23  )
    24  
    25  // LabelsService handles communication with the label related methods of the
    26  // GitLab API.
    27  //
    28  // GitLab API docs: https://docs.gitlab.com/ee/api/labels.html
    29  type LabelsService struct {
    30  	client *Client
    31  }
    32  
    33  // Label represents a GitLab label.
    34  //
    35  // GitLab API docs: https://docs.gitlab.com/ee/api/labels.html
    36  type Label struct {
    37  	ID                     int    `json:"id"`
    38  	Name                   string `json:"name"`
    39  	Color                  string `json:"color"`
    40  	TextColor              string `json:"text_color"`
    41  	Description            string `json:"description"`
    42  	OpenIssuesCount        int    `json:"open_issues_count"`
    43  	ClosedIssuesCount      int    `json:"closed_issues_count"`
    44  	OpenMergeRequestsCount int    `json:"open_merge_requests_count"`
    45  	Subscribed             bool   `json:"subscribed"`
    46  	Priority               int    `json:"priority"`
    47  	IsProjectLabel         bool   `json:"is_project_label"`
    48  }
    49  
    50  // UnmarshalJSON implements the json.Unmarshaler interface.
    51  func (l *Label) UnmarshalJSON(data []byte) error {
    52  	type alias Label
    53  	if err := json.Unmarshal(data, (*alias)(l)); err != nil {
    54  		return err
    55  	}
    56  
    57  	if l.Name == "" {
    58  		var raw map[string]interface{}
    59  		if err := json.Unmarshal(data, &raw); err != nil {
    60  			return err
    61  		}
    62  		if title, ok := raw["title"].(string); ok {
    63  			l.Name = title
    64  		}
    65  	}
    66  
    67  	return nil
    68  }
    69  
    70  func (l Label) String() string {
    71  	return Stringify(l)
    72  }
    73  
    74  // ListLabelsOptions represents the available ListLabels() options.
    75  //
    76  // GitLab API docs: https://docs.gitlab.com/ee/api/labels.html#list-labels
    77  type ListLabelsOptions struct {
    78  	ListOptions
    79  	WithCounts            *bool   `url:"with_counts,omitempty" json:"with_counts,omitempty"`
    80  	IncludeAncestorGroups *bool   `url:"include_ancestor_groups,omitempty" json:"include_ancestor_groups,omitempty"`
    81  	Search                *string `url:"search,omitempty" json:"search,omitempty"`
    82  }
    83  
    84  // ListLabels gets all labels for given project.
    85  //
    86  // GitLab API docs: https://docs.gitlab.com/ee/api/labels.html#list-labels
    87  func (s *LabelsService) ListLabels(pid interface{}, opt *ListLabelsOptions, options ...RequestOptionFunc) ([]*Label, *Response, error) {
    88  	project, err := parseID(pid)
    89  	if err != nil {
    90  		return nil, nil, err
    91  	}
    92  	u := fmt.Sprintf("projects/%s/labels", PathEscape(project))
    93  
    94  	req, err := s.client.NewRequest(http.MethodGet, u, opt, options)
    95  	if err != nil {
    96  		return nil, nil, err
    97  	}
    98  
    99  	var l []*Label
   100  	resp, err := s.client.Do(req, &l)
   101  	if err != nil {
   102  		return nil, resp, err
   103  	}
   104  
   105  	return l, resp, nil
   106  }
   107  
   108  // GetLabel get a single label for a given project.
   109  //
   110  // GitLab API docs: https://docs.gitlab.com/ee/api/labels.html#get-a-single-project-label
   111  func (s *LabelsService) GetLabel(pid interface{}, labelID interface{}, options ...RequestOptionFunc) (*Label, *Response, error) {
   112  	project, err := parseID(pid)
   113  	if err != nil {
   114  		return nil, nil, err
   115  	}
   116  	label, err := parseID(labelID)
   117  	if err != nil {
   118  		return nil, nil, err
   119  	}
   120  	u := fmt.Sprintf("projects/%s/labels/%s", PathEscape(project), PathEscape(label))
   121  
   122  	req, err := s.client.NewRequest(http.MethodGet, u, nil, options)
   123  	if err != nil {
   124  		return nil, nil, err
   125  	}
   126  
   127  	var l *Label
   128  	resp, err := s.client.Do(req, &l)
   129  	if err != nil {
   130  		return nil, resp, err
   131  	}
   132  
   133  	return l, resp, nil
   134  }
   135  
   136  // CreateLabelOptions represents the available CreateLabel() options.
   137  //
   138  // GitLab API docs: https://docs.gitlab.com/ee/api/labels.html#create-a-new-label
   139  type CreateLabelOptions struct {
   140  	Name        *string `url:"name,omitempty" json:"name,omitempty"`
   141  	Color       *string `url:"color,omitempty" json:"color,omitempty"`
   142  	Description *string `url:"description,omitempty" json:"description,omitempty"`
   143  	Priority    *int    `url:"priority,omitempty" json:"priority,omitempty"`
   144  }
   145  
   146  // CreateLabel creates a new label for given repository with given name and
   147  // color.
   148  //
   149  // GitLab API docs: https://docs.gitlab.com/ee/api/labels.html#create-a-new-label
   150  func (s *LabelsService) CreateLabel(pid interface{}, opt *CreateLabelOptions, options ...RequestOptionFunc) (*Label, *Response, error) {
   151  	project, err := parseID(pid)
   152  	if err != nil {
   153  		return nil, nil, err
   154  	}
   155  	u := fmt.Sprintf("projects/%s/labels", PathEscape(project))
   156  
   157  	req, err := s.client.NewRequest(http.MethodPost, u, opt, options)
   158  	if err != nil {
   159  		return nil, nil, err
   160  	}
   161  
   162  	l := new(Label)
   163  	resp, err := s.client.Do(req, l)
   164  	if err != nil {
   165  		return nil, resp, err
   166  	}
   167  
   168  	return l, resp, nil
   169  }
   170  
   171  // DeleteLabelOptions represents the available DeleteLabel() options.
   172  //
   173  // GitLab API docs: https://docs.gitlab.com/ee/api/labels.html#delete-a-label
   174  type DeleteLabelOptions struct {
   175  	Name *string `url:"name,omitempty" json:"name,omitempty"`
   176  }
   177  
   178  // DeleteLabel deletes a label given by its name or ID.
   179  //
   180  // GitLab API docs: https://docs.gitlab.com/ee/api/labels.html#delete-a-label
   181  func (s *LabelsService) DeleteLabel(pid interface{}, lid interface{}, opt *DeleteLabelOptions, options ...RequestOptionFunc) (*Response, error) {
   182  	project, err := parseID(pid)
   183  	if err != nil {
   184  		return nil, err
   185  	}
   186  	u := fmt.Sprintf("projects/%s/labels", PathEscape(project))
   187  
   188  	if lid != nil {
   189  		label, err := parseID(lid)
   190  		if err != nil {
   191  			return nil, err
   192  		}
   193  		u = fmt.Sprintf("projects/%s/labels/%s", PathEscape(project), PathEscape(label))
   194  	}
   195  
   196  	req, err := s.client.NewRequest(http.MethodDelete, u, opt, options)
   197  	if err != nil {
   198  		return nil, err
   199  	}
   200  
   201  	return s.client.Do(req, nil)
   202  }
   203  
   204  // UpdateLabelOptions represents the available UpdateLabel() options.
   205  //
   206  // GitLab API docs: https://docs.gitlab.com/ee/api/labels.html#edit-an-existing-label
   207  type UpdateLabelOptions struct {
   208  	Name        *string `url:"name,omitempty" json:"name,omitempty"`
   209  	NewName     *string `url:"new_name,omitempty" json:"new_name,omitempty"`
   210  	Color       *string `url:"color,omitempty" json:"color,omitempty"`
   211  	Description *string `url:"description,omitempty" json:"description,omitempty"`
   212  	Priority    *int    `url:"priority,omitempty" json:"priority,omitempty"`
   213  }
   214  
   215  // UpdateLabel updates an existing label with new name or now color. At least
   216  // one parameter is required, to update the label.
   217  //
   218  // GitLab API docs: https://docs.gitlab.com/ee/api/labels.html#edit-an-existing-label
   219  func (s *LabelsService) UpdateLabel(pid interface{}, opt *UpdateLabelOptions, options ...RequestOptionFunc) (*Label, *Response, error) {
   220  	project, err := parseID(pid)
   221  	if err != nil {
   222  		return nil, nil, err
   223  	}
   224  	u := fmt.Sprintf("projects/%s/labels", PathEscape(project))
   225  
   226  	req, err := s.client.NewRequest(http.MethodPut, u, opt, options)
   227  	if err != nil {
   228  		return nil, nil, err
   229  	}
   230  
   231  	l := new(Label)
   232  	resp, err := s.client.Do(req, l)
   233  	if err != nil {
   234  		return nil, resp, err
   235  	}
   236  
   237  	return l, resp, nil
   238  }
   239  
   240  // SubscribeToLabel subscribes the authenticated user to a label to receive
   241  // notifications. If the user is already subscribed to the label, the status
   242  // code 304 is returned.
   243  //
   244  // GitLab API docs:
   245  // https://docs.gitlab.com/ee/api/labels.html#subscribe-to-a-label
   246  func (s *LabelsService) SubscribeToLabel(pid interface{}, labelID interface{}, options ...RequestOptionFunc) (*Label, *Response, error) {
   247  	project, err := parseID(pid)
   248  	if err != nil {
   249  		return nil, nil, err
   250  	}
   251  	label, err := parseID(labelID)
   252  	if err != nil {
   253  		return nil, nil, err
   254  	}
   255  	u := fmt.Sprintf("projects/%s/labels/%s/subscribe", PathEscape(project), PathEscape(label))
   256  
   257  	req, err := s.client.NewRequest(http.MethodPost, u, nil, options)
   258  	if err != nil {
   259  		return nil, nil, err
   260  	}
   261  
   262  	l := new(Label)
   263  	resp, err := s.client.Do(req, l)
   264  	if err != nil {
   265  		return nil, resp, err
   266  	}
   267  
   268  	return l, resp, nil
   269  }
   270  
   271  // UnsubscribeFromLabel unsubscribes the authenticated user from a label to not
   272  // receive notifications from it. If the user is not subscribed to the label, the
   273  // status code 304 is returned.
   274  //
   275  // GitLab API docs:
   276  // https://docs.gitlab.com/ee/api/labels.html#unsubscribe-from-a-label
   277  func (s *LabelsService) UnsubscribeFromLabel(pid interface{}, labelID interface{}, options ...RequestOptionFunc) (*Response, error) {
   278  	project, err := parseID(pid)
   279  	if err != nil {
   280  		return nil, err
   281  	}
   282  	label, err := parseID(labelID)
   283  	if err != nil {
   284  		return nil, err
   285  	}
   286  	u := fmt.Sprintf("projects/%s/labels/%s/unsubscribe", PathEscape(project), PathEscape(label))
   287  
   288  	req, err := s.client.NewRequest(http.MethodPost, u, nil, options)
   289  	if err != nil {
   290  		return nil, err
   291  	}
   292  
   293  	return s.client.Do(req, nil)
   294  }
   295  
   296  // PromoteLabel Promotes a project label to a group label.
   297  //
   298  // GitLab API docs:
   299  // https://docs.gitlab.com/ee/api/labels.html#promote-a-project-label-to-a-group-label
   300  func (s *LabelsService) PromoteLabel(pid interface{}, labelID interface{}, options ...RequestOptionFunc) (*Response, error) {
   301  	project, err := parseID(pid)
   302  	if err != nil {
   303  		return nil, err
   304  	}
   305  	label, err := parseID(labelID)
   306  	if err != nil {
   307  		return nil, err
   308  	}
   309  	u := fmt.Sprintf("projects/%s/labels/%s/promote", PathEscape(project), PathEscape(label))
   310  
   311  	req, err := s.client.NewRequest(http.MethodPut, u, nil, options)
   312  	if err != nil {
   313  		return nil, err
   314  	}
   315  
   316  	return s.client.Do(req, nil)
   317  }
   318
View as plain text