github_api2 1.0.0

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

@@ -0,0 +1,407 @@
+# encoding: utf-8
+
+require_relative '../../api'
+
+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
+    # List user teams
+    #
+    # List all of the teams across all of the organizations
+    # to which the authenticated user belongs. This method
+    # requires user or repo scope when authenticating via OAuth.
+    #
+    # @example
+    #   github = Github.new oauth_token: '...'
+    #   github.orgs.teams.list
+    #
+    # 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'
+    #
+    # @api public
+    def list(*args)
+      params = arguments(args).params
+
+      if (org = params.delete('org'))
+        response = get_request("/orgs/#{org}/teams", params)
+      else
+        response = get_request('/user/teams', params)
+      end
+      return response unless block_given?
+      response.each { |el| yield el }
+    end
+    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'
+    #
+    # @api public
+    def get(*args)
+      arguments(args, required: [:id])
+
+      get_request("/teams/#{arguments.id}", arguments.params)
+    end
+    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
+    # @option params [String] :name
+    #   Required. The name of the team
+    # @option params [String] :description
+    #   The description of the team.
+    # @option params [Array[String]] :repo_names
+    #   The repositories to add the team to.
+    # @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.
+    #    * push - team members can pull and push,
+    #             but not administer this repositores.
+    #    * admin - team members can pull, push and
+    #              administor these repositories.
+    #   Default: pull
+    #
+    # @example
+    #   github = Github.new oauth_token: '...'
+    #   github.orgs.teams.create 'org-name',
+    #     name: "new team",
+    #     permission: "push",
+    #     repo_names: [
+    #       "github/dotfiles"
+    #     ]
+    #
+    # @api public
+    def create(*args)
+      arguments(args, required: [:org_name]) do
+        assert_required %w(name)
+      end
+
+      post_request("/orgs/#{arguments.org_name}/teams", arguments.params)
+    end
+
+    # Edit a team
+    #
+    # 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
+    # @option params [String] :name
+    #   The repositories to add the team to.
+    # @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.
+    #    * push - team members can pull and push,
+    #             but not administer this repositores.
+    #    * admin - team members can pull, push and
+    #              administer these repositories.
+    #   Default: pull
+    #
+    # @example
+    #  github = Github.new oauth_token: '...'
+    #  github.orgs.teams.edit 'team-id',
+    #    name: "new team name",
+    #    permission: "push"
+    #
+    # @api public
+    def edit(*args)
+      arguments(args, required: [:id]) do
+        assert_required %w(name)
+      end
+
+      patch_request("/teams/#{arguments.id}", arguments.params)
+    end
+
+    # 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
+    #
+    # @example
+    #   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_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'
+    #   github.orgs.teams.list_members 'team-id' { |member| ... }
+    #
+    # @api public
+    def list_members(*args)
+      arguments(args, required: [:team_id])
+
+      response = get_request("/teams/#{arguments.team_id}/members", arguments.params)
+      return response unless block_given?
+      response.each { |el| yield el }
+    end
+    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: [:team_id, :user])
+
+      response = get_request("/teams/#{arguments.team_id}/members/#{arguments.user}", arguments.params)
+      response.status == 204
+    rescue Github::Error::NotFound
+      false
+    end
+
+    # 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
+    # that the team is associated with.
+    #
+    # @example
+    #  github = Github.new oauth_token: '...'
+    #  github.orgs.teams.add_member 'team-id', 'user-name'
+    #
+    # @api public
+    def add_member(*args)
+      arguments(args, required: [:id, :user])
+
+      put_request("/teams/#{arguments.id}/members/#{arguments.user}",
+                  arguments.params)
+    end
+    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
+    # the team is associated with.
+    # note: This does not delete the user, it just remove them from the team.
+    #
+    # @example
+    #  github = Github.new oauth_token: '...'
+    #  github.orgs.teams.remove_member 'team-id', 'user-name'
+    #
+    # @api public
+    def remove_member(*args)
+      arguments(args, required: [:id, :user])
+
+      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_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'
+    #
+    # @api public
+    def list_repos(*args)
+      arguments(args, required: [:id])
+
+      response = get_request("/teams/#{arguments.id}/repos", arguments.params)
+      return response unless block_given?
+      response.each { |el| yield el }
+    end
+    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'
+    #
+    # @api public
+    def team_repo?(*args)
+      arguments(args, required: [:id, :user, :repo])
+
+      response = get_request("/teams/#{arguments.id}/repos/#{arguments.user}/#{arguments.repo}", arguments.params)
+      response.status == 204
+    rescue Github::Error::NotFound
+      false
+    end
+    alias_method :team_repository?, :team_repo?
+
+    # Add a team repository
+    #
+    # In order to add a repo to a team, the authenticated user must be
+    # an owner of the org that the team is associated with. Also, the repo
+    # 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'
+    #
+    # @api public
+    def add_repo(*args)
+      arguments(args, required: [:id, :user, :repo])
+
+      put_request("/teams/#{arguments.id}/repos/#{arguments.user}/#{arguments.repo}", arguments.params)
+    end
+    alias_method :add_repository, :add_repo
+
+    # Remove a team repository
+    #
+    # In order to add a repo to a team, the authenticated user must be
+    # 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'
+    #
+    # @api public
+    def remove_repo(*args)
+      arguments(args, required: [:id, :user, :repo])
+
+      delete_request("/teams/#{arguments.id}/repos/#{arguments.user}/#{arguments.repo}", arguments.params)
+    end
+    alias_method :remove_repository, :remove_repo
+  end # Client::Orgs::Teams
+end # Github

