github_api 0.2.2 → 0.3.0

data/README.rdoc

@@ -28,7 +28,7 @@ You can authenticate either using OAuth authentication convenience methods(see s
 
   @github = Github.new :login => 'peter-murach', :password => '...'
 
-  or use convenience method:
+or use convenience method:
 
   @github = Github.new :basic_auth => 'login:password'
 
@@ -67,6 +67,7 @@ Main API methods are grouped into the following classes that can be instantiated
   Github::PullRequests
   Github::Repos
   Github::Users
+  Github::Authorizations
 
 Some parts of GitHub API v3 require you to be autheticated, for instance the following are examples of APIs only for the authenticated user
 
@@ -117,6 +118,13 @@ In order to authenticate the user through OAuth2 on GitHub you need to
 
 Once you have your access token, configure your github instance following instructions under Configuration.
 
+Alternatively you can use OAuth Authorizations API. For instance, to create access token through GitHub API do following
+
+  @github = Github.new :basic_auth => 'login:password'
+  @github.oauth.create_authorization 'scopes' => ['repo']
+
+You can add more than one scope from the <tt>user</tt>, <tt>public_repo</tt>, <tt>repo</tt>, <tt>gist</tt> or leave the scopes parameter out, in which case, the default read-only access will be assumed(includes public user profile info, public repo info, and gists).
+
 == MIME Types
 
 Issues, PullRequests and few other API leverage custom mime types which are <tt>:json</tt>, <tt>:blob</tt>, <tt>:raw</tt>, <tt>:text</tt>, <tt>:html</tt>, <tt>:full</tt>. By default <tt>:raw</tt> is used.

data/lib/github_api.rb

@@ -53,6 +53,7 @@ module Github
     :Users        => 'users',
     :CoreExt      => 'core_ext',
     :MimeType     => 'mime_type',
-    :Authorization => 'authorization'
+    :Authorization => 'authorization',
+    :Authorizations => 'authorizations'
 
 end # Github

data/lib/github_api/authorization.rb

@@ -42,6 +42,11 @@ module Github
       @client.auth_code.get_token(authorization_code, params)
     end
 
+    # Check whether authentication credentials are present
+    def authenticated?
+      basic_auth? || oauth_token? || (login? && password?)
+    end
+
     private
 
     def _verify_client # :nodoc:

data/lib/github_api/authorizations.rb

@@ -0,0 +1,119 @@
+# encoding: utf-8
+
+module Github
+  class Authorizations < API
+
+    VALID_AUTH_PARAM_NAMES = %w[
+      scopes
+      add_scopes
+      remove_scopes
+    ].freeze
+
+    # Creates new OAuth Authorizations API
+    def initialize(options = {})
+      super(options)
+    end
+
+    # List authorizations
+    #
+    # = Examples
+    #  @github = Github.new :basic_auth => 'login:password'
+    #  @github.oauth.authorizations
+    #  @github.oauth.authorizations { |auth| ... }
+    #
+    def authorizations(params={})
+      _check_if_authenticated
+      _normalize_params_keys(params)
+
+      response = get("/authorizations", params)
+      return response unless block_given?
+      response.each { |el| yield el }
+    end
+    alias :auths :authorizations
+    alias :list_auths :authorizations
+    alias :list_authorizations :authorizations
+
+    # Get a single authorization
+    #
+    # = Examples
+    #  @github = Github.new :basic_auth => 'login:password'
+    #  @github.oauth.authorization 'authorization-id'
+    #
+    def authorization(authorization_id, params={})
+      _validate_presence_of(authorization_id)
+      _check_if_authenticated
+      _normalize_params_keys params
+
+      get "/authorizations/#{authorization_id}", params
+    end
+    alias :auth :authorization
+    alias :get_auth :authorization
+    alias :get_authorization :authorization
+
+    # Create a new authorization
+    #
+    # = Inputs
+    # * <tt>:scopes</tt> - Optional array - A list of scopes that this authorization is in.
+    # = Examples
+    #  @github = Github.new :basic_auth => 'login:password'
+    #  @github.oauth.create_authorization
+    #    "scopes" => ["public_repo"]
+    #
+    def create_authorization(params={})
+      _check_if_authenticated
+      _normalize_params_keys(params)
+      _filter_params_keys(VALID_AUTH_PARAM_NAMES, params)
+
+      post("/authorizations", params)
+    end
+    alias :create_auth :create_authorization
+
+    # Update an existing authorization
+    #
+    # = Inputs
+    # * <tt>:scopes</tt> - Optional array - A list of scopes that this authorization is in.
+    # * <tt>:add_scopes</tt> - Optional array - A list of scopes to add to this authorization.
+    # * <tt>:remove_scopes</tt> - Optional array - A list of scopes to remove from this authorization.
+    #
+    # = Examples
+    #  @github = Github.new :basic_auth => 'login:password'
+    #  @github.oauth.update_authorization
+    #    "add_scopes" => ["repo"],
+    #
+    def update_authorization(authorization_id, params={})
+      _check_if_authenticated
+      _validate_presence_of(authorization_id)
+
+      _normalize_params_keys(params)
+      _filter_params_keys(VALID_AUTH_PARAM_NAMES, params)
+
+      patch("/authorizations/#{authorization_id}", params)
+    end
+    alias :update_auth :update_authorization
+
+    # Delete an authorization
+    #
+    # = Examples
+    #  @github.oauth.delete_authorization 'authorization-id'
+    #
+    def delete_authorization(authorization_id, params={})
+      _check_if_authenticated
+      _validate_presence_of(authorization_id)
+
+      _normalize_params_keys(params)
+      _filter_params_keys(VALID_AUTH_PARAM_NAMES, params)
+
+      delete("/authorizations/#{authorization_id}", params)
+    end
+    alias :delete_auth :delete_authorization
+    alias :remove_auth :delete_authorization
+    alias :remove_authorization :delete_authorization
+
+    private
+
+    def _check_if_authenticated
+      raise ArgumentError, 'You can only access authentication tokens through Basic Authentication' unless authenticated?
+    end
+
+  end # Authorizations
+end # Github

data/lib/github_api/client.rb

@@ -39,5 +39,11 @@ module Github
       @users ||= _create_instance Github::Users, options
     end
 
+    # An API for users to manage their own tokens. You can only access your own
+    # tokens, and only through Basic Authentication.
+    def oauth(options = {})
+      @oauth ||= _create_instance Github::Authorizations, options
+    end
+
   end # Client
 end # Github

data/lib/github_api/version.rb

@@ -3,8 +3,8 @@
 module Github
   module VERSION
     MAJOR = 0
-    MINOR = 2
-    PATCH = 2
+    MINOR = 3
+    PATCH = 0
     BUILD = nil
 
     STRING = [MAJOR, MINOR, PATCH, BUILD].compact.join('.');

data/spec/fixtures/auths/authorization.json

@@ -0,0 +1,14 @@
+{
+  "id": 1,
+  "url": "https://api.github.com/authorizations/1",
+  "scopes": [
+    "public_repo"
+  ],
+  "token": "abc123",
+  "app": {
+    "url": "http://my-github-app.com",
+    "name": "my github app"
+  },
+ "updated_at": "2011-09-06T20:39:23Z",
+ "created_at": "2011-09-06T17:26:27Z"
+}

data/spec/fixtures/auths/authorizations.json

@@ -0,0 +1,16 @@
+[
+  {
+    "id": 1,
+    "url": "https://api.github.com/authorizations/1",
+    "scopes": [
+      "public_repo"
+    ],
+    "token": "abc123",
+    "app": {
+      "url": "http://my-github-app.com",
+      "name": "my github app"
+    },
+   "updated_at": "2011-09-06T20:39:23Z",
+   "created_at": "2011-09-06T17:26:27Z"
+  }
+]

data/spec/github/authorizations_spec.rb

@@ -0,0 +1,241 @@
+require 'spec_helper'
+
+describe Github::Authorizations do
+
+  let(:github) { Github.new }
+
+  before do
+    github.basic_auth = 'login:password'
+  end
+
+  after do
+    reset_authentication_for github
+  end
+
+  describe "authorizations" do
+    context "resource found" do
+      before do
+        stub_get("/authorizations").
+          to_return(:body => fixture('auths/authorizations.json'), :status => 200, :headers => {:content_type => "application/json; charset=utf-8"})
+      end
+
+
+      it "should fail to get resource without basic authentication" do
+        reset_authentication_for github
+        expect { github.oauth.authorizations }.to raise_error(ArgumentError)
+      end
+
+      it "should get the resources" do
+        github.oauth.authorizations
+        a_get("/authorizations").should have_been_made
+      end
+
+      it "should return array of resources" do
+        authorizations = github.oauth.authorizations
+        authorizations.should be_an Array
+        authorizations.should have(1).items
+      end
+
+      it "should be a mash type" do
+        authorizations = github.oauth.authorizations
+        authorizations.first.should be_a Hashie::Mash
+      end
+
+      it "should get authorization information" do
+        authorizations = github.oauth.authorizations
+        authorizations.first.token.should == 'abc123'
+      end
+
+      it "should yield to a block" do
+        github.oauth.should_receive(:authorizations).and_yield('web')
+        github.oauth.authorizations { |param| 'web' }
+      end
+    end
+
+    context "resource not found" do
+      before do
+        stub_get("/authorizations").
+          to_return(:body => "", :status => [404, "Not Found"])
+      end
+
+      it "should return 404 with a message 'Not Found'" do
+        expect { github.oauth.authorizations }.to raise_error(Github::ResourceNotFound)
+      end
+    end
+  end # authorizations
+
+  describe "authorization" do
+    let(:authorization_id) { 1 }
+
+    context "resource found" do
+      before do
+        stub_get("/authorizations/#{authorization_id}").
+          to_return(:body => fixture('auths/authorization.json'), :status => 200, :headers => {:content_type => "application/json; charset=utf-8"})
+      end
+
+      it "should fail to get resource without authorization id" do
+        expect { github.oauth.authorization nil }.to raise_error(ArgumentError)
+      end
+
+      it "should get the resource" do
+        github.oauth.authorization authorization_id
+        a_get("/authorizations/#{authorization_id}").should have_been_made
+      end
+
+      it "should get authorization information" do
+        authorization = github.oauth.authorization authorization_id
+        authorization.id.should == authorization_id
+        authorization.token.should == 'abc123'
+      end
+
+      it "should return mash" do
+        authorization = github.oauth.authorization authorization_id
+        authorization.should be_a Hashie::Mash
+      end
+    end
+
+    context "resource not found" do
+      before do
+        stub_get("/authorizations/#{authorization_id}").
+          to_return(:body => fixture('auths/authorization.json'), :status => 404, :headers => {:content_type => "application/json; charset=utf-8"})
+      end
+
+      it "should fail to retrive resource" do
+        expect {
+          github.oauth.authorization authorization_id
+        }.to raise_error(Github::ResourceNotFound)
+      end
+    end
+  end # authorization
+
+  describe "create_authorization" do
+    let(:inputs) { { :scopes => ['repo'] } }
+
+    context "resouce created" do
+
+      it "should fail to get resource without basic authentication" do
+        reset_authentication_for github
+        expect { github.oauth.create_authorization }.to raise_error(ArgumentError)
+      end
+
+      before do
+        stub_post("/authorizations").with(inputs).
+          to_return(:body => fixture('auths/authorization.json'), :status => 201, :headers => {:content_type => "application/json; charset=utf-8"})
+      end
+
+      it "should create resource successfully" do
+        github.oauth.create_authorization inputs
+        a_post("/authorizations").with(inputs).should have_been_made
+      end
+
+      it "should return the resource" do
+        authorization = github.oauth.create_authorization inputs
+        authorization.should be_a Hashie::Mash
+      end
+
+      it "should get the authorization information" do
+        authorization = github.oauth.create_authorization inputs
+        authorization.token.should == 'abc123'
+      end
+    end
+
+    context "failed to create resource" do
+      before do
+        stub_post("/authorizations").with(inputs).
+          to_return(:body => '', :status => 404, :headers => {:content_type => "application/json; charset=utf-8"})
+
+      end
+
+      it "should fail to retrieve resource" do
+        expect {
+          github.oauth.create_authorization inputs
+        }.to raise_error(Github::ResourceNotFound)
+      end
+    end
+  end # create_authorization
+
+  describe "update_authorization" do
+    let(:authorization_id) { 1 }
+    let(:inputs) { { :add_scopes => ['repo'] } }
+
+    context "resouce updated" do
+
+      it "should fail to get resource without basic authentication" do
+        reset_authentication_for github
+        expect { github.oauth.update_authorization }.to raise_error(ArgumentError)
+      end
+
+      before do
+        stub_patch("/authorizations/#{authorization_id}").with(inputs).
+          to_return(:body => fixture('auths/authorization.json'), :status => 201, :headers => {:content_type => "application/json; charset=utf-8"})
+      end
+
+      it "should update resource successfully" do
+        github.oauth.update_authorization authorization_id, inputs
+        a_patch("/authorizations/#{authorization_id}").with(inputs).should have_been_made
+      end
+
+      it "should return the resource" do
+        authorization = github.oauth.update_authorization authorization_id, inputs
+        authorization.should be_a Hashie::Mash
+      end
+
+      it "should get the authorization information" do
+        authorization = github.oauth.update_authorization authorization_id, inputs
+        authorization.token.should == 'abc123'
+      end
+    end
+
+    context "failed to update resource" do
+      before do
+        stub_patch("/authorizations/#{authorization_id}").with(inputs).
+          to_return(:body => '', :status => 404, :headers => {:content_type => "application/json; charset=utf-8"})
+
+      end
+
+      it "should fail to retrieve resource" do
+        expect {
+          github.oauth.update_authorization authorization_id, inputs
+        }.to raise_error(Github::ResourceNotFound)
+      end
+    end
+  end # update_authorization
+
+  describe "delete_authorization" do
+    let(:authorization_id) { 1 }
+    let(:inputs) { { :add_scopes => ['repo'] } }
+
+    context "resouce deleted" do
+
+      it "should fail to get resource without basic authentication" do
+        reset_authentication_for github
+        expect { github.oauth.delete_authorization nil }.to raise_error(ArgumentError)
+      end
+
+      before do
+        stub_delete("/authorizations/#{authorization_id}").
+          to_return(:body => '', :status => 204, :headers => {:content_type => "application/json; charset=utf-8"})
+      end
+
+      it "should delete resource successfully" do
+        github.oauth.delete_authorization authorization_id
+        a_delete("/authorizations/#{authorization_id}").should have_been_made
+      end
+    end
+
+    context "failed to create resource" do
+      before do
+        stub_delete("/authorizations/#{authorization_id}").
+          to_return(:body => '', :status => 404, :headers => {:content_type => "application/json; charset=utf-8"})
+
+      end
+
+      it "should fail to retrieve resource" do
+        expect {
+          github.oauth.delete_authorization authorization_id
+        }.to raise_error(Github::ResourceNotFound)
+      end
+    end
+  end # delete_authorization
+
+end # Github::Authorizations

data/spec/spec_helper.rb

@@ -66,6 +66,12 @@ end
 
 OAUTH_TOKEN = 'bafec72922f31fe86aacc8aca4261117f3bd62cf'
 
+def reset_authentication_for(object)
+  ['basic_auth', 'oauth_token', 'login', 'password' ].each do |item|
+    object.send("#{item}=", nil)
+  end
+end
+
 class Hash
   def except(*keys)
     cpy = self.dup

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 2
-  - 2
-  version: 0.2.2
+  - 3
+  - 0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Piotr Murach
@@ -26,9 +26,9 @@ dependencies:
       - !ruby/object:Gem::Version 
         segments: 
         - 1
-        - 1
+        - 2
         - 0
-        version: 1.1.0
+        version: 1.2.0
   type: :runtime
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
@@ -196,6 +196,7 @@ files:
 - lib/github_api/api/utils.rb
 - lib/github_api/api.rb
 - lib/github_api/authorization.rb
+- lib/github_api/authorizations.rb
 - lib/github_api/cache_control.rb
 - lib/github_api/client.rb
 - lib/github_api/compatibility.rb
@@ -246,6 +247,8 @@ files:
 - lib/github_api/users.rb
 - lib/github_api/version.rb
 - lib/github_api.rb
+- spec/fixtures/auths/authorization.json
+- spec/fixtures/auths/authorizations.json
 - spec/fixtures/orgs/members.json
 - spec/fixtures/orgs/org.json
 - spec/fixtures/orgs/orgs.json
@@ -278,6 +281,7 @@ files:
 - spec/fixtures/repos/watchers.json
 - spec/github/api_spec.rb
 - spec/github/authorization_spec.rb
+- spec/github/authorizations_spec.rb
 - spec/github/client_spec.rb
 - spec/github/core_ext/hash_spec.rb
 - spec/github/gists/comments_spec.rb