github_api 0.12.4 → 0.13.0

data/lib/github_api/client/orgs/memberships.rb

@@ -0,0 +1,129 @@
+# encoding: utf-8
+
+module Github
+  class Client::Orgs::Memberships < API
+    # List your organization memberships
+    #
+    # @see List your organization memberships
+    #
+    # @example
+    #   github = Github.new
+    #   github.orgs.memberships.list
+    #
+    # @api public
+    def list(*args)
+      arguments(args)
+
+      response = get_request('/user/memberships/orgs', arguments.params)
+      return response unless block_given?
+      response.each { |el| yield el }
+    end
+    alias_method :all, :list
+
+    # Get organization membership
+    #
+    # In order to get a user's membership with an organization,
+    # the authenticated user must be an organization owner.
+    #
+    # @see https://developer.github.com/v3/orgs/members/#get-organization-membership
+    # @param [String] :org
+    # @param [String] :username
+    #
+    # @example
+    #   github = Github.new oauth_toke: '...'
+    #   github.orgs.memberships.get 'orgname', username: 'piotr'
+    #
+    # Get your organization membership
+    #
+    # @see https://developer.github.com/v3/orgs/members/#get-your-organization-membership
+    #
+    # @example
+    #   github = Github.new oauth_token
+    #   github.orgs.memberships.get 'orgname'
+    #
+    # @api public
+    def get(*args)
+      arguments(args, required: [:org_name])
+      params = arguments.params
+
+      if (username = params.delete('username'))
+        get_request("/orgs/#{arguments.org_name}/memberships/#{username}", params)
+      else
+        get_request("/user/memberships/orgs/#{arguments.org_name}", params)
+      end
+    end
+    alias_method :find, :get
+
+    # Add/update user's membership with organization
+    #
+    # In order to create or update a user's membership with an organization,
+    # the authenticated user must be an organization owner.
+    #
+    # @see https://developer.github.com/v3/orgs/members/#add-or-update-organization-membership
+    #
+    # @param [String] :org
+    # @param [String] :username
+    # @param [Hash] options
+    # @option options [String] :role
+    #   Required. The role to give the user in the organization. Can be one of:
+    #     * admin - The user will become an owner of the organization.
+    #     * member - The user will become a non-owner member of the organization.
+    #
+    # @example
+    #   github = Github.new oauth_token: '...'
+    #   github.orgs.memberships.add 'org-name', 'member-name', role: 'role'
+    #
+    # @api public
+    def create(*args)
+      arguments(args, required: [:org_name, :username]) do
+        assert_required :role
+      end
+
+      put_request("/orgs/#{arguments.org_name}/memberships/#{arguments.username}",
+                  arguments.params)
+    end
+    alias_method :update, :create
+    alias_method :add, :create
+
+    # Edit your organization membership
+    #
+    # @see https://developer.github.com/v3/orgs/members/#edit-your-organization-membership
+    # @param [String] :org
+    # @param [Hash] params
+    # @option params [String] :state
+    #   Required. The state that the membership should be in.
+    #   Only "active" will be accepted.
+    #
+    # @example
+    #   github = Github.new oauth_token: '...'
+    #   github.orgs.memberships.edit 'org-name', state: 'active'
+    #
+    # @api public
+    def edit(*args)
+      arguments(args, required: [:org_name]) do
+        assert_required :state
+      end
+
+      patch_request("/user/memberships/orgs/#{arguments.org_name}",
+                    arguments.params)
+    end
+
+    # Remove organization membership
+    #
+    # @see https://developer.github.com/v3/orgs/members/#remove-organization-membership
+    # @param [String] :org
+    # @param [String] :username
+    #
+    # @example
+    #   github = Github.new oauth_token: '...'
+    #   github.orgs.memberships.remove 'orgname', 'username'
+    #
+    # @api public
+    def delete(*args)
+      arguments(args, required: [:org_name, :username])
+
+      delete_request("/orgs/#{arguments.org_name}/memberships/#{arguments.username}", arguments.params)
+    end
+    alias_method :remove, :delete
+  end # Client::Orgs::Memberships
+end # Github

data/lib/github_api/client/orgs/teams.rb

@@ -1,16 +1,10 @@
 # encoding: utf-8
 
 module Github
+  # All actions against teams require at a minimum an authenticated user
+  # who is a member of the owner's team in the :org being managed.
+  # Api calls that require explicit permissions are noted.
   class Client::Orgs::Teams < API