data/lib/github_api2/client/orgs.rb

@@ -0,0 +1,127 @@
+# encoding: utf-8
+
+require_relative '../api'
+
+module Github
+  # Organizations API
+  class Client::Orgs < API
+
+    require_all 'github_api2/client/orgs',
+                'hooks',
+                'members',
+                'memberships',
+                'projects',
+                'teams'
+
+    # Access to Client::Orgs::Hooks API
+    namespace :hooks
+
+    # Access to Client::Orgs::Members API
+    namespace :members
+
+    # Access to Client::Orgs::Memberships API
+    namespace :memberships
+
+    # Access to Client::Orgs::Projects API
+    namespace :projects
+
+    # Access to Client::Orgs::Teams API
+    namespace :teams
+
+    # List all organizations
+    #
+    # Lists all organizations, in the order that they were created on GitHub.
+    #
+    # @see https://developer.github.com/v3/orgs/#list-all-organizations
+    #
+    # @param [Hash] params
+    # @option params [String] :since
+    #   The integer ID of the last Organization that you've seen.
+    #
+    # @example
+    #   github = Github.new
+    #   github.orgs.list :every
+    #
+    # List all public organizations for a user.
+    #
+    # @see https://developer.github.com/v3/orgs/#list-user-organizations
+    #
+    # @example
+    #   github = Github.new
+    #   github.orgs.list user: 'user-name'
+    #
+    # List public and private organizations for the authenticated user.
+    #
+    # @example
+    #   github = Github.new oauth_token: '..'
+    #   github.orgs.list
+    #
+    # @api public
+    def list(*args)
+      params = arguments(args).params
+
+      if (user_name = params.delete('user'))
+        response = get_request("/users/#{user_name}/orgs", params)
+      elsif args.map(&:to_s).include?('every')
+        response = get_request('/organizations', params)
+      else
+        # For the authenticated user
+        response = get_request('/user/orgs', params)
+      end
+      return response unless block_given?
+      response.each { |el| yield el }
+    end
+    alias_method :all, :list
+
+    # Get properties for a single organization
+    #
+    # @see https://developer.github.com/v3/orgs/#get-an-organization
+    #
+    # @example
+    #  github = Github.new
+    #  github.orgs.get 'github'
+    #
+    # @api public
+    def get(*args)
+      arguments(args, required: [:org_name])
+
+      get_request("/orgs/#{arguments.org_name}", arguments.params)
+    end
+    alias_method :find, :get
+
+    # Edit organization
+    #
+    # @see https://developer.github.com/v3/orgs/#edit-an-organization
+    #
+    # @param [Hash] params
+    # @option params [String] :billing_email
+    #   Billing email address. This address is not publicized.
+    # @option params [String] :company
+    #   The company name
+    # @option params [String] :email
+    #   The publicly visible email address
+    # @option params [String] :location
+    #   The location
+    # @option params [String] :name
+    #   The shorthand name of the company.
+    # @option params [String] :description
+    #   The description of the company.
+    #
+    # @example
+    #  github = Github.new oauth_token: '...'
+    #  github.orgs.edit 'github',
+    #    billing_email: "support@github.com",
+    #    blog: "https://github.com/blog",
+    #    company: "GitHub",
+    #    email: "support@github.com",
+    #    location: "San Francisco",
+    #    name: "github"
+    #
+    # @api public
+    def edit(*args)
+      arguments(args, required: [:org_name])
+
+      patch_request("/orgs/#{arguments.org_name}", arguments.params)
+    end
+  end # Orgs
+end # Github

