github_api 0.3.5 → 0.3.6

data/lib/github_api/repos/commits.rb

@@ -0,0 +1,180 @@
+# encoding: utf-8
+
+module Github
+  class Repos
+    module Commits
+
+      REQUIRED_COMMENT_PARAMS = %w[
+        body
+        commit_id
+        line
+        path
+        position
+      ].freeze
+
+      # Creates a commit comment
+      #
+      # = Inputs
+      # * <tt>:body</tt> - Required string.
+      # * <tt>:comment_id</tt> - Required string - Sha of the commit to comment on.
+      # * <tt>:line</tt> - Required number - Line number in the file to comment on.
+      # * <tt>:path</tt> - Required string - Relative path of the file to comment on.
+      # * <tt>:position</tt> - Required number - Line index in the diff to comment on.
+      #
+      # = Examples
+      #  @github = Github.new
+      #  @github.repos.create_comment 'user-name', 'repo-name', 'sha-key', 
+      #    "body" => "Nice change",
+      #    "commit_id" => "6dcb09b5b57875f334f61aebed695e2e4193db5e",
+      #    "line" => 1,
+      #    "path" =>  "file1.txt",
+      #    "position" =>  4
+      #
+      def create_comment(user_name, repo_name, sha, params={})
+        _update_user_repo_params(user_name, repo_name)
+        _validate_user_repo_params(user, repo) unless user? && repo?
+        _validate_presence_of sha
+
+        _normalize_params_keys(params)
+        _filter_params_keys(REQUIRED_COMMENT_PARAMS, params)
+
+        raise ArgumentError, "Expected following inputs to the method: #{REQUIRED_COMMENT_PARAMS.join(', ')}" unless _validate_inputs(REQUIRED_COMMENT_PARAMS, params)
+
+        post("/repos/#{user}/#{repo}/commits/#{sha}/comments", params)
+      end
+      alias :create_commit_comment :create_comment
+
+      # Deletes a commit comment
+      #
+      # = Examples
+      #  @github = Github.new
+      #  @github.repos.delete_comment 'user-name', 'repo-name', 'comment-id'
+      #
+      def delete_comment(user_name, repo_name, comment_id, params={})
+        _update_user_repo_params(user_name, repo_name)
+        _validate_user_repo_params(user, repo) unless user? && repo?
+        _validate_presence_of comment_id
+        _normalize_params_keys(params)
+
+        delete("/repos/#{user}/#{repo}/comments/#{comment_id}", params)
+      end
+      alias :delete_commit_comment :delete_comment
+
+      # List commits on a repository
+      #
+      # = Parameters
+      # * <tt>:sha</tt>   Optional string. Sha or branch to start listing commits from.
+      # * <tt>:path</tt>  Optional string. Only commits containing this file path will be returned
+      #
+      # = Examples
+      #  @github = Github.new
+      #  @github.repos.commits 'user-name', 'repo-name', :sha => '...'
+      #  @github.repos.commits 'user-name', 'repo-name', :sha => '...' { |commit| ... }
+      #
+      def commits(user_name=nil, repo_name=nil, params={})
+        _update_user_repo_params(user_name, repo_name)
+        _validate_user_repo_params(user, repo) unless user? && repo?
+        _normalize_params_keys(params)
+        _filter_params_keys(%w[ sha path], params)
+
+        response = get("/repos/#{user}/#{repo}/commits", params)
+        return response unless block_given?
+        response.each { |el| yield el }
+      end
+      alias :list_commits :commits
+      alias :list_repo_commits :commits
+      alias :list_repository_commits :commits
+
+      # List commit comments for a repository
+      #
+      # = Examples
+      #  @github = Github.new
+      #  @github.repos.repo_comments 'user-name', 'repo-name'
+      #  @github.repos.repo_comments 'user-name', 'repo-name' { |com| ... }
+      #
+      def repo_comments(user_name=nil, repo_name=nil, params={})
+        _update_user_repo_params(user_name, repo_name)
+        _validate_user_repo_params(user, repo) unless user? && repo?
+        _normalize_params_keys(params)
+
+        response = get("/repos/#{user}/#{repo}/comments", params)
+        return response unless block_given?
+        response.each { |el| yield el }
+      end
+      alias :list_repo_comments :repo_comments
+      alias :list_repository_comments :repo_comments
+
+      # List comments for a single commit
+      #
+      # = Examples
+      #  @github = Github.new
+      #  @github.repos.commit_comments 'user-name', 'repo-name', '6dcb09b5b57875f334f61aebed695e2e4193db5e'
+      #
+      def commit_comments(user_name, repo_name, sha, params={})
+        _update_user_repo_params(user_name, repo_name)
+        _validate_user_repo_params(user, repo) unless user? && repo?
+        _validate_presence_of sha
+        _normalize_params_keys(params)
+
+        response = get("/repos/#{user}/#{repo}/commits/#{sha}/comments", params)
+        return response unless block_given?
+        response.each { |el| yield el }
+      end
+      alias :list_commit_comments :commit_comments
+
+      # Gets a single commit
+      #
+      # = Examples
+      #  @github = Github.new
+      #  @github.repos.commit 'user-name', 'repo-name', '6dcb09b5b57875f334f61aebed6')
+      #
+      def commit(user_name, repo_name, sha, params={})
+        _update_user_repo_params(user_name, repo_name)
+        _validate_user_repo_params(user, repo) unless user? && repo?
+        _validate_presence_of sha
+        _normalize_params_keys(params)
+
+        get("/repos/#{user}/#{repo}/commits/#{sha}", params)
+      end
+      alias :get_commit :commit
+
+      # Gets a single commit comment
+      #
+      # = Examples
+      #  @github = Github.new
+      #  @github.repos.commit_comment 'user-name', 'repo-name', 'comment-id'
+      #
+      def commit_comment(user_name, repo_name, comment_id, params={})
+        _update_user_repo_params(user_name, repo_name)
+        _validate_user_repo_params(user, repo) unless user? && repo?
+        _validate_presence_of comment_id
+        _normalize_params_keys(params)
+
+        get("/repos/#{user}/#{repo}/comments/#{comment_id}", params)
+      end
+      alias :get_commit_comment :commit_comment
+
+      # Update a commit comment
+      #
+      # = Inputs
+      # * <tt>:body</tt> - Required string.
+      #
+      # = Examples
+      #  @github = Github.new
+      #  @github.repos.update_comment 'user-name', 'repo-name', 'comment-id',
+      #    "body" => "Nice change"
+      #
+      def update_comment(user_name, repo_name, comment_id, params={})
+        _update_user_repo_params(user_name, repo_name)
+        _validate_user_repo_params(user, repo) unless user? && repo?
+        _validate_presence_of comment_id
+
+        _normalize_params_keys(params)
+        raise ArgumentError, "expected following inputs to the method: 'body'" unless _validate_inputs(["body"], params)
+
+        patch("/repos/#{user}/#{repo}/comments/#{comment_id}", params)
+      end
+
+    end # Commits
+  end # Repos
+end # Github