-    # All actions against teams require at a minimum an authenticated user
-    # who is a member of the owner’s team in the :org being managed.
-    # Api calls that require explicit permissions are noted.
-
-    VALID_TEAM_PARAM_NAMES = %w[ name repo_names permission ].freeze
-    VALID_TEAM_PARAM_VALUES = {
-      'permission' => %w[ pull push admin ].freeze
-    }
-
     # List user teams
     #
     # List all of the teams across all of the organizations
@@ -23,6 +17,8 @@ module Github
     #
     # List teams
     #
+    # @see https://developer.github.com/v3/orgs/teams/#list-teams
+    #
     # @example
     #   github = Github.new oauth_token: '...'
     #   github.orgs.teams.list org: 'org-name'
@@ -31,18 +27,20 @@ module Github
     def list(*args)
       params = arguments(args).params
 
-      response = if org = params.delete('org')
-        get_request("/orgs/#{org}/teams", params)
+      if (org = params.delete('org'))
+        response = get_request("/orgs/#{org}/teams", params)
       else
-        get_request("/user/teams", params)
+        response = get_request('/user/teams', params)
       end
       return response unless block_given?
       response.each { |el| yield el }
     end
-    alias :all :list
+    alias_method :all, :list
 
     # Get a team
     #
+    # @see https://developer.github.com/v3/orgs/teams/#get-team
+    #
     # @example
     #   github = Github.new oauth_token: '...'
     #   github.orgs.teams.get 'team-id'
@@ -53,18 +51,28 @@ module Github
 
       get_request("/teams/#{arguments.id}", arguments.params)
     end
-    alias :find :get
+    alias_method :find, :get
 
     # Create a team
     #
     # In order to create a team, the authenticated user must be an owner of :org
     #
+    # @see https://developer.github.com/v3/orgs/teams/#create-team
+    #
     # @param [Hash] params
-    # @input params [String] :name
+    # @option params [String] :name
     #   Required. The name of the team
-    # @input params [Array[String]] :repo_names
+    # @option params [String] :description
+    #   The description of the team.
+    # @option params [Array[String]] :repo_names
     #   The repositories to add the team to.
-    # @input params [String] :permission
+    # @option params [String] :privacy
+    #   The level of privacy this team should have. Can be one of:
+    #     * secret - only visible to organization owners and
+    #                members of this team.
+    #     * closed - visible to all members of this organization.
+    #   Default: secret
+    # @option params [String] :permission
     #   The permission to grant the team. Can be one of:
     #    * pull - team members can pull, but not push or
     #             administor this repositories.
@@ -86,9 +94,7 @@ module Github
     # @api public
     def create(*args)
       arguments(args, required: [:org_name]) do
-        permit VALID_TEAM_PARAM_NAMES
-        assert_values VALID_TEAM_PARAM_VALUES
-        assert_required %w[name]
+        assert_required %w(name)
       end
 
       post_request("/orgs/#{arguments.org_name}/teams", arguments.params)
@@ -99,10 +105,20 @@ module Github
     # In order to edit a team, the authenticated user must be an owner
     # of the org that the team is associated with.
     #
+    # @see https://developer.github.com/v3/orgs/teams/#edit-team
+    #
     # @param [Hash] params
-    # @input params [String] :name
+    # @option params [String] :name
     #   The repositories to add the team to.
-    # @input params [String] :permission
+    # @option params [String] :description
+    #   The description of the team.
+    # @option params [String] :privacy
+    #   The level of privacy this team should have. Can be one of:
+    #     * secret - only visible to organization owners and
+    #                members of this team.
+    #     * closed - visible to all members of this organization.
+    #   Default: secret
+    # @option params [String] :permission
     #   The permission to grant the team. Can be one of:
     #    * pull - team members can pull, but not push or
     #             administor this repositories.
@@ -121,9 +137,7 @@ module Github
     # @api public
     def edit(*args)
       arguments(args, required: [:id]) do
-        permit VALID_TEAM_PARAM_NAMES
-        assert_values VALID_TEAM_PARAM_VALUES
-        assert_required %w[name]
+        assert_required %w(name)
       end
 
       patch_request("/teams/#{arguments.id}", arguments.params)
@@ -131,6 +145,8 @@ module Github
 
     # Delete a team
     #