data/lib/github_api2/client/projects/cards.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+# encoding: utf-8
+
+require_relative '../../api'
+
+module Github
+  class Client::Projects::Cards < API
+    REQUIRED_MOVE_CARD_PARAMS = %w(position).freeze
+
+    # List project cards for a column
+    #
+    # @example
+    #  github = Github.new
+    #  github.projects.cards.list :column_id
+    #
+    # @see https://developer.github.com/v3/projects/cards/#list-project-cards
+    #
+    # @api public
+    def list(*args)
+      arguments(args, required: [:column_id])
+      params = arguments.params
+
+      params["accept"] ||= ::Github::Client::Projects::PREVIEW_MEDIA
+
+      response = get_request("/projects/columns/#{arguments.column_id}/cards", params)
+
+      return response unless block_given?
+      response.each { |el| yield el }
+    end
+    alias all list
+
+    # Get a project card
+    #
+    # @example
+    #  github = Github.new
+    #  github.projects.cards.get :card_id
+    #
+    # @see https://developer.github.com/v3/projects/cards/#get-a-project-card
+    #
+    # @api public
+    def get(*args)
+      arguments(args, required: [:card_id])
+      params = arguments.params
+
+      params["accept"] ||= ::Github::Client::Projects::PREVIEW_MEDIA
+
+      get_request("/projects/columns/cards/#{arguments.card_id}", params)
+    end
+    alias find get
+
+    # Create a project card for a column
+    #
+    # @param [Hash] params
+    # @option params [String] :note
+    #  The card's note content. Only valid for cards without another type of
+    #  content, so this must be omitted if content_id and content_type are
+    #  specified.
+    # @option params [Integer] :content_id
+    #  The id of the Issue to associate with this card.
+    # @option params [String] :content_type
+    #  The type of content to associate with this card. Can only be "Issue" at
+    #  this time.
+    #
+    # @example
+    #  github = Github.new
+    #  github.projects.cards.create :column_id, note: 'Card Note'
+    #
+    # @example
+    #   github = Github.new
+    #   github.projects.cards.create :column_id, content_id: <content-id>, content_type: 'content-type'
+    #
+    # @see https://developer.github.com/v3/projects/cards/#create-a-project-card
+    #
+    # @api public
+    def create(*args)
+      arguments(args, required: [:column_id])
+      params = arguments.params
+
+      params["accept"] ||= ::Github::Client::Projects::PREVIEW_MEDIA
+
+      post_request("/projects/columns/#{arguments.column_id}/cards", params)
+    end
+
+    # Update a project card
+    #
+    # @param [Hash] params
+    # @option params [String] :note
+    #   The card's note content. Only valid for cards without another type of
+    #   content, so this cannot be specified if the card already has a
+    #   content_id and content_type.
+    #
+    # @example
+    #   github = Github.new
+    #   github.projects.cards.update :card_id, note: 'New card note'
+    #
+    # @see https://developer.github.com/v3/projects/cards/#update-a-project-card
+    #
+    # @api public
+    def update(*args)
+      arguments(args, required: [:card_id])
+      params = arguments.params
+
+      params["accept"] ||= ::Github::Client::Projects::PREVIEW_MEDIA
+
+      patch_request("/projects/columns/cards/#{arguments.card_id}", params)
+    end
+    alias edit update
+
+    # Delete a project card
+    #
+    # @example
+    #   github = Github.new
+    #   github.projects.cards.delete :card_id
+    #
+    # @see https://developer.github.com/v3/projects/cards/#delete-a-project-card
+    #
+    # @api public
+    def delete(*args)
+      arguments(args, required: [:card_id])
+      params = arguments.params
+
+      params["accept"] ||= ::Github::Client::Projects::PREVIEW_MEDIA
+
+      delete_request("/projects/columns/cards/#{arguments.card_id}", params)
+    end
+    alias remove delete
+
+    # Move a project card
+    #
+    # @param [Hash] params
+    # @option params [String] :position
+    #   Required. Required. Can be one of 'first', 'last', or
+    #   'after:<column-id>', where <column-id> is the id value of a column in
+    #   the same project.
+    #
+    # @example
+    #  github = Github.new
+    #  github.projects.cards.move :card_id, position: 'bottom'
+    #
+    # @example
+    #  github = Github.new
+    #  github.projects.cards.move :card_id, position: 'after:<card-id>', column_id: <column-id>
+    #
+    # @see https://developer.github.com/v3/projects/cards/#move-a-project-card
+    #
+    # @api public
+    def move(*args)
+      arguments(args, required: [:card_id]) do
+        assert_required REQUIRED_MOVE_CARD_PARAMS
+      end
+      params = arguments.params
+
+      params["accept"] ||= ::Github::Client::Projects::PREVIEW_MEDIA
+
+      post_request("/projects/columns/cards/#{arguments.card_id}/moves", params)
+    end
+  end
+end