data/lib/github_api/repos/downloads.rb

@@ -0,0 +1,155 @@
+# encoding: utf-8
+
+module Github
+  class Repos
+    module Downloads
+
+      REQUIRED_PARAMS = %w[ name size ]
+
+      VALID_DOWNLOAD_PARAM_NAMES = %w[
+        name
+        size
+        description
+        content_type
+      ].freeze
+
+      REQUIRED_S3_PARAMS = %w[
+        path
+        acl
+        name
+        accesskeyid
+        policy
+        signature
+        mime_type
+      ].freeze
+
+      # Status code for successful upload to Amazon S3 service
+      SUCCESS_STATUS = 201
+
+      # List downloads for a repository
+      #
+      # = Examples
+      #  @github = Github.new
+      #  @github.repos.downloads 'user-name', 'repo-name'
+      #  @github.repos.downloads 'user-name', 'repo-name' { |downl| ... }
+      #
+      def downloads(user_name=nil, repo_name=nil, params={})
+        _update_user_repo_params(user_name, repo_name)
+        _validate_user_repo_params(user, repo) unless user? && repo?
+        _normalize_params_keys(params)
+
+        response = get("/repos/#{user}/#{repo}/downloads", params)
+        return response unless block_given?
+        response.each { |el| yield el }
+      end
+      alias :list_downloads :downloads
+      alias :get_downloads :downloads
+
+      # Get a single download
+      #
+      # = Examples
+      #  @github = Github.new
+      #  @github.repos.download 'user-name', 'repo-name'
+      #
+      def download(user_name, repo_name, download_id, params={})
+        _update_user_repo_params(user_name, repo_name)
+        _validate_user_repo_params(user, repo) unless user? && repo?
+        _validate_presence_of download_id
+        _normalize_params_keys(params)
+
+        get("/repos/#{user}/#{repo}/downloads/#{download_id}", params)
+      end
+      alias :get_download :download
+
+      # Delete download from a repository
+      #
+      # = Examples
+      #  @github = Github.new
+      #  @github.repos.delete_download 'user-name', 'repo-name', 'download-id'
+      #
+      def delete_download(user_name, repo_name, download_id, params={})
+        _update_user_repo_params(user_name, repo_name)
+        _validate_user_repo_params(user, repo) unless user? && repo?
+        _validate_presence_of download_id
+        _normalize_params_keys(params)
+
+        delete("/repos/#{user}/#{repo}/downloads/#{download_id}", params)
+      end
+
+      # Creating a new download is a two step process.
+      # You must first create a new download resource using this method.
+      # Response from this method is to be used in #upload method.
+      #
+      # = Inputs
+      # * <tt>:name</tt> - Required string - name of the file that is being created.
+      # * <tt>:size</tt> - Required number - size of file in bytes.
+      # * <tt>:description</tt> - Optional string
+      # * <tt>:content_type</tt> - Optional string
+      #
+      # = Examples
+      #  @github = Github.new
+      #  @github.repos.create_download 'user-name', 'repo-name',
+      #    "name" =>  "new_file.jpg",
+      #    "size" => 114034,
+      #    "description" => "Latest release",
+      #    "content_type" => "text/plain"
+      #
+      def create_download(user_name=nil, repo_name=nil, params={})
+        _update_user_repo_params(user_name, repo_name)
+        _validate_user_repo_params(user, repo) unless user? && repo?
+
+        _normalize_params_keys(params)
+        _filter_params_keys(VALID_DOWNLOAD_PARAM_NAMES, params)
+
+        raise ArgumentError, "Required parameters are: #{REQUIRED_PARAMS.join(', ')}" unless _validate_inputs(REQUIRED_PARAMS, params)
+
+        post("/repos/#{user}/#{repo}/downloads", params)
+      end
+
+      # Upload a file to Amazon, using the reponse instance from
+      # Github::Repos::Downloads#create_download. This can be done by passing
+      # the response object as an argument to upload method.
+      #
+      # = Parameters
+      # * <tt>resource</tt> - Required Hashie::Mash -resource of the create_download call
+      # * <tt>:size</tt> - Required number - size of file in bytes.
+      #
+      def upload(resource, filename)
+        _validate_presence_of resource, filename
+        raise ArgumentError, 'Need to provied resource of Github::Repose::Downloads#create_download call' unless resource.is_a? Hashie::Mash
+
+        REQUIRED_S3_PARAMS.each do |key|
+          raise ArgumentError, "Expected following key: #{key}" unless resource.respond_to?(key)
+        end
+
+        # TODO use ordered hash if Ruby < 1.9
+        hash = ruby_18 {
+          require 'active_support'
+          ActiveSupport::OrderedHash.new } || ruby_19 { Hash.new }
+
+        mapped_params = {
+          'key'                   => resource.path,
+          'acl'                   => resource.acl,
+          'success_action_status' => SUCCESS_STATUS,
+          'Filename'              => resource.name,
+          'AWSAccessKeyId'        => resource.accesskeyid,
+          'Policy'                => resource.policy,
+          'Signature'             => resource.signature,
+          'Content-Type'          => resource.mime_type,
+          'file'                  => prepend_at_for(filename.to_s)
+        }
+
+        post('', mapped_params, { :url => resource.s3_url })
+      end
+      alias :upload_to_s3 :upload
+      alias :upload_to_amazon :upload
+
+    private
+
+      def prepend_at_for(file)
+        /^@.*/ =~ file ? '@' + file : file
+      end
+
+    end # Downloads
+  end # Repos
+end # Github