+    # @see https://developer.github.com/v3/orgs/teams/#delete-team
+    #
     # In order to delete a team, the authenticated user must be an owner
     # of the org that the team is associated with
     #
@@ -138,18 +154,23 @@ module Github
     #   github = Github.new oauth_token: '...'
     #   github.orgs.teams.delete 'team-id'
     #
+    # @api public
     def delete(*args)
       arguments(args, required: [:id])
 
       delete_request("/teams/#{arguments.id}", arguments.params)
     end
-    alias :remove :delete
+    alias_method :remove, :delete
 
     # List team members
     #
     # In order to list members in a team, the authenticated user
     # must be a member of the team.
     #
+    # @see https://developer.github.com/v3/orgs/teams/#list-team-members
+    #
+    # @param [Integer] :team_id
+    #
     # @example
     #   github = Github.new oauth_token: '...'
     #   github.orgs.teams.list_members 'team-id'
@@ -157,25 +178,30 @@ module Github
     #
     # @api public
     def list_members(*args)
-      arguments(args, required: [:id])
+      arguments(args, required: [:team_id])
 
-      response = get_request("/teams/#{arguments.id}/members", arguments.params)
+      response = get_request("/teams/#{arguments.team_id}/members", arguments.params)
       return response unless block_given?
       response.each { |el| yield el }
     end
-    alias :all_members :list_members
+    alias_method :all_members, :list_members
 
     # Check if a user is a member of a team
     #
+    # @see https://developer.github.com/v3/orgs/teams/#get-team-member
+    #
+    # @param [Integer] :team_id
+    # @param [String] :username
+    #
     # @example
     #   github = Github.new oauth_token: '...'
     #   github.orgs.teams.team_member? 'team-id', 'user-name'
     #
     # @api public
     def team_member?(*args)
-      arguments(args, required: [:id, :user])
+      arguments(args, required: [:team_id, :user])
 
-      response = get_request("/teams/#{arguments.id}/members/#{arguments.user}", arguments.params)
+      response = get_request("/teams/#{arguments.team_id}/members/#{arguments.user}", arguments.params)
       response.status == 204
     rescue Github::Error::NotFound
       false
@@ -184,7 +210,7 @@ module Github
     # Add a team member
     #
     # In order to add a user to a team, the authenticated user must
-    # have ‘admin’ permissions to the team or be an owner of the org
+    # have 'admin' permissions to the team or be an owner of the org
     # that the team is associated with.
     #
     # @example
@@ -195,14 +221,17 @@ module Github
     def add_member(*args)
       arguments(args, required: [:id, :user])
 
-      put_request("/teams/#{arguments.id}/members/#{arguments.user}", arguments.params)
+      put_request("/teams/#{arguments.id}/members/#{arguments.user}",
+                  arguments.params)
     end
-    alias :add_team_member :add_member
+    alias_method :add_team_member, :add_member
 
     # Remove a team member
     #
+    # @see https://developer.github.com/v3/orgs/teams/#remove-team-member
+    #
     # In order to remove a user from a team, the authenticated user must
-    # have ‘admin’ permissions to the team or be an owner of the org that
+    # have 'admin' permissions to the team or be an owner of the org that
     # the team is associated with.
     # note: This does not delete the user, it just remove them from the team.
     #
@@ -214,12 +243,91 @@ module Github
     def remove_member(*args)
       arguments(args, required: [:id, :user])
 
-      delete_request("/teams/#{arguments.id}/members/#{arguments.user}", arguments.params)
+      delete_request("/teams/#{arguments.id}/members/#{arguments.user}",
+                     arguments.params)
+    end
+    alias_method :remove_team_member, :remove_member
+
+    # Get team membership
+    #
+    # In order to get a user's membership with a team,
+    # the team must be visible to the authenticated user.
+    #
+    # @see https://developer.github.com/v3/orgs/teams/#get-team-membership
+    #
+    # @param [Integer] :team_id
+    # @param [String]  :username
+    #
+    # @example
+    #   github = Github.new oauth_token: '...'
+    #   github.orgs.teams.team_membership 'team-id', 'username'
+    #
+    # @api public
+    def team_membership(*args)
+      arguments(args, required: [:team_id, :username])
+
+      get_request("/teams/#{arguments.team_id}/memberships/#{arguments.username}",
+                  arguments.params)
+    end
+
+    # Add a team membership
+    #
+    # In order to add a user to a team, the authenticated user must
+    # have 'admin' permissions to the team or be an owner of the org
+    # that the team is associated with.
+    #
+    # @see https://developer.github.com/v3/orgs/teams/#add-team-membership
+    #
+    # @param [Integer] :team_id
+    # @param [String] :username
+    # @param [Hash] :params
+    # @option params [String] :role
+    #   The role that this user should have in the team. Can be one of:
+    #     * member - a normal member of the team.
+    #     * maintainer - a team maintainer. Able to add/remove
+    #       other team members, promote other team members to
+    #       team maintainer, and edit the team's name and description.
+    #   Default: member
+    #
+    # @example
+    #   github = Github.new oauth_token: '...'
+    #   github.orgs.teams.add_membership 'team-id', 'user-name'
+    #
+    # @api public
+    def add_membership(*args)
+      arguments(args, required: [:team_id, :user])
+
+      put_request("/teams/#{arguments.team_id}/memberships/#{arguments.user}",
+                  arguments.params)
     end
