orgs_members.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  // Membership represents the status of a user's membership in an organization or team.
    14  type Membership struct {
    15  	URL *string `json:"url,omitempty"`
    16  
    17  	// State is the user's status within the organization or team.
    18  	// Possible values are: "active", "pending"
    19  	State *string `json:"state,omitempty"`
    20  
    21  	// Role identifies the user's role within the organization or team.
    22  	// Possible values for organization membership:
    23  	//     member - non-owner organization member
    24  	//     admin - organization owner
    25  	//
    26  	// Possible values for team membership are:
    27  	//     member - a normal member of the team
    28  	//     maintainer - a team maintainer. Able to add/remove other team
    29  	//                  members, promote other team members to team
    30  	//                  maintainer, and edit the team’s name and description
    31  	Role *string `json:"role,omitempty"`
    32  
    33  	// For organization membership, the API URL of the organization.
    34  	OrganizationURL *string `json:"organization_url,omitempty"`
    35  
    36  	// For organization membership, the organization the membership is for.
    37  	Organization *Organization `json:"organization,omitempty"`
    38  
    39  	// For organization membership, the user the membership is for.
    40  	User *User `json:"user,omitempty"`
    41  }
    42  
    43  func (m Membership) String() string {
    44  	return Stringify(m)
    45  }
    46  
    47  // ListMembersOptions specifies optional parameters to the
    48  // OrganizationsService.ListMembers method.
    49  type ListMembersOptions struct {
    50  	// If true (or if the authenticated user is not an owner of the
    51  	// organization), list only publicly visible members.
    52  	PublicOnly bool `url:"-"`
    53  
    54  	// Filter members returned in the list. Possible values are:
    55  	// 2fa_disabled, all. Default is "all".
    56  	Filter string `url:"filter,omitempty"`
    57  
    58  	// Role filters members returned by their role in the organization.
    59  	// Possible values are:
    60  	//     all - all members of the organization, regardless of role
    61  	//     admin - organization owners
    62  	//     member - non-owner organization members
    63  	//
    64  	// Default is "all".
    65  	Role string `url:"role,omitempty"`
    66  
    67  	ListOptions
    68  }
    69  
    70  // ListMembers lists the members for an organization. If the authenticated
    71  // user is an owner of the organization, this will return both concealed and
    72  // public members, otherwise it will only return public members.
    73  //
    74  // GitHub API docs: https://docs.github.com/en/rest/orgs/members#list-organization-members
    75  // GitHub API docs: https://docs.github.com/en/rest/orgs/members#list-public-organization-members
    76  func (s *OrganizationsService) ListMembers(ctx context.Context, org string, opts *ListMembersOptions) ([]*User, *Response, error) {
    77  	var u string
    78  	if opts != nil && opts.PublicOnly {
    79  		u = fmt.Sprintf("orgs/%v/public_members", org)
    80  	} else {
    81  		u = fmt.Sprintf("orgs/%v/members", org)
    82  	}
    83  	u, err := addOptions(u, opts)
    84  	if err != nil {
    85  		return nil, nil, err
    86  	}
    87  
    88  	req, err := s.client.NewRequest("GET", u, nil)
    89  	if err != nil {
    90  		return nil, nil, err
    91  	}
    92  
    93  	var members []*User
    94  	resp, err := s.client.Do(ctx, req, &members)
    95  	if err != nil {
    96  		return nil, resp, err
    97  	}
    98  
    99  	return members, resp, nil
   100  }
   101  
   102  // IsMember checks if a user is a member of an organization.
   103  //
   104  // GitHub API docs: https://docs.github.com/en/rest/orgs/members#check-organization-membership-for-a-user
   105  func (s *OrganizationsService) IsMember(ctx context.Context, org, user string) (bool, *Response, error) {
   106  	u := fmt.Sprintf("orgs/%v/members/%v", org, user)
   107  	req, err := s.client.NewRequest("GET", u, nil)
   108  	if err != nil {
   109  		return false, nil, err
   110  	}
   111  
   112  	resp, err := s.client.Do(ctx, req, nil)
   113  	member, err := parseBoolResponse(err)
   114  	return member, resp, err
   115  }
   116  
   117  // IsPublicMember checks if a user is a public member of an organization.
   118  //
   119  // GitHub API docs: https://docs.github.com/en/rest/orgs/members#check-public-organization-membership-for-a-user
   120  func (s *OrganizationsService) IsPublicMember(ctx context.Context, org, user string) (bool, *Response, error) {
   121  	u := fmt.Sprintf("orgs/%v/public_members/%v", org, user)
   122  	req, err := s.client.NewRequest("GET", u, nil)
   123  	if err != nil {
   124  		return false, nil, err
   125  	}
   126  
   127  	resp, err := s.client.Do(ctx, req, nil)
   128  	member, err := parseBoolResponse(err)
   129  	return member, resp, err
   130  }
   131  
   132  // RemoveMember removes a user from all teams of an organization.
   133  //
   134  // GitHub API docs: https://docs.github.com/en/rest/orgs/members#remove-an-organization-member
   135  func (s *OrganizationsService) RemoveMember(ctx context.Context, org, user string) (*Response, error) {
   136  	u := fmt.Sprintf("orgs/%v/members/%v", org, user)
   137  	req, err := s.client.NewRequest("DELETE", u, nil)
   138  	if err != nil {
   139  		return nil, err
   140  	}
   141  
   142  	return s.client.Do(ctx, req, nil)
   143  }
   144  
   145  // PublicizeMembership publicizes a user's membership in an organization. (A
   146  // user cannot publicize the membership for another user.)
   147  //
   148  // GitHub API docs: https://docs.github.com/en/rest/orgs/members#set-public-organization-membership-for-the-authenticated-user
   149  func (s *OrganizationsService) PublicizeMembership(ctx context.Context, org, user string) (*Response, error) {
   150  	u := fmt.Sprintf("orgs/%v/public_members/%v", org, user)
   151  	req, err := s.client.NewRequest("PUT", u, nil)
   152  	if err != nil {
   153  		return nil, err
   154  	}
   155  
   156  	return s.client.Do(ctx, req, nil)
   157  }
   158  
   159  // ConcealMembership conceals a user's membership in an organization.
   160  //
   161  // GitHub API docs: https://docs.github.com/en/rest/orgs/members#remove-public-organization-membership-for-the-authenticated-user
   162  func (s *OrganizationsService) ConcealMembership(ctx context.Context, org, user string) (*Response, error) {
   163  	u := fmt.Sprintf("orgs/%v/public_members/%v", org, user)
   164  	req, err := s.client.NewRequest("DELETE", u, nil)
   165  	if err != nil {
   166  		return nil, err
   167  	}
   168  
   169  	return s.client.Do(ctx, req, nil)
   170  }
   171  
   172  // ListOrgMembershipsOptions specifies optional parameters to the
   173  // OrganizationsService.ListOrgMemberships method.
   174  type ListOrgMembershipsOptions struct {
   175  	// Filter memberships to include only those with the specified state.
   176  	// Possible values are: "active", "pending".
   177  	State string `url:"state,omitempty"`
   178  
   179  	ListOptions
   180  }
   181  
   182  // ListOrgMemberships lists the organization memberships for the authenticated user.
   183  //
   184  // GitHub API docs: https://docs.github.com/en/rest/orgs/members#list-organization-memberships-for-the-authenticated-user
   185  func (s *OrganizationsService) ListOrgMemberships(ctx context.Context, opts *ListOrgMembershipsOptions) ([]*Membership, *Response, error) {
   186  	u := "user/memberships/orgs"
   187  	u, err := addOptions(u, opts)
   188  	if err != nil {
   189  		return nil, nil, err
   190  	}
   191  
   192  	req, err := s.client.NewRequest("GET", u, nil)
   193  	if err != nil {
   194  		return nil, nil, err
   195  	}
   196  
   197  	var memberships []*Membership
   198  	resp, err := s.client.Do(ctx, req, &memberships)
   199  	if err != nil {
   200  		return nil, resp, err
   201  	}
   202  
   203  	return memberships, resp, nil
   204  }
   205  
   206  // GetOrgMembership gets the membership for a user in a specified organization.
   207  // Passing an empty string for user will get the membership for the
   208  // authenticated user.
   209  //
   210  // GitHub API docs: https://docs.github.com/en/rest/orgs/members#get-an-organization-membership-for-the-authenticated-user
   211  // GitHub API docs: https://docs.github.com/en/rest/orgs/members#get-organization-membership-for-a-user
   212  func (s *OrganizationsService) GetOrgMembership(ctx context.Context, user, org string) (*Membership, *Response, error) {
   213  	var u string
   214  	if user != "" {
   215  		u = fmt.Sprintf("orgs/%v/memberships/%v", org, user)
   216  	} else {
   217  		u = fmt.Sprintf("user/memberships/orgs/%v", org)
   218  	}
   219  
   220  	req, err := s.client.NewRequest("GET", u, nil)
   221  	if err != nil {
   222  		return nil, nil, err
   223  	}
   224  
   225  	membership := new(Membership)
   226  	resp, err := s.client.Do(ctx, req, membership)
   227  	if err != nil {
   228  		return nil, resp, err
   229  	}
   230  
   231  	return membership, resp, nil
   232  }
   233  
   234  // EditOrgMembership edits the membership for user in specified organization.
   235  // Passing an empty string for user will edit the membership for the
   236  // authenticated user.
   237  //
   238  // GitHub API docs: https://docs.github.com/en/rest/orgs/members#update-an-organization-membership-for-the-authenticated-user
   239  // GitHub API docs: https://docs.github.com/en/rest/orgs/members#set-organization-membership-for-a-user
   240  func (s *OrganizationsService) EditOrgMembership(ctx context.Context, user, org string, membership *Membership) (*Membership, *Response, error) {
   241  	var u, method string
   242  	if user != "" {
   243  		u = fmt.Sprintf("orgs/%v/memberships/%v", org, user)
   244  		method = "PUT"
   245  	} else {
   246  		u = fmt.Sprintf("user/memberships/orgs/%v", org)
   247  		method = "PATCH"
   248  	}
   249  
   250  	req, err := s.client.NewRequest(method, u, membership)
   251  	if err != nil {
   252  		return nil, nil, err
   253  	}
   254  
   255  	m := new(Membership)
   256  	resp, err := s.client.Do(ctx, req, m)
   257  	if err != nil {
   258  		return nil, resp, err
   259  	}
   260  
   261  	return m, resp, nil
   262  }
   263  
   264  // RemoveOrgMembership removes user from the specified organization. If the
   265  // user has been invited to the organization, this will cancel their invitation.
   266  //
   267  // GitHub API docs: https://docs.github.com/en/rest/orgs/members#remove-organization-membership-for-a-user
   268  func (s *OrganizationsService) RemoveOrgMembership(ctx context.Context, user, org string) (*Response, error) {
   269  	u := fmt.Sprintf("orgs/%v/memberships/%v", org, user)
   270  	req, err := s.client.NewRequest("DELETE", u, nil)
   271  	if err != nil {
   272  		return nil, err
   273  	}
   274  
   275  	return s.client.Do(ctx, req, nil)
   276  }
   277  
   278  // ListPendingOrgInvitations returns a list of pending invitations.
   279  //
   280  // GitHub API docs: https://docs.github.com/en/rest/orgs/members#list-pending-organization-invitations
   281  func (s *OrganizationsService) ListPendingOrgInvitations(ctx context.Context, org string, opts *ListOptions) ([]*Invitation, *Response, error) {
   282  	u := fmt.Sprintf("orgs/%v/invitations", org)
   283  	u, err := addOptions(u, opts)
   284  	if err != nil {
   285  		return nil, nil, err
   286  	}
   287  
   288  	req, err := s.client.NewRequest("GET", u, nil)
   289  	if err != nil {
   290  		return nil, nil, err
   291  	}
   292  
   293  	var pendingInvitations []*Invitation
   294  	resp, err := s.client.Do(ctx, req, &pendingInvitations)
   295  	if err != nil {
   296  		return nil, resp, err
   297  	}
   298  
   299  	return pendingInvitations, resp, nil
   300  }
   301  
   302  // CreateOrgInvitationOptions specifies the parameters to the OrganizationService.Invite
   303  // method.
   304  type CreateOrgInvitationOptions struct {
   305  	// GitHub user ID for the person you are inviting. Not required if you provide Email.
   306  	InviteeID *int64 `json:"invitee_id,omitempty"`
   307  	// Email address of the person you are inviting, which can be an existing GitHub user.
   308  	// Not required if you provide InviteeID
   309  	Email *string `json:"email,omitempty"`
   310  	// Specify role for new member. Can be one of:
   311  	// * admin - Organization owners with full administrative rights to the
   312  	// 	 organization and complete access to all repositories and teams.
   313  	// * direct_member - Non-owner organization members with ability to see
   314  	//   other members and join teams by invitation.
   315  	// * billing_manager - Non-owner organization members with ability to
   316  	//   manage the billing settings of your organization.
   317  	// Default is "direct_member".
   318  	Role   *string `json:"role"`
   319  	TeamID []int64 `json:"team_ids"`
   320  }
   321  
   322  // CreateOrgInvitation invites people to an organization by using their GitHub user ID or their email address.
   323  // In order to create invitations in an organization,
   324  // the authenticated user must be an organization owner.
   325  //
   326  // GitHub API docs: https://docs.github.com/en/rest/orgs/members#create-an-organization-invitation
   327  func (s *OrganizationsService) CreateOrgInvitation(ctx context.Context, org string, opts *CreateOrgInvitationOptions) (*Invitation, *Response, error) {
   328  	u := fmt.Sprintf("orgs/%v/invitations", org)
   329  
   330  	req, err := s.client.NewRequest("POST", u, opts)
   331  	if err != nil {
   332  		return nil, nil, err
   333  	}
   334  
   335  	var invitation *Invitation
   336  	resp, err := s.client.Do(ctx, req, &invitation)
   337  	if err != nil {
   338  		return nil, resp, err
   339  	}
   340  
   341  	return invitation, resp, nil
   342  }
   343  
   344  // ListOrgInvitationTeams lists all teams associated with an invitation. In order to see invitations in an organization,
   345  // the authenticated user must be an organization owner.
   346  //
   347  // GitHub API docs: https://docs.github.com/en/rest/orgs/members#list-organization-invitation-teams
   348  func (s *OrganizationsService) ListOrgInvitationTeams(ctx context.Context, org, invitationID string, opts *ListOptions) ([]*Team, *Response, error) {
   349  	u := fmt.Sprintf("orgs/%v/invitations/%v/teams", org, invitationID)
   350  	u, err := addOptions(u, opts)
   351  	if err != nil {
   352  		return nil, nil, err
   353  	}
   354  
   355  	req, err := s.client.NewRequest("GET", u, nil)
   356  	if err != nil {
   357  		return nil, nil, err
   358  	}
   359  
   360  	var orgInvitationTeams []*Team
   361  	resp, err := s.client.Do(ctx, req, &orgInvitationTeams)
   362  	if err != nil {
   363  		return nil, resp, err
   364  	}
   365  
   366  	return orgInvitationTeams, resp, nil
   367  }
   368  
   369  // ListFailedOrgInvitations returns a list of failed inviatations.
   370  //
   371  // GitHub API docs: https://docs.github.com/en/rest/orgs/members#list-failed-organization-invitations
   372  func (s *OrganizationsService) ListFailedOrgInvitations(ctx context.Context, org string, opts *ListOptions) ([]*Invitation, *Response, error) {
   373  	u := fmt.Sprintf("orgs/%v/failed_invitations", org)
   374  	u, err := addOptions(u, opts)
   375  	if err != nil {
   376  		return nil, nil, err
   377  	}
   378  
   379  	req, err := s.client.NewRequest("GET", u, nil)
   380  	if err != nil {
   381  		return nil, nil, err
   382  	}
   383  
   384  	var failedInvitations []*Invitation
   385  	resp, err := s.client.Do(ctx, req, &failedInvitations)
   386  	if err != nil {
   387  		return nil, resp, err
   388  	}
   389  
   390  	return failedInvitations, resp, nil
   391  }
   392
View as plain text