data/lib/github_api/repos/forks.rb

@@ -0,0 +1,48 @@
+# encoding: utf-8
+
+module Github
+  class Repos
+    module Forks
+
+      # List repository forks
+      #
+      # = Examples
+      #  @github = Github.new
+      #  @github.repos.forks 'user-name', 'repo-name'
+      #  @github.repos.forks 'user-name', 'repo-name' { |hook| ... }
+      #
+      def forks(user_name=nil, repo_name=nil, params = {})
+        _update_user_repo_params(user_name, repo_name)
+        _validate_user_repo_params(user, repo) unless user? && repo?
+        _normalize_params_keys(params)
+
+        response = get("/repos/#{user}/#{repo}/forks", params)
+        return response unless block_given?
+        response.each { |el| yield el }
+      end
+      alias :repo_forks :forks
+      alias :repository_forks :forks
+
+      # Create a fork for the authenticated user
+      #
+      # = Inputs
+      # * <tt>:org</tt> - Optional string - the name of the service that is being called.
+      #
+      # = Examples
+      #  @github = Github.new
+      #  @github.repos.create_fork 'user-name', 'repo-name',
+      #    "org" =>  "github"
+      #
+      def create_fork(user_name=nil, repo_name=nil, params={})
+        _update_user_repo_params(user_name, repo_name)
+        _validate_user_repo_params(user, repo) unless user? && repo?
+
+        _normalize_params_keys(params)
+        _filter_params_keys(%w[ org ], params)
+
+        post("/repos/#{user}/#{repo}/forks", params)
+      end
+
+    end # Forks
+  end # Repos
+end # Github