-    alias :remove_team_member :remove_member
+    alias_method :add_team_membership, :add_membership
+
+    # Remove a team membership
+    #
+    # In order to remove a user from a team, the authenticated user must
+    # have 'admin' permissions to the team or be an owner of the org that
+    # the team is associated with.
+    # note: This does not delete the user, it just remove them from the team.
+    #
+    # @see https://developer.github.com/v3/orgs/teams/#remove-team-membership
+    #
+    # @example
+    #  github = Github.new oauth_token: '...'
+    #  github.orgs.teams.remove_membership 'team-id', 'user-name'
+    #
+    # @api public
+    def remove_membership(*args)
+      arguments(args, required: [:team_id, :user])
+
+      delete_request("/teams/#{arguments.team_id}/memberships/#{arguments.user}",
+                     arguments.params)
+    end
+    alias_method :remove_team_membership, :remove_membership
 
     # List team repositories
     #
+    # @see https://developer.github.com/v3/orgs/teams/#list-team-repos
+    #
     # @example
     #  github = Github.new oauth_token: '...'
     #  github.orgs.teams.list_repos 'team-id'
@@ -232,10 +340,12 @@ module Github
       return response unless block_given?
       response.each { |el| yield el }
     end
-    alias :repos :list_repos
+    alias_method :repos, :list_repos
 
     # Check if a repository belongs to a team
     #
+    # @see https://developer.github.com/v3/orgs/teams/#get-team-repo
+    #
     # @example
     #  github = Github.new oauth_token: '...'
     #  github.orgs.teams.team_repo? 'team-id', 'user-name', 'repo-name'
@@ -249,7 +359,7 @@ module Github
     rescue Github::Error::NotFound
       false
     end
-    alias :team_repository? :team_repo?
+    alias_method :team_repository?, :team_repo?
 
     # Add a team repository
     #
@@ -258,9 +368,11 @@ module Github
     # must be owned by the organization, or a direct for of a repo owned
     # by the organization.
     #
+    # @see https://developer.github.com/v3/orgs/teams/#add-team-repo
+    #
     # @example
-    #  github = Github.new oauth_token: '...'
-    #  github.orgs.teams.add_repo 'team-id', 'user-name', 'repo-name'
+    #   github = Github.new oauth_token: '...'
+    #   github.orgs.teams.add_repo 'team-id', 'user-name', 'repo-name'
     #
     # @api public
     def add_repo(*args)
@@ -268,7 +380,7 @@ module Github
 
       put_request("/teams/#{arguments.id}/repos/#{arguments.user}/#{arguments.repo}", arguments.params)
     end
-    alias :add_repository :add_repo
+    alias_method :add_repository, :add_repo
 
     # Remove a team repository
     #
@@ -276,6 +388,8 @@ module Github
     # an owner of the org that the team is associated with.
     # note: This does not delete the repo, it just removes it from the team.
     #
+    # @see https://developer.github.com/v3/orgs/teams/#remove-team-repo
+    #
     # @example
     #  github = Github.new oauth_token: '...'
     #  github.orgs.teams.remove_repo 'team-id', 'user-name', 'repo-name'
@@ -286,6 +400,6 @@ module Github
 
       delete_request("/teams/#{arguments.id}/repos/#{arguments.user}/#{arguments.repo}", arguments.params)
     end
-    alias :remove_repository :remove_repo
+    alias_method :remove_repository, :remove_repo
   end # Client::Orgs::Teams
 end # Github