github_api2 1.0.0

data/lib/github_api2/client/git_data/references.rb

@@ -0,0 +1,150 @@
+# encoding: utf-8
+
+require_relative '../../api'
+
+module Github
+  class Client::GitData::References < API
+
+    VALID_REF_PARAM_NAMES = %w[ ref sha force ].freeze
+
+    REQUIRED_REF_PARAMS = %w[ ref sha ].freeze
+
+    VALID_REF_PARAM_VALUES = {
+      'ref' => %r{^refs\/\w+(\/\w+)*} # test fully qualified reference
+    }
+
+    # Get all references
+    #
+    # This will return an array of all the references on the system,
+    # including things like notes and stashes if they exist on the server.
+    # Anything in the namespace, not just <tt>heads</tt> and <tt>tags</tt>,
+    # though that would be the most common.
+    #
+    # @example
+    #  github = Github.new
+    #  github.git_data.references.list 'user-name', 'repo-name'
+    #
+    # @example
+    #  github.git_data.references.list 'user-name', 'repo-name', ref:'tags'
+    #
+    # @api public
+    def list(*args)
+      arguments(args, required: [:user, :repo])
+      params = arguments.params
+      user = arguments.user
+      repo = arguments.repo
+
+      response = if (ref = params.delete('ref'))
+        formatted_ref = validate_reference ref
+        get_request("/repos/#{user}/#{repo}/git/#{formatted_ref}", params)
+      else
+        get_request("/repos/#{user}/#{repo}/git/refs", params)
+      end
+      return response unless block_given?
+      response.each { |el| yield el }
+    end
+    alias :all :list
+
+    # Get a reference
+    #
+    # The ref in the URL must be formatted as <tt>heads/branch</tt>,
+    # not just branch. For example, the call to get the data for a
+    # branch named sc/featureA would be formatted as heads/sc/featureA
+    #
+    # @example
+    #  github = Github.new
+    #  github.git_data.references.get 'user-name', 'repo-name', 'heads/branch'
+    #
+    # @api public
+    def get(*args)
+      arguments(args, required: [:user, :repo, :ref])
+      validate_reference arguments.ref
+      params = arguments.params
+
+      get_request("/repos/#{arguments.user}/#{arguments.repo}/git/refs/#{arguments.ref}", params)
+    end
+    alias :find :get
+
+    # Create a reference
+    #
+    # @param [Hash] params
+    # @input params [String] :ref
+    #   The name of the fully qualified reference (ie: refs/heads/master).
+    #   If it doesn’t start with ‘refs’ and have at least two slashes,
+    #   it will be rejected.
+    # @input params [String] :sha
+    #   The SHA1 value to set this reference to
+    #
+    # @example
+    #  github = Github.new
+    #  github.git_data.references.create 'user-name', 'repo-name',
+    #    ref: "refs/heads/master",
+    #    sha:  "827efc6d56897b048c772eb4087f854f46256132"
+    #
+    # @api public
+    def create(*args)
+      arguments(args, required: [:user, :repo]) do
+        permit VALID_REF_PARAM_NAMES
+        assert_required REQUIRED_REF_PARAMS
+      end
+      params = arguments.params
+      validate_reference params['ref']
+
+      post_request("/repos/#{arguments.user}/#{arguments.repo}/git/refs", params)
+    end
+
+    # Update a reference
+    #
+    # @param [Hash] params
+    # @input params [String] :sha
+    #   The SHA1 value to set this reference to
+    # @input params [Boolean] :force
+    #   Indicates whether to force the update or to make sure the update
+    #   is a fast-forward update. Leaving this out or setting it to false
+    #   will make sure you’re not overwriting work. Default: false
+    #
+    # @example
+    #  github = Github.new
+    #  github.git_data.references.update 'user-name', 'repo-name', 'heads/master',
+    #    sha:  "827efc6d56897b048c772eb4087f854f46256132",
+    #    force: true
+    #
+    # @api public
+    def update(*args)
+      arguments(args, required: [:user, :repo, :ref]) do
+        permit VALID_REF_PARAM_NAMES
+        assert_required %w[ sha ]
+      end
+
+      patch_request("/repos/#{arguments.user}/#{arguments.repo}/git/refs/#{arguments.ref}", arguments.params)
+    end
+
+    # Delete a reference
+    #
+    # @example
+    #  github = Github.new
+    #  github.git_data.references.delete 'user-name', 'repo-name',
+    #    "heads/master"
+    #
+    # @api public
+    def delete(*args)
+      arguments(args, required: [:user, :repo, :ref])
+      params = arguments.params
+
+      delete_request("/repos/#{arguments.user}/#{arguments.repo}/git/refs/#{arguments.ref}", params)
+    end
+    alias :remove :delete
+
+    private
+
+    def validate_reference(ref)
+      refs = (ref =~ (/^(\/)?refs.*/) ? ref : "refs/#{ref}").gsub(/(\/)+/, '/')
+      refs.gsub!(/^\//, '')
+      unless VALID_REF_PARAM_VALUES['ref'] =~ refs
+        raise ArgumentError, "Provided 'reference' is invalid"
+      end
+
+      refs
+    end
+  end # GitData::References
+end # Github

data/lib/github_api2/client/git_data/tags.rb

@@ -0,0 +1,95 @@
+# encoding: utf-8
+
+require_relative '../../api'
+
+module Github
+  class Client::GitData::Tags < API
+    # This tags api only deals with tag objects -
+    # so only annotated tags, not lightweight tags.
+    # Refer https://developer.github.com/v3/git/tags/#parameters
+
+    VALID_TAG_PARAM_NAMES = %w[
+      tag
+      message
+      object
+      type
+      name
+      email
+      date
+      tagger
+    ].freeze
+
+    VALID_TAG_PARAM_VALUES = {
+      'type' => %w[ blob tree commit ]
+    }
+
+    # Get a tag
+    #
+    # @example
+    #  github = Github.new
+    #  github.git_data.tags.get 'user-name', 'repo-name', 'sha'
+    #
+    # @api public
+    def get(*args)
+      arguments(args, required: [:user, :repo, :sha])
+      params = arguments.params
+
+      get_request("/repos/#{arguments.user}/#{arguments.repo}/git/tags/#{arguments.sha}", params)
+    end
+    alias :find :get
+
+    # Create a tag object
+    #
+    # Note that creating a tag object does not create the reference that
+    # makes a tag in Git. If you want to create an annotated tag in Git,
+    # you have to do this call to create the tag object, and then create
+    # the refs/tags/[tag] reference. If you want to create a lightweight
+    # tag, you simply have to create the reference -
+    # this call would be unnecessary.
+    #
+    # @param [Hash] params
+    # @input params [String] :tag
+    #   The tag
+    # @input params [String] :message
+    #   The tag message
+    # @input params [String] :object
+    #   The SHA of the git object this is tagging
+    # @input params [String] :type
+    #   The type of the object we're tagging.
+    #   Normally this is a commit but it can also be a tree or a blob
+    # @input params [Hash] :tagger
+    #   A hash with information about the individual creating the tag.
+    #
+    # The tagger hash contains the following keys:
+    # @input tagger [String] :name
+    #   The name of the author of the tag
+    # @input tagger [String] :email
+    #   The email of the author of the tag
+    # @input tagger [String] :date
+    #   When this object was tagged. This is a timestamp in ISO 8601
+    #   format: YYYY-MM-DDTHH:MM:SSZ.
+    #
+    # @xample
+    #  github = Github.new
+    #  github.git_data.tags.create 'user-name', 'repo-name',
+    #     tag: "v0.0.1",
+    #     message: "initial version\n",
+    #     type: "commit",
+    #     object: "c3d0be41ecbe669545ee3e94d31ed9a4bc91ee3c",
+    #     tagger: {
+    #       name: "Scott Chacon",
+    #       email: "schacon@gmail.com",
+    #       date: "2011-06-17T14:53:3"
+    #     }
+    #
+    # @api public
+    def create(*args)
+      arguments(args, required: [:user, :repo]) do
+        permit VALID_TAG_PARAM_NAMES
+        assert_values VALID_TAG_PARAM_VALUES
+      end
+
+      post_request("/repos/#{arguments.user}/#{arguments.repo}/git/tags", arguments.params)
+    end
+  end # GitData::Tags
+end # Github

data/lib/github_api2/client/git_data/trees.rb

@@ -0,0 +1,113 @@
+# encoding: utf-8
+
+require_relative '../../api'
+
+module Github
+  class Client::GitData::Trees < API
+
+    VALID_TREE_PARAM_NAMES = %w[
+      base_tree
+      tree
+      path
+      mode
+      type
+      sha
+      content
+      url
+    ].freeze
+
+    VALID_TREE_PARAM_VALUES = {
+      'mode' => %w[ 100644 100755 040000 160000 120000 ],
+      'type' => %w[ blob tree commit ]
+    }
+
+    # Get a tree
+    #
+    # @example
+    #  github = Github.new
+    #  github.git_data.trees.get 'user-name', 'repo-name', 'sha'
+    #  github.git_data.trees.get 'user-name', 'repo-name', 'sha' do |file|
+    #    file.path
+    #  end
+    #
+    # Get a tree recursively
+    #
+    # @example
+    #  github = Github.new
+    #  github.git_data.trees.get 'user-name', 'repo-name', 'sha', recursive: true
+    #
+    # @api public
+    def get(*args)
+      arguments(args, required: [:user, :repo, :sha])
+      user   = arguments.user
+      repo   = arguments.repo
+      sha    = arguments.sha
+      params = arguments.params
+
+      response = if params['recursive']
+        params['recursive'] = 1
+        get_request("/repos/#{user}/#{repo}/git/trees/#{sha}", params)
+      else
+        get_request("/repos/#{user}/#{repo}/git/trees/#{sha.to_s}", params)
+      end
+      return response unless block_given?
+      response.tree.each { |el| yield el }
+    end
+    alias :find :get
+
+    # Create a tree
+    #
+    # The tree creation API will take nested entries as well.
+    # If both a tree and a nested path modifying that tree are specified,
+    # it will overwrite the contents of that tree with the new path contents
+    # and write a new tree out.
+    #
+    # @param [Hash] params
+    # @input params [String] :base_tree
+    #   The SHA1 of the tree you want to update with new data
+    # @input params [Array[Hash]] :tree
+    #   Required. Objects (of path, mode, type, and sha)
+    #   specifying a tree structure
+    #
+    # The tree parameter takes the following keys:
+    # @input tree [String] :path
+    #   The file referenced in the tree
+    # @input tree [String] :mode
+    #   The file mode; one of 100644 for file (blob), 100755 for
+    #   executable (blob), 040000 for subdirectory (tree), 160000 for
+    #   submodule (commit), or 120000 for a blob that specifies
+    #   the path of a symlink
+    # @input tree [String] :type
+    #   Either blob, tree, or commit
+    # @input tree [String] :sha
+    #   The SHA1 checksum ID of the object in the tree
+    # @input tree [String] :content
+    #   The content you want this file to have - GitHub will write
+    #   this blob out and use the SHA for this entry.
+    #   Use either this or <tt>tree.sha</tt>
+    #
+    # @example
+    #  github = Github.new
+    #  github.git_data.trees.create 'user-name', 'repo-name',
+    #    tree: [
+    #      {
+    #        path: "file.rb",
+    #        mode: "100644",
+    #        type: "blob",
+    #        sha: "44b4fc6d56897b048c772eb4087f854f46256132"
+    #      },
+    #      ...
+    #    ]
+    #
+    # @api public
+    def create(*args)
+      arguments(args, required: [:user, :repo]) do
+        assert_required %w[ tree ]
+        permit VALID_TREE_PARAM_NAMES, 'tree', { recursive: true }
+        assert_values VALID_TREE_PARAM_VALUES, 'tree'
+      end
+
+      post_request("/repos/#{arguments.user}/#{arguments.repo}/git/trees", arguments.params)
+    end
+  end # GitData::Trees
+end # Github

data/lib/github_api2/client/git_data.rb

@@ -0,0 +1,31 @@
+# encoding: utf-8
+
+require_relative '../api'
+
+module Github
+  class Client::GitData < API
+
+    require_all 'github_api2/client/git_data',
+      'blobs',
+      'commits',
+      'references',
+      'tags',
+      'trees'
+
+    # Access to GitData::Blobs API
+    namespace :blobs
+
+    # Access to GitData::Commits API
+    namespace :commits
+
+    # Access to GitData::References API
+    namespace :references
+
+    # Access to GitData::Tags API
+    namespace :tags
+
+    # Access to GitData::Tags API
+    namespace :trees
+
+  end # GitData
+end # Github

data/lib/github_api2/client/gitignore.rb

@@ -0,0 +1,57 @@
+# encoding: utf-8
+
+require_relative '../api'
+
+module Github
+  # When you create a new GitHub repository via the API, you can specify a
+  # .gitignore template to apply to the repository upon creation.
+  class Client::Gitignore < API
+    # List all templates available to pass as an option
+    # when creating a repository.
+    #
+    # @see https://developer.github.com/v3/gitignore/#listing-available-templates
+    #
+    # @example
+    #  github = Github.new
+    #  github.gitignore.list
+    #  github.gitignore.list { |template| ... }
+    #
+    # @api public
+    def list(*args)
+      arguments(args)
+
+      response = get_request("/gitignore/templates", arguments.params)
+      return response unless block_given?
+      response.each { |el| yield el }
+    end
+    alias :all :list
+
+    # Get a single template
+    #
+    # @see https://developer.github.com/v3/gitignore/#get-a-single-template
+    #
+    # @example
+    #  github = Github.new
+    #  github.gitignore.get "template-name"
+    #
+    # Use the raw media type to get the raw contents.
+    #
+    # @examples
+    #  github = Github.new
+    #  github.gitignore.get "template-name", accept: 'applicatin/vnd.github.raw'
+    #
+    # @api public
+    def get(*args)
+      arguments(args, required: [:name])
+      params = arguments.params
+
+      if (media = params.delete('accept'))
+        params['accept'] = media
+        params['raw'] = true
+      end
+
+      get_request("/gitignore/templates/#{arguments.name}", params)
+    end
+    alias :find :get
+  end # Client::Gitignore
+end # Github

data/lib/github_api2/client/issues/assignees.rb

@@ -0,0 +1,77 @@
+# encoding: utf-8
+
+require_relative '../../api'
+
+module Github
+  class Client::Issues::Assignees < API
+    # Lists all the available assignees (owner + collaborators)
+    # to which issues may be assigned.
+    #
+    # @example
+    #  Github.issues.assignees.list 'owner', 'repo'
+    #  Github.issues.assignees.list 'owner', 'repo' { |assignee| ... }
+    #
+    # @api public
+    def list(*args)
+      arguments(args, required: [:owner, :repo])
+
+      response = get_request("/repos/#{arguments.owner}/#{arguments.repo}/assignees", arguments.params)
+      return response unless block_given?
+      response.each { |el| yield el }
+    end
+    alias :all :list
+
+    # Check to see if a particular user is an assignee for a repository.
+    #
+    # @example
+    #  Github.issues.assignees.check 'user', 'repo', 'assignee'
+    #
+    # @example
+    #  github = Github.new user: 'user-name', repo: 'repo-name'
+    #  github.issues.assignees.check 'assignee'
+    #
+    # @api public
+    def check(*args)
+      arguments(args, required: [:owner, :repo, :assignee])
+      params = arguments.params
+
+      get_request("/repos/#{arguments.owner}/#{arguments.repo}/assignees/#{arguments.assignee}",params)
+      true
+    rescue Github::Error::NotFound
+      false
+    end
+
+    # Add assignees to an issue
+    #
+    # @example
+    #   github = Github.new
+    #   github.issues.assignees.add 'user', 'repo', 'issue-number',
+    #     'hubot', 'other_assignee', ...
+    #
+    # @api public
+    def add(*args)
+      arguments(args, required: [:user, :repo, :number])
+      params = arguments.params
+      params['data'] = { 'assignees' => arguments.remaining } unless arguments.remaining.empty?
+
+      post_request("/repos/#{arguments.user}/#{arguments.repo}/issues/#{arguments.number}/assignees", params)
+    end
+    alias :<< :add
+
+    # Remove a assignees from an issue
+    #
+    # @example
+    #   github = Github.new
+    #   github.issues.assignees.remove 'user', 'repo', 'issue-number',
+    #     'hubot', 'other_assignee'
+    #
+    # @api public
+    def remove(*args)
+      arguments(args, required: [:user, :repo, :number])
+      params = arguments.params
+      params['data'] = { 'assignees' => arguments.remaining } unless arguments.remaining.empty?
+
+      delete_request("/repos/#{arguments.user}/#{arguments.repo}/issues/#{arguments.number}/assignees", params)
+    end
+  end # Issues::Assignees
+end # Github

data/lib/github_api2/client/issues/comments.rb

@@ -0,0 +1,146 @@
+# encoding: utf-8
+
+require_relative '../../api'
+
+module Github
+  class Client::Issues::Comments < API
+
+    VALID_ISSUE_COMMENT_PARAM_NAME = %w[
+      body
+      resource
+      mime_type
+    ].freeze
+
+    # List comments on an issue
+    #
+    # @example
+    #  github = Github.new
+    #  github.issues.comments.all 'owner-name', 'repo-name', number: 'id'
+    #  github.issues.comments.all 'owner-name', 'repo-name', number: 'id' {|com| .. }
+    # @example
+    #  github.issues.comments.all owner: 'username', repo: 'repo-name', number: 'id'
+    #
+    # List comments in a repository
+    #
+    # @param [Hash] params
+    # @option params [String] :sort
+    #   Optional string, created or updated
+    # @option params [String] :direction
+    #   Optional string, asc or desc. Ignored with sort parameter.
+    # @option params [String] :since
+    #   Optional string of a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ
+    #
+    # @example
+    #   github = Github.new
+    #   github.issues.comments.all 'user-name', 'repo-name'
+    #   github.issues.comments.all 'user-name', 'repo-name' {|com| .. }
+    #
+    # @api public
+    def list(*args)
+      arguments(args, required: [:user, :repo])
+      params = arguments.params
+
+      response = if (number = params.delete('number'))
+        get_request("/repos/#{arguments.user}/#{arguments.repo}/issues/#{number}/comments", params)
+      else
+        get_request("/repos/#{arguments.user}/#{arguments.repo}/issues/comments", params)
+      end
+      return response unless block_given?
+      response.each { |el| yield el }
+    end
+    alias :all :list
+
+    # Get a single comment
+    #
+    # @example
+    #  github = Github.new
+    #  github.issues.comments.find 'user-name', 'repo-name', 'id'
+    #
+    # @example
+    #  github.issues.comments.find owner: 'user-name', repo: 'repo-name', id: 'id'
+    #
+    def get(*args)
+      arguments(args, required: [:user, :repo, :id])
+      params = arguments.params
+
+      get_request("/repos/#{arguments.user}/#{arguments.repo}/issues/comments/#{arguments.id}", params)
+    end
+    alias :find :get
+
+    # Create a comment
+    #
+    # @param [Hash] params
+    # @option [String] :body
+    #   Required string
+    #
+    # @example
+    #  github = Github.new
+    #  github.issues.comments.create 'user-name', 'repo-name', 'number',
+    #     body: 'a new comment'
+    #
+    # @example
+    #   github.issues.comments.create
+    #     user: 'owner-name',
+    #     repo: 'repo-name',
+    #     number: 'issue-number',
+    #     body: 'a new comment body'
+    #
+    # @api public
+    def create(*args)
+      arguments(args, required: [:user, :repo, :number]) do
+        permit VALID_ISSUE_COMMENT_PARAM_NAME
+        assert_required %w[ body ]
+      end
+      params = arguments.params
+
+      post_request("/repos/#{arguments.user}/#{arguments.repo}/issues/#{arguments.number}/comments", params)
+    end
+
+    # Edit a comment
+    #
+    # @param [Hash] params
+    # @option params [String] :body
+    #   Required string
+    #
+    # @example
+    #  github = Github.new
+    #  github.issues.comments.edit 'owner-name', 'repo-name', 'id',
+    #     body: 'a new comment'
+    #
+    # @example
+    #   github.issues.comments.edit
+    #     user: 'owner-name',
+    #     repo: 'repo-name',
+    #     id: 'comment-id',
+    #     body: 'a new comment body'
+    #
+    # @api public
+    def edit(*args)
+      arguments(args, required: [:user, :repo, :id]) do
+        permit VALID_ISSUE_COMMENT_PARAM_NAME
+        assert_required %w[ body ]
+      end
+
+      patch_request("/repos/#{arguments.user}/#{arguments.repo}/issues/comments/#{arguments.id}", arguments.params)
+    end
+
+    # Delete a comment
+    #
+    # = Examples
+    #  github = Github.new
+    #  github.issues.comments.delete 'owner-name', 'repo-name', 'comment-id'
+    #
+    # @example
+    #   github.issues.comments.delete
+    #     user: 'owner-name',
+    #     repo: 'repo-name',
+    #     id: 'comment-id',
+    #
+    # @api public
+    def delete(*args)
+      arguments(args, required: [:user, :repo, :id])
+
+      delete_request("/repos/#{arguments.user}/#{arguments.repo}/issues/comments/#{arguments.id}", arguments.params)
+    end
+  end # Issues::Comments
+end # Github