data/lib/github_api/repos/hooks.rb

@@ -0,0 +1,174 @@
+# encoding: utf-8
+
+module Github
+  class Repos
+    # The Repository Hooks API manages the post-receive web and service hooks for a repository.
+    module Hooks
+
+      VALID_HOOK_PARAM_NAMES = %w[
+        name
+        config
+        active
+        events
+        add_events
+        remove_events
+      ].freeze # :nodoc:
+
+      # Active hooks can be configured to trigger for one or more events. The default event is push.
+      # The available events are:
+      VALID_HOOK_PARAM_VALUES = {
+        'events' => %w[
+          push
+          issues
+          issue_comment
+          commit_comment
+          pull_request
+          gollum
+          watch
+          download
+          fork
+          fork_apply
+          member
+          public
+        ]
+      }.freeze # :nodoc:
+
+      REQUIRED_PARAMS = %w[ name config ].freeze # :nodoc:
+
+      # List repository hooks
+      #
+      # = Examples
+      #  @github = Github.new
+      #  @github.repos.hooks 'user-name', 'repo-name'
+      #  @github.repos.hooks 'user-name', 'repo-name' { |hook| ... }
+      #
+      def hooks(user_name=nil, repo_name=nil, params={})
+        _update_user_repo_params(user_name, repo_name)
+        _validate_user_repo_params(user, repo) unless user? && repo?
+        _normalize_params_keys(params)
+
+        response = get("/repos/#{user}/#{repo}/hooks", params)
+        return response unless block_given?
+        response.each { |el| yield el }
+      end
+      alias :repo_hooks :hooks
+      alias :repository_hooks :hooks
+
+      # Get a single hook
+      #
+      # = Examples
+      #  @github = Github.new
+      #  @github.repos.hook 'user-name', 'repo-name'
+      #
+      def hook(user_name, repo_name, hook_id, params={})
+        _update_user_repo_params(user_name, repo_name)
+        _validate_user_repo_params(user, repo) unless user? && repo?
+        _validate_presence_of hook_id
+        _normalize_params_keys(params)
+
+        get("/repos/#{user}/#{repo}/hooks/#{hook_id}", params)
+      end
+      alias :get_hook :hook
+      alias :repo_hook :hook
+      alias :repository_hook :hook
+      alias :get_repo_hook :hook
+
+      # Create a hook
+      #
+      # = Inputs
+      # * <tt>:name</tt> - Required string - the name of the service that is being called.
+      # * <tt>:config</tt> - Required hash - A Hash containing key/value pairs to provide settings for this hook.
+      # * <tt>:events</tt> - Optional array - Determines what events the hook is triggered for. Default: ["push"]
+      # * <tt>:active</tt> - Optional boolean - Determines whether the hook is actually triggered on pushes.
+      #
+      # = Examples
+      #  @github = Github.new
+      #  @github.repos.create_hook 'user-name', 'repo-name',
+      #    "name" =>  "web",
+      #    "active" => true,
+      #    "config" => {
+      #      "url" => "http://something.com/webhook"
+      #      }
+      #    }
+      #
+      def create_hook(user_name=nil, repo_name=nil, params={})
+        _update_user_repo_params(user_name, repo_name)
+        _validate_user_repo_params(user, repo) unless user? && repo?
+
+        _normalize_params_keys(params)
+        _filter_params_keys(VALID_HOOK_PARAM_NAMES, params)
+
+        raise ArgumentError, "Required parameters are: name, config" unless _validate_inputs(REQUIRED_PARAMS, params)
+
+        post("/repos/#{user}/#{repo}/hooks", params)
+      end
+
+      # Edit a hook
+      #
+      # = Inputs
+      # * <tt>:name</tt> - Required string - the name of the service that is being called.
+      # * <tt>:config</tt> - Required hash - A Hash containing key/value pairs to provide settings for this hook.
+      # * <tt>:events</tt> - Optional array - Determines what events the hook is triggered for. This replaces the entire array of events. Default: ["push"].
+      # * <tt>:add_events</tt> - Optional array - Determines a list of events to be added to the list of events that the Hook triggers for.
+      # * <tt>:remove_events</tt> - Optional array - Determines a list of events to be removed from the list of events that the Hook triggers for.
+      # * <tt>:active</tt> - Optional boolean - Determines whether the hook is actually triggered on pushes.
+      #
+      # = Examples
+      #  @github = Github.new
+      #  @github.repos.edit_hook 'user-name', 'repo-name',
+      #    "name" => "campfire",
+      #    "active" =>  true,
+      #    "config" =>  {
+      #      "subdomain" => "github",
+      #      "room" =>  "Commits",
+      #      "token" => "abc123"
+      #    }
+      #
+      def edit_hook(user_name, repo_name, hook_id, params={})
+        _update_user_repo_params(user_name, repo_name)
+        _validate_user_repo_params(user, repo) unless user? && repo?
+        _validate_presence_of hook_id
+
+        _normalize_params_keys(params)
+        _filter_params_keys(VALID_HOOK_PARAM_NAMES, params)
+
+        raise ArgumentError, "Required parameters are: name, config" unless _validate_inputs(REQUIRED_PARAMS, params)
+
+        patch("/repos/#{user}/#{repo}/hooks/#{hook_id}", params)
+      end
+
+      # Test a hook
+      #
+      # This will trigger the hook with the latest push to the current repository.
+      #
+      # = Examples
+      #  @github = Github.new
+      #  @github.repos.test_hook 'user-name', 'repo-name', 'hook-id'
+      #
+      def test_hook(user_name, repo_name, hook_id, params={})
+        _update_user_repo_params(user_name, repo_name)
+        _validate_user_repo_params(user, repo) unless user? && repo?
+        _validate_presence_of hook_id
+        _normalize_params_keys(params)
+
+        post("/repos/#{user}/#{repo}/hooks/#{hook_id}/test", params)
+      end
+
+      # Delete a hook
+      #
+      # = Examples
+      #  @github = Github.new
+      #  @github.repos.delete_hook 'user-name', 'repo-name', 'hook-id'
+      #
+      def delete_hook(user_name, repo_name, hook_id, params={})
+        _update_user_repo_params(user_name, repo_name)
+        _validate_user_repo_params(user, repo) unless user? && repo?
+        _validate_presence_of hook_id
+        _normalize_params_keys(params)
+
+        delete("/repos/#{user}/#{repo}/hooks/#{hook_id}", params)
+      end
+
+    end # Hooks
+  end # Repos
+end # Github