ruby-trello 0.4.4.3 → 0.5.0

data/README.md

@@ -16,6 +16,86 @@ Seriously, [check it out](http://www.trello.com/).
 Full Disclosure: This library is mostly complete, if you do find anything missing or not functioning as you expect it
 to, please [let us know](https://trello.com/card/spot-a-bug-report-it/4f092b2ee23cb6fe6d1aaabd/17).
 
+## Configuration
+
+Basic authorization
+
+```ruby
+Trello.configure do |config|
+  config.developer_public_key = TRELLO_DEVELOPER_PUBLIC_KEY
+  config.member_token = TRELLO_MEMBER_TOKEN
+end
+```
+
+2-legged OAuth authorization
+
+```ruby
+Trello.configure do |config|
+  config.consumer_key = TRELLO_CONSUMER_KEY
+  config.consumer_secret = TRELLO_CONSUMER_SECRET
+  config.oauth_token = TRELLO_OAUTH_TOKEN
+  config.oauth_token_secret = TRELLO_OAUTH_TOKEN_SECRET
+end
+```
+
+3-legged OAuth authorization
+
+```ruby
+Trello.configure do |config|
+  config.consumer_key    = TRELLO_CONSUMER_KEY
+  config.consumer_secret = TRELLO_CONSUMER_SECRET
+  config.return_url      = "http://your.site.com/path/to/receive/post"
+  config.callback        = lambda { |request_token| DB.save(request_token.key, request_token.secret) }
+end
+```
+
+All the calls this library make to Trello require authentication using these keys. Be sure to protect them.
+
+So lets say you want to get information about the user *bobtester*. We can do something like this:
+
+```ruby
+bob = Trello::Member.find("bobtester")
+# Print out his name
+puts bob.full_name # "Bob Tester"
+# Print his bio
+puts bob.bio # A wonderfully delightful test user
+# How about a list of his boards?
+bob.boards
+```
+
+#### Multiple Users
+
+Applications that make requests on behalf of multiple Trello users have an alternative to global configuration. For each user's access token/secret pair, instantiate a `Trello::Client`:
+
+```ruby
+@client_bob = Trello::Client.new(
+  :consumer_key => YOUR_CONSUMER_KEY,
+  :consumer_secret => YOUR_CONSUMER_SECRET,
+  :oauth_token => "Bob's access token",
+  :oauth_token_secret => "Bob's access secret"
+)
+
+@client_alice = Trello::Client.new(
+  :consumer_key => YOUR_CONSUMER_KEY,
+  :consumer_secret => YOUR_CONSUMER_SECRET,
+  :oauth_token => "Alice's access token",
+  :oauth_token_secret => "Alice's access secret"
+)
+```
+
+You can now make threadsafe requests as the authenticated user:
+
+```ruby
+Thread.new do
+  @client_bob.find(:members, "bobtester")
+  @client_bob.find(:boards, "bobs_board_id")
+end
+Thread.new do
+  @client_alice.find(:members, "alicetester")
+  @client_alice.find(:boards, "alices_board_id")
+end
+```
+
 ## Special thanks
 
 A special thanks goes out to [Ben Biddington](https://github.com/ben-biddington) who has contributed a significant amount
@@ -27,11 +107,4 @@ Several ways you can contribute. Documentation, code, tests, feature requests, b
 
 We develop ruby-trello using [Trello itself](https://trello.com/board/ruby-trello/4f092b2ee23cb6fe6d1aaabd).
 
-Pick up an editor, fix a test! (If you want to, of course.) Send a pull
-request, and I'll look at it. I only ask a few things:
-
-1. Feature branches please!
-2. Adding or refactoring existing features, ensure there are tests.
-
-Also, don't be afraid to send a pull request if your changes aren't done. Just
-let me know.
+Please see the `CONTRIBUTING.md` file for more information.

data/lib/trello.rb

@@ -1,3 +1,4 @@
+
 require 'oauth'
 require 'json'
 require 'logger'
@@ -7,20 +8,18 @@ require 'active_model'
 #
 # First, set up your key information. You can get this information by {clicking here}[https://trello.com/1/appKey/generate].
 #
-#   include Trello
-#   include Trello::Authorization
-#   
-#   Trello::Authorization.const_set :AuthPolicy, OAuthPolicy
-#   
-#   OAuthPolicy.consumer_credential = OAuthCredential.new 'PUBLIC_KEY', 'SECRET'
-#
 # You can get the key by going to this url in your browser:
-# https://trello.com/1/authorize?key=PUBLIC_KEY_FROM_ABOVE&name=MyApp&response_type=token&scope=read,write,account&expiration=never
+# https://trello.com/1/authorize?key=TRELLO_CONSUMER_KEY_FROM_ABOVE&name=MyApp&response_type=token&scope=read,write,account&expiration=never
 # Only request the permissions you need; i.e., scope=read if you only need read, or scope=write if you only need write. Comma separate scopes you need.
 # If you want your token to expire after 30 days, drop the &expiration=never. Then run the following code, where KEY denotes the key returned from the
 # url above:
 #
-#   OAuthPolicy.token = OAuthCredential.new 'KEY', nil
+# Trello.configure do |config|
+#   config.consumer_key = TRELLO_CONSUMER_KEY
+#   config.consumer_secret = TRELLO_CONSUMER_SECRET
+#   config.oauth_token = TRELLO_OAUTH_TOKEN
+#   config.oauth_token_secret = TRELLO_OAUTH_TOKEN_SECRET
+# end
 #
 # All the calls this library make to Trello require authentication using these keys. Be sure to protect them.
 #
@@ -47,6 +46,7 @@ module Trello
   autoload :Card,              'trello/card'
   autoload :Checklist,         'trello/checklist'
   autoload :Client,            'trello/client'
+  autoload :Configuration,     'trello/configuration'
   autoload :HasActions,        'trello/has_actions'
   autoload :Item,              'trello/item'
   autoload :CheckItemState,         'trello/item_state'
@@ -81,4 +81,20 @@ module Trello
   def self.logger=(logger)
     @logger = logger
   end
+
+  def self.client
+    @client ||= Client.new
+  end
+
+  def self.configure(&block)
+    reset!
+    client.configure(&block)
+  end
+
+  def self.reset!
+    @client = nil
+  end
+
+  def self.auth_policy; client.auth_policy; end
+  def self.configuration; client.configuration; end
 end

data/lib/trello/action.rb

@@ -8,7 +8,7 @@ module Trello
     class << self
       # Locate a specific action and return a new Action object.
       def find(id)
-        super(:actions, id)
+        client.find(:action, id)
       end
     end
 
@@ -27,20 +27,20 @@ module Trello
 
     # Returns the board this action occurred on.
     def board
-      Client.get("/actions/#{id}/board").json_into(Board)
+      client.get("/actions/#{id}/board").json_into(Board)
     end
 
     # Returns the card the action occurred on.
     def card
-      Client.get("/actions/#{id}/card").json_into(Card)
+      client.get("/actions/#{id}/card").json_into(Card)
     end
 
     # Returns the list the action occurred on.
     def list
-      Client.get("/actions/#{id}/list").json_into(List)
+      client.get("/actions/#{id}/list").json_into(List)
     end
 
     # Returns the member who created the action.
-    one :member_creator, :via => Member, :using => :member_creator_id
+    one :member_creator, :via => Member, :path => :members, :using => :member_creator_id
   end
 end

data/lib/trello/association_proxy.rb

@@ -2,12 +2,12 @@ require 'active_support/core_ext'
 
 module Trello
   class AssociationProxy
+    extend Forwardable
     alias :proxy_extend :extend
 
     instance_methods.each { |m| undef_method m unless m.to_s =~ /^(?:nil\?|send|object_id|to_a)$|^__|^respond_to|proxy_/ }
 
-    delegate :owner, :target, :to => :@association
-    delegate :count,          :to => :@association
+    def_delegators :@association, :owner, :target, :count
 
     def initialize(association)
       @association = association
@@ -39,4 +39,4 @@ module Trello
       proxy_assocation.concat(records) && self
     end
   end
-end
+end

data/lib/trello/authorization.rb

@@ -4,21 +4,34 @@ require "oauth"
 module Trello
   module Authorization
 
-    AuthPolicy = Class.new
+    AuthPolicy = Class.new do
+      def initialize(attrs = {}); end
+    end
 
     class BasicAuthPolicy
       class << self
         attr_accessor :developer_public_key, :member_token
 
         def authorize(request)
-          the_uri = Addressable::URI.parse(request.uri)
-          existing_values = the_uri.query_values.nil? ? {} : the_uri.query_values
-          new_values = { :key => @developer_public_key, :token => @member_token }
-          the_uri.query_values = new_values.merge existing_values
-
-          Request.new request.verb, the_uri, request.headers, request.body
+          new.authorize(request)
         end
       end
+
+      attr_accessor :developer_public_key, :member_token
+
+      def initialize(attrs = {})
+        @developer_public_key = attrs[:developer_public_key]  || self.class.developer_public_key
+        @member_token         = attrs[:member_token]          || self.class.member_token
+      end
+
+      def authorize(request)
+        the_uri = Addressable::URI.parse(request.uri)
+        existing_values = the_uri.query_values.nil? ? {} : the_uri.query_values
+        new_values = { :key => @developer_public_key, :token => @member_token }
+        the_uri.query_values = new_values.merge existing_values
+
+        Request.new request.verb, the_uri, request.headers, request.body
+      end
     end
 
     class Clock
@@ -57,60 +70,103 @@ module Trello
         attr_accessor :consumer_credential, :token, :return_url, :callback
 
         def authorize(request)
-          unless consumer_credential
-            Trello.logger.error "The consumer_credential has not been supplied."
-            fail "The consumer_credential has not been supplied."
-          end
-
-          if token
-            request.headers = {"Authorization" => get_auth_header(request.uri, :get)}
-            request
-          else
-            consumer(:return_url => return_url, :callback_method => :postMessage)
-            request_token = consumer.get_request_token
-            callback.call request_token
-            return nil
-          end
+          new.authorize(request)
         end
+      end
 
-        private
-
-        def consumer_params(params = {})
-          {
-            :scheme      => :header,
-            :scope       => 'read,write,account',
-            :http_method => :get,
-            :request_token_path => "https://trello.com/1/OAuthGetRequestToken",
-            :authorize_path     => "https://trello.com/1/OAuthAuthorizeToken",
-            :access_token_path  => "https://trello.com/1/OAuthGetAccessToken"
-          }.merge!(params)
+      attr_accessor :attributes
+      attr_accessor :consumer_credential, :token, :return_url, :callback
+
+      def initialize(attrs = {})
+        @consumer_key       = attrs[:consumer_key]
+        @consumer_secret    = attrs[:consumer_secret]
+        @oauth_token        = attrs[:oauth_token]
+        @oauth_token_secret = attrs[:oauth_token_secret]
+        @return_url         = attrs[:return_url]          || self.class.return_url
+        @callback           = attrs[:callback]            || self.class.callback
+      end
+
+      def authorize(request)
+        unless consumer_credential
+          Trello.logger.error "The consumer_credential has not been supplied."
+          fail "The consumer_credential has not been supplied."
         end
 
-        def consumer(options = {})
-          @consumer ||= OAuth::Consumer.new(
-            consumer_credential.key,
-            consumer_credential.secret,
-            consumer_params(options)
-          )
+        if token
+          request.headers = {"Authorization" => get_auth_header(request.uri, :get)}
+          request
+        else
+          consumer(:return_url => return_url, :callback_method => :postMessage)
+          request_token = consumer.get_request_token
+          callback.call request_token
+          return nil
         end
+      end
 
-        def get_auth_header(url, verb, options = {})
-          self.token ||= OAuththCredential.new
+      def consumer_credential
+        @consumer_credential ||= build_consumer_credential
+      end
 
-          request = Net::HTTP::Get.new Addressable::URI.parse(url).to_s
+      def token
+        @token ||= build_token
+      end
+
+      def consumer_key; consumer_credential.key; end
+      def consumer_secret; consumer_credential.secret; end
+      def oauth_token; token.key; end
+      def oauth_token_secret; token.secret; end
 
-          consumer.options[:signature_method] = 'HMAC-SHA1'
-          consumer.options[:nonce]            = Nonce.next
-          consumer.options[:timestamp] 	      = Clock.timestamp
-          consumer.options[:uri]              = url
-          consumer.key                        = consumer_credential.key
-          consumer.secret                     = consumer_credential.secret
+      private
 
-          consumer.sign!(request, OAuth::Token.new(token.key, token.secret))
+      def build_consumer_credential
+        if @consumer_key && @consumer_secret
+          OAuthCredential.new @consumer_key, @consumer_secret
+        else
+          self.class.consumer_credential
+        end
+      end
 
-          request['authorization']
+      def build_token
+        if @oauth_token
+          OAuthCredential.new @oauth_token, @oauth_token_secret
+        else
+          self.class.token
         end
       end
+
+      def consumer_params(params = {})
+        {
+          :scheme      => :header,
+          :scope       => 'read,write,account',
+          :http_method => :get,
+          :request_token_path => "https://trello.com/1/OAuthGetRequestToken",
+          :authorize_path     => "https://trello.com/1/OAuthAuthorizeToken",
+          :access_token_path  => "https://trello.com/1/OAuthGetAccessToken"
+        }.merge!(params)
+      end
+
+      def consumer(options = {})
+        @consumer ||= OAuth::Consumer.new(
+          consumer_credential.key,
+          consumer_credential.secret,
+          consumer_params(options)
+        )
+      end
+
+      def get_auth_header(url, verb, options = {})
+        request = Net::HTTP::Get.new Addressable::URI.parse(url).to_s
+
+        consumer.options[:signature_method] = 'HMAC-SHA1'
+        consumer.options[:nonce]            = Nonce.next
+        consumer.options[:timestamp] 	      = Clock.timestamp
+        consumer.options[:uri]              = url
+        consumer.key                        = consumer_credential.key
+        consumer.secret                     = consumer_credential.secret
+
+        consumer.sign!(request, OAuth::Token.new(token.key, token.secret))
+
+        request['authorization']
+      end
     end
   end
 end

data/lib/trello/basic_data.rb

@@ -7,8 +7,36 @@ module Trello
     include ActiveModel::Serializers::JSON
 
     class << self
-      def find(path, id)
-        Client.get("/#{path}/#{id}").json_into(self)
+      def path_name
+        name.split("::").last.underscore
+      end
+
+      def find(id)
+        client.find(path_name, id)
+      end
+
+      def create(options)
+        client.create(path_name, options)
+      end
+
+      def save(options)
+        new(options).tap do |basic_data|
+          yield basic_data if block_given?
+        end.save
+      end
+
+      def parse(response)
+        response.json_into(self).tap do |basic_data|
+          yield basic_data if block_given?
+        end
+      end
+
+      def parse_many(response)
+        response.json_into(self).map do |data|
+          data.tap do |d|
+            yield d if block_given?
+          end
+        end
       end
     end
 
@@ -43,7 +71,13 @@ module Trello
           options = opts.dup
           klass   = options.delete(:via) || Trello.const_get(name.to_s.camelize)
           ident   = options.delete(:using) || :id
-          klass.find(self.send(ident))
+          path    = options.delete(:path)
+
+          if path
+            client.find(path, self.send(ident))
+          else
+            klass.find(self.send(ident))
+          end
         end
       end
     end
@@ -55,14 +89,20 @@ module Trello
           resource  = options.delete(:in)  || self.class.to_s.split("::").last.downcase.pluralize
           klass     = options.delete(:via) || Trello.const_get(name.to_s.singularize.camelize)
           params    = options.merge(args[0] || {})
-          resources = Client.get("/#{resource}/#{id}/#{name}", params).json_into(klass)
+          resources = client.find_many(klass, "/#{resource}/#{id}/#{name}", params)
           MultiAssociation.new(self, resources).proxy
         end
       end
     end
 
+    def self.client
+      Trello.client
+    end
+
     register_attributes :id, :readonly => [ :id ]
 
+    attr_writer :client
+
     def initialize(fields = {})
       update_fields(fields)
     end
@@ -80,5 +120,9 @@ module Trello
     def ==(other)
       id == other.id
     end
+
+    def client
+      @client ||= self.class.client
+    end
   end
 end