users.go

Documentation: github.com/google/go-github/v47/github

     1  // Copyright 2013 The go-github AUTHORS. All rights reserved.
     2  //
     3  // Use of this source code is governed by a BSD-style
     4  // license that can be found in the LICENSE file.
     5  
     6  package github
     7  
     8  import (
     9  	"context"
    10  	"fmt"
    11  )
    12  
    13  // UsersService handles communication with the user related
    14  // methods of the GitHub API.
    15  //
    16  // GitHub API docs: https://docs.github.com/en/rest/users/
    17  type UsersService service
    18  
    19  // User represents a GitHub user.
    20  type User struct {
    21  	Login                   *string    `json:"login,omitempty"`
    22  	ID                      *int64     `json:"id,omitempty"`
    23  	NodeID                  *string    `json:"node_id,omitempty"`
    24  	AvatarURL               *string    `json:"avatar_url,omitempty"`
    25  	HTMLURL                 *string    `json:"html_url,omitempty"`
    26  	GravatarID              *string    `json:"gravatar_id,omitempty"`
    27  	Name                    *string    `json:"name,omitempty"`
    28  	Company                 *string    `json:"company,omitempty"`
    29  	Blog                    *string    `json:"blog,omitempty"`
    30  	Location                *string    `json:"location,omitempty"`
    31  	Email                   *string    `json:"email,omitempty"`
    32  	Hireable                *bool      `json:"hireable,omitempty"`
    33  	Bio                     *string    `json:"bio,omitempty"`
    34  	TwitterUsername         *string    `json:"twitter_username,omitempty"`
    35  	PublicRepos             *int       `json:"public_repos,omitempty"`
    36  	PublicGists             *int       `json:"public_gists,omitempty"`
    37  	Followers               *int       `json:"followers,omitempty"`
    38  	Following               *int       `json:"following,omitempty"`
    39  	CreatedAt               *Timestamp `json:"created_at,omitempty"`
    40  	UpdatedAt               *Timestamp `json:"updated_at,omitempty"`
    41  	SuspendedAt             *Timestamp `json:"suspended_at,omitempty"`
    42  	Type                    *string    `json:"type,omitempty"`
    43  	SiteAdmin               *bool      `json:"site_admin,omitempty"`
    44  	TotalPrivateRepos       *int       `json:"total_private_repos,omitempty"`
    45  	OwnedPrivateRepos       *int       `json:"owned_private_repos,omitempty"`
    46  	PrivateGists            *int       `json:"private_gists,omitempty"`
    47  	DiskUsage               *int       `json:"disk_usage,omitempty"`
    48  	Collaborators           *int       `json:"collaborators,omitempty"`
    49  	TwoFactorAuthentication *bool      `json:"two_factor_authentication,omitempty"`
    50  	Plan                    *Plan      `json:"plan,omitempty"`
    51  	LdapDn                  *string    `json:"ldap_dn,omitempty"`
    52  
    53  	// API URLs
    54  	URL               *string `json:"url,omitempty"`
    55  	EventsURL         *string `json:"events_url,omitempty"`
    56  	FollowingURL      *string `json:"following_url,omitempty"`
    57  	FollowersURL      *string `json:"followers_url,omitempty"`
    58  	GistsURL          *string `json:"gists_url,omitempty"`
    59  	OrganizationsURL  *string `json:"organizations_url,omitempty"`
    60  	ReceivedEventsURL *string `json:"received_events_url,omitempty"`
    61  	ReposURL          *string `json:"repos_url,omitempty"`
    62  	StarredURL        *string `json:"starred_url,omitempty"`
    63  	SubscriptionsURL  *string `json:"subscriptions_url,omitempty"`
    64  
    65  	// TextMatches is only populated from search results that request text matches
    66  	// See: search.go and https://docs.github.com/en/rest/search/#text-match-metadata
    67  	TextMatches []*TextMatch `json:"text_matches,omitempty"`
    68  
    69  	// Permissions and RoleName identify the permissions and role that a user has on a given
    70  	// repository. These are only populated when calling Repositories.ListCollaborators.
    71  	Permissions map[string]bool `json:"permissions,omitempty"`
    72  	RoleName    *string         `json:"role_name,omitempty"`
    73  }
    74  
    75  func (u User) String() string {
    76  	return Stringify(u)
    77  }
    78  
    79  // Get fetches a user. Passing the empty string will fetch the authenticated
    80  // user.
    81  //
    82  // GitHub API docs: https://docs.github.com/en/rest/users/users#get-the-authenticated-user
    83  // GitHub API docs: https://docs.github.com/en/rest/users/users#get-a-user
    84  func (s *UsersService) Get(ctx context.Context, user string) (*User, *Response, error) {
    85  	var u string
    86  	if user != "" {
    87  		u = fmt.Sprintf("users/%v", user)
    88  	} else {
    89  		u = "user"
    90  	}
    91  	req, err := s.client.NewRequest("GET", u, nil)
    92  	if err != nil {
    93  		return nil, nil, err
    94  	}
    95  
    96  	uResp := new(User)
    97  	resp, err := s.client.Do(ctx, req, uResp)
    98  	if err != nil {
    99  		return nil, resp, err
   100  	}
   101  
   102  	return uResp, resp, nil
   103  }
   104  
   105  // GetByID fetches a user.
   106  //
   107  // Note: GetByID uses the undocumented GitHub API endpoint /user/:id.
   108  func (s *UsersService) GetByID(ctx context.Context, id int64) (*User, *Response, error) {
   109  	u := fmt.Sprintf("user/%d", id)
   110  	req, err := s.client.NewRequest("GET", u, nil)
   111  	if err != nil {
   112  		return nil, nil, err
   113  	}
   114  
   115  	user := new(User)
   116  	resp, err := s.client.Do(ctx, req, user)
   117  	if err != nil {
   118  		return nil, resp, err
   119  	}
   120  
   121  	return user, resp, nil
   122  }
   123  
   124  // Edit the authenticated user.
   125  //
   126  // GitHub API docs: https://docs.github.com/en/rest/users/users#update-the-authenticated-user
   127  func (s *UsersService) Edit(ctx context.Context, user *User) (*User, *Response, error) {
   128  	u := "user"
   129  	req, err := s.client.NewRequest("PATCH", u, user)
   130  	if err != nil {
   131  		return nil, nil, err
   132  	}
   133  
   134  	uResp := new(User)
   135  	resp, err := s.client.Do(ctx, req, uResp)
   136  	if err != nil {
   137  		return nil, resp, err
   138  	}
   139  
   140  	return uResp, resp, nil
   141  }
   142  
   143  // HovercardOptions specifies optional parameters to the UsersService.GetHovercard
   144  // method.
   145  type HovercardOptions struct {
   146  	// SubjectType specifies the additional information to be received about the hovercard.
   147  	// Possible values are: organization, repository, issue, pull_request. (Required when using subject_id.)
   148  	SubjectType string `url:"subject_type"`
   149  
   150  	// SubjectID specifies the ID for the SubjectType. (Required when using subject_type.)
   151  	SubjectID string `url:"subject_id"`
   152  }
   153  
   154  // Hovercard represents hovercard information about a user.
   155  type Hovercard struct {
   156  	Contexts []*UserContext `json:"contexts,omitempty"`
   157  }
   158  
   159  // UserContext represents the contextual information about user.
   160  type UserContext struct {
   161  	Message *string `json:"message,omitempty"`
   162  	Octicon *string `json:"octicon,omitempty"`
   163  }
   164  
   165  // GetHovercard fetches contextual information about user. It requires authentication
   166  // via Basic Auth or via OAuth with the repo scope.
   167  //
   168  // GitHub API docs: https://docs.github.com/en/rest/users/users#get-contextual-information-for-a-user
   169  func (s *UsersService) GetHovercard(ctx context.Context, user string, opts *HovercardOptions) (*Hovercard, *Response, error) {
   170  	u := fmt.Sprintf("users/%v/hovercard", user)
   171  	u, err := addOptions(u, opts)
   172  	if err != nil {
   173  		return nil, nil, err
   174  	}
   175  
   176  	req, err := s.client.NewRequest("GET", u, nil)
   177  	if err != nil {
   178  		return nil, nil, err
   179  	}
   180  
   181  	hc := new(Hovercard)
   182  	resp, err := s.client.Do(ctx, req, hc)
   183  	if err != nil {
   184  		return nil, resp, err
   185  	}
   186  
   187  	return hc, resp, nil
   188  }
   189  
   190  // UserListOptions specifies optional parameters to the UsersService.ListAll
   191  // method.
   192  type UserListOptions struct {
   193  	// ID of the last user seen
   194  	Since int64 `url:"since,omitempty"`
   195  
   196  	// Note: Pagination is powered exclusively by the Since parameter,
   197  	// ListOptions.Page has no effect.
   198  	// ListOptions.PerPage controls an undocumented GitHub API parameter.
   199  	ListOptions
   200  }
   201  
   202  // ListAll lists all GitHub users.
   203  //
   204  // To paginate through all users, populate 'Since' with the ID of the last user.
   205  //
   206  // GitHub API docs: https://docs.github.com/en/rest/users/users#list-users
   207  func (s *UsersService) ListAll(ctx context.Context, opts *UserListOptions) ([]*User, *Response, error) {
   208  	u, err := addOptions("users", opts)
   209  	if err != nil {
   210  		return nil, nil, err
   211  	}
   212  
   213  	req, err := s.client.NewRequest("GET", u, nil)
   214  	if err != nil {
   215  		return nil, nil, err
   216  	}
   217  
   218  	var users []*User
   219  	resp, err := s.client.Do(ctx, req, &users)
   220  	if err != nil {
   221  		return nil, resp, err
   222  	}
   223  
   224  	return users, resp, nil
   225  }
   226  
   227  // ListInvitations lists all currently-open repository invitations for the
   228  // authenticated user.
   229  //
   230  // GitHub API docs: https://docs.github.com/en/rest/collaborators/invitations#list-repository-invitations-for-the-authenticated-user
   231  func (s *UsersService) ListInvitations(ctx context.Context, opts *ListOptions) ([]*RepositoryInvitation, *Response, error) {
   232  	u, err := addOptions("user/repository_invitations", opts)
   233  	if err != nil {
   234  		return nil, nil, err
   235  	}
   236  
   237  	req, err := s.client.NewRequest("GET", u, nil)
   238  	if err != nil {
   239  		return nil, nil, err
   240  	}
   241  
   242  	invites := []*RepositoryInvitation{}
   243  	resp, err := s.client.Do(ctx, req, &invites)
   244  	if err != nil {
   245  		return nil, resp, err
   246  	}
   247  
   248  	return invites, resp, nil
   249  }
   250  
   251  // AcceptInvitation accepts the currently-open repository invitation for the
   252  // authenticated user.
   253  //
   254  // GitHub API docs: https://docs.github.com/en/rest/collaborators/invitations#accept-a-repository-invitation
   255  func (s *UsersService) AcceptInvitation(ctx context.Context, invitationID int64) (*Response, error) {
   256  	u := fmt.Sprintf("user/repository_invitations/%v", invitationID)
   257  	req, err := s.client.NewRequest("PATCH", u, nil)
   258  	if err != nil {
   259  		return nil, err
   260  	}
   261  
   262  	return s.client.Do(ctx, req, nil)
   263  }
   264  
   265  // DeclineInvitation declines the currently-open repository invitation for the
   266  // authenticated user.
   267  //
   268  // GitHub API docs: https://docs.github.com/en/rest/collaborators/invitations#decline-a-repository-invitation
   269  func (s *UsersService) DeclineInvitation(ctx context.Context, invitationID int64) (*Response, error) {
   270  	u := fmt.Sprintf("user/repository_invitations/%v", invitationID)
   271  	req, err := s.client.NewRequest("DELETE", u, nil)
   272  	if err != nil {
   273  		return nil, err
   274  	}
   275  
   276  	return s.client.Do(ctx, req, nil)
   277  }
   278
View as plain text