go-github/github/issues_milestones.go

// Copyright 2014 The go-github AUTHORS. All rights reserved.
//
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

package github

import (
	"context"
	"fmt"
)

// Milestone represents a GitHub repository milestone.
type Milestone struct {
	URL          *string    `json:"url,omitempty"`
	HTMLURL      *string    `json:"html_url,omitempty"`
	LabelsURL    *string    `json:"labels_url,omitempty"`
	ID           *int64     `json:"id,omitempty"`
	Number       *int       `json:"number,omitempty"`
	State        *string    `json:"state,omitempty"`
	Title        *string    `json:"title,omitempty"`
	Description  *string    `json:"description,omitempty"`
	Creator      *User      `json:"creator,omitempty"`
	OpenIssues   *int       `json:"open_issues,omitempty"`
	ClosedIssues *int       `json:"closed_issues,omitempty"`
	CreatedAt    *Timestamp `json:"created_at,omitempty"`
	UpdatedAt    *Timestamp `json:"updated_at,omitempty"`
	ClosedAt     *Timestamp `json:"closed_at,omitempty"`
	DueOn        *Timestamp `json:"due_on,omitempty"`
	NodeID       *string    `json:"node_id,omitempty"`
}

func (m Milestone) String() string {
	return Stringify(m)
}

// CreateMilestoneRequest represents a request to create a milestone.
type CreateMilestoneRequest struct {
	Title       string     `json:"title"`
	State       *string    `json:"state,omitempty"`
	Description *string    `json:"description,omitempty"`
	DueOn       *Timestamp `json:"due_on,omitempty"`
}

// UpdateMilestoneRequest represents a request to update a milestone.
type UpdateMilestoneRequest struct {
	Title       *string    `json:"title,omitempty"`
	State       *string    `json:"state,omitempty"`
	Description *string    `json:"description,omitempty"`
	DueOn       *Timestamp `json:"due_on,omitempty"`
}

// MilestoneListOptions specifies the optional parameters to the
// IssuesService.ListMilestones method.
type MilestoneListOptions struct {
	// State filters milestones based on their state. Possible values are:
	// open, closed, all. Default is "open".
	State string `url:"state,omitempty"`

	// Sort specifies how to sort milestones. Possible values are: due_on, completeness.
	// Default value is "due_on".
	Sort string `url:"sort,omitempty"`

	// Direction in which to sort milestones. Possible values are: asc, desc.
	// Default is "asc".
	Direction string `url:"direction,omitempty"`

	ListOptions
}

// ListMilestones lists all milestones for a repository.
//
// GitHub API docs: https://docs.github.com/rest/issues/milestones?apiVersion=2022-11-28#list-milestones
//
//meta:operation GET /repos/{owner}/{repo}/milestones
func (s *IssuesService) ListMilestones(ctx context.Context, owner, repo string, opts *MilestoneListOptions) ([]*Milestone, *Response, error) {
	u := fmt.Sprintf("repos/%v/%v/milestones", owner, repo)
	u, err := addOptions(u, opts)
	if err != nil {
		return nil, nil, err
	}

	req, err := s.client.NewRequest(ctx, "GET", u, nil)
	if err != nil {
		return nil, nil, err
	}

	var milestones []*Milestone
	resp, err := s.client.Do(req, &milestones)
	if err != nil {
		return nil, resp, err
	}

	return milestones, resp, nil
}

// GetMilestone gets a single milestone.
//
// GitHub API docs: https://docs.github.com/rest/issues/milestones?apiVersion=2022-11-28#get-a-milestone
//
//meta:operation GET /repos/{owner}/{repo}/milestones/{milestone_number}
func (s *IssuesService) GetMilestone(ctx context.Context, owner, repo string, number int) (*Milestone, *Response, error) {
	u := fmt.Sprintf("repos/%v/%v/milestones/%v", owner, repo, number)
	req, err := s.client.NewRequest(ctx, "GET", u, nil)
	if err != nil {
		return nil, nil, err
	}

	var milestone *Milestone
	resp, err := s.client.Do(req, &milestone)
	if err != nil {
		return nil, resp, err
	}

	return milestone, resp, nil
}

// CreateMilestone creates a new milestone on the specified repository.
//
// GitHub API docs: https://docs.github.com/rest/issues/milestones?apiVersion=2022-11-28#create-a-milestone
//
//meta:operation POST /repos/{owner}/{repo}/milestones
func (s *IssuesService) CreateMilestone(ctx context.Context, owner, repo string, body CreateMilestoneRequest) (*Milestone, *Response, error) {
	u := fmt.Sprintf("repos/%v/%v/milestones", owner, repo)
	req, err := s.client.NewRequest(ctx, "POST", u, body)
	if err != nil {
		return nil, nil, err
	}

	var m *Milestone
	resp, err := s.client.Do(req, &m)
	if err != nil {
		return nil, resp, err
	}

	return m, resp, nil
}

// UpdateMilestone updates a milestone.
//
// GitHub API docs: https://docs.github.com/rest/issues/milestones?apiVersion=2022-11-28#update-a-milestone
//
//meta:operation PATCH /repos/{owner}/{repo}/milestones/{milestone_number}
func (s *IssuesService) UpdateMilestone(ctx context.Context, owner, repo string, number int, body UpdateMilestoneRequest) (*Milestone, *Response, error) {
	u := fmt.Sprintf("repos/%v/%v/milestones/%v", owner, repo, number)
	req, err := s.client.NewRequest(ctx, "PATCH", u, body)
	if err != nil {
		return nil, nil, err
	}

	var m *Milestone
	resp, err := s.client.Do(req, &m)
	if err != nil {
		return nil, resp, err
	}

	return m, resp, nil
}

// DeleteMilestone deletes a milestone.
//
// GitHub API docs: https://docs.github.com/rest/issues/milestones?apiVersion=2022-11-28#delete-a-milestone
//
//meta:operation DELETE /repos/{owner}/{repo}/milestones/{milestone_number}
func (s *IssuesService) DeleteMilestone(ctx context.Context, owner, repo string, number int) (*Response, error) {
	u := fmt.Sprintf("repos/%v/%v/milestones/%v", owner, repo, number)
	req, err := s.client.NewRequest(ctx, "DELETE", u, nil)
	if err != nil {
		return nil, err
	}

	return s.client.Do(req, nil)
}