epics.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  	"fmt"
    21  	"net/http"
    22  	"time"
    23  )
    24  
    25  // EpicsService handles communication with the epic related methods
    26  // of the GitLab API.
    27  //
    28  // GitLab API docs: https://docs.gitlab.com/ee/api/epics.html
    29  type EpicsService struct {
    30  	client *Client
    31  }
    32  
    33  // EpicAuthor represents a author of the epic.
    34  type EpicAuthor struct {
    35  	ID        int    `json:"id"`
    36  	State     string `json:"state"`
    37  	WebURL    string `json:"web_url"`
    38  	Name      string `json:"name"`
    39  	AvatarURL string `json:"avatar_url"`
    40  	Username  string `json:"username"`
    41  }
    42  
    43  // Epic represents a GitLab epic.
    44  //
    45  // GitLab API docs: https://docs.gitlab.com/ee/api/epics.html
    46  type Epic struct {
    47  	ID                      int         `json:"id"`
    48  	IID                     int         `json:"iid"`
    49  	GroupID                 int         `json:"group_id"`
    50  	ParentID                int         `json:"parent_id"`
    51  	Title                   string      `json:"title"`
    52  	Description             string      `json:"description"`
    53  	State                   string      `json:"state"`
    54  	Confidential            bool        `json:"confidential"`
    55  	WebURL                  string      `json:"web_url"`
    56  	Author                  *EpicAuthor `json:"author"`
    57  	StartDate               *ISOTime    `json:"start_date"`
    58  	StartDateIsFixed        bool        `json:"start_date_is_fixed"`
    59  	StartDateFixed          *ISOTime    `json:"start_date_fixed"`
    60  	StartDateFromMilestones *ISOTime    `json:"start_date_from_milestones"`
    61  	DueDate                 *ISOTime    `json:"due_date"`
    62  	DueDateIsFixed          bool        `json:"due_date_is_fixed"`
    63  	DueDateFixed            *ISOTime    `json:"due_date_fixed"`
    64  	DueDateFromMilestones   *ISOTime    `json:"due_date_from_milestones"`
    65  	CreatedAt               *time.Time  `json:"created_at"`
    66  	UpdatedAt               *time.Time  `json:"updated_at"`
    67  	ClosedAt                *time.Time  `json:"closed_at"`
    68  	Labels                  []string    `json:"labels"`
    69  	Upvotes                 int         `json:"upvotes"`
    70  	Downvotes               int         `json:"downvotes"`
    71  	UserNotesCount          int         `json:"user_notes_count"`
    72  	URL                     string      `json:"url"`
    73  }
    74  
    75  func (e Epic) String() string {
    76  	return Stringify(e)
    77  }
    78  
    79  // ListGroupEpicsOptions represents the available ListGroupEpics() options.
    80  //
    81  // GitLab API docs: https://docs.gitlab.com/ee/api/epics.html#list-epics-for-a-group
    82  type ListGroupEpicsOptions struct {
    83  	ListOptions
    84  	AuthorID                *int          `url:"author_id,omitempty" json:"author_id,omitempty"`
    85  	Labels                  *LabelOptions `url:"labels,comma,omitempty" json:"labels,omitempty"`
    86  	WithLabelDetails        *bool         `url:"with_labels_details,omitempty" json:"with_labels_details,omitempty"`
    87  	OrderBy                 *string       `url:"order_by,omitempty" json:"order_by,omitempty"`
    88  	Sort                    *string       `url:"sort,omitempty" json:"sort,omitempty"`
    89  	Search                  *string       `url:"search,omitempty" json:"search,omitempty"`
    90  	State                   *string       `url:"state,omitempty" json:"state,omitempty"`
    91  	CreatedAfter            *time.Time    `url:"created_after,omitempty" json:"created_after,omitempty"`
    92  	CreatedBefore           *time.Time    `url:"created_before,omitempty" json:"created_before,omitempty"`
    93  	UpdatedAfter            *time.Time    `url:"updated_after,omitempty" json:"updated_after,omitempty"`
    94  	UpdatedBefore           *time.Time    `url:"updated_before,omitempty" json:"updated_before,omitempty"`
    95  	IncludeAncestorGroups   *bool         `url:"include_ancestor_groups,omitempty" json:"include_ancestor_groups,omitempty"`
    96  	IncludeDescendantGroups *bool         `url:"include_descendant_groups,omitempty" json:"include_descendant_groups,omitempty"`
    97  	MyReactionEmoji         *string       `url:"my_reaction_emoji,omitempty" json:"my_reaction_emoji,omitempty"`
    98  }
    99  
   100  // ListGroupEpics gets a list of group epics. This function accepts pagination
   101  // parameters page and per_page to return the list of group epics.
   102  //
   103  // GitLab API docs: https://docs.gitlab.com/ee/api/epics.html#list-epics-for-a-group
   104  func (s *EpicsService) ListGroupEpics(gid interface{}, opt *ListGroupEpicsOptions, options ...RequestOptionFunc) ([]*Epic, *Response, error) {
   105  	group, err := parseID(gid)
   106  	if err != nil {
   107  		return nil, nil, err
   108  	}
   109  	u := fmt.Sprintf("groups/%s/epics", PathEscape(group))
   110  
   111  	req, err := s.client.NewRequest(http.MethodGet, u, opt, options)
   112  	if err != nil {
   113  		return nil, nil, err
   114  	}
   115  
   116  	var es []*Epic
   117  	resp, err := s.client.Do(req, &es)
   118  	if err != nil {
   119  		return nil, resp, err
   120  	}
   121  
   122  	return es, resp, nil
   123  }
   124  
   125  // GetEpic gets a single group epic.
   126  //
   127  // GitLab API docs: https://docs.gitlab.com/ee/api/epics.html#single-epic
   128  func (s *EpicsService) GetEpic(gid interface{}, epic int, options ...RequestOptionFunc) (*Epic, *Response, error) {
   129  	group, err := parseID(gid)
   130  	if err != nil {
   131  		return nil, nil, err
   132  	}
   133  	u := fmt.Sprintf("groups/%s/epics/%d", PathEscape(group), epic)
   134  
   135  	req, err := s.client.NewRequest(http.MethodGet, u, nil, options)
   136  	if err != nil {
   137  		return nil, nil, err
   138  	}
   139  
   140  	e := new(Epic)
   141  	resp, err := s.client.Do(req, e)
   142  	if err != nil {
   143  		return nil, resp, err
   144  	}
   145  
   146  	return e, resp, nil
   147  }
   148  
   149  // GetEpicLinks gets all child epics of an epic.
   150  //
   151  // GitLab API docs: https://docs.gitlab.com/ee/api/epic_links.html
   152  func (s *EpicsService) GetEpicLinks(gid interface{}, epic int, options ...RequestOptionFunc) ([]*Epic, *Response, error) {
   153  	group, err := parseID(gid)
   154  	if err != nil {
   155  		return nil, nil, err
   156  	}
   157  	u := fmt.Sprintf("groups/%s/epics/%d/epics", PathEscape(group), epic)
   158  
   159  	req, err := s.client.NewRequest(http.MethodGet, u, nil, options)
   160  	if err != nil {
   161  		return nil, nil, err
   162  	}
   163  
   164  	var e []*Epic
   165  	resp, err := s.client.Do(req, &e)
   166  	if err != nil {
   167  		return nil, resp, err
   168  	}
   169  
   170  	return e, resp, nil
   171  }
   172  
   173  // CreateEpicOptions represents the available CreateEpic() options.
   174  //
   175  // GitLab API docs: https://docs.gitlab.com/ee/api/epics.html#new-epic
   176  type CreateEpicOptions struct {
   177  	Title            *string       `url:"title,omitempty" json:"title,omitempty"`
   178  	Description      *string       `url:"description,omitempty" json:"description,omitempty"`
   179  	Labels           *LabelOptions `url:"labels,comma,omitempty" json:"labels,omitempty"`
   180  	StartDateIsFixed *bool         `url:"start_date_is_fixed,omitempty" json:"start_date_is_fixed,omitempty"`
   181  	StartDateFixed   *ISOTime      `url:"start_date_fixed,omitempty" json:"start_date_fixed,omitempty"`
   182  	DueDateIsFixed   *bool         `url:"due_date_is_fixed,omitempty" json:"due_date_is_fixed,omitempty"`
   183  	DueDateFixed     *ISOTime      `url:"due_date_fixed,omitempty" json:"due_date_fixed,omitempty"`
   184  }
   185  
   186  // CreateEpic creates a new group epic.
   187  //
   188  // GitLab API docs: https://docs.gitlab.com/ee/api/epics.html#new-epic
   189  func (s *EpicsService) CreateEpic(gid interface{}, opt *CreateEpicOptions, options ...RequestOptionFunc) (*Epic, *Response, error) {
   190  	group, err := parseID(gid)
   191  	if err != nil {
   192  		return nil, nil, err
   193  	}
   194  	u := fmt.Sprintf("groups/%s/epics", PathEscape(group))
   195  
   196  	req, err := s.client.NewRequest(http.MethodPost, u, opt, options)
   197  	if err != nil {
   198  		return nil, nil, err
   199  	}
   200  
   201  	e := new(Epic)
   202  	resp, err := s.client.Do(req, e)
   203  	if err != nil {
   204  		return nil, resp, err
   205  	}
   206  
   207  	return e, resp, nil
   208  }
   209  
   210  // UpdateEpicOptions represents the available UpdateEpic() options.
   211  //
   212  // GitLab API docs: https://docs.gitlab.com/ee/api/epics.html#update-epic
   213  type UpdateEpicOptions struct {
   214  	Title            *string       `url:"title,omitempty" json:"title,omitempty"`
   215  	Confidential     *bool         `url:"confidential,omitempty" json:"confidential,omitempty"`
   216  	Description      *string       `url:"description,omitempty" json:"description,omitempty"`
   217  	Labels           *LabelOptions `url:"labels,comma,omitempty" json:"labels,omitempty"`
   218  	StartDateIsFixed *bool         `url:"start_date_is_fixed,omitempty" json:"start_date_is_fixed,omitempty"`
   219  	StartDateFixed   *ISOTime      `url:"start_date_fixed,omitempty" json:"start_date_fixed,omitempty"`
   220  	DueDateIsFixed   *bool         `url:"due_date_is_fixed,omitempty" json:"due_date_is_fixed,omitempty"`
   221  	DueDateFixed     *ISOTime      `url:"due_date_fixed,omitempty" json:"due_date_fixed,omitempty"`
   222  	StateEvent       *string       `url:"state_event,omitempty" json:"state_event,omitempty"`
   223  }
   224  
   225  // UpdateEpic updates an existing group epic. This function is also used
   226  // to mark an epic as closed.
   227  //
   228  // GitLab API docs: https://docs.gitlab.com/ee/api/epics.html#update-epic
   229  func (s *EpicsService) UpdateEpic(gid interface{}, epic int, opt *UpdateEpicOptions, options ...RequestOptionFunc) (*Epic, *Response, error) {
   230  	group, err := parseID(gid)
   231  	if err != nil {
   232  		return nil, nil, err
   233  	}
   234  	u := fmt.Sprintf("groups/%s/epics/%d", PathEscape(group), epic)
   235  
   236  	req, err := s.client.NewRequest(http.MethodPut, u, opt, options)
   237  	if err != nil {
   238  		return nil, nil, err
   239  	}
   240  
   241  	e := new(Epic)
   242  	resp, err := s.client.Do(req, e)
   243  	if err != nil {
   244  		return nil, resp, err
   245  	}
   246  
   247  	return e, resp, nil
   248  }
   249  
   250  // DeleteEpic deletes a single group epic.
   251  //
   252  // GitLab API docs: https://docs.gitlab.com/ee/api/epics.html#delete-epic
   253  func (s *EpicsService) DeleteEpic(gid interface{}, epic int, options ...RequestOptionFunc) (*Response, error) {
   254  	group, err := parseID(gid)
   255  	if err != nil {
   256  		return nil, err
   257  	}
   258  	u := fmt.Sprintf("groups/%s/epics/%d", PathEscape(group), epic)
   259  
   260  	req, err := s.client.NewRequest(http.MethodDelete, u, nil, options)
   261  	if err != nil {
   262  		return nil, err
   263  	}
   264  
   265  	return s.client.Do(req, nil)
   266  }
   267
View as plain text