github.com/google/go-github/v68@v68.0.0/github/users.go (about) 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/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 *int64 `json:"total_private_repos,omitempty"` 45 OwnedPrivateRepos *int64 `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/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 // Assignment identifies how a user was assigned to an organization role. Its 75 // possible values are: "direct", "indirect", "mixed". This is only populated when 76 // calling the ListUsersAssignedToOrgRole method. 77 Assignment *string `json:"assignment,omitempty"` 78 // InheritedFrom identifies the team that a user inherited their organization role 79 // from. This is only populated when calling the ListUsersAssignedToOrgRole method. 80 InheritedFrom *Team `json:"inherited_from,omitempty"` 81 } 82 83 func (u User) String() string { 84 return Stringify(u) 85 } 86 87 // Get fetches a user. Passing the empty string will fetch the authenticated 88 // user. 89 // 90 // GitHub API docs: https://docs.github.com/rest/users/users#get-a-user 91 // GitHub API docs: https://docs.github.com/rest/users/users#get-the-authenticated-user 92 // 93 //meta:operation GET /user 94 //meta:operation GET /users/{username} 95 func (s *UsersService) Get(ctx context.Context, user string) (*User, *Response, error) { 96 var u string 97 if user != "" { 98 u = fmt.Sprintf("users/%v", user) 99 } else { 100 u = "user" 101 } 102 req, err := s.client.NewRequest("GET", u, nil) 103 if err != nil { 104 return nil, nil, err 105 } 106 107 uResp := new(User) 108 resp, err := s.client.Do(ctx, req, uResp) 109 if err != nil { 110 return nil, resp, err 111 } 112 113 return uResp, resp, nil 114 } 115 116 // GetByID fetches a user. 117 // 118 // GitHub API docs: https://docs.github.com/rest/users/users#get-a-user-using-their-id 119 // 120 //meta:operation GET /user/{account_id} 121 func (s *UsersService) GetByID(ctx context.Context, id int64) (*User, *Response, error) { 122 u := fmt.Sprintf("user/%d", id) 123 req, err := s.client.NewRequest("GET", u, nil) 124 if err != nil { 125 return nil, nil, err 126 } 127 128 user := new(User) 129 resp, err := s.client.Do(ctx, req, user) 130 if err != nil { 131 return nil, resp, err 132 } 133 134 return user, resp, nil 135 } 136 137 // Edit the authenticated user. 138 // 139 // GitHub API docs: https://docs.github.com/rest/users/users#update-the-authenticated-user 140 // 141 //meta:operation PATCH /user 142 func (s *UsersService) Edit(ctx context.Context, user *User) (*User, *Response, error) { 143 u := "user" 144 req, err := s.client.NewRequest("PATCH", u, user) 145 if err != nil { 146 return nil, nil, err 147 } 148 149 uResp := new(User) 150 resp, err := s.client.Do(ctx, req, uResp) 151 if err != nil { 152 return nil, resp, err 153 } 154 155 return uResp, resp, nil 156 } 157 158 // HovercardOptions specifies optional parameters to the UsersService.GetHovercard 159 // method. 160 type HovercardOptions struct { 161 // SubjectType specifies the additional information to be received about the hovercard. 162 // Possible values are: organization, repository, issue, pull_request. (Required when using subject_id.) 163 SubjectType string `url:"subject_type"` 164 165 // SubjectID specifies the ID for the SubjectType. (Required when using subject_type.) 166 SubjectID string `url:"subject_id"` 167 } 168 169 // Hovercard represents hovercard information about a user. 170 type Hovercard struct { 171 Contexts []*UserContext `json:"contexts,omitempty"` 172 } 173 174 // UserContext represents the contextual information about user. 175 type UserContext struct { 176 Message *string `json:"message,omitempty"` 177 Octicon *string `json:"octicon,omitempty"` 178 } 179 180 // GetHovercard fetches contextual information about user. It requires authentication 181 // via Basic Auth or via OAuth with the repo scope. 182 // 183 // GitHub API docs: https://docs.github.com/rest/users/users#get-contextual-information-for-a-user 184 // 185 //meta:operation GET /users/{username}/hovercard 186 func (s *UsersService) GetHovercard(ctx context.Context, user string, opts *HovercardOptions) (*Hovercard, *Response, error) { 187 u := fmt.Sprintf("users/%v/hovercard", user) 188 u, err := addOptions(u, opts) 189 if err != nil { 190 return nil, nil, err 191 } 192 193 req, err := s.client.NewRequest("GET", u, nil) 194 if err != nil { 195 return nil, nil, err 196 } 197 198 hc := new(Hovercard) 199 resp, err := s.client.Do(ctx, req, hc) 200 if err != nil { 201 return nil, resp, err 202 } 203 204 return hc, resp, nil 205 } 206 207 // UserListOptions specifies optional parameters to the UsersService.ListAll 208 // method. 209 type UserListOptions struct { 210 // ID of the last user seen 211 Since int64 `url:"since,omitempty"` 212 213 // Note: Pagination is powered exclusively by the Since parameter, 214 // ListOptions.Page has no effect. 215 // ListOptions.PerPage controls an undocumented GitHub API parameter. 216 ListOptions 217 } 218 219 // ListAll lists all GitHub users. 220 // 221 // To paginate through all users, populate 'Since' with the ID of the last user. 222 // 223 // GitHub API docs: https://docs.github.com/rest/users/users#list-users 224 // 225 //meta:operation GET /users 226 func (s *UsersService) ListAll(ctx context.Context, opts *UserListOptions) ([]*User, *Response, error) { 227 u, err := addOptions("users", opts) 228 if err != nil { 229 return nil, nil, err 230 } 231 232 req, err := s.client.NewRequest("GET", u, nil) 233 if err != nil { 234 return nil, nil, err 235 } 236 237 var users []*User 238 resp, err := s.client.Do(ctx, req, &users) 239 if err != nil { 240 return nil, resp, err 241 } 242 243 return users, resp, nil 244 } 245 246 // ListInvitations lists all currently-open repository invitations for the 247 // authenticated user. 248 // 249 // GitHub API docs: https://docs.github.com/rest/collaborators/invitations#list-repository-invitations-for-the-authenticated-user 250 // 251 //meta:operation GET /user/repository_invitations 252 func (s *UsersService) ListInvitations(ctx context.Context, opts *ListOptions) ([]*RepositoryInvitation, *Response, error) { 253 u, err := addOptions("user/repository_invitations", opts) 254 if err != nil { 255 return nil, nil, err 256 } 257 258 req, err := s.client.NewRequest("GET", u, nil) 259 if err != nil { 260 return nil, nil, err 261 } 262 263 invites := []*RepositoryInvitation{} 264 resp, err := s.client.Do(ctx, req, &invites) 265 if err != nil { 266 return nil, resp, err 267 } 268 269 return invites, resp, nil 270 } 271 272 // AcceptInvitation accepts the currently-open repository invitation for the 273 // authenticated user. 274 // 275 // GitHub API docs: https://docs.github.com/rest/collaborators/invitations#accept-a-repository-invitation 276 // 277 //meta:operation PATCH /user/repository_invitations/{invitation_id} 278 func (s *UsersService) AcceptInvitation(ctx context.Context, invitationID int64) (*Response, error) { 279 u := fmt.Sprintf("user/repository_invitations/%v", invitationID) 280 req, err := s.client.NewRequest("PATCH", u, nil) 281 if err != nil { 282 return nil, err 283 } 284 285 return s.client.Do(ctx, req, nil) 286 } 287 288 // DeclineInvitation declines the currently-open repository invitation for the 289 // authenticated user. 290 // 291 // GitHub API docs: https://docs.github.com/rest/collaborators/invitations#decline-a-repository-invitation 292 // 293 //meta:operation DELETE /user/repository_invitations/{invitation_id} 294 func (s *UsersService) DeclineInvitation(ctx context.Context, invitationID int64) (*Response, error) { 295 u := fmt.Sprintf("user/repository_invitations/%v", invitationID) 296 req, err := s.client.NewRequest("DELETE", u, nil) 297 if err != nil { 298 return nil, err 299 } 300 301 return s.client.Do(ctx, req, nil) 302 }