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