bitbucket_rest_api 0.1.0

data/README.md

@@ -0,0 +1,163 @@
+# BitBucketAPI
+
+[Wiki](https://bitbucket.com/vongrippen/bitbucket/wiki) | [RDocs](http://rubydoc.info/github/vongrippen/bitbucket/master/frames)
+
+A Ruby wrapper for the BitBucket REST API.
+
+## Installation
+
+Install the gem by issuing
+
+```ruby
+gem install bitbucket_rest_api
+```
+
+or put it in your Gemfile and run `bundle install`
+
+```ruby
+gem "bitbucket_rest_api"
+```
+
+## Usage
+
+Create a new client instance
+
+```ruby
+bitbucket = BitBucket.new
+```
+
+At this stage you can also supply various configuration parameters, such as `:user`,`:repo`, `:oauth_token`, `:oauth_secret`, `:basic_auth` which are used throughout the API. These can be passed directly as hash options:
+
+```ruby
+bitbucket = BitBucket.new oauth_token: 'token', oauth_secret: 'secret'
+```
+
+Alternatively, you can configure the BitBucket settings by passing a block, for instance, with custom enteprise endpoint like
+
+```ruby
+bitbucket = BitBucket.new do |config|
+  config.oauth_token  = 'token'
+  config.oauth_secret = 'secret'
+  config.adapter      = :net_http
+end
+```
+
+You can authenticate either using OAuth authentication or through basic authentication by passing your login and password credentials
+
+```ruby
+bitbucket = BitBucket.new login:'vongrippen', password:'...'
+```
+
+or use convenience method:
+
+```ruby
+bitbucket = BitBucket.new basic_auth: 'login:password'
+```
+
+You can interact with BitBucket interface, for example repositories, by issuing following calls that correspond directly to the BitBucket API hierarchy
+
+```ruby
+bitbucket.repos.changesets.all  'user-name', 'repo-name'
+bitbucket.repos.keys.list     'user-name', 'repo-name'
+```
+
+The response is of type [Hashie::Mash] and allows to traverse all the json response attributes like method calls.
+
+## Inputs
+
+Some API methods apart from required parameters such as username or repository name
+allow you to switch the way the data is returned to you, for instance by passing
+a block you can iterate over the list of repositories
+
+```ruby
+bitbucket.repos.list do |repo|
+    puts repo.slug
+end
+```
+
+## Advanced Configuration
+
+The `bitbucket_rest_api` gem will use the default middleware stack which is exposed by calling `stack` on client instance. However, this stack can be freely modified with methods such as `insert`, `insert_after`, `delete` and `swap`. For instance to add your `CustomMiddleware` do
+
+```ruby
+bitbucket = BitBucket.new do |config|
+  config.stack.insert_after BitBucket::Response::Helpers, CustomMiddleware
+end
+```
+
+Furthermore, you can build your entire custom stack and specify other connection options such as `adapter`
+
+```ruby
+bitbucket = BitBucket.new do |config|
+  config.adapter :excon
+
+  config.stack do |builder|
+    builder.use BitBucket::Response::Helpers
+    builder.use BitBucket::Response::Jsonize
+  end
+end
+```
+
+## API
+
+Main API methods are grouped into the following classes that can be instantiated on their own
+
+```ruby
+BitBucket         - full API access
+
+BitBucket::Repos           BitBucket::Issues
+```
+
+Some parts of BitBucket API require you to be authenticated, for instance the following are examples of APIs only for the authenticated user
+
+```ruby
+BitBucket::Issues::Create
+```
+
+You can find out supported methods by calling `actions` on a class instance in your `irb`:
+
+```ruby
+>> BitBucket::Repos.actions                 >> bitbucket.issues.actions
+---                                         ---
+|--> all                                    |--> all
+|--> branches                               |--> comments
+|--> collaborators                          |--> create
+|--> commits                                |--> edit
+|--> contribs                               |--> events
+|--> contributors                           |--> find
+|--> create                                 |--> get
+|--> downloads                              |--> labels
+|--> edit                                   |--> list
+|--> find                                   |--> list_repo
+|--> forks                                  |--> list_repository
+|--> get                                    |--> milestones
+|--> hooks                                  ...
+...
+```
+
+## Configuration
+
+Certain methods require authentication. To get your BitBucket OAuth credentials,
+register an app with BitBucket.
+
+```ruby
+BitBucket.configure do |config|
+  config.oauth_token   = YOUR_OAUTH_ACCESS_TOKEN
+  config.oauth_secret  = YOUR_OAUTH_ACCESS_TOKEN_SECRET
+  config.basic_auth    = 'login:password'
+end
+
+or
+
+BitBucket.new(:oauth_token => YOUR_OAUTH_TOKEN, :oauth_secret => YOUR_OAUTH_ACCESS_TOKEN_SECRET)
+BitBucket.new(:basic_auth => 'login:password')
+```
+
+## Development
+
+Questions or problems? Please post them on the [issue tracker](https://bitbucket.com/vongrippen/bitbucket/issues). You can contribute changes by forking the project and submitting a pull request. You can ensure the tests are passing by running `bundle` and `rake`.
+
+## Copyright
+
+Copyright (c) 2012 James M Cochran.
+Original github_api gem Copyright (c) 2011-2012 Piotr Murach. See LICENSE.txt for further details.

data/lib/bitbucket_rest_api/api/actions.rb

@@ -0,0 +1,50 @@
+# encoding: utf-8
+
+module BitBucket
+  class API
+
+    # Returns all API public methods for a given class.
+    def self.inherited(klass)
+      klass.class_eval <<-RUBY_EVAL, __FILE__, __LINE__ + 1
+        def self.actions
+          self.new.api_methods_in(#{klass})
+        end
+        def actions
+          api_methods_in(#{klass})
+        end
+      RUBY_EVAL
+      super
+    end
+
+    def api_methods_in(klass)
+      puts "---"
+      (klass.send(:instance_methods, false) - ['actions']).sort.each do |method|
+        puts "|--> #{method}"
+      end
+      klass.included_modules.each do |mod|
+        if mod.to_s =~ /#{klass}/
+          puts "| \\ #{mod.to_s}"
+          mod.instance_methods(false).each do |met|
+            puts "|  |--> #{met}"
+          end
+          puts "| /"
+        end
+      end
+      puts "---"
+      nil
+    end
+
+    def append_arguments(method)
+      _method = self.method(method)
+      if _method.arity == 0
+        args = "()"
+      elsif _method.arity > 0
+        args = "(few)"
+      else
+        args = "(else)"
+      end
+      args
+    end
+
+  end # API
+end # BitBucket

data/lib/bitbucket_rest_api/api.rb

@@ -0,0 +1,121 @@
+# -*- encoding: utf-8 -*-
+
+require 'bitbucket_rest_api/configuration'
+require 'bitbucket_rest_api/connection'
+require 'bitbucket_rest_api/validations'
+require 'bitbucket_rest_api/request'
+require 'bitbucket_rest_api/core_ext/hash'
+require 'bitbucket_rest_api/core_ext/array'
+require 'bitbucket_rest_api/compatibility'
+require 'bitbucket_rest_api/api/actions'
+require 'bitbucket_rest_api/api_factory'
+
+module BitBucket
+  class API
+    include Authorization
+    include Connection
+    include Request
+
+    # TODO consider these optional in a stack
+    include Validations
+    include ParameterFilter
+    include Normalizer
+
+    attr_reader *Configuration::VALID_OPTIONS_KEYS
+
+    attr_accessor *VALID_API_KEYS
+
+    # Callback to update global configuration options
+    class_eval do
+      Configuration::VALID_OPTIONS_KEYS.each do |key|
+        define_method "#{key}=" do |arg|
+          self.instance_variable_set("@#{key}", arg)
+          BitBucket.send("#{key}=", arg)
+        end
+      end
+    end
+
+    # Creates new API
+    def initialize(options={}, &block)
+      super()
+      setup options
+      set_api_client
+      client if client_id? && client_secret?
+
+      self.instance_eval(&block) if block_given?
+    end
+
+    def setup(options={})
+      options = BitBucket.options.merge(options)
+      Configuration::VALID_OPTIONS_KEYS.each do |key|
+        send("#{key}=", options[key])
+      end
+      process_basic_auth(options[:basic_auth])
+    end
+
+    # Extract login and password from basic_auth parameter
+    def process_basic_auth(auth)
+      case auth
+      when String
+        self.login, self.password = auth.split(':', 2)
+      when Hash
+        self.login    = auth[:login]
+        self.password = auth[:password]
+      end
+    end
+
+    # Assigns current api class
+    def set_api_client
+      BitBucket.api_client = self
+    end
+
+    # Responds to attribute query or attribute clear
+    def method_missing(method, *args, &block) # :nodoc:
+      case method.to_s
+      when /^(.*)\?$/
+        return !self.send($1.to_s).nil?
+      when /^clear_(.*)$/
+        self.send("#{$1.to_s}=", nil)
+      else
+        super
+      end
+    end
+
+    def _update_user_repo_params(user_name, repo_name=nil) # :nodoc:
+      self.user = user_name || self.user
+      self.repo = repo_name || self.repo
+    end
+
+    def _merge_user_into_params!(params)  #  :nodoc:
+      params.merge!({ 'user' => self.user }) if user?
+    end
+
+    def _merge_user_repo_into_params!(params)   #  :nodoc:
+      { 'user' => self.user, 'repo' => self.repo }.merge!(params)
+    end
+
+    # TODO: See whether still needed, consider adding to core_exts
+    def _hash_traverse(hash, &block)
+      hash.each do |key, val|
+        block.call(key)
+        case val
+        when Hash
+          val.keys.each do |k|
+            _hash_traverse(val, &block)
+          end
+        when Array
+          val.each do |item|
+            _hash_traverse(item, &block)
+          end
+        end
+      end
+      return hash
+    end
+
+    def _merge_mime_type(resource, params) # :nodoc:
+                                           #       params['resource'] = resource
+                                           #       params['mime_type'] = params['mime_type'] || :raw
+    end
+
+  end # API
+end # BitBucket

data/lib/bitbucket_rest_api/api_factory.rb

@@ -0,0 +1,30 @@
+# encoding: utf-8
+
+require 'bitbucket_rest_api/core_ext/hash'
+
+module BitBucket
+  class ApiFactory
+
+    # Instantiates a new bitbucket api object
+    def self.new(klass, options={})
+      return create_instance(klass, options) if klass
+      raise ArgumentError, 'must provide klass to be instantiated'
+    end
+
+    # Passes configuration options to instantiated class
+    def self.create_instance(klass, options)
+      options.symbolize_keys!
+      instance = convert_to_constant(klass.to_s).new options
+      BitBucket.api_client = instance
+      instance
+    end
+
+    def self.convert_to_constant(classes)
+      constant = BitBucket
+      classes.split('::').each do |klass|
+        constant = constant.const_get klass
+      end
+      return constant
+    end
+  end
+end # BitBucket

data/lib/bitbucket_rest_api/authorization.rb

@@ -0,0 +1,49 @@
+# encoding: utf-8
+
+module BitBucket
+  module Authorization
+
+    # Setup OAuth instance
+    def client
+      @client ||= ::OAuth::Consumer.new(client_id, client_secret,
+                                      {:signature_method=>"HMAC-SHA1",
+                                       :request_token_path=>"/1.0/oauth/request_token",
+                                       :authorize_path=>"/1.0/oauth/authenticate",
+                                       :access_token_path=>"/1.0/oauth/access_token",
+                                       :proxy=>nil,
+                                       :scheme=>:header,
+                                       :http_method=>:post,
+                                       :oauth_version=>"1.0",
+                                       :site=>"https://api.bitbucket.org"}
+      )
+    end
+
+    # Check whether authentication credentials are present
+    def authenticated?
+      basic_authed? || oauth_token?
+    end
+
+    # Check whether basic authentication credentials are present
+    def basic_authed?
+      basic_auth? || (login? && password?)
+    end
+
+    # Select authentication parameters
+    def authentication
+      if basic_auth?
+        { :basic_auth => basic_auth }
+      elsif login? && password?
+        { :login => login, :password => password }
+      else
+        { }
+      end
+    end
+
+    private
+
+    def _verify_client # :nodoc:
+      raise ArgumentError, 'Need to provide client_id and client_secret' unless client_id? && client_secret?
+    end
+
+  end # Authorization
+end # BitBucket

data/lib/bitbucket_rest_api/client.rb

@@ -0,0 +1,52 @@
+# encoding: utf-8
+
+module BitBucket
+  class Client < API
+
+    # This is a read-only API to the BitBucket events.
+    # These events power the various activity streams on the site.
+    def events(options = {})
+      raise "Unimplemented"
+      #@events ||= ApiFactory.new 'Events', options
+    end
+
+    def issues(options = {})
+      @issues ||= ApiFactory.new 'Issues', options
+    end
+
+    # An API for users to manage their own tokens.
+    def oauth(options = {})
+      raise "Unimpletmented"
+      #@oauth ||= ApiFactory.new 'Authorizations', options
+    end
+    alias :authorizations :oauth
+
+    def teams(options = {})
+      raise "Unimplemented"
+      #@teams ||= ApiFactory.new 'teams', options
+    end
+
+    def pull_requests(options = {})
+      raise "Unimplemented"
+      #@pull_requests ||= ApiFactory.new 'PullRequests', options
+    end
+
+    def repos(options = {})
+      @repos ||= ApiFactory.new 'Repos', options
+    end
+    alias :repositories :repos
+
+    def search(options = {})
+      raise "Unimplemented"
+      #@search ||= ApiFactory.new 'Search', options
+    end
+
+    # Many of the resources on the users API provide a shortcut for getting
+    # information about the currently authenticated user.
+    def users(options = {})
+      raise "Unimplemented"
+      #@users ||= ApiFactory.new 'Users', options
+    end
+
+  end # Client
+end # BitBucket

data/lib/bitbucket_rest_api/compatibility.rb

@@ -0,0 +1,23 @@
+# coding: utf-8
+
+if RUBY_VERSION < "1.9"
+
+  def ruby_18 #:nodoc:
+    yield
+  end
+
+  def ruby_19 #:nodoc:
+    false
+  end
+
+else
+
+  def ruby_18 #:nodoc:
+    false
+  end
+
+  def ruby_19 #:nodoc:
+    yield
+  end
+
+end

data/lib/bitbucket_rest_api/configuration.rb

@@ -0,0 +1,101 @@
+# encoding: utf-8
+
+module BitBucket
+  module Configuration
+
+    VALID_OPTIONS_KEYS         = [
+        :adapter,
+        :client_id,
+        :client_secret,
+        :oauth_token,
+        :oauth_secret,
+        :endpoint,
+        :mime_type,
+        :user_agent,
+        :connection_options,
+        :repo,
+        :user,
+        :login,
+        :password,
+        :basic_auth
+    ].freeze
+
+    # Other adapters are :typhoeus, :patron, :em_synchrony, :excon, :test
+    DEFAULT_ADAPTER            = :net_http
+
+    # By default, don't set an application key
+    DEFAULT_CLIENT_ID          = nil
+
+    # By default, don't set an application secret
+    DEFAULT_CLIENT_SECRET      = nil
+
+    # By default, don't set a user oauth access token
+    DEFAULT_OAUTH_TOKEN        = nil
+
+    # By default, don't set a user oauth access token secret
+    DEFAULT_OAUTH_SECRET       = nil
+
+    # By default, don't set a user login name
+    DEFAULT_LOGIN              = nil
+
+    # By default, don't set a user password
+    DEFAULT_PASSWORD           = nil
+
+    # By default, don't set a user basic authentication
+    DEFAULT_BASIC_AUTH         = nil
+
+    # The endpoint used to connect to BitBucket if none is set, in the event that BitBucket is ever available on location
+    DEFAULT_ENDPOINT           = 'https://bitbucket.org/api/1.0'.freeze
+
+    # The value sent in the http header for 'User-Agent' if none is set
+    DEFAULT_USER_AGENT         = "BitBucket Ruby Gem #{BitBucket::VERSION::STRING}".freeze
+
+    # By default the <tt>Accept</tt> header will make a request for <tt>JSON</tt>
+    DEFAULT_MIME_TYPE          = :json
+
+    # By default uses the Faraday connection options if none is set
+    DEFAULT_CONNECTION_OPTIONS = { }
+
+    # By default, don't set user name
+    DEFAULT_USER               = nil
+
+    # By default, don't set repository name
+    DEFAULT_REPO               = nil
+
+    attr_accessor *VALID_OPTIONS_KEYS
+
+    # Convenience method to allow for global setting of configuration options
+    def configure
+      yield self
+    end
+
+    def self.extended(base)
+      base.set_defaults
+    end
+
+    def options
+      options = { }
+      VALID_OPTIONS_KEYS.each { |k| options[k] = send(k) }
+      options
+    end
+
+    def set_defaults
+      self.adapter            = DEFAULT_ADAPTER
+      self.client_id          = DEFAULT_CLIENT_ID
+      self.client_secret      = DEFAULT_CLIENT_SECRET
+      self.oauth_token        = DEFAULT_OAUTH_TOKEN
+      self.oauth_secret       = DEFAULT_OAUTH_SECRET
+      self.endpoint           = DEFAULT_ENDPOINT
+      self.user_agent         = DEFAULT_USER_AGENT
+      self.connection_options = DEFAULT_CONNECTION_OPTIONS
+      self.mime_type          = DEFAULT_MIME_TYPE
+      self.user               = DEFAULT_USER
+      self.repo               = DEFAULT_REPO
+      self.login              = DEFAULT_LOGIN
+      self.password           = DEFAULT_PASSWORD
+      self.basic_auth         = DEFAULT_BASIC_AUTH
+      self
+    end
+
+  end # Configuration
+end # BitBucket

data/lib/bitbucket_rest_api/connection.rb

@@ -0,0 +1,97 @@
+# encoding: utf-8
+
+require 'faraday'
+require 'bitbucket_rest_api/response'
+require 'bitbucket_rest_api/response/mashify'
+require 'bitbucket_rest_api/response/jsonize'
+require 'bitbucket_rest_api/response/helpers'
+require 'bitbucket_rest_api/response/raise_error'
+require 'bitbucket_rest_api/request/oauth'
+require 'bitbucket_rest_api/request/basic_auth'
+require 'bitbucket_rest_api/request/jsonize'
+
+module BitBucket
+  module Connection
+    extend self
+    include BitBucket::Constants
+
+    ALLOWED_OPTIONS = [
+        :headers,
+        :url,
+        :params,
+        :request,
+        :ssl
+    ].freeze
+
+    def default_options(options={})
+      {
+          :headers => {
+              ACCEPT           => "application/json;q=0.1",
+              ACCEPT_CHARSET   => "utf-8",
+              USER_AGENT       => user_agent,
+              CONTENT_TYPE     => 'application/json'
+          },
+          :ssl => { :verify => false },
+          :url => options.fetch(:endpoint) { BitBucket.endpoint }
+      }.merge(options)
+    end
+
+    # Default middleware stack that uses default adapter as specified at
+    # configuration stage.
+    #
+    def default_middleware(options={})
+      Proc.new do |builder|
+        builder.use BitBucket::Request::Jsonize
+        builder.use Faraday::Request::Multipart
+        builder.use Faraday::Request::UrlEncoded
+        builder.use BitBucket::Request::OAuth, client, oauth_token, oauth_secret if oauth_token? and oauth_secret?
+        builder.use BitBucket::Request::BasicAuth, authentication if basic_authed?
+
+        builder.use Faraday::Response::Logger if ENV['DEBUG']
+        builder.use BitBucket::Response::Helpers
+        unless options[:raw]
+          builder.use BitBucket::Response::Mashify
+          builder.use BitBucket::Response::Jsonize
+        end
+        builder.use BitBucket::Response::RaiseError
+        builder.adapter adapter
+      end
+    end
+
+    @connection = nil
+
+    @stack = nil
+
+    def clear_cache
+      @connection = nil
+    end
+
+    def caching?
+      !@connection.nil?
+    end
+
+    # Exposes middleware builder to facilitate custom stacks and easy
+    # addition of new extensions such as cache adapter.
+    #
+    def stack(options={}, &block)
+      @stack ||= begin
+        if block_given?
+          Faraday::Builder.new(&block)
+        else
+          Faraday::Builder.new(&default_middleware(options))
+        end
+      end
+    end
+
+    # Returns a Fraday::Connection object
+    #
+    def connection(options = {})
+      conn_options = default_options(options)
+      clear_cache unless options.empty?
+      puts "OPTIONS:#{conn_options.inspect}" if ENV['DEBUG']
+
+      @connection ||= Faraday.new(conn_options.merge(:builder => stack(options)))
+    end
+
+  end # Connection
+end # BitBucket