1package gitlab
2
3import (
4 "fmt"
5 "time"
6)
7
8// EpicsService handles communication with the epic related methods
9// of the GitLab API.
10//
11// GitLab API docs: https://docs.gitlab.com/ee/api/epics.html
12type EpicsService struct {
13 client *Client
14}
15
16// EpicAuthor represents a author of the epic.
17type EpicAuthor struct {
18 ID int `json:"id"`
19 State string `json:"state"`
20 WebURL string `json:"web_url"`
21 Name string `json:"name"`
22 AvatarURL string `json:"avatar_url"`
23 Username string `json:"username"`
24}
25
26// Epic represents a GitLab epic.
27//
28// GitLab API docs: https://docs.gitlab.com/ee/api/epics.html
29type Epic struct {
30 ID int `json:"id"`
31 IID int `json:"iid"`
32 GroupID int `json:"group_id"`
33 Author *EpicAuthor `json:"author"`
34 Description string `json:"description"`
35 State string `json:"state"`
36 Upvotes int `json:"upvotes"`
37 Downvotes int `json:"downvotes"`
38 Labels []string `json:"labels"`
39 Title string `json:"title"`
40 UpdatedAt *time.Time `json:"updated_at"`
41 CreatedAt *time.Time `json:"created_at"`
42 UserNotesCount int `json:"user_notes_count"`
43 StartDate *ISOTime `json:"start_date"`
44 StartDateIsFixed bool `json:"start_date_is_fixed"`
45 StartDateFixed *ISOTime `json:"start_date_fixed"`
46 StartDateFromMilestones *ISOTime `json:"start_date_from_milestones"`
47 DueDate *ISOTime `json:"due_date"`
48 DueDateIsFixed bool `json:"due_date_is_fixed"`
49 DueDateFixed *ISOTime `json:"due_date_fixed"`
50 DueDateFromMilestones *ISOTime `json:"due_date_from_milestones"`
51}
52
53func (e Epic) String() string {
54 return Stringify(e)
55}
56
57// ListGroupEpicsOptions represents the available ListGroupEpics() options.
58//
59// GitLab API docs: https://docs.gitlab.com/ee/api/epics.html#list-epics-for-a-group
60type ListGroupEpicsOptions struct {
61 ListOptions
62 State *string `url:"state,omitempty" json:"state,omitempty"`
63 Labels Labels `url:"labels,comma,omitempty" json:"labels,omitempty"`
64 AuthorID *int `url:"author_id,omitempty" json:"author_id,omitempty"`
65 OrderBy *string `url:"order_by,omitempty" json:"order_by,omitempty"`
66 Sort *string `url:"sort,omitempty" json:"sort,omitempty"`
67 Search *string `url:"search,omitempty" json:"search,omitempty"`
68}
69
70// ListGroupEpics gets a list of group epics. This function accepts pagination
71// parameters page and per_page to return the list of group epics.
72//
73// GitLab API docs: https://docs.gitlab.com/ee/api/epics.html#list-epics-for-a-group
74func (s *EpicsService) ListGroupEpics(gid interface{}, opt *ListGroupEpicsOptions, options ...OptionFunc) ([]*Epic, *Response, error) {
75 group, err := parseID(gid)
76 if err != nil {
77 return nil, nil, err
78 }
79 u := fmt.Sprintf("groups/%s/epics", pathEscape(group))
80
81 req, err := s.client.NewRequest("GET", u, opt, options)
82 if err != nil {
83 return nil, nil, err
84 }
85
86 var es []*Epic
87 resp, err := s.client.Do(req, &es)
88 if err != nil {
89 return nil, resp, err
90 }
91
92 return es, resp, err
93}
94
95// GetEpic gets a single group epic.
96//
97// GitLab API docs: https://docs.gitlab.com/ee/api/epics.html#single-epic
98func (s *EpicsService) GetEpic(gid interface{}, epic int, options ...OptionFunc) (*Epic, *Response, error) {
99 group, err := parseID(gid)
100 if err != nil {
101 return nil, nil, err
102 }
103 u := fmt.Sprintf("groups/%s/epics/%d", pathEscape(group), epic)
104
105 req, err := s.client.NewRequest("GET", u, nil, options)
106 if err != nil {
107 return nil, nil, err
108 }
109
110 e := new(Epic)
111 resp, err := s.client.Do(req, e)
112 if err != nil {
113 return nil, resp, err
114 }
115
116 return e, resp, err
117}
118
119// CreateEpicOptions represents the available CreateEpic() options.
120//
121// GitLab API docs: https://docs.gitlab.com/ee/api/epics.html#new-epic
122type CreateEpicOptions struct {
123 Title *string `url:"title,omitempty" json:"title,omitempty"`
124 Description *string `url:"description,omitempty" json:"description,omitempty"`
125 Labels Labels `url:"labels,comma,omitempty" json:"labels,omitempty"`
126 StartDateIsFixed *bool `url:"start_date_is_fixed,omitempty" json:"start_date_is_fixed,omitempty"`
127 StartDateFixed *ISOTime `url:"start_date_fixed,omitempty" json:"start_date_fixed,omitempty"`
128 DueDateIsFixed *bool `url:"due_date_is_fixed,omitempty" json:"due_date_is_fixed,omitempty"`
129 DueDateFixed *ISOTime `url:"due_date_fixed,omitempty" json:"due_date_fixed,omitempty"`
130}
131
132// CreateEpic creates a new group epic.
133//
134// GitLab API docs: https://docs.gitlab.com/ee/api/epics.html#new-epic
135func (s *EpicsService) CreateEpic(gid interface{}, opt *CreateEpicOptions, options ...OptionFunc) (*Epic, *Response, error) {
136 group, err := parseID(gid)
137 if err != nil {
138 return nil, nil, err
139 }
140 u := fmt.Sprintf("groups/%s/epics", pathEscape(group))
141
142 req, err := s.client.NewRequest("POST", u, opt, options)
143 if err != nil {
144 return nil, nil, err
145 }
146
147 e := new(Epic)
148 resp, err := s.client.Do(req, e)
149 if err != nil {
150 return nil, resp, err
151 }
152
153 return e, resp, err
154}
155
156// UpdateEpicOptions represents the available UpdateEpic() options.
157//
158// GitLab API docs: https://docs.gitlab.com/ee/api/epics.html#update-epic
159type UpdateEpicOptions struct {
160 Title *string `url:"title,omitempty" json:"title,omitempty"`
161 Description *string `url:"description,omitempty" json:"description,omitempty"`
162 Labels Labels `url:"labels,comma,omitempty" json:"labels,omitempty"`
163 StartDateIsFixed *bool `url:"start_date_is_fixed,omitempty" json:"start_date_is_fixed,omitempty"`
164 StartDateFixed *ISOTime `url:"start_date_fixed,omitempty" json:"start_date_fixed,omitempty"`
165 DueDateIsFixed *bool `url:"due_date_is_fixed,omitempty" json:"due_date_is_fixed,omitempty"`
166 DueDateFixed *ISOTime `url:"due_date_fixed,omitempty" json:"due_date_fixed,omitempty"`
167 StateEvent *string `url:"state_event,omitempty" json:"state_event,omitempty"`
168}
169
170// UpdateEpic updates an existing group epic. This function is also used
171// to mark an epic as closed.
172//
173// GitLab API docs: https://docs.gitlab.com/ee/api/epics.html#update-epic
174func (s *EpicsService) UpdateEpic(gid interface{}, epic int, opt *UpdateEpicOptions, options ...OptionFunc) (*Epic, *Response, error) {
175 group, err := parseID(gid)
176 if err != nil {
177 return nil, nil, err
178 }
179 u := fmt.Sprintf("groups/%s/epics/%d", pathEscape(group), epic)
180
181 req, err := s.client.NewRequest("PUT", u, opt, options)
182 if err != nil {
183 return nil, nil, err
184 }
185
186 e := new(Epic)
187 resp, err := s.client.Do(req, e)
188 if err != nil {
189 return nil, resp, err
190 }
191
192 return e, resp, err
193}
194
195// DeleteEpic deletes a single group epic.
196//
197// GitLab API docs: https://docs.gitlab.com/ee/api/epics.html#delete-epic
198func (s *EpicsService) DeleteEpic(gid interface{}, epic int, options ...OptionFunc) (*Response, error) {
199 group, err := parseID(gid)
200 if err != nil {
201 return nil, err
202 }
203 u := fmt.Sprintf("groups/%s/epics/%d", pathEscape(group), epic)
204
205 req, err := s.client.NewRequest("DELETE", u, nil, options)
206 if err != nil {
207 return nil, err
208 }
209
210 return s.client.Do(req, nil)